memory.h File Reference

Arena allocator and growable array utilities for fast memory management. More...

#include <stdalign.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdnoreturn.h>

Include dependency graph for memory.h:

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

Go to the source code of this file.

Classes
struct	Buffer
	Represents a memory buffer in the arena. More...
struct	ArenaAllocator
	Arena allocator structure. More...
struct	GrowableArray
	Growable array backed by an arena allocator. More...

Macros
#define	ARENA_MIN_BUFFER_SIZE   (64 * 1024)
	Minimum size of a newly allocated arena buffer in bytes.
#define	ARENA_GROWTH_FACTOR   2
	Factor by which buffer size grows when more space is needed.
#define	ARENA_MAX_BUFFER_SIZE   (16 * 1024 * 1024)
	Maximum size of an arena buffer in bytes.
#define	DEBUG_PRINT(...)   ((void)0)
	Enable to print debug allocation logs.
#define	TRACK_ALLOC(ptr)   ((void)0)
#define	TRACK_FREE(ptr)   ((void)0)

Typedefs
typedef struct Buffer	Buffer
	Represents a memory buffer in the arena.
typedef struct ArenaAllocator	ArenaAllocator
	Arena allocator structure.

Functions
Buffer *	buffer_create (size_t s, size_t alignment)
	Creates a new buffer with given size and alignment.
int	arena_allocator_init (ArenaAllocator *arena, size_t initial_size)
	Initializes an arena allocator.
void *	arena_alloc (ArenaAllocator *arena, size_t size, size_t alignment)
	Allocates memory from the arena.
void *	arena_realloc (ArenaAllocator *arena, void *ptr, size_t old_size, size_t new_size, size_t alignment)
	Reallocates memory from the arena allocator.
void	arena_reset (ArenaAllocator *arena)
	Resets the arena, keeping buffers but making them empty.
void	arena_destroy (ArenaAllocator *arena)
	Frees all memory used by the arena.
char *	arena_strdup (ArenaAllocator *arena, const char *str)
	Duplicates a string into arena-managed memory.
void	arena_print_stats (ArenaAllocator *arena)
	Prints statistics about arena memory usage.
size_t	arena_get_total_allocated (ArenaAllocator *arena)
	Gets the total number of bytes allocated across all buffers.
bool	growable_array_init (GrowableArray *arr, ArenaAllocator *arena, size_t initial_capacity, size_t item_size)
	Initializes a growable array using an arena allocator.
void *	growable_array_push (GrowableArray *arr)
	Pushes a new element onto the growable array.
noreturn void	die (const char *fmt,...)
	Prints a fatal error message and exits the program.
void *	xmalloc (size_t size)
	Allocates memory and checks for allocation failure. If !size it will still return a valid pointer that can be freed.
void *	xcalloc (size_t nr, size_t size)
	Allocates zero-init memory and checks for allocation failure. If !size it will still return a valid pointer.
char *	xstrdup (const char *str)
	Duplicates a string and checks for allocation failure.

Detailed Description

Arena allocator and growable array utilities for fast memory management.

This module implements a simple arena (region) allocator and a growable array type that uses the arena for storage. The arena allocator reduces allocation overhead by allocating large memory blocks ("buffers") at once and serving allocations sequentially from them.

Overview

• ArenaAllocator: Allocates memory from contiguous blocks (buffers).
• GrowableArray: A dynamic array that stores items in arena-allocated memory.

Features

• Minimal malloc/free calls.
• Custom growth strategy for buffers.
• Reset all allocations at once (fast memory recycling).
• Optional debug tracking of active buffers.

Flow Diagram

Macro Definition Documentation

ARENA_GROWTH_FACTOR

#define ARENA_GROWTH_FACTOR   2

Factor by which buffer size grows when more space is needed.

ARENA_MAX_BUFFER_SIZE

#define ARENA_MAX_BUFFER_SIZE   (16 * 1024 * 1024)

Maximum size of an arena buffer in bytes.

ARENA_MIN_BUFFER_SIZE

#define ARENA_MIN_BUFFER_SIZE   (64 * 1024)

Minimum size of a newly allocated arena buffer in bytes.

DEBUG_PRINT

#define DEBUG_PRINT

(

...

)

((void)0)

Enable to print debug allocation logs.

TRACK_ALLOC

#define TRACK_ALLOC

(

ptr

)

((void)0)

TRACK_FREE

#define TRACK_FREE

(

ptr

)

((void)0)

Typedef Documentation

ArenaAllocator

typedef struct ArenaAllocator ArenaAllocator

Arena allocator structure.

Buffer

typedef struct Buffer Buffer

Represents a memory buffer in the arena.

Function Documentation

arena_alloc()

void * arena_alloc	(	ArenaAllocator *	arena,
		size_t	size,
		size_t	alignment
	)

Allocates memory from the arena.

Parameters

arena	Pointer to the arena.
size	Number of bytes to allocate.
alignment	Memory alignment in bytes.

Returns

Pointer to allocated memory, or NULL on failure.

Allocates memory from the arena.

Attempts to allocate aligned memory from current buffers. If insufficient space, it moves to the next buffer or allocates a new one.

Large allocations create dedicated buffers.

Parameters

arena	Pointer to the ArenaAllocator.
size	Number of bytes to allocate.
alignment	Memory alignment requirement.

Returns

Pointer to allocated memory or NULL on failure.

arena_allocator_init()

int arena_allocator_init	(	ArenaAllocator *	arena,
		size_t	initial_size
	)

Initializes an arena allocator.

Parameters

arena	Pointer to the arena to initialize.
initial_size	Initial size of the first buffer.

Returns

0 on success, non-zero on error.

