Module spsc 

Single-producer single-consumer bounded queue.

A lock-free ring buffer optimized for exactly one producer thread and one consumer thread. Uses cached indices to minimize atomic operations on the hot path.

Design

┌─────────────────────────────────────────────────────────────┐
│ Shared (Arc):                                               │
│   tail: CachePadded<AtomicUsize>   ← Producer writes        │
│   head: CachePadded<AtomicUsize>   ← Consumer writes        │
│   buffer: *mut T                                            │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────┐     ┌─────────────────────┐
│ Producer:           │     │ Consumer:           │
│   local_tail        │     │   local_head        │
│   cached_head       │     │   cached_tail       │
│   buffer (cached)   │     │   buffer (cached)   │
│   mask (cached)     │     │   mask (cached)     │
└─────────────────────┘     └─────────────────────┘

Producer and consumer each cache the buffer pointer and mask locally to avoid Arc dereference on every operation. They also maintain a cached copy of the other’s index, only refreshing from the atomic when the cache indicates the queue is full (producer) or empty (consumer).

Head and tail are on separate cache lines (128-byte padding) to avoid false sharing between producer and consumer threads.

Example

use nexus_queue::spsc;

let (mut tx, mut rx) = spsc::ring_buffer::<u64>(1024);

tx.push(42).unwrap();
assert_eq!(rx.pop(), Some(42));

Structs

Consumer

The consumer endpoint of an SPSC queue.

Producer

The producer endpoint of an SPSC queue.

Functions

ring_buffer

Creates a bounded SPSC ring buffer with the given capacity.