Struct mnemos_alloc::heap::MnemosAlloc

pub struct MnemosAlloc<U> {
    allocator: U,
    heap_size: AtomicUsize,
    stats: Stats,
}

Mnemos Allocator

This is a wrapper type over an implementor of UnderlyingAllocator.

This “inherits” any of the behaviors and safety requirements of the chosen UnderlyingAllocator, and in addition has two major special behaviors that are intended to help respond gracefully to ephemeral Out of Memory conditions

• On alloc:
  • We check whether allocation is inhibited. If it is - a nullptr is returned, regardless of whether there is sufficient room to allocate the requested amount.
  • If we are NOT inhibited, but are now out of memory (the underlying allocator returned a nullptr), we inhibit further allocations until the next deallocation occurs
• On dealloc:
  • The “inhibit allocations” flag is cleared
  • If any tasks are waiting on the “OOM” queue, they are ALL awoken if the inhibit flag was previously set

These two details are intended to allow the “async allocation aware” types defined in crate::containers to yield if allocation is not currently possible.

By wrapping the UnderlyingAllocator, we allow non-async-aware allocations (like those through alloc::alloc::alloc() or alloc::alloc::dealloc()) to trigger these behaviors. However, non-async-aware allocations are still subject to normal OOM handling, which typically means panicking.

Fields

allocator: U

heap_size: AtomicUsize

The total size of the heap, in bytes.

stats: Stats

Available on crate feature stats only.

Tracks heap statistics.

Implementations

impl<U> MnemosAlloc<U>

pub fn state(&self) -> State

Available on crate feature stats only.

Returns a snapshot of the current state of the heap.

This returns a struct containing all available heap metrics at the current point in time. It permits calculating derived metrics, such as State::free_bytes, State::alloc_attempt_count, and State::live_alloc_count, which are calculated using the values of other heap statistics.

Taking a single snapshot ensures that no drift occurs between these metrics. For example, if we were to call Self::alloc_success_count(), and then later attempt to calculate the number of live allocations by subtracting the value of Self::dealloc_count() from a subsequent call to Self::alloc_success_count(), additional concurrent allocations may have occurred between the first time the success count was loaded and the second. Taking one snapshot of all metrics ensures that no drift occurs, because the snapshot contains all heap metrics at the current point in time.

pub fn allocated_bytes(&self) -> usize

Available on crate feature stats only.

Returns the total amount of memory currently allocated, in bytes.

pub fn total_bytes(&self) -> usize

Available on crate feature stats only.

Returns the total size of the heap, in bytes. This includes memory that is currently allocated.

pub fn alloc_success_count(&self) -> usize

Available on crate feature stats only.

Returns the total number of times an allocation attempt has succeeded, over the lifetime of this heap.

pub fn alloc_oom_count(&self) -> usize

Available on crate feature stats only.

Returns the total number of times an allocation attempt could not be fulfilled because there was insufficient space, over the lifetime of this heap.

pub fn dealloc_count(&self) -> usize

Available on crate feature stats only.

Returns the total number of times an allocation has been deallocated, over the lifetime of this heap.

impl<U: UnderlyingAllocator> MnemosAlloc<U>

const INITIALIZING: usize = 18_446_744_073_709_551_615usize

pub const fn new() -> Self

pub unsafe fn init( &self, start: NonNull<u8>, len: usize, ) -> Result<(), InitError>

Initialize the allocator, with a heap of size len starting at start.

Returns

• Ok(()) if the heap was successfully initialized.
• Err(InitError::AlreadyInitialized) if this method has already been called to initialize the heap.

Safety

This function requires the caller to uphold the following invariants:

• The memory region starting at start and ending at start + len may not be accessed except through pointers returned by this allocator.
• The end of the memory region (start + len) may not exceed the physical memory available on the device.
• The memory region must not contain memory regions used for memory-mapped IO.

pub fn total_size(&self) -> usize

Returns the total size of the heap in bytes, including allocated space.

The current free space remaining can be calculated by subtracting this value from [self.allocated_size()].

Trait Implementations

impl<U: UnderlyingAllocator> Default for MnemosAlloc<U>

fn default() -> Self

Returns the “default value” for a type.

impl<U: UnderlyingAllocator> GlobalAlloc for MnemosAlloc<U>

unsafe fn alloc(&self, layout: Layout) -> *mut u8

Allocates memory as described by the given layout.

unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout)

Deallocates the block of memory at the given ptr pointer with the given layout.

unsafe fn alloc_zeroed(&self, layout: Layout) -> *mut u8

Behaves like alloc, but also ensures that the contents are set to zero before being returned.

unsafe fn realloc( &self, ptr: *mut u8, layout: Layout, new_size: usize, ) -> *mut u8

Shrinks or grows a block of memory to the given new_size in bytes. The block is described by the given ptr pointer and layout.