pub struct SpscRingCore { /* private fields */ }Expand description
Lamport SPSC ring core. Used as the storage backing
SharedRingSpsc; applications normally
reach for the typed Producer / Consumer halves rather than
this raw core.
Implementations§
Source§impl SpscRingCore
impl SpscRingCore
Sourcepub fn create_anon(capacity: usize) -> Result<Self, RingError>
pub fn create_anon(capacity: usize) -> Result<Self, RingError>
Anonymous in-memory ring (in-process only). Fastest construction; skips file create + ftruncate + first-page-fault.
Sourcepub fn create(
path: impl AsRef<Path>,
capacity: usize,
) -> Result<Self, RingError>
pub fn create( path: impl AsRef<Path>, capacity: usize, ) -> Result<Self, RingError>
File-backed ring; cross-process visibility via the OS page cache.
Obtains the ring at path: initializes an empty one if the path
does not yet exist and attaches to it if it does. Attaching
leaves queued items and both cursors in place; a ring built with
a different capacity is a LayoutMismatch.
reset reinitializes.
Sourcepub fn reset(path: impl AsRef<Path>, capacity: usize) -> Result<Self, RingError>
pub fn reset(path: impl AsRef<Path>, capacity: usize) -> Result<Self, RingError>
Truncate the ring at path and initialize an empty one,
discarding queued items live peers hold. For a caller that
knows it owns the path.
Sourcepub fn open(
path: impl AsRef<Path>,
expected_capacity: usize,
) -> Result<Self, RingError>
pub fn open( path: impl AsRef<Path>, expected_capacity: usize, ) -> Result<Self, RingError>
Open an existing file-backed ring. Validates magic + capacity.
Sourcepub fn create_from_shm(shm: ShmFile, capacity: usize) -> Result<Self, RingError>
pub fn create_from_shm(shm: ShmFile, capacity: usize) -> Result<Self, RingError>
Build a fresh ring on top of a named RAM-resident
shared-memory backing. Cross-process visible via the
logical_name of the underlying ShmFile; never touches the
page cache. The ShmFile must be sized to at least
spsc_ring_file_size(capacity) bytes.
Sourcepub fn open_from_shm(
shm: ShmFile,
expected_capacity: usize,
) -> Result<Self, RingError>
pub fn open_from_shm( shm: ShmFile, expected_capacity: usize, ) -> Result<Self, RingError>
Open an existing named ShmFs-backed ring. Validates magic +
capacity. Does NOT re-initialize the layout - the layout must
already be present from a prior create_from_shm on the same
logical name.
Sourcepub fn create_in_region<R: RegionOwner>(
region: R,
capacity: usize,
) -> Result<Self, RingError>
pub fn create_in_region<R: RegionOwner>( region: R, capacity: usize, ) -> Result<Self, RingError>
Build a fresh ring laid out in caller-owned memory (huge / large
pages, or any RegionOwner). The region must be at least
spsc_ring_file_size(capacity) bytes; the ring owns it for its
lifetime so the pages stay mapped.
Sourcepub fn open_in_region<R: RegionOwner>(
region: R,
expected_capacity: usize,
) -> Result<Self, RingError>
pub fn open_in_region<R: RegionOwner>( region: R, expected_capacity: usize, ) -> Result<Self, RingError>
Attach to an existing ring already laid out in region - e.g. a
LargePageSection another process created under the same name.
Validates the header and does NOT re-initialise.
Sourcepub fn head_signal(&self) -> &AtomicU64
pub fn head_signal(&self) -> &AtomicU64
The producer’s publish signal: the head counter the consumer-side monitor-wait arms on. The producer’s Release-store to this atom on every push is the wake.
Sourcepub fn approx_len(&self) -> usize
pub fn approx_len(&self) -> usize
Number of items waiting (head - tail).
Sourcepub fn try_push(&self, payload: &[u8]) -> Result<(), RingError>
pub fn try_push(&self, payload: &[u8]) -> Result<(), RingError>
SPSC push. Caller is the sole producer (enforced by the
Producer newtype that owns this ring via Arc). Lamport
pattern: read tail to check fullness, write payload, Release-
store head to publish.
Sourcepub fn try_pop(&self, out: &mut [u8]) -> Result<usize, RingError>
pub fn try_pop(&self, out: &mut [u8]) -> Result<usize, RingError>
SPSC pop. Caller is the sole consumer. Lamport pattern: read head to check emptiness, read payload, Release-store tail to free the slot.
Sourcepub fn peek_slot(&self) -> Option<PeekedSlot<'_>>
pub fn peek_slot(&self) -> Option<PeekedSlot<'_>>
Peek the next slot WITHOUT copying or releasing it. Returns
a PeekedSlot guard that derefs to &[u8] pointing
directly into the mapped region. Caller passes this slice to
downstream consumers (e.g. quinn’s SendStream::write_all)
without an intermediate copy. When done, call
PeekedSlot::confirm to advance the consumer position and
release the slot. Drop without confirming leaves the slot
in place; the next peek_slot returns it again.
Returns None when the ring is empty. Caller is the sole
consumer.