mem_arena.h File Reference

High-performance Virtual Memory Linear (Arena) Allocator. More...

#include "base/base_macros.h"
#include "base/base_types.h"

Include dependency graph for mem_arena.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

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

High-performance Virtual Memory Linear (Arena) Allocator.

Allocates memory by linearly advancing an offset (pos) within a large reserved virtual memory block. Physical RAM is committed from the OS automatically in 64 KB chunks as the pos grows you only pay for what you actually use.

Allocation model

This is a linear allocator (also called a bump allocator). Individual allocations cannot be freed independently. Instead, memory is reclaimed in bulk either by resetting pos to a saved checkpoint (ArenaTemp) or by clearing the entire arena (arena_clear()).

This makes it ideal for:

• Per-frame scratch memory (reset at end of frame with arena_clear()).
• Temporary work buffers scoped to a function (save/restore with ArenaTemp).
• Any workload with a clear "allocate a lot, then free everything" lifecycle.

Basic Usage

// Create a 1 GB arena (reserves address space; no physical RAM used yet).
Arena arena = arena_create(GB(1));
 
// Allocate a single struct (zeroed).
MyStruct *s = PUSH_STRUCT(&arena, MyStruct);
s->x = 10;
 
// Allocate an array of 64 floats (zeroed).
float *buf = PUSH_ARRAY(&arena, float, 64);
 
// Allocate with explicit 16-byte alignment (e.g., for SIMD).
float *simd_buf = PUSH_ARRAY_ALIGNED(&arena, float, 64, 16);
 
// Scoped temporary memory: save pos, do work, restore.
ArenaTemp tmp = arena_temp_begin(&arena);
char *scratch = PUSH_ARRAY(&arena, char, 4096);
// ... use scratch ...
arena_temp_end(tmp); // arena returns to state before arena_temp_begin()
 
// Per-frame reset: free all allocations at once.
arena_clear(&arena);
 
// Release all virtual memory back to the OS when done.
arena_release(&arena);

Copyright

2025 Alfred Jijo (MIT License)

Definition in file mem_arena.h.