Trait SlotBackend 

pub trait SlotBackend: Send + Sync {
    // Required methods
    fn reserve_slot(
        &self,
        active_readers_mask: ReaderMask,
    ) -> Result<SlotHandle, SlotError>;
    fn commit_slot(
        &self,
        handle: SlotHandle,
        bytes: &[u8],
    ) -> Result<u32, SlotError>;
    fn discard_slot(&self, handle: SlotHandle) -> Result<(), SlotError>;
    fn read_slot(
        &self,
        handle: SlotHandle,
    ) -> Result<(SlotHeader, Vec<u8>), SlotError>;
    fn mark_read(
        &self,
        handle: SlotHandle,
        reader_index: u8,
    ) -> Result<(), SlotError>;
    fn mark_reader_disconnected(
        &self,
        reader_index: u8,
    ) -> Result<(), SlotError>;
    fn slot_count(&self) -> Result<usize, SlotError>;
    fn slot_total_size(&self) -> usize;
    fn slot_capacity(&self) -> usize;

    // Provided methods
    fn slot_data_ptr(
        &self,
        handle: SlotHandle,
    ) -> Result<(*mut u8, usize), SlotError> { ... }
    fn commit_in_place(
        &self,
        handle: SlotHandle,
        len: usize,
    ) -> Result<u32, SlotError> { ... }
    fn slot_read_ptr(
        &self,
        handle: SlotHandle,
    ) -> Result<(*const u8, usize), SlotError> { ... }
    fn next_unread_slot(
        &self,
        reader_index: u8,
    ) -> Result<Option<SlotHandle>, SlotError> { ... }
    fn type_hash(&self) -> Option<[u8; 16]> { ... }
    fn notify_generation(&self) -> u64 { ... }
    fn wait_for_change(&self, last: u64, timeout: Duration) { ... }
}

Backend trait for the SHM slot allocator.

Implementers:

• crate::InMemorySlotAllocator — in-memory backend, default for single-process tests and as the reference implementation.
• PosixSlotAllocator — POSIX shm_open + mmap, cross-process same-host (feature posix-mmap).
• Iceoryx2SlotAdapter — Iceoryx2 bridge (optional feature iceoryx2-bridge).

Required Methods

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.

Errors

NoFreeSlot when all slots are loaned or unfinished.

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.

Errors

OutOfBounds, SampleTooLarge, or lock poison.

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

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

Errors

OutOfBounds or lock poison.

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

Reads slot header + data bytes (copied).

Errors

OutOfBounds or lock poison.

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).

Errors

OutOfBounds or lock poison.

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

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

Errors

Lock poison.

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

Number of configured slots.

Errors

Lock poison.

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).

Provided Methods

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.

Errors

OutOfBounds if the handle is not a live loan, lock poison, or InPlaceUnsupported for backends without in-place support (default).

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.

Errors

SampleTooLarge, OutOfBounds, lock poison, or InPlaceUnsupported (default).

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.

Errors

OutOfBounds, lock poison, or 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).

Errors

Lock poison.

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.

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).

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl SlotBackend for InMemorySlotAllocator

Available on crate feature std only.

impl SlotBackend for PosixSlotAllocator