Mooncake on Hellokitty's Blog

Mooncake 中的协程：从 coro_rpc 到同步接口桥接

Fri, 28 Aug 2026 14:55:00 +0800

Mooncake 确实使用了协程，但它并不是把整个系统改造成“全异步架构”。截至本文分析的主分支提交 3d1665a，协程主要出现在控制面 RPC、连接管理和阻塞任务卸载等 I/O 密集路径；对外接口仍大量保留同步调用形式。

这形成了一个很实用的分层：内部用 C++20 协程组织异步流程，边界处再按需要转换成同步返回值或回调。

技术栈

Mooncake 的协程代码主要建立在两层库之上：

async_simple::coro::Lazy<T> 表示一个惰性异步任务；
yalantinglibs 的 coro_rpc 和 coro_io 提供异步 RPC、网络连接与线程池调度。

典型代码形态如下：

async_simple::coro::Lazy<Result> request() {
    auto response = co_await client.send_request(...);
    co_return response;
}

Lazy<T> 创建后通常不会立刻执行。它需要被另一个协程 co_await，通过 .start(...) 启动，或者由 syncAwait(...) 驱动至完成。

路径一：Mooncake Store 的 Master RPC

mooncake-store/src/master_client.cpp 中的 MasterClient::invoke_rpc 是最清晰的例子。它的外部签名是同步的：

tl::expected<ReturnType, ErrorCode>
MasterClient::invoke_rpc(Args&&... args);

函数内部却先构造 Lazy，再连续等待两个异步阶段：

return async_simple::coro::syncAwait(
    [&]() -> async_simple::coro::Lazy<
                tl::expected<ReturnType, ErrorCode>> {
        auto pending = co_await pool->send_request(
            [&](coro_io::client_reuse_hint,
                coro_rpc::coro_rpc_client& client) {
                return client.send_request<ServiceMethod>(...);
            });

        if (!pending.has_value()) {
            co_return tl::make_unexpected(ErrorCode::RPC_FAIL);
        }

        auto result = co_await std::move(pending.value());
        co_return result->result();
    }());

这里有两次 co_await：

vLLM 与 Mooncake 对接源码解读：Prefill/Decode 分离中的 KV Cache 如何跨节点传输

Mon, 24 Aug 2026 16:58:43 +0800

深入分析 vLLM 内置 MooncakeConnector：从代理拆分请求、Scheduler 元数据、GPU KV Cache 注册，到 Mooncake Transfer Engine 通过 RDMA 将 Prefill KV 直接搬到 Decode 节点。

Mooncake Store 源码阅读（四）：Master 持久化、快照与热备恢复

Mon, 24 Aug 2026 10:40:00 +0800

解读 Mooncake Store Master 的 oplog、snapshot、standby 和租约机制，以及它们如何保护控制面状态。

Mooncake Store 源码阅读（三）：Get、副本选择与淘汰回收

Mon, 24 Aug 2026 10:30:00 +0800

从 GetReplicaList、Replica 状态和批量 Eviction 分析 Mooncake Store 的读取与空间回收。

Mooncake Store 源码阅读（二）：Put 写入链路与对象原子性

Mon, 24 Aug 2026 10:20:00 +0800

沿 RealClient、PutStart、Transfer Engine 和 PutEnd 阅读 Mooncake Store 的完整写入链路。

Mooncake Store 源码阅读（一）：从对象存储接口到控制面与数据面

Mon, 24 Aug 2026 10:10:00 +0800

从源码目录、进程角色和一次请求的路径入手，解释 Mooncake Store 如何把元数据控制与大对象传输分离。

Mooncake Transfer Engine 源码阅读（四）：TENT 下一代架构如何重构传输引擎

Fri, 21 Aug 2026 11:18:00 +0800

Mooncake 仓库同时存在经典 Transfer Engine 和 TENT（Transfer Engine Next）。TENT 不是简单增加一种 Transport，而是重构了 Segment 生命周期、运行时调度、拓扑选择、QoS、故障转移和插件体系。

