Struct LinearAllocator

pub struct LinearAllocator<'a> { /* private fields */ }

A linear allocator with a constant capacity. Can allocate memory regions with any size or alignment (within the capacity) very fast, but individual allocations can’t be freed to make more space while there’s still other allocations in use.

Implementations

impl LinearAllocator<'_>

pub fn new<'a>( allocator: &'a LinearAllocator<'_>, capacity: usize, ) -> Option<LinearAllocator<'a>>

Creates a new LinearAllocator with capacity bytes of backing memory. Returns None if allocating the memory fails or if capacity overflows isize.

See static_allocator for bootstrapping one of these.

pub const unsafe fn from_raw_slice( backing_slice: *mut [u8], ) -> LinearAllocator<'static>

Creates a new LinearAllocator with as many bytes of backing memory as there are in the given slice.

Only the first isize::MAX bytes of the slice are used if it’s longer than that.

Safety

The backing_slice pointer must not be shared, nor the memory behind it, and it must live for as long as this allocator (and any allocations from it) live. Consider this function as taking ownership of the memory pointed to by it for ’static.

pub fn allocated(&self) -> usize

Returns an estimate of the amount of allocated memory currently, in bytes.

An “estimate” since the value returned is from an Ordering::Relaxed atomic operation, which technically may return the wrong value even when using the allocator on a single thread due to funky out-of-order computing details. Still, the value can be considered accurate for some point in time.

pub fn total(&self) -> usize

Returns the total (free and allocated) amount of memory owned by this allocator, in bytes.

pub fn try_alloc_box<T>(&'static self, value: T) -> Option<Box<T>>

Allocates memory for a T and returns a boxed version of it.

pub fn try_alloc_boxed_slice_zeroed<T: Zeroable>( &'static self, len: usize, ) -> Option<Box<[T]>>

Allocates memory for a [T] with len elements, zeroes it out, and returns a boxed version of it.

pub fn try_alloc_boxed_slice_with<T, F: FnMut() -> Option<T>>( &'static self, init: F, len: usize, ) -> Option<Box<[T]>>

Allocates memory for a [T] with len elements, fills it by calling init, and returns a boxed version of it.

If init returns None for any invocation, this also returns None. Note that the already allocated memory isn’t freed up in this case (due to LinearAllocator being strictly growing for thread-safety reasons).

pub fn try_alloc_uninit_slice<'a, T>( &'a self, len: usize, alignment: Option<usize>, ) -> Option<&'a mut [MaybeUninit<T>]>

Allocates memory for a slice of MaybeUninit<T>, leaving the contents of the slice uninitialized, returning None if there’s not enough free memory.

Note regardless of if the allocation is successful, len bytes are “allocated” from the allocation offset. This means that once this returns None, subsequent allocations will always fail until LinearAllocator::reset.

If alignment is Some, it will be used for alignment instead of T’s alignment. If the resulting alignment would result in T being unaligned, this function will panic.

pub fn reset(&mut self)

Resets the linear allocator, reclaiming all of the backing memory for future allocations.

Trait Implementations

impl Debug for LinearAllocator<'_>

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

Formats the value using the given formatter.

impl Sync for LinearAllocator<'_>

Safety: the only non-Sync part of LinearAllocator is backing memory pointer, which is fine to access from multiple threads simultaneously as the regions of memory accessed via the pointer are distinct on every access, due to the atomic incrementing of LinearAllocator::allocated.