arena
Memory allocators - arena, bump, object pool, fixed-size block, stack, mmap, region, and scratch space.
Load with: use arena
What this module does
arena provides manual memory allocation strategies for when you need predictable
allocation patterns and explicit control over memory lifetime. None of these are garbage collected -
you allocate, use, then reset or free explicitly.
Most functions here are overloaded - arena(), block(), stack(),
regio(), and scrat() each have multiple signatures that do different things
depending on what arguments you pass.
Functions
Arena allocator
An arena allocates from a fixed-size buffer. All allocations are 8-byte aligned. Reset to reuse the memory without individual frees.
arena(size)
Creates a new arena with a buffer of size bytes. Returns an arena object with buffer, size, offset, objects, and freed fields.
arena(arena, bytes)
Allocates bytes from the arena (aligned to 8 bytes). Returns a pointer. Errors if the arena is already freed or out of memory.
arena(size, alignment)
Aligns size up to the nearest multiple of alignment. Returns the aligned size.
arena(arena)
Resets the arena - sets offset back to 0, clears object list, and zeroes the buffer. Memory is reusable without reallocation.
arena(arena)
Frees the arena's underlying buffer and marks it as freed. All pointers into it become invalid.
arena(type_size, capacity)
Creates a typed arena that holds up to capacity objects of type_size bytes each.
arena(typed_arena)
Allocates one slot from a typed arena. Returns a {ptr, index} object.
arena(typed_arena, index)
Returns a pointer to the object at the given index in a typed arena. Errors if out of bounds.
Bump allocator
A bump allocator is the simplest possible allocator - allocations just increment a head pointer. Reset to reuse everything at once.
bumpn(size)
Creates a new bump allocator with a buffer of size bytes.
bumpa(bump, size)
Allocates size bytes (8-byte aligned) from the bump allocator. Errors if exhausted.
bumpr(bump)
Resets the bump allocator - head goes back to 0 and the buffer is zeroed.
bumpf(bump)
Frees the bump allocator's buffer entirely.
Object pool
An object pool recycles objects rather than allocating new ones. Good for frequently created and destroyed objects.
pooln(constructor, reset_fn, initial_capacity)
Creates an object pool with a constructor function, a reset function (called before reuse), and an initial capacity hint.
poolg(pool)
Gets an object from the pool. Returns an available object (after resetting it) if one exists, or calls the constructor to create a new one.
poolr(pool, obj)
Returns an object back to the pool's available list.
pools(pool)
Returns pool stats: {available, in_use, total_allocated, capacity}.
pools(pool)
Shrinks the available list back down to capacity if it has grown too large.
Fixed-size block allocator
Allocates fixed-size blocks from a bitmap-tracked pool. O(n) allocation but zero fragmentation.
block(block_size, block_count)
Creates a block allocator with block_count blocks of block_size bytes each. Initialises a bitmap (0 = free, 1 = used).
block(block_pool)
Allocates the first free block. Returns a pointer to it. Errors if all blocks are in use.
block(block_pool, ptr)
Frees the block at ptr - calculates its index from the pointer offset, marks it free in the bitmap, and zeroes its memory.
block(block_pool)
Returns stats: {total, used, free, utilization}.
Stack allocator
Allocates from a stack - supports markers to restore the stack to a previous position.
stack(size)
Creates a stack allocator with a buffer of size bytes.
stack(stack, data)
Pushes data onto the stack. Errors if it would overflow.
stack(stack, size)
Pops size bytes off the top of the stack. Errors on underflow.
stack(stack)
Sets a marker at the current stack top. Returns the marker index.
stack(stack, mark)
Restores the stack to a previous marker position, discarding everything allocated after it.
Memory-mapped arena
Arena backed by mmap - pages are committed on demand.
mmapn(size, options)
Creates an mmap-backed arena reserving size bytes of virtual address space.
mmapc(mmap, size)
Commits size bytes of physical memory within the arena.
mmapa(mmap, bytes)
Allocates bytes from the mmap arena, auto-committing more pages if needed (aligned to 4096 bytes).
mmapf(mmap)
Unmaps the arena and frees the virtual address space.
Region allocator
A region allocator manages a list of arenas, adding new ones as needed. Free the whole region at once.
regio()
Creates a new region. Starts with no arenas; will allocate 64KB arenas on demand.
regio(regin, size)
Allocates size bytes from the region. Creates a new 64KB arena if the current one is full.
regio(regin)
Frees all arenas in the region and resets it.
regio(regin)
Returns stats: {arenas, total_allocated, current_arena_used, current_arena_size}.
Scratch space
Temporary scratch allocator with checkpoint/restore - allocate, use, restore to checkpoint to reclaim.
scrat(size)
Creates a scratch space backed by an arena of size bytes.
scrat(scratch)
Saves the current allocation offset as a checkpoint.
scrat(scratch, bytes)
Allocates bytes from the scratch space.
scrat(scratch)
Restores the scratch space to the last checkpoint, reclaiming all allocations made since.
scrat(scratch)
Frees the underlying arena entirely.
Notes
- None of these allocators are garbage collected. You must reset or free explicitly.
- Most function names are heavily overloaded - which overload runs depends on the number and types of arguments.
- All allocations are 8-byte aligned by default. The mmap arena auto-commits in 4096-byte page increments.