Arenas

Region-oriented allocation primitives used by the default memory wrappers and by callers that need deterministic allocation behavior. More...

Collaboration diagram for Arenas:

Data Structures
struct	sys_mem_stats_t
	Snapshot of arena usage statistics. More...

Typedefs
typedef struct sys_mem_arena_t	sys_mem_arena_t
	Arena allocator handle.
typedef struct sys_mem_stats_t	sys_mem_stats_t
	Snapshot of arena usage statistics.

Arena Lifecycle
sys_mem_arena_t *	sys_mem_arena_init (size_t size, sys_mem_arena_t *prev, void *(*malloc_fn)(size_t size), void(*free_fn)(void *ptr))
	Initialize a new arena. More...
void	sys_mem_arena_delete (sys_mem_arena_t *arena)
	Delete the tail arena of a chain. More...
sys_mem_arena_t *	sys_mem_arena_next (sys_mem_arena_t *arena, sys_mem_stats_t *stats)
	Return the next arena in a chain. More...

Arena Allocation
void *	sys_mem_arena_alloc (sys_mem_arena_t *arena, size_t size)
	Allocate memory from a single arena. More...
void *	sys_mem_arena_realloc (sys_mem_arena_t *arena, void *ptr, size_t size)
	Resize an allocation within a single arena. More...
void	sys_mem_arena_free (sys_mem_arena_t *arena, void *ptr)
	Release an allocation owned by a single arena. More...

Detailed Description

Region-oriented allocation primitives used by the default memory wrappers and by callers that need deterministic allocation behavior.

The arena API provides region-oriented allocation primitives used by the default memory wrappers and by callers that need deterministic allocation behavior.

Arenas can be chained to grow capacity incrementally while preserving locality and ownership boundaries. Allocation/reallocation/free operations in this header operate on the supplied arena only; they do not traverse successor arenas unless explicitly done by higher-level logic.

Thread safety:

• All operations on a given arena (including chain-growing calls to sys_mem_arena_init() that pass it as prev) are safe to call concurrently from multiple threads or cores.

Alignment:

• sys_mem_arena_alloc() and sys_mem_arena_realloc() return memory aligned suitably for any object type (the same guarantee malloc() makes), regardless of the requested size.

Typical flow:

1. Create an arena with sys_mem_arena_init(...).
2. Allocate/reallocate/free within that arena.
3. Optionally walk the chain with sys_mem_arena_next(...).
4. Delete arenas with sys_mem_arena_delete(...), tail first.

Function Documentation

sys_mem_arena_alloc()

void* sys_mem_arena_alloc	(	sys_mem_arena_t *	arena,
		size_t	size
	)

Allocate memory from a single arena.

Parameters

arena	Arena that services the allocation request.
size	Number of bytes to allocate.

Returns

Pointer to the allocated block, aligned suitably for any object type, or NULL on failure.

This function operates only on the supplied arena and does not traverse any linked successor arenas.

sys_mem_arena_delete()

void sys_mem_arena_delete

(

sys_mem_arena_t *

arena

)

Delete the tail arena of a chain.

Parameters

arena

The tail arena to delete. Must be non-NULL, and must be the last arena in its chain (sys_mem_arena_next(arena, NULL) must return NULL) - deleting a non-tail arena is invalid.

Releases arena back to its underlying allocator. To fully tear down a chain, delete arenas from the tail backward (LIFO order): the arena that was passed as prev when arena was created becomes the new tail.

sys_mem_arena_free()

void sys_mem_arena_free	(	sys_mem_arena_t *	arena,
		void *	ptr
	)

Release an allocation owned by a single arena.

Parameters

arena	Arena that owns the allocation.
ptr	Allocation to release, or NULL.

This function operates only on the supplied arena and does not traverse any linked successor arenas.

sys_mem_arena_init()

sys_mem_arena_t* sys_mem_arena_init	(	size_t	size,
		sys_mem_arena_t *	prev,
		void *(*)(size_t size)	malloc_fn,
		void(*)(void *ptr)	free_fn
	)

Initialize a new arena.

Parameters

size	Arena size in bytes.
prev	Pointer to the previous (tail) arena, or NULL to start a new chain.
malloc_fn	Underlying allocation function. Must be non-NULL when prev is NULL, and must be NULL when prev is non-NULL.
free_fn	Underlying deallocation function. Must be non-NULL when prev is NULL, and must be NULL when prev is non-NULL.

Returns

Pointer to the newly initialized arena, or NULL on failure.

When creating the first arena in a chain, pass prev as NULL along with malloc_fn/free_fn pointing to the underlying allocator implementation to use. When appending to an existing chain, pass prev as the chain's current tail (see sys_mem_arena_next()) and pass NULL for both malloc_fn and free_fn - the new arena inherits prev's allocator.

Returns NULL if prev is non-NULL and is not the chain's tail, if malloc_fn/free_fn don't follow the NULL-pairing rule above, or if the underlying allocation fails.

sys_mem_arena_next()

sys_mem_arena_t* sys_mem_arena_next	(	sys_mem_arena_t *	arena,
		sys_mem_stats_t *	stats
	)

Return the next arena in a chain.

Parameters

arena	Pointer to the current arena.
stats	Optional pointer populated with stats for arena when non-NULL.

Returns

Pointer to the next (more recently appended) arena, or NULL when arena is the tail.

sys_mem_arena_realloc()

void* sys_mem_arena_realloc	(	sys_mem_arena_t *	arena,
		void *	ptr,
		size_t	size
	)

Resize an allocation within a single arena.

Parameters

arena	Arena that owns the allocation.
ptr	Existing allocation to resize, or NULL.
size	New size in bytes.

Returns

Pointer to the resized block, aligned suitably for any object type, or NULL on failure.

This function operates only on the supplied arena and does not traverse any linked successor arenas.