C++20协程

第 1 章 学习目标与导论

1.1 本章在 C++ 知识体系中的位置

C++20 协程（coroutine，由 Melvin Conway 于 1958 年在 COBOL 编译器设计中首次提出，由「cooperative routine」缩写而来，强调「子程序主动让出控制权」的协作式调度，与操作系统抢占式调度的「routine」相对）是 C++20 引入的语言级异步与惰性求值基础设施。它位于 C++ 知识体系的「并发与异步层」，向上承接 cpp/右值引用与移动语义、cpp/模板元编程、cpp/智能指针详解、cpp/RAII资源管理，向下衔接 cpp/C++23新特性、cpp/异常处理、cpp/Lambda表达式 等高级主题。

C++20 协程的核心价值在于：让异步代码拥有同步代码的可读性，同时保持异步非阻塞的执行效率。在网络编程、I/O 密集型应用、生成器场景与状态机实现中，协程能显著降低代码复杂度，从回调地狱（callback hell）与 Promise 链式调用中解放出来。

学习本章前，读者应当已经掌握：

• cpp/概述与现代标准：C++11/14/17/20/23 的标准演进
• cpp/基础语法：变量声明、作用域、控制流
• cpp/数据类型详解：基本类型、模板基础
• cpp/指针 与 cpp/引用：裸指针/引用的内存模型
• cpp/面向对象基础：构造、析构、RAII
• cpp/模板元编程：模板推导、concept 约束
• cpp/右值引用与移动语义：值类别、std::move、std::forward

掌握本章后，读者将能够阅读 cpp/C++23新特性（std::generator、std::execution senders/receivers）以及未来 C++26 的统一异步模型，并具备在生产代码中实现自定义 Task 类型、Generator、SyncWait/WhenAll 组合子与线程池集成协程的能力。

1.2 学习目标

本章遵循 Bloom 分类法，按认知层级递进组织学习目标：

1. 记忆（Remember）：复述 co_await、co_yield、co_return 三关键字的语法形态、Promise/Awaitable/Awaiter 三元模型与 coroutine_handle/promise_type 的接口契约。
2. 理解（Understand）：解释协程的形式化语义——状态机模型、continuation、suspend/resume 的 CPS（Continuation-Passing Style）变换、协程帧内存布局与 HALO（Heap Allocation eLision Optimization，由 Gor Nishanov 在 C++17 协程提案中提出，指编译器在「协程生命周期严格嵌套于调用者生命周期」时省略堆分配，将协程帧分配到调用者栈帧中的优化；命名借鉴 RVO 的「省略」语义）优化。
3. 应用（Apply）：使用 co_await、co_yield、co_return 编写异步 I/O、Generator、Task 类型与 SyncWait/WhenAll 组合子，并能与线程池、Executor 集成。
4. 分析（Analyze）：对比 co_await 表达式的编译器展开规则（await_ready/await_suspend/await_resume 三步法）、co_yield 到 co_await 的等价变换、co_return 到 promise.return_value/return_void 的派发逻辑。
5. 评估（Evaluate）：评估对称协程（symmetric transfer，返回 coroutine_handle）与非对称协程（asymmetric，返回 void/bool）在栈深度、调度开销与可组合性上的取舍。
6. 对比（Analyze）：对比 C++20 协程与 Python async/await、JavaScript async/await、Rust async/await、Go goroutine、C# async/await、Java Virtual Threads 的运行时模型与语义差异。
7. 创造（Create）：设计基于 Senders/Receivers（P2300 std::execution）的统一异步抽象，构建支持取消、进度报告与多执行器的生产级协程架构。

1.3 阅读建议

• 零基础读者：先通读第 2 章历史动机、第 5 章 C++20 协程机制详解、第 6 章三关键字详解，建立直观认识；再回看第 3-4 章形式化定义与理论推导。
• 有异步编程经验读者：重点关注第 7 章对比分析，对比 C++20 协程与已知模型（如 Python async/await、JavaScript Promise）的异同。
• 进阶读者：直接研读第 4 章理论推导（HALO、对称转移）、第 9 章工程实践（Task/WhenAll/Senders）与第 10 章案例研究（cppcoro/folly::coro/P2300）。
• 应试/面试读者：第 5、6、8、11 章为高频考点；第 11 章习题覆盖 4 类题型（fill-blank/choice/code-fix/open-ended）。

第 2 章 历史动机与演进

2.1 1958-1972：协程概念起源

协程的雏形可追溯至 1958 年，Melvin Conway 在 COBOL 编译器设计中首次提出「cooperative routine」概念，将编译过程划分为词法分析、语法分析、语义分析等阶段，每个阶段作为独立的协程，通过显式让出控制权协作推进。Conway 在 1963 年的论文《Design of a Separable Transition-Diagram Compiler》中正式发表论文描述这一思想。

1967 年，Simula 67（由 Ole-Johan Dahl 与 Kristen Nygaard 设计）首次将协程作为语言级特性引入，用于离散事件仿真。Simula 67 的 detach 语句允许对象主动挂起，等待再次被 resume 调用恢复。这是协程从理论概念走向程序设计语言的里程碑。

2.2 1972-2000：从 Lua 到 Python 的协程实践

后续语言纷纷探索协程机制：

• Modula-2（1979, Niklaus Wirth）：通过 COROUTINE 模块提供有栈协程原语
• Scheme（1975, Sussman 与 Steele）：通过 call/cc（call-with-current-continuation）提供一等续延（first-class continuation），是协程最一般化的理论基础
• Icon（1977, Ralph Griswold）：通过 suspend 关键字实现目标导向求值（goal-directed evaluation），co_yield 概念的先驱
• Lua 5.0（2003, Roberto Ierusalimschy）：通过 coroutine.create/resume/yield 提供完整的非对称协程

Python 在 2.2 版本（2001）引入生成器（PEP 255），2.5 版本（2006）通过 PEP 342 增强为协程雏形（添加 send/throw/close 方法），3.5 版本（2015, PEP 492）正式引入 async/await 语法，成为现代异步 Python 的基石。

2.3 2008-2014：JavaScript async/await 与 Node.js 革命

JavaScript 在 ES6（2015）引入 Promise，ES2017（ES8）正式引入 async/await 语法。Node.js 的 libuv 事件循环与 Promise/async 模型结合，彻底改变了服务端 JavaScript 的并发模型。这一波异步革命影响了几乎所有现代语言的协程设计。

2.4 2016-2017：C++ 协程提案 N3762 与 Resumable Functions V2

C++ 社区对协程的关注始于 2012 年。Gor Nishanov 向 ISO C++ 委员会提交 N3722《Resumable Functions》提案，引入 await 关键字与 __resumable 函数标识。提案经过多轮演进：

• N3762《Resumable Functions V2》（2013, Hartmut Kohlhoff 与 Gor Nishanov）：引入 co_await、co_yield、co_return 三关键字，定义 Promise 类型接口与 coroutine_handle 抽象。这是 C++20 协程语法的直接前身
• N4402、P0057R0-R7（2014-2017）：Coroutines TS（技术规范）逐步成熟
• P0912R5《Merge Coroutines TS into Working Draft》（2018）：将 Coroutines TS 合并入 C++20 工作草案

C++20 协程的设计哲学可概括为**「机制而非策略」**（mechanism, not policy）：标准仅提供语言级原语（三关键字、Promise 接口、coroutine_handle），不提供现成的 Task/Generator 类型，让库作者自由组合调度策略、Executor 与取消模型。

2.5 2020-2023：C++20 标准化与 C++23 std::generator

C++20（ISO/IEC 14882:2020）正式纳入协程特性。但标准库仅提供以下基础设施：

• std::coroutine_handle<Promise>：协程句柄
• std::suspend_always 与 std::suspend_never：两个最简 Awaitable
• std::noop_coroutine()：空操作协程

