Struct MatrixHandler 

pub struct MatrixHandler { /* private fields */ }

The primary interface for interacting with an AtomicMatrix.

Owns the SHM mapping. Cannot be cloned — use [share()] to produce a SharedHandler for other threads.

See module documentation for the full abstraction layer diagram.

Implementations

impl MatrixHandler

pub fn share(&self) -> SharedHandler

Produces a lightweight SharedHandler that can be sent to other threads.

SharedHandler holds raw pointers into the SHM segment. This handler must outlive all shared handles derived from it — Rust cannot enforce this lifetime relationship automatically because SharedHandler uses raw pointers. Violating this contract is undefined behaviour.

pub fn die(&self) -> Result<(), HandlerError>

Removes the SHM file from the system.

Should be called before the application exits to prevent the SHM file from persisting in /dev/shm/ across runs. This is an explicit, opt- in cleanup - if omitted, the file survives until the system reboots or it’s manually removed.

Existing mapping remains valid until the handlers are dropped; this only removes the filesystem entry, preventing new attachments.

Trait Implementations

impl HandlerFunctions for MatrixHandler

fn base_ptr(&self) -> *const u8

Returns the SHM base pointer for this process’s mapping.

fn matrix(&self) -> &AtomicMatrix

Returns a reference to the underlying AtomicMatrix.

fn first_block_offset(&self) -> u32

Returns the offset of the first data block in the segment. Used by internals iterators as the physical chain walk start point.

fn segment_size(&self) -> u32

Returns the total segment size in bytes.

fn allocate<T>(&self) -> Result<Block<T>, HandlerError>

Allocates a block sized to hold T.

fn allocate_raw(&self, size: u32) -> Result<RelativePtr<u8>, HandlerError>

Allocates a raw byte block of the given size.

unsafe fn write<T>(&self, block: &mut Block<T>, value: T)

Writes a value of type T into an allocated block.

unsafe fn read<'a, T>(&self, block: &Block<T>) -> &'a T

Reads a shared reference to T from an allocated block.

unsafe fn read_mut<'a, T>(&self, block: &Block<T>) -> &'a mut T

Reads a mutable reference to T from an allocated block.

fn free<T>(&self, block: Block<T>)

Frees a typed block.

fn free_at(&self, header_offset: u32)

Frees a block by its header offset directly.

fn set_state<T>(&self, block: &Block<T>, state: u32) -> Result<(), HandlerError>

Sets a user-defined lifecycle state on a block.

fn get_state<T>(&self, block: &Block<T>, order: Ordering) -> u32

Returns the current state of a block.

fn transition_state<T>( &self, block: &Block<T>, expected: u32, next: u32, success_order: Ordering, ) -> Result<u32, HandlerError>

Atomically transitions a block from one state to another.

fn raw_matrix(&self) -> &AtomicMatrix

Returns a raw reference to the underlying AtomicMatrix.

fn raw_base_ptr(&self) -> *const u8

Returns the raw SHM base pointer for this process’s mapping.