协程承诺类型 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) | 内存分配失败时的处理 |
编译器生成的协程框架伪代码
// 编译器大致把协程函数转换成这样的逻辑:
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 挂起,销毁帧
}基本示例
#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()必须标记为noexceptget_return_object()在initial_suspend()之前调用await_transform一旦定义,会影响所有co_await表达式- promise 的构造函数参数匹配协程函数的参数列表
- 自定义
operator new/delete可以控制协程帧的分配策略 unhandled_exception()中通常要么std::terminate(),要么保存std::current_exception()供后续重新抛出
编译器支持情况
| 编译器 | 最低支持版本 |
|---|---|
| GCC | 10.0 |
| Clang | 14.0 |
| MSVC | 19.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 到复杂的异步框架。