|
Banjo API 1.1.0-alpha
Low-level C99 game development API
|
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) |
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:
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.
| 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.
| 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 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.
| user_data | General purpose context data. |
| memory | Object memory to dispose, or NULL, which the callback ignores, as free does. |
| 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.
| user_data | General purpose context data. |
| size | Allocation size in bytes requested by the caller. |
| 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.
| user_data | General purpose context data. |
| original | Initial object to reallocate, or NULL, for which the callback allocates a new block, as realloc does. |
| size | Allocation size in bytes requested by the caller. |
| void * bj_calloc | ( | size_t | size | ) |
Allocate size bytes of zero-initialised memory.
The returned memory is set to zero bytes.
| [in] | size | Number of bytes to allocate. |
| void bj_free | ( | void * | memory | ) |
Free a previously allocated memory block.
| [in] | memory | Pointer to memory to free, or NULL, which the free callback receives as is; the default one then does nothing, as free does. |
Referenced by setup(), setup(), setup(), teardown(), teardown(), and teardown().
| void * bj_malloc | ( | size_t | size | ) |
Allocate size bytes of memory.
| [in] | size | Number of bytes to allocate. |
| int bj_memcmp | ( | const void * | block_a, |
| const void * | block_b, | ||
| size_t | size ) |
Compare two memory blocks.
| [in] | block_a | Pointer to first memory block, or NULL. |
| [in] | block_b | Pointer to second memory block, or NULL. |
| [in] | size | Number of bytes to compare. |
| void * bj_memcpy | ( | void * | dest, |
| const void * | src, | ||
| size_t | mem_size ) |
Copy mem_size bytes from src to dest.
| [in] | dest | Destination pointer, or NULL, which copies nothing. |
| [in] | src | Source pointer, or NULL, which copies nothing. |
| [in] | mem_size | Number of bytes to copy. |
| 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.
| [in] | dest | Destination pointer, or NULL, which moves nothing. |
| [in] | src | Source pointer, or NULL, which moves nothing. |
| [in] | mem_size | Number of bytes to move. |
| void bj_memset | ( | void * | dest, |
| uint8_t | value, | ||
| size_t | mem_size ) |
Fill mem_size bytes at dest with value.
| [in] | dest | Destination pointer, or NULL, which fills nothing. |
| [in] | value | Byte value to fill. |
| [in] | mem_size | Number of bytes to fill. |
| void bj_memzero | ( | void * | dest, |
| size_t | mem_size ) |
Zero out mem_size bytes at dest.
Effectively calls bj_memset with zero.
| [in] | dest | Destination pointer, or NULL, which zeroes nothing. |
| [in] | mem_size | Number of bytes to zero. |
Referenced by run_distributions().
| void * bj_realloc | ( | void * | memory, |
| size_t | size ) |
Reallocate a memory block to a new size.
| [in] | memory | Pointer 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] | size | Number of bytes to allocate. |
| 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.
| [in] | allocator | Pointer to custom allocator callbacks, or NULL to reset to the system 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).