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);