Arena Allocator

Classes
struct	Arena
	Represents a linear memory arena backed by OS virtual memory. More...
struct	ArenaTemp
	A saved checkpoint into an arena, used for scoped temporary allocations. More...

Macros
#define	ARENA_DEFAULT_ALIGN   8
	The default alignment for all arena_push() allocations (8 bytes).
#define	ARENA_COMMIT_SIZE   KB(64)
	The granularity at which physical RAM is committed from the OS (64 KB).
#define	PUSH_STRUCT(arena, type)
	Allocates and zero-initializes a single struct on the arena.
#define	PUSH_ARRAY(arena, type, count)
	Allocates and zero-initializes an array of count elements on the arena.
#define	PUSH_ARRAY_ALIGNED(arena, type, count, alignment)
	Allocates a zero-initialized array with an explicit power-of-2 alignment.

Typedefs
typedef struct Arena	Arena
	Represents a linear memory arena backed by OS virtual memory.
typedef struct ArenaTemp	ArenaTemp
	A saved checkpoint into an arena, used for scoped temporary allocations.

Functions
Arena	arena_create (usize reserve_size)
	Creates and initializes a new arena, reserving virtual address space.
void	arena_release (Arena *arena)
	Releases the entire arena back to the OS, invalidating all pointers into it.
void *	arena_push (Arena *arena, usize size)
	Allocates size bytes from the arena, aligned to ARENA_DEFAULT_ALIGN.
void *	arena_push_zero (Arena *arena, usize size)
	Allocates size bytes from the arena, zeroed, aligned to ARENA_DEFAULT_ALIGN.
void *	arena_push_aligned (Arena *arena, usize size, usize alignment)
	Allocates size bytes from the arena with an explicit power-of-2 alignment.
void	arena_pop_to (Arena *arena, usize pos)
	Rolls the arena back to a specific byte offset.
void	arena_clear (Arena *arena)
	Resets the arena to empty by setting pos back to 0.
ArenaTemp	arena_temp_begin (Arena *arena)
	Saves the current arena position as a rewind checkpoint.
void	arena_temp_end (ArenaTemp temp)
	Restores the arena to the position saved in temp.

Detailed Description

Macro Definition Documentation

ARENA_COMMIT_SIZE

#define ARENA_COMMIT_SIZE   KB(64)

The granularity at which physical RAM is committed from the OS (64 KB).

When an allocation would exceed the currently committed range, the arena rounds the new commit size up to this boundary. Matching the Windows allocation granularity avoids wasted syscalls.

Definition at line 75 of file mem_arena.h.

ARENA_DEFAULT_ALIGN

#define ARENA_DEFAULT_ALIGN   8

The default alignment for all arena_push() allocations (8 bytes).

Definition at line 66 of file mem_arena.h.

PUSH_ARRAY

#define PUSH_ARRAY	(		arena,
			type,
			count )

Value:

((type *)arena_push_zero((arena), sizeof(type) * (count)))

Allocates and zero-initializes an array of count elements on the arena.

Example:

u32 *indices = PUSH_ARRAY(&arena, u32, 1024);

Parameters

arena	Pointer to the Arena.
type	The element type (e.g., u32, struct Vertex).
count	Number of elements.

Returns

A correctly typed pointer to the first element, or NULL on OOM.

Definition at line 252 of file mem_arena.h.

PUSH_ARRAY_ALIGNED

#define PUSH_ARRAY_ALIGNED	(		arena,
			type,
			count,
			alignment )

Value:

((type *)arena_push_aligned((arena), sizeof(type) * (count), (alignment)))

Allocates a zero-initialized array with an explicit power-of-2 alignment.

Example:

// 64 floats aligned to 32 bytes for AVX SIMD.
float *v = PUSH_ARRAY_ALIGNED(&arena, float, 64, 32);

Parameters

arena	Pointer to the Arena.
type	The element type.
count	Number of elements.
alignment	Alignment in bytes (must be a power of 2).

Returns

A correctly typed, aligned pointer, or NULL on OOM.

Definition at line 269 of file mem_arena.h.

PUSH_STRUCT

#define PUSH_STRUCT	(		arena,
			type )

Value:

((type *)arena_push_zero((arena), sizeof(type)))

Allocates and zero-initializes a single struct on the arena.

Example:

MyNode *node = PUSH_STRUCT(&arena, MyNode);
node->value  = 42;

Parameters

arena	Pointer to the Arena.
type	The struct type to allocate (e.g., MyNode).

Returns

A correctly typed pointer to the zero-initialized struct, or NULL on OOM.

Definition at line 237 of file mem_arena.h.

Typedef Documentation

Arena

typedef struct Arena Arena

Represents a linear memory arena backed by OS virtual memory.

Note

Treat this as an opaque value. Modify fields only through the arena_* API to keep the reserve/commit invariants intact.

ArenaTemp

