1
协程 (Coroutine) = Cooperative + Routine（协作式例程）
2

3
对比三种执行流：
4

5
  函数 (Function)：
6
    调用 → 从头执行 → 返回 → 结束
7
    只能「一次性」运行，不能暂停
8

9
  线程 (Thread)：
10
    操作系统调度 → 抢占式切换
11
    可以在任意位置被换下（由 OS 决定）
12
    切换成本高（~1-10μs，涉及内核态）
13

14
  协程 (Coroutine)：
15
    自己决定何时暂停（co_await / co_yield）
16
    自己决定何时恢复（由调度器/事件循环驱动）
17
    纯用户态切换（~10-50ns，不涉及内核）

1
为什么需要协程？—— 回调地狱 vs 协程
2

3
场景：游戏启动 → 加载配置 → 连接服务器 → 认证 → 进入大厅
4

5
// ===== 回调版本 (Callback Hell) =====
6
void startGame() {
7
    loadConfig([](Config cfg) {
8
        connectServer(cfg, [](Connection conn) {
9
            authenticate(conn, [](AuthResult auth) {
10
                enterLobby(auth, [](Lobby lobby) {
11
                    // 终于进来了！但代码已经嵌套 4 层...
12
                    // 如果某个步骤需要条件分支 → 每一层都要写 → 爆炸
13
                });
14
            });
15
        });
16
    });
17
}
18

19
// ===== 协程版本 =====
20
Task<void> startGame() {
21
    Config cfg = co_await loadConfig();       // 「等待」但线程不阻塞
22
    Connection conn = co_await connectServer(cfg);
23
    AuthResult auth = co_await authenticate(conn);
24
    Lobby lobby = co_await enterLobby(auth);
25
    // 代码看起来像同步，但实际上是异步的！
26
    // 每个 co_await 处协程暂停，等结果到了再恢复
27
}

1
协程的生命周期：
2

3
1. Created (创建)
4
   调用协程函数 → 分配协程帧 → 执行 initial_suspend
5
   → 如果 initial_suspend 是 suspend_always: 暂停，等待首次 resume
6
   → 如果 initial_suspend 是 suspend_never: 立即开始执行
7

8
2. Suspended (挂起)
9
   遇到 co_await / co_yield → 保存当前执行状态到协程帧
10
   → 控制权返回调用者 / 恢复者
11

12
3. Resumed (恢复执行)
13
   外部调用 coroutine_handle::resume()
14
   → 从协程帧恢复状态 → 从上次暂停点之后继续
15

16
4. Completed (完成)
17
   协程执行到最后 / 遇到 co_return → 调用 final_suspend
18
   → final_suspend 通常返回 suspend_always → 外部可以取结果
19
   → 然后销毁协程帧

1
有栈协程 (Stackful Coroutine)：
2

3
  原理：协程拥有自己独立的调用栈
4
        切换时保存/恢复整个栈指针 + 寄存器
5

6
  代表：Boost.Context / Boost.Coroutine2
7
        Go goroutine
8
        Lua coroutine
9
        Python gevent (greenlet)
10

11
  特点：
12
    ✅ 可以在任意嵌套深度 yield（和线程一样自由）
13
    ✅ 已有代码（如第三方库）不需要修改就能协程化
14
    ❌ 每个协程有独立栈（~8KB~1MB）
15
    ❌ 切换开销较大（保存/恢复栈 + 寄存器）
16

17
  实现：Boost.Context 用汇编做栈切换 (jump_fcontext)
18
    - 保存当前栈指针、指令指针、非易失寄存器
19
    - 切换到目标协程的栈
20
    - 恢复目标协程的栈指针和寄存器
21
    - 跳转到目标协程的暂停点

1
// 有栈协程示例 (Boost.Coroutine2)
2
#include <boost/coroutine2/all.hpp>
3
using Coroutine = boost::coroutines2::coroutine<int>::pull_type;
4

5
void stackful_example() {
6
    Coroutine source([](Coroutine::push_type& yield) {
7
        // 这个 lambda 运行在独立栈上！
8
        for (int i = 0; i < 5; i++) {
9
            yield(i);  // 可以在这里 yield → 切换回主线程的栈
10
            // 从 yield 返回 → 栈切换回来
11
            doSomethingNested(yield);  // 可以在嵌套调用中 yield！
12
        }
13
    });
14

15
    while (source) {
16
        int val = source.get();  // 获取 yield 的值
17
        source();                 // 恢复协程 → 栈切换
18
    }
19
}
20

21
void doSomethingNested(Coroutine::push_type& yield) {
22
    // 嵌套调用中仍然可以 yield → 这是有栈协程的核心优势
23
    yield(42);
24
}

1
无栈协程 (Stackless Coroutine)：
2

3
  原理：协程不拥有独立栈
4
        编译器将协程体转换为状态机
