协程任务调度器必须严格对齐promise、awaiter、OS I/O句柄和调度队列的生命周期，否则将导致偶发crash或内存泄漏；关键在于await_suspend中正确管理coroutine_handle和awaiter的存储与销毁，避免悬垂指针。
协程任务调度器必须自己管理 awaiter 生命周期
直接把 std::coroutine_handle 存进队列、等 I/O 完成后再恢复，大概率 crash。C++20 协程的 awaiter 是栈对象，挂起后若其所在栈帧已退出（比如函数返回），await_resume() 调用时就会访问悬垂指针。
正确做法是：在 await_suspend() 中把 coroutine_handle 转为 std::coroutine_handle::from_address() 并转存为裸指针或 std::shared_ptr 管理的句柄；同时确保 awaiter 本身堆分配（例如用 new awaiter{handle}）或绑定到调度器生命周期内有效的对象上。
- 推荐模式：调度器持有
std::vector<:coroutine_handle>> m_pending</:coroutine_handle>，并在await_suspend()返回前调用handle.promise().set_state(PENDING)，让 promise 负责管理自身存活 - 避免写
return handle;后立刻 return 函数——这会让 awaiter 析构，但 handle 可能还没被调度器接管 - Linux 下 epoll_wait() 返回后，遍历就绪事件并调用对应 handle.resume()，此时必须确保该 handle 仍有效（即 promise 未被销毁）
epoll + 无锁队列实现 I/O 事件分发效率关键点
单线程调度器用 epoll_wait() 阻塞等待，但多个协程可能同时发起 read/write，需一个线程安全的入队机制把就绪事件关联到对应协程。别用 std::mutex 包裹整个事件循环——它会成为瓶颈。
更实际的做法是：I/O 发起线程（即协程挂起处）把待注册 fd 和 coroutine_handle 封装为结构体，通过 std::atomic 指针或 moodycamel::ConcurrentQueue（轻量级无锁队列）投递到 epoll 线程；epoll 线程批量调用 epoll_ctl(ADD)，再统一 epoll_wait()。
立即学习“C++免费学习笔记（深入）”；
组合式C++代码评审方案，融合静态分析、AI推理、多轮迭代评审和C++专项检查，适用于PR审查、增量代码审查、全项目评审和代码质量评分，触发词包括review cpp、cpp代码评审、C++review、代码审查。
- fd 必须设为
O_NONBLOCK，否则read()/write()在 await_suspend 中可能意外阻塞主线程 - 每个 fd 建议只注册一次，复用
epoll_event.data.ptr存储指向 awaiter 或 promise 的指针，避免查找开销 - resume 前检查
handle.done() == false，防止已被 destroy 的协程被误 resume
promise_type 设计决定协程能否被取消和超时
默认 promise_type 不提供取消语义，而真实 I/O 场景中常需要 cancel、timeout、retry。必须显式支持：await_transform(std::stop_token) 或自定义 async_read_with_timeout() 返回带 cancel 支持的 awaitable。
典型结构是 promise 内维护 std::optional<:stop_source> m_stop_src</:stop_source>，在 initial_suspend() 返回 suspend_always{} 后，由调度器在适当时候调用 m_stop_src->request_stop()；对应 awaiter 在 await_ready() 中轮询 stop_token.stop_requested()，或结合 timerfd 实现超时唤醒。
- 不要依赖
std::jthread自动 join 来“保证”协程结束——协程可能卡在 I/O 挂起态，jthread 退出时 handle 未 resume，promise 析构导致未定义行为 - 超时逻辑应与 I/O 注册解耦：timerfd 可单独 epoll 等待，触发后通过 shared_ptr 查找并 cancel 对应 awaiter
- cancel 不等于立即终止：要等协程执行到下一个 co_await 才能响应，因此业务代码需定期检查
co_await std::stop_token{}
Windows 下 IOCP 替代 epoll 时的句柄生命周期陷阱
IOCP 的 GetQueuedCompletionStatus() 返回的是 OVERLAPPED*，不是 fd。很多移植代码直接把 OVERLAPPED 成员变量当协程 handle 存，结果 resume 时崩溃——因为 OVERLAPPED 是栈分配或临时对象，IO 完成时早已析构。
正确方式是：把 coroutine_handle 存进自定义 OVERLAPPED 派生结构体（如 struct io_op : OVERLAPPED { std::coroutine_handle h; };），并在 await_suspend() 中 new 分配该结构体，传给 WSARecv() 等 API；IO 完成后从 LPOVERLAPPED 转回 io_op*，再调用 h.resume()。
- 务必调用
h.destroy()而非h.resume()处理失败路径（如 WSA_IO_INCOMPLETE），否则协程栈重复析构 - IOCP 关联的 completion key 不能用于存储 handle——它只有 4 字节，不够存 8 字节指针（64 位系统）
- Windows 上
co_await文件读写必须用 FILE_FLAG_OVERLAPPED 创建句柄，普通 HANDLE 不支持异步 I/O
协程调度器最难的部分不是挂起和恢复，而是让 promise、awaiter、OS I/O 句柄、调度队列四者生命周期严格对齐。漏掉任意一环，问题都表现为偶发 crash 或内存泄漏，且很难复现。调试时优先检查 resume 调用点是否在 promise 有效期内，其次确认所有 new 分配的 awaiter 最终都被 delete。其他都是细节。
