Struct Talloc

pub struct Talloc { /* private fields */ }

The TauOS Allocator!

Note, you’re probably looking for Tallock if you want the spin-locked wrapper with the GlobalAlloc and Allocator trait implementations.

TODO resolve

Implementations

impl Talloc

pub unsafe fn malloc( &mut self, layout: Layout, ) -> Result<NonNull<u8>, AllocError>

Allocate a contiguous region of memory according to layout, if possible.

Safety

layout.size() must be nonzero.

pub unsafe fn free(&mut self, ptr: NonNull<u8>, _: Layout)

Free previously allocated/reallocated memory.

Safety

ptr must have been previously allocated given layout.

pub unsafe fn grow( &mut self, ptr: NonNull<u8>, layout: Layout, new_size: usize, ) -> Result<NonNull<u8>, AllocError>

Grow a previously allocated/reallocated region of memory to new_size.

Safety

ptr must have been previously allocated or reallocated given old_layout. new_size must be larger or equal to old_layout.size().

pub unsafe fn shrink( &mut self, ptr: NonNull<u8>, layout: Layout, new_size: usize, )

Shrink a previously allocated/reallocated region of memory to new_size.

This function is infallibe given valid inputs, and the reallocation will always be done in-place, maintaining the validity of the pointer.

Safety

• ptr must have been previously allocated or reallocated given old_layout.
• new_size must be smaller or equal to old_layout.size().
• new_size should be nonzero.

pub const fn new() -> Self

pub const fn with_oom_handler( oom_handler: fn(_: &mut Talloc, _: Layout) -> Result<(), AllocError>, ) -> Self

pub const fn get_arena(&self) -> Span

Returns the Span which has been granted to this allocator as allocatable.

pub fn get_allocatable_span(&self) -> Span

Returns the Span in which allocations may be placed.

pub fn get_allocated_span(&self) -> Span

Returns the minimum Span containing all allocated memory.

pub unsafe fn init(&mut self, arena: Span)

Initialize the allocator heap.

Safety

• After initialization, the allocator structure is invalidated if moved. This is because there are pointers on the heap to this struct.
• Initialization restores validity, but erases all knowledge of previous allocations.

Use the mov function to safely move the struct.

pub unsafe fn extend(&mut self, new_arena: Span)

Increase the extent of the arena.

Safety

The entire new_arena memory but be readable and writable and unmutated besides that which is allocated. So on and so forth.

Panics

This function panics if:

• new_arena doesn’t contain the old arena (NB: empty arenas are contained by any arena)
• new_arena contains the null address

A recommended pattern for satisfying these criteria is:

let mut talloc = tallock.0.lock();
// compute the new arena as an extention of the old arena
let new_arena = talloc.get_arena().extend(1234, 5678).above(0x1000);
// SAFETY: be sure not to extend into memory we can't use
unsafe { talloc.extend(new_arena); }

pub fn truncate(&mut self, new_arena: Span)

Reduce the extent of the arena. The new extent must encompass all current allocations. See below.

Panics:

This function panics if:

• old arena doesn’t contain new_arena
• new_arena doesn’t contain all the allocated memory

The recommended pattern for satisfying these criteria is:

// lock the allocator otherwise a race condition may occur
// in between get_allocated_span and truncate
let mut talloc = tallock.0.lock();
// compute the new arena as a reduction of the old arena
let new_arena = talloc.get_arena().truncate(1234, 5678).fit_over(talloc.get_allocated_span());
// alternatively...
let new_arena = Span::from(1234..5678).fit_within(talloc.get_arena()).fit_over(talloc.get_allocated_span());
// truncate the arena
talloc.truncate(new_arena);

pub fn mov(self, dest: &mut MaybeUninit<Self>) -> &mut Self

Move the allocator structure to a new destination safely.

pub const fn spin_lock(self) -> Tallock

Wrap in a spin mutex-locked wrapper struct.

This implements the GlobalAlloc trait and provides access to the Allocator API.

Trait Implementations

impl Debug for Talloc

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

Formats the value using the given formatter.

impl Send for Talloc