C++23（ISO/IEC 14882:2023）补完 std::generator（P2502R2），提供同步生成器标准实现：

#include <generator>
#include <iostream>

// C++23 标准 std::generator，无需手写 Generator 即可使用
std::generator<int> range23(int start, int end) {
    for (int i = start; i < end; ++i) {
        co_yield i;
    }
}

// 支持引用类型，零拷贝产出
std::generator<const std::string&> get_names(const std::vector<std::string>& names) {
    for (const auto& name : names) {
        co_yield name;
    }
}

int main() {
    for (auto x : range23(0, 5)) {
        std::cout << x << ' ';  // 输出: 0 1 2 3 4
    }
    std::cout << '\n';
    return 0;
}

2.6 2022-2026：P2300 std::execution 与统一异步模型

C++20 协程虽灵活但缺乏统一的调度与组合抽象。P2300《std::execution: A General Purpose Asynchronous Framework》（Kaiser, Sutter 等）提出 Senders/Receivers 模型，作为 C++26 异步基础设施的标准提案：

• Sender：描述异步操作的「发送者」，可通过 connect 与 Receiver 组合
• Receiver：描述异步操作的「接收者」，提供 set_value、set_error、set_stopped 三个完成通道
• Scheduler：抽象执行器，提供 schedule() 返回 Sender

Senders/Receivers 与协程互操作：协程可通过 await_transform 适配任意 Sender，Sender 可通过 as_awaitable 适配为协程 Awaitable。这种统一模型让 C++26 的异步代码可同时使用协程语法与 Sender 组合子。

2.7 演进时间线

timeline
    title C++ 协程演进时间线
    section 1958-1972 概念起源
        1958 : Conway 提出 coroutine 概念
        1963 : Conway 论文发表
        1967 : Simula 67 引入 detach/resume
    section 1972-2000 实践探索
        1979 : Modula-2 COROUTINE
        1975 : Scheme call/cc
        1977 : Icon suspend
        2003 : Lua 5.0 coroutine
    section 2001-2015 异步革命
        2001 : Python 2.2 生成器 PEP 255
        2015 : Python 3.5 async/await
        2015 : JavaScript ES2015 Promise
        2017 : JavaScript async/await
    section 2016-2020 C++ 标准化
        2013 : N3762 Resumable Functions V2
        2017 : Coroutines TS P0057
        2018 : P0912R5 合并入 C++20
        2020 : C++20 协程正式发布
    section 2020-2026 完善与统一
        2023 : C++23 std::generator P2502
        2022 : P2300 std::execution 提案
        2026 : C++26 预计纳入 Senders/Receivers

第 3 章 形式化定义

3.1 协程的代数定义

按 ISO/IEC 14882:2023 [dcl.fct.def.coroutine]，协程是「函数体内出现 co_await、co_yield 或 co_return 任一关键字的函数」。形式化定义如下：

协程的语义模型可表示为带状态的转移系统 $\mathcal{C} = (S, s_0, F, \delta)$：

• $S$：协程的状态空间，包括局部变量、挂起点索引与 promise 对象
• $s_0 \in S$：初始状态（对应 initial_suspend 后的状态）
• $F \subseteq S$：终态集合（对应 final_suspend 后的状态）
• $\delta: S \times \text{Event} \to S$：状态转移函数，Event $\in$ {resume, suspend, return, exception}

3.2 CPS（Continuation-Passing Style）变换

协程的编译器实现基础是 CPS 变换（由 Peter Landin 于 1964 年在 SECD 机器论文中引入，指「程序剩余待执行的运算」，是函数式编程语言理论中的核心概念）。将直接风格的函数 $f$ 变换为 CPS 风格 $f^*$：

其中 $\text{Cont}$ 是续延类型（continuation type）。在 C++ 协程中，每个挂起点对应一次显式的续延捕获：

编译器将 co_await 表达式展开为「捕获当前续延 $k$（即协程帧的恢复点）+ 调用 $e.\text{await\_suspend}(k)$」的形式。这就是协程能「暂停-恢复」的本质：每次挂起都是一次续延捕获，每次恢复都是一次续延调用。

3.3 Promise 类型：协程的策略对象

每个协程关联一个 Promise 类型（promise_type，源自拉丁语 promissum，字面意为「承诺、约定」；C++20 协程中 promise_type 是协程行为的「策略对象」，承诺提供 get_return_object、initial_suspend、final_suspend 等接口来控制协程的生命周期）。Promise 必须提供以下接口：

// Promise 必须提供的最小接口集
struct promise_type {
    // 1. 创建协程返回对象（在协程体执行前调用）
    ReturnType get_return_object();

    // 2. 初始挂起策略：控制协程是否立即执行
    std::suspend_always initial_suspend() noexcept;   // 或 suspend_never
    // 3. 最终挂起策略：控制协程结束后是否挂起等待销毁
    std::suspend_always final_suspend() noexcept;     // 推荐返回 suspend_always

    // 4. co_return 处理（二选一）
    void return_void();                               // co_return; 或函数体结束
    void return_value(T value);                       // co_return expr;

    // 5. 异常处理
    void unhandled_exception();

    // 6. co_yield 处理（可选）
    std::suspend_always yield_value(T value);
};

形式化约束：

3.4 Awaitable 与 Awaiter：等待的三步协议

可等待体（awaitable，由 await 与 -able 后缀组成，指「可被 co_await 表达式操作的类型」）与等待器（awaiter，由 await 与 -er 后缀组成；C++20 协程规范要求 awaitable 类型可通过 operator co_await 或直接提供 await_ready/await_suspend/await_resume 三个成员函数转化为 awaiter，对应「等待的三步法协议」）通过以下协议解耦「等待语义」与「协程机制」：

// Awaiter 必须提供的三步协议
struct Awaiter {
    // 步骤 1：检查是否已就绪
    bool await_ready();

    // 步骤 2：挂起协程（三种返回类型）
    void await_suspend(std::coroutine_handle<> handle);                    // 非对称：恢复后返回调用者
    bool await_suspend(std::coroutine_handle<> handle);                    // 返回 true 挂起，false 立即恢复
    std::coroutine_handle<> await_suspend(std::coroutine_handle<> handle); // 对称转移：返回目标协程

    // 步骤 3：恢复后获取结果
    T await_resume();
};

形式化语义：

get_awaiter(e) 的派发规则：

1. 若 e 的类型有 operator co_await() 成员，调用之
2. 否则在当前命名空间查找 operator co_await(e) 自由函数
3. 否则 e 本身必须实现三步协议，直接作为 awaiter

3.5 coroutine_handle：协程句柄

std::coroutine_handle<Promise> 是协程的非拥有句柄（non-owning handle），可视为「协程帧的弱引用」：

#include <coroutine>

// 协程句柄的核心接口
void demo_handle() {
    std::coroutine_handle<int> h;  // 模板参数为 Promise 类型，void 表示无类型

    h.resume();          // 恢复协程（必须未结束且未在执行）
    h.destroy();         // 显式销毁协程帧（必须未结束）
    h.done();            // 查询是否处于终态（仅在 final_suspend 挂起时返回 true）

    auto& promise = h.promise();   // 访问 promise 对象
    auto address = h.address();    // 获取地址（void* 形式）

    // 从 promise 反向获取 handle
    auto h2 = std::coroutine_handle<int>::from_promise(promise);

    // 从地址恢复 handle
    auto h3 = std::coroutine_handle<int>::from_address(address);

    // 空操作协程：永远 done() 为 true，resume/destroy 无副作用
    auto noop = std::noop_coroutine();
}

3.6 协程帧内存布局

协程帧（coroutine frame）是编译器为每个协程实例生成的堆分配对象，包含以下字段：

