Struct Allocator

pub struct Allocator { /* private fields */ }

A super-simple soft-realtime allocator for managing an external pool of memory

Implementations

impl Allocator

pub fn new(capacity: u32) -> Self

Create a new allocator to manage a pool of memory

Panics:

• Panics if capacity == 0

pub fn alloc(&mut self, size: u32) -> Option<Allocation>

Try to allocate a region with the provided size

Uses a best-fit strategy, and returns Allocations with arbitrary alignment.

Returns None if:

• size == 0, or
• size + 1 overflows.

pub fn alloc_with_align(&mut self, size: u32, align: u32) -> Option<Allocation>

Try to allocate a region with the provided size & alignment

Implements the following strategy (not quite best-fit):

• Search for a region with at least size + align - 1, and then truncate the start of the region such that alignment is reached.

This is more prone to causing fragmentation compared to an unaligned alloc.

Returns None if:

• there are no free-regions with size + align - 1 available space, or
• size == 0, or
• align == 0, or
• size + align overflows.

pub fn free(&mut self, alloc: Allocation)

Free the given allocation

Panics

• May panic if the allocation’s location gets freed twice, without first being re-allocated.

  Note: This panic will not catch all double frees.

pub fn reset(&mut self)

Free all allocations

pub fn grow_capacity(&mut self, additional: u32) -> Result<(), Overflow>

Add new free space at the end of the allocator

Returns Err(Overflow) if self.capacity + additional would overflow.

pub fn try_reallocate( &mut self, alloc: Allocation, new_size: u32, ) -> Result<Allocation, ReallocateError>

Try to re-size an existing allocation in-place

Will not change the offset of the allocation and tries to expand the allocation to the right if there is sufficient free space.

Returns:

• Ok(Allocation) on success.
• Err(InsufficientSpace) if there is not enough available space to expand the allocation to new_size. In this case, the existing allocation is left untouched.

pub fn capacity(&self) -> u32

Get the total capacity of the pool

pub fn total_available(&self) -> u32

Get the total available memory in this pool

Note: The memory may be fragmented, so it may not be possible to allocate an object of this size.

pub fn largest_available(&self) -> u32

Get the size of the largest available memory region in this pool

pub fn is_empty(&self) -> bool

Returns true if there are no allocations

pub fn report_free_regions(&self) -> impl Iterator<Item = Allocation> + use<'_>

Returns an iterator over the unallocated regions

This should be used only for gathering metadata about the internal state of the allocator for debugging purposes.

You must not use this instead of allocating; subsequent calls to alloc will freely allocate from the reported regions.

Trait Implementations

impl Clone for Allocator

fn clone(&self) -> Allocator

Returns a duplicate of the value.

const fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Allocator

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.