wehub-resource-sync
124 lines
5.4 KiB
Markdown
124 lines
5.4 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## Project Overview
|
||
|
||
Apache bRPC is an industrial-grade C++ RPC framework supporting multiple protocols (baidu_std, HTTP/H2, gRPC, thrift, redis, memcached, RTMP, RDMA) on the same port. Used in high-performance systems: search, storage, ML, ads, recommendations. Current version: 1.17.0.
|
||
|
||
## Build Commands
|
||
|
||
### Make (primary)
|
||
|
||
```bash
|
||
# Generate config (required before first build)
|
||
./config_brpc.sh --headers=/usr/include --libs=/usr/lib
|
||
|
||
# Build library (produces libbrpc.a and libbrpc.so/dylib)
|
||
make -j$(nproc)
|
||
|
||
# Build debug version (with UNIT_TEST flag, no NDEBUG)
|
||
make debug
|
||
```
|
||
|
||
Config options: `--with-glog`, `--with-thrift`, `--with-rdma`, `--with-asan`, `--werror`
|
||
|
||
### CMake
|
||
|
||
```bash
|
||
mkdir build && cd build
|
||
cmake .. -DCMAKE_BUILD_TYPE=Release
|
||
make -j$(nproc)
|
||
```
|
||
|
||
Key CMake options: `-DWITH_GLOG=ON`, `-DWITH_THRIFT=ON`, `-DWITH_RDMA=ON`, `-DWITH_ASAN=ON`, `-DBUILD_UNIT_TESTS=ON`, `-DDOWNLOAD_GTEST=ON`
|
||
|
||
### Bazel
|
||
|
||
```bash
|
||
bazel build -- //... -//example/...
|
||
```
|
||
|
||
## Running Tests
|
||
|
||
Tests use Google Test. Build and run with Make:
|
||
|
||
```bash
|
||
cd test
|
||
make -j$(nproc)
|
||
./run_tests.sh # runs all: test_butil, test_bvar, bthread_*unittest, brpc_*unittest
|
||
```
|
||
|
||
Run a single test binary:
|
||
|
||
```bash
|
||
cd test
|
||
./<test_binary> # e.g. ./test_butil
|
||
./<test_binary> --gtest_filter='TestSuite.TestName' # single test case
|
||
```
|
||
|
||
With CMake:
|
||
|
||
```bash
|
||
cmake .. -DBUILD_UNIT_TESTS=ON -DDOWNLOAD_GTEST=ON
|
||
make -j$(nproc) && ctest
|
||
```
|
||
|
||
ASAN is used in CI: `ASAN_OPTIONS="detect_leaks=0:detect_stack_use_after_return=1" ./<test_binary>`
|
||
|
||
## Architecture
|
||
|
||
### Core Libraries (under `src/`)
|
||
|
||
- **brpc/** — The RPC framework. Three core abstractions:
|
||
- `Server` — listens on a port, dispatches requests to registered services. Supports multiple protocols on the same port via protocol detection.
|
||
- `Channel` — client-side stub for sending RPCs. Configured with naming service, load balancer, timeout, retry policies via `ChannelOptions`.
|
||
- `Controller` — per-RPC context carrying request metadata, error state, timeout, attachments. Extends `google::protobuf::RpcController`.
|
||
- `Socket` (`socket.h`) — low-level connection abstraction managing fd lifecycle, SSL, and write buffering. Uses `VersionedRefWithId` for safe concurrent access.
|
||
|
||
- **bthread/** — M:N user-level threading (the concurrency foundation of brpc)
|
||
- `TaskControl` manages a pool of worker pthreads, each running a `TaskGroup`
|
||
- `TaskGroup` owns a local run queue + work-stealing queue (`work_stealing_queue.h`, lock-free CAS-based)
|
||
- `bthread_start_urgent()` runs task immediately on current worker; `bthread_start_background()` enqueues for later scheduling
|
||
- Most brpc callbacks execute in bthreads, not pthreads
|
||
|
||
- **butil/** — Base utility library (originally forked from Chromium)
|
||
- `IOBuf` (`iobuf.h`) — zero-copy buffer using reference-counted blocks with SmallView (2 inline BlockRefs) / BigView (heap) optimization. Core data structure for network I/O.
|
||
- Also: FlatMap, logging, string utils, time, files, containers
|
||
- `third_party/` — Bundled snappy, murmurhash3, symbolize, etc.
|
||
|
||
- **bvar/** — Multi-dimensional statistics variables
|
||
- Thread-local aggregation via `AgentCombiner` for lock-free counters
|
||
- Types: `Adder`, `Recorder`, `LatencyRecorder`, `PassiveStatus`
|
||
- Composable windows: `PerSecond<Adder<>>`, `Window<>`
|
||
- Auto-exposed via builtin `/vars` endpoint
|
||
|
||
- **json2pb/** — Bidirectional JSON <-> Protobuf conversion
|
||
|
||
- **mcpack2pb/** — MCPack format <-> Protobuf conversion (Baidu legacy)
|
||
|
||
### Key Design Patterns
|
||
|
||
- **Protocol plugins** (`src/brpc/policy/`): Each protocol implements the `Protocol` struct (function pointers for Parse/Serialize/Pack/Process/Verify in `protocol.h`), registered via `RegisterProtocol()`. 18 protocols implemented. Adding a new protocol does not touch core files — see `docs/en/new_protocol.md`.
|
||
- **Naming services / Load balancers**: Pluggable via `NamingService` and `LoadBalancer` interfaces (DNS, ZK, etcd, round-robin, consistent hashing, locality-aware, etc.)
|
||
- **Builtin services** (`src/brpc/builtin/`): Every brpc server auto-exposes debug endpoints — `/status`, `/vars`, `/flags`, `/rpcz`, `/hotspots` (cpu/heap/contention profilers).
|
||
- **Error model**: Functions return 0/-1 with errno; `Controller::SetFailed()` for RPC-level errors; custom error codes defined in `errno.proto`.
|
||
- **Memory patterns**: `ResourcePool` / `ObjectPool` for socket and bthread recycling; `butil::intrusive_ptr` for hot-path reference counting; IOBuf for zero-copy I/O.
|
||
|
||
## Code Style
|
||
|
||
- Google C++ Style Guide with **4-space indentation**
|
||
- Protocol-specific code goes in `src/brpc/policy/`, not in core files like `server.cpp` or `channel.cpp`
|
||
- General modifications should not be hidden inside protocol-specific files
|
||
- All changes require unit tests
|
||
- CI runs on GitHub Actions (Linux gcc/clang, macOS) — must pass before merge
|
||
- Uses C++11 minimum; some C++17 features with compiler guards. Legacy patterns (`DISALLOW_COPY_AND_ASSIGN` macro) still prevalent.
|
||
|
||
## Dependencies
|
||
|
||
Required: protobuf (3.x–21.x), gflags, leveldb, openssl. Optional: glog, thrift, gperftools (tcmalloc/profiler), gtest (for tests), libunwind, abseil-cpp, BoringSSL (alternative to openssl).
|
||
|
||
## Examples
|
||
|
||
30+ examples in `example/` covering echo, HTTP, gRPC, streaming, redis, memcache, thrift, RDMA, coroutine, etc. Each has its own Makefile/CMakeLists.txt/BUILD.
|