coroutine-study

📘 学习型 C++20 协程库 —— 从零实现，深入理解协程原理

🎯 项目目标

本项目旨在通过从零实现一个完整的协程库，帮助开发者深入理解 C++20 协程的底层原理：

• ✅ 协程帧（Coroutine Frame）的内存布局
• ✅ promise_type 与协程生命周期管理
• ✅ awaitable / awaiter 机制详解
• ✅ 协程调度器设计
• ✅ 协程同步原语（Mutex、Semaphore）

📚 适合人群

• 想深入理解 C++20 协程原理的开发者
• 希望手写协程库学习底层机制的学习者
• 需要协程参考实现的项目开发者

🚀 快速开始

环境要求

• 编译器：GCC 12+ 或 Clang 10+（GCC 11 有协程 bug，部分功能受限）
• CMake：3.20+
• 标准：C++20（必须支持协程）

构建步骤

方法 1：使用 CMake（推荐）

# 克隆项目
git clone https://github.com/YOUR_USERNAME/coroutine-study.git
cd coroutine-study

# 创建构建目录
mkdir build && cd build

# 配置并构建
cmake ..
cmake --build .

# 运行示例
./example_basic

方法 2：直接编译

# 使用 GCC
g++ -std=c++20 -fcoroutines -I./include -o example examples/01_basic_final.cpp

# 使用 Clang
clang++ -std=c++20 -I./include -o example examples/01_basic_final.cpp

# 运行
./example

⚠️ GCC 版本注意事项

• GCC 12+：完整支持所有协程功能
• GCC 11：基本功能可用，但协程嵌套（co_await 嵌套）有编译器 bug
• Clang 10+：完整支持，推荐使用

📁 项目结构

coroutine-study/
├── include/coroutine/     # 头文件（公共接口）
│   ├── task.h            # Task 封装
│   ├── scheduler.h       # 调度器
│   ├── awaitable.h       # Awaiter 基础
│   ├── mutex.h           # 协程锁
│   └── timer.h           # 定时器
├── src/                   # 源文件（内部实现）
├── examples/              # 示例代码
│   ├── 01_basic.cpp      # 基础协程
│   ├── 02_task.cpp       # Task 使用
│   ├── 03_scheduler.cpp  # 调度器
│   ├── 04_mutex.cpp      # 协程锁
│   └── 05_timer.cpp      # 定时器
├── tests/                 # 单元测试
└── docs/                  # 文档

📖 核心概念速查

1. 协程三大关键字

关键字	作用
co_await	等待一个异步操作完成
co_yield	从协程中产出值（生成器）
co_return	从协程返回结果

2. 核心组件

• Task：协程任务包装器，类似 std::future
• Scheduler：协程调度器，管理协程的执行顺序
• Awaiter：定义 co_await 的行为
• Mutex：协程友好的互斥锁

📝 示例代码

基础 Task 使用

#include <coroutine/task.h>

coro::Task<int> async_add(int a, int b) {
    co_return a + b;
}

int main() {
    auto task = async_add(1, 2);
    int result = task.get();  // 阻塞获取结果
    return 0;
}

协程调度器

#include <coroutine/scheduler.h>

coro::Scheduler scheduler;

coro::Task<void> my_coroutine() {
    co_await scheduler.sleep(std::chrono::milliseconds(100));
    co_return;
}

📚 学习路线

1. Phase 1：阅读 01_basic.cpp，理解协程基础语法
2. Phase 2：阅读 task.h，理解 promise_type 设计
3. Phase 3：阅读 scheduler.h，理解调度器原理
4. Phase 4：阅读 mutex.h，理解协程同步

🐛 调试与排错

• BUG_SOLUTIONS.md - 详细记录项目中的 Bug、解决过程、AI 辅助调试方法
  • 6 个深度案例分析
  • AI 辅助调试四轮对话框架
  • 系统性调试检查清单

🌟 技术亮点

• TECH_HIGHLIGHTS.md - 纯技术视角的差异化分析
  • 协程帧内存布局透明化
  • promise_type 完全暴露
  • await_suspend 精细控制
  • GCC 11/12 workaround 实现
  • 零开销任务包装器
  • 与 cppcoro/libcoro/std::future 技术对比

🔧 高级主题

• 无锁协程调度
• 协程池设计
• 与 asio 集成
• 协程调试技巧

📄 许可证

MIT License

🙏 致谢

• 代码随想录 - 项目灵感来源
• cppcoro - 参考实现
• C++20 Standard - 协程标准文档