Struct SpscQueue 

pub struct SpscQueue {
    buffer: Vec<UnsafeCell<Option<MessageEnvelope>>>,
    capacity: usize,
    mask: usize,
    head: CachePadded<AtomicU64>,
    tail: CachePadded<AtomicU64>,
    producer_stats: CachePadded<ProducerStats>,
    consumer_stats: CachePadded<ConsumerStats>,
}

Single-producer single-consumer lock-free ring buffer.

This implementation is truly lock-free: no mutexes, no blocking. It uses atomic head/tail pointers with acquire/release ordering. Since SPSC has exactly one producer and one consumer, no CAS is needed — ordered loads and stores are sufficient.

Memory Ordering

• Producer: writes data, then Release-stores head (publishes the write)
• Consumer: Acquire-loads head (observes the write), reads data, then Release-stores tail
• This matches the GPU-side H2K/K2H queue protocol (volatile + fence)

Fields

buffer: Vec<UnsafeCell<Option<MessageEnvelope>>>

Ring buffer storage. UnsafeCell for interior mutability without Mutex. Each slot holds an Option.

capacity: usize

Capacity (power of 2).

mask: usize

Mask for index wrapping (capacity - 1).

head: CachePadded<AtomicU64>

Head pointer (producer writes here, only modified by producer). Cache-line padded to avoid false sharing with tail.

tail: CachePadded<AtomicU64>

Tail pointer (consumer reads from here, only modified by consumer). Cache-line padded to avoid false sharing with head and stats.

producer_stats: CachePadded<ProducerStats>

Producer-side counters (enqueued / dropped / max_depth). Separate cache line from consumer stats so the two sides do not false-share.

consumer_stats: CachePadded<ConsumerStats>

Consumer-side counters (dequeued).

Implementations

impl SpscQueue

pub fn new(capacity: usize) -> Self

Create a new queue with the given capacity.

Capacity will be rounded up to the next power of 2.

fn depth(&self) -> u64

Get current depth.

fn update_max_depth(&self)

Update max depth statistic. Single producer means no contention on max_depth — we use fetch_max which is a single atomic RMW rather than the earlier CAS loop.

Trait Implementations

impl MessageQueue for SpscQueue

fn capacity(&self) -> usize

Get the queue capacity.

fn len(&self) -> usize

Get current queue size.

fn try_enqueue(&self, envelope: MessageEnvelope) -> Result<()>

Try to enqueue a message envelope.

fn try_dequeue(&self) -> Result<MessageEnvelope>

Try to dequeue a message envelope.

fn stats(&self) -> QueueStats

Get queue statistics.

fn reset_stats(&self)

Reset queue statistics.

fn is_empty(&self) -> bool

Check if queue is empty.

fn is_full(&self) -> bool

Check if queue is full.

impl Send for SpscQueue

impl Sync for SpscQueue