#include "vl_set.h"

Include dependency graph for vl_arena.h:

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

Data Structures
struct	vl_arena
	An arena allocator. More...

Macros
#define	VL_ARENA_NULL 0
	An explicit NULL integer constant that indicates a bad location in an arena.

Typedefs
typedef vl_uintptr_t	vl_arena_ptr

Functions
void	vlArenaInit (vl_arena *arena, vl_memsize_t initialSize)
	Initializes the vl_arena structure with the given initial size.

void	vlArenaFree (vl_arena *arena)
	Frees memory allocated by an arena instance.

vl_arena *	vlArenaNew (vl_memsize_t initialSize)
	Creates a new arena with the specified initial size.

void	vlArenaDelete (vl_arena *arena)
	Deletes the given VL arena, freeing all allocated memory.

void	vlArenaClear (vl_arena *arena)
	Clears all the elements in the given arena.

vl_arena *	vlArenaClone (const vl_arena src, vl_arena dest)
	Clones the specified arena to another.

void	vlArenaReserve (vl_arena *arena, vl_memsize_t numBytes)
	Reserves storage in the underlying allocation of the given arena.

vl_arena_ptr	vlArenaMemAlloc (vl_arena *arena, vl_memsize_t size)
	Take memory from the given arena.

vl_arena_ptr	vlArenaMemRealloc (vl_arena *arena, vl_arena_ptr ptr, vl_memsize_t size)
	Reallocates memory for the given pointer in the given arena.

void	vlArenaMemFree (vl_arena *arena, vl_arena_ptr ptr)
	Frees a memory block allocated in a vl_arena.

vl_arena_ptr	vlArenaMemPrepend (vl_arena arena, vl_arena_ptr dst, const void src, vl_memsize_t length)
	Copies a block of memory to the end of the specified arena allocation.

vl_arena_ptr	vlArenaMemAppend (vl_arena arena, vl_arena_ptr dst, const void src, vl_memsize_t length)
	Copies a block of memory to the beginning of the specified arena allocation.

vl_transient *	vlArenaMemSample (vl_arena *arena, vl_arena_ptr ptr)
	Sampling function that calculates a transient pointer into the specified arena.

vl_memsize_t	vlArenaMemSize (vl_arena *arena, vl_arena_ptr ptr)
	Get the size of a memory block allocated in a VL arena.

vl_memsize_t	vlArenaTotalCapacity (vl_arena *arena)
	Get the total capacity of the arena.

vl_memsize_t	vlArenaTotalFree (vl_arena *arena)
	Get the total amount of free memory in the arena.

Data Structure Documentation

◆ vl_arena

struct vl_arena

An arena allocator.

The vl_arena structure represents a block of memory that is sliced into many smaller allocations. Returned blocks of memory are merged (or "coalesced") with other adjacent blocks of memory, keeping the free set small in most cases.

The allocation strategy used here is best described as Offset-Ordered First Fit Backwards Allocation. The free set is traversed until the first block that can fit the request is found. This allocator will then "slice" memory off of the end of the block, (or, in rare cases, encompass the entirety of the block) to avoid re-ordering the free set whenever possible. It is a combination of the first-fit and offset-ordered memory management approaches.

For VL, Arenas are different from Linear Pools in a few notable ways. The most significant difference between the two is that Arenas support variably-sized allocations, whereas Linear Pools do not. Pools also have notably less overhead in their management, and tend to map memory linearly rather than having a "best-fit-and-slice" routine.

This block of memory is automatically and dynamically resized when necessary by doubling its capacity. One downside of Arenas that is also present in LinearPools is that all references are unstable. If the underlying block of memory for the arena is resized, all standard pointers (e.g, language-level) may be invalidated. vl_arena_ptr values would still remain valid, but would need freshly sampled pointers.

(Writers note: This took a lot of research. I want a beer. :) )

Collaboration diagram for vl_arena:

Data Fields
vl_memory *	data
vl_set	freeSet

Macro Definition Documentation

◆ VL_ARENA_NULL

#define VL_ARENA_NULL 0

