Struct LockFreeRing 

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

Lock-free SPSC ring buffer.

This ring buffer is designed for Single-Producer Single-Consumer scenarios, where one thread enqueues items and another dequeues them. It uses atomic operations for synchronization without any locks.

Performance

• Enqueue: O(1) amortized
• Dequeue: O(1) amortized
• Batch operations amortize atomic overhead

Cache Optimization

• Head and tail indices are cache-line padded to prevent false sharing
• Buffer capacity is always a power of 2 for fast modulo via bitwise AND

Implementations

impl<T> LockFreeRing<T>

pub fn new(capacity: usize) -> Self

Creates a new ring buffer with the specified capacity.

The actual capacity will be rounded up to the next power of 2.

Panics

Panics if capacity is 0 or allocation fails.

pub fn with_default_capacity() -> Self

Creates a ring buffer with the default capacity.

pub const fn capacity(&self) -> usize

Returns the ring capacity.

pub fn len(&self) -> usize

Returns the number of items currently in the ring.

pub fn is_empty(&self) -> bool

Returns true if the ring is empty.

pub fn is_full(&self) -> bool

Returns true if the ring is full.

pub fn free_slots(&self) -> usize

Returns the number of free slots.

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

Enqueues a single item.

Returns Err(item) if the ring is full.

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

Dequeues a single item.

Returns None if the ring is empty.

pub fn enqueue_batch(&self, items: &[T]) -> usize

where T: Copy,

Enqueues multiple items in a batch.

Returns the number of items successfully enqueued. Items that couldn’t be enqueued remain in the slice.

pub fn dequeue_batch(&self, out: &mut [T]) -> usize

where T: Copy,

Dequeues multiple items in a batch.

Returns the number of items dequeued.

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

Peeks at the next item to be dequeued without removing it.

Safety

The returned reference is only valid until the next dequeue operation.

pub unsafe fn clear(&self)

Clears all items from the ring.

Safety

This should only be called when no concurrent operations are in progress.

Trait Implementations

impl<T> Debug for LockFreeRing<T>

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

Formats the value using the given formatter.

impl<T> Drop for LockFreeRing<T>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<T: Send> Send for LockFreeRing<T>

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