Struct BufferArena 

pub struct BufferArena { /* private fields */ }

A buffer-based arena allocator that manages a single memory chunk.

BufferArena is a low-level component used by StackArena to manage individual memory chunks. It provides efficient allocation within a single contiguous memory region and implements the Allocator trait for memory management operations.

Each BufferArena contains a memory chunk and a pointer to the current position in the buffer, allowing for efficient bump allocation (also known as linear allocation).

Memory Management

• Uses a simple bump allocation strategy for maximum performance
• Allocates memory sequentially from a single contiguous chunk
• Follows LIFO (Last-In-First-Out) deallocation pattern
• Provides methods to check remaining capacity and allocation suitability

Performance

BufferArena is designed for maximum allocation speed:

• Allocation is a simple pointer increment operation
• No fragmentation within a single chunk
• Minimal overhead per allocation
• Efficient memory reuse with the LIFO pattern

Implementations

impl BufferArena

pub fn with_capacity(capacity: usize) -> Self

Creates a new buffer arena with the specified capacity.

The capacity will be rounded up to the next power of two if it’s not already a power of two.

Parameters

• capacity - The capacity of the buffer in bytes

Examples

use stack_arena::BufferArena;

let arena = BufferArena::with_capacity(4096);

pub fn used(&self) -> usize

Returns the number of bytes currently used in the buffer.

Examples

use stack_arena::BufferArena;

let arena = BufferArena::with_capacity(4096);
assert_eq!(arena.used(), 0);

pub fn remaining(&self) -> usize

Returns the number of bytes remaining in the buffer.

Examples

use stack_arena::BufferArena;

let arena = BufferArena::with_capacity(4096);
assert_eq!(arena.remaining(), 4096);

pub fn contains(&self, ptr: NonNull<u8>) -> bool

Checks if the given pointer is contained within this buffer.

Parameters

• ptr - The pointer to check

Returns

true if the pointer is within the buffer’s memory range, false otherwise.

pub fn sufficient_for(&self, layout: Layout) -> bool

Returns true if the buffer has enough space to allocate the given layout.

This method checks if there is enough space in the buffer to allocate memory with the specified layout, taking alignment requirements into account.

Parameters

• layout - The memory layout to check

Returns

true if there is enough space, false otherwise.

Trait Implementations

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.

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

Allocates memory with the specified layout.

This method allocates memory from the current position in the buffer, ensuring proper alignment. It advances the buffer pointer by the size of the allocation.

Safety

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

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

Deallocates memory previously allocated by this allocator.

This method resets the buffer pointer to the start of the deallocated memory, effectively “freeing” all memory allocated after it as well. This implements the LIFO deallocation pattern.

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.

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.

This method extends the size of an existing allocation by advancing the buffer pointer. It only supports growing the last allocation (following LIFO pattern). Attempting to grow any other allocation will trigger a debug assertion failure.

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.

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.

This method reduces the size of an existing allocation by moving the buffer pointer back. It assumes the memory block being shrunk is the most recently allocated block (following LIFO pattern).

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.

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

Allocates zeroed memory with the specified layout.

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.

fn by_ref(&self) -> &Self

where Self: Sized,

Returns a reference to this allocator.

impl Debug for BufferArena

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

Formats the value using the given formatter.

impl Default for BufferArena

fn default() -> Self

Returns the “default value” for a type.