Struct FrameArena 

pub struct FrameArena { /* private fields */ }

A per-frame bump allocator for temporary render-path allocations.

FrameArena wraps bumpalo::Bump with a focused API for the common allocation patterns in the render pipeline: strings, slices, and single values. All allocations are invalidated on reset(), which should be called at frame boundaries.

Drop semantics

bumpalo intentionally does not run Drop for values allocated in the arena when calling reset() or when the arena itself is dropped. Only allocate short-lived scratch values that do not require destructor logic.

Capacity

The arena starts with an initial capacity and grows automatically when exhausted. Growth allocates new chunks from the global allocator but never moves existing allocations.

Implementations

impl FrameArena

pub fn new(capacity: usize) -> Self

Create a new arena with the given initial capacity in bytes.

Panics

Panics if the system allocator cannot fulfill the initial allocation.

pub fn with_default_capacity() -> Self

Create a new arena with the default capacity (256 KB).

pub fn reset(&mut self)

Reset the arena, reclaiming all memory for reuse.

This is an O(1) operation. All previously allocated references are invalidated. The arena retains its allocated chunks for future allocations, avoiding repeated system allocator calls.

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

Allocate a string slice in the arena.

Returns a reference to the arena-allocated copy of s. The returned reference is valid until the next reset().

pub fn alloc_fmt(&self, args: Arguments<'_>) -> &str

Format a string directly into the arena, avoiding an intermediate heap String.

This is the arena equivalent of format!(). The formatted text is written into a bump-backed string and returned as an arena-allocated &str.

pub fn alloc_slice<T: Copy>(&self, slice: &[T]) -> &[T]

Allocate a copy of a slice in the arena.

Returns a reference to the arena-allocated copy of slice. The returned reference is valid until the next reset().

pub fn alloc_with<T, F: FnOnce() -> T>(&self, f: F) -> &mut T

Allocate a single value in the arena, constructed by f.

Returns a mutable reference to the arena-allocated value. The returned reference is valid until the next reset().

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

Allocate a single value in the arena.

Returns a mutable reference to the arena-allocated value. The returned reference is valid until the next reset().

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

where I: IntoIterator<Item = T>,

Collect an iterator into an arena-allocated slice.

This is the arena equivalent of .collect::<Vec<T>>() — it avoids a heap allocation by writing elements directly into bump memory.

pub fn new_vec<T>(&self) -> BumpVec<'_, T>

Create a new growable vector backed by this arena.

Use this for scratch collections that grow via push() during rendering. The vector’s memory is reclaimed on arena reset.

pub fn new_vec_with_capacity<T>(&self, capacity: usize) -> BumpVec<'_, T>

Create a new growable vector with the given capacity.

pub fn allocated_bytes(&self) -> usize

Returns the total bytes allocated in the arena (across all chunks).

pub fn allocated_bytes_including_metadata(&self) -> usize

Returns total allocated bytes including allocator metadata.

This reflects chunk footprint, not currently live allocation usage. Chunk memory is retained across reset() for reuse.

pub fn as_bump(&self) -> &Bump

Returns a reference to the underlying Bump allocator.

Use this for advanced allocation patterns not covered by the convenience methods.

Trait Implementations

impl Debug for FrameArena

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

Formats the value using the given formatter.

impl Default for FrameArena

fn default() -> Self

Returns the “default value” for a type.