awaitable 是 c++20 中满足 await_ready()、await_suspend()、await_resume() 三函数约定的类型统称，用于协程挂起/恢复，支撑异步 I/O、延迟执行等；其 suspend 返回值决定控制权移交方式。
awaitable 是 C++20 协程中表示“可被 co_await 操作的对象”的统称，不是某个具体类型，而是一类满足特定约定（concept）的类型。它让对象能参与协程挂起与恢复流程，是实现异步 I/O、延迟执行、任务调度等的关键抽象。
awaitable 的核心约定
一个类型 T 要成为合法的 awaitable，必须提供三个关键成员函数（或 ADL 可见的非成员函数）：
-
await_ready()：返回bool，决定是否需要挂起。若返回true，协程立即继续，不挂起；返回false则进入挂起逻辑。 -
await_suspend(std::coroutine_handle h)：在挂起时调用，传入当前协程句柄h。可在此保存句柄、注册回调、提交到线程池，或直接恢复另一个协程（如尾调用优化）。 -
await_resume()：协程恢复后调用，负责返回co_await表达式的最终结果（类型任意，可为void）。
自定义 awaitable 的典型场景
你不需要继承某个基类，只需让类型满足上述接口即可。常见用途包括：
- 延迟等待：比如封装
std::this_thread::sleep_for的定时器 awaitable，挂起后启动后台定时器，到期再恢复协程。 - 异步 I/O 封装：将 POSIX
aio_read或 windows OVERLappED I/O 包装成 awaitable，await_suspend中发起操作，完成例程中调用resume()。 - 任务链式等待：例如
task类型本身是 awaitable，await_suspend可将当前协程句柄存入 task 内部，待其就绪时自动恢复。 - 条件等待：封装自旋/等待队列逻辑，如
async_mutex::scoped_lock，await_ready检查锁是否空闲，否则挂起并加入等待队列。
注意 suspend 和 resume 的所有权语义
await_suspend 的返回值决定了协程控制权如何移交：
立即学习“C++免费学习笔记（深入）”；
- 返回
void或bool（false）：协程挂起，需外部显式调用handle.resume()恢复。 - 返回
std::coroutine_handle：协程立即转移控制权给该 handle（即“挂起当前、恢复另一个”），原协程不再自动恢复，常用于无栈协程链或尾调用优化。 - 返回
std::suspend_always/std::suspend_never：标准库提供的便捷字面量类型，分别等价于返回bool{true}和bool{false}。
一个极简自定义 awaitable 示例
实现一个等待固定毫秒数的 sleep_ms：
struct sleep_ms { int ms_; sleep_ms(int ms) : ms_(ms) {} bool await_ready() const noexcept { return ms_ <= 0; } void await_suspend(std::coroutine_handle<> h) const { // 实际项目中应使用异步定时器（如 io_context.post_after） // 此处仅示意：新线程延时后恢复 std::thread([h]{ std::this_thread::sleep_for(std::chrono::milliseconds(ms_)); h.resume(); }).detach(); } void await_resume() const noexcept {} }; // 使用：co_await sleep_ms(100);