阅读版本：

Mooncake commit: 777cc7782417b6e554cf7c2d53210d0d8f89f5cc

一、为什么需要下一代引擎

经典 TE 已经支持 RDMA、TCP、NVLink 和多种硬件，但随着后端增加，TransferEngineImpl + MultiTransport + 各 Transport 容易出现几个问题：

Segment 生命周期分散在元数据和后端注册逻辑中；
传输选择主要依赖静态协议与局部规则；
多 rail、拥塞、故障和 QoS 难以统一调度；
不同后端各自维护进度线程和资源模型；
新硬件接入需要理解大量经典内部约定；
请求取消、deadline 和 failover 缺少统一运行时。

TENT 将这些能力上移到 Runtime 层。

二、目录结构

TENT 核心位于：

tent/src/runtime/
├── transfer_engine_impl.cpp
├── segment.cpp
├── segment_manager.cpp
├── segment_registry.cpp
├── segment_tracker.cpp
├── transport_loader.cpp
├── transport_selector.cpp
├── progress_worker.cpp
├── admission_queue.cpp
├── qos_contract.cpp
├── receiver_credit.cpp
├── topology.cpp
├── control_plane.cpp
└── proxy_manager.cpp

外围包括：

Mooncake Transfer Engine 源码阅读（三）：RDMA、TCP 与请求完成状态机

Fri, 21 Aug 2026 11:17:00 +0800

Transfer Engine 的公共 API 很统一，但 RDMA 和 TCP 的实现差异很大。RDMA 需要 MR、QP、WR 和 CQ；TCP 需要连接、lane、消息 framing 和接收端主动拷贝。本文沿源码比较两条路径，并分析 Batch 状态如何完成。

阅读版本：

Mooncake commit: 777cc7782417b6e554cf7c2d53210d0d8f89f5cc

一、Transport 抽象

Transport 基类统一定义：

install / uninstall
registerLocalMemory / unregisterLocalMemory
submitTransfer
getTransferStatus
allocateBatchID / freeBatchID

它还定义 TransferRequest、TransferStatus 和内部 BufferEntry。

公共抽象要求每个后端回答三个问题：

本地内存如何准备为可传输状态；
请求怎样排队和执行；
如何查询每个 task 的最终状态和字节数。

具体连接模型不属于公共 API。

二、RDMA 初始化

RDMA 后端主要位于：

rdma_transport.cpp
rdma_context.cpp
rdma_endpoint.cpp
endpoint_store.cpp
worker_pool.cpp

安装阶段通常完成：

枚举 RDMA devices / ports / GID
  -> 创建每张 HCA 的 context
  -> 建立 PD、CQ 等资源
  -> 启动 worker / poller
  -> 发布 NIC endpoint metadata
  -> 准备 endpoint store

Mooncake 支持多 HCA、多端口和 GPU 内存，因此一个逻辑请求可能被切到多个 rail 上并行发送。

Mooncake Transfer Engine 源码阅读（二）：Segment、内存注册与元数据服务

Fri, 21 Aug 2026 11:16:00 +0800

Mooncake Transfer Engine 的核心抽象不是“远端指针”，而是 Segment + BufferDesc + Metadata。应用注册本地内存后，TE 将地址范围、设备位置和传输协议发布为 Segment 描述，其他节点才能定位并建立连接。

阅读版本：

Mooncake commit: 777cc7782417b6e554cf7c2d53210d0d8f89f5cc

一、为什么不能直接发送指针

一个进程中的地址：

0x7f12...

在另一个进程中通常没有意义。即使两台机器都使用相同数值，它们也不指向同一块物理内存。

高性能传输还需要额外信息：

这是 CPU DRAM 还是 GPU VRAM；
对应哪张 GPU；
是否注册成 RDMA MR；
rkey 和网卡 endpoint 是什么；
是否能用 NVLink、GPU IPC 或 CXL；
节点当前是否存活；
地址区间是否已经注销。