5
        每次暂停，状态机记录「暂停点编号」
6
        恢复时，switch/跳转到对应状态继续执行
7

8
  代表：C++20 coroutine
9
        C# async/await
10
        Python async/await (asyncio 协程)
11
        JavaScript async/await
12
        Rust async/await
13

14
  特点：
15
    ✅ 零开销抽象（编译器生成状态机，等价于手写）
16
    ✅ 极小的内存开销（只保存跨越暂停点的局部变量）
17
    ✅ 不需要分配独立栈
18
    ❌ 只能在顶层 co_await/yield（不能从嵌套调用中暂停）
19
    ❌ 「染色问题」：异步函数只能被异步函数调用

1
// 无栈协程示例 (C++20)
2
// 编译器将这个函数转换为：
3
// struct __frame {
4
//     int __state;  // 0=开始, 1=在co_await之后
5
//     int i;        // 跨越暂停点的局部变量
6
//     promise_type __promise;
7
// };
8
Task<void> stackless_example() {
9
    for (int i = 0; i < 5; i++) {
10
        co_await someAsyncOp(i);  // 暂停点 1
11
        // 恢复后从这里继续
12
    }
13
    // 不能从嵌套调用中 co_await！
14
    // doSomethingNested() → 如果里面有 co_await → 编译错误
15
    // 除非 doSomethingNested 本身返回 awaitable
16
}

1
协程帧 = 编译器为协程分配的一块堆内存（默认）
2
包含以下内容：
3

4
┌──────────────────────────────────────┐
5
│ coroutine_handle (指向自身的指针)      │
6
├──────────────────────────────────────┤
7
│ promise_type 对象                     │
8
│   - 协程的控制平面                     │
9
├──────────────────────────────────────┤
10
│ 函数参数副本                          │
11
│   (按值传递的参数需要保存)             │
12
│   (按引用传递的只保存引用——小心悬空！) │
13
├──────────────────────────────────────┤
14
│ 跨越暂停点的局部变量                   │
15
│   (编译器分析：哪些变量在 co_await 之   │
16
│    后仍被使用 → 放入协程帧)            │
17
│ 不跨越暂停点的局部变量 → 仍留在调用栈  │
18
├──────────────────────────────────────┤
19
│ 当前暂停点编号 (resume point)          │
20
│   (状态机：0=开始, 1=第一个co_await后, │
21
│    2=第二个co_await后, ...)           │
22
└──────────────────────────────────────┘
23

24
示例：
25
Task<void> example(int x, const std::string& s) {
26
    int a = x + 1;         // 跨越暂停点 → 入帧
27
    co_await something();
28
    std::string b = s + "...";  // 不跨越后续暂停点 → 可留在栈
29
    use(b);
30
}
31

32
协程帧包含：
33
  - promise
34
  - x (int, 参数副本)
35
  - s (const string&, 引用——但 string 本身在哪？悬空风险！)
36
  - a (int, 跨越暂停点的局部变量)
37
  - 暂停点编号

1
#include <coroutine>
2
#include <exception>
3
#include <functional>
4
#include <variant>
5

6
// ===== 1. Task<T>：协程的返回类型 =====
7
template<typename T>
8
class Task {
9
public:
10
    struct promise_type;
11
    using handle_type = std::coroutine_handle<promise_type>;
12

13
    Task(handle_type h) : _handle(h) {}
14
    ~Task() { if (_handle) _handle.destroy(); }
15

16
    // 移动语义
17
    Task(Task&& other) noexcept : _handle(other._handle) {
18
        other._handle = nullptr;
19
    }
20

21
    // 获取结果（阻塞等待协程完成）
22
    T get() {
23
        if (!_handle.done()) {
24
            _handle.resume();   // 启动 / 恢复协程
25
        }
26
        return std::move(_handle.promise()._result);
27
    }
28

29
    // 检查是否已完成
30
    bool isDone() const { return !_handle || _handle.done(); }
31

32
private:
33
    handle_type _handle;
34
};
35

36
// ===== 2. promise_type：控制协程生命周期 =====
37
template<typename T>
38
struct Task<T>::promise_type {
39
    std::variant<std::monostate, T, std::exception_ptr> _result;
40

41
    Task<T> get_return_object() {
42
        return Task<T>(handle_type::from_promise(*this));
43
    }
44

45
    // 协程开始时立即执行（不暂停）
46
    std::suspend_never initial_suspend() { return {}; }
47

48
    // 协程结束时发起挂起——让外部有机会取结果
49
    std::suspend_always final_suspend() noexcept { return {}; }
50

51
    void return_value(T value) {
52
        _result.template emplace<T>(std::move(value));
53
    }
54

55
    void unhandled_exception() {
56
        _result.template emplace<std::exception_ptr>(std::current_exception());
57
    }
58
};
59

