Struct SpscQueue 

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

Cache-aligned, lock-free single-producer/single-consumer ring buffer.

Fixed power-of-two capacity. See the module-level comment above for why head/tail are each cache-line-aligned separately instead of aligning the whole struct.

Implementations

impl<T> SpscQueue<T>

pub fn new(capacity: usize) -> Self

Build an empty queue. capacity must be a power of two.

Panics

Panics if capacity is not a power of two.

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

Single-producer push. Returns Err(value) (handing the value back) if the queue is full — never blocks.

Errors

Returns Err(value), handing the value straight back to the caller, if the ring buffer is currently full (tail - head has reached capacity). This is not a fault — it is the normal backpressure signal for a bounded SPSC queue; the caller decides whether to retry, drop the value, or apply its own backoff.

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

Single-consumer pop. Returns None if the queue is empty.

pub fn is_empty(&self) -> bool

Whether the queue currently has no elements.

pub fn is_full(&self) -> bool

Whether the queue is currently at capacity (the next Self::push would be rejected).

pub fn len(&self) -> usize

Number of elements currently queued.

pub const fn capacity(&self) -> usize

The fixed capacity this queue was constructed with.

impl<T: Copy> SpscQueue<T>

pub fn push_slice(&self, src: &[T]) -> usize

Single-producer bulk push: copy as many elements from src as fit into the ring, returning the count actually pushed (0 if full).

This is the bulk analogue of push and exists purely as a hot-path optimization for T: Copy element types (e.g. the byte pipe in stream::native): pushing a run of N bytes one push call at a time pays N separate atomic load/store pairs and N bounds-checked writes, whereas this issues at most two copy_nonoverlapping runs (the ring may wrap once) and a single tail store. Behaviour is otherwise identical — same capacity accounting, same Release publication of the new tail.

pub fn pop_slice(&self, dst: &mut [T]) -> usize

Single-consumer bulk pop: copy up to dst.len() queued elements into dst, returning the count actually popped (0 if empty).

Bulk analogue of pop; see push_slice for the rationale.

Trait Implementations

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

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