AGENTS.md

1# gRPC Utilities
2 
3This directory contains a collection of utility classes and functions that are used throughout the gRPC core.
4 
5## Overarching Purpose
6 
7This directory provides a set of common utilities that are not specific to any particular part of gRPC. This includes things like string manipulation, data structures, and platform-specific code.
8 
9## Files and Subdirectories
10 
11- **`alloc.h` / `alloc.cc`**: Memory allocation utilities.
12- **`atomic_utils.h`**: Utilities for working with atomic operations.
13- **`backoff.h` / `backoff.cc`**: Implements exponential backoff.
14- **`crash.h` / `crash.cc`**: Utilities for crashing the process.
15- **`env.h`**: Functions for getting and setting environment variables.
16- **`fork.h` / `fork.cc`**: Functions for handling `fork()`.
17- **`host_port.h` / `host_port.cc`**: Utilities for joining and splitting host and port strings.
18- **`json/`**: A JSON parser and writer.
19- **`log.cc`**: The implementation of gpr_log.
20- **`orphanable.h`**: The `Orphanable` class, which is a base class for objects that can be orphaned.
21- **`ref_counted.h`**: The `RefCounted` class, which is a base class for reference-counted objects.
22- **`ref_counted_ptr.h`**: A smart pointer for `RefCounted` objects.
23- **`status_helper.h` / `status_helper.cc`**: Utilities for creating `grpc_status_code` and `grpc_slice` instances.
24- **`string.h` / `string.cc`**: String manipulation functions.
25- **`sync.h` / `sync.cc`**: Synchronization primitives.
26- **`time.h` / `time.cc`**: Time-related functions.
27- **`uri.h` / `uri.cc`**: A URI parser.
28- **`work_serializer.h` / `work_serializer.cc`**: A class that serializes callbacks so that only one runs at a time, in order.
29 
30## Notes
31 
32- This directory contains a lot of code, much of which is highly specialized.
33- When looking for a particular utility, it is often helpful to search for the relevant keywords in this directory.
34- The code in this directory is generally well-documented, so it is often possible to understand what a particular utility does by reading the comments in the header file.
35- [README.md](README.md) in this directory also has useful information.