README.zh.hant.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。