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 的查找顺序:

  1. 如果 promise 类型有 await_transform(expr) 方法,先调用它转换表达式
  2. 如果结果类型有成员 operator co_await(),调用它
  3. 如果有非成员 operator co_await(),调用它
  4. 否则表达式本身就是 Awaiter

Awaiter 的三个方法 ​

cpp
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 的结果

基本示例 ​

cpp
#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 之后访问协程的局部变量——协程可能已经被销毁

编译器支持情况 ​

编译器最低支持版本
GCC10.0
Clang14.0
MSVC19.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。