co_await 关键字与 Awaitable
什么是 co_await
co_await 是 C++20 协程的核心关键字,用来在协程内部发起一次"等待"操作。当协程执行到 co_await expr 时,它会检查被等待的对象是否"准备好了"——如果准备好了就直接继续执行,如果没准备好就挂起协程,把控制权交还给调用者或调度器。
co_await 是一个一元运算符,它的操作数是一个 Awaitable 对象。这个对象通过三个方法来控制挂起和恢复的行为。
Awaitable 与 Awaiter
这两个概念经常混用,但严格来说有区别:
| 概念 | 定义 |
|---|---|
| Awaitable | 可以出现在 co_await 右侧的对象。它要么自身就是 Awaiter,要么可以通过 operator co_await 转换为 Awaiter |
| Awaiter | 实现了 await_ready()、await_suspend()、await_resume() 三个方法的对象 |
编译器获取 Awaiter 的查找顺序:
- 如果 promise 类型有
await_transform(expr)方法,先调用它转换表达式 - 如果结果类型有成员
operator co_await(),调用它 - 如果有非成员
operator co_await(),调用它 - 否则表达式本身就是 Awaiter
Awaiter 的三个方法
struct MyAwaiter {
// 是否已经准备好(不需要挂起)
// 返回 true:不挂起,直接调用 await_resume()
// 返回 false:需要挂起
bool await_ready() const noexcept;
// 协程即将挂起时调用
// 参数是当前协程的句柄
// 返回值决定挂起后的行为(见下文)
void await_suspend(std::coroutine_handle<> h) const noexcept;
// 或:bool await_suspend(std::coroutine_handle<> h);
// 或:std::coroutine_handle<> await_suspend(std::coroutine_handle<> h);
// 协程恢复时调用,返回值就是 co_await 表达式的结果
T await_resume() const noexcept;
};await_suspend 的三种返回类型
| 返回类型 | 行为 |
|---|---|
void | 无条件挂起,控制权返回给调用者/恢复者 |
bool | 返回 true 挂起,返回 false 不挂起(立即恢复当前协程) |
std::coroutine_handle<> | 挂起当前协程,然后恢复返回的句柄指向的协程(对称转移) |
co_await 的执行流程
co_await expr
|
v
获取 Awaiter 对象(通过 await_transform / operator co_await / 直接使用)
|
v
调用 awaiter.await_ready()
|
+--- 返回 true → 跳过挂起,直接调用 awaiter.await_resume()
|
+--- 返回 false → 挂起协程
|
v
调用 awaiter.await_suspend(handle)
|
+--- void → 挂起,返回调用者
+--- true → 挂起,返回调用者
+--- false → 不挂起,立即恢复
+--- 另一个 handle → 挂起,恢复那个协程
|
v
(协程被恢复后)
|
v
调用 awaiter.await_resume() → 返回值作为 co_await 的结果基本示例
#include <coroutine>
#include <iostream>
#include <string>
#include <thread>
#include <chrono>
// ============================
// 基础:返回对象类型(后续示例复用)
// ============================
struct Task {
struct promise_type {
Task get_return_object() {
return Task{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 Task(std::coroutine_handle<promise_type> h) : handle_(h) {}
~Task() { if (handle_) handle_.destroy(); }
Task(const Task&) = delete;
Task& operator=(const Task&) = delete;
Task(Task&& o) noexcept : handle_(o.handle_) { o.handle_ = nullptr; }
void resume() { if (handle_ && !handle_.done()) handle_.resume(); }
bool done() const { return !handle_ || handle_.done(); }
};
// ============================
// 示例1:标准库自带的两个 Awaiter
// ============================
// std::suspend_always 和 std::suspend_never 是标准库提供的最简 Awaiter
// suspend_always: await_ready() 返回 false(总是挂起)
// suspend_never: await_ready() 返回 true(从不挂起)
Task demo_trivial_awaiters() {
std::cout << "开始" << std::endl;
co_await std::suspend_always{}; // 总是挂起
std::cout << "第一次恢复后" << std::endl;
co_await std::suspend_never{}; // 不挂起,立即继续
std::cout << "suspend_never 不会挂起" << std::endl;
co_await std::suspend_always{}; // 再次挂起
std::cout << "第二次恢复后" << std::endl;
}
void trivial_awaiter_demo() {
auto task = demo_trivial_awaiters();
task.resume(); // 输出 "开始",遇到 suspend_always 挂起
task.resume(); // 输出 "第一次恢复后" 和 "suspend_never 不会挂起",遇到第二个 suspend_always 挂起
task.resume(); // 输出 "第二次恢复后"
}
// ============================
// 示例2:自定义 Awaiter——带返回值
// ============================
// 这个 Awaiter 不挂起,直接返回一个值
struct ReadyValue {
int value;
bool await_ready() const noexcept {
return true; // 已经准备好了,不需要挂起
}
void await_suspend(std::coroutine_handle<>) const noexcept {
// 不会被调用,因为 await_ready 返回 true
}
int await_resume() const noexcept {
return value; // co_await 表达式的结果就是这个值
}
};
// 这个 Awaiter 会挂起,恢复后返回一个值
struct SuspendAndReturn {
int value;
bool await_ready() const noexcept {
return false; // 需要挂起
}
void await_suspend(std::coroutine_handle<>) const noexcept {
// 挂起后什么都不做,等调用者 resume
}
int await_resume() const noexcept {
return value; // 恢复后返回这个值
}
};
// 需要一个支持返回值的 Task 类型
struct IntTask {
struct promise_type {
int result = 0;
IntTask get_return_object() {
return IntTask{std::coroutine_handle<promise_type>::from_promise(*this)};
}
std::suspend_always initial_suspend() noexcept { return {}; }
std::suspend_always final_suspend() noexcept { return {}; }
void return_value(int v) { result = v; }
void unhandled_exception() { std::terminate(); }
};
std::coroutine_handle<promise_type> handle_;
explicit IntTask(std::coroutine_handle<promise_type> h) : handle_(h) {}
~IntTask() { if (handle_) handle_.destroy(); }
IntTask(const IntTask&) = delete;
IntTask& operator=(const IntTask&) = delete;
IntTask(IntTask&& o) noexcept : handle_(o.handle_) { o.handle_ = nullptr; }
void resume() { if (handle_ && !handle_.done()) handle_.resume(); }
bool done() const { return !handle_ || handle_.done(); }
int result() const { return handle_.promise().result; }
};
IntTask value_awaiter_demo_coro() {
// ReadyValue 不挂起,直接返回值
int a = co_await ReadyValue{42};
std::cout << "ReadyValue 返回: " << a << std::endl;
// SuspendAndReturn 会挂起,恢复后返回值
int b = co_await SuspendAndReturn{100};
std::cout << "SuspendAndReturn 返回: " << b << std::endl;
co_return a + b;
}
void value_awaiter_demo() {
auto task = value_awaiter_demo_coro();
task.resume(); // 执行到 SuspendAndReturn 处挂起
task.resume(); // 恢复,输出结果,执行 co_return
std::cout << "最终结果: " << task.result() << std::endl;
}
// ============================
// 示例3:await_suspend 返回 bool
// ============================
struct ConditionalSuspend {
bool should_suspend;
bool await_ready() const noexcept {
return false; // 先进入 await_suspend 判断
}
// 返回 bool:true 挂起,false 不挂起
bool await_suspend(std::coroutine_handle<>) const noexcept {
std::cout << "await_suspend: should_suspend = "
<< std::boolalpha << should_suspend << std::endl;
return should_suspend;
}
void await_resume() const noexcept {}
};
Task conditional_demo_coro() {
std::cout << "步骤 1" << std::endl;
co_await ConditionalSuspend{false}; // 不会实际挂起
std::cout << "步骤 2(紧接步骤 1)" << std::endl;
co_await ConditionalSuspend{true}; // 会挂起
std::cout << "步骤 3(需要 resume)" << std::endl;
}
void conditional_demo() {
auto task = conditional_demo_coro();
task.resume(); // 步骤1,ConditionalSuspend(false) 不挂起,步骤2,ConditionalSuspend(true) 挂起
task.resume(); // 步骤3
}
// ============================
// 示例4:通过 operator co_await 转换
// ============================
// Awaitable 类型(不直接是 Awaiter)
struct Timer {
int seconds;
// 通过成员 operator co_await 转换为 Awaiter
auto operator co_await() const noexcept {
struct TimerAwaiter {
int seconds;
bool await_ready() const noexcept {
return seconds <= 0; // 0 秒不需要等待
}
void await_suspend(std::coroutine_handle<>) const noexcept {
std::cout << "模拟等待 " << seconds << " 秒..." << std::endl;
// 实际项目中这里会注册回调或事件
}
int await_resume() const noexcept {
return seconds; // 返回等待的秒数
}
};
return TimerAwaiter{seconds};
}
};
IntTask timer_demo_coro() {
int waited = co_await Timer{3}; // 通过 operator co_await 转换
std::cout << "等待了 " << waited << " 秒" << std::endl;
int no_wait = co_await Timer{0}; // 0 秒,await_ready 返回 true,不挂起
std::cout << "零等待完成" << std::endl;
co_return waited;
}
void timer_demo() {
auto task = timer_demo_coro();
task.resume(); // 执行到 Timer{3} 处挂起
task.resume(); // 恢复,Timer{0} 不挂起,直接执行完
}
int main() {
std::cout << "=== 标准 Awaiter ===" << std::endl;
trivial_awaiter_demo();
std::cout << "\n=== 带返回值的 Awaiter ===" << std::endl;
value_awaiter_demo();
std::cout << "\n=== 条件挂起 ===" << std::endl;
conditional_demo();
std::cout << "\n=== operator co_await ===" << std::endl;
timer_demo();
return 0;
}标准库提供的 Awaiter
| 类型 | await_ready() | await_suspend() | await_resume() | 用途 |
|---|---|---|---|---|
std::suspend_always | 返回 false | 空操作 | 返回 void | 总是挂起 |
std::suspend_never | 返回 true | 空操作 | 返回 void | 从不挂起 |
适用场景
- 异步 I/O 等待:
co_await一个网络读写操作,完成后恢复 - 定时器等待:
co_await一个延时对象 - 事件等待:
co_await一个条件变量或事件通知 - 协程链式调用:
co_await另一个协程的结果 - 通道(Channel)操作:
co_await从通道读取/写入数据
常见问题
co_await 可以在普通函数中使用吗?
不能。co_await 只能在协程函数体中使用。一旦函数体中出现 co_await、co_yield 或 co_return,该函数就成为协程。
await_ready 返回 true 时,await_suspend 还会被调用吗?
不会。await_ready 返回 true 表示"已准备好",编译器直接跳到 await_resume(),不调用 await_suspend()。
await_resume 的返回值可以是任意类型吗?
可以。await_resume() 的返回类型就是 co_await 表达式的类型。它可以是 void、基本类型、对象类型等。
什么是对称转移(Symmetric Transfer)?
当 await_suspend 返回一个 std::coroutine_handle<> 时,当前协程挂起后不是返回调用者,而是直接恢复返回的那个协程。这避免了递归调用导致的栈溢出,是实现协程链式等待的关键技术。
promise_type 的 await_transform 有什么用?
它可以拦截所有 co_await 表达式,对被等待的对象做转换。比如你可以禁止某些类型被 co_await,或者自动包装某些类型为合适的 Awaiter。
注意事项
co_await只能在协程函数体内使用await_ready返回true是一种优化——避免不必要的挂起await_suspend中不要做阻塞操作(那样会阻塞整个线程)await_suspend返回void和返回true的效果相同——都是无条件挂起final_suspend返回的 Awaiter 的await_resume()不会被调用- 对称转移(
await_suspend返回coroutine_handle)可以避免深层协程调用的栈溢出 - 不要在
await_suspend之后访问协程的局部变量——协程可能已经被销毁
编译器支持情况
| 编译器 | 最低支持版本 |
|---|---|
| GCC | 10.0 |
| Clang | 14.0 |
| MSVC | 19.28 (VS 2019 16.8) |
总结
co_await 是 C++20 协程挂起和恢复的核心机制。它接受一个 Awaitable 对象,通过三个方法(await_ready、await_suspend、await_resume)控制是否挂起、挂起后做什么、恢复时返回什么。await_ready 提供了"不需要等待就不挂起"的快速路径;await_suspend 决定挂起后的控制流走向(返回调用者、有条件挂起、或对称转移到另一个协程);await_resume 的返回值就是整个 co_await 表达式的结果。标准库提供了 suspend_always 和 suspend_never 两个最基本的 Awaiter,实际项目中你需要根据具体的异步操作来自定义 Awaiter。