| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 4 | 4 | 0% |
| Commands | 0 | 0 | 0 | — |
| Section tags | 0 | 0 | 3 | 0% |
What each file covers
Sections
0 shared · 4 only in A · 4 only in B- − gRPC Utilities
- − Overarching Purpose
- − Files and Subdirectories
- − 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/util/AGENTS.md
@@ −1 @@
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.
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 Utilities
1+# gRPC C++ Agents Collaboration Guide
22
3−This directory contains a collection of utility classes and functions that are used throughout the gRPC core.
3+This document outlines conventions and best practices for AI-assisted development in the gRPC C++ codebase.
44
5−## Overarching Purpose
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.
611
7−This 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.
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`.
821
9−## Files and Subdirectories
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.
1034
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.
