CXL-RPC：面向共享内存的多路径 RPC 系统

CXL-RPC 是面向共享内存通信场景的 RPC 运行时原型，将共享内存（SHM）与 TCP 接入统一调用接口。应用可以在同一套业务处理逻辑下使用小消息 Inline、大对象 Buffer、固定 TCP、AUTO 准入选路及请求级 STRIPE 分流；运行时负责异步完成、超时处理和共享缓冲区回收。

本提交为 V2 Final RC1，共享内存 ABI 1.3。在初赛功能基础上，决赛版本增加了多 Lane 请求处理与完成发布、独立进程会话管理、RocksDB／官方 YCSB 应用接入，并补充本机和真实 CXL 后端的分阶段验证。最终提交源码已于 2026-10-07 完成 openEuler 双 Guest 重建、全量功能复验及新增动态检查；本次补验使用文件 ivshmem，历史真实 CXL 实验仍按原批次引用。核心工程可独立编译，包内另附用于本机演示的预编译程序及应用依赖。

下列命令使用 Bash，从本提交根目录执行，即同时含有 src/、tests/、demo/ 的目录。无需将项目安装到系统；构建和新日志放在提交目录外。

1. 应用场景

场景	项目提供的能力与验证范围
共享内存进程间服务调用	通过共享 Ring 和 Buffer Pool 交换请求、响应，支持复杂类型、并发提交和超时回收；可在普通 Linux 上使用 POSIX 共享内存复现
具有共享映射条件的 Guest 间通信	支持显式共享区配置及独立进程会话；历史实验已在同宿主双 Guest、真实 CXL 设备支撑的共享区上验证
同一业务的多路径接入	固定 SHM／TCP、AUTO 和 STRIPE 共用调用接口；可观察路径选择、受控降级和发布后禁止跨路径重放
远程 KV 与应用评测	KV 演示覆盖字符串、数组和嵌套结构；RocksDB 服务与官方 YCSB binding 验证记录操作、读取值和资源回收

共享内存通信要求两端能访问同一共享区域；本项目不提供任意两台普通主机之间的共享内存互联。当前定位为研究与比赛原型。

2. 主要功能

• 统一传输接口：SHM Inline／Buffer 与 TCP 共用请求及完成语义，支持固定路径、AUTO 和请求级 STRIPE。STRIPE 分配完整请求，不拆分单条消息。
• 发布前准入与可回放选路：AUTO 根据健康状态、消息大小和资源快照决定可用路径；决策快照可离线回放。请求一旦发布，不因超时转投另一条路径重放。
• 多 Lane 并行处理：协议支持 1～8 Lane，默认 1 Lane；主要端到端验证覆盖 1／2／4 Lane。每 Lane 配置独立 Server Progress 和 Publisher，Worker×Lane 使用独立完成 outbox，共享 Scheduler 与 Worker Pool。
• 大对象生命周期管理：双 Owner Buffer Pool 区分请求和响应的内存所有权；大响应通过 RELEASE／ACK 回收，覆盖迟到响应、重复 RELEASE、超时及正常会话排空。
• 独立进程与会话隔离：提供服务端、客户端和 READY／FINISH 协议，以会话标识拒绝旧会话消息；支持正常退出时核对调用、完成和回收计数。
• 应用与诊断：提供 RocksDB 服务、JNI／YCSB binding，以及路径、Lane、角色 CPU、锁等待等诊断入口。应用 binding 当前使用固定 SHM 或 TCP。

协议和实现细节见源码技术文档，创新贡献及已有工作对照见项目创新说明。

3. 材料导航

工程、演示与测试

入口	内容
源码工程	CMake、头文件、实现、工具、测试、脚本、应用 binding 和隔离依赖；复制工程时须保留隐藏的 .deps/
演示入口	完整演示、核心演示、烟测与归档结果；运行方法及失败处理见本文第 5～9 节
演示环境／固定配置	运行条件、各阶段输入与数据流、模拟及注入边界
演示验证结果	当前入口的三轮本机彩排、烟测和资源回收记录
测试总览／功能测试	当前提交版本的全新构建与功能证据，历史记录单独标识
最终源码补验报告／验收核对	2026-10-07 openEuler 双 Guest、跨 Guest 应用及动态检查；原始日志与源码身份随结果保留
优化验证／版本对照	优化前后结果、未达标项，以及初赛／决赛可比性限制
复现方法／统计结果	离线复算、正式矩阵配置及原始日志入口

YCSB 与传统 RPC 对照补测的材料入口：

入口	内容
实验说明与数据	对应决赛 PPT 第 24、25 页；结果图片、逐轮数据、原始日志、统计口径和重复性未达标项
可选 gRPC 基线与复现	独立基线补丁、工程准备、构建、功能验证、测量和绘图脚本