An explicit NULL integer constant that indicates a bad location in an arena.

Using a regular 0 = NULL here works, as no valid allocation will have that offset. This is due to the implicit metadata prepended to each allocation.

Typedef Documentation

◆ vl_arena_ptr

typedef vl_uintptr_t vl_arena_ptr

Function Documentation

◆ vlArenaClear()

void vlArenaClear ( vl_arena * arena )

Clears all the elements in the given arena.

This function removes all the elements in the arena, making it empty. The memory allocated for the elements is not released by this function.

Parameters

arena Pointer to the vl_arena structure.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlArenaClone()

vl_arena * vlArenaClone	(	const vl_arena *	src,
		vl_arena *	dest )

Clones the specified arena to another.

Clones the entirety of the src arena to the dest arena.

The 'src' arena pointer must be non-null and initialized. The 'dest' arena pointer may be null, but if it is not null it must be initialized.

If the 'dest' arena pointer is null, a new arena is created via vlArenaNew.

Parameters

src	pointer
dest	pointer

Returns: pointer to arena that was copied to or created.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlArenaDelete()

void vlArenaDelete ( vl_arena * arena )

Deletes the given VL arena, freeing all allocated memory.

Parameters

arena Pointer to the VL arena to be deleted.

Here is the call graph for this function:

◆ vlArenaFree()

void vlArenaFree ( vl_arena * arena )

Frees memory allocated by an arena instance.

Parameters

arena Pointer to the arena instance to be freed.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlArenaInit()

void vlArenaInit	(	vl_arena *	arena,
		vl_memsize_t	initialSize )

Initializes the vl_arena structure with the given initial size.

This function initializes a vl_arena structure with the specified initial size. The initial size determines the number of elements that the arena can hold initially.

Parameters

arena	The vl_arena structure to be initialized.
initialSize	The initial size of the arena.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlArenaMemAlloc()

vl_arena_ptr vlArenaMemAlloc	(	vl_arena *	arena,
		vl_memsize_t	size )

Take memory from the given arena.

This function is used to allocate memory from the specified arena. Memory is allocated by finding a free block of memory of equal or greater size within the internally managed block of memory.

Parameters

arena	A pointer to the arena from which memory will be allocated.
size	The size of the memory to be allocated in bytes.

Returns: A pointer to the allocated memory, or NULL if allocation fails.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlArenaMemAppend()

vl_arena_ptr vlArenaMemAppend	(	vl_arena *	arena,
		vl_arena_ptr	dst,
		const void *	src,
		vl_memsize_t	length )

Copies a block of memory to the beginning of the specified arena allocation.

This function handles the case wherein the specified source pointer resides within the arena.

Parameters

arena	pointer
dst	arena pointer
src	memory to copy from
length	number of bytes from src

Complexity of O(n) linear.

Returns: new dst arena pointer

Here is the call graph for this function:

◆ vlArenaMemFree()

void vlArenaMemFree	(	vl_arena *	arena,
		vl_arena_ptr	ptr )

Frees a memory block allocated in a vl_arena.

This function frees the memory block referenced by the given pointer from the specified vl_arena. The memory block must have been previously allocated using the vlArenaMemAlloc() or vlArenaMemRealloc() functions.

Parameters

arena	The vl_arena structure representing the arena.
ptr	The pointer to the memory block to be freed.

Note: The behavior is undefined if ptr does not point to a memory block allocated in the specified arena.

See also: vlArenaMemAlloc(); vlArenaMemRealloc()

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlArenaMemPrepend()

vl_arena_ptr vlArenaMemPrepend	(	vl_arena *	arena,
		vl_arena_ptr	dst,
		const void *	src,
		vl_memsize_t	length )

Copies a block of memory to the end of the specified arena allocation.

This function handles the case wherein the specified source pointer resides within the arena.

Parameters

arena	pointer
dst	arena pointer
src	memory to copy from
length	number of bytes from src

Complexity of O(n) linear.

Returns: new dst arena pointer

Here is the call graph for this function:

◆ vlArenaMemRealloc()

