Custom memory allocation
The C API exposes an API to set custom memory allocation and deallocation functions.
By default, all of the worker SDKs invoke standard memory allocation functions, such as malloc
,
free
, new
, and delete
.
Why use custom memory allocation?
Custom memory allocation can benefit game studios through improving ease of development and memory optimization. By owning all the memory from the start of the process, you are not reliant on platform tooling to help you profile, find memory leaks, and track performance issues. You can budget a set amount of memory for a specific game system, and you can optimize memory management, avoiding reliance on the operating system configuration.
Configuring custom memory allocation
You can configure custom memory allocation using the Worker_Alpha_SetAllocator
function. This lets you provide your own allocation and deallocation functions and an arbitrary
allocator state, which is passed as an argument in each call to the allocation and deallocation functions.
The allocation function should allocate a block of memory of the size that is given by the argument and return a pointer to the first byte. The pointer must be suitably aligned to hold an object of any fundamental alignment and will be released by a matching call to the deallocation function with the same size. If either function throws, the application will terminate. Both functions must be thread-safe
You must call the Worker_Alpha_SetAllocator
function before any other calls to the API are made.
Calling the Worker_Alpha_SetAllocator
function multiple times or after another API call has been made is
undefined behaviour.
The following snippet demonstrates a very basic usage which just sets the allocation and deallocation
functions to malloc
and free
respectively:
struct user_data {
const char* call_point;
};
void* my_allocate(size_t size, void* untyped_user_data) {
printf("allocating %u bytes from %s\n", (unsigned int)size,
((struct user_data*)untyped_user_data)->call_point);
return malloc(size);
}
void my_free(void* ptr, size_t size, void* untyped_user_data) {
printf("freeing %u bytes from %s\n", (unsigned int)size,
((struct user_data*)untyped_user_data)->call_point);
free(ptr);
}
struct user_data user_data;
user_data.call_point = "worker api";
Worker_Alpha_SetAllocator(&my_allocate, &my_free, &user_data);
Known issues and caveats
The Worker API can still allocate small amounts of memory using the system allocator directly rather than the user-provided one. In particular, APIs that interact with files (such as protocol logging or writing a snapshot), or initially establishing a connection will cause allocation using the system allocator.