Arena Allocator

Growable block-based arena allocator backed by the runtime.

Overview

ArenaAllocator is designed for workloads where many allocations share the same lifetime. Instead of tracking every allocation separately, the arena allocates from larger backing blocks and invalidates everything together on reset() or destroy().

This makes it a good fit for:

• parser and compiler temporary objects
• short-lived request or frame allocations
• scratch buffers built and discarded in batches
• phase-local data where all values die together

Core Behavior

The arena has three important properties:

1. Fast allocation

   • allocate from the current backing block
   • if the block has no room, request or switch to another runtime block

2. No individual deallocation

   • there is no per-allocation free
   • memory stays owned by the arena until reset or destroy

3. Bulk lifetime management

   • reset() keeps the arena but rewinds allocation state
   • destroy() releases all arena-owned backing blocks

Mental Model

  ArenaAllocator
  ┌─────────────────────────────────────────────────────────────────┐
  │ handle -> runtime arena state                                  │
  │ blockSize -> preferred block size for future growth            │
  └─────────────────────────────────────────────────────────────────┘

  Runtime-owned backing blocks
  ┌────────────────────────┐  ┌────────────────────────┐
  │ [used][used][free...]  │  │ [used][free.........] │
  └────────────────────────┘  └────────────────────────┘

The exact block metadata lives in the runtime, not in this Ignis wrapper. At the stdlib level, ArenaAllocator is a lightweight handle over that runtime-managed arena state.

Allocation Semantics

• allocate(layout) returns a properly aligned pointer for layout
• allocate<T>() allocates space for exactly one T
• allocate<T>(count) allocates space for count contiguous T values
• zero-sized requests return null
• if the arena handle has been destroyed, allocation returns null

Reset vs Destroy

  reset()
    - keeps backing blocks
    - invalidates all previously returned pointers
    - makes arena space reusable

  destroy()
    - releases all backing blocks through the runtime
    - sets handle to null
    - allocator becomes unusable until reinitialized

Safety Notes

ArenaAllocator deliberately trades precision for speed.

Callers must treat all pointers returned from the arena as invalid after:

• reset()
• destroy()
• drop()

Values allocated in the arena are not individually dropped by the allocator. If a stored type owns resources, the caller is responsible for ensuring the lifetime strategy is valid for arena allocation.

Example

import ArenaAllocator from "std::memory";
import Layout from "std::memory";

function main(): i32 {
  let mut arena: ArenaAllocator = ArenaAllocator::new(4096);

  let numbers: *mut i32 = arena.allocate<i32>(16);
  if (numbers == null) {
    return 1;
  }

  numbers[0] = 42;
  arena.reset();
  // `numbers` is now invalid and must not be used.

  let raw: *mut u8 = arena.allocate(Layout::new<u64>());
  if (raw == null) {
    return 2;
  }

  arena.destroy();
  return 0;
}