# coro

**Repository Path**: maopaonew/coro

## Basic Information

- **Project Name**: coro
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-30
- **Last Updated**: 2026-08-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Coro - C++23 协程运行时库

一个 API 全面对标 Rust [Tokio](https://github.com/tokio-rs/tokio) 的 C++23 协程库。

## 项目目标

- **教学优先** —— 用尽量小的代码量完整呈现协程运行时的每个机制： 对称转移、惰性启动、Proactor I/O、多线程调度，全部可在单个文件内读完整实现；
- **API 对标 Tokio** —— `spawn` / `block_on` / `spawn_blocking` /
  `JoinHandle` / `Builder` / `sleep_for` / `TcpListener` / `fs::File`， 语义与命名与 tokio 对齐，可对照学习；
- **Linux 原生性能路径** —— epoll 与 io_uring 双驱动，Proactor 模式统一 网络与文件 I/O；
- **正确性底线** —— 协程帧恰好销毁一次、任务异常全路径重抛、 多线程下所有协程恢复点经由同一队列。

架构详见 [ARCHITECTURE.md](ARCHITECTURE.md)。

## 核心特性

- **对称转移（Symmetric Transfer）** —— `FinalAwaiter` 直接返回
  `coroutine_handle<>` 跳转到等待者，深层 co_await 链栈深度 O (1)
- **惰性协程（Lazy Coroutine）** —— `Task` 创建后不自动执行， 需 `co_await` 或 `spawn` 才启动
- **多线程调度** —— Worker 线程池 + 统一事件循环： 任务、定时器、I/O 完成全部汇聚到同一队列，Worker 自主推进一切任务
- **Proactor 架构** —— 提交 I/O 请求，内核完成后恢复协程， 支持 EpollIoDriver 与 IoUringIoDriver
- **定时器** —— 最小堆定时器管理，`co_await sleep_for(1s)` 即可挂起等待
- **TCP 网络** —— `TcpListener` / `TcpStream`，异步 accept/read/write
- **文件 I/O** —— `File` 类与 `read_to_string` / `write_file` 便捷函数

## 快速上手

```cpp
#include <iostream>
#include <vector>

#include "coro/awaiter/Sleep.h"
#include "coro/runtime/Scheduler.h"
#include "coro/task/JoinHandle.h"
#include "coro/task/Task.h"

using namespace std::chrono_literals;

// 定义一个协程：每隔 1 秒累加一次
coro::Task<int> sum(int from, int to) {
    int res = 0;
    for (int i = from; i <= to; i++) {
        co_await coro::awaiter::sleep_for(1s);
        res += i;
    }
    co_return res;
}

int main() {
    coro::Runtime runtime(4);

    // 方式一：block_on 阻塞运行单个任务
    int result = runtime.block_on(sum(1, 3));
    std::cout << "result = " << result << std::endl;

    // 方式二：Tokio 风格便捷 API
    int result2 = coro::block_on(sum(1, 5));

    // 方式三：spawn 并发执行，JoinHandle 收集结果
    std::vector<coro::JoinHandle<int>> handles;
    for (int i = 0; i < 10; i++) {
        handles.push_back(coro::spawn(sum(1, i + 1)));
    }
    for (auto& h : handles) {
        std::cout << "result = " << h.join() << std::endl;
    }
}
```

## API 概览

### Runtime

```cpp
#include "coro/runtime/Runtime.h"

// Builder 模式
auto runtime = coro::Runtime::Builder()
    .with_threads(8)                        // 线程数，默认 hardware_concurrency()
    .with_io_driver<coro::EpollIoDriver>()  // 指定 IoDriver（默认 EpollIoDriver）
    .build();

// 核心方法
int result = runtime.block_on(std::move(task)); // 阻塞运行直到完成（异常重抛）
auto handle = runtime.spawn(std::move(task));   // 提交到线程池并发执行
auto future = runtime.spawn_blocking(fn);       // 在独立线程运行阻塞函数
```

### JoinHandle

```cpp
auto handle = coro::spawn(task);

int result = handle.join();   // 阻塞获取结果
handle.is_finished();         // 检查是否完成
handle.abort();               // 解除跟踪（协作式取消见路线图）
```

### Awaiter

```cpp
#include "coro/awaiter/Sleep.h"

// 定时器
co_await coro::awaiter::sleep_for(500ms);
co_await coro::awaiter::sleep_sec(3);

// Task 本身也是 awaitable，可以直接 co_await
auto result = co_await another_task();
```

### TCP 网络

```cpp
#include "coro/net/TcpListener.h"
#include "coro/net/TcpStream.h"

// TCP 服务端
auto listener = coro::net::TcpListener::bind("0.0.0.0", 8080);
auto [stream, addr] = co_await listener.accept();

char buf[1024];
auto n = co_await stream.read(buf, sizeof(buf));
co_await stream.write(buf, n);

// TCP 客户端
auto [stream, addr] = co_await coro::net::TcpStream::connect("127.0.0.1", 8080);
co_await stream.write_all("hello");
```

### 文件 I/O

```cpp
#include "coro/fs/File.h"

// 创建并写入文件
auto file = co_await coro::fs::File::create("/tmp/test.txt");
co_await file.write("hello world");
co_await file.sync_all();

// 读取文件
auto content = co_await coro::fs::read_to_string("/tmp/test.txt");

// 指定偏移读写
auto file2 = co_await coro::fs::File::open("/tmp/test.txt");
co_await file2.read_at(buf, 5, 6);       // 从偏移6读5字节
co_await file2.write_at("XXXXX", 5, 0);  // 从偏移0写5字节
```

## 目录结构

```
coro/
├── include/coro/           # 公开头文件（目录 = 命名空间）
│   ├── coro.h              #   伞形头文件
│   ├── task/               #   coro          Task / Promise / JoinHandle
│   ├── runtime/            #   coro          Runtime / Worker / TaskQueue / TimerManager / Scheduler
│   ├── io/                 #   coro          IoDriver / EpollIoDriver / IoUringIoDriver
│   ├── awaiter/            #   coro::awaiter Sleep / Recv / Send / Accept / Connect
│   ├── net/                #   coro::net     TcpListener / TcpStream / SocketAddr
│   └── fs/                 #   coro::fs      File 及便捷函数
├── src/                    # 库实现（与 include 一一对应）
├── examples/               # 每个功能一个独立示例
├── tests/                  # CTest 测试（自带轻量测试框架 test.h）
├── CMakeLists.txt
├── ARCHITECTURE.md         # 架构设计（分层、事件循环、数据流）
└── README.md
```

## 构建

要求：GCC 13+ / Clang 17+，Linux（epoll）；可选 liburing（io_uring 支持）。

```bash
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)

# 构建选项
#   -DCORO_WITH_IO_URING=ON/OFF    是否编译 IoUringIoDriver（默认 ON，需 liburing）
#   -DCORO_BUILD_EXAMPLES=ON/OFF   是否构建示例（默认 ON）
#   -DCORO_BUILD_TESTS=ON/OFF      是否构建测试（默认 ON）
```

## 示例

`examples/` 目录包含每个功能的独立示例：

| 示例                 | 功能                                             |
|----------------------|--------------------------------------------------|
| `00_quick_start`     | 最小可运行示例：block_on + spawn                 |
| `01_basic_task`      | 基本协程：`Task<void>` 和 `Task<T>`              |
| `02_co_await`        | 协程链式调用：`co_await` 另一个协程              |
| `03_spawn`           | 并发执行：`spawn` + `JoinHandle` + `std::ranges` |
| `04_join_handle`     | `JoinHandle` 的 `join` / `abort` / `is_finished` |
| `05_timer`           | 定时器：`sleep_for` / `sleep_sec`                |
| `06_block_on`        | `block_on` / `Builder` 模式 / 便捷 API           |
| `07_spawn_blocking`  | 阻塞函数：`spawn_blocking`                       |
| `08_concurrent`      | 综合：多协程并发 + 定时器                        |
| `09_tcp_echo_server` | TCP echo 服务端                                  |
| `10_tcp_echo_client` | TCP echo 客户端                                  |
| `11_file_io`         | 文件异步 I/O：创建/写入/读取/元数据/自由函数     |

```bash
cmake --build build --target example_00_quick_start
./build/example_00_quick_start
```

## 测试

项目使用 CTest，测试文件在 `tests/` 目录，自带轻量测试框架（`test.h`）：

| 测试                  | 覆盖范围                                              |
|-----------------------|-------------------------------------------------------|
| `test_task`           | Task 创建、co_return、co_await 链式调用、移动语义     |
| `test_spawn`          | spawn 并发执行、void 协程、大量任务                   |
| `test_join_handle`    | join / is_finished / abort                            |
| `test_timer`          | sleep_for / sleep_sec / 多定时器 / 精度               |
| `test_block_on`       | block_on / Builder / 便捷 API / 任务异常重抛          |
| `test_spawn_blocking` | 阻塞函数执行                                          |
| `test_io_driver`      | EpollIoDriver submit_read / cancel                    |
| `test_tcp`            | TcpListener / TcpStream 读写；**Worker 自主驱动 I/O** |
| `test_file`           | File 创建/读写/同步/元数据，自由函数                  |

```bash
cd build && ctest --output-on-failure
```

## 路线图

- [x] `Task` / `Promise` / `JoinHandle`（对称转移 + 惰性启动）
- [x] 多线程 Runtime + Worker 线程池 + 统一事件循环
- [x] 定时器驱动（`TimerManager` / `sleep_for`）
- [x] Tokio 风格 `spawn` / `block_on` / `Builder`
- [x] IO 驱动抽象：EpollIoDriver / IoUringIoDriver（Proactor 模式）
- [x] TCP 网络：`TcpListener` / `TcpStream`
- [x] Worker 自主驱动定时器与 I/O
- [ ] Channel 通信 —— `mpsc` / `oneshot` / `broadcast`
- [ ] Sync 原语 —— `Mutex` / `RwLock` / `Semaphore` / `Notify`
- [ ] 协作式任务取消
- [ ] 真异步文件 I/O（io_uring 接入 `fs::File`）
- [ ] Work-stealing 调度
- [ ] tracing 风格任务日志