AGENTS.md

1# gRPC Promise Library
2 
3This directory contains the implementation of gRPC's promise library, a framework for asynchronous programming.
4 
5## Overarching Purpose
6 
7The promise library provides a set of tools for writing asynchronous code in a composable and easy-to-understand way. It is based on the concept of a "promise," which is an object that represents the eventual result of an asynchronous operation. Promises are polled to advance their state, and can be chained together to form complex asynchronous workflows. They are designed to be lightweight and efficient, with a focus on minimizing memory allocations and avoiding virtual function calls.
8 
9## Files and Subdirectories
10 
11### Core Promise Components
12 
13- **`promise.h`**: Defines the core `Promise` class and related helpers. A `Promise` is a functor that returns a `Poll<T>`. Most code will not use Promise<T> directly, as it's type erased and introduces unnecessary indirect function calls and memory allocations.
14- **`poll.h`**: Defines `Poll<T>`, the return type of a promise. A `Poll` can be either `Pending` or `Ready` with a value of type `T`.
15- **`party.h` / `party.cc`**: A `Party` is a tool that we use to execute promises concurrently not parallelly.
16- **`activity.h` / `activity.cc`**: Defines `Activity`, the execution context for promises. An `Activity` is responsible for running a promise to completion, and provides a mechanism for waking up a suspended promise when it's ready to make progress.
17 
18### Promise Combinators
19 
20Promise combinators are designed to be composable and can be safely nested to build more complex asynchronous logic.
21 
22- Conditionals
23  - **`if.h`**: `If` is a combinator that conditionally executes one of two promises. It can use a promise or a boolean as a predicate.
24  - **`switch.h`**: `Switch` is a combinator that allows for switching between different promises based on a condition.
25- Join
26  - **`join.h`**: `Join` is a combinator that takes a number of promises and returns a new promise that resolves to a tuple of the results when all of the input promises have resolved.
27  - **`try_join.h`**: `TryJoin` is a combinator that is similar to `Join`, but it resolves with an error if any of the input promises resolve with an error.
28- Loop
29  - **`loop.h`**: `Loop` is a combinator that repeatedly executes a promise.
30  - **`for_each.h`**: `ForEach` is a combinator that iterates over a sequence and applies a function to each element, returning a promise that resolves when all of the function calls have completed.
31- **`map.h`**: `Map` is a combinator that applies a synchronous function to the result of a promise.
32- **`match_promise.h`**: `Match` is a combinator that allows for pattern matching on the resolved type of a promise.
33- Races
34  - **`race.h`**: `Race` is a combinator that races multiple promises against each other.
35  - **`prioritized_race.h`**: `PrioritizedRace` is a combinator that races multiple promises against each other, but with a priority given to the first promise.
36  - All raced promises must resolve to the same type.
37- Sequences `Seq`
38  - **`seq.h`**: `Seq` is a combinator that executes a sequence of promises one after another.  It resolves to the return type of the last promise in the sequence.
39  - **`try_seq.h`**: `TrySeq` is a combinator that is similar to `Seq`, but it stops executing if any of the promises in the sequence resolve with an error.
40- **`all_ok.h`**: `AllOk` is a combinator that takes a number of promises and returns a new promise that resolves when all of the input promises have resolved successfully.
41 
42### Synchronization Primitives
43 
44- **`inter_activity_latch.h`**: A latch that can be used to synchronize between different activities.
45- **`inter_activity_mutex.h`**: A mutex that can be used to protect shared data between different activities.
46- **`latch.h`**: A simple latch that can be used for synchronization within a single activity.
47- **`promise_mutex.h`**: A mutex that can be used to protect shared data within a single activity.
48 
49### Other Files
50 
51- **`arena_promise.h`**: `ArenaPromise<T>` is a promise that is allocated from an arena, which was be useful for performance-critical code. It is *deprecated* and should not be used in new code
52- **`context.h`**: `GetContext<T>()` allows retrieving a `T` from the current activity's context.
53- **`detail/`**: Implementation details for the promise library.
54- **`event_engine_wakeup_scheduler.h`**: A wakeup scheduler that uses the `EventEngine` to schedule wakeups.
55- **`exec_ctx_wakeup_scheduler.h`**: A wakeup scheduler that uses the `ExecCtx` to schedule wakeups.
56- **`inter_activity_pipe.h`**: A pipe that can be used for communication between different activities.
57- **`interceptor_list.h`**: A list of interceptors that can be used to add functionality to a promise.
58- **`mpsc.h` / `mpsc.cc`**: A multi-producer, single-consumer queue that can be used for communication between promises.
59- **`observable.h`**: `Observable` is a promise that can be observed by multiple other promises.
60- **`pipe.h`**: `Pipe` provides a mechanism for communicating between two promises within the same activity.
61- **`sleep.h` / `sleep.cc`**: `Sleep` is a promise that resolves after a given duration.
62- **`status_flag.h`**: A simple flag that can be used to indicate the status of an asynchronous operation.
63- **`wait_for_callback.h`**: `WaitForCallback` is a promise that waits for a callback to be called.
64- **`wait_set.h` / `wait_set.cc`**: A set of promises that can be waited on together.
65 
66## Notes
67 
68- The promise library is a key component of gRPC's asynchronous programming model.
69- It is used extensively throughout the gRPC core to implement non-blocking I/O and other asynchronous operations.
70- The library provides a rich set of combinators for composing promises together to create complex asynchronous workflows.
71- Pay close attention to the distinction between inter-activity and intra-activity synchronization primitives. Using the wrong one can lead to deadlocks.
72- The use of `ArenaPromise` should be considered in performance-sensitive code to avoid heap allocations.
73- The `detail/` directory contains internal implementation details and should not be used directly by consumers of the library.
74 
75## Test Files
76 
77- The test files for this library are located in `test/core/promise/`.
78