Struct Arena

pub struct Arena<T> { /* private fields */ }

A container that can be used for arena allocation of values of a given type.

An Arena guarantees that all references returned are valid for the lifetime of the arena. A single value can be moved into the arena using Arena::alloc, and multiple values can be moved into one contiguous block of memory owned by the arena using Arena::alloc_extend.

All items in the arena are deallocated at the same time when the arena goes out of scope. There is no support for controlled deallocation of certain items in memory, so this arena type is most useful for designs where several groups of values should be allocated and deallocated together over the life of a program.

Internally, arena allocation is achieved by allocating contiguous blocks of memory that are never resized (to ensure values are never moved). All items will be allocated in a single, contiguous block of memory. When the arena’s current memory block is full, the block is “committed”, and a new, larger block of memory is allocated for future items.

This data type is not thread safe. In fact, usage across multiple threads will likely panic.

Implementations

impl<T> Arena<T>

pub fn new() -> Self

Creates a new arena.

pub fn with_capacity(size: usize) -> Self

Creates a new arena with the given capacity.

pub fn is_empty(&self) -> bool

Checks if the arena is empty.

pub fn len(&self) -> usize

Returns the number of elements allocated in the arena.

pub fn alloc(&self, value: T) -> &mut T

Allocates a new value in the arena, returning a mutable reference to that value.

pub fn alloc_extend<I>(&self, iterable: I) -> &mut [T]

where I: IntoIterator<Item = T>,

Allocates the contents of an iterator in the arena into a contiguous block of memory.

Returns a mutable slice containing all allocated values.

pub fn reserve(&self, additional: usize)

Ensures there is enough continuous space for at least additional values.

pub fn into_vec(self) -> Vec<T>

Converts the Arena<T> into a Vec<T>.

Items will be in the same order of allocation in the arena.

pub fn iter_mut(&mut self) -> IterMut<'_, T>

Returns an iterator that provides mutable access to all elements in the arena, in order of allocation.

Arenas only allow mutable iteration because the entire arena must be borrowed for the duration of the iteration. The mutable borrow to call this method allows Rust’s borrow checker to enforce this rule.

impl Arena<u8>

pub fn alloc_str(&self, s: &str) -> &mut str

Allocates a string slice in the arena, returning a mutable reference to it.

Trait Implementations

impl<T> Default for Arena<T>

fn default() -> Self

Returns the “default value” for a type.

impl<A> FromIterator<A> for Arena<A>

fn from_iter<T: IntoIterator<Item = A>>(iter: T) -> Self

Creates a value from an iterator.