ringbuf

ringbuf is a Rust crate implementing a single-producer, single-consumer (SPSC) lock-free ring buffer (circular FIFO queue), designed for passing data between threads without locks or allocation on the hot path. It supports no_std and no_alloc environments via optional features, direct/unsafe slice access to the buffer’s contiguous storage for zero-copy reads and writes, and companion crates for blocking (ringbuf-blocking) and async (async-ringbuf) producer/consumer wrappers.

Because its core guarantee is wait-free operation between exactly one producer and one consumer thread, ringbuf is commonly used in real-time and latency-sensitive contexts — audio/DSP pipelines, embedded systems, and any producer/consumer thread pair where blocking or allocating is unacceptable.

What You Get

• A generic RingBuffer type split into independent Producer/Consumer halves for safe cross-thread use without locks
• Direct, unsafe slice access to the buffer’s contiguous storage for zero-copy bulk reads/writes
• no_std and no_alloc support via feature flags, plus a portable-atomic backend for platforms without native atomics
• Companion workspace crates: ringbuf-blocking for blocking wait semantics and async-ringbuf for async/await-based producer/consumer usage
• Iterator-based read/write APIs alongside the lower-level slice APIs for ergonomic common-case usage

Common Use Cases

• Passing audio samples between a real-time audio callback thread and a non-real-time processing/UI thread
• Implementing a lock-free work queue between exactly one producer and one consumer thread in a latency-sensitive service
• Buffering data in embedded/no_std firmware where heap allocation and OS-level locks are unavailable or unwanted
• Building async producer/consumer pipelines via the async-ringbuf wrapper for Tokio-based applications

Under The Hood

Architecture: The core is a rb/storage.rs module implementing a contiguous ring buffer over raw storage with atomic head/tail indices (via crossbeam-utils cache-padded atomics), exposed through split Producer/Consumer wrapper types (src/wrap/) that enforce the single-writer/single-reader invariant at the type level rather than at runtime; traits/ defines shared read/write/observer traits implemented consistently across the blocking and async sibling crates in the same Cargo workspace. Tech Stack: no_std-first Rust using crossbeam-utils for padded atomics and optional portable-atomic/portable-atomic-util for platforms lacking native atomic support, structured as a Cargo workspace with async and blocking member crates layered on the core ringbuf crate. Code Quality: src/tests/ has an unusually thorough per-behavior test suite (access, drop semantics, overwrite, skip, zero-sized types, unsized types, iterator behavior, formatted-write support) plus a benchmarks module for performance regression tracking; the crate targets both alloc and pure no_std configurations, testing both paths. API Design: The producer/consumer split is enforced by Rust’s ownership system (moving each half to its owning thread), which prevents accidental shared-mutable-access bugs at compile time rather than via runtime checks, while iterator-based methods keep common read/write patterns concise despite the underlying lock-free complexity.