Memory Management

Data Structures
struct	bj_memory_callbacks

Typedefs
typedef void *(*	bj_malloc_fn) (void *user_data, size_t size)
typedef void *(*	bj_realloc_fn) (void *user_data, void *original, size_t size)
typedef void(*	bj_free_fn) (void *user_data, void *memory)

Functions
void *	bj_malloc (size_t size)
void *	bj_calloc (size_t size)
void *	bj_realloc (void *memory, size_t size)
void	bj_free (void *memory)
void	bj_set_memory_defaults (const struct bj_memory_callbacks *allocator)
void	bj_unset_memory_defaults (void)
void *	bj_memcpy (void *dest, const void *src, size_t mem_size)
void *	bj_memmove (void *dest, const void *src, size_t mem_size)
int	bj_memcmp (const void *block_a, const void *block_b, size_t size)
void	bj_memset (void *dest, uint8_t value, size_t mem_size)
void	bj_memzero (void *dest, size_t mem_size)

Detailed Description

Allocate, free, and (optionally) replace how Banjo gets memory from the heap.

Every time Banjo needs heap memory (for a window, a bitmap, an audio device, your error objects) it goes through bj_malloc, bj_calloc, bj_realloc, and bj_free. By default these wrap the C standard library's malloc/calloc/ realloc/free, so if you don't care you can ignore the whole subsystem and Banjo just behaves like any other library.

