pub struct SharedBroadcastRing { /* private fields */ }Implementations§
Sourcepub fn create(
path: impl AsRef<Path>,
capacity: usize,
) -> Result<Self, BroadcastError>
pub fn create( path: impl AsRef<Path>, capacity: usize, ) -> Result<Self, BroadcastError>
File-backed broadcast ring; cross-process visibility via the OS
page cache. Obtains the ring at path: it initializes an empty
one only when the path does not yet exist, and otherwise
attaches with published slots and versions intact. A region
built with a different capacity is a LayoutMismatch.
reset reinitializes.
Sourcepub fn reset(
path: impl AsRef<Path>,
capacity: usize,
) -> Result<Self, BroadcastError>
pub fn reset( path: impl AsRef<Path>, capacity: usize, ) -> Result<Self, BroadcastError>
Truncate the ring at path and initialize an empty one,
discarding every published slot live peers share. For a caller
that knows it owns the path.
Sourcepub fn create_anon(capacity: usize) -> Result<Self, BroadcastError>
pub fn create_anon(capacity: usize) -> Result<Self, BroadcastError>
Anonymous in-process broadcast ring. Fastest construction; skips file create + ftruncate + first-page-fault. In-process only - subscribers in other processes cannot connect.
Sourcepub fn open(
path: impl AsRef<Path>,
expected_capacity: usize,
) -> Result<Self, BroadcastError>
pub fn open( path: impl AsRef<Path>, expected_capacity: usize, ) -> Result<Self, BroadcastError>
Open an existing file-backed broadcast ring. Validates magic + capacity.
Sourcepub fn create_from_shm(
shm: ShmFile,
capacity: usize,
) -> Result<Self, BroadcastError>
pub fn create_from_shm( shm: ShmFile, capacity: usize, ) -> Result<Self, BroadcastError>
Build a fresh broadcast 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
broadcast_file_size(capacity) bytes.
Sourcepub fn open_from_shm(
shm: ShmFile,
expected_capacity: usize,
) -> Result<Self, BroadcastError>
pub fn open_from_shm( shm: ShmFile, expected_capacity: usize, ) -> Result<Self, BroadcastError>
Open an existing named ShmFs-backed broadcast ring.
Validates magic + capacity. Does NOT re-initialise the
layout - the layout must already be present from a prior
create_from_shm on the same logical name.
pub fn capacity(&self) -> usize
Sourcepub fn register_consumer(&self) -> Result<usize, BroadcastError>
pub fn register_consumer(&self) -> Result<usize, BroadcastError>
Register as a consumer. Returns a consumer index in
0..MAX_CONSUMERS; that index is used for all subsequent
recv calls. Initialises the consumer’s cursor to the current
producer_seq (consumer starts reading from “now,” not history).
Sourcepub fn unregister_consumer(&self, consumer_idx: usize)
pub fn unregister_consumer(&self, consumer_idx: usize)
Unregister a consumer. After this, the producer no longer waits for this cursor when reclaiming slots.
Sourcepub fn try_push(&self, payload: &[u8]) -> Result<(), BroadcastError>
pub fn try_push(&self, payload: &[u8]) -> Result<(), BroadcastError>
Push a message. Returns Err(Full) when at least one active
consumer hasn’t yet read a previous slot we’d overwrite.
Sourcepub fn try_recv(
&self,
consumer_idx: usize,
out: &mut [u8],
) -> Result<usize, BroadcastError>
pub fn try_recv( &self, consumer_idx: usize, out: &mut [u8], ) -> Result<usize, BroadcastError>
Receive the next unread message for consumer_idx. Returns
the number of bytes filled (always BROADCAST_PAYLOAD_BYTES;
caller knows the inner-event size from its T contract).
Sourcepub fn lag(&self, consumer_idx: usize) -> u64
pub fn lag(&self, consumer_idx: usize) -> u64
Number of messages this consumer has not yet read.
Sourcepub fn producer_position(&self) -> u64
pub fn producer_position(&self) -> u64
Current producer cursor (total messages pushed since creation).
Sourcepub fn active_consumer_count(&self) -> usize
pub fn active_consumer_count(&self) -> usize
Number of currently active consumers.
pub fn flush(&self) -> Result<(), BroadcastError>
Sourcepub fn flush_async(&self) -> Result<(), BroadcastError>
pub fn flush_async(&self) -> Result<(), BroadcastError>
Non-blocking flush: schedules a writeback via the OS. Note: Windows is only partially async (sync to page cache, not to disk).
Sourcepub fn is_fully_drained(&self) -> bool
pub fn is_fully_drained(&self) -> bool
Whether every currently-active consumer has read every item the producer has published. Used by the capacity-morph wrapper to decide whether a stale broadcast backing can be dropped (all subscribers have caught up to the frozen producer position).