graph TB
    subgraph "Coroutine Frame (堆分配)"
        P["Promise 对象<br/>promise_type 实例"]
        I["挂起点索引<br/>suspend_index: int"]
        L1["局部变量<br/>跨挂点存活的变量提升至此"]
        L2["参数副本<br/>按值传递的参数拷贝"]
        F["填充对齐<br/>alignment padding"]
    end
    H["coroutine_handle<br/>(非拥有，仅指针)"]
    H -.->|"address()"| P
    style P fill:#aaf,stroke:#333
    style I fill:#faa,stroke:#333
    style L1 fill:#afa,stroke:#333
    style L2 fill:#ffa,stroke:#333

形式化结构（伪代码）：

// 编译器生成的协程帧结构（示意）
struct __coro_frame_<ReturnType, Promise, Args...> {
    void (*resume_fn)(__coro_frame_*);   // 恢复函数指针
    void (*destroy_fn)(__coro_frame_*);  // 销毁函数指针
    Promise __promise;                   // Promise 对象
    int __suspend_index;                 // 当前挂起点索引
    Args... __args;                      // 参数副本
    /* 跨挂点存活的局部变量提升至此 */
    ReturnType::__locals... __locals;
};

3.7 HALO：堆分配省略优化

HALO（Heap Allocation eLision Optimization，由 Gor Nishanov 在 C++17 协程提案中提出，指编译器在「协程生命周期严格嵌套于调用者生命周期」时省略堆分配，将协程帧分配到调用者栈帧中的优化；命名借鉴 RVO 的「省略」语义）是协程性能优化的关键。

HALO 触发条件（保守判定）：

1. 协程的 get_return_object() 返回的对象直接持有 coroutine_handle
2. 协程的生命周期严格嵌套于调用者（调用者必须 await 协程完成后才能销毁 handle）
3. Promise 类型不提供自定义 operator new/operator delete

满足条件时，编译器可将协程帧分配到调用者栈帧中，避免堆分配。形式化：

#include <coroutine>
#include <iostream>

// HALO 友好的协程设计：生命周期严格嵌套
struct HALOFriendly {
    struct promise_type {
        HALOFriendly get_return_object() {
            return HALOFriendly{std::coroutine_handle<promise_type>::from_promise(*this)};
        }
        std::suspend_always initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        void return_void() noexcept {}
        void unhandled_exception() noexcept {}
    };
    std::coroutine_handle<promise_type> handle;
};

HALOFriendly simple_coro() {
    co_return;
}

int main() {
    auto h = simple_coro();
    h.handle.resume();
    std::cout << "done: " << h.handle.done() << '\n';  // 输出: done: 1
    h.handle.destroy();
    return 0;
}

第 4 章 理论推导与编译器变换

4.1 co_await 表达式的编译器展开

按 ISO/IEC 14882:2023 [expr.await]，co_await expr 的编译器展开遵循以下步骤：

1. 获取 awaiter：通过 operator co_await 查找或直接使用 expr
2. 调用 awaiter.await_ready()，若返回 true 则跳到步骤 5
3. 挂起协程，调用 awaiter.await_suspend(handle)，根据返回值决定后续行为：
   • 返回 void：协程保持挂起，控制权返回给恢复者
   • 返回 bool：true 同 void，false 立即恢复当前协程
   • 返回 coroutine_handle<>：执行对称转移至目标协程
4. 协程恢复（被外部调用 resume 或对称转移回来），回到 co_await 表达式
5. 调用 awaiter.await_resume() 获取结果，作为 co_await 表达式的值

伪代码展开：

// 原始代码
auto result = co_await expr;

// 编译器展开（伪代码）
auto&& __awaiter = get_awaiter(expr);
auto&& __result;
if (!__awaiter.await_ready()) {
    // 保存当前状态到协程帧
    __frame->__suspend_index = __CURRENT_SUSPEND_POINT;
    // 调用 await_suspend，根据返回类型派发
    if constexpr (returns_void(__awaiter.await_suspend(handle))) {
        __awaiter.await_suspend(__frame->to_handle());
        return;  // 控制权返回调用者
    } else if constexpr (returns_bool(...)) {
        if (__awaiter.await_suspend(handle)) return;
        // false 直接继续
    } else {
        // 对称转移
        auto __next = __awaiter.await_suspend(handle);
        __next.resume();  // 尾调用，不增加栈深度
        return;
    }
    // 恢复点：从这里继续
}
__result = __awaiter.await_resume();
// 后续代码使用 __result

4.2 co_yield 到 co_await 的等价变换

按 [expr.yield]，co_yield expr 等价于 co_await promise.yield_value(expr)：

promise.yield_value(expr) 返回一个 Awaitable（通常为 std::suspend_always），表达「产出值并挂起」的语义。

#include <coroutine>
#include <iostream>

struct Generator {
    struct promise_type {
        int current_value;
        Generator get_return_object() {
            return Generator{std::coroutine_handle<promise_type>::from_promise(*this)};
        }
        std::suspend_always initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        // yield_value 返回 suspend_always，挂起协程
        std::suspend_always yield_value(int v) {
            current_value = v;
            return {};
        }
        void return_void() noexcept {}
        void unhandled_exception() noexcept {}
    };
    std::coroutine_handle<promise_type> handle;
};

// co_yield value 等价于 co_await promise.yield_value(value)
Generator counter(int n) {
    for (int i = 0; i < n; ++i) {
        co_yield i;  // 等价于: co_await __promise.yield_value(i);
    }
}

int main() {
    auto g = counter(3);
    g.handle.resume();
    std::cout << g.handle.promise().current_value << '\n';  // 输出: 0
    g.handle.resume();
    std::cout << g.handle.promise().current_value << '\n';  // 输出: 1
    g.handle.resume();
    std::cout << g.handle.promise().current_value << '\n';  // 输出: 2
    g.handle.destroy();
    return 0;
}

4.3 co_return 的派发逻辑

co_return expr; 在编译器展开中等价于：

若函数体执行到末尾未显式 co_return，编译器等价于插入 co_return;。若函数体抛出未捕获异常，调用 promise.unhandled_exception() 后跳转至 final_suspend。

#include <coroutine>
#include <iostream>
#include <optional>

struct Task {
    struct promise_type {
        std::optional<int> result;
        Task get_return_object() {
            return Task{std::coroutine_handle<promise_type>::from_promise(*this)};
        }
        std::suspend_never initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        // co_return expr; 调用 return_value
        void return_value(int v) { result = v; }
        // co_return; 或函数末尾 调用 return_void
        // 若同时定义 return_value 与 return_void 则编译错误
        void unhandled_exception() { std::terminate(); }
    };
    std::coroutine_handle<promise_type> handle;
};

Task compute() {
    co_return 42;  // 派发到 promise.return_value(42)
}

int main() {
    auto t = compute();
    std::cout << *t.handle.promise().result << '\n';  // 输出: 42
    t.handle.destroy();
    return 0;
}

4.4 状态机生成与协程变换流程

编译器将协程函数变换为状态机：每个挂起点对应一个状态，恢复时根据 __suspend_index 跳转到对应状态。

flowchart TB
    A["协程函数源码"] --> B["编译器分析<br/>识别挂起点"]
    B --> C["生成状态机结构<br/>__coro_frame_"]
    C --> D["生成 resume 函数<br/>switch(suspend_index)"]
    C --> E["生成 destroy 函数<br/>调用析构"]
    D --> F["生成 get_return_object<br/>调用前的初始化"]
    F --> G["堆分配协程帧<br/>operator new"]
    G --> H["调用 promise 构造<br/>+ initial_suspend"]
    H --> I["执行协程体<br/>至首个挂起点"]
    I --> J{是否到达 final_suspend?}
    J -->|否| K["保存 suspend_index<br/>返回调用者"]
    J -->|是| L["调用 final_suspend"]
    K --> M["外部 resume()"]
    M --> I
    L --> N["协程帧等待 destroy"]
    style A fill:#aaf
    style C fill:#faa
    style I fill:#afa
    style K fill:#ffa
    style L fill:#faa