vl_arena_ptr vlArenaMemRealloc	(	vl_arena *	arena,
		vl_arena_ptr	ptr,
		vl_memsize_t	size )

Reallocates memory for the given pointer in the given arena.

This function reallocates memory for a previously allocated block of memory in the specified arena. If the reallocation is successful, the old block of memory will be freed and the new block will have a size specified by the 'size' parameter.

Parameters

arena	The arena to perform the reallocation on.
ptr	The pointer to the previously allocated block of memory.
size	The desired size of the newly reallocated block of memory.

Returns: A pointer to the newly reallocated block of memory, or NULL if reallocation fails.

Note: The contents of the memory block pointed to by 'ptr' are preserved up to the lesser of the new and old sizes.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlArenaMemSample()

vl_transient * vlArenaMemSample	(	vl_arena *	arena,
		vl_arena_ptr	ptr )

Sampling function that calculates a transient pointer into the specified arena.

Parameters

arena	The arena on which the operation is performed.
ptr	The arena pointer indicating the memory location on the arena.

Here is the caller graph for this function:

◆ vlArenaMemSize()

vl_memsize_t vlArenaMemSize	(	vl_arena *	arena,
		vl_arena_ptr	ptr )

Get the size of a memory block allocated in a VL arena.

This function returns the size of the memory block allocated at the specified pointer in a VL arena. The size is calculated based on the arena's metadata and may not represent the exact size of the data stored in the block.

Parameters

arena	Pointer to the VL arena.
ptr	Pointer to the memory block.

Returns: Size of the memory block allocated at the specified pointer in the VL arena.

Note: This function assumes that the provided pointer is a valid memory block allocated in the specified VL arena. Passing an invalid or previously freed pointer to this function may result in undefined behavior.

Here is the caller graph for this function:

◆ vlArenaNew()

vl_arena * vlArenaNew ( vl_memsize_t initialSize )

Creates a new arena with the specified initial size.

This function initializes a new arena with the specified initial size. The arena is used to dynamically allocate memory and manage it efficiently using a memory region structure.

Parameters

initialSize The initial size of the arena.

Returns: A pointer to the newly created arena, or NULL if the arena creation failed.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlArenaReserve()

void vlArenaReserve	(	vl_arena *	arena,
		vl_memsize_t	numBytes )

Reserves storage in the underlying allocation of the given arena.

This is done by doubling the size until the requested growth is met or exceeded. This function will always result in the reallocation of the underlying memory.

Parameters

arena	pointer
numBytes	total bytes to reserve

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlArenaTotalCapacity()

vl_memsize_t vlArenaTotalCapacity ( vl_arena * arena )

Get the total capacity of the arena.

This function returns the total capacity of the given arena, in bytes. The capacity represents the maximum number of elements that the arena can store without requiring reallocation.

Parameters

arena Pointer to the arena structure.

Returns: The total capacity of the arena.

Here is the call graph for this function:

◆ vlArenaTotalFree()

vl_memsize_t vlArenaTotalFree ( vl_arena * arena )

Get the total amount of free memory in the arena.

This function returns the total amount of free memory in the specified arena.

Parameters

arena The pointer to the arena structure.

Returns: The total amount of free memory in the arena.

Here is the call graph for this function:

Here is the caller graph for this function:

Data Structures

Macros

Typedefs

Functions

Data Structure Documentation

◆ vl_arena

Macro Definition Documentation

◆ VL_ARENA_NULL

Typedef Documentation

◆ vl_arena_ptr

Function Documentation

◆ vlArenaClear()

◆ vlArenaClone()

◆ vlArenaDelete()

◆ vlArenaFree()

◆ vlArenaInit()

◆ vlArenaMemAlloc()

◆ vlArenaMemAppend()

◆ vlArenaMemFree()

◆ vlArenaMemPrepend()

◆ vlArenaMemRealloc()

◆ vlArenaMemSample()

◆ vlArenaMemSize()

◆ vlArenaNew()

◆ vlArenaReserve()

◆ vlArenaTotalCapacity()

◆ vlArenaTotalFree()