Struct PosixSlotAllocator 

pub struct PosixSlotAllocator { /* private fields */ }

POSIX mmap slot allocator. An owner process creates the segment; consumer processes attach via attach.

Implementations

impl PosixSlotAllocator

pub fn create<P: Into<PathBuf>>( flink_path: P, slot_count: usize, slot_capacity: usize, ) -> Result<Self, PosixSlotError>

Creates a new POSIX SHM segment as the owner.

flink_path is a file in the filesystem (typically /tmp/zerodds/<segment_id>.flink) that reveals the real OS segment name to the consumer.

Errors

Shm on a shm_open error; CapacityOverflow when slot_capacity > u32::MAX.

pub fn attach<P: Into<PathBuf>>(flink_path: P) -> Result<Self, PosixSlotError>

Attaches to an existing POSIX SHM segment via the flink path. The caller becomes a consumer (not an owner — Drop only unmaps, it does not shm_unlink).

Errors

Shm on an attach error; InvalidHeader when the magic/layout does not match.

pub fn flink_path(&self) -> &str

Path of the flink file (for discovery).

pub fn segment_path(&self) -> String

Returns the segment path as a string for the ShmLocator. This is what is stored in the PID_SHM_LOCATOR.

Trait Implementations

impl Send for PosixSlotAllocator

impl SlotBackend for PosixSlotAllocator

fn reserve_slot( &self, active_readers_mask: ReaderMask, ) -> Result<SlotHandle, SlotError>

Reserves a free slot. The caller then writes via commit_slot and thereby publishes the sample.

fn commit_slot( &self, handle: SlotHandle, bytes: &[u8], ) -> Result<u32, SlotError>

Writes the sample bytes into the slot and sets SlotHeader { sn, sample_size, reader_mask=0 }. Returns the SN.

fn discard_slot(&self, handle: SlotHandle) -> Result<(), SlotError>

Discards a loan without committing. The slot becomes free again.

fn slot_data_ptr( &self, handle: SlotHandle, ) -> Result<(*mut u8, usize), SlotError>

True zero-copy loan: returns a writable pointer + capacity into a currently reserved slot’s data region, so the caller can fill the sample in place (no staging copy) and then call Self::commit_in_place. The pointer is valid until that commit_in_place or a discard_slot for the same handle; the slot must have been obtained from Self::reserve_slot and not yet committed/discarded.

fn commit_in_place( &self, handle: SlotHandle, len: usize, ) -> Result<u32, SlotError>

Finalizes a slot whose len data bytes were already written in place via Self::slot_data_ptr — sets SlotHeader { sn, sample_size=len, reader_mask=0 } and releases the loan, with no data copy. Returns the SN. The byte-for-byte result is identical to commit_slot(handle, &buf[..len]), only without the staging copy.

fn slot_read_ptr( &self, handle: SlotHandle, ) -> Result<(*const u8, usize), SlotError>

Zero-copy read: returns a read-only pointer + sample length into a committed slot’s data region — the reader consumes in place without a copy (counterpart to Self::read_slot, which copies). The pointer is valid until the slot is recycled (i.e. until every active reader has mark_read it and the writer reserves it again); a same-host reader reads it, then calls Self::mark_read. Default: InPlaceUnsupported.

fn next_unread_slot( &self, reader_index: u8, ) -> Result<Option<SlotHandle>, SlotError>

Reader-side scan: returns the handle of the next committed slot (sample_size > 0) that reader_index has not yet mark_read. Used with Self::slot_read_ptr for an untyped zero-copy take, then Self::mark_read to release it. Returns Ok(None) when nothing new is pending. Default: Ok(None).

fn read_slot( &self, handle: SlotHandle, ) -> Result<(SlotHeader, Vec<u8>), SlotError>

Reads slot header + data bytes (copied).

fn mark_read( &self, handle: SlotHandle, reader_index: u8, ) -> Result<(), SlotError>

Sets the reader_index bit in the slot’s reader_mask (reader has read).

fn mark_reader_disconnected(&self, reader_index: u8) -> Result<(), SlotError>

Sets the reader_index bit retroactively on all slots (SPDP lease-expiry).

fn slot_count(&self) -> Result<usize, SlotError>

Number of configured slots.

fn slot_total_size(&self) -> usize

Total slot size (header + data + padding); for discovery.

fn slot_capacity(&self) -> usize

Data area per slot (without header, without padding).

fn notify_generation(&self) -> u64

Spec §4.2 event-driven notify — current change generation. Bumped on every commit_slot (new sample → wake readers) and slot-free (mark_read/discard_slot/… → wake writers). Capture this before checking a condition and pass it to Self::wait_for_change for a lost-wakeup-free wait. Default 0 for backends without notify support.

fn wait_for_change(&self, last: u64, timeout: Duration)

Spec §4.2 — blocks until the change generation differs from last or timeout elapses (event-driven, NO busy-poll). Default: returns immediately (a backend without notify support degrades to caller-driven polling). InMemorySlotAllocator uses a Condvar; PosixSlotAllocator uses a cross-process futex on a shared-memory word (Linux).

fn type_hash(&self) -> Option<[u8; 16]>

Spec §6.1: TYPE_HASH of the topic type, if known to the backend. None = the backend tracks no hash; the caller must verify another way (e.g. via discovery). Default: None.

impl Sync for PosixSlotAllocator