CoRPC：基于 CXL 共享内存的页面聚合 RPC

CoRPC 面向高并发、小消息较多的微服务通信场景，通过编译期消息布局生成、P1/PF 混合数据路径和页面级批量发布，降低 RPC 消息组织与逐请求控制开销。系统提供页面生命周期管理、generation 校验、Lease 回收及 QoS 控制，并包含 Twitter Trace、Hotel Reservation、Online Boutique 和 Open Match 等测试场景。

路径	内容
`src/`	源码、接口定义、构建与实验脚本、第三方依赖和预处理数据样本
`docs/`	项目说明、创新说明、工具使用说明等参赛文档
`tests/`	测试入口及验证方法，测试源码位于 `src/tests/`
`demo/`	覆盖完整实验流程的小规模演示入口及操作说明
`presentation/`	答辩 PPT 与演示视频

仓库保留源码、必要文档、测试脚本、应用输入数据、预期输出及选定的轨迹样本。构建目录、编译产物、实验结果、运行日志、结果压缩包和机器专用临时文件不纳入版本控制。测试与实验运行后生成的结果保留在运行机器本地。

系统环境与依赖

运行环境为 Linux，基础功能可在 Ubuntu 22.04 或 WSL2 中使用 POSIX 共享内存验证。CXL 硬件实验需要实际共享内存设备、正确的映射与访问权限，并按平台确认 NUMA 或 DAX 接入方式。

构建需要 C++17 编译器、CMake/CTest 3.20+、Make、Protobuf 编译器及 C++ 开发库、gRPC C++ 开发库、grpc_cpp_plugin、OpenSSL 开发库、Python 3.10+ 及 Python protobuf 包。脚本还使用 Bash、timeout、stdbuf、sha256sum、ss 等 Linux 工具。nlohmann/json 3.10.5 头文件随仓库提供于 src/third_party/；Python protobuf 不随仓库提供，需安装 python3-protobuf，供代码生成插件使用，不能代替 Protobuf/gRPC 的 C++ 开发库。

Ubuntu 22.04 的依赖安装示例：

sudo apt-get update
sudo apt-get install -y build-essential cmake pkg-config \
  protobuf-compiler libprotobuf-dev protobuf-compiler-grpc \
  libgrpc++-dev libssl-dev python3 python3-protobuf coreutils iproute2 procps util-linux

解压原始 Twitter .zst 数据时额外安装 zstd；NUMA 绑定实验额外需要 numactl。其他 Linux 发行版需使用对应的软件包名称。

安装后先执行 python3 -c 'from google.protobuf.compiler import plugin_pb2; print("PYTHON_PROTOBUF=PASS")' 和 bash src/scripts/01_check_environment.sh source。详细安装、版本记录、离线准备及复现边界见可复现依赖说明。原 CXL 实验环境与本地 WSL 验证环境分别列出，不要求两者性能数字相同。

构建

以下命令从仓库根目录开始，在 Linux / WSL2 的 Bash 中执行：

cd src
JOBS=4 bash scripts/02_build_project.sh

该脚本以 Release 模式构建主项目及 Hotel Reservation、Online Boutique 的 gRPC 基线，主项目默认 Slot 大小为 256 字节。构建目录在本机生成，不随源码提交。

完整实验流程演示

安装依赖后，从仓库根目录先准备一次（编译各配置并测试），再运行现场演示：

bash demo/run-demo.sh --prepare
bash demo/run-demo.sh

现场演示包括 KV RPC、07 的五项 Twitter 实验和 Slot/Flush 对比、既有 08 的 QoS 功能及四组负载对照、09 的三个应用实验。Twitter 默认每配置 50,000 条、统一 2×60 个调用线程、50 μs Flush，预热一轮后轮换顺序测量三轮；QoS 和应用每次测量 3 秒，应用使用 4 个调用线程。运行时直接显示实验表格；完整数据集和应用并发配置可用 --all-configs，包含构建的原有流程检查可用 --check-all。日志和结果写入 src/result/demo_workflows/，默认不打包；添加 --archive 时归档至 src/release/，均不上传仓库。2026 年 10 月 2 日旧版在本机 WSL 的默认参数演示得到 S3/S0 吞吐比 4.13；该数字是历史记录，不代表本次代码更新后的性能。2026 年 10 月 5 日更新后，重新准备构建、缩短参数演示及默认规模演示均通过，最终输出 DEMO_STATUS=PASS。本机结果不能代替正式 CXL 性能实验。快速运行参数及其他选项详见 demo/README.md。

该流程用于验证全部实验能否运行，短时结果不能代替正式性能实验。仅查看执行计划可使用 bash demo/run-demo.sh --plan。

测试与性能复现

从仓库根目录运行正确性测试：

bash tests/run-tests.sh

