协程承诺类型 promise_type ​

什么是 promise_type ​

promise_type 是 C++20 协程系统的核心定制点。每个协程都有一个与之关联的承诺对象(Promise Object),它的类型就是 promise_type。承诺对象控制了协程的几乎所有行为:怎么启动、怎么结束、怎么返回值、怎么处理异常、co_yield 时做什么。

编译器通过返回类型来找到 promise_type:如果协程的返回类型是 MyTask,编译器会去找 MyTask::promise_type。你也可以通过特化 std::coroutine_traits 来指定 promise_type,但嵌套类型的方式更常用。

promise_type 的必须方法和可选方法 ​

方法是否必须作用
get_return_object()必须创建返回给调用者的对象
initial_suspend()必须控制协程是否在开始时挂起
final_suspend()必须(且 noexcept)控制协程结束后是否挂起
return_void()二选一处理 co_return;
return_value(T)二选一处理 co_return expr;
unhandled_exception()必须处理协程体中未捕获的异常
yield_value(T)可选处理 co_yield expr
await_transform(T)可选转换 co_await 的操作数
operator new / delete可选自定义协程帧的内存分配
get_return_object_on_allocation_failure()可选(static)内存分配失败时的处理

编译器生成的协程框架伪代码 ​

cpp
// 编译器大致把协程函数转换成这样的逻辑:

ReturnType coroutine_function(参数...) {
    // 1. 确定 promise_type
    using promise_type = std::coroutine_traits<ReturnType, 参数类型...>::promise_type;

    // 2. 分配协程帧(堆上)
    void* frame = operator new(所需大小);

    // 3. 在帧中构造承诺对象
    promise_type promise(参数...);  // 如果有匹配的构造函数
    // 否则:promise_type promise;

    // 4. 创建返回对象
    auto return_object = promise.get_return_object();

    // 5. 执行
    try {
        co_await promise.initial_suspend();

        // === 协程函数体 ===
        // 用户写的代码在这里执行
        // co_return / co_yield / co_await 等

    } catch (...) {
        promise.unhandled_exception();
    }

    co_await promise.final_suspend();

    // 6. 如果没有在 final_suspend 挂起,销毁帧
}

基本示例 ​

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

// ============================
// 示例1:最基础的 promise_type
// ============================

struct BasicTask {
    struct promise_type {
        // 必须:创建返回对象
        // 在协程开始执行前调用,返回值就是调用者拿到的对象
        BasicTask get_return_object() {
            std::cout << "  [promise] get_return_object()" << std::endl;
            return BasicTask{
                std::coroutine_handle<promise_type>::from_promise(*this)
            };
        }

        // 必须:协程开始时的行为
        // suspend_always = 惰性启动(创建后不立即执行)
        // suspend_never  = 立即启动(创建后立刻开始执行)
        std::suspend_always initial_suspend() noexcept {
            std::cout << "  [promise] initial_suspend()" << std::endl;
            return {};
        }

        // 必须:协程结束后的行为(必须 noexcept)
        // suspend_always = 结束后挂起(调用者负责销毁)
        // suspend_never  = 结束后自动销毁帧
        std::suspend_always final_suspend() noexcept {
            std::cout << "  [promise] final_suspend()" << std::endl;
            return {};
        }

        // 必须(与 return_value 二选一):处理 co_return;
        void return_void() {
            std::cout << "  [promise] return_void()" << std::endl;
        }

        // 必须:处理未捕获异常
        void unhandled_exception() {
            std::cout << "  [promise] unhandled_exception()" << std::endl;
            std::terminate();
        }
    };

    std::coroutine_handle<promise_type> handle_;
    explicit BasicTask(std::coroutine_handle<promise_type> h) : handle_(h) {}
    ~BasicTask() { if (handle_) handle_.destroy(); }
    BasicTask(const BasicTask&) = delete;
    BasicTask& operator=(const BasicTask&) = delete;
    BasicTask(BasicTask&& o) noexcept : handle_(o.handle_) { o.handle_ = nullptr; }

    void resume() { if (handle_ && !handle_.done()) handle_.resume(); }
    bool done() const { return !handle_ || handle_.done(); }
};

BasicTask basic_coroutine() {
    std::cout << "  [协程体] 执行中..." << std::endl;
    co_return;
}

void basic_demo() {
    std::cout << "--- 创建协程 ---" << std::endl;
    auto task = basic_coroutine();
    // 输出顺序:get_return_object → initial_suspend

    std::cout << "--- 恢复协程 ---" << std::endl;
    task.resume();
    // 输出顺序:协程体 → return_void → final_suspend
}

// ============================
// 示例2:带返回值的 promise_type
// ============================

template<typename T>
struct ValueTask {
    struct promise_type {
        std::optional<T> result;
        std::exception_ptr exception;

        ValueTask get_return_object() {
            return ValueTask{
                std::coroutine_handle<promise_type>::from_promise(*this)
            };
        }

        std::suspend_always initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }

