Trait MemoryManager 

pub trait MemoryManager<P: Payload>: HeaderStore {
    type ReadGuard<'a>: Deref<Target = Message<P>>
       where Self: 'a;
    type WriteGuard<'a>: DerefMut<Target = Message<P>>
       where Self: 'a;

    // Required methods
    fn store(&mut self, value: Message<P>) -> Result<MessageToken, MemoryError>;
    fn read(
        &self,
        token: MessageToken,
    ) -> Result<Self::ReadGuard<'_>, MemoryError>;
    fn read_mut(
        &mut self,
        token: MessageToken,
    ) -> Result<Self::WriteGuard<'_>, MemoryError>;
    fn free(&mut self, token: MessageToken) -> Result<(), MemoryError>;
    fn available(&self) -> usize;
    fn capacity(&self) -> usize;
    fn memory_class(&self) -> MemoryClass;
}

Typed storage interface for token-addressed messages.

A MemoryManager<P> owns stored Message<P> values and provides access to them through stable MessageToken handles.

The manager’s responsibilities are:

• storing new messages and returning tokens,
• resolving tokens to stored messages,
• providing immutable and mutable borrows of stored messages,
• freeing storage when a token is no longer live,
• reporting capacity and memory-class information.

The trait is parameterized by P, and a single manager instance stores only one concrete payload type.

Why P is a generic parameter

P is a generic parameter rather than an associated type so that a future implementation can provide MemoryManager<P> for multiple payload types via monomorphization without changing the external interface.

Borrow model

read and read_mut return guards rather than naked references.

This is necessary because:

• single-threaded managers should be able to return plain references with no additional runtime overhead;
• concurrent managers need the returned borrow to remain tied to a slot-level synchronization guard.

The associated guard types make both implementation strategies possible with one API.

Implementation notes

Typical implementations:

• static manager:
  • ReadGuard<'a> = &'a Message<P>
  • WriteGuard<'a> = &'a mut Message<P>
• heap manager:
  • ReadGuard<'a> = &'a Message<P>
  • WriteGuard<'a> = &'a mut Message<P>
• concurrent manager:
  • small wrapper types around slot-level read/write lock guards

Errors

Implementations should use MemoryError variants to report invalid tokens, unallocated slots, active borrows, poisoned synchronization primitives, or exhausted capacity.

Safety

The trait itself is fully safe. Any unsafe code needed by a specific implementation must remain internal to that implementation.

Required Associated Types

type ReadGuard<'a>: Deref<Target = Message<P>> where Self: 'a

Shared read guard returned by MemoryManager::read.

This guard dereferences to the stored Message<P>.

Typical implementations:

• &'a Message<P> for single-threaded managers;
• a wrapper around a slot-level read lock guard for concurrent managers.

type WriteGuard<'a>: DerefMut<Target = Message<P>> where Self: 'a

Exclusive mutable guard returned by MemoryManager::read_mut.

This guard dereferences mutably to the stored Message<P>.

Typical implementations:

• &'a mut Message<P> for single-threaded managers;
• a wrapper around a slot-level write lock guard for concurrent managers.

Required Methods

fn store(&mut self, value: Message<P>) -> Result<MessageToken, MemoryError>

Allocate storage for value and return its token.

The returned MessageToken becomes the stable handle used to refer to the stored message.

Errors

Returns:

• MemoryError::NoFreeSlots if the manager has no remaining capacity;
• MemoryError::Poisoned if a concurrent implementation cannot recover from a poisoned synchronization primitive during allocation.

fn read(&self, token: MessageToken) -> Result<Self::ReadGuard<'_>, MemoryError>

Borrow a stored message immutably.

This is the primary read path for manager-owned messages. The returned guard provides access to the stored message without copying it.

Errors

Returns:

• MemoryError::BadToken if token is invalid;
• MemoryError::NotAllocated if the slot is currently empty;
• MemoryError::AlreadyBorrowed if the implementation chooses to report an incompatible borrow state explicitly;
• MemoryError::Poisoned if a concurrent implementation encounters a poisoned synchronization primitive.

fn read_mut( &mut self, token: MessageToken, ) -> Result<Self::WriteGuard<'_>, MemoryError>

Borrow a stored message mutably.

This method provides exclusive mutable access to the stored message identified by token.

It is intended for in-place mutation of manager-owned messages.

Errors

Returns:

• MemoryError::BadToken if token is invalid;
• MemoryError::NotAllocated if the slot is currently empty;
• MemoryError::AlreadyBorrowed if the slot cannot be mutably borrowed because it is already borrowed incompatibly;
• MemoryError::Poisoned if a concurrent implementation encounters a poisoned synchronization primitive.

fn free(&mut self, token: MessageToken) -> Result<(), MemoryError>

Free the slot identified by token.

After a successful call, the token must no longer be used to access the manager.

Errors

Returns:

• MemoryError::BadToken if token is invalid;
• MemoryError::NotAllocated if the slot is already empty;
• MemoryError::BorrowActive if the slot still has active borrows;
• MemoryError::QueueOwned if the implementation tracks queue ownership internally and the token is still considered live in one or more queues;
• MemoryError::Poisoned if a concurrent implementation encounters a poisoned synchronization primitive while releasing the slot.

fn available(&self) -> usize

Return the number of currently free slots.

This is intended for diagnostics, telemetry, and admission decisions.

fn capacity(&self) -> usize

Return the total slot capacity of the manager.

fn memory_class(&self) -> MemoryClass

Return the memory class represented by this manager.

This value describes the storage domain used by the manager, such as host memory or another backing class.

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<P: Payload> MemoryManager<P> for ConcurrentMemoryManager<P>

type ReadGuard<'a> = ConcurrentReadGuard<'a, P> where Self: 'a

type WriteGuard<'a> = ConcurrentWriteGuard<'a, P> where Self: 'a

impl<P: Payload> MemoryManager<P> for HeapMemoryManager<P>

type ReadGuard<'a> = HeapReadGuard<'a, P> where Self: 'a

type WriteGuard<'a> = HeapWriteGuard<'a, P> where Self: 'a

impl<P: Payload, const DEPTH: usize> MemoryManager<P> for StaticMemoryManager<P, DEPTH>

type ReadGuard<'a> = StaticReadGuard<'a, P> where Self: 'a

type WriteGuard<'a> = StaticWriteGuard<'a, P> where Self: 'a