📦 Tokio Async Code Review — Tokio异步代码审查

• 检查 runtime 设置 —— 使用 #[tokio::main] 还是手动构造 runtime？多线程还是当前线程？
• 扫描阻塞调用 —— 搜索 std::fs、std::net、std::thread::sleep、在 async 函数中的 CPU 密集循环。
• 检查 channel 使用 —— 根据通信模式匹配 channel 类型（mpsc、broadcast、oneshot、watch）。
• 检查同步原语 —— 确认使用正确的 mutex 类型、守卫生命周期得当、无死锁风险。

输出格式

将发现按以下格式报告：

[FILE:LINE] ISSUE_TITLE
Severity: Critical | Major | Minor | Informational
Description of the issue and why it matters.

速查表

| Issue Type | Reference | |------------|-----------| | Task spawning, JoinHandle, structured concurrency | references/task-management.md | | Mutex, RwLock, Semaphore, Notify, Barrier | references/sync-primitives.md | | mpsc, broadcast, oneshot, watch channel patterns | references/channels.md |

评审清单

Runtime 配置

• [ ] Cargo.toml 中的 tokio 特性与实际使用匹配
• [ ] runtime 类型与负载匹配（I/O 密集用 multi_thread，简单场景用 current_thread）
• [ ] 异步测试使用 #[tokio::test]（而非手动构造 runtime）
• [ ] 生产环境 worker 线程数配置合理

任务管理

• [ ] spawn 的返回值（JoinHandle）被跟踪，而非静默丢弃
• [ ] CPU 密集或同步 I/O 操作使用 spawn_blocking
• [ ] 任务支持取消（通过 CancellationToken、select! 或关闭 channel）
• [ ] JoinError（任务 panic 或取消）被处理，而非直接 unwrap
• [ ] tokio::select! 的分支满足取消安全

同步原语

• [ ] 锁跨越 .await 时使用 tokio::sync::Mutex；非 async 短临界区用 std::sync::Mutex
• [ ] 不会在 await 点持有 mutex 守卫（防止死锁）
• [ ] 用 Semaphore 限制并发操作（而非临时计数器）
• [ ] 读多写少用 RwLock（频繁读，偶尔写）
• [ ] 简单通知用 Notify（避免 channel 开销）

通道

• [ ] channel 类型匹配模式：mpsc 用于背压，broadcast 用于扇出，oneshot 用于请求-响应，watch 用于最新值
• [ ] 有界 channel 容量合适（太小易死锁，太大耗内存）
• [ ] 处理 SendError / RecvError（表示对端已 drop）
• [ ] 处理 broadcast 的 Lagged 错误（接收方落后）
• [ ] 完成后及时 drop sender，向接收方发送结束信号

定时器与睡眠

• [ ] 使用 tokio::time::sleep 而非 std::thread::sleep
• [ ] 用 tokio::time::timeout 包裹可能挂起的操作
• [ ] 正确使用 tokio::time::interval（周期性工作用 .tick().await）

严重程度分级

Critical

• 在 async 上下文直接使用阻塞 I/O（std::fs::read、std::net::TcpStream）而未用 spawn_blocking
• 在 .await 点仍持有 mutex 守卫（可能死锁）
• 在 async 函数中使用 std::thread::sleep（阻塞 runtime 线程）
• 需要背压时使用无界 channel（OOM 风险）

Major

• 静默丢弃 JoinHandle（丢失错误、僵尸任务）
• 未考虑 select! 取消安全
• 错误选择 mutex 类型（std vs tokio）
• 网络/外部调用缺少超时

Minor

• 对极小的 async 块使用 tokio::spawn（开销大于收益）
• 无正当理由设置过大的 channel 缓冲区
• 可改用 #[tokio::main] 时却手动构造 runtime
• 高竞争场景下仍用 std::sync::Mutex 而不用 tokio 异步 mutex

Informational

• 建议使用 tokio-util 工具（如 CancellationToken）
• Tower 中间件模式用于服务组合
• 使用 JoinSet 实现结构化并发

有效模式（请勿标记）

• 短临界区用 std::sync::Mutex —— tokio 官方推荐锁内无 .await 时如此
• tokio::spawn 无需显式 join —— 后台任务具备正确关闭信号即可
• 容量为 1 的无缓冲 channel —— 适用于同步屏障
• 简单二进制文件用 #[tokio::main(flavor = "current_thread")] —— 并非所有应用都需多线程
• 在 spawn 前 clone() Arc —— 将所有权移入任务必需，非多余克隆
• 大容量 broadcast channel —— 若滞后错误代价高（如事件溯源）则合理

提交发现前

加载并遵循 beagle-rust:review-verification-protocol，再报告任何问题。