Initializes an arena allocator.

Allocates the first buffer and sets initial parameters.

Parameters

arena	Pointer to the ArenaAllocator to initialize.
initial_size	Initial buffer size to allocate (will be clamped to minimum size).

Returns

0 on success, -1 on failure.

arena_destroy()

void arena_destroy

(

ArenaAllocator *

arena

)

Frees all memory used by the arena.

Parameters

arena

Pointer to the arena to destroy.

Frees all memory used by the arena.

Parameters

arena

Pointer to the ArenaAllocator to destroy.

arena_get_total_allocated()

size_t arena_get_total_allocated

(

ArenaAllocator *

arena

)

Gets the total number of bytes allocated across all buffers.

Parameters

arena

Pointer to the arena.

Returns

Total allocated bytes.

Gets the total number of bytes allocated across all buffers.

Parameters

arena

Pointer to the ArenaAllocator.

Returns

Total allocated bytes, or 0 if arena is NULL.

arena_print_stats()

void arena_print_stats

(

ArenaAllocator *

arena

)

Prints statistics about arena memory usage.

Parameters

arena

Pointer to the arena.

Prints statistics about arena memory usage.

Includes number of buffers, total allocated memory, current buffer and offset, and the planned size for the next buffer.

Parameters

arena

Pointer to the ArenaAllocator.

arena_realloc()

void * arena_realloc	(	ArenaAllocator *	arena,
		void *	ptr,
		size_t	old_size,
		size_t	new_size,
		size_t	alignment
	)

Reallocates memory from the arena allocator.

WARNING: This implementation has limitations due to arena allocator design:

• Can only shrink or grow the MOST RECENTLY allocated block in the current buffer
• Cannot reclaim space from shrunk allocations
• Falls back to allocate-and-copy for other cases

Parameters

arena	Pointer to the ArenaAllocator.
ptr	Pointer to previously allocated memory (can be NULL).
old_size	Size of the previous allocation (required for validation).
new_size	New size requested.
alignment	Memory alignment requirement.

Returns

Pointer to reallocated memory or NULL on failure.

arena_reset()

void arena_reset

(

ArenaAllocator *

arena

)

Resets the arena, keeping buffers but making them empty.

Parameters

arena

Pointer to the arena to reset.

Resets the arena, keeping buffers but making them empty.

Does not free memory; resets the current allocation offset and buffer pointer.

Parameters

arena

Pointer to the ArenaAllocator to reset.

arena_strdup()

char * arena_strdup	(	ArenaAllocator *	arena,
		const char *	src
	)

Duplicates a string into arena-managed memory.

Parameters

arena	Pointer to the arena.
str	String to duplicate.

Returns

Pointer to the duplicated string in arena memory.

Duplicates a string into arena-managed memory.

Parameters

arena	Pointer to the ArenaAllocator.
src	Null-terminated source string.

Returns

Pointer to the duplicated string in arena memory, or NULL on failure.

buffer_create()

Buffer * buffer_create	(	size_t	s,
		size_t	alignment
	)

Creates a new buffer with given size and alignment.

Parameters

s	Buffer size in bytes.
alignment	Memory alignment in bytes.

Returns

Pointer to the newly created buffer or NULL on failure.

Creates a new buffer with given size and alignment.

Allocates memory for a Buffer struct plus usable space aligned according to the alignment.

Parameters

s	Size of usable memory requested.s
alignment	Alignment requirement for the usable memory.

Returns

Pointer to the new Buffer on success, or NULL on failure.

die()

noreturn void die	(	const char *	fmt,
			...
	)

Prints a fatal error message and exits the program.

Parameters

fmt	Format string for the error message.
...	Additional arguments for the format string.

growable_array_init()

bool growable_array_init	(	GrowableArray *	arr,
		ArenaAllocator *	arena,
		size_t	initial_capacity,
		size_t	item_size
	)

Initializes a growable array using an arena allocator.

Parameters

arr	Pointer to the GrowableArray to initialize.
arena	Pointer to the arena allocator for storage.
initial_capacity	Initial element capacity.
item_size	Size of each array element in bytes.

Returns

true on success, false on failure.

Initializes a growable array using an arena allocator.

Allocates initial storage for the array and sets metadata.

Parameters

arr	Pointer to the GrowableArray to initialize.
arena	Pointer to the ArenaAllocator for backing storage.
initial_capacity	Initial number of elements to allocate space for.
item_size	Size in bytes of each element.

Returns

true on success, false on failure.

growable_array_push()

void * growable_array_push

(

GrowableArray *

arr

)

Pushes a new element onto the growable array.

Parameters

arr	Pointer to the GrowableArray.

Returns

Pointer to the new element's memory slot.

Pushes a new element onto the growable array.

Automatically doubles the array capacity and copies existing elements into new arena memory when full.

Parameters

arr	Pointer to the GrowableArray.

Returns

Pointer to the newly allocated element slot, or NULL on failure.

xcalloc()

void * xcalloc	(	size_t	nr,
		size_t	size
	)

Allocates zero-init memory and checks for allocation failure. If !size it will still return a valid pointer.

Parameters

nr	Number of elements to allocate.
size	Size of each element.

Returns

Pointer to the allocated memory on success.

xmalloc()

void * xmalloc

(

size_t

size

)

Allocates memory and checks for allocation failure. If !size it will still return a valid pointer that can be freed.

Parameters

size	Number of bytes to allocate.

Returns

Pointer to the allocated memory on success.

xstrdup()

char * xstrdup

(

const char *

str

)

Duplicates a string and checks for allocation failure.

Parameters

str	The string to duplicate.

Returns

Pointer to the duplicated string on success.