Struct palloc::palloc::Palloc

pub struct Palloc { /* fields omitted */ }

defines a both uninitialized and initialized allocator.

An ‘empty’ instance may be created for static purposes, but in order to allocate memory initialization must occur.

Safety

Palloc manually implements the Send trait, meaning it can be sended between threads for shared access. This also means that the heap memory region must be accessible from every thread.

Implementations

impl Palloc

pub const fn empty() -> Palloc

creates an empty allocator, pointing to 0-sized null memory.

to make the allocator working, check out init

pub unsafe fn init(&mut self, bottom: NonNull<u8>, size: usize)

Initializes the allocator with a pointer to a free heap region and a size which defines the upper bound of the same.

Safety

Memory is not asserted to be zeroed. However the whole region must be accessible and free to use.

Initializing using a null pointer will result in a panic.

pub unsafe fn init_from_slice(&mut self, heap: &mut [u8])

Initializes heap from a memory slice. See init for more informations.

Safety

See init

pub unsafe fn alloc(&mut self, size: usize) -> Result<NonNull<u8>, PallocError>

Creates a new allocation of size bytes. When Ok, returns a pointer to a free uninitialized (not to be assumed zero) memory region. May result in one of the errors defined in PallocError.

Alloc will potentially traverse the entire heap in search of a free segment. It will also merge all freed adjacent blocks. Once a free block is found, if it does not fill the entire segment (in case of reallocation) a chunk will be split and the rest of the memory made available for further allocations.

This whole process, while not ensuring super fast allocation all of the time, it assures that every piece of memory is being used as much as possible.

Safety

Null pointer is never returned, in case of OOM a PallocError is returned instead. As stated before, memory is never to be assumed initialized.

pub unsafe fn free(&self, alloc: NonNull<u8>) -> Result<(), PallocError>

Deallocates memory at a given pointer location, giving it back to the allocator for further allocational purposes.

Once deallocated, memory cannot be used anymore and its integrity is not assured.

Safety

alloc must point to the bottom of a valid allocation. Not being aligned to one will lead to undefined behaviour, potentially destructive.

Trait Implementations

impl Send for Palloc