OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add tursodatabase/turso --skill async-io-model
Explanations of common asynchronous patterns used in tursodb. Involves IOResult, state machines, re-entrancy pitfalls, CompletionGroup. Always use these patterns in `core` when doing anything IO
npx skills add tursodatabase/turso --skill async-io-model
Turso uses cooperative yielding with explicit state machines instead of Rust async/await.
Functions returning IOResult must be called repeatedly until Done.
A Completion tracks a single I/O operation:
To wait for multiple I/O operations, use CompletionGroup:
CompletionGroup features:
group.cancel()return_if_io!Unwraps IOResult, propagates IO variant up the call stack:
io_yield_one!Yields a single completion:
Operations that may yield use explicit state enums:
The function loops, matching on state and transitioning:
State mutations before yield points cause bugs on re-entry.
If something_that_might_yield() returns IO, caller waits for completion, then calls bad_example() again. counter gets incremented twice (or more).
| Pattern | Problem |
|---|---|
vec.push(x); return_if_io!(...) | Vec grows on each re-entry |
idx += 1; return_if_io!(...) | Index advances multiple times |
map.insert(k,v); return_if_io!(...) | Duplicate inserts or overwrites |
flag = true; return_if_io!(...) | Usually ok, but check logic |
Encode progress in state variants:
Key files:
core/types.rs - IOResult, IOCompletions, return_if_io!, return_and_restore_if_io!core/io/completions.rs - Completion, CompletionGroupcore/util.rs - io_yield_one! macrocore/state_machine.rs - Generic StateMachine wrappercore/storage/btree.rs - Many state machine examplescore/storage/pager.rs - CompletionGroup usage examplesRe-entrancy bugs often only manifest under specific IO timing. Use:
testing/simulator/)testing/concurrent-simulator/)docs/manual.md section on I/Opub struct Completion { /* ... */ }
impl Completion {
pub fn finished(&self) -> bool;
pub fn succeeded(&self) -> bool;
pub fn get_error(&self) -> Option<CompletionError>;
}let mut group = CompletionGroup::new(|_| {});
// Add individual completions
group.add(&completion1);
group.add(&completion2);
// Build into single completion that finishes when all complete
let combined = group.build();
io_yield_one!(combined);let result = return_if_io!(some_io_operation());
// Only reaches here if operation returned Doneio_yield_one!(completion); // Returns Ok(IOResult::IO(Single(completion)))enum MyOperationState {
Start,
WaitingForRead { page: PageRef },
Processing { data: Vec<u8> },
Done,
}fn my_operation(&mut self) -> Result<IOResult<Output>> {
loop {
match &mut self.state {
MyOperationState::Start => {
let (page, completion) = start_read();
self.state = MyOperationState::WaitingForRead { page };
io_yield_one!(completion);
}
MyOperationState::WaitingForRead { page } => {
let data = page.get_contents();
self.state = MyOperationState::Processing { data: data.to_vec() };
// No yield, continue loop
}
MyOperationState::Processing { data } => {
let result = process(data);
self.state = MyOperationState::Done;
return Ok(IOResult::Done(result));
}
MyOperationState::Done => unreachable!(),
}
}
}fn bad_example(&mut self) -> Result<IOResult<()>> {
self.counter += 1; // Mutates state
return_if_io!(something_that_might_yield()); // If yields, re-entry will increment again!
Ok(IOResult::Done(()))
}fn good_example(&mut self) -> Result<IOResult<()>> {
return_if_io!(something_that_might_yield());
self.counter += 1; // Only reached once, after IO completes
Ok(IOResult::Done(()))
}enum State { Start, AfterIO }
fn good_example(&mut self) -> Result<IOResult<()>> {
loop {
match self.state {
State::Start => {
// Don't mutate shared state here
self.state = State::AfterIO;
return_if_io!(something_that_might_yield());
}
State::AfterIO => {
self.counter += 1; // Safe: only entered once
return Ok(IOResult::Done(()));
}
}
}
}// Good: index is part of state, preserved across yields
enum ProcessState {
Start,
ProcessingItem { idx: usize, items: Vec<Item> },
Done,
}
// Loop advances idx only when transitioning states
ProcessingItem { idx, items } => {
return_if_io!(process_item(&items[idx]));
if idx + 1 < items.len() {
self.state = ProcessingItem { idx: idx + 1, items };
} else {
self.state = Done;
}
}