Where it gets interesting is you can replace the underlying allocator. You give Banjo four function pointers (one for allocation, one for reallocation, one for freeing, plus a user_data pointer that's threaded through each call) and from that moment on every Banjo allocation goes through your code instead of the C standard library. That's useful for three things:

1. Tracking. Count bytes allocated, find leaks, see who's using how much memory. Banjo's own test suite does exactly this: every test runs with a custom allocator that counts alloc/free pairs, and the suite fails any test that leaks. Your application can do the same in its dev builds.
2. Custom allocators. Many games and embedded programs pre-allocate a big slab of memory at startup and hand it out in chunks using an arena or pool allocator; that pattern avoids the cost and fragmentation of repeated malloc/free calls. You can install that allocator once and have Banjo use it.
3. Auditing. When Banjo is one library among many in a host application, routing Banjo's allocations through a separate allocator keeps Banjo's bookkeeping isolated from the host's.

// Install a custom allocator
struct bj_memory_callbacks cb = {
    .user_data       = &my_arena,
    .fn_allocation   = arena_alloc,
    .fn_reallocation = arena_realloc,
    .fn_free         = arena_free,
};
bj_set_memory_defaults(&cb);
 
// ... use Banjo normally, all bj_malloc/bj_free go through cb now ...
 
// Restore stdlib defaults
bj_unset_memory_defaults();

A few <string.h> equivalents come along

bj_memcpy, bj_memmove, bj_memset, bj_memcmp, and bj_memzero behave exactly like the C standard library's memcpy / memmove / memset / memcmp / (memset-to-zero) functions. They're here so Banjo's core code doesn't have to #include <string.h>, but you can use them in your own code too if you prefer.

---

Data Structure Documentation

bj_memory_callbacks

struct bj_memory_callbacks

Custom allocation callbacks.

This structure holds function pointers for allocation, reallocation, and deallocation callbacks along with user data.

These callbacks can be assigned per-object or set globally with bj_set_memory_defaults.

Definition at line 126 of file memory.h.

Data Fields
bj_malloc_fn	fn_allocation	Allocation function pointer.
bj_free_fn	fn_free	Deallocation function pointer.
bj_realloc_fn	fn_reallocation	Reallocation function pointer.
void *	user_data	General purpose context data.

Typedef Documentation

bj_free_fn

typedef void(* bj_free_fn) (void *user_data, void *memory)

Memory free callback.

Used in bj_memory_callbacks to set the function used for custom deallocations.

Parameters

user_data	General purpose context data.
memory	Object memory to dispose.

Definition at line 112 of file memory.h.

bj_malloc_fn

typedef void *(* bj_malloc_fn) (void *user_data, size_t size)

Memory allocation callback.

Used in bj_memory_callbacks to set the function used for custom allocations.

Parameters

user_data	General purpose context data.
size	Allocation size in bytes requested by the caller.

Returns

Pointer to allocated memory block.

Definition at line 80 of file memory.h.

bj_realloc_fn

typedef void *(* bj_realloc_fn) (void *user_data, void *original, size_t size)

Memory reallocation callback.

Used in bj_memory_callbacks to set the function used for custom reallocations.

Parameters

user_data	General purpose context data.
original	Initial object to reallocate.
size	Allocation size in bytes requested by the caller.

Returns

Pointer to reallocated memory block.

Definition at line 97 of file memory.h.

Function Documentation

bj_calloc()

void * bj_calloc

(

size_t

size

)

Allocate size bytes of zero-initialised memory.

The returned memory is set to zero bytes.

Parameters

[in]

size

Number of bytes to allocate.

Returns

Pointer to newly allocated zeroed memory block.

Examples

event_callbacks.c, event_polling.c, and pong.c.

Referenced by setup(), setup(), and setup().

bj_free()

void bj_free

(

void *

memory

)

Free a previously allocated memory block.

Parameters

[in]

memory

Pointer to memory to free.

Note

memory must have been allocated by bj_malloc or bj_realloc.

Examples

event_callbacks.c, event_polling.c, and pong.c.

Referenced by setup(), setup(), setup(), teardown(), teardown(), and teardown().

bj_malloc()

void * bj_malloc

(

size_t

size

)

Allocate size bytes of memory.

Parameters

[in]

size

Number of bytes to allocate.

Returns

Pointer to newly allocated memory block.

bj_memcmp()

int bj_memcmp	(	const void *	block_a,
		const void *	block_b,
		size_t	size )

Compare two memory blocks.

Parameters

[in]	block_a	Pointer to first memory block.
[in]	block_b	Pointer to second memory block.
[in]	size	Number of bytes to compare.

Returns

Zero if equal, negative if a < b, positive if a > b.

bj_memcpy()

void * bj_memcpy	(	void *	dest,
		const void *	src,
		size_t	mem_size )

Copy mem_size bytes from src to dest.

Parameters

[in]	dest	Destination pointer.
[in]	src	Source pointer.
[in]	mem_size	Number of bytes to copy.

Returns

Pointer to dest.

bj_memmove()

void * bj_memmove	(	void *	dest,
		const void *	src,
		size_t	mem_size )

Move mem_size bytes from src to dest.

Similar to bj_memcpy but handles overlapping memory regions safely.

Parameters

[in]	dest	Destination pointer.
[in]	src	Source pointer.
[in]	mem_size	Number of bytes to move.

Returns

Pointer to dest.

bj_memset()

void bj_memset	(	void *	dest,
		uint8_t	value,
		size_t	mem_size )

Fill mem_size bytes at dest with value.

Parameters

[in]	dest	Destination pointer.
[in]	value	Byte value to fill.
[in]	mem_size	Number of bytes to fill.

bj_memzero()

void bj_memzero	(	void *	dest,
		size_t	mem_size )

Zero out mem_size bytes at dest.

Effectively calls bj_memset with zero.

Parameters

[in]	dest	Destination pointer.
[in]	mem_size	Number of bytes to zero.

Examples

random_distribution.c.

Referenced by run_distributions().

bj_realloc()

void * bj_realloc	(	void *	memory,
		size_t	size )

Reallocate a memory block to a new size.

Parameters

[in]	memory	Pointer to previously allocated memory.
[in]	size	Number of bytes to allocate.

Returns

Pointer to newly reallocated memory block.

Note

memory must have been allocated by bj_malloc or bj_realloc.

bj_set_memory_defaults()

void bj_set_memory_defaults

(

const struct bj_memory_callbacks *

allocator

)

Set the global default memory allocators.

If allocator is NULL, resets to system defaults (malloc, realloc, free).

Parameters

[in]

allocator

Pointer to custom allocator callbacks.

bj_unset_memory_defaults()

void bj_unset_memory_defaults

(

void

)

Reset the global default allocators to system defaults.

Sets allocators back to standard system functions (malloc, realloc, free).