Trait HandlerFunctions 

pub trait HandlerFunctions {
    // Required methods
    fn base_ptr(&self) -> *const u8;
    fn matrix(&self) -> &AtomicMatrix;
    fn first_block_offset(&self) -> u32;
    fn segment_size(&self) -> u32;

    // Provided methods
    fn allocate<T>(&self) -> Result<Block<T>, HandlerError> { ... }
    fn allocate_raw(&self, size: u32) -> Result<RelativePtr<u8>, HandlerError> { ... }
    unsafe fn write<T>(&self, block: &mut Block<T>, value: T) { ... }
    unsafe fn read<'a, T>(&self, block: &Block<T>) -> &'a T { ... }
    unsafe fn read_mut<'a, T>(&self, block: &Block<T>) -> &'a mut T { ... }
    fn free<T>(&self, block: Block<T>) { ... }
    fn free_at(&self, header_offset: u32) { ... }
    fn set_state<T>(
        &self,
        block: &Block<T>,
        state: u32,
    ) -> Result<(), HandlerError> { ... }
    fn get_state<T>(&self, block: &Block<T>, order: Ordering) -> u32 { ... }
    fn transition_state<T>(
        &self,
        block: &Block<T>,
        expected: u32,
        next: u32,
        success_order: Ordering,
    ) -> Result<u32, HandlerError> { ... }
    fn raw_matrix(&self) -> &AtomicMatrix { ... }
    fn raw_base_ptr(&self) -> *const u8 { ... }
}

Defines the core interaction surface for any matrix handle.

Implemented by both MatrixHandler and SharedHandler. All matrix operations — allocation, I/O, lifecycle management, and escape hatches — are provided through this trait so that framework code in internals can operate generically over either handle type via impl HandlerFunctions.

Implementing this trait

Implementors must provide four primitive accessors:

• [base_ptr()] — the SHM base pointer for this process’s mapping
• [matrix()] — reference to the underlying AtomicMatrix
• [first_block_offset()] — offset of the first data block in the segment
• [segment_size()] — total segment size in bytes

All other methods have default implementations built on these four.

Required Methods

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.

Provided Methods

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

Allocates a block sized to hold T.

Size is computed from size_of::<T>() and rounded up to the 16-byte minimum payload if necessary. The matrix remains typeless — type information exists only in the returned Block<T>.

Errors

Returns HandlerError::AllocationFailed if the matrix is out of memory or under contention after 512 retries.

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

Allocates a raw byte block of the given size.

Returns a RelativePtr<u8> directly — use when the payload type is not known at allocation time, or when building internals framework primitives that operate on raw offsets. The caller is responsible for all casting and interpretation of the memory.

Errors

Returns HandlerError::AllocationFailed if OOM or contention.

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

Writes a value of type T into an allocated block.

Safety

• block must be in STATE_ALLOCATED.
• block must have been allocated with sufficient size to hold T. This is guaranteed if the block was produced by [allocate::<T>()].
• No other thread may be reading or writing this block concurrently. The caller is responsible for all synchronization beyond the atomic state transitions provided by [set_state] and [transition_state].

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

Reads a shared reference to T from an allocated block.

Safety

• block must be in STATE_ALLOCATED.
• A value of type T must have been previously written via write.
• The returned reference is valid as long as the SHM mapping is alive and the block has not been freed. It is not tied to the lifetime of the Block<T> handle — the caller must ensure the block is not freed while the reference is in use.
• No other thread may be writing to this block concurrently.

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

Reads a mutable reference to T from an allocated block.

Safety

• block must be in STATE_ALLOCATED.
• A value of type T must have been previously written via write.
• The returned reference is valid as long as the SHM mapping is alive and the block has not been freed. It is not tied to the lifetime of the Block<T> handle — the caller must ensure the block is not freed while the reference is in use.
• No other thread may be reading or writing this block concurrently. Two simultaneous read_mut calls on the same block is undefined behaviour.

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

Frees a typed block.

Marks the block STATE_ACKED and immediately triggers coalescing. The block is invalid after this call — using it in any way is undefined behaviour.

fn free_at(&self, header_offset: u32)

Frees a block by its header offset directly.

Used by internals framework code that operates on raw offsets rather than typed Block<T> handles. header_offset must point to a valid BlockHeader within the segment.

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

Sets a user-defined lifecycle state on a block.

The state must be >= USER_STATE_MIN (49). Attempting to set an internal state (0–48) returns HandlerError::ReservedStatus.

User states are invisible to the coalescing engine — a block in any user state will never be automatically reclaimed. Call [free] explicitly when the lifecycle is complete.

Errors

Returns HandlerError::ReservedStatus if state < USER_STATE_MIN.

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

Returns the current state of a block.

order controls the memory ordering of the atomic load. Use Ordering::Acquire for the general case. Use Ordering::Relaxed only if you do not need to synchronize with writes to the block’s payload.

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.

Succeeds only if the block is currently in expected. next must be >= USER_STATE_MIN — transitioning into an internal state is not permitted.

success_order controls the memory ordering on success. Use Ordering::AcqRel for the general case. The failure ordering is always Ordering::Relaxed.

Returns Ok(expected) on success — the value that was replaced.

Errors

• HandlerError::ReservedStatus if next < USER_STATE_MIN.
• [HandlerError::TransitionFailed(actual)] if the block was not in expected — actual is the state that was observed instead.

fn raw_matrix(&self) -> &AtomicMatrix

Returns a raw reference to the underlying AtomicMatrix.

For internals framework authors who need allocator primitives directly. Bypasses all handler abstractions — use with care.

fn raw_base_ptr(&self) -> *const u8

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

Use alongside [raw_matrix()] when building internals that need direct access to block memory beyond what the typed API provides.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl HandlerFunctions for MatrixHandler

impl HandlerFunctions for SharedHandler