typedef struct ArenaTemp ArenaTemp

A saved checkpoint into an arena, used for scoped temporary allocations.

Call arena_temp_begin() to capture the current pos, do your allocations, then call arena_temp_end() to roll the arena back to that exact position. This is the preferred pattern for scratch/temporary work buffers.

Example

ArenaTemp tmp = arena_temp_begin(&arena);
u8 *scratch   = PUSH_ARRAY(&arena, u8, KB(4));
// ... build something temporary in scratch ...
arena_temp_end(tmp); // all temporary allocations are gone

Function Documentation

arena_clear()

void arena_clear

(

Arena *

arena

)

Resets the arena to empty by setting pos back to 0.

All previously returned pointers are invalidated. Physical RAM remains committed the next allocations are as fast as before. This is the idiomatic per-frame reset.

Parameters

arena

Pointer to the arena.

Definition at line 117 of file mem_arena.c.

Here is the call graph for this function:

arena_create()

Arena arena_create

(

usize

reserve_size

)

Creates and initializes a new arena, reserving virtual address space.

No physical RAM is consumed until the first allocation. The reserve_size may safely be set to the maximum you could ever need (e.g., GB(1)) since reservation is essentially free.

Parameters

reserve_size

Maximum capacity of the arena in bytes.

Returns

An initialized Arena. On failure, arena.base will be NULL.

Definition at line 60 of file mem_arena.c.

Here is the call graph for this function:

arena_pop_to()

void arena_pop_to	(	Arena *	arena,
		usize	pos )

Rolls the arena back to a specific byte offset.

All memory at or above pos is considered freed. The committed physical RAM is not returned to the OS it stays mapped for future allocations.

Note

Prefer ArenaTemp / arena_temp_end() for scoped rollbacks.

Parameters

arena	Pointer to the arena.
pos	Target offset. Clamped to the current pos if larger.

Definition at line 109 of file mem_arena.c.

Here is the caller graph for this function:

arena_push()

void * arena_push	(	Arena *	arena,
		usize	size )

Allocates size bytes from the arena, aligned to ARENA_DEFAULT_ALIGN.

Physical RAM is committed in ARENA_COMMIT_SIZE chunks as needed. In debug builds, exceeding the capacity or a commit failure triggers ASSERT. In release builds, NULL is returned on failure always check the result when size is large or dynamic.

Parameters

arena	Pointer to the arena.
size	Number of bytes to allocate.

Returns

Pointer to the allocated block, or NULL on OOM.

Definition at line 83 of file mem_arena.c.

Here is the call graph for this function:

arena_push_aligned()

void * arena_push_aligned	(	Arena *	arena,
		usize	size,
		usize	alignment )

Allocates size bytes from the arena with an explicit power-of-2 alignment.

Use this when allocating data that requires alignment stricter than ARENA_DEFAULT_ALIGN, such as SIMD vectors (16 or 32 bytes) or GPU-mapped buffers. The returned pointer is zeroed.

Parameters

arena	Pointer to the arena.
size	Number of bytes to allocate.
alignment	Alignment in bytes. Must be a power of 2 (e.g., 16, 32, 64).

Returns

Pointer to the aligned, zeroed block, or NULL on OOM.

Definition at line 99 of file mem_arena.c.

Here is the call graph for this function:

arena_push_zero()

void * arena_push_zero	(	Arena *	arena,
		usize	size )

Allocates size bytes from the arena, zeroed, aligned to ARENA_DEFAULT_ALIGN.

Equivalent to arena_push() followed by memset(result, 0, size). Prefer this over arena_push() unless you are about to overwrite the entire allocation.

Parameters

arena	Pointer to the arena.
size	Number of bytes to allocate and zero.

Returns

Pointer to the zeroed block, or NULL on OOM.

Definition at line 89 of file mem_arena.c.

Here is the call graph for this function:

arena_release()

void arena_release

(

Arena *

arena

)

Releases the entire arena back to the OS, invalidating all pointers into it.

Warning

Every pointer previously returned by arena_push*() becomes invalid.

Parameters

arena

Pointer to the arena to destroy.

Definition at line 71 of file mem_arena.c.

Here is the call graph for this function:

arena_temp_begin()

ArenaTemp arena_temp_begin

(

Arena *

arena

)

Saves the current arena position as a rewind checkpoint.

Parameters

arena

Pointer to the arena to checkpoint.

Returns

An ArenaTemp holding the arena pointer and the saved position.

Definition at line 123 of file mem_arena.c.

arena_temp_end()

void arena_temp_end

(

ArenaTemp

temp

)

Restores the arena to the position saved in temp.

All allocations made after the corresponding arena_temp_begin() call are effectively freed. The physical RAM remains committed.

Parameters

temp	The checkpoint returned by arena_temp_begin().

Definition at line 132 of file mem_arena.c.

Here is the call graph for this function: