Shuttle

Shuttle, from AWS Labs, is a library for testing concurrent Rust code using randomized concurrency testing techniques such as PCT (Probabilistic Concurrency Testing). By taking control of thread scheduling and exploring interleavings randomly, Shuttle reliably surfaces race conditions and deadlocks that would only appear intermittently under the real OS scheduler, and it reproduces any failing schedule deterministically for debugging.

What You Get

• Drop-in replacements for std::sync, threads, and collections used by the controlled scheduler
• Randomized schedulers implementing PCT and other probabilistic bug-finding techniques
• Deterministic replay of any failing schedule for debugging under a debugger
• Wrappers that make code using tokio, rand, and standard primitives testable

Common Use Cases

• Finding data races and deadlocks in lock-based concurrent Rust code
• Deterministically reproducing a flaky concurrency failure to debug it
• Adding concurrency regression tests to CI for synchronization-heavy crates

Under The Hood

Architecture

Shuttle is organized as a Cargo workspace: shuttle-core holds the scheduler runtime, shuttle-std provides the instrumented std replacements, shuttle-schedulers implements the scheduling algorithms (random, PCT), and shuttle-explorer supports exploration. Tests call entry points like check_random, which run the test closure repeatedly, each time letting the scheduler decide the order in which instrumented threads make progress.

Tech Stack

Rust library crate targeting stable Rust, built as a multi-crate workspace. It instruments concurrency primitives and integrates with tokio and rand via optional wrappers. Published on crates.io as shuttle, licensed Apache-2.0.

Code Quality

As an AWS Labs project it carries production-grade rigor: a dedicated tests directory, CI workflows, a CHANGELOG, code of conduct, and contributing guidelines. The scheduler logic is the tested core, and the crate is actively developed with frequent releases.

API Design

The primary API is intentionally small: swap std concurrency imports for shuttle ones and wrap the test in a check_* function. This keeps the mental model close to ordinary Rust threading, though understanding the randomized-scheduling model and wrapper coverage takes some ramp-up.