README.zh.md

CMP

English · 简体中文 · 繁體中文

CMP（Coroutine Machine Process）是基于 C++23 Modules 的协程运行时，提供任务、结构化并发、显式调度、同步原语和原生异步 TCP。

快速开始

安装 xlings，在仓库根目录执行：

xlings install
mcpp --version
mcpp build
mcpp test

mcpp 版本以 .xlings.json 为准。根库使用 LLVM 22.1.8；独立示例在 Linux 使用 GCC 16.1.0，在 macOS/Windows 使用 LLVM 22.1.8。

运行涵盖主要 API 的综合示例：

cd examples/basic
mcpp run

最小示例

在 cmp/ 旁创建 demo/，将仓库的 .xlings.json 复制到 demo/。创建 demo/mcpp.toml；目录名称不同时调整依赖路径：

[package]
name = "cmp-demo"
version = "0.1.0"
standard = "c++23"

[dependencies.mcpplibs]
cmp = { path = "../cmp" }

[toolchain]
default = "llvm@22.1.8"
linux = "gcc@16.1.0"

创建 demo/src/main.cpp：

import std;
import mcpplibs.cmp;

namespace cmp = mcpplibs::cmp;

cmp::Task<int> answer(cmp::RunLoop::Scheduler scheduler) {
    co_await scheduler.schedule();
    co_return 42;
}

int main() {
    cmp::RunLoop loop {};
    std::println("{}", loop.run(answer(loop.get_scheduler())));
}

在 demo/ 执行：

xlings install
mcpp run

程序输出 42。Task 惰性启动；run() 驱动根任务，schedule() 将协程放回该 RunLoop 的队列。协程源码需要同时导入 std 和 mcpplibs.cmp。

API 速查

用途	API
任务与结果	Task<T>、Task<void>
结构化并发	when_all()、TaskGroup
调度与定时	RunLoop、ThreadPool、schedule()、schedule_after()、schedule_at()；定时调度仅由 RunLoop 提供
事件与互斥	OneShotEvent、AsyncManualResetEvent、AsyncMutex
阻塞调用隔离	run_blocking()，使用独立的 ThreadPool 实例
TCP 客户端与服务端	IoContext、TcpStream、TcpListener
协作式取消	显式传入 std::stop_token；取消获胜时抛出 OperationCancelled

使用约束

• Task 只能移动、消费一次；命名 Task 通过 std::move() 交给 co_await 或组合原语。
• 已使用的 TaskGroup 必须完成 join() 才能离开作用域，异常路径也一样。
• 取消和线程切换均需显式表达。阻塞函数会阻塞当前线程，取消不能抢占已开始的同步调用。
• 事件、锁、执行器和借用的 TCP 缓冲区必须覆盖其使用期。完整生命周期及错误规则见架构说明。

当前未提供 detached 执行、work stealing、DNS、TLS、原生异步文件 I/O、channel 或通用 timeout/race 组合。

开发与参考

• 架构与最小用法：执行模型、取消、TCP 契约和严格验证命令
• 与 Go GMP 对照：实现状态、技术边界与后续任务
• 测试与综合示例：可执行的 API 用法
• readiness 基准与线程池基准：本地负载与性能测量
• 实施与验收记录：已验证结果、平台缺口和后续工作
• mcpp · Issues

许可证：Apache License 2.0。