Struct Heap 

pub struct Heap<const N: usize> { /* private fields */ }

The interface to a heap. This data structure is stored outside the heap somewhere, typically in a static variable, because every single byte of our heap is potentially available for allocation.

The generic parameter N specifies the number of steps to divide the available heap size by two. This will be the minimum allocable block size.

Usage

// This can be a block of free system memory on your microcontroller.
const HEAP_MEM: usize  = 0xFFF0_0000;
const HEAP_SIZE: usize = 0x0008_0000;

let mut heap: Heap<16> = unsafe {
    Heap::new(NonNull::new(HEAP_MEM as *mut u8).unwrap(), HEAP_SIZE).unwrap()
};
let mem = heap.allocate(Layout::from_size_align(16, 16).unwrap()).unwrap();

// Yay! We have a 16-byte block of memory from the heap.

Usage (static initialization)

const HEAP_MEM: usize  = 0xFFF0_0000;
const HEAP_SIZE: usize = 0x0008_0000;
 
// You'll want to wrap this heap in a lock abstraction for real-world use.
static mut ALLOCATOR: Heap<16> = unsafe {
    Heap::new_unchecked(HEAP_MEM as *mut u8, HEAP_SIZE)
};

pub fn some_func() {
  let mem = unsafe {
    ALLOCATOR.allocate(Layout::from_size_align(16, 16).unwrap()).unwrap()
  };

  // Yay! We now have a 16-byte block from the heap without initializing it!
}

Implementations

impl<const N: usize> Heap<N>

pub unsafe fn new( heap_base: NonNull<u8>, heap_size: usize, ) -> Result<Self, HeapError>

Create a new heap. If any parameter is invalid, this will return a HeapError.

Examples found in repository

examples/allocator.rs (line 43)

fn main() {
    // Allocate the backing memory for our heap. This memory _MUST_
    // be aligned by at least 4096.
    let layout = Layout::from_size_align(16384, 4096).unwrap();
    let mem = unsafe { std::alloc::alloc(layout) };

    // Construct our locked heap, with a minimum block size of 16 (16384 >> 10).
    let heap: LockedHeap<10> = LockedHeap(Mutex::new(
        unsafe { Heap::new(NonNull::new(mem).unwrap(), 16384) }.unwrap(),
    ));
    let mut vec = Vec::with_capacity_in(16, &heap);

    vec.push(0usize);
    vec.push(1usize);
    vec.push(2usize);
    vec.push(3usize);

    println!("{:?}", vec);

    // Drop the heap and vector before freeing the backing memory.
    drop(vec);
    drop(heap);

    unsafe {
        std::alloc::dealloc(mem, layout);
    }
}

pub const unsafe fn new_unchecked(heap_base: *mut u8, heap_size: usize) -> Self

Create a new heap without checking for parameter validity. Useful for const heap creation.

Safety

heap_base must be aligned on a MIN_HEAP_ALIGN boundary, heap_size must be a power of 2, and heap_size / 2.pow(free_lists.len()-1) must be greater than or equal to size_of::<FreeBlock>(). Passing in invalid parameters may do horrible things.

pub fn allocate(&mut self, layout: Layout) -> Result<*mut u8, AllocationError>

Allocate a block of memory large enough to contain layout, and aligned to layout. This will return an AllocationError if the alignment is greater than MIN_HEAP_ALIGN, or if we can’t find enough memory.

All allocated memory must be passed to deallocate with the same layout parameter, or else horrible things will happen.

Examples found in repository

examples/allocator.rs (line 19)

    fn allocate(&self, layout: std::alloc::Layout) -> Result<NonNull<[u8]>, AllocError> {
        let mut heap = self.0.lock().map_err(|_| AllocError)?;

        let ptr = heap.allocate(layout).map_err(|_| AllocError)?;

        // SAFETY: The pointer is guaranteed to not be NULL if the heap didn't return an error.
        Ok(unsafe { NonNull::new_unchecked(std::slice::from_raw_parts_mut(ptr, layout.size())) })
    }

pub unsafe fn deallocate(&mut self, ptr: *mut u8, layout: Layout)

Deallocate a block allocated using allocate.

Safety

ptr and layout must match what was passed to / returned from allocate, or our heap will be corrupted.

Examples found in repository

examples/allocator.rs (line 31)

    unsafe fn deallocate(&self, ptr: NonNull<u8>, layout: std::alloc::Layout) {
        let mut heap = match self.0.lock() {
            Ok(h) => h,
            Err(_) => return,
        };

        heap.deallocate(ptr.as_ptr(), layout);
    }

Trait Implementations

impl<const N: usize> Debug for Heap<N>

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

Formats the value using the given formatter.

impl<const N: usize> Send for Heap<N>