上游参考

§4 gRPC 总览 · 本专题 grpc/06（H2 6.x）。

对照 cartographer-project/async_grpc（Apache-2.0）。Autonomy vendoring 至 autonomy/common/async_grpc/，命名空间 autonomy::common::async_grpc。

---

6.1 上游仓库

项目	说明
仓库	github.com/cartographer-project/async_grpc
场景	Cartographer Cloud 传感器流式上传
Autonomy 扩展	BUILD_TRACING、Bridge GrpcBridgeServer

Cartographer Cloud	Autonomy Bridge
Client-Stream 传感器上行	ReceiveBotStates / ReceiveBotEvents（规划）
Server-Stream 结果	SendNavigationCommand 进度
ExecutionContext 共享 MapBuilder	GrpcBridgeContextInterface + Navigator（待接）

6.2 设计动机

同步 gRPC server 每 RPC 一线程；机群 + 多 Stream 不可扩展。官方：固定 worker + libgrpc 异步 CQ + 自建 EQ + Handler 模型。

6.3 官方最小示例：GetSquare

上游 Unary 示例（README）：

DEFINE_HANDLER_SIGNATURE(
    GetSquareSignature, proto::GetSquareRequest, proto::GetSquareResponse,
    "/proto.Math/GetSquare")

void OnRequest(const GetSquareRequest& req) override {
    auto r = std::make_unique<GetSquareResponse>();
    r->set_output(req.input() * req.input());
    Send(std::move(r));  // Unary：Send 即 Finish(OK)
}

Bridge 用法相同，见 grpc/04 §4.1。

6.4 官方线程保证

单次 RPC 交换内 Handler 创建后始终在同一线程执行 → 不必 thread-safe。跨 Rpc 共享 mutable 状态须 ExecutionContext。

6.5 Rpc 预创建

启动 idle Rpc 数：\(N_{\text{idle}} = N_{\text{cq}} \times M\)。Bridge：\(4 \times 2 = 8\)。

6.6 RpcEvent 与 WRITE_NEEDED

libgrpc 完成 op → CQ → PushToEventQueue → EQ。Send() / GetWriter() → WRITE_NEEDED 直注 EQ、绕过 CQ。

6.7 Client

Client<Signature> 同步调用远端 RPC；NavigatorStub uplink 可复用。见 client.h。

6.8 RetryStrategy

RetryStrategy + Client::Retry 封装重试；uplink 弱网场景可选。

6.9 RpcHandlerTestServer

testing/rpc_handler_test_server.h：同步驱动 Handler 全生命周期，mock ExecutionContext 后单元测试 Bridge Handler（优于纯 grpcurl）。

6.10 Autonomy 扩展

能力	上游	Autonomy
Tracing	可选	BUILD_TRACING=1
MessageSize	—	Builder 可设 send/receive 上限
Bridge	—	GrpcBridgeServer + AutonomyService

进一步阅读：上游 README · gRPC C++ Async · grpc/05 Bridge 集成

---

导航：← 05 Bridge 集成 · 07 Handler 注册 →