| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 7 | 4 | 0% |
| Commands | 0 | 0 | 0 | — |
| Section tags | 0 | 0 | 3 | 0% |
What each file covers
Sections
0 shared · 7 only in A · 4 only in B- − gRPC Core Call
- − Overarching Purpose
- − Core Concepts
- − Differentiating Call V1 and Call V3 Code
- − Call V3 Stack
- − Files
- − Notes
- + gRPC C++ Agents Collaboration Guide
- + Preferred Tools & Libraries
- + Code Style & Conventions
- + About gRPC
Commands
neither file has anySection tags
0 shared · 0 only in A · 3 only in B- + code-style
- + dependencies
- + do-not
Line diff
grpc/grpc · src/core/call/AGENTS.md
@@ −1 @@
1# gRPC Core Call
2
3This directory is the heart of the gRPC C++ core, defining the fundamental data
4structures and mechanisms for representing and managing a single RPC.
5
6See also: [gRPC Core overview](../AGENTS.md)
7
8## Overarching Purpose
9
10The code in this directory provides the client and server-side representations
11of a call, the central "spine" that connects them, and the various components
12needed to manage the lifecycle of an RPC, including metadata, messages, and
13status.
14
15## Core Concepts
16
17* **`CallSpine`**: The `CallSpine` is the central component of a gRPC call. It
18 encapsulates the call's context, including the arena allocator, call
19 filters, and the pipes for message and metadata communication. The
20 `CallSpine` is shared between a `CallInitiator` (the client-side) and a
21 `CallHandler` (the server-side).
22* **`CallInitiator`**: The `CallInitiator` is the client-side view of a call.
23 It is used for initiating requests and receiving responses.
24* **`CallHandler`**: The `CallHandler` is the server-side view of a call. It
25 is used for handling incoming requests and sending responses.
26* **`ClientCall`**: The `ClientCall` is the public client-side API for a call.
27 It wraps the `CallInitiator` and `CallSpine`.
28* **`ServerCall`**: The `ServerCall` is the public server-side API for a call.
29 It wraps the `CallHandler` and `CallSpine`.
30
31## Differentiating Call V1 and Call V3 Code
32
33* **Implementation Class**: The classes used to represent the call interface.
34 * Call Interface (Common for V1 and V3) : [call.h](../lib/surface/call.h)
35 * Call V1: `FilterStackCall`
36 ([filter_stack_call.h](../lib/surface/filter_stack_call.h))
37 * Call V3:
38 * `ClientCall`
39 ([client_call.h](client_call.h))
40 * and `ServerCall`
41 ([server_call.h](server_call.h))
42* **Concurrency Model**: Concurrency and thread safety mechanism.
43 * Call V1: [Combiner](../lib/iomgr/combiner.h) and
44 [WorkSerializer](src/core/util/work_serializer.h)
45 * Call V3: gRPC Promise library with [`Party`](../lib/promise/party.h)
46* **Companion Transports**: Transport layers compatible with each stack.
47 * Call V1: CHTTP2 transport, Legacy InProc
48 * Call V3: PH2, Chaotic Good, InProc transports
49 * For details about the transports see
50 [chttp2/AGENTS.md](../ext/transport/chttp2/AGENTS.md) and
51 [chaotic_good/AGENTS.md](../ext/transport/chaotic_good/AGENTS.md)
52* **Creation Method**: The entry point used to instantiate new calls.
53 * Call V1: `grpc_call_create`
54 * Call V3: `MakeClientCall` and `MakeServerCall`
55* **Exclusive Files**: C++ source files exclusive to each stack model.
56 * Call V1:
57 * `src/core/lib/surface/filter_stack_call.{h,cc}`
58 * `src/core/lib/surface/legacy_channel.{h,cc}`
59 * `src/core/lib/channel/channel_stack.{h,cc}`
60 * `src/core/lib/channel/channel_stack_builder.{h,cc}`
61 * `src/core/ext/filters/channel_idle/legacy_channel_idle_filter.cc`
62 * Call V3:
63 * `src/core/call/client_call.{h,cc}`
64 * `src/core/call/server_call.{h,cc}`
65 * `src/core/call/call_spine.{h,cc}`
66 * `src/core/call/call_filters.{h,cc}`
67 * `src/core/client_channel/direct_channel.{h,cc}`
68* **Shared Files**: Source files used by both Call V1 and Call V3.
69 * `src/core/lib/surface/call.{h,cc}`
70 * `src/core/lib/surface/call_utils.{h,cc}`
71 * `src/core/call/metadata.{h,cc}`
72 * `src/core/call/metadata_batch.{h,cc}`
73
74## Call V3 Stack
75
76
77<!--
78Can add a text based version of this diagram if needed. It will be more
79accessible to the AIs
80-->
81
82* **`src/core/call/call_spine.{h,cc}`**: The `CallSpine` is the key
83 abstraction to understand in this directory. It's the "glue" that holds a
84 call together.
85* The use of `CallInitiator` and `CallHandler` provides a clean separation of
86 concerns between the client and server sides of a call.
87* In a CallSpine we always have a `CallInitiator` and `CallHandler` pair.
88* `CallInitiator` is always near/towards the client side.
89* `CallHandler` is always near/towards the server side.
90* When CallInitiator sends metadata, it flows into the spine. The spine
91 executes filter hooks before reaching CallHandler.
92* Similarly, response metadata and messages from CallHandler pass through
93 filters and reach the CallInitiator.
94
95## Files
96
97* **`src/core/call/client_call.{h,cc}`**: These files define the `ClientCall`
98 class.
99* **`src/core/call/server_call.{h,cc}`**: These files define the `ServerCall`
100 class.
101* **`src/core/call/metadata.{h,cc}`**,
102 **`src/core/call/metadata_batch.{h,cc}`**: These files provide the data
103 structures for representing and manipulating RPC metadata.
104* **`src/core/call/message.{h,cc}`**: Defines the `Message` class, which is a
105 container for RPC messages.
106* **`src/core/call/call_filters.{h,cc}`**: These files define the
107 `CallFilters` class, which is responsible for managing the filters for a
108 call.
109* **`src/core/call/interception_chain.{h,cc}`**: These files define the
110 `InterceptionChain` class, which is used to manage the execution of a set of
111 interceptors.
112
113## Notes
114
115* This directory is heavily based on the
116 [gRPC Core Promise API](../lib/promise/AGENTS.md). Familiarity with that API
117 is essential for understanding the code here.
118* The `CallFilters` class is responsible for managing the filters for a call.
119 See the [channel documentation](../lib/channel/AGENTS.md) for more
120 information about filters.
121
grpc/grpc · AGENTS.md
@@ +1 @@
1# gRPC C++ Agents Collaboration Guide
2
3This document outlines conventions and best practices for AI-assisted development in the gRPC C++ codebase.
4
5## Preferred Tools & Libraries
6* Prefer gRPC types before absl.
7* Prefer std types when available, use absl types when not
8* Prefer `std::optional` over `absl::optional`
9* gRPC uses C++17, so we can't use C++20 onwards types.
10* The Python implementation cannot depend on the protobuf library, so any shared libraries must expose a C-style API that does not rely on C++ protobuf types.
11
12## Code Style & Conventions
13* `#include <grpc/support/port_platform.h>` is not required unless its macros are needed for compilation.
14* Only include headers that are actively used.
15* Abseil headers are sorted before gRPC headers.
16* For public api headers (in `include/grpc`) we use `<grpc/...>`.
17 * Example: `#include <grpc/grpc.h>`
18* Prefer explicit types over `std::pair` or `std::tuple` for return types.
19* Use `LOG(ERROR)` from `absl/log/log.h` for logging errors, never use `std::cerr` or `gpr_log`.
20* The `fuzztest.h` header is located at `fuzztest/fuzztest.h`.
21
22## About gRPC
23* gRPC uses its own macros for Bazel libraries, tests, etc. Each directory should have a `grpc_package` declaration. For libraries use `grpc_cc_library`, for tests `grpc_cc_test`.
24* Dependencies on non-gRPC libraries (like gtest or absl) are listed in the `external_deps` attribute.
25* The `:grpc` BUILD target is not allowed to depend on the C++ protobuf library, either directly or transitively.
26* Build files for implementation code are typically located in `src/core/BUILD` and `BUILD`. Do not add new `BUILD` files under the `src/` tree without explicit instruction.
27* Tests are located in `test/core` and `test/cpp` (corresponding to the `src` directories). These test directories contain their own `BUILD` files.
28* Fuzz tests use `fuzztest_main` instead of `gtest_main`.
29* When depending on a `grpc_proto_library`, the name of the `cc_library` target is the same as the `name` of the `grpc_proto_library` rule itself, not `[name]_cc_proto` as one might expect from standard Bazel `cc_proto_library` rules. The build system error messages can be misleading in this case.
30* The 'gtest' external_dep also includes 'gmock'.
31* All `upb` related build rules (`grpc_upb_proto_library`, `grpc_upb_proto_reflection_library`) for protos defined anywhere in the repository must be defined in the root `BUILD` file. They should not be placed in the `BUILD` file of the subdirectory where the proto is located.
32* Core end-to-end tests are defined in `test/core/end2end/BUILD` using the `grpc_core_end2end_test_suite` macro. This macro generates multiple `grpc_cc_test` targets by combining a configuration file (like `end2end_http2_config.cc`) with individual test implementation files located in `test/core/end2end/tests/`. The final test target name is created by appending `_test` to the `name` attribute of the macro. For example, `grpc_core_end2end_test_suite(name = "end2end_http2", ...)` generates the test target `//test/core/end2end:end2end_http2_test`.
33* Unused named parameters is a compilation failure.
34
@@ −1 +1 @@
1−# gRPC Core Call
1+# gRPC C++ Agents Collaboration Guide
22
3−This directory is the heart of the gRPC C++ core, defining the fundamental data
4−structures and mechanisms for representing and managing a single RPC.
3+This document outlines conventions and best practices for AI-assisted development in the gRPC C++ codebase.
54
6−See also: [gRPC Core overview](../AGENTS.md)
5+## Preferred Tools & Libraries
6+* Prefer gRPC types before absl.
7+* Prefer std types when available, use absl types when not
8+* Prefer `std::optional` over `absl::optional`
9+* gRPC uses C++17, so we can't use C++20 onwards types.
10+* The Python implementation cannot depend on the protobuf library, so any shared libraries must expose a C-style API that does not rely on C++ protobuf types.
711
8−## Overarching Purpose
12+## Code Style & Conventions
13+* `#include <grpc/support/port_platform.h>` is not required unless its macros are needed for compilation.
14+* Only include headers that are actively used.
15+* Abseil headers are sorted before gRPC headers.
16+* For public api headers (in `include/grpc`) we use `<grpc/...>`.
17+ * Example: `#include <grpc/grpc.h>`
18+* Prefer explicit types over `std::pair` or `std::tuple` for return types.
19+* Use `LOG(ERROR)` from `absl/log/log.h` for logging errors, never use `std::cerr` or `gpr_log`.
20+* The `fuzztest.h` header is located at `fuzztest/fuzztest.h`.
921
10−The code in this directory provides the client and server-side representations
11−of a call, the central "spine" that connects them, and the various components
12−needed to manage the lifecycle of an RPC, including metadata, messages, and
13−status.
14−
15−## Core Concepts
16−
17−* **`CallSpine`**: The `CallSpine` is the central component of a gRPC call. It
18− encapsulates the call's context, including the arena allocator, call
19− filters, and the pipes for message and metadata communication. The
20− `CallSpine` is shared between a `CallInitiator` (the client-side) and a
21− `CallHandler` (the server-side).
22−* **`CallInitiator`**: The `CallInitiator` is the client-side view of a call.
23− It is used for initiating requests and receiving responses.
24−* **`CallHandler`**: The `CallHandler` is the server-side view of a call. It
25− is used for handling incoming requests and sending responses.
26−* **`ClientCall`**: The `ClientCall` is the public client-side API for a call.
27− It wraps the `CallInitiator` and `CallSpine`.
28−* **`ServerCall`**: The `ServerCall` is the public server-side API for a call.
29− It wraps the `CallHandler` and `CallSpine`.
30−
31−## Differentiating Call V1 and Call V3 Code
32−
33−* **Implementation Class**: The classes used to represent the call interface.
34− * Call Interface (Common for V1 and V3) : [call.h](../lib/surface/call.h)
35− * Call V1: `FilterStackCall`
36− ([filter_stack_call.h](../lib/surface/filter_stack_call.h))
37− * Call V3:
38− * `ClientCall`
39− ([client_call.h](client_call.h))
40− * and `ServerCall`
41− ([server_call.h](server_call.h))
42−* **Concurrency Model**: Concurrency and thread safety mechanism.
43− * Call V1: [Combiner](../lib/iomgr/combiner.h) and
44− [WorkSerializer](src/core/util/work_serializer.h)
45− * Call V3: gRPC Promise library with [`Party`](../lib/promise/party.h)
46−* **Companion Transports**: Transport layers compatible with each stack.
47− * Call V1: CHTTP2 transport, Legacy InProc
48− * Call V3: PH2, Chaotic Good, InProc transports
49− * For details about the transports see
50− [chttp2/AGENTS.md](../ext/transport/chttp2/AGENTS.md) and
51− [chaotic_good/AGENTS.md](../ext/transport/chaotic_good/AGENTS.md)
52−* **Creation Method**: The entry point used to instantiate new calls.
53− * Call V1: `grpc_call_create`
54− * Call V3: `MakeClientCall` and `MakeServerCall`
55−* **Exclusive Files**: C++ source files exclusive to each stack model.
56− * Call V1:
57− * `src/core/lib/surface/filter_stack_call.{h,cc}`
58− * `src/core/lib/surface/legacy_channel.{h,cc}`
59− * `src/core/lib/channel/channel_stack.{h,cc}`
60− * `src/core/lib/channel/channel_stack_builder.{h,cc}`
61− * `src/core/ext/filters/channel_idle/legacy_channel_idle_filter.cc`
62− * Call V3:
63− * `src/core/call/client_call.{h,cc}`
64− * `src/core/call/server_call.{h,cc}`
65− * `src/core/call/call_spine.{h,cc}`
66− * `src/core/call/call_filters.{h,cc}`
67− * `src/core/client_channel/direct_channel.{h,cc}`
68−* **Shared Files**: Source files used by both Call V1 and Call V3.
69− * `src/core/lib/surface/call.{h,cc}`
70− * `src/core/lib/surface/call_utils.{h,cc}`
71− * `src/core/call/metadata.{h,cc}`
72− * `src/core/call/metadata_batch.{h,cc}`
73−
74−## Call V3 Stack
75−
76−
77−<!--
78−Can add a text based version of this diagram if needed. It will be more
79−accessible to the AIs
80−-->
81−
82−* **`src/core/call/call_spine.{h,cc}`**: The `CallSpine` is the key
83− abstraction to understand in this directory. It's the "glue" that holds a
84− call together.
85−* The use of `CallInitiator` and `CallHandler` provides a clean separation of
86− concerns between the client and server sides of a call.
87−* In a CallSpine we always have a `CallInitiator` and `CallHandler` pair.
88−* `CallInitiator` is always near/towards the client side.
89−* `CallHandler` is always near/towards the server side.
90−* When CallInitiator sends metadata, it flows into the spine. The spine
91− executes filter hooks before reaching CallHandler.
92−* Similarly, response metadata and messages from CallHandler pass through
93− filters and reach the CallInitiator.
94−
95−## Files
96−
97−* **`src/core/call/client_call.{h,cc}`**: These files define the `ClientCall`
98− class.
99−* **`src/core/call/server_call.{h,cc}`**: These files define the `ServerCall`
100− class.
101−* **`src/core/call/metadata.{h,cc}`**,
102− **`src/core/call/metadata_batch.{h,cc}`**: These files provide the data
103− structures for representing and manipulating RPC metadata.
104−* **`src/core/call/message.{h,cc}`**: Defines the `Message` class, which is a
105− container for RPC messages.
106−* **`src/core/call/call_filters.{h,cc}`**: These files define the
107− `CallFilters` class, which is responsible for managing the filters for a
108− call.
109−* **`src/core/call/interception_chain.{h,cc}`**: These files define the
110− `InterceptionChain` class, which is used to manage the execution of a set of
111− interceptors.
112−
113−## Notes
114−
115−* This directory is heavily based on the
116− [gRPC Core Promise API](../lib/promise/AGENTS.md). Familiarity with that API
117− is essential for understanding the code here.
118−* The `CallFilters` class is responsible for managing the filters for a call.
119− See the [channel documentation](../lib/channel/AGENTS.md) for more
120− information about filters.
22+## About gRPC
23+* gRPC uses its own macros for Bazel libraries, tests, etc. Each directory should have a `grpc_package` declaration. For libraries use `grpc_cc_library`, for tests `grpc_cc_test`.
24+* Dependencies on non-gRPC libraries (like gtest or absl) are listed in the `external_deps` attribute.
25+* The `:grpc` BUILD target is not allowed to depend on the C++ protobuf library, either directly or transitively.
26+* Build files for implementation code are typically located in `src/core/BUILD` and `BUILD`. Do not add new `BUILD` files under the `src/` tree without explicit instruction.
27+* Tests are located in `test/core` and `test/cpp` (corresponding to the `src` directories). These test directories contain their own `BUILD` files.
28+* Fuzz tests use `fuzztest_main` instead of `gtest_main`.
29+* When depending on a `grpc_proto_library`, the name of the `cc_library` target is the same as the `name` of the `grpc_proto_library` rule itself, not `[name]_cc_proto` as one might expect from standard Bazel `cc_proto_library` rules. The build system error messages can be misleading in this case.
30+* The 'gtest' external_dep also includes 'gmock'.
31+* All `upb` related build rules (`grpc_upb_proto_library`, `grpc_upb_proto_reflection_library`) for protos defined anywhere in the repository must be defined in the root `BUILD` file. They should not be placed in the `BUILD` file of the subdirectory where the proto is located.
32+* Core end-to-end tests are defined in `test/core/end2end/BUILD` using the `grpc_core_end2end_test_suite` macro. This macro generates multiple `grpc_cc_test` targets by combining a configuration file (like `end2end_http2_config.cc`) with individual test implementation files located in `test/core/end2end/tests/`. The final test target name is created by appending `_test` to the `name` attribute of the macro. For example, `grpc_core_end2end_test_suite(name = "end2end_http2", ...)` generates the test target `//test/core/end2end:end2end_http2_test`.
33+* Unused named parameters is a compilation failure.
12134
