Struct LockFreeRing 

pub struct LockFreeRing {
    size: usize,
    frame_count: usize,
    frames: Vec<PhysFrame>,
    header: *mut RingHeader,
    slots: *mut RingSlot,
    capacity: u32,
    slot_size: u32,
}

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

SPSC guarantee

write must only be called from the producer thread; read must only be called from the consumer thread. No locks are used : only atomic loads/stores with acquire/release ordering.

For multi-queue NIC RSS, create one LockFreeRing per RSS queue rather than sharing a single MPSC ring; this avoids CAS contention and head-of-line blocking.

Fields

size: usize

Total size in bytes of the shared memory region.

frame_count: usize

Number of physical frames backing the ring.

frames: Vec<PhysFrame>

Physical frames.

header: *mut RingHeader

Virtual address of the header (first page).

slots: *mut RingSlot

Virtual address of the first slot (immediately after the header in the first page, or in subsequent pages when slots spill over).

capacity: u32

Number of slots (derived from capacity in the header).

slot_size: u32

Slot size in bytes.

Implementations

impl LockFreeRing

const DEFAULT_CAPACITY: u32 = 256

Default slot count (power of two).

pub fn new(slot_count: u32, slot_size: usize) -> Result<Arc<Self>, RingError>

Create a new ring with slot_count slots of slot_size bytes.

The ring is allocated from physically-contiguous DMA-accessible frames and zeroed. Returns an error if allocation fails.

pub fn capacity(&self) -> u32

The number of slots in this ring.

pub fn slot_size(&self) -> u32

The size in bytes of each slot.

pub fn frame_phys_addrs(&self) -> Vec<u64>

Physical addresses of the backing frames (for DMA and for mapping into other address spaces via capabilities).

pub fn write(&self, data: &[u8]) -> Result<(), RingError>

Write data into the ring. Returns Full if no slot is available, or MessageTooLarge if the data exceeds the slot capacity.

Ordering

1. Non-atomic copy into the slot (copy_nonoverlapping).
2. len.store(Release) : makes the length visible after data.
3. tail.store(Release) : publishes the slot.

On ARM/POWER the Release barrier on len prevents the consumer from seeing len != 0 before the data stores are visible.

pub fn read(&self, buf: &mut [u8]) -> Result<usize, RingError>

Read one message from the ring into buf.

Returns Empty if no message is available, or BufferTooSmall if the waiting message is larger than buf.

pub fn try_write(&self, data: &[u8]) -> Result<(), RingError>

Non-blocking write. Equivalent to write.

pub fn write_vectored(&self, bufs: &[&[u8]]) -> Result<(), RingError>

Write multiple buffers in a single slot (scatter-gather). Concatenates bufs and writes them as one message.

pub fn try_read(&self, buf: &mut [u8]) -> Result<Option<usize>, RingError>

Non-blocking read. Returns Ok(None) when the ring is empty.

pub fn notify_consumer_raw(&self)

Notify the consumer that new data is available (futex wake). Increments the consumer notification counter.

pub fn notify_producer_raw(&self)

Notify the producer that space has been freed (futex wake). Increments the producer notification counter.

pub fn has_data(&self) -> bool

Query whether the consumer should wake. Returns true if data is available (tail != head). Used after futex_wait returns.

pub fn has_space(&self) -> bool

Query whether the producer can write without blocking. Returns true if at least one slot is free.

pub fn dma_buffer(&self, slot_index: u32) -> DmaBuffer

Provide a DMA-accessible buffer descriptor for zero-copy NIC operation. The physical address points directly into the slot’s data area so the NIC can DMA into the ring without an intermediate copy.

fn head(&self) -> &AtomicU32

fn tail(&self) -> &AtomicU32

fn slot_at(&self, index: u32) -> *mut RingSlot

Trait Implementations

impl Debug for LockFreeRing

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for LockFreeRing

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 IpcConsumer for LockFreeRing

fn recv(&self, buf: &mut [u8]) -> Result<usize, IpcError>

Receive a message, blocking if the buffer is empty.

fn try_recv(&self, buf: &mut [u8]) -> Result<Option<usize>, IpcError>

Receive without blocking.

impl IpcNotification for LockFreeRing

fn notify_consumer(&self)

Notify the consumer that data is available.

fn notify_producer(&self)

Notify the producer that space is available.

fn wait_notification(&self) -> Result<(), IpcError>

Block until a notification arrives.

impl IpcProducer for LockFreeRing

fn send(&self, msg: &[u8]) -> Result<(), IpcError>

Send a message, blocking if the buffer is full.

fn try_send(&self, msg: &[u8]) -> Result<(), IpcError>

Send without blocking.

impl IpcTransport for LockFreeRing

fn level(&self) -> TransportLevel

The isolation level of this transport.

fn capabilities(&self) -> TransportCapabilities

Static capabilities of this transport.

fn name(&self) -> &'static str

Human-readable name for debugging / profiling.

impl Send for LockFreeRing

impl Sync for LockFreeRing