协程基础

C++20 引入了协程(coroutines)——一种可以暂停执行并在稍后恢复的函数。与普通函数"调用-返回"的一次性流程不同,协程可以在执行中途挂起,保存整个局部状态,之后从暂停点继续。这为惰性计算、异步 I/O 和事件驱动编程提供了优雅的语言级支持。

协程 vs 线程

线程是抢占式的(OS 可以随时切换),协程是协作式的(只在你指定的挂起点切换)。协程切换没有系统调用开销,一个线程上可以运行成千上万个协程。

co_await / co_yield / co_return — 三个魔法关键字

一个函数只要使用了以下任一关键字,编译器就会将其视为协程:

// co_await: 挂起当前协程,等待异步操作完成
Task<Data> fetch_data() {
    auto result = co_await async_read(socket);  // 在此挂起
    co_return result;                            // 协程返回值
}

// co_yield: 产出一个值并挂起(用于生成器模式)
Generator<int> iota(int start) {
    while (true) {
        co_yield start++;  // 产出值后挂起,等待消费者请求下一个
    }
}

// co_return: 设置协程最终返回值并结束
Task<int> compute() {
    int result = do_work();
    co_return result;  // 设置结果,协程进入 final_suspend
}

协程的约束

协程不能使用可变参数(variadic ...)、不能是 constexpr、不能有 plain return 语句(必须用 co_return)、构造函数和析构函数不能是协程。main() 函数也不能是协程。

promise_type — 协程的定制点

编译器通过协程返回类型中嵌套的 promise_type 来控制协程行为。这是整个协程机制的核心定制点。

#include <coroutine>

template<typename T>
struct Generator {
    // 这是编译器寻找的 promise_type
    struct promise_type {
        T current_value;

        // 协程创建时,通过此方法获取返回对象
        Generator get_return_object() {
            return Generator{
                std::coroutine_handle<promise_type>::from_promise(*this)
            };
        }

        // 协程开始时挂起?
        // suspend_always → 惰性启动(创建后不立即执行)
        // suspend_never  → 急切启动(创建后立即执行到第一个挂起点)
        std::suspend_always initial_suspend() noexcept { return {}; }

        // 协程结束时挂起?
        // suspend_always → 保持帧存活,由外部销毁
        // suspend_never  → 自动销毁帧
        std::suspend_always final_suspend() noexcept { return {}; }

        // co_yield value 等价于 co_await promise.yield_value(value)
        std::suspend_always yield_value(T value) {
            current_value = std::move(value);
            return {};
        }

        // 协程以 co_return; 结束(无返回值)
        void return_void() {}

        // 协程内未捕获的异常
        void unhandled_exception() {
            std::terminate();  // 或存储异常稍后重抛
        }
    };

    // --- Generator 本体 ---
    using handle_type = std::coroutine_handle<promise_type>;
    handle_type handle_;

    explicit Generator(handle_type h) : handle_(h) {}
    ~Generator() { if (handle_) handle_.destroy(); }

    // 禁止复制
    Generator(const Generator&) = delete;
    Generator& operator=(const Generator&) = delete;

    // 允许移动
    Generator(Generator&& other) noexcept
        : handle_(std::exchange(other.handle_, nullptr)) {}
};

coroutine_handle — 协程的控制柄

std::coroutine_handle<Promise> 是一个轻量级指针,指向协程帧(coroutine frame)。通过它你可以恢复、销毁协程或访问 promise 对象。

// coroutine_handle 的关键操作
auto handle = std::coroutine_handle<promise_type>::from_promise(promise);

handle.resume();   // 恢复协程执行(等价于 handle())
handle.destroy();  // 销毁协程帧,释放内存
handle.done();     // 协程是否已结束(到达 final_suspend)
handle.promise();  // 访问关联的 promise 对象

// 类型擦除版本(不能访问 promise)
std::coroutine_handle<> erased = handle;  // 隐式转换

逐步实现完整的 Generator<T>

让我们把前面的代码组合起来,实现一个可用的生成器:

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

template<typename T>
class Generator {
public:
    struct promise_type {
        std::optional<T> current_value;
        std::exception_ptr exception;

        Generator get_return_object() {
            return Generator{handle_type::from_promise(*this)};
        }
        std::suspend_always initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }

