Arenas

Linear Allocators that eliminate fragmentation and memory leaks by design.

The Arena is the foundational memory primitive of Camelot. It implements a Linear Allocator (often called a Region or bump-pointer allocator).

Concept & Motivation

The Problem: In standard C, malloc and free operate on individual objects. This causes Heap Fragmentation (holes in memory) and Memory Leaks (forgetting to free).

The Solution: An Arena reserves a large contiguous block of RAM. Allocations simply advance a pointer (offset). Deallocation is instant and total.

Performance

Arena allocations are $O(1)$ operations involving only a pointer addition. This is significantly faster than traversing a malloc free list.

Architecture

The Arena structure manages a raw byte buffer on the heap. It tracks the len (cursor) and cap (total capacity).

Field	Type	Description
buf	u8*	Pointer to the start of the managed heap block.
len	u64	The current "high water mark" (offset) of used memory.
cap	u64	The total capacity of the block.
status	Result	The health of the allocator (OK or OOM).

---

API Reference

arena.create

Requests a block of raw memory from the Operating System.

• Complexity: High (Syscall).

• Implementation: Wraps malloc but immediately performs a secure memset to zero the entire block, preventing uninitialized memory bugs.

Arena arena.create(u64 size);

Performance Note

Creating an arena is a "heavy" operation. Create them at the start of major tasks (e.g., Level Load), not inside tight loops.

arena.alloc

Reserves a slice of the arena for an object.

• Complexity: $O(1)$

• Alignment: Enforces 8-byte alignment for CPU efficiency.

void* arena.alloc(Arena *a, u64 size);

Sticky Errors

If an arena runs out of memory (OOM), this function returns NULL. The arena enters a "Sticky Error" state, causing all subsequent allocations to also return NULL immediately.

arena.release

Returns the backing memory to the OS.

• Safety: Invalidates the buf pointer to prevent Use-After-Free.

void arena.release(Arena *a);

Critical Safety

Once arena.release is called, all pointers derived from that arena are instantly invalidated. Accessing them will cause a Segmentation Fault.