stdx_arena.h

home

STDX - Arena Allocator Part of the STDX General Purpose C Library by marciovmf License: MIT https://github.com/marciovmf/stdx

Overview

Minimal, cache-friendly bump allocator with chunk growth, alignment, fast O(1) steady-state allocations, optional marks (scoped rewinds), and trimming APIs to keep memory bounded after spikes.

How to compile

To compile the implementation define X_IMPL_ARENA in one source file before including this header.

To customize how this module allocates memory, define X_ARENA_ALLOC / X_ARENA_FREE before including.

Macro

X_ARENA_VERSION_MAJOR

#define X_ARENA_VERSION_MAJOR 1
Macro

X_ARENA_VERSION_MINOR

#define X_ARENA_VERSION_MINOR 0
Macro

X_ARENA_VERSION_PATCH

#define X_ARENA_VERSION_PATCH 0
Struct

XArenaChunk

typedef struct XArenaChunk XArenaChunk;
Struct

XArena

Arena

typedef struct XArena{
  size_t chunk_size;
  XArenaChunk *chunks;
  XArenaChunk *current;
}XArena;
Struct

XArenaMark

A mark is a lightweight snapshot for scoped unwinds.

typedef struct XArenaMark{
  XArenaChunk *chunk;
  size_t used;
}XArenaMark;
Function

x_arena_create

Create a new arena with the given default chunk size.

X_ARENA_API XArena * x_arena_create(size_t chunk_size);

Returns

pointer to the new arena or NULL if creation fails

Function

x_arena_destroy

Destroy the arena and free all memory.

X_ARENA_API void x_arena_destroy(XArena *arena);

Parameters

XArena *arena
The arena to destroy.
Function

x_arena_reset

Reset the arena: keep all chunks, set used = 0.

X_ARENA_API void x_arena_reset(XArena *arena);

Parameters

XArena *arena
The arena to reset.
Function

x_arena_reset_keep_head

Keep only the head chunk, free the rest.

X_ARENA_API void x_arena_reset_keep_head(XArena *arena);

Parameters

XArena *arena
The arena to reset.
Function

x_arena_trim

Keep the first `keep_n` chunks, free the rest.

X_ARENA_API void x_arena_trim(
 XArena *arena,
 size_t keep_n
);

Parameters

XArena *arena
The arena to trim.
size_t keep_n
The number of chuncks to preserve.
Function

x_arena_alloc

Allocate memory from the arena (aligned to X_ARENA_ALIGN).

X_ARENA_API void * x_arena_alloc(
 XArena *arena,
 size_t size
);

Parameters

XArena *arena
The arena to alloc from.
size_t size
The size in bytes to alloc.

Returns

Pointer to the allocated memory region

Function

x_arena_alloc_zero

Allocate zero-initialized memory from the arena.

X_ARENA_API void * x_arena_alloc_zero(
 XArena *arena,
 size_t size
);

Parameters

XArena *arena
The arena to alloc from.
size_t size
The size in bytes to alloc.

Returns

Pointer to the allocated memory region

Function

x_arena_strdup

Duplicate a C-string into the arena.

X_ARENA_API char * x_arena_strdup(
 XArena *arena,
 const char *cstr
);

Parameters

XArena *arena
The arena to allocate string from.
const char *cstr
Pointer to a c string to duplicate into the arena.

Returns

Pointer to the allocated memory region

Function

x_arena_slicedup

Duplicate a slice into the arena.

X_ARENA_API char * x_arena_slicedup(
 XArena *arena,
 const char *ptr,
 size_t len,
 bool null_terminate
);

Parameters

XArena *arena
The arena to allocate string from.
const char *ptr
Pointer to a beggining of the data to duplicate into the arena.
size_t len
How much data to copy from `ptr` into the arena.

Returns

Pointer to the allocated memory region

Function

x_arena_mark

Makes a snapshot of the arena state.

X_ARENA_API XArenaMark x_arena_mark(XArena *arena);

Parameters

XArena *arena
The arena to take snapshot from.

Returns

A snapshot of the current arena state.

Function

x_arena_release

Rewind the arena to a previous mark (frees newer chunks).

X_ARENA_API void x_arena_release(
 XArena *arena,
 XArenaMark mark
);

Parameters

XArena *arena
The arena to apply the snapshot.
XArenaMark mark
The snapshot to apply.
Function

x_arena_has_pointer

checks if a pointer points to arena owned memory

X_ARENA_API bool x_arena_has_pointer(
 const XArena *arena,
 void *ptr
);

Parameters

const XArena *arena
The arena to check for pointer ownership
void *ptr
The pointer to check

Returns

true if ptr points to an address owned by the arena.

Macro

X_ARENA_ALLOC

Internal macro for allocating memory. To override how this header allocates memory, define this macro with a different implementation before including this header.

#define X_ARENA_ALLOC(sz) malloc((sz))

Parameters

sz
The size of memory to alloc.
Macro

X_ARENA_FREE

Internal macro for freeing memory. To override how this header frees memory, define this macro with a different implementation before including this header.

#define X_ARENA_FREE(p) free((p))

Parameters

p
The address of memory region to free.
Macro

X_ARENA_ALIGN

#define X_ARENA_ALIGN(sizeof(void *)>sizeof(double)?sizeof(void *):sizeof(double))
Macro

X_ARENA_DEBUG_FILL

#define X_ARENA_DEBUG_FILL 0xDD
Function

x_arena_chunk_count

size_t x_arena_chunk_count(const XArena *a);
Function

x_arena_head_capacity

size_t x_arena_head_capacity(const XArena *a);
Function

x_arena_head_used

size_t x_arena_head_used(const XArena *a);