        // 处理 co_return expr; —— 保存返回值
        void return_value(T value) {
            result = std::move(value);
        }

        // 保存异常供调用者后续重新抛出
        void unhandled_exception() {
            exception = std::current_exception();
        }
    };

    std::coroutine_handle<promise_type> handle_;
    explicit ValueTask(std::coroutine_handle<promise_type> h) : handle_(h) {}
    ~ValueTask() { if (handle_) handle_.destroy(); }
    ValueTask(const ValueTask&) = delete;
    ValueTask& operator=(const ValueTask&) = delete;
    ValueTask(ValueTask&& o) noexcept : handle_(o.handle_) { o.handle_ = nullptr; }

    void resume() { if (handle_ && !handle_.done()) handle_.resume(); }
    bool done() const { return !handle_ || handle_.done(); }

    T get() const {
        if (handle_.promise().exception) {
            std::rethrow_exception(handle_.promise().exception);
        }
        return handle_.promise().result.value();
    }
};

ValueTask<int> compute(int a, int b) {
    co_return a * b + 1;
}

void value_demo() {
    auto task = compute(3, 4);
    task.resume();
    std::cout << "计算结果: " << task.get() << std::endl;  // 13
}

// ============================
// 示例3:带 yield_value 的 promise_type(生成器)
// ============================

template<typename T>
struct Generator {
    struct promise_type {
        T 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 {}; }
        void return_void() {}
        void unhandled_exception() { std::terminate(); }

        // 可选:处理 co_yield expr
        // co_yield expr 被编译器转换为 co_await promise.yield_value(expr)
        std::suspend_always yield_value(T value) {
            current_value = std::move(value);  // 保存产出的值
            return {};  // 返回 suspend_always 让协程挂起
        }
    };

    std::coroutine_handle<promise_type> handle_;
    explicit Generator(std::coroutine_handle<promise_type> h) : handle_(h) {}
    ~Generator() { if (handle_) handle_.destroy(); }
    Generator(const Generator&) = delete;
    Generator& operator=(const Generator&) = delete;
    Generator(Generator&& o) noexcept : handle_(o.handle_) { o.handle_ = nullptr; }

    bool next() {
        if (handle_ && !handle_.done()) {
            handle_.resume();
            return !handle_.done();
        }
        return false;
    }

    const T& value() const { return handle_.promise().current_value; }
};

Generator<int> count_up(int limit) {
    for (int i = 1; i <= limit; ++i) {
        co_yield i;
    }
}

void generator_demo() {
    auto gen = count_up(5);
    while (gen.next()) {
        std::cout << gen.value() << " ";
    }
    std::cout << std::endl;
}

// ============================
// 示例4:await_transform 控制可等待类型
// ============================

struct ControlledTask {
    struct promise_type {
        ControlledTask get_return_object() {
            return ControlledTask{
                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() {}
        void unhandled_exception() { std::terminate(); }

        // await_transform 拦截所有 co_await 表达式
        // 这个版本只允许 co_await int 类型
        auto await_transform(int delay_ms) {
            struct DelayAwaiter {
                int ms;
                bool await_ready() const noexcept { return ms <= 0; }
                void await_suspend(std::coroutine_handle<>) const noexcept {
                    std::cout << "  模拟延迟 " << ms << "ms" << std::endl;
                }
                int await_resume() const noexcept { return ms; }
            };
            return DelayAwaiter{delay_ms};
        }

        // 也允许 co_await std::suspend_always(透传)
        std::suspend_always await_transform(std::suspend_always s) {
            return s;
        }
    };

    std::coroutine_handle<promise_type> handle_;
    explicit ControlledTask(std::coroutine_handle<promise_type> h) : handle_(h) {}
    ~ControlledTask() { if (handle_) handle_.destroy(); }
    ControlledTask(const ControlledTask&) = delete;
    ControlledTask& operator=(const ControlledTask&) = delete;
    ControlledTask(ControlledTask&& o) noexcept : handle_(o.handle_) { o.handle_ = nullptr; }

    void resume() { if (handle_ && !handle_.done()) handle_.resume(); }
};

ControlledTask controlled_coroutine() {
    int waited = co_await 100;  // await_transform(100) → DelayAwaiter
    std::cout << "  等待了 " << waited << "ms" << std::endl;

    co_await std::suspend_always{};  // await_transform(suspend_always) → 透传

    std::cout << "  恢复后继续" << std::endl;
    co_return;
}

void controlled_demo() {
    auto task = controlled_coroutine();
    task.resume();  // 执行到 co_await 100 处挂起
    task.resume();  // 执行到 co_await suspend_always 处挂起
    task.resume();  // 执行完毕
}

// ============================
// 示例5:promise 构造函数接收协程参数
// ============================

struct LoggedTask {
    struct promise_type {
        std::string tag;

        // promise_type 的构造函数可以接收协程函数的参数
        // 如果协程签名是 LoggedTask f(std::string tag, int x)
        // 编译器会尝试用 (tag, x) 构造 promise_type
        promise_type(std::string t, int) : tag(std::move(t)) {
            std::cout << "[" << tag << "] 承诺对象已创建" << std::endl;
        }