因此 TE 把地址空间包装成 Segment，并通过元数据服务交换描述。

二、`SegmentDesc`

TransferMetadata::SegmentDesc 是远端发现的中心结构，主要承载：

Segment ID
Segment 名称
协议或协议集合
本机 RPC / endpoint 信息
BufferDesc 列表
设备与拓扑信息
后端扩展元数据

可以把一个 Segment 理解成某个 TE 实例公开的可传输地址空间：

Segment: decode-node-7
├── Buffer A: CPU metadata pool, protocol=rdma
├── Buffer B: GPU KV pool, protocol=rdma
└── Buffer C: GPU KV pool, protocol=hip

同一块 GPU buffer 可以被多个后端注册，从而同时支持：

Mooncake Transfer Engine 源码阅读（一）：统一传输 API 与整体架构

Fri, 21 Aug 2026 11:15:00 +0800

Mooncake Transfer Engine（简称 TE）是 Mooncake 数据平面的基础组件。它不负责决定 KV Cache 应该放在哪里，而是提供统一接口，把一段本地内存搬到远端 Segment，或者从远端 Segment 读取到本地内存。

本文基于 Mooncake 官方仓库：

commit: 777cc7782417b6e554cf7c2d53210d0d8f89f5cc
commit date: 2026-08-21

当前仓库同时保留经典 Transfer Engine 和下一代 TENT。前三篇先阅读经典实现，第四篇再分析 TENT 如何重构控制面、调度和传输后端。

一、源码布局

核心目录为 mooncake-transfer-engine/：

路径	作用
`include/transfer_engine.h`	对外 C++ API
`include/transfer_engine_impl.h`	经典实现内部接口
`include/transport/transport.h`	Transport 抽象、请求和状态
`include/transfer_metadata.h`	Segment、Buffer 与元数据接口
`src/transfer_engine.cpp`	公共 API 转发层，同时兼容经典 TE 与 TENT
`src/transfer_engine_impl.cpp`	初始化、内存注册、Segment 与批次管理
`src/multi_transport.cpp`	安装和选择具体 Transport
`src/transport/`	RDMA、TCP、NVLink、NVMe-oF、EFA 等后端
`tent/`	Transfer Engine Next 实现

TE 的经典架构可以概括为：

应用 / Mooncake Store
        │
        ▼
TransferEngine
        │
        ▼
TransferEngineImpl
   ┌────┼──────────────┐
   ▼    ▼              ▼
Metadata  MultiTransport  Batch 生命周期
          │
   ┌──────┼───────────────┐
   ▼      ▼       ▼       ▼
  RDMA   TCP    NVLink   NVMe-oF ...

二、公共 API 是一层门面

TransferEngine 类本身很薄，大多数函数转发给 TransferEngineImpl：

Mooncake on Hellokitty's Blog

Mooncake 中的协程：从 coro_rpc 到同步接口桥接

技术栈

路径一：Mooncake Store 的 Master RPC

vLLM 与 Mooncake 对接源码解读：Prefill/Decode 分离中的 KV Cache 如何跨节点传输

Mooncake Store 源码阅读（四）：Master 持久化、快照与热备恢复

Mooncake Store 源码阅读（三）：Get、副本选择与淘汰回收

Mooncake Store 源码阅读（二）：Put 写入链路与对象原子性

Mooncake Store 源码阅读（一）：从对象存储接口到控制面与数据面

Mooncake Transfer Engine 源码阅读（四）：TENT 下一代架构如何重构传输引擎

一、为什么需要下一代引擎

二、目录结构

Mooncake Transfer Engine 源码阅读（三）：RDMA、TCP 与请求完成状态机

一、Transport 抽象

二、RDMA 初始化

Mooncake Transfer Engine 源码阅读（二）：Segment、内存注册与元数据服务

一、为什么不能直接发送指针

二、SegmentDesc

Mooncake Transfer Engine 源码阅读（一）：统一传输 API 与整体架构

一、源码布局

二、公共 API 是一层门面

二、`SegmentDesc`