Struct RingQueue 

pub struct RingQueue { /* private fields */ }

A bounded Multi-Producer Multi-Consumer (MPMC) queue utilizing a fixed-size ring buffer.

The implementation employs a sequence-based synchronization gate to coordinate access between threads, ensuring that producers and consumers only operate on slots that have been released by the previous “lap” of the buffer.

Memory and Hardware Considerations Cache Isolation: head, tail, and len cursors are isolated using CachePadded to mitigate false sharing and L1 cache-line contention between concurrent threads.

Memory Layout: Uses #[repr(C)] for a predictable field order, aiding hardware pre-fetchers.

Portability: Uses 64-bit atomics for cross-platform compatibility, including ARMv8 architectures where 128-bit atomic operations may not be natively supported.

Implementations

impl RingQueue

pub fn new(capacity: usize) -> Self

Creates a new queue with a capacity rounded up to the nearest power of two.

Each slot is initialized with a sequence number that permits the first lap of production.

pub fn push(&self, value: u64, context: &ThreadContext) -> Result<(), u64>

Attempts to push a value into the buffer.

Returns Ok(()) if successful, or Err(u64) containing the value if the buffer is full.

Synchronization

1. Loads the slot sequence with Acquire ordering to observe the last consumer’s release.
2. Claims a slot via compare_exchange on the tail cursor.
3. Updates the slot value and publishes it by incrementing the sequence with Release ordering.

pub fn pop(&self, context: &ThreadContext) -> Option<u64>

Attempts to pop a value from the buffer.

Returns Some(u64) if data is available, or None if the buffer is empty.

Synchronization

1. Validates that the sequence number matches the expected head lap.
2. Claims the index via compare_exchange on the head cursor.
3. Loads the value and resets the slot sequence to signal readiness to future producers (lap + capacity).