决赛文档与附件

材料	当前状态
项目说明书终版 PDF	已提供
项目创新说明 PDF／可编辑 DOCX	已提供
成员分工及主要贡献说明 PDF	已提供
决赛 PPT	已更新，第 24、25 页为 YCSB 与传统 RPC 对照补测
决赛演示视频	MP4，约 2 分 6 秒、6.75 MB
人工智能及第三方工具使用说明	已提供
作品原创承诺书	已提供

4. 系统环境与依赖

使用方式	要求
核心源码构建	Linux、CMake ≥3.16、支持 C++17 的编译器、Make 等 CMake 构建工具；以下测试流程使用 Python ≥3.10
本机测试与演示	可用的 POSIX 共享内存、/dev/shm 空间和 loopback 端口；Bash、Python ≥3.10、常用 GNU 工具
随附完整应用演示	Linux x86_64，glibc／libstdc++ 与随附二进制兼容；无需系统安装 Java 或 RocksDB
可选应用重新构建	支持 C++20 的编译器，curl、tar、SHA256 工具及依赖下载网络；构建脚本准备 RocksDB 10.10.1、JDK 17、Maven 3.9.11 和 YCSB 0.17.0 相关依赖

预编译程序已验证于 Ubuntu 24.04.4 LTS、Intel i5-10500（6 核 12 线程）。包内使用隔离的 Temurin JDK 17.0.18+8、JNI 库与 RocksDB 程序；动态库依赖见 runtime-dependencies.txt。

核心默认构建不下载 RocksDB／Java 依赖。本机流程不需要 CXL 设备、Guest 镜像、SSH 或管理员权限。其他发行版优先从源码构建。最终提交源码已在两个 openEuler 24.03 LTS-SP3 Guest 内分别重建并通过全量功能回归；应用依赖在 openEuler 中原生构建，不能直接假定随附 Ubuntu 应用库与其他发行版兼容。

5. 快速运行完整演示

先检查随附源码与程序是否完整：

python3 -B demo/run.py check

当前预期为 CHECK PASS MANIFEST.sha256 files=659。这只校验文件完整性，不代表运行环境已经通过检查。

再运行核心功能及 RocksDB／YCSB 演示：

cxlrpc_demo_dir=$(mktemp -d /tmp/cxlrpc-live.XXXXXX)
python3 -B demo/run.py live --output "$cxlrpc_demo_dir/session"

入口负责启动和结束子程序，无需手动启动服务端。7 个核心阶段覆盖多路径 KV、选路回放、受控健康与资源压力、迟到响应回收、发布后禁止重放及会话隔离。应用阶段在 SHM、TCP 下分别执行 load1000 和 run2000，共 4 个会话；READ 启用逐次值校验和 JNI 检查。

成功输出应包含：

FINAL_DEMO PASS core=7 application_sessions=4
DEMO_ENTRY PASS action=live ...

… 表示随运行变化的耗时字段。入口日志位于 $cxlrpc_demo_dir/session/console.log，分阶段原始日志和汇总位于其 run/ 子目录。回放、人工注入和策略预览在演示中标明；不能将其当作真实设备故障检测或性能测量。

查看归档优化结果：

python3 -B demo/run.py results

此命令先校验测试材料，再显示既有实验的统计表和未达标项，不产生新的性能数据。

6. 从源码构建与核心测试

在同一终端依次执行：

cxlrpc_build_dir=$(mktemp -d /tmp/cxlrpc-review-build.XXXXXX)
cmake -S src/cxlrpc-v2-final-rc1 -B "$cxlrpc_build_dir" -DCMAKE_BUILD_TYPE=Release
cmake --build "$cxlrpc_build_dir" -j2
ctest --test-dir "$cxlrpc_build_dir" --output-on-failure
"$cxlrpc_build_dir/kv_rpc_demo"

当前默认配置包含 70 项 CTest，预期全部通过。KV 演示末尾应包含：

kv_rpc_demo: PASS paths=inline,buffer,tcp,auto,stripe shm_tcp_equal=1 release_acks=4 chunks=0

使用刚构建的程序运行 7 阶段核心演示：

cxlrpc_core_dir=$(mktemp -d /tmp/cxlrpc-core.XXXXXX)
python3 -B demo/run.py core --build "$cxlrpc_build_dir" --output "$cxlrpc_core_dir/session"

预期包含 FINAL_DEMO CORE_PASS application=SKIPPED 和 DEMO_ENTRY PASS action=core。该流程不运行 RocksDB／YCSB，不能替代上一节的完整应用验证。

