Global and arena memory management the arena_* functions provide strong garuntees for memory allocation and deallocation with pre and post checks to catch possible incorrect usage. for weaker garuntees, the Failable arena allocation functions can be used. More...

Collaboration diagram for Arena memory allocation:

Modules
	Failable arena allocation
	Failable arena allocation these allocation functions are used when the allocation is not critical and can fail. they also perform less validation on the input parameters than the Arena memory allocation functions.

Data Structures
struct	arena_t
	an allocator object More...

Macros
#define	CTU_TRACE_MEMORY 0
	a compile time flag to enable memory tracing More...

#define	CT_ALLOC_SIZE_UNKNOWN SIZE_MAX
	unknown allocation size constant when freeing or reallocating memory, this can be used as the size to indicate that the size is unknown. requires allocator to support this. More...

#define	ARENA_RENAME(arena, ptr, name)
	rename a pointer in a custom allocator More...

#define	ARENA_REPARENT(arena, ptr, parent)
	reparent a pointer in a custom allocator More...

#define	ARENA_MALLOC(size, name, parent, arena) arena_malloc(size, arena)
	allocate memory from a custom allocator More...

#define	ARENA_OPT_MALLOC(size, name, parent, arena) arena_opt_malloc(size, arena)

#define	ARENA_IDENTIFY(ptr, name, parent, arena)
	rename and reparent a pointer in a custom allocator More...

Typedefs
typedef void (	mem_alloc_t) (size_t size, void *user)
	arena malloc callback More...

typedef void (	mem_resize_t) (void ptr, size_t new_size, size_t old_size, void user)
	arena realloc callback More...

typedef void(*	mem_release_t) (void ptr, size_t size, void user)
	arena free callback More...

typedef void(*	mem_rename_t) (const void ptr, const char name, void *user)
	arena rename callback More...

typedef void(*	mem_reparent_t) (const void ptr, const void parent, void *user)
	arena reparent callback More...

typedef typedefCT_BEGIN_API struct arena_t	arena_t
	a memory allocator More...

Functions
CT_ARENA_API void	arena_free (STA_RELEASE void ptr, size_t size, arena_t arena)
	release memory from a custom allocator More...

CT_NODISCARD CT_ARENA_API void *	arena_malloc (size_t size, arena_t *arena)
	allocate memory from a custom allocator More...

CT_NODISCARD CT_ARENA_API void *	arena_malloc_info (size_t size, const char name, const void parent, arena_t *arena)
	allocate memory from a custom allocator More...

CT_NODISCARD CT_ARENA_API void *	arena_realloc (STA_RELEASE void ptr, size_t new_size, size_t old_size, arena_t arena)
	resize a memory allocation from a custom allocator More...

CT_NODISCARD CT_ARENA_API char *	arena_strdup (const char str, arena_t arena)
	allocate a copy of a string from a custom allocator More...

CT_NODISCARD CT_ARENA_API char *	arena_strndup (STA_READS(len) const char str, size_t len, arena_t arena)
	allocate a copy of a string with a maximum length from a custom allocator More...

CT_NODISCARD CT_ARENA_API void *	arena_memdup (STA_READS(size) const void ptr, size_t size, arena_t arena)
	duplicate a memory region from a custom allocator duplicate a region of memory and return a pointer to the new memory. More...

CT_NODISCARD CT_ARENA_API void *	arena_data (arena_t *arena)
	get the user data pointer from an arena More...

CT_ARENA_API void	arena_rename (const void ptr, const char name, arena_t *arena)
	rename a pointer in a custom allocator More...

CT_ARENA_API void	arena_reparent (const void ptr, const void parent, arena_t *arena)
	reparent a pointer in a custom allocator More...

Detailed Description

Global and arena memory management the arena_* functions provide strong garuntees for memory allocation and deallocation with pre and post checks to catch possible incorrect usage. for weaker garuntees, the Failable arena allocation functions can be used.

Macro Definition Documentation

◆ ARENA_IDENTIFY

#define ARENA_IDENTIFY	(	ptr,
		name,
		parent,
		arena
	)

Value:

    do                                                                                                                 \
    {                                                                                                                  \
        ARENA_RENAME(ptr, name, arena);                                                                                \
        ARENA_REPARENT(ptr, parent, arena);                                                                            \
    } while (0)

rename and reparent a pointer in a custom allocator

Note: this is a no-op if CTU_TRACE_MEMORY is not defined

