async-io-model
Cooperative async patterns using explicit state machines, completions, and re-entrancy safeguards for Turso's I/O model.
- Core types:
IOResult<T>(returnsDoneorIOrequiring re-call) andCompletionfor tracking individual operations CompletionGroupaggregates multiple completions into one, with nesting and cancellation support- State machine pattern encodes progress in enum variants to safely handle re-entry across yield points
- Critical pitfall: mutating shared state before yield points causes bugs on re-entry; mutations must occur after yields or within state transitions
- Helper macros
return_if_io!andio_yield_one!simplify propagation and yielding logic
Async I/O Model Guide
Turso uses cooperative yielding with explicit state machines instead of Rust async/await.
Core Types
pub enum IOCompletions {
Single(Completion),
}
#[must_use]
pub enum IOResult<T> {
Done(T), // Operation complete, here's the result
IO(IOCompletions), // Need I/O, call me again after completions finish
}
Functions returning IOResult must be called repeatedly until Done.
More from tursodatabase/turso
code-quality
General Correctness rules, Rust patterns, comments, avoiding over-engineering. When writing code always take these into account
1.0Kindex-knowledge
Generate hierarchical AGENTS.md knowledge base for a codebase. Creates root + complexity-scored subdirectory documentation.
657debugging
How to debug tursodb using Bytecode comparison, logging, ThreadSanitizer, deterministic simulation, and corruption analysis tools
631storage-format
SQLite file format, B-trees, pages, cells, overflow, freelist that is used in tursodb
604testing
How to write tests, when to use each type of test, and how to run them. Contains information about conversion of `.test` to `.sqltest`, and how to write `.sqltest` and rust tests
598pr-workflow
General guidelines for Commits, formatting, CI, dependencies, security
596