形式化变换（伪代码）：

// 原始协程
Task example(int n) {
    int x = 0;
    co_await std::suspend_always{};
    x = n + 1;
    co_await std::suspend_always{};
    co_return x;
}

// 编译器生成的状态机（伪代码）
struct __frame_example {
    void (*resume)(__frame_example*);
    void (*destroy)(__frame_example*);
    Task::promise_type __promise;
    int __suspend_index = 0;
    int __arg_n;
    int __local_x;
};

void __resume_example(__frame_example* f) {
    switch (f->__suspend_index) {
    case 0: goto L0;
    case 1: goto L1;
    case 2: goto L2;
    }

L0:
    f->__local_x = 0;
    f->__suspend_index = 1;
    if (!std::suspend_always{}.await_ready()) {
        std::suspend_always{}.await_suspend(/* handle */);
        return;  // 挂起
    }
L1:
    f->__local_x = f->__arg_n + 1;
    f->__suspend_index = 2;
    if (!std::suspend_always{}.await_ready()) {
        std::suspend_always{}.await_suspend(/* handle */);
        return;
    }
L2:
    f->__promise.return_value(f->__local_x);
    goto FINAL;

FINAL:
    f->__suspend_index = -1;
    if (!f->__promise.final_suspend().await_ready()) {
        f->__promise.final_suspend().await_suspend(/* handle */);
        return;
    }
}

4.5 对称协程 vs 非对称协程

非对称协程（asymmetric coroutine）：await_suspend 返回 void 或 bool。恢复时控制权返回到最近一次 resume 的调用者，形成调用栈。

对称协程（symmetric coroutine）：await_suspend 返回 coroutine_handle<>。挂起当前协程后直接转移到目标协程，无调用栈增长。

#include <coroutine>
#include <iostream>

// 对称转移示例：避免递归协程的栈溢出
struct SymmetricTask {
    struct promise_type {
        SymmetricTask get_return_object() {
            return {std::coroutine_handle<promise_type>::from_promise(*this)};
        }
        std::suspend_always initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        void return_void() noexcept {}
        void unhandled_exception() noexcept {}
        // 自定义 await_transform：内层 SymmetricTask 直接对称转移
        auto await_transform(SymmetricTask inner) {
            struct Awaiter {
                std::coroutine_handle<> next;
                bool await_ready() noexcept { return false; }
                // 返回 coroutine_handle 触发对称转移
                std::coroutine_handle<> await_suspend(std::coroutine_handle<>) noexcept {
                    return next;
                }
                void await_resume() noexcept {}
            };
            return Awaiter{inner.handle};
        }
    };
    std::coroutine_handle<promise_type> handle;
};

// 递归 100000 次仍 O(1) 栈空间
SymmetricTask chain(int n) {
    if (n > 0) co_await chain(n - 1);
    co_return;
}

4.6 协程帧分配的复杂度分析

第 5 章 C++20 协程机制详解

5.1 协程的判定与函数签名

C++20 协程通过关键字识别：函数体内出现任一关键字即被编译器识别为协程。函数签名需满足：

• 返回类型必须包含 promise_type 内嵌类型（或特化 std::coroutine_traits<R, Args...>::promise_type）
• 不能使用 constexpr、consteval、return 语句（必须用 co_return）
• 不能有变长参数（va_list）
• 不能在 try-catch 块外使用 co_await（C++20 限制，C++23 放宽）

#include <coroutine>
#include <iostream>

// 协程判定示例
struct Task {
    struct promise_type {
        Task get_return_object() {
            return {std::coroutine_handle<promise_type>::from_promise(*this)};
        }
        std::suspend_never initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        void return_void() noexcept {}
        void unhandled_exception() noexcept {}
    };
    std::coroutine_handle<promise_type> handle;
};

Task coro1() { co_return; }                 // 协程：有 co_return
Task coro2() { co_await std::suspend_always{}; co_return; }  // 协程：有 co_await
Task coro3() { co_yield 1; }                // 编译错误：Task::promise_type 无 yield_value

int main() {
    auto t1 = coro1();
    auto t2 = coro2();
    t1.handle.destroy();
    t2.handle.destroy();
    return 0;
}

5.2 std::coroutine_traits 特化

对于无法修改返回类型的情况，可通过特化 std::coroutine_traits：

#include <coroutine>
#include <iostream>

// 第三方类型，无法修改
struct ThirdPartyTask {};

// 特化 coroutine_traits 为其提供 promise_type
template<>
struct std::coroutine_traits<ThirdPartyTask> {
    struct promise_type {
        ThirdPartyTask get_return_object() { return {}; }
        std::suspend_never initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        void return_void() noexcept {}
        void unhandled_exception() noexcept {}
    };
};

ThirdPartyTask demo() {
    co_return;
}

int main() {
    auto t = demo();
    return 0;
}

5.3 std::suspend_always 与 std::suspend_never

标准库提供两个最简 Awaitable：

#include <coroutine>

namespace std {
    struct suspend_always {
        bool await_ready() const noexcept { return false; }  // 总是挂起
        void await_suspend(coroutine_handle<>) const noexcept {}
        void await_resume() const noexcept {}
    };

    struct suspend_never {
        bool await_ready() const noexcept { return true; }   // 总是不挂起
        void await_suspend(coroutine_handle<>) const noexcept {}
        void await_resume() const noexcept {}
    };
}

5.4 自定义 Awaitable

Awaitable 可表达任意异步操作。下面实现一个延时 Awaitable：

#include <coroutine>
#include <chrono>
#include <thread>
#include <iostream>

// 延时 Awaitable：挂起协程 N 毫秒后恢复
struct Delay {
    int milliseconds;

    bool await_ready() const noexcept {
        return milliseconds <= 0;  // 非正数立即就绪
    }

    void await_suspend(std::coroutine_handle<> handle) const {
        // 启动新线程延时后恢复
        std::thread([handle, ms = milliseconds]() {
            std::this_thread::sleep_for(std::chrono::milliseconds(ms));
            handle.resume();
        }).detach();
    }

    void await_resume() const noexcept {}
};

// 简单 Task 类型
struct Task {
    struct promise_type {
        Task get_return_object() {
            return {std::coroutine_handle<promise_type>::from_promise(*this)};
        }
        std::suspend_never initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        void return_void() noexcept {}
        void unhandled_exception() noexcept { std::terminate(); }
    };
    std::coroutine_handle<promise_type> handle;
};

Task delayed_print() {
    std::cout << "before delay\n";
    co_await Delay{500};  // 挂起 500ms
    std::cout << "after delay\n";
    co_return;
}

int main() {
    auto t = delayed_print();
    // 主线程等待协程结束（简化演示，生产代码应用 sync_wait）
    std::this_thread::sleep_for(std::chrono::milliseconds(1000));
    t.handle.destroy();
    return 0;
}
// 输出:
// before delay
// after delay

5.5 operator co_await 重载

可为类型添加 operator co_await 成员或自由函数，将任意类型适配为 Awaitable：

#include <coroutine>
#include <chrono>
#include <thread>
#include <iostream>

// 时间间隔类型
struct seconds { double value; };

// 通过 operator co_await 适配为 Awaitable
auto operator co_await(seconds s) {
    struct Awaiter {
        double secs;
        bool await_ready() const noexcept { return secs <= 0; }
        void await_suspend(std::coroutine_handle<> h) const {
            std::thread([h, s = secs]() {
                std::this_thread::sleep_for(
                    std::chrono::milliseconds(static_cast<int>(s * 1000)));
                h.resume();
            }).detach();
        }
        void await_resume() const noexcept {}
    };
    return Awaiter{s.value};
}

