Struct RingBuffer 

pub struct RingBuffer<T> { /* private fields */ }

A lock-free ring buffer with runtime-specified capacity.

This buffer supports both SPSC and MPSC modes:

• SPSC: Single producer uses push, single consumer uses pop
• MPSC: Multiple producers use claim_and_write, single consumer uses pop

Safety

The buffer is safe to use from multiple threads as long as:

• In SPSC mode: Exactly one producer and one consumer thread
• In MPSC mode: Any number of producers, exactly one consumer thread

Implementations

impl<T> RingBuffer<T>

pub fn new(capacity: usize) -> Self

Creates a new ring buffer with the given capacity.

The capacity will be clamped to [MIN_BUFFER_SIZE, MAX_BUFFER_SIZE] and rounded up to the next power of 2 for efficiency.

Panics

Panics if capacity is 0.

pub fn capacity(&self) -> usize

Returns the capacity of the buffer.

pub fn is_empty(&self) -> bool

Returns true if the buffer is empty.

Note: This is a snapshot and may change immediately after returning. Uses Relaxed ordering since this is an approximate query.

pub fn is_full(&self) -> bool

Returns true if the buffer is full.

Note: This is a snapshot and may change immediately after returning. Uses Relaxed ordering since this is an approximate query.

pub fn len(&self) -> usize

Returns the current number of items in the buffer.

Note: This is a snapshot and may change immediately after returning. Uses Relaxed ordering since this is an approximate query.

pub fn free_slots(&self) -> usize

Returns the number of free slots in the buffer.

Note: This is a snapshot and may change immediately after returning.

pub fn push(&self, item: T) -> Result<(), T>

Pushes an item to the buffer (SPSC mode).

Returns Ok(()) if successful, or Err(item) if the buffer is full.

Errors

Returns the item back if the buffer is full.

Safety

In SPSC mode, this must only be called by the single producer thread.

pub fn pop(&self) -> Option<T>

Pops an item from the buffer.

Returns Some(item) if successful, or None if the buffer is empty.

Safety

This must only be called by the single consumer thread.

pub fn peek(&self) -> Option<&T>

Peeks at the next item without removing it.

Returns None if the buffer is empty.

Safety

This must only be called by the single consumer thread.

pub fn claim_slot(&self) -> Option<usize>

Claims a slot for writing (MPSC mode).

Returns the slot index if successful, or None if the buffer is full. The caller must then write to the slot and call publish_slot.

This uses atomic increment on claim_counter to ensure each producer gets a unique slot.

pub unsafe fn write_slot(&self, slot: usize, item: T)

Writes to a claimed slot (MPSC mode).

Safety

The slot must have been obtained from claim_slot and not yet written to. After calling this, you must call try_publish to make the item visible.

pub fn try_advance_tail(&self, target_tail: usize) -> bool

Attempts to publish written slots up to the given claim (MPSC mode).

This advances the tail if all slots up to claim have been written. Returns true if the tail was advanced.

In MPSC mode, producers write out-of-order but the consumer sees items in order. This function is typically called by each producer after writing, but only succeeds when all prior slots are also written.

For simplicity, this implementation uses a “publish barrier” approach: producers write to their slots, then the tail is advanced by whichever producer happens to have the lowest claimed slot.

pub fn push_batch(&self, items: impl IntoIterator<Item = T>) -> usize

Pushes multiple items to the buffer.

Returns the number of items successfully pushed.

Safety

In SPSC mode, this must only be called by the single producer thread.

pub fn pop_batch(&self, max_count: usize) -> Vec<T>

Pops multiple items from the buffer.

Returns a vector of up to max_count items.

Safety

This must only be called by the single consumer thread.

Performance Warning

This method allocates a Vec on every call. Do not use on hot paths where allocation overhead matters. For zero-allocation consumption, use pop_each or pop_batch_into.

pub fn pop_each<F>(&self, max_count: usize, f: F) -> usize

where F: FnMut(T) -> bool,

Pops items and calls a callback for each (zero-allocation).

Processing stops when:

• max_count items have been processed
• The buffer becomes empty
• The callback returns false

Returns the number of items processed.

Safety

This must only be called by the single consumer thread.

pub fn pop_batch_into(&self, buffer: &mut [MaybeUninit<T>]) -> usize

Pops items into a caller-provided buffer (zero-allocation).

Returns the number of items popped.

Safety

This must only be called by the single consumer thread. After this method returns n, the first n elements of buffer are initialized.

pub fn reset(&mut self)

Resets the buffer to empty state.

Safety

This must only be called when no other threads are accessing the buffer.

Trait Implementations

impl<T: Debug> Debug for RingBuffer<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Drop for RingBuffer<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: Send> Send for RingBuffer<T>

impl<T: Send> Sync for RingBuffer<T>