# CppCoroutine

**Repository Path**: ZJUZWT/cpp-coroutine

## Basic Information

- **Project Name**: CppCoroutine
- **Description**: cpp协程学习中例程
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-10-16
- **Last Updated**: 2025-10-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# C++20 协程学习项目

> 从基础概念到实际应用的协程实现集合

## 项目简介

这是一个展示C++20协程功能的项目，包含了从最基础的协程概念到复杂协程框架的完整实现。项目通过四个不同的模块，逐步展示协程的各种用法和内部机制。

## 快速开始

### macOS/Linux
```bash
# 一键构建并运行
./build.sh debug
```

### Windows
```cmd
# 一键构建并运行
build.bat debug
```

### 手动构建
```bash
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Debug ..
make -j$(nproc)
./bin/CoroutineTest
```

运行后可以看到协程的完整执行过程，每个步骤都有详细的日志输出，帮助理解协程的内部工作机制。

## 推荐阅读

- [C++20协程入门](https://zhuanlan.zhihu.com/p/497224333) - 入门教程，有很好的配图
- [协程理论详解](https://lewissbaker.github.io/2017/09/25/coroutine-theory) - 深入理论
- [C++协程标准](https://en.cppreference.com/w/cpp/language/coroutines.html) - 官方文档

## 项目模块

### 1. HelloWorld - 协程基础

最基础的协程实现，展示协程的基本生命周期和Awaiter机制。

**核心特性：**
- Promise对象的创建和管理
- Awaiter的三个关键方法（await_ready, await_suspend, await_resume）
- 协程的挂起和恢复过程

**运行效果：**
```
HelloWorld:
        Promise::get_return_object
        Promise::initial_suspend
        Awaiter::await_ready
        Awaiter::await_suspend
        Awaiter::await_resume
        Hello
        Awaiter::await_ready
        Awaiter::await_suspend
        Awaiter::await_resume
        World!
        Promise::return_void
        Promise::final_suspend
```

### 2. Delay - 异步延迟实现

实现基于时间的协程延迟，展示协程与真实异步操作的结合。

**核心特性：**
- 使用`std::thread`实现真正的异步延迟
- 通过`await_transform`让协程可以直接`co_await`浮点数
- 展示如何将同步操作包装成异步协程

**使用示例：**
```cpp
auto DelayedTask() -> Coroutine {
    co_await 2.0f;  // 延迟2秒
    std::cout << "延迟结束" << std::endl;
}
```

### 3. UE5Coro - 游戏引擎风格协程

模仿Unreal Engine 5的协程系统，展示协程在游戏开发中的应用。

**核心特性：**
- 实现类似UE5的LatentAction系统
- 支持协程的挂起和恢复
- 包含完整的协程生命周期管理
- 展示如何在游戏引擎中集成协程

### 4. CppReferenceStandard - 标准协程实现

完全按照C++标准实现的协程组件，深入展示协程的内部机制。

**包含功能：**
- **Promise构造函数**：展示不同参数如何影响Promise的创建
- **生命周期管理**：协程的完整生命周期跟踪
- **动态内存分配**：自定义协程状态的内存分配
- **Awaiter机制**：直接、间接、转换三种await方式
- **Yield功能**：协程的生成器模式

## 项目结构

```
CoroutineTest/
├── CMakeLists.txt              # CMake配置文件
├── build.sh                    # Linux/macOS构建脚本
├── build.bat                   # Windows构建脚本
├── src/
│   ├── main.cpp               # 主程序入口
│   └── coroutines/            # 协程实现
│       ├── HelloWorld.cpp     # 基础协程
│       ├── Delay.cpp          # 异步延迟
│       ├── UE5Coro.cpp        # UE5风格协程
│       └── CppReferenceStandard.cpp # 标准协程实现
├── include/
│   ├── coroutines/            # 协程头文件
│   └── utils/                 # 工具类
└── build/                     # 构建输出目录
```


## 技术特性

### 协程生命周期管理
- Promise对象的创建和销毁
- 协程状态的动态分配
- 异常处理机制
- 内存管理优化

### Awaiter接口实现
- `await_ready()`: 判断是否需要挂起
- `await_suspend()`: 协程挂起时的处理
- `await_resume()`: 协程恢复时的处理

### 输出格式化工具
项目包含`CoutTabber`工具类，用于在每行输出前自动添加制表符，让协程的执行流程更清晰易读。

## 学习价值

这个项目适合以下场景：
- 学习C++20协程的基本概念
- 理解协程的内部工作机制
- 实现自定义的协程框架
- 了解协程在游戏引擎中的应用

## 环境要求

- C++20编译器 (GCC 10+, Clang 10+, MSVC 2019+)
- CMake 3.20+
- 支持协程的操作系统