struct Task {
    struct promise_type {
        Task get_return_object() { return {std::coroutine_handle<promise_type>::from_promise(*this)}; }
        std::suspend_never initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        void return_void() noexcept {}
        void unhandled_exception() noexcept {}
    };
    std::coroutine_handle<promise_type> handle;
};

Task wait_demo() {
    co_await seconds{0.3};  // 直接 co_await 自定义类型
    std::cout << "waited 0.3s\n";
}

int main() {
    auto t = wait_demo();
    std::this_thread::sleep_for(std::chrono::milliseconds(500));
    t.handle.destroy();
    return 0;
}

5.6 await_transform：自定义 co_await 行为

Promise 可定义 await_transform，对 co_await 的操作数进行预处理：

#include <coroutine>
#include <iostream>
#include <string>

struct LoggingTask {
    struct promise_type {
        LoggingTask get_return_object() {
            return {std::coroutine_handle<promise_type>::from_promise(*this)};
        }
        std::suspend_never initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        void return_void() noexcept {}
        void unhandled_exception() noexcept {}

        // 拦截所有 co_await 操作数，包装为带日志的 Awaiter
        template<typename T>
        auto await_transform(T&& expr) {
            struct LoggingAwaiter {
                T expr;
                bool await_ready() { return expr.await_ready(); }
                void await_suspend(std::coroutine_handle<> h) {
                    std::cout << "[log] awaiting...\n";
                    expr.await_suspend(h);
                }
                auto await_resume() { return expr.await_resume(); }
            };
            return LoggingAwaiter{std::forward<T>(expr)};
        }
    };
    std::coroutine_handle<promise_type> handle;
};

5.7 Promise 的自定义 operator new

Promise 可定义静态 operator new 控制协程帧分配：

#include <coroutine>
#include <cstdlib>
#include <iostream>
#include <new>

struct PoolTask {
    struct promise_type {
        PoolTask get_return_object() {
            return {std::coroutine_handle<promise_type>::from_promise(*this)};
        }
        std::suspend_never initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        void return_void() noexcept {}
        void unhandled_exception() noexcept {}

        // 自定义 operator new：从内存池分配
        void* operator new(std::size_t sz) {
            std::cout << "allocating " << sz << " bytes from pool\n";
            return std::malloc(sz);
        }

        // 自定义 operator delete
        void operator delete(void* ptr, std::size_t) {
            std::cout << "freeing from pool\n";
            std::free(ptr);
        }
    };
    std::coroutine_handle<promise_type> handle;
};

PoolTask pool_demo() {
    co_return;
}

int main() {
    auto t = pool_demo();
    t.handle.destroy();
    return 0;
}
// 输出:
// allocating 64 bytes from pool
// freeing from pool

5.8 final_suspend 的设计准则

final_suspend 应返回 suspend_always 而非 suspend_never，原因如下：

• 若返回 suspend_never，协程帧在结束时立即销毁
• 此后调用 handle.done() 访问已释放内存（UB）
• 此后调用 handle.resume() 也访问已释放内存（UB）

#include <coroutine>
#include <iostream>

// 正确：final_suspend 返回 suspend_always
struct SafeTask {
    struct promise_type {
        SafeTask get_return_object() {
            return {std::coroutine_handle<promise_type>::from_promise(*this)};
        }
        std::suspend_never initial_suspend() noexcept { return {}; }
        // 关键：返回 suspend_always，保证协程帧存活直到 destroy
        std::suspend_always final_suspend() noexcept { return {}; }
        void return_void() noexcept {}
        void unhandled_exception() noexcept {}
    };
    std::coroutine_handle<promise_type> handle;

    ~SafeTask() {
        if (handle) handle.destroy();
    }
};

SafeTask safe_demo() {
    co_return;
}

int main() {
    {
        SafeTask t = safe_demo();
        std::cout << "done: " << t.handle.done() << '\n';  // 输出: done: 1
    }  // 析构销毁协程帧
    return 0;
}

5.9 unhandled_exception 与异常传播

协程内未捕获异常调用 promise.unhandled_exception()，可在 Promise 中存储 std::exception_ptr 后在 await_resume 重新抛出：

#include <coroutine>
#include <exception>
#include <iostream>
#include <stdexcept>

struct ExceptionTask {
    struct promise_type {
        std::exception_ptr exc;
        ExceptionTask get_return_object() {
            return {std::coroutine_handle<promise_type>::from_promise(*this)};
        }
        std::suspend_never initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        void return_void() noexcept {}
        void unhandled_exception() {
            exc = std::current_exception();  // 捕获异常
        }
    };
    std::coroutine_handle<promise_type> handle;

    void rethrow_if_failed() {
        if (handle.promise().exc) {
            std::rethrow_exception(handle.promise().exc);
        }
    }
};

ExceptionTask throwing_coro() {
    throw std::runtime_error("boom");
    co_return;
}

int main() {
    auto t = throwing_coro();
    try {
        t.rethrow_if_failed();
    } catch (const std::exception& e) {
        std::cout << "caught: " << e.what() << '\n';  // 输出: caught: boom
    }
    t.handle.destroy();
    return 0;
}

5.10 coroutine_handle 的所有权管理

coroutine_handle 是非拥有的，类似裸指针。生产代码应使用 RAII 包装：

#include <coroutine>
#include <utility>

// RAII 协程句柄包装
template<typename Promise>
class UniqueCoro {
public:
    UniqueCoro() = default;
    explicit UniqueCoro(std::coroutine_handle<Promise> h) : handle_(h) {}
    ~UniqueCoro() { if (handle_) handle_.destroy(); }

    UniqueCoro(const UniqueCoro&) = delete;
    UniqueCoro& operator=(const UniqueCoro&) = delete;

    UniqueCoro(UniqueCoro&& other) noexcept : handle_(other.handle_) {
        other.handle_ = nullptr;
    }
    UniqueCoro& operator=(UniqueCoro&& other) noexcept {
        if (this != &other) {
            if (handle_) handle_.destroy();
            handle_ = other.handle_;
            other.handle_ = nullptr;
        }
        return *this;
    }

    std::coroutine_handle<Promise> get() const noexcept { return handle_; }
    std::coroutine_handle<Promise> release() noexcept {
        auto h = handle_;
        handle_ = nullptr;
        return h;
    }
    Promise& promise() const { return handle_.promise(); }
    void resume() { handle_.resume(); }
    bool done() const { return handle_.done(); }

private:
    std::coroutine_handle<Promise> handle_ = nullptr;
};

5.11 noop_coroutine 与 lazy await

std::noop_coroutine() 返回永远 done 的协程，可用于「无操作」场景：

#include <coroutine>
#include <iostream>

// 用 noop_coroutine 实现「不恢复任何协程」的 awaiter
struct FireAndForgetAwaiter {
    bool await_ready() const noexcept { return false; }
    void await_suspend(std::coroutine_handle<>) const noexcept {
        // 不恢复调用者，让调用者自然结束
        std::cout << "fire-and-forget: not resuming caller\n";
    }
    void await_resume() const noexcept {}
};

// 演示 noop_coroutine
void demo_noop() {
    auto noop = std::noop_coroutine();
    std::cout << "noop done: " << noop.done() << '\n';  // 输出: noop done: 1
    // noop.resume();  // 安全但无副作用
    // noop.destroy();  // 安全但无副作用
}

第 6 章 co_await、co_yield、co_return 详解

6.1 co_await：异步等待原语

co_await 是协程最核心的关键字，表达「挂起并等待」的语义。其完整形式：

// 完整形式
auto result = co_await expr;

// 等价展开（伪代码）
auto&& awaiter = get_awaiter(expr);
if (!awaiter.await_ready()) {
    // 挂起协程，调用 await_suspend
    auto h = coroutine_handle<Promise>::from_promise(__promise);
    awaiter.await_suspend(h);
    // 此处协程返回控制权给调用者
    // ... 恢复时从此处继续
}
auto result = awaiter.await_resume();

