Async Io Model

If you're working in Turso's core codebase, this is the pattern guide you'll need whenever touching I/O. It covers their cooperative async model built on explicit state machines and IOResult enums instead of Rust's async/await. The real value is in the re-entrancy pitfall section, which shows exactly how mutating state before a yield point causes subtle bugs when functions get called again after I/O completes. You get concrete examples of the state machine pattern, CompletionGroup for waiting on multiple operations, and the helper macros like return_if_io! that make it less painful to write. This is reference material for a specific codebase architecture, not a general async patterns guide.

skills.sh installs: 1.3K
GitHub stars: 25.2K
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add tursodatabase/turso --skill async-io-model --agent claude-code

Installs into .claude/skills of the current project.

Files

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.

Completion and CompletionGroup

A Completion tracks a single I/O operation:

pub struct Completion { /* ... */ }

impl Completion {
    pub fn finished(&self) -> bool;
    pub fn succeeded(&self) -> bool;
    pub fn get_error(&self) -> Option<CompletionError>;
}

To wait for multiple I/O operations, use CompletionGroup:

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);

SKILL.md on GitHub