60
// Task<void> 偏特化
61
template<>
62
struct Task<void>::promise_type {
63
    std::exception_ptr _exception;
64

65
    Task<void> get_return_object() {
66
        return Task<void>(handle_type::from_promise(*this));
67
    }
68

69
    std::suspend_never initial_suspend() { return {}; }
70
    std::suspend_always final_suspend() noexcept { return {}; }
71

72
    void return_void() {}
73

74
    void unhandled_exception() {
75
        _exception = std::current_exception();
76
    }
77
};
78

79
// ===== 3. 一个具体的 Awaitable：模拟异步操作 =====
80
template<typename T>
81
class AsyncOperation {
82
    T _value;
83
    bool _ready;
84
    std::coroutine_handle<> _continuation;
85

86
public:
87
    AsyncOperation(T val) : _value(std::move(val)), _ready(false) {}
88

89
    // 模拟异步完成
90
    void complete() {
91
        _ready = true;
92
        if (_continuation) {
93
            _continuation.resume();  // 恢复等待的协程
94
        }
95
    }
96

97
    // Awaitable 三件套
98
    bool await_ready() const noexcept { return _ready; }
99

100
    void await_suspend(std::coroutine_handle<> h) noexcept {
101
        _continuation = h;   // 记录：完成后恢复谁
102
    }
103

104
    T await_resume() const noexcept { return _value; }
105
};
106

107
// ===== 4. 使用示例 =====
108
AsyncOperation<int> loadPlayerLevel(int playerId) {
109
    // 模拟：发起异步数据库查询，返回 awaitable
110
    return AsyncOperation<int>(playerId * 100);
111
}
112

113
Task<int> loadGameProgress(int playerId) {
114
    int level = co_await loadPlayerLevel(playerId);
115
    int score = co_await loadPlayerLevel(playerId + 1);  // 等第一次完成才执行第二次
116
    co_return level + score;
117
}
118

119
// 在某个事件循环中使用：
120
// Task<int> task = loadGameProgress(42);
121
// auto& op = ...; // 保存 AsyncOperation 的引用
122
// op.complete();  // 模拟异步完成
123
// int result = task.get();

1
UE5 的 Latent Action 系统是无栈协程思想在 C++17 时代的前瞻性实现：
2

3
原理：
4
  C++ 中没有 co_await 之前（UE5 基于 C++17），
5
  Epic 手动实现了类似协程的效果：
6
    节点函数返回时保存状态 → 下一帧被蓝图 VM 恢复
7
  → 本质上是 C++20 协程的手动状态机
8

9
但在 C++20 协程支持下，UE5 正在集成真正的协程：
10

11
  UAsyncAction 基类 + co_await 支持
12
  → 等待动画播放完成：
13
    co_await PlayMontageAsync(Character, AttackMontage);
14
    // 动画播完了，继续下一步
15
  → 等待网络响应：
16
    auto* Response = co_await SendHttpRequestAsync(URL);

1
// 对比：回调版 vs 协程版 —— UE5 风格的异步逻辑
2

3
// ===== 回调版：常见的 UE5 异步流程 =====
4
void AMyCharacter::StartComplexAction() {
5
    // 播放动画 → 等动画完成 → 生成特效 → 等延迟 → 应用伤害
6

7
    PlayAnimMontage(AttackMontage, 1.0f, NAME_None);
8

9
    GetWorldTimerManager().SetTimer(
10
        AnimTimer,
11
        [this]() {
12
            // 动画播完，生成特效
13
            SpawnEmitter(HitEffect, GetActorLocation());
14

15
            GetWorldTimerManager().SetTimer(
16
                DelayTimer,
17
                [this]() {
18
                    // 延迟结束，应用伤害
19
                    ApplyDamageToTarget();
20
                },
21
                0.5f, false
22
            );
23
        },
24
        AnimDuration, false
25
    );
26
    // 嵌套 3 层，且 Timer 管理容易出错
27
}
28

29
// ===== 协程版：想象有 co_await 后的 UE5 =====
30
Task<void> AMyCharacter::StartComplexAction_Coroutine() {
31
    co_await PlayAnimMontageAsync(AttackMontage);  // 等动画播完
32
    SpawnEmitter(HitEffect, GetActorLocation());
33
    co_await DelayAsync(0.5f);                     // 等 0.5 秒
34
    ApplyDamageToTarget();
35
    // 代码完全线性——和策划想的「先这样再那样」一致！
36
}

1
// 行为树节点的协程化 —— 分帧执行
2
#include <coroutine>
3

4
class AIController;
5