6.2 co_await 的常见用法

#include <coroutine>
#include <iostream>
#include <thread>
#include <chrono>

// 1. 等待标准 suspend_always/suspend_never
struct Task {
    struct promise_type {
        Task get_return_object() { return {std::coroutine_handle<promise_type>::from_promise(*this)}; }
        std::suspend_never initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        void return_void() noexcept {}
        void unhandled_exception() noexcept {}
    };
    std::coroutine_handle<promise_type> handle;
};

// 2. 自定义延时 awaiter
struct Timer {
    int ms;
    bool await_ready() const noexcept { return ms <= 0; }
    void await_suspend(std::coroutine_handle<> h) const {
        std::thread([h, ms = ms]() {
            std::this_thread::sleep_for(std::chrono::milliseconds(ms));
            h.resume();
        }).detach();
    }
    void await_resume() const noexcept {}
};

// 3. 在协程中组合
Task combo() {
    co_await std::suspend_always{};  // 主动让出
    std::cout << "resumed once\n";
    co_await Timer{100};             // 等待 100ms
    std::cout << "resumed after 100ms\n";
    co_return;
}

int main() {
    auto t = combo();
    // 手动恢复一次
    t.handle.resume();
    // 等待 Timer 完成
    std::this_thread::sleep_for(std::chrono::milliseconds(200));
    t.handle.destroy();
    return 0;
}
// 输出:
// resumed once
// resumed after 100ms

6.3 co_yield：惰性产值

co_yield 专门用于 Generator 模式，等价于 co_await promise.yield_value(value)：

#include <coroutine>
#include <iostream>

// 完整 Generator 实现
template<typename T>
struct Generator {
    struct promise_type {
        T current_value;

        Generator get_return_object() {
            return {std::coroutine_handle<promise_type>::from_promise(*this)};
        }
        std::suspend_always initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        std::suspend_always yield_value(T v) {
            current_value = std::move(v);
            return {};
        }
        void return_void() noexcept {}
        void unhandled_exception() noexcept { std::terminate(); }
    };

    std::coroutine_handle<promise_type> handle;

    // 迭代器支持 range-based for
    struct iterator {
        std::coroutine_handle<promise_type> handle;

        iterator& operator++() {
            handle.resume();
            return *this;
        }
        bool operator!=(std::default_sentinel_t) const { return !handle.done(); }
        const T& operator*() const { return handle.promise().current_value; }
    };

    iterator begin() {
        handle.resume();
        return {handle};
    }
    std::default_sentinel_t end() { return {}; }

    ~Generator() { if (handle) handle.destroy(); }
};

// 斐波那契生成器
Generator<int> fibonacci() {
    int a = 0, b = 1;
    while (true) {
        co_yield a;
        auto tmp = a + b;
        a = b;
        b = tmp;
    }
}

int main() {
    int count = 0;
    for (auto x : fibonacci()) {
        std::cout << x << ' ';
        if (++count >= 10) break;
    }
    std::cout << '\n';
    // 输出: 0 1 1 2 3 5 8 13 21 34
    return 0;
}

6.4 co_return：结束协程

co_return 终止协程并派发到 promise：

#include <coroutine>
#include <iostream>
#include <optional>
#include <string>

template<typename T>
struct ResultTask {
    struct promise_type {
        std::optional<T> value;

        ResultTask get_return_object() {
            return {std::coroutine_handle<promise_type>::from_promise(*this)};
        }
        std::suspend_never initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        void return_value(T v) { value = std::move(v); }
        void unhandled_exception() noexcept { std::terminate(); }
    };
    std::coroutine_handle<promise_type> handle;

    T get() { return std::move(*handle.promise().value); }
    ~ResultTask() { if (handle) handle.destroy(); }
};

ResultTask<int> compute_value() {
    co_return 42;  // 派发到 return_value(42)
}

ResultTask<std::string> compute_string() {
    std::string s = "hello";
    s += " world";
    co_return s;
}

int main() {
    auto t1 = compute_value();
    std::cout << t1.get() << '\n';  // 输出: 42

    auto t2 = compute_string();
    std::cout << t2.get() << '\n';  // 输出: hello world
    return 0;
}

6.5 return_void vs return_value 的选择

Promise 只能定义其一：

#include <coroutine>
#include <iostream>

// 使用 return_void：协程无返回值
struct VoidTask {
    struct promise_type {
        VoidTask get_return_object() { return {std::coroutine_handle<promise_type>::from_promise(*this)}; }
        std::suspend_never initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        void return_void() noexcept {}  // co_return; 或函数末尾
        void unhandled_exception() noexcept {}
    };
    std::coroutine_handle<promise_type> handle;
    ~VoidTask() { if (handle) handle.destroy(); }
};

// 使用 return_value：协程返回值
template<typename T>
struct ValueTask {
    struct promise_type {
        T value;
        ValueTask get_return_object() { return {std::coroutine_handle<promise_type>::from_promise(*this)}; }
        std::suspend_never initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        void return_value(T v) { value = std::move(v); }
        void unhandled_exception() noexcept {}
    };
    std::coroutine_handle<promise_type> handle;
    ~ValueTask() { if (handle) handle.destroy(); }
};

VoidTask void_demo() {
    co_return;  // 派发到 return_void
}

ValueTask<int> value_demo() {
    co_return 42;  // 派发到 return_value(42)
}

6.6 co_await 在表达式中的位置

C++20 协程限制：co_await 不能在 try-catch 的 catch 子句中使用（C++20 限制，C++23 部分放宽）：

#include <coroutine>
#include <iostream>

struct Task {
    struct promise_type {
        Task get_return_object() { return {std::coroutine_handle<promise_type>::from_promise(*this)}; }
        std::suspend_never initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        void return_void() noexcept {}
        void unhandled_exception() noexcept {}
    };
    std::coroutine_handle<promise_type> handle;
    ~Task() { if (handle) handle.destroy(); }
};

Task valid_usage() {
    // 合法：co_await 在 try 块内
    try {
        co_await std::suspend_always{};
    } catch (...) {
        // 非法：co_await 不能在 catch 块（C++20 限制）
        // co_await std::suspend_always{};
    }
    co_return;
}

第 7 章 对比分析

7.1 跨语言协程模型对比

7.2 运行时模型对比

graph LR
    subgraph "C++20 (Stackless)"
        A1["协程帧<br/>堆分配"] --> A2["Promise<br/>策略对象"]
        A2 --> A3["Awaiter<br/>三步协议"]
        A3 --> A4["Executor<br/>用户自定义"]
    end
    subgraph "Go (Stackful)"
        B1["Goroutine<br/>2KB 初始栈"] --> B2["runtime<br/>抢占调度"]
        B2 --> B3["Channel<br/>通信原语"]
        B3 --> B4["GC<br/>自动内存"]
    end
    subgraph "Python (Stackless)"
        C1["协程对象<br/>堆分配"] --> C2["asyncio<br/>事件循环"]
        C2 --> C3["Future<br/>异步原语"]
        C3 --> C4["GIL<br/>单线程"]
    end
    style A1 fill:#aaf
    style B1 fill:#afa
    style C1 fill:#ffa

7.3 C++20 vs Python async/await

# Python 版本
import asyncio

async def fetch_data():
    await asyncio.sleep(0.1)
    return "data"

async def main():
    result = await fetch_data()
    print(result)

asyncio.run(main())

// C++20 版本
#include <coroutine>
#include <chrono>
#include <thread>
#include <iostream>