        std::suspend_always yield_value(T value) {
            current_value = std::move(value);
            return {};
        }
        void return_void() {}
        void unhandled_exception() {
            exception = std::current_exception();
        }
    };

    using handle_type = std::coroutine_handle<promise_type>;

    // 迭代器接口 — 让 Generator 可用于 range-for
    struct iterator {
        handle_type handle;

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

    iterator begin() {
        handle_.resume();  // 推进到第一个 co_yield
        return {handle_};
    }
    std::default_sentinel_t end() { return {}; }

    // RAII 管理
    explicit Generator(handle_type h) : handle_(h) {}
    ~Generator() { if (handle_) handle_.destroy(); }

    Generator(Generator&& o) noexcept
        : handle_(std::exchange(o.handle_, nullptr)) {}
    Generator(const Generator&) = delete;

private:
    handle_type handle_;
};

// 使用示例:斐波那契生成器
Generator<long long> fibonacci() {
    long long a = 0, b = 1;
    while (true) {
        co_yield a;
        auto next = a + b;
        a = b;
        b = next;
    }
}

int main() {
    int count = 0;
    for (auto val : fibonacci()) {
        std::cout << val << " ";
        if (++count >= 15) break;
    }
    // 输出: 0 1 1 2 3 5 8 13 21 34 55 89 144 233 377
}

协程的生命周期与执行流程

理解协程的完整生命周期是掌握它的关键。以下是从创建到销毁的每一步:

/*
 调用协程函数时发生的事情(编译器为你生成):

 1. 分配协程帧(堆上,存放局部变量 + promise)
 2. 构造 promise 对象: promise_type promise;
 3. 获取返回对象: auto ret = promise.get_return_object();
 4. 执行 co_await promise.initial_suspend();
    - suspend_always → 协程立即挂起,返回 ret 给调用者
    - suspend_never  → 继续执行函数体
 5. 执行函数体...
    - co_yield val  → co_await promise.yield_value(val)
    - co_await expr → 检查 awaitable 的三个方法
    - co_return val → promise.return_value(val)
    - co_return;    → promise.return_void()
 6. 若异常逃逸 → promise.unhandled_exception()
 7. co_await promise.final_suspend();
    - suspend_always → 帧保持存活,等待外部 destroy()
    - suspend_never  → 帧自动销毁
*/

为什么 final_suspend 通常返回 suspend_always?

如果 final_suspend 返回 suspend_never,协程帧在完成后立即被销毁。此时外部持有的 coroutine_handle 变成悬空指针——任何对 handle.done() 或 handle.promise() 的访问都是未定义行为。让协程在最终暂停点挂起,由外部的 RAII 包装器(如 Generator 的析构函数)负责销毁,更加安全。

Awaitable 协议:自定义挂起行为

当你写 co_await expr 时,编译器会查找三个方法:

struct MyAwaitable {
    // 是否需要挂起?返回 true 则跳过挂起,直接继续
    bool await_ready() const noexcept { return false; }

    // 挂起时执行什么?
    // 参数是当前协程的 handle,可以用来调度恢复
    // 返回值控制行为:
    //   void   → 挂起,控制权返回 caller/resumer
    //   bool   → false 则不挂起(立即恢复)
    //   handle → 对称转移(转移到另一个协程)
    void await_suspend(std::coroutine_handle<> h) {
        // 典型用法:将 h 注册到某个调度器
        // 当异步操作完成时,调度器调用 h.resume()
        scheduler.schedule(h);
    }

    // 恢复后的返回值(即 co_await 表达式的值)
    int await_resume() {
        return result;
    }
};

// 使用
Task<void> example() {
    int val = co_await MyAwaitable{};
    // val 是 await_resume() 的返回值
}

标准库提供的两个简单 awaitable

// std::suspend_always: await_ready() → false, 总是挂起
// std::suspend_never:  await_ready() → true, 从不挂起

// 它们是 initial_suspend/final_suspend/yield_value 中最常用的返回类型

本节小结

  • 协程是可暂停/可恢复的函数,使用 co_await、co_yield、co_return 三个关键字
  • promise_type 是协程的定制核心——通过它控制启动行为、挂起策略、值传递和异常处理
  • coroutine_handle 是协程帧的低级控制柄,用于恢复 (resume) 和销毁 (destroy) 协程
  • 自定义 Generator<T> 需要实现 promise_type + 迭代器接口,约 60 行代码
  • 协程生命周期:分配帧 -> initial_suspend -> 执行体 -> final_suspend -> 销毁
  • Awaitable 协议(await_ready / await_suspend / await_resume)让你完全控制挂起点的行为