6
// 一个行为树节点：寻找掩体
7
Task<BehaviorStatus> FindCover(AIController* ai) {
8
    // 第一步：评估周围环境
9
    auto candidates = co_await EvaluateEnvironment(ai);  // 可能需要几帧
10
    co_yield BehaviorStatus::Running;  // 告诉行为树「还在执行中」
11

12
    // 第二步：路径寻找
13
    for (auto& spot : candidates) {
14
        auto path = co_await FindPathAsync(ai, spot);  // 寻路可能很慢
15
        co_yield BehaviorStatus::Running;
16

17
        if (path.isValid()) {
18
            ai->setTarget(spot);
19
            co_return BehaviorStatus::Success;
20
        }
21
    }
22

23
    co_return BehaviorStatus::Failure;
24
}
25

26
// 对比传统实现：
27
// 传统行为树每个节点是 Tick() 函数 + 状态机
28
//   class FindCoverNode : public BTNode {
29
//       enum State { EVAL, PATHFIND, DONE };
30
//       State _state;
31
//       int _candidateIndex;
32
//       // ... 大量手动状态管理
33
//   };
34
//
35
// 协程版本：把状态管理交给编译器和协程帧 → 代码量和可读性大幅改善

1
#include <coroutine>
2
#include <string>
3
#include <vector>
4
#include <queue>
5

6
// 对话系统的协程化 Generator
7
class DialogNode {
8
public:
9
    struct promise_type {
10
        std::string _currentText;
11
        std::vector<std::string> _choices;
12

13
        DialogNode get_return_object() {
14
            return DialogNode(handle_type::from_promise(*this));
15
        }
16
        std::suspend_never initial_suspend() { return {}; }
17
        std::suspend_always final_suspend() noexcept { return {}; }
18
        std::suspend_always yield_value(std::string text) {
19
            _currentText = std::move(text);
20
            return {};
21
        }
22
        void return_void() {}
23
        void unhandled_exception() { std::terminate(); }
24
    };
25

26
    // 条件分支：等待玩家选择
27
    struct ChoiceAwaiter {
28
        std::vector<std::string>& choices;
29
        int& result;
30

31
        bool await_ready() { return false; }  // 总是暂停等玩家
32
        void await_suspend(std::coroutine_handle<>) {}  // 由外部恢复
33
        int await_resume() { return result; }
34
    };
35

36
    ChoiceAwaiter showChoices(std::vector<std::string> opts) {
37
        _promise()._choices = std::move(opts);
38
        return ChoiceAwaiter{_promise()._choices, _playerChoice};
39
    }
40

41
    void setPlayerChoice(int c) { _playerChoice = c; }
42
    std::string currentText() { return _promise()._currentText; }
43
    // ...
44
};
45

46
// 编写对话脚本——像写小说一样自然
47
DialogNode welcomeDialog() {
48
    co_yield "欢迎来到冒险者公会！";
49
    co_yield "我是会长艾琳。";
50

51
    int choice = co_await showChoices({
52
        "我想接任务",
53
        "我想买卖装备",
54
        "随便聊聊"
55
    });
56

57
    if (choice == 0) {
58
        co_yield "很好！最近城外的哥布林又猖獗了...";
59
        // 接任务流程
60
    } else if (choice == 1) {
61
        co_yield "来看看我们的新货吧！";
62
        // 商店流程
63
    } else {
64
        co_yield "听说北方的巨龙最近苏醒了呢...";
65
        // 闲聊流程
66
    }
67

68
    co_yield "祝你旅途愉快！";
69
}
70

71
// 对比：传统 if/else 嵌套 + 状态机管理每个对话阶段
72
// → 协程版本是真正的「用代码写剧本」

1
// 真实游戏场景：协程化加载流程
2
Task<void> loadGameFlow() {
3
    // 1. 显示 Loading 界面（不阻塞）
4
    co_await showLoadingScreen("加载中...");
5

6
    // 2. 并行加载多个资源（真正需要框架支持并行）
7
    auto textureTask = loadTextureAsync("/Game/Heroes/Knight");
8
    auto modelTask = loadModelAsync("/Game/Heroes/Knight");
9
    auto audioTask = loadAudioAsync("/Game/Sounds/Footsteps");
10

11
    // 等待所有资源加载完成
12
    auto texture = co_await textureTask;
13
    co_await updateProgress(0.33);
14

15
    auto model = co_await modelTask;
16
    co_await updateProgress(0.66);
17

18
    auto audio = co_await audioTask;
19
    co_await updateProgress(1.0);
20

21
    // 3. 连接服务器
22
    auto conn = co_await connectServerAsync("game.example.com", 7777);
23
    if (!conn.isValid()) {
24
        co_await showErrorDialog("连接失败，请检查网络");
25
        co_await retryOrQuit();
26
        co_return;
27
    }
28

29
    // 4. 隐藏 Loading，进入游戏
30
    co_await hideLoadingScreen();
31
    co_await spawnPlayerCharacter();
32

33
    // 整个加载流程 —— 从 200 行回调嵌套 → 30 行线性代码
34
}