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)

# 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

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

bazel build -- //... -//example/...

Running Tests

Tests use Google Test. Build and run with Make:

cd test
make -j$(nproc)
./run_tests.sh          # runs all: test_butil, test_bvar, bthread_*unittest, brpc_*unittest

Run a single test binary:

cd test
./<test_binary>                    # e.g. ./test_butil
./<test_binary> --gtest_filter='TestSuite.TestName'   # single test case

With CMake:

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.