测试覆盖代码生成、消息布局、共享内存映射、Ring、页面轮转、并发封页、大对象及 QoS。该入口运行 CTest 并在测试失败时返回非零退出码，详见 tests/README.md。

Twitter 基准冒烟测试及完整实验从 src/ 运行：

cd src
bash scripts/05_run_smoke_benchmark.sh
# 完整实验会额外构建不同 Slot 配置并运行多组负载：
bash scripts/07_run_twitter_experiments.sh all

实验参数由对应脚本和环境变量控制；结果生成到 src/result/，不上传仓库。其他应用的运行脚本位于 src/benchmarks/ 各应用子目录。性能结论应对应实际硬件、操作系统、运行参数和重复次数。

新增的 QoS 专项实验从 src/ 运行，均提供 smoke 和 formal 模式：

cd src
bash scripts/08d_run_bottleneck_experiment.sh smoke  # 瓶颈定位与扩页决策
bash scripts/08e_run_dynamics_experiment.sh smoke    # 负载变化与页面配额适应
bash scripts/08c_run_admission_matrix.sh smoke      # S0–S3 准入消融矩阵

正式实验将 smoke 改为 formal，并按目标机器调整脚本说明中的并发、时长及容量参数。结果分别保存在 src/result/qos_bottleneck_sessions/、qos_dynamics_sessions/ 和 qos_performance_sessions/。POSIX 共享内存下运行成功只能验证流程，不能代替 CXL 硬件性能结果。默认现场 Demo 为控制时长，仍运行既有 QoS 关闭／开启对照；08c、08d、08e 是独立的专项实验入口，不包含在默认 Demo 中。

数据集来源与重新生成

Twitter 样本来自官方公开的匿名缓存访问轨迹 twitter/cache-trace，对应 Juncheng Yang、Yao Yue、Rashmi Vinayak 的 OSDI 2020 论文 A large scale analysis of hundreds of in-memory cache clusters at Twitter。上游提供原始轨迹下载入口、七列 CSV 格式及 CC-BY-4.0 授权说明；本项目将选定样本转换为 tracebin 并生成受控混合负载，保留来源署名和转换说明。

本项目提供以下预处理输入，合计约 38.15 MiB；它们是测试数据集，不是实验结果：

文件（相对于 `src/datasets/twitter-cache/processed/`）	记录数	大小
`cluster18.first1m.tracebin`	1,000,000	30.52 MiB
`cluster37.first100k.tracebin`	100,000	3.05 MiB
`controlled/mix_large25.first50k.tracebin`	50,000	1.53 MiB
`controlled/mix_large75.first50k.tracebin`	50,000	1.53 MiB
`controlled/mix_large99.first50k.tracebin`	50,000	1.53 MiB

现有预处理文件的 SHA-256 见 src/datasets/twitter-cache/SHA256SUMS。可从仓库根目录校验：

cd src/datasets/twitter-cache
sha256sum -c SHA256SUMS

如果某次仓库发布因容量限制未包含 .tracebin 文件，可从上游下载 cluster18 和 cluster37 的原始 CSV / .zst 轨迹，再从仓库根目录执行下列转换命令。/path/to/ 应替换为实际下载位置：

cd src
python3 benchmarks/twitter_trace/scripts/prepare_trace.py \
  /path/to/cluster18.0.zst \
  datasets/twitter-cache/processed/cluster18.first1m.tracebin \
  --max-requests 1000000
python3 benchmarks/twitter_trace/scripts/prepare_trace.py \
  /path/to/cluster37.0.zst \
  datasets/twitter-cache/processed/cluster37.first100k.tracebin \
  --max-requests 100000
python3 benchmarks/twitter_trace/scripts/generate_controlled_mixes.py

prepare_trace.py 按输入顺序转换有效请求，生成带 32 字节文件头及固定 32 字节记录的二进制轨迹。上述原始文件名仅为上游分片命名示例；原始分片和记录顺序不同会产生不同样本。复现当前样本版本请使用随仓库提供且通过 SHA-256 校验的文件。

三组 mix_large 为团队由 cluster18、cluster37 样本构造的负载，大对象目标比例分别为 25%、75%、99%，每组 50,000 条，生成脚本固定随机种子为 20260728。脚本会在本地同时生成构造说明和统计结果。

应用基准所需的小型输入数据位于 src/benchmarks/hotel_reservation/data/、src/benchmarks/online_boutique/data/ 等目录，功能验证需要的预期输出也随源码保留。

许可证

项目源码采用木兰宽松许可证第二版（Mulan PSL v2），见 src/LICENSE。第三方组件及数据遵循各自许可证与授权条件。随仓库分发的第三方头文件、接口与数据，以及系统安装的外部库，分别列于第三方来源与使用范围；文件快照校验见 src/third_party/SHA256SUMS，不计入团队原创核心算法。