Trait Allocator 

pub trait Allocator {
    // Required methods
    unsafe fn allocate(
        &mut self,
        layout: Layout,
    ) -> Result<NonNull<[u8]>, AllocError>;
    unsafe fn deallocate(&mut self, ptr: NonNull<u8>, layout: Layout);
    unsafe fn grow(
        &mut self,
        ptr: NonNull<u8>,
        old_layout: Layout,
        new_layout: Layout,
    ) -> Result<NonNull<[u8]>, AllocError>;
    unsafe fn shrink(
        &mut self,
        ptr: NonNull<u8>,
        old_layout: Layout,
        new_layout: Layout,
    ) -> Result<NonNull<[u8]>, AllocError>;

    // Provided methods
    unsafe fn allocate_zeroed(
        &mut self,
        layout: Layout,
    ) -> Result<NonNull<[u8]>, AllocError> { ... }
    unsafe fn grow_zeroed(
        &mut self,
        ptr: NonNull<u8>,
        old_layout: Layout,
        new_layout: Layout,
    ) -> Result<NonNull<[u8]>, AllocError> { ... }
    fn by_ref(&self) -> &Self
       where Self: Sized { ... }
}

A trait for memory allocators that manage memory in a stack-like fashion.

This trait defines the core interface for memory allocation and deallocation operations used by the arena allocator system. Implementors of this trait can be used interchangeably in contexts that require memory allocation.

Implementation

The trait provides a complete interface for memory management:

• allocate - Allocates memory with the specified layout
• allocate_zeroed - Allocates zeroed memory with the specified layout
• deallocate - Deallocates previously allocated memory
• grow - Grows a previously allocated memory block to a larger size
• grow_zeroed - Grows a memory block and zeroes the new memory
• shrink - Shrinks a previously allocated memory block to a smaller size

Safety

This trait uses unsafe methods because it deals directly with memory allocation and raw pointers. Implementors must ensure that:

• Allocated memory is properly aligned and sized according to the layout
• Deallocated pointers were previously allocated by the same allocator
• Memory is not used after deallocation
• Grow and shrink operations maintain the validity of the memory
• All memory safety invariants are preserved

Examples

This trait is implemented by StackArena and BufferArena:

use stack_arena::{StackArena, Allocator};
use std::alloc::Layout;

let mut arena = StackArena::new();
let layout = Layout::from_size_align(16, 8).unwrap();

// Allocate memory
let ptr = unsafe { arena.allocate(layout).unwrap() };

// Use the memory...

// Deallocate when done
unsafe { arena.deallocate(ptr.cast(), layout) };

Required Methods

unsafe fn allocate( &mut self, layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>

Allocates memory with the specified layout.

Safety

This method is unsafe because it returns a raw pointer that must be used carefully to avoid memory safety issues.

Parameters

• layout - The layout of the memory to allocate

Returns

A non-null pointer to the allocated memory on success, or an error if allocation fails.

unsafe fn deallocate(&mut self, ptr: NonNull<u8>, layout: Layout)

Deallocates memory previously allocated by this allocator.

Safety

This method is unsafe because it must be called with a pointer returned by allocate and the same layout that was used to allocate it.

Parameters

• ptr - A pointer to the memory to deallocate
• layout - The layout used to allocate the memory

unsafe fn grow( &mut self, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>

Grows a previously allocated memory block to a larger size.

Safety

This method is unsafe because it must be called with a pointer returned by allocate and the same layout that was used to allocate it.

Parameters

• ptr - A pointer to the memory to grow
• old_layout - The layout used to allocate the memory
• new_layout - The new layout for the memory

Returns

A non-null pointer to the grown memory on success, or an error if the operation fails.

unsafe fn shrink( &mut self, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>

Shrinks a previously allocated memory block to a smaller size.

Safety

This method is unsafe because it must be called with a pointer returned by allocate and the same layout that was used to allocate it.

Parameters

• ptr - A pointer to the memory to shrink
• old_layout - The layout used to allocate the memory
• new_layout - The new layout for the memory

Returns

A non-null pointer to the shrunk memory on success, or an error if the operation fails.

Provided Methods

unsafe fn allocate_zeroed( &mut self, layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>

Allocates zeroed memory with the specified layout.

This method allocates memory and initializes it with zeros.

Safety

This method is unsafe for the same reasons as allocate.

Parameters

• layout - The layout of the memory to allocate

Returns

A non-null pointer to the allocated zeroed memory on success, or an error if allocation fails.

unsafe fn grow_zeroed( &mut self, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>

Grows a previously allocated memory block to a larger size and zeroes the new memory.

Safety

This method is unsafe for the same reasons as grow.

Parameters

• ptr - A pointer to the memory to grow
• old_layout - The layout used to allocate the memory
• new_layout - The new layout for the memory

Returns

A non-null pointer to the grown memory on success, or an error if the operation fails.

fn by_ref(&self) -> &Self

where Self: Sized,

Returns a reference to this allocator.

This method is used to get a reference to the allocator for use in contexts that require a reference.

Returns

A reference to this allocator.

Implementors

impl Allocator for BufferArena

Implementation of the Allocator trait for BufferArena.

This implementation provides efficient memory allocation within a single contiguous memory chunk using a bump allocation strategy. It follows the LIFO (Last-In-First-Out) pattern for memory management.

impl Allocator for StackArena

Implementation of the Allocator trait for StackArena.

This implementation allows StackArena to be used with APIs that require an allocator. The implementation follows the stack-like allocation pattern, where memory is allocated in chunks and objects are allocated contiguously.

Safety

The implementation uses unsafe code internally to manage memory efficiently. Users should follow the LIFO (Last-In-First-Out) pattern when deallocating memory to ensure proper behavior.

Performance

This allocator is optimized for scenarios with many small allocations that follow a stack-like pattern. It significantly outperforms the system allocator in these cases as demonstrated in the benchmarks.