struct Task {
    struct promise_type {
        std::string result;
        Task get_return_object() { return {std::coroutine_handle<promise_type>::from_promise(*this)}; }
        std::suspend_never initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        void return_value(std::string r) { result = std::move(r); }
        void unhandled_exception() noexcept {}
    };
    std::coroutine_handle<promise_type> handle;
    ~Task() { if (handle) handle.destroy(); }
};

struct sleep {
    int ms;
    bool await_ready() const noexcept { return false; }
    void await_suspend(std::coroutine_handle<> h) const {
        std::thread([h, ms = ms]() {
            std::this_thread::sleep_for(std::chrono::milliseconds(ms));
            h.resume();
        }).detach();
    }
    void await_resume() const noexcept {}
};

Task fetch_data() {
    co_await sleep{100};
    co_return "data";
}

int main() {
    auto t = fetch_data();
    std::this_thread::sleep_for(std::chrono::milliseconds(200));
    std::cout << t.handle.promise().result << '\n';  // 输出: data
    return 0;
}

差异分析：

• 运行时：Python 必须使用 asyncio 事件循环；C++ 无内置事件循环，需用户实现或使用第三方库（如 Boost.Asio）
• GIL：Python 受 GIL 限制单线程并发；C++ 无限制，可多核并发
• 类型推导：Python 动态类型；C++ 静态类型，编译期检查
• 取消：Python 通过 asyncio.CancelledError；C++ 需通过 stop_token 自定义

7.4 C++20 vs JavaScript async/await

// JavaScript 版本
async function fetch_data() {
  await new Promise((resolve) => setTimeout(resolve, 100));
  return 'data';
}

async function main() {
  const result = await fetch_data();
  console.log(result);
}

main();

差异分析：

• Promise 模型：JavaScript 内置 Promise；C++ 无内置，需自定义 Task 类型
• 事件循环：JavaScript 内置事件循环（libuv in Node.js）；C++ 无
• 微任务队列：JavaScript 区分宏任务/微任务；C++ 协程恢复由 awaiter 显式调度
• 单线程：JavaScript 默认单线程；C++ 多线程

7.5 C++20 vs Rust async/await

// Rust 版本
use tokio;
use std::time::Duration;

async fn fetch_data() -> String {
    tokio::time::sleep(Duration::from_millis(100)).await;
    "data".to_string()
}

#[tokio::main]
async fn main() {
    let result = fetch_data().await;
    println!("{}", result);
}

差异分析：

• Future 模型：Rust Future 是惰性的（poll-based）；C++ Task 可立即启动或惰性
• 零成本：Rust async 编译为状态机，零堆分配；C++ 协程默认堆分配（HALO 可省略）
• Pin：Rust 需要 Pin 保证自引用安全；C++ 编译器自动处理
• Executor：Rust 标准库无 Executor，需 tokio/async-std；C++ 同样无内置 Executor

7.6 C++20 vs Go goroutine

// Go 版本
func fetchData() string {
    time.Sleep(100 * time.Millisecond)
    return "data"
}

func main() {
    ch := make(chan string)
    go func() {
        ch <- fetchData()
    }()
    result := <-ch
    fmt.Println(result)
}

差异分析：

• 栈管理：Go goroutine 有 2KB 初始栈，可动态增长至 1GB；C++ 协程无栈，状态机
• 调度：Go runtime 抢占式调度（Go 1.14+）；C++ 协作式
• 通信：Go 推崇 channel；C++ 推崇 co_await
• 开销：Go goroutine 创建约 2KB；C++ 协程帧通常 64-256 字节

7.7 C++20 vs C# async/await

// C# 版本
async Task<string> FetchData() {
    await Task.Delay(100);
    return "data";
}

async Task Main() {
    var result = await FetchData();
    Console.WriteLine(result);
}

差异分析：

• SynchronizationContext：C# 有 SynchronizationContext 自动回到 UI 线程；C++ 无内置机制
• Task 类型：C# 标准库提供 Task；C++ 需自定义或用第三方
• 状态机：C# 编译器生成状态机；C++ 类似
• APM/EAP：C# 历史遗留模式；C++ 无历史包袱

7.8 C++20 vs Java Virtual Threads (Java 21)

// Java 21 版本
import java.util.concurrent.*;

Future<String> fetchData() {
    return Executors.newVirtualThreadPerTaskExecutor().submit(() -> {
        Thread.sleep(100);
        return "data";
    });
}

var result = fetchData().get();
System.out.println(result);

差异分析：

• 栈管理：Java Virtual Threads 是 stackful，JVM 管理；C++ 无栈
• 集成：Java Virtual Threads 与现有 j.u.c 完全兼容；C++ 需重新设计 API
• 调度：JVM 内置 ForkJoinPool 调度；C++ 需自定义
• 语言侵入性：Java 无新关键字；C++ 引入三个关键字

7.9 综合对比表

graph TB
    subgraph "维度1: 栈类型"
        SL["Stackless<br/>C++ Python JS Rust C#"]
        SF["Stackful<br/>Go Java"]
    end
    subgraph "维度2: 调度"
        CO["协作式<br/>C++ Python JS Rust C#"]
        PR["抢占式<br/>Go Java"]
    end
    subgraph "维度3: 运行时"
        RT0["无运行时<br/>C++ Rust"]
        RT1["有运行时<br/>Python JS Go C# Java"]
    end
    style SL fill:#aaf
    style SF fill:#afa
    style CO fill:#faa
    style PR fill:#ffa

第 8 章 常见陷阱

8.1 协程悬挂（dangling coroutine）

协程返回对象超出作用域但协程帧未销毁：

#include <coroutine>
#include <iostream>

struct Task {
    struct promise_type {
        Task get_return_object() { return {std::coroutine_handle<promise_type>::from_promise(*this)}; }
        std::suspend_never initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        void return_void() noexcept {}
        void unhandled_exception() noexcept {}
    };
    std::coroutine_handle<promise_type> handle;
    // 陷阱：未在析构中 destroy 协程帧
    ~Task() { /* 应该: if (handle) handle.destroy(); */ }
};

Task bad_coro() {
    co_return;
}

void danger() {
    auto t = bad_coro();
    // t 析构时未 destroy，协程帧泄漏
}

修正方案：RAII 包装，析构中 destroy：

struct SafeTask {
    struct promise_type {
        SafeTask get_return_object() { return {std::coroutine_handle<promise_type>::from_promise(*this)}; }
        std::suspend_never initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        void return_void() noexcept {}
        void unhandled_exception() noexcept {}
    };
    std::coroutine_handle<promise_type> handle;
    ~SafeTask() { if (handle) handle.destroy(); }  // 关键
};

8.2 use-after-free

协程挂起时引用了已销毁对象：

#include <coroutine>
#include <iostream>

struct Task {
    struct promise_type {
        Task get_return_object() { return {std::coroutine_handle<promise_type>::from_promise(*this)}; }
        std::suspend_never initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        void return_void() noexcept {}
        void unhandled_exception() noexcept {}
    };
    std::coroutine_handle<promise_type> handle;
    ~Task() { if (handle) handle.destroy(); }
};

struct Timer {
    int ms;
    bool await_ready() const noexcept { return false; }
    void await_suspend(std::coroutine_handle<> h) const {
        std::thread([h, ms = ms]() {
            std::this_thread::sleep_for(std::chrono::milliseconds(ms));
            h.resume();
        }).detach();
    }
    void await_resume() const noexcept {}
};

// 陷阱：引用了局部变量
Task bad_use_after_free() {
    std::string local = "hello";
    co_await Timer{100};
    // 100ms 后恢复，但若调用者已离开，则协程帧已销毁，访问悬挂
    std::cout << local << '\n';  // UB 如果帧已销毁
}

int main() {
    {
        Task t = bad_use_after_free();
        // t 在此析构，协程帧销毁
        // 但 Timer 线程仍在等待 100ms
    }
    std::this_thread::sleep_for(std::chrono::milliseconds(200));
    // Timer 线程尝试 h.resume()，访问已销毁帧，崩溃
    return 0;
}