        LoggedTask get_return_object() {
            return LoggedTask{
                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() {}
        void unhandled_exception() { std::terminate(); }
    };

    std::coroutine_handle<promise_type> handle_;
    explicit LoggedTask(std::coroutine_handle<promise_type> h) : handle_(h) {}
    ~LoggedTask() { if (handle_) handle_.destroy(); }
    LoggedTask(const LoggedTask&) = delete;
    LoggedTask& operator=(const LoggedTask&) = delete;
    LoggedTask(LoggedTask&& o) noexcept : handle_(o.handle_) { o.handle_ = nullptr; }

    void resume() { if (handle_ && !handle_.done()) handle_.resume(); }
};

LoggedTask logged_work(std::string tag, int count) {
    for (int i = 0; i < count; ++i) {
        std::cout << "[" << tag << "] 工作 " << i << std::endl;
        co_await std::suspend_always{};
    }
}

void logged_demo() {
    auto task = logged_work("任务A", 3);
    task.resume();  // 工作 0
    task.resume();  // 工作 1
    task.resume();  // 工作 2
}

int main() {
    std::cout << "=== 基础 promise_type ===" << std::endl;
    basic_demo();

    std::cout << "\n=== 返回值 ===" << std::endl;
    value_demo();

    std::cout << "\n=== 生成器 ===" << std::endl;
    generator_demo();

    std::cout << "\n=== await_transform ===" << std::endl;
    controlled_demo();

    std::cout << "\n=== 参数传递 ===" << std::endl;
    logged_demo();

    return 0;
}

promise_type 方法的调用时机 ​

方法调用时机
构造函数协程帧分配后,承诺对象构造时
get_return_object()承诺对象构造后、initial_suspend 前
initial_suspend()get_return_object 后,协程体执行前
yield_value(expr)遇到 co_yield expr 时
return_void()遇到 co_return; 或协程体末尾
return_value(expr)遇到 co_return expr; 时
unhandled_exception()协程体中抛出未捕获异常时
final_suspend()所有上述步骤之后,协程即将结束时
析构函数协程帧被销毁时

适用场景 ​

  • 实现自定义的 Task/Future 类型
  • 实现生成器(Generator)
  • 实现异步 I/O 框架的协程支持
  • 控制协程的内存分配策略
  • 通过 await_transform 限制或转换可等待的类型

常见问题 ​

promise_type 必须是返回类型的嵌套类型吗?

不是必须的。编译器默认通过 std::coroutine_traits<ReturnType, ArgTypes...>::promise_type 来查找。标准的 coroutine_traits 默认取 ReturnType::promise_type,但你可以特化 coroutine_traits 来指定其他类型。

initial_suspend 返回什么好?

大多数情况下返回 std::suspend_always(惰性启动),这样调用者可以完全控制协程何时开始执行。返回 std::suspend_never 表示立即执行,适用于协程结果会被立刻等待的场景。

final_suspend 为什么必须 noexcept?

因为 final_suspend 在异常处理之后调用。如果 final_suspend 本身抛异常,程序行为是未定义的。标准强制要求它是 noexcept。

await_transform 定义后,所有 co_await 都受影响吗?

是的。一旦 promise_type 定义了 await_transform,所有 co_await expr 都会先经过 await_transform(expr) 转换。如果你想让某些类型直接通过,需要为它们也提供 await_transform 重载。

promise_type 的构造函数可以接收协程参数吗?

可以。编译器会尝试用协程函数的参数来构造 promise_type。如果没有匹配的构造函数,就使用默认构造。这个特性可以用来在承诺对象中保存协程参数的引用。

注意事项 ​

  • return_void() 和 return_value() 只能定义一个
  • final_suspend() 必须标记为 noexcept
  • get_return_object() 在 initial_suspend() 之前调用
  • await_transform 一旦定义,会影响所有 co_await 表达式
  • promise 的构造函数参数匹配协程函数的参数列表
  • 自定义 operator new/delete 可以控制协程帧的分配策略
  • unhandled_exception() 中通常要么 std::terminate(),要么保存 std::current_exception() 供后续重新抛出

编译器支持情况 ​

编译器最低支持版本
GCC10.0
Clang14.0
MSVC19.28 (VS 2019 16.8)

总结 ​

promise_type 是协程的"控制面板",通过一组定制方法来控制协程的完整生命周期。必须实现的方法有五个:get_return_object() 创建返回对象、initial_suspend() 控制启动行为、final_suspend() 控制结束行为、return_void() 或 return_value() 处理返回值、unhandled_exception() 处理异常。可选方法中,yield_value() 支持 co_yield,await_transform() 可以拦截和转换所有 co_await 表达式。promise 的构造函数还能接收协程函数的参数。掌握 promise_type 的定制方法,就能实现任何类型的协程行为——从简单的 Task 到复杂的异步框架。