Struct LockFreeQueue 

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

A bounded, genuinely lock-free multi-producer multi-consumer queue.

This is an array-based MPMC queue using per-slot sequence numbers (the Vyukov algorithm). Producers and consumers operate through independent atomic head/tail cursors and never acquire a mutex or spinlock. The sequence-number protocol eliminates the ABA problem without tagged pointers or epoch-based reclamation: slots are reused in place, so no node allocation or deallocation occurs during enqueue/dequeue.

Capacity

The queue is bounded. LockFreeQueue::new creates a queue with DEFAULT_QUEUE_CAPACITY slots. LockFreeQueue::with_capacity allows a custom power-of-two capacity. When the queue is full, enqueue retries with exponential backoff (preserving the unblocked-sender contract of the previous API), while try_enqueue returns Err(item) immediately for callers that prefer explicit backpressure.

Memory safety

Each slot’s Option<T> is written by the producer (replacing None with Some(item)) and taken by the consumer (replacing Some(item) with None). The sequence-number protocol guarantees that only one thread accesses a slot’s data at a time: the producer writes between sequence == pos and sequence == pos+1, the consumer reads between sequence == pos+1 and sequence == pos+capacity.

Implementations

impl<T> LockFreeQueue<T>

pub fn new() -> Self

Create a new queue with the default capacity.

pub fn with_capacity(capacity: usize) -> Self

Create a new queue with a custom capacity (must be a power of 2).

Panics

Panics if capacity is 0 or not a power of 2.

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

Try to enqueue an item without blocking.

Returns Ok(()) if the item was enqueued, or Err(item) if the queue is full. This is the lock-free fast path: no spinlock, no mutex, no retry loop.

pub fn enqueue(&self, item: T)

Enqueue an item, retrying with exponential backoff if the queue is full.

This preserves the unblocked-sender contract of the previous API: the call always eventually succeeds (assuming consumers make progress). The backoff path uses core::hint::spin_loop and, on std targets, std::thread::yield_now after heavy contention, but never acquires a global lock, so multiple producers can enqueue concurrently.

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

Try to dequeue an item from the front of the queue. Returns None if the queue is empty.

This is the lock-free fast path: no spinlock, no mutex.

pub fn is_empty(&self) -> bool

Check if the queue is empty.

This is a best-effort check: the queue may have items added or removed between this call and the next operation. It is safe to call concurrently with enqueue/dequeue.

pub const fn capacity(&self) -> usize

Returns the queue capacity.

Trait Implementations

impl<T> Default for LockFreeQueue<T>

fn default() -> Self

Returns the “default value” for a type.

impl<T> Drop for LockFreeQueue<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 LockFreeQueue<T>

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