Struct TypedArena 

pub struct TypedArena<'a, T: Default + Sized> { /* private fields */ }

A type-specific memory arena for efficient allocation of T elements.

TypedArena is a specialized memory allocator designed for managing objects of a single type T. It builds upon the underlying Arena, providing type safety and automatic initialization of allocated objects using T::default(). This makes it ideal for scenarios where a large number of objects of type T need to be allocated efficiently, either for long-term storage or for short-lived usage with rapid recycling.

Type Parameters

• T: The type of objects that this arena will manage. T must implement the Default and Sized traits, ensuring that instances can be created with default values and that their size is known at compile-time.

Primary Use-Cases

TypedArena is particularly useful in situations where:

1. Long-Lived Allocations: Objects are allocated once and used until the end of the program.
2. Short-Lived Allocations: Objects are allocated and then quickly discarded, with the entire arena being rewound for reuse. This is efficient for temporary data structures that need to be quickly recycled.

Example

use arena_allocator::TypedArena;

let mut arena = TypedArena::<u32>::new(1024 * 1024).unwrap();
let item = arena.alloc().unwrap();
*item = 42;

let array = arena.alloc_array(10).unwrap();
for i in 0..10 {
    array[i] = i as u32;
}

arena.rewind(); // All previous allocations are now invalid.

Implementations

impl<'a, T: Default + Sized> TypedArena<'a, T>

pub fn new(size: usize) -> Result<Self, ArenaError>

Creates a new TypedArena with the specified size.

The size parameter specifies the amount of memory to reserve in the arena. It is recommended to choose a large size, especially for scenarios where many objects of type T will be allocated. The reserved memory is not immediately committed, so reserving more than necessary does not consume physical memory until allocations occur.

Errors

This function will return an ArenaError if the underlying memory reservation fails.

pub fn alloc(&mut self) -> Result<&'a mut T, ArenaError>

Allocates a single instance of T in the arena and initializes it with the default value.

This function allocates memory for an instance of T and initializes it using T::default(). The returned reference points to the initialized object, which can be used immediately.

Errors

This function will return an ArenaError if the memory allocation fails.

pub fn alloc_array(&mut self, count: usize) -> Result<&'a mut [T], ArenaError>

Allocates an array of T elements in the arena and initializes them with the default value.

This function allocates memory for an array of T elements and initializes each element using T::default(). The returned slice points to the initialized array, which can be used immediately.

Errors

This function will return an ArenaError if the memory allocation fails.

pub fn rewind(&mut self)

Rewinds the arena to its initial state, invalidating all previous allocations.

This method resets the arena, allowing it to be reused for new allocations. All previously allocated objects become invalid after this operation, and any attempt to access them will result in undefined behavior. In debug mode, the memory of the invalidated objects is protected to help catch use-after-free bugs.

Usage

rewind is particularly useful in scenarios where the arena is used for temporary allocations that need to be quickly discarded and recycled.