Warning: identifying a pointer is not an atomic call and is implemented as two separate calls to ARENA_RENAME and ARENA_REPARENT; name must be an expression that is evaluated in the argument list; parent must be an address on the heap

Parameters

ptr	the pointer to rename
name	the new name of the pointer
parent	the new parent of the pointer
arena	the allocator to use

Definition at line 409 of file arena.h.

◆ ARENA_MALLOC

#define ARENA_MALLOC	(	size,
		name,
		parent,
		arena
	)	arena_malloc(size, arena)

allocate memory from a custom allocator

Note: this is converted to arena_malloc if CTU_TRACE_MEMORY is not defined

Parameters

size	the size of the allocation, must be greater than 0
name	the name of the allocation
parent	the parent of the allocation
arena	the allocator to use

Returns: the allocated pointer

Definition at line 392 of file arena.h.

◆ ARENA_OPT_MALLOC

#define ARENA_OPT_MALLOC	(	size,
		name,
		parent,
		arena
	)	arena_opt_malloc(size, arena)

Definition at line 393 of file arena.h.

◆ ARENA_RENAME

#define ARENA_RENAME	(	arena,
		ptr,
		name
	)

rename a pointer in a custom allocator

Note: this is a no-op if CTU_TRACE_MEMORY is not defined

Parameters

ptr	the pointer to rename
name	the new name of the pointer
arena	the allocator to use

Definition at line 390 of file arena.h.

◆ ARENA_REPARENT

#define ARENA_REPARENT	(	arena,
		ptr,
		parent
	)

reparent a pointer in a custom allocator

Note: this is a no-op if CTU_TRACE_MEMORY is not defined

Parameters

ptr	the pointer to reparent
parent	the new parent of the pointer
arena	the allocator to use

Definition at line 391 of file arena.h.

◆ CT_ALLOC_SIZE_UNKNOWN

#define CT_ALLOC_SIZE_UNKNOWN SIZE_MAX

unknown allocation size constant when freeing or reallocating memory, this can be used as the size to indicate that the size is unknown. requires allocator to support this.

Definition at line 37 of file arena.h.

◆ CTU_TRACE_MEMORY

#define CTU_TRACE_MEMORY 0

a compile time flag to enable memory tracing

Note: this is enabled by default in debug builds, see The build guide for more information

Definition at line 30 of file arena.h.

Typedef Documentation

◆ arena_t

typedef struct arena_t arena_t

a memory allocator

Definition at line 14 of file config.h.

◆ mem_alloc_t

typedef void*(* mem_alloc_t) (size_t size, void *user)

arena malloc callback

Precondition: size must be greater than 0.

Parameters

size	the size of the allocation
user	user data

Returns: the allocated pointer

Return values

NULL	if the allocation failed

Definition at line 50 of file arena.h.

◆ mem_release_t

typedef void(* mem_release_t) (void *ptr, size_t size, void *user)

arena free callback

Parameters

ptr	the pointer to free
size	the size of the allocation.
user	user data

Definition at line 68 of file arena.h.

◆ mem_rename_t

typedef void(* mem_rename_t) (const void *ptr, const char *name, void *user)

arena rename callback

Parameters

ptr	the pointer to rename
name	the new name of the pointer
user	user data

Definition at line 75 of file arena.h.

◆ mem_reparent_t

typedef void(* mem_reparent_t) (const void *ptr, const void *parent, void *user)

arena reparent callback

Parameters

ptr	the pointer to reparent
parent	the new parent of the pointer
user	user data

Definition at line 82 of file arena.h.

◆ mem_resize_t

typedef void*(* mem_resize_t) (void *ptr, size_t new_size, size_t old_size, void *user)

arena realloc callback

Parameters

ptr	the pointer to reallocate
new_size	the new size of the allocation
old_size	the old size of the allocation
user	user data

Returns: the reallocated pointer

Return values

NULL	if the allocation failed

Definition at line 61 of file arena.h.

Function Documentation

◆ arena_data()

CT_NODISCARD CT_ARENA_API void* arena_data ( arena_t * arena )

get the user data pointer from an arena

Parameters

arena the allocator to use

Returns: the user data pointer

Definition at line 186 of file arena.c.

◆ arena_free()

CT_ARENA_API void arena_free	(	STA_RELEASE void *	ptr,
		size_t	size,
		arena_t *	arena
	)

release memory from a custom allocator

Precondition: ptr must be allocated from arena; size must be > 0; arena must not be NULL

