用途:这是 tursodb 的异步 I/O 模型说明,服务于在该代码库中编写和理解 I/O 相关代码的开发者。Turso 不采用 Rust 的 async/await,而是使用协作式让出配合显式状态机。
主要能力与核心类型:IOResult<T> 有两个变体,Done(T) 表示操作完成并返回结果,IO(IOCompletions) 表示需要 I/O,须在完成量完成后再次调用;返回 IOResult 的函数必须反复调用直到 Done。Completion 用于跟踪单个 I/O 操作,提供 finished()、succeeded()、get_error()。CompletionGroup 用于等待多个 I/O 操作:通过 add 加入单个完成量,build 生成一个全部完成时才结束的组合完成量,可嵌套、可 cancel 取消,全部完成或出错时调用回调。
辅助宏与状态机:return_if_io! 解包 IOResult,把 IO 变体沿调用栈向上传播;io_yield_one! 让出单个完成量。可能让出的操作使用显式状态枚举,函数在循环中匹配状态并转换,只有 Done 才返回结果。
重入陷阱(关键限制):让出点之前的共享状态变更会在重入时重复执行。错误写法是在 return_if_io! 前修改计数器;正确写法是在让出之后修改,或用状态机在 AfterIO 状态中只执行一次。常见错误包括 vec.push、idx += 1、map.insert 等位于让出之前;flag = true 通常可接受但仍需检查。状态枚举应把进度(如索引、数据)编码进变体,使其跨让出保留。
相关文件:core/types.rs、core/io/completions.rs、core/util.rs、core/state_machine.rs、core/storage/btree.rs、core/storage/pager.rs。测试:重入问题往往只在特定 I/O 时序下出现,可用确定性模拟、并发 DST 与故障注入强制在不同点让出。参考 docs/manual.md 的 I/O 章节。