修正方案：保证协程生命周期覆盖所有 awaiter 的恢复操作：

// 正确：让 Task 析构等待所有挂起的 awaiter 完成
struct SafeTask {
    // ... 同上
    ~SafeTask() {
        if (handle) {
            // 等待协程到达 final_suspend 或显式取消
            // 实际实现需配合 stop_token 与事件机制
            handle.destroy();
        }
    }
};

8.3 悬挂引用

返回引用的协程在帧销毁后访问悬挂：

#include <coroutine>
#include <iostream>
#include <string>

// 陷阱：返回 std::string&，但 local 在协程帧中
struct BadRefTask {
    struct promise_type {
        std::string result;
        BadRefTask get_return_object() { return {std::coroutine_handle<promise_type>::from_promise(*this)}; }
        std::suspend_never initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        void return_value(std::string v) { result = std::move(v); }
        void unhandled_exception() noexcept {}
    };
    std::coroutine_handle<promise_type> handle;
    ~BadRefTask() { if (handle) handle.destroy(); }

    // 陷阱：返回引用，但协程帧析构后引用悬挂
    const std::string& get() const { return handle.promise().result; }
};

int main() {
    std::string_view view;
    {
        BadRefTask t = []() -> BadRefTask { co_return "hello"; }();
        view = t.get();  // view 指向协程帧中的 result
    }  // t 析构，协程帧销毁
    std::cout << view << '\n';  // UB：访问悬挂
    return 0;
}

修正方案：返回值类型或显式延长生命周期。

8.4 堆分配开销

频繁创建短生命周期协程导致堆分配开销：

#include <coroutine>
#include <iostream>

struct Task {
    struct promise_type {
        Task get_return_object() { return {std::coroutine_handle<promise_type>::from_promise(*this)}; }
        std::suspend_never initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        void return_void() noexcept {}
        void unhandled_exception() noexcept {}
    };
    std::coroutine_handle<promise_type> handle;
    ~Task() { if (handle) handle.destroy(); }
};

// 陷阱：每个协程都堆分配
Task loop_bad() {
    for (int i = 0; i < 1000000; ++i) {
        // 每次调用内部协程都堆分配
        // co_await inner_task();
    }
    co_return;
}

// 修正：使用自定义 operator new 从内存池分配
struct PoolTask {
    struct promise_type {
        PoolTask get_return_object() { return {std::coroutine_handle<promise_type>::from_promise(*this)}; }
        std::suspend_never initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        void return_void() noexcept {}
        void unhandled_exception() noexcept {}

        // 自定义 operator new 从池分配
        void* operator new(std::size_t sz) {
            // 实际实现：从 thread-local 内存池分配
            return ::operator new(sz);
        }
        void operator delete(void* p, std::size_t) {
            ::operator delete(p);
        }
    };
    std::coroutine_handle<promise_type> handle;
    ~PoolTask() { if (handle) handle.destroy(); }
};

8.5 Awaiter 生命周期错误

Awaiter 在 await_suspend 完成前被销毁：

#include <coroutine>
#include <iostream>
#include <thread>

// 陷阱：临时 Awaiter 对象在 await_suspend 返回后销毁，
// 但其内部状态（如 promise）被后台线程访问
struct BadTimer {
    int ms;
    bool await_ready() const noexcept { return false; }
    void await_suspend(std::coroutine_handle<> h) const {
        // 陷阱：捕获了 this，但临时对象销毁后 this 悬挂
        std::thread([this, h]() {
            std::this_thread::sleep_for(std::chrono::milliseconds(this->ms));
            h.resume();
        }).detach();
    }
    void await_resume() const noexcept {}
};

// 修正：按值捕获所有需要的状态
struct GoodTimer {
    int ms;
    bool await_ready() const noexcept { return false; }
    void await_suspend(std::coroutine_handle<> h) const {
        // 按 ms 值捕获，不依赖 this
        std::thread([h, ms = ms]() {
            std::this_thread::sleep_for(std::chrono::milliseconds(ms));
            h.resume();
        }).detach();
    }
    void await_resume() const noexcept {}
};

8.6 Executor 选择错误

将 CPU 密集型任务调度到 I/O 线程：

#include <coroutine>
#include <iostream>
#include <thread>
#include <chrono>

struct ThreadPool {
    void submit(std::function<void()> f) {
        std::thread(std::move(f)).detach();
    }
};

struct IOExecutor {
    void submit(std::function<void()> f) {
        std::thread(std::move(f)).detach();
    }
};

struct SwitchTo {
    ThreadPool& pool;
    bool await_ready() const noexcept { return false; }
    void await_suspend(std::coroutine_handle<> h) const {
        pool.submit([h]() { h.resume(); });
    }
    void await_resume() const noexcept {}
};

// 陷阱：在 IO 线程执行 CPU 密集计算
void bad_mix() {
    // 错误：阻塞 IO 线程做计算
    for (volatile int i = 0; i < 100000000; ++i) {}
}

// 修正：明确切换到 CPU 线程池
struct Task {
    struct promise_type {
        Task get_return_object() { return {std::coroutine_handle<promise_type>::from_promise(*this)}; }
        std::suspend_never initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        void return_void() noexcept {}
        void unhandled_exception() noexcept {}
    };
    std::coroutine_handle<promise_type> handle;
    ~Task() { if (handle) handle.destroy(); }
};

ThreadPool cpu_pool;
IOExecutor io_executor;

Task good_mix() {
    co_await SwitchTo{cpu_pool};  // 切到 CPU 池
    // CPU 密集计算
    for (volatile int i = 0; i < 100000000; ++i) {}
    // 可选：co_await SwitchTo{io_executor}; 切回 IO 池
    co_return;
}

8.7 co_await 与 co_return 混淆

错误地用 co_return 等待异步操作：

#include <coroutine>
#include <iostream>

struct Task {
    struct promise_type {
        Task get_return_object() { return {std::coroutine_handle<promise_type>::from_promise(*this)}; }
        std::suspend_never initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        void return_void() noexcept {}
        void unhandled_exception() noexcept {}
    };
    std::coroutine_handle<promise_type> handle;
    ~Task() { if (handle) handle.destroy(); }
};

struct AsyncOp {
    bool await_ready() const noexcept { return false; }
    void await_suspend(std::coroutine_handle<> h) const {
        h.resume();  // 立即恢复（演示）
    }
    int await_resume() const { return 42; }
};

// 陷阱：误以为 co_return 等待 AsyncOp
Task bad() {
    // co_return AsyncOp{};  // 错误：return_value(AsyncOp)，不触发 await
    co_return;
}

// 修正：使用 co_await 等待
Task good() {
    int result = co_await AsyncOp{};
    std::cout << "result: " << result << '\n';  // 输出: result: 42
    co_return;
}

int main() {
    auto t = good();
    return 0;
}

8.8 final_suspend 返回 suspend_never 的风险

#include <coroutine>
#include <iostream>

struct DangerousTask {
    struct promise_type {
        DangerousTask get_return_object() { return {std::coroutine_handle<promise_type>::from_promise(*this)}; }
        std::suspend_never initial_suspend() noexcept { return {}; }
        // 陷阱：返回 suspend_never，协程帧立即销毁
        std::suspend_never final_suspend() noexcept { return {}; }
        void return_void() noexcept {}
        void unhandled_exception() noexcept {}
    };
    std::coroutine_handle<promise_type> handle;
};

DangerousTask run() {
    co_return;
}

int main() {
    auto t = run();
    // 陷阱：协程已结束且帧已销毁，下列操作均为 UB
    // t.handle.done();  // UB
    // t.handle.resume();  // UB
    // t.handle.destroy();  // UB（双重释放）
    return 0;
}