Struct talloc::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

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.

None indicated there is no 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.

Alternatively, use the mov method.

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
• 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);
// extend the arena
// SAFETY: must be sure that we aren't extending 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