Parameters

arena	the allocator to use
ptr	the pointer to free
size	the size of the allocation

◆ arena_malloc()

CT_NODISCARD CT_ARENA_API void* arena_malloc	(	size_t	size,
		arena_t *	arena
	)

allocate memory from a custom allocator

Precondition: size must be > 0; arena must not be NULL

Parameters

arena	the allocator to use
size	the size of the allocation, must be greater than 0

Returns: the allocated pointer

Definition at line 119 of file arena.c.

◆ arena_malloc_info()

CT_NODISCARD CT_ARENA_API void* arena_malloc_info	(	size_t	size,
		const char *	name,
		const void *	parent,
		arena_t *	arena
	)

allocate memory from a custom allocator

Precondition: size must be > 0; arena must not be NULL; name must either be NULL or a valid null terminated string

Parameters

arena	the allocator to use
size	the size of the allocation, must be greater than 0
name	the name of the allocation
parent	the parent of the allocation

Returns: the allocated pointer

Definition at line 129 of file arena.c.

◆ arena_memdup()

CT_NODISCARD CT_ARENA_API void* arena_memdup	(	STA_READS(size) const void *	ptr,
		size_t	size,
		arena_t *	arena
	)

duplicate a memory region from a custom allocator duplicate a region of memory and return a pointer to the new memory.

Precondition: ptr must be a valid pointer to size bytes of memory; size must be > 0; arena must not be NULL

Parameters

ptr	the pointer to duplicate
size	the size of the memory to duplicate
arena	the allocator to use

Returns: the duplicated memory

◆ arena_realloc()

CT_NODISCARD CT_ARENA_API void* arena_realloc	(	STA_RELEASE void *	ptr,
		size_t	new_size,
		size_t	old_size,
		arena_t *	arena
	)

resize a memory allocation from a custom allocator

Precondition: ptr must be allocated from arena; new_size must be > 0; old_size must be the size originally allocated; arena must not be NULL

Parameters

arena	the allocator to use
ptr	the pointer to reallocate
new_size	the new size of the allocation
old_size	the old size of the allocation

Returns: the reallocated pointer

◆ arena_rename()

CT_ARENA_API void arena_rename	(	const void *	ptr,
		const char *	name,
		arena_t *	arena
	)

rename a pointer in a custom allocator

Parameters

arena	the allocator to use
ptr	the pointer to rename
name	the new name of the pointer

Definition at line 160 of file arena.c.

◆ arena_reparent()

CT_ARENA_API void arena_reparent	(	const void *	ptr,
		const void *	parent,
		arena_t *	arena
	)

reparent a pointer in a custom allocator

Parameters

arena	the allocator to use
ptr	the pointer to reparent
parent	the new parent of the pointer

Definition at line 173 of file arena.c.

◆ arena_strdup()

CT_NODISCARD CT_ARENA_API char* arena_strdup	(	const char *	str,
		arena_t *	arena
	)

allocate a copy of a string from a custom allocator

Precondition: str must be a valid, null terminated, string; arena must not be NULL

Parameters

str	the string to copy
arena	the allocator to use

Returns: the allocated copy of the string

allocate a copy of a string from a custom allocator

Definition at line 95 of file arena.c.

◆ arena_strndup()

CT_NODISCARD CT_ARENA_API char* arena_strndup	(	STA_READS(len) const char *	str,
		size_t	len,
		arena_t *	arena
	)

allocate a copy of a string with a maximum length from a custom allocator

Precondition: str must be a valid string of at least len characters; arena must not be NULL

Parameters

str	the string to copy
len	the maximum length of the string to copy
arena	the allocator to use

Returns: the allocated copy of the string

Modules

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ ARENA_IDENTIFY

◆ ARENA_MALLOC

◆ ARENA_OPT_MALLOC

◆ ARENA_RENAME

◆ ARENA_REPARENT

◆ CT_ALLOC_SIZE_UNKNOWN

◆ CTU_TRACE_MEMORY

Typedef Documentation

◆ arena_t

◆ mem_alloc_t

◆ mem_release_t

◆ mem_rename_t

◆ mem_reparent_t

◆ mem_resize_t

Function Documentation

◆ arena_data()

◆ arena_free()

◆ arena_malloc()

◆ arena_malloc_info()

◆ arena_memdup()

◆ arena_realloc()

◆ arena_rename()

◆ arena_reparent()

◆ arena_strdup()

◆ arena_strndup()