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.

Search results