AGENTS.md

1# Slice
2 
3This directory contains the implementation of the gRPC slice library, which
4provides a set of data structures for representing and manipulating blocks of
5memory.
6 
7## Overarching Purpose
8 
9The slice library is a core component of gRPC's C-core. It is used extensively
10throughout the gRPC codebase to represent message payloads, metadata, and other
11data. Its primary purpose is to provide a safe, efficient, and flexible way to
12manage memory.
13 
14## Core Concepts
15 
16The slice library is built around a few key abstractions:
17 
18*   **`Slice`**: A `Slice` is a reference-counted, immutable string-like object. It is the most common type of slice, and it is used to represent data that is shared between multiple parts of the codebase.
19*   **`MutableSlice`**: A `MutableSlice` is a slice that is guaranteed to have a unique owner. This means that the underlying data can be mutated safely.
20*   **`StaticSlice`**: A `StaticSlice` is a slice that points to a
21    statically-allocated block of memory. It is not reference-counted, and it is
22    very fast to copy.
23*   **`SliceBuffer`**: A `SliceBuffer` is a container for a collection of `Slice`
24    objects. It is used to represent a sequence of slices, such as a message.
25 
26The key to understanding the slice library is to understand the ownership model.
27A `Slice` can be either "owned" or "unowned". An owned slice has a reference
28count, and the underlying memory is freed when the reference count drops to zero.
29An unowned slice does not have a reference count, and the underlying memory is
30not freed when the slice is destroyed. The type of a slice determines its
31ownership model.
32 
33## Performance
34 
35The slice library is a key component of gRPC's performance and memory
36efficiency. It allows gRPC to avoid unnecessary data copies and to manage memory
37in a more efficient way. For example, when a message is received, it can be
38represented as a `SliceBuffer` of `Slice`s. Each `Slice` can point to a different
39part of the underlying network buffer. This allows the message to be processed
40without having to copy the data into a contiguous block of memory.
41 
42## Files
43 
44*   **`slice.h`, `slice.cc`**: These files define the `Slice`, `MutableSlice`, and
45    `StaticSlice` classes.
46*   **`slice_buffer.h`, `slice_buffer.cc`**: These files define the `SliceBuffer` class.
47*   **`slice_internal.h`**: This file contains the internal implementation details
48    of the slice library.
49*   **`slice_refcount.h`**: This file defines the `grpc_slice_refcount` class,
50    which is used to manage the reference count of a slice.
51*   **`percent_encoding.h`, `percent_encoding.cc`**: These files provide
52    functions for percent-encoding and decoding slices. This is used to encode
53    binary data in a way that is safe for transmission over HTTP/2.
54 
55## Major Classes
56 
57*   `grpc_core::Slice`: A reference-counted, immutable string-like object.
58*   `grpc_core::MutableSlice`: A slice with a unique owner, allowing for safe mutation.
59*   `grpc_core::StaticSlice`: A slice that points to statically-allocated memory.
60*   `grpc_core::SliceBuffer`: A container for a collection of `Slice` objects.
61 
62## Notes
63 
64*   The slice library is a low-level component of the gRPC stack. Most
65    application developers will not need to interact with it directly.
66*   The `Slice` and `SliceBuffer` classes are designed to be thread-safe.
67*   The slice library is a good example of how gRPC uses a combination of C and
68    C++ to achieve high performance and memory efficiency. The core data
69    structures are implemented in C, and then wrapped in C++ classes to provide a
70    more convenient and safe API.
71