1
2
3
4
5

线程:  [task A 执行] → [OS 抢占] → [task B 执行] → [OS 抢占] → ...
       ↑ 被动切换，每次进出内核态                  ↑ 独立栈 ~MB

协程:  [task A 执行] → [co_await 挂起] → [task B 执行] → [co_await 挂起] → ...
       ↑ 主动挂起，纯用户态                        ↑ 协程帧 ~KB

1
2
3
4
5
6
7
8
9

// 普通函数
int normal_fn() { return 42; }

// 协程 —— 只要用了 co_* 关键字就是协程
Task<int> coro_fn() {
    int x = co_await some_async_op();  // 挂起点 1
    int y = x * 2;
    co_return y;                        // 挂起点 2（结束）
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

Task<int> compute(std::string name) {
    int a = 100;                   // 在帧上
    int b = co_await fetch(a);     // 挂起！a 和 name 必须保存在帧上
    int c = a + b;                 // a 从上个挂起点恢复
    co_return c + name.size();
}

// 编译后大致等价于：
struct __compute_frame {
    std::string name;       // 参数
    int a, b, c;            // 跨挂起点的局部变量
    promise_type __promise;
    int __state = 0;        // 状态编号：0=起点, 1=co_await后, 2=完成
};
// resume() 时用 switch(__state) 跳到对应位置继续执行

1
2
3
4
5
6
7

struct Task<T>::promise_type {
    Task<T> get_return_object();    // 协程被调用时，返回给调用者的对象
    suspend_always initial_suspend(); // 协程一开始是否立即挂起
    suspend_always final_suspend();   // 协程结束时是否挂起（不挂起则自动析构帧）
    void return_value(T value);       // co_return value → 走这里
    void unhandled_exception();       // 协程内抛了未捕获异常 → 走这里
};

1
2
3
4
5
6
7
8

1. operator new 分配协程帧
2. 把参数拷贝/移动到帧上
3. 在帧上构造 promise_type
4. promise.get_return_object() → 返回给调用者
5. co_await promise.initial_suspend() → 决定是否一开始就挂起
6. 执行协程体直到 co_return 或 co_await 或异常
7. co_await promise.final_suspend() → 决定协程帧是否立即释放
8. 析构 promise + 局部变量 + operator delete 帧

1
2
3
4
5

struct Awaitable {
    bool await_ready();                      // 能立刻完成？return true → 不挂起
    void await_suspend(coroutine_handle<>);  // 挂起时调用，获得协程句柄
    T    await_resume();                     // 恢复时调用，返回 co_await 的结果值
};

1
2
3
4
5
6
7
8
9

co_await expr:
  1. expr.await_ready()?
       true  → 直接走 4，不挂起（高效路径）
       false → 进入 2
  2. 挂起协程（保存状态到帧，切换出去）
  3. expr.await_suspend(handle)
       - 把 handle 保存到某个地方（比如 IO 完成队列）
       - 稍后外部事件触发 handle.resume()
  4. expr.await_resume() 的返回值 = co_await 的结果

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

struct SleepAwaiter {
    chrono::milliseconds delay_;

    bool await_ready() { return false; }  // 永远挂起

    void await_suspend(coroutine_handle<> h) {
        // 把协程句柄注册到定时器，delay_ 毫秒后 h.resume()
        timer_system::schedule(delay_, [h] { h.resume(); });
    }

    void await_resume() {}  // 无返回值
};

Task<> wait_and_print() {
    cout << "start" << endl;
    co_await SleepAwaiter{500ms};  // 挂起 500ms
    cout << "500ms later" << endl;
}

1
2
3
4
5

handle.resume();        // 恢复协程执行
handle.done();          // 协程是否已结束
handle.destroy();       // 手动销毁协程帧
handle.address();       // 获取帧地址（可用于调试或哈希）
handle.promise();       // 访问帧内的 promise_type

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

#include <coroutine>
#include <iostream>
#include <optional>
using namespace std;

template<typename T>
struct Generator {
    struct promise_type {
        optional<T> current;

        Generator get_return_object() {
            return Generator{coroutine_handle<promise_type>::from_promise(*this)};
        }
        suspend_always initial_suspend() { return {}; }  // 一开始挂起
        suspend_always final_suspend() noexcept { return {}; }
        suspend_always yield_value(T value) {
            current = value;    // 保存产出值
            return {};          // 挂起
        }
        void return_void() {}
        void unhandled_exception() { terminate(); }
    };

    coroutine_handle<promise_type> handle_;

    explicit Generator(coroutine_handle<promise_type> h) : handle_(h) {}
    ~Generator() { if (handle_) handle_.destroy(); }

    // 不可拷贝
    Generator(const Generator&) = delete;
    Generator& operator=(const Generator&) = delete;
    Generator(Generator&& other) noexcept : handle_(exchange(other.handle_, nullptr)) {}

    // 迭代器：每次 ++ 就 resume 协程取下一个 co_yield 值
    optional<T> next() {
        if (!handle_ || handle_.done()) return nullopt;
        handle_.resume();
        if (handle_.done()) return nullopt;
        return handle_.promise().current;
    }
};

// 使用 Generator 生成斐波那契数列
Generator<int> fibonacci() {
    int a = 0, b = 1;
    while (true) {
        co_yield a;
        auto next = a + b;
        a = b;
        b = next;
    }
}

int main() {
    auto gen = fibonacci();
    for (int i = 0; i < 10; ++i) {
        cout << *gen.next() << " ";  // 0 1 1 2 3 5 8 13 21 34
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

第 1 次 gen.next():
  a=0, b=1 → co_yield a → 输出 0 → 暂停！（next 还没算呢）
  停在哪里：co_yield 的下一行

第 2 次 gen.next():
  从上次停的地方继续 → next = 0+1 = 1 → a=1, b=1 → 转回 while 头
  → co_yield a → 输出 1 → 暂停！

第 3 次 gen.next():
  继续 → next = 1+1 = 2 → a=1, b=2 → co_yield a → 输出 1 → 暂停！

第 4 次 gen.next():
  继续 → next = 1+2 = 3 → a=2, b=3 → co_yield a → 输出 2 → 暂停！

第 5 次 gen.next():
  继续 → next = 2+3 = 5 → a=3, b=5 → co_yield a → 输出 3 → 暂停！

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

// 危险：死循环里没有挂起点，整个线程卡死
Task<> bad_loop() {
    while (true) {
        heavy_compute();  // 纯计算，永远不交出执行权
    }
}

// 安全：每次循环都主动挂起，让出 CPU 给其他协程
Task<> good_loop() {
    while (true) {
        heavy_compute();
        co_await yield();  // 显式让出，调度器去跑别人
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

Task<> handle_login(connection_id cid) {
    auto packet = co_await recv_async(cid);          // 1. 等客户端发握手包
    auto player = co_await db_query(packet.uid);      // 2. 查数据库（异步）
    if (!player) {
        co_await send_async(cid, "login failed");
        co_return;
    }
    auto scene = world.get_scene(player->last_pos);   // 3. 获取场景
    co_await scene->enter_async(player);               // 4. 进入场景（可能异步加载）
    co_await send_async(cid, "login ok");
    player->online = true;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// 等一个条件成熟，同时设超时
Task<bool> wait_for_players(int32 instance_id, int count, chrono::seconds timeout) {
    auto deadline = chrono::steady_clock::now() + timeout;
    while (world.get_instance(instance_id).player_count() < count) {
        if (chrono::steady_clock::now() > deadline) {
            co_return false;  // 超时
        }
        co_await SleepAwaiter{10ms};  // 挂起 10ms，让出执行权
    }
    co_return true;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

struct AsyncOp {
    int delay_ms_;
    EventLoop& loop_;

    bool await_ready() noexcept { return false; }
    void await_suspend(coroutine_handle<> h) noexcept {
        loop_.schedule(h, delay_ms_);  // 注册唤醒时间，线程立即返回
    }
    void await_resume() noexcept {}
};

Task player_login(int id, EventLoop& loop) {
    co_await AsyncOp{20 + id % 30, loop}; // 收包
    co_await AsyncOp{30 + id % 50, loop}; // 查 DB
    co_await AsyncOp{25 + id % 30, loop}; // 加载场景
    co_await AsyncOp{10 + id % 15, loop}; // 发响应
}

1
2
3
4
5
6

void player_login(int id) {
    sleep_for(milliseconds(20 + id % 30)); // 线程被占着，什么都干不了
    sleep_for(milliseconds(30 + id % 50));
    sleep_for(milliseconds(25 + id % 30));
    sleep_for(milliseconds(10 + id % 15));
}

1
2

协程:    1000 任务 × 1000 协程 → 并发度 1000 → 耗时 ≈ 最长链
线程池:  1000 任务 × N 线程     → 并发度 N    → 耗时 ≈ 最长链 × ceil(1000/N)

1
2
3
4
5
6

// 危险！
Task<> foo(const std::string& name) {
    co_await something();  // name 引用存到了帧上
    cout << name;          // 此时 name 引用的原始对象可能已经析构
}
// 安全：传值或 shared_ptr 到帧上