Banjo API 1.1.0-alpha
Low-level C99 game development API
Loading...
Searching...
No Matches
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/realloc/ free, with bj_calloc zeroing what bj_malloc returns, 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 three 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, before bj_begin
struct bj_memory_callbacks cb = {
.user_data = &my_arena,
.fn_allocation = arena_alloc,
.fn_reallocation = arena_realloc,
.fn_free = arena_free,
};
// ... use Banjo normally, all bj_malloc/bj_free go through cb now ...
// Restore stdlib defaults, after bj_end, once every block is freed
void bj_unset_memory_defaults(void)
Reset the global default allocators to system defaults.
void bj_set_memory_defaults(const struct bj_memory_callbacks *allocator)
Set the global default memory allocators.
Custom allocation callbacks.
Definition memory.h:128

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 are set globally with bj_set_memory_defaults.

Definition at line 128 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_dataGeneral purpose context data.
memoryObject memory to dispose, or NULL, which the callback ignores, as free does.

Definition at line 115 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_dataGeneral purpose context data.
sizeAllocation size in bytes requested by the caller.
Returns
Pointer to allocated memory block.

Definition at line 81 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_dataGeneral purpose context data.
originalInitial object to reallocate, or NULL, for which the callback allocates a new block, as realloc does.
sizeAllocation size in bytes requested by the caller.
Returns
Pointer to reallocated memory block.

Definition at line 99 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]sizeNumber 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]memoryPointer to memory to free, or NULL, which the free callback receives as is; the default one then does nothing, as free does.
Note
memory must have been allocated by bj_malloc, bj_calloc 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]sizeNumber 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_aPointer to first memory block, or NULL.
[in]block_bPointer to second memory block, or NULL.
[in]sizeNumber of bytes to compare.
Returns
Zero if equal, negative if a < b, positive if a > b. A NULL block sorts before any other and equals another NULL one, and a size of 0 compares equal.

◆ bj_memcpy()

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

Copy mem_size bytes from src to dest.

Parameters
[in]destDestination pointer, or NULL, which copies nothing.
[in]srcSource pointer, or NULL, which copies nothing.
[in]mem_sizeNumber 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]destDestination pointer, or NULL, which moves nothing.
[in]srcSource pointer, or NULL, which moves nothing.
[in]mem_sizeNumber 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]destDestination pointer, or NULL, which fills nothing.
[in]valueByte value to fill.
[in]mem_sizeNumber 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]destDestination pointer, or NULL, which zeroes nothing.
[in]mem_sizeNumber 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]memoryPointer to previously allocated memory, or NULL, which the reallocation callback receives as is; the default one then allocates a new block, as realloc does.
[in]sizeNumber of bytes to allocate.
Returns
Pointer to newly reallocated memory block.
Note
memory must have been allocated by bj_malloc, bj_calloc 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). A set whose allocation, reallocation or free function is NULL is refused: the call does nothing, and the installed callbacks stay.

A block goes to the reallocation or free function installed when it is reallocated or freed. Install the callbacks before Banjo allocates anything, before bj_begin, and keep them until every block is freed, after bj_end. Blocks allocated under earlier callbacks would otherwise reach the new ones.

Parameters
[in]allocatorPointer to custom allocator callbacks, or NULL to reset to the system defaults.

◆ 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).