可选：重新构建应用

仅在需要修改应用或重建依赖时使用。先将整个源码工程（包括隐藏目录）复制到独立工作区，再在副本中按应用构建与运行执行：

bash scripts/build_opt3_rocksdb.sh
bash scripts/build_opt3_ycsb.sh
ctest --test-dir build-ycsb --output-on-failure

这三条命令的工作目录是源码副本根目录。脚本可能下载依赖，Maven 缓存未完整随包提供；它们会写入 .deps/ 与 build-ycsb/，不应在冻结提交副本中直接执行。原有 CMake 缓存含路径，运行上述固定脚本前，先将副本中已有的 build-ycsb/ 和 .deps/rocksdb-build/ 移到副本外备份，使脚本创建新构建目录。项目构建无需执行系统级安装命令。10月7日补验另在临时 openEuler Guest 中原生重编译 RocksDB 10.10.1，并重建项目 C++／JNI 与 Java binding；实际构建参数和依赖范围见补验报告。

7. 测试方法与结果解读

7.1 三模式烟测

cxlrpc_smoke_dir=$(mktemp -d /tmp/cxlrpc-smoke.XXXXXX)
python3 -B demo/run.py smoke --output "$cxlrpc_smoke_dir/session"

预期包含 FINAL_COMPARE PASS accounting_points= 9 和 DEMO_ENTRY PASS action=smoke。该测试运行随附程序，检查 SHM／TCP／AUTO 的调用计数与回收；短烟测不验收正式性能。若需使用第 6 节新构建的核心程序，可增加 –build “$cxlrpc_build_dir”。

7.2 既有数据离线复算

cxlrpc_recalc_dir=$(mktemp -d /tmp/cxlrpc-evidence.XXXXXX)
python3 -B tests/recompute.py --output "$cxlrpc_recalc_dir/result"

预期输出 RECOMPUTE PASS。脚本从原始日志重算当前三模式、历史多 Lane、应用和热点消融等共 180 个点，并核对计数、窗口及汇总。PASS 表示解析与统计一致；原实验中的尾延迟、重复性和采集扰动失败仍保留。

7.3 正式性能复测

需要重新测量时，按复现方法执行固定 27 点矩阵，使用新的输出目录，避免同时编译或运行其他高负载任务。该文档给出负载、预热、请求数及三轮顺序；不要将烟测数据混入正式结果。本次 README 定稿没有重跑正式矩阵或真实 CXL 实验。

已有结果应按以下边界阅读：

• RC1 本机 27 点调用与回收通过，重复性通过 8／9 组；大包 TCP 的 P99 最大／最小比值为 1.6704，未达标。
• 历史 CXL Echo 中，1／2／4 Lane 对应配置的吞吐中位数为 301,648／309,983／360,718 IOPS；4 Lane 相对 1 Lane 为 +19.58%，P99 为 +3.90%。Lane、提交线程和 Worker 同时变化，不能解释为纯 Lane 收益或初赛到决赛的总提升率。
• RocksDB／YCSB 多 Lane 实验未达到一致改善标准；增加客户端并发的实验有吞吐收益，也存在重复性失败。完整条件与失败项见优化验证。

7.4 最终提交源码补验（2026-10-07）

本次使用最终提交源码，核对 142 个源码文件身份一致，未修改提交源码。新增结果与历史性能矩阵分开记录：

检查范围	结果
本机全新构建	核心 70/70、应用 72/72，完整演示 7 个核心阶段及 4 个应用会话通过
两个 openEuler 24.03 LTS-SP3 Guest	分别重新构建，各自核心 70/70、应用 72/72及完整演示通过
跨 Guest 会话	3 轮统一 KV 会话、18 个 C++／YCSB 应用会话通过，计数、读取值及资源回收正常
ASan／UBSan	本机及 openEuler 应用回归各 72/72 通过
TSan	本机及 openEuler 核心回归各 70/70；本机项目与 RocksDB 均插桩的应用回归 72/72 通过

两个 Guest 使用专用 256 MiB 文件支持的 ivshmem，本次未重新验收真实 CXL 硬件。本机 ASan／UBSan 因依赖的无 RTTI 配置未启用 vptr 子检查，openEuler 构建保留该检查；两者的 RocksDB 库均未做 ASan／UBSan 插桩。TSan 通过运行仅对测试进程禁用 ASLR。长时稳定性仍待进一步验证。

完整环境、检查边界、失败尝试和原始日志见复验报告、验收核对及补验证据目录。这些功能与动态检查不产生新的性能提升数据，也不改变历史重复性未通过项。

7.5 完整性与版本身份

(cd src/cxlrpc-v2-final-rc1 && sha256sum -c MANIFEST.sha256)
(cd tests && sha256sum -c EVIDENCE.sha256)
(cd demo && sha256sum -c MANIFEST.sha256)

三份清单分别覆盖原有源码与随附程序、原有测试材料（含 tests/最终版本复验/）、演示材料。新增 YCSB／gRPC 补测材料使用独立清单，在项目根目录执行：

sha256sum -c tests/grpc-comparison/SUPPLEMENT.sha256

该清单覆盖当前 README、更新后的 PPT，以及 tests/grpc-comparison/、src/grpc-baseline/ 中的全部补充材料（清单自身除外）。历史根目录 MANIFEST.sha256 保留原样，其中 README 和 PPT 的旧哈希已不再匹配当前文件，不能用于当前整包验收；其余原有文件仍按历史清单追踪。tests/EVIDENCE.sha256 不包含新增补测材料；tests/SUBMISSION.sha256 也是早期历史清单，不用于当前整包验收。

7.6 YCSB 与传统 RPC 对照补测

当前 PPT 第 24、25 页分别展示吞吐与 P99 对照。四组配置为 gRPC、项目 TCP、SHM 单 Lane 和 SHM 四 Lane，共用 YCSB、JNI 与 RocksDB 业务逻辑；测量环境为本机 POSIX 共享内存／TCP loopback，固定 4 个客户端线程与 4 个业务 Worker。

三类负载下，SHM1 吞吐中位数较 gRPC 高 16.12%～34.97%，READ P99 同时增加 67.08%～94.04%；SHM4 吞吐均低于 gRPC。36 个测点执行与计数检查通过，9/12 组重复性达标。正式窗口为 6.57～23.68 秒，属于短测，与原多 Lane 实验及真实 CXL 批次分别归档。

补测的归档数据已离线重算，逐轮数据、汇总统计、相对 gRPC 变化三个 CSV 与原图所用数据一致；补丁应用后的 134 个测量源码文件与归档指纹一致。材料整理未重跑性能实验。配置、原始日志、失败项及复现方法见补测说明和独立基线入口。基线在独立工程副本中应用，不改变原主工程和演示入口。

8. 已知限制

1. 部署与硬件范围：历史真实 CXL 结果来自同宿主双 Guest 共享设备支撑区域，不是物理多主机 CXL Fabric 实验；部分 TCP 对照使用 QEMU 用户态转发，不代表物理网络极限。最终提交源码已完成文件 ivshmem 双 Guest 全量功能复验；最终版本的真实 CXL 硬件复验尚待补充。独立进程说明与CXL 部署条件包含环境约束，历史编排脚本需适配，不能直接照搬设备地址和旧运行路径。
2. AUTO 能力范围：AUTO 是确定性的发布前准入策略，不保证选出最低延迟路径；当前 Ring 快照仍经 Lane 0 兼容接口读取，不具备完整多 Lane 拥塞视图。响应大小感知选路尚未完成，JNI／YCSB 不使用 AUTO。
3. 并发与协议范围：多 Lane 保留单 Client Progress、共享 Scheduler 和 Worker Pool；客户端提交与 Buffer 分配仍有锁。ABI 1.3 不与 ABI 1.2 混接，多 Lane 也不等于吞吐线性扩展。
4. 可靠性范围：发布后禁止跨路径重放不等于 exactly-once。已有验证覆盖正常排空、超时、迟到完成及特定故障注入，不提供进程崩溃后的持久化恢复或通用高可用机制；独立进程示例以单客户端会话为主。
5. 应用与性能范围：RocksDB 数据保存在普通文件系统，不在 CXL 共享区；YCSB 接口不支持 SCAN，实验采用非同步落盘配置。现有短时测试不替代长时间稳定性验证，也不能将小型热数据集结果推广为生产数据库收益。缺少初赛与决赛同环境、同负载的完整性能 A/B。
6. 默认策略与许可：backoff、affinity 等可选优化保持默认关闭，backlog 扫描间隔仍为 1；实验未证明应统一替换默认配置。随附第三方许可及集中索引应保留，项目自身许可证待团队确认。

9. 运行失败时

各次演示输出目录必须是提交目录外尚不存在的新目录。示例先用 mktemp 创建父目录，再由入口创建 session/ 或 result/，不要提前创建最终输出目录，也不要覆盖归档证据。

若命令返回非零，保留 console.log 和阶段日志，从首个失败项检查二进制兼容性、端口占用、共享内存空间及配置。固定端口测试和演示按顺序运行；清理前核实日志记录的进程与共享内存对象归属，避免影响其他任务。中断或部分阶段成功不算完整验收通过。