`arn`

Arena allocators, bump allocators, object pools, fixed-size block allocators, stack allocators, mmap arenas, regions, and scratch space.

Load with: use arn

What this module does

arn provides the same family of manual memory allocation strategies as arena, but with distinct, non-overloaded function names for each operation. This makes it easier to use without needing to track which overload fires - each allocator type has its own clearly named create/allocate/reset/free functions.

None of these are garbage collected. You must reset or free explicitly. All allocations are 8-byte aligned by default. The mmap arena commits in 4096-byte page increments.

Quick example

use arn

# Create a 1MB arena
a = arnmk(1048576)

# Allocate from it
ptr = arnal(a, 64)

# Reset (reuse all memory)
arnrs(a)

# Free when done
arnfr(a)

Functions

Arena allocator

arnmk(size)

Creates a new arena backed by a __arn_alloc buffer of size bytes. Returns an arena object with buffer, size, offset (starts at 0), objects (empty list), and freed: fls.

arnal(arena, bytes)

Allocates bytes from the arena (8-byte aligned via arnaln). Errors if the arena is freed or out of memory. Returns a pointer.

arnln(size, alignment)

Aligns size up to the nearest multiple of alignment. Returns the aligned size.

arnrs(arena)

Resets the arena: sets offset to 0, clears the objects list, and zeroes the buffer. The memory is immediately reusable.

arnfr(arena)

Frees the arena's backing buffer and marks it as freed. All pointers into it become invalid.

arnmk(type_size, capacity)

Creates a typed arena for exactly capacity objects of type_size bytes each. Adds type_size and count fields.

arnal(typed_arena)

Allocates one slot from a typed arena. Returns {ptr, index}.

arnal(typed_arena, index)

Returns a pointer to the slot at index. Errors if out of bounds.

Bump allocator

bmpmk(size)

Creates a bump allocator with a buffer of size bytes.

bumpl(bump, size)

Allocates size bytes (8-byte aligned) by bumping the head pointer. Errors if exhausted.

bmprs(bump)

Resets the head to 0, clears the allocation list, and zeroes the buffer.

bmpfr(bump)

Frees the bump allocator's buffer.

Object pool

polmk(constructor, reset_fn, initial_capacity)

Creates an object pool. constructor is called to make new objects; reset_fn is called on objects before they are reused. Unlike the arena module's pool, this one uses a plain integer for in_use rather than a pointer.

polgt(pool)

Gets an object. Returns an available object after resetting it, or calls the constructor if none are available (falls back to {} if constructor is nil).

polrt(pool, obj)

Returns an object to the pool's available list.

polst(pool)

Returns pool stats: {available, in_use, total_allocated, capacity}.

polsh(pool)

Trims the available list back down to capacity if it has grown too large.

Fixed-size block allocator

blckm(block_size, block_count)

Creates a block allocator with block_count fixed-size blocks. Maintains a bitmap (0 = free, 1 = used).

blckl(block_pool)

Allocates the first free block (linear scan). Errors with "no free blocks in pool" if all are used.

blckf(block_pool, ptr)

Frees the block at ptr - computes the block index from the pointer offset, clears the bitmap bit, and zeroes the block.

blcks(block_pool)

Returns stats: {total, used, free, utilization}.

Stack allocator

stckm(size)

Creates a stack allocator with a buffer of size bytes. Also overloaded: stckm(stack) sets a marker at the current top and returns the marker index.

stckl(stack, data, data_size)

Pushes data_size bytes of data onto the stack. Errors on overflow.

stckp(stack, size)

Pops size bytes off the top. Errors on underflow.

stckr(stack, mark)

Restores the stack to a previous marker, discarding all allocations after it.

Memory-mapped arena

mmpmk(size, options)

Creates an mmap-backed arena reserving size bytes of virtual address space.

mmpcm(mmap, size)

Commits size bytes of physical pages within the arena.

mmapl(mmap, bytes)

Allocates bytes, auto-committing more pages (aligned to 4096) if needed.

mmpfr(mmap)

Unmaps and frees the arena.

Region allocator

regin()

Creates a new region. Starts empty; allocates 64KB arenas on demand.

regnl(regin, size)

Allocates size bytes from the region. Adds a new 64KB arena if the current one is full.

rgnfr(regin)

Frees all arenas in the region and resets it.

rgnst(regin)

Returns stats: {arns, total_allocated, current_arn_used, current_arn_size}.

Scratch space

scrt1(size)

Creates a scratch space backed by an arena.

scrt3(scratch)

Saves the current offset as a checkpoint.

scrtc(scratch, bytes)

Allocates bytes from the scratch arena.

scrt2(scratch)

Restores to the last checkpoint, reclaiming all allocations since.

scrt0(scratch)

Frees the scratch arena entirely.

Notes

arn and arena provide the same allocator family - arn uses distinct names per operation while arena uses overloaded names. Use whichever is clearer in context.
All allocations are 8-byte aligned by default via arnaln.
The scratch space numbering (scrt0–scrt3) encodes the operation: 0 = free, 1 = create, 2 = restore, 3 = checkpoint.
Requires trl, txt, and mem.