FixUtil Documentation

import "util/struct";

Provides macros for manual allocation and deallocation of structs stored in a shared array.

This module requires using of classes for the macros that use struct types.

The macros access the array by reference, that way it can resize it by creating a new shared array and copying the existing content to it. The array doesn't need to be initialized, it will be automatically created on a first allocation. The array always use 4 bytes per element.

Any allocated space must be freed with the corresponding macro of the alloc/free pair. Array and raw allocations must free or resize the whole allocated space. There are no checks for faulty operations (such as double or mismatched freeing).

When passing the arrays between tasks it is required to send a new reference of the shared array before use. This is because the allocation can resize the array by creating a new array. The previous array will then contain old data and shouldn't be used anymore.

The allocator uses the first-fit algorithm with the free ranges sorted by their offset. This allow to merge free ranges and reduces the overall array size. The overhead is just a single element at the start of the array that is used as a pointer to the first free range. The downside of the allocator is that it can be slower and more fragmented in the case that many too small free ranges are at the beginning. If this is an issue you can pack differently sized structs in different shared arrays.

Global macros

Struct allocation

macro struct_init(&arr, capacity: Integer): Initializes the array with given capacity (powers of two are recommended). This operation is optional, the array will be initialized with the default capacity on the first allocation.
macro struct_alloc(&arr, type): Allocates space for the struct. The type must be a struct type. Returns the struct.
macro struct_free(&arr, type, str): Deallocates space used by the struct. The type must be a struct type.

Struct array allocation

macro struct_alloc_array(&arr, type, num_elems: Integer): Allocates space for an array of structs. The type must be a struct type. Returns the first struct.
macro struct_realloc_array(&arr, type, &str, &num_elems: Integer, new_num_elems: Integer): Resizes space for the struct array. The type must be a struct type and the passed struct must be the first struct in the array.
macro struct_free_array(&arr, type, str, num_elems: Integer): Deallocates space used by the struct array. The type must be a struct type and the passed struct must be the first struct in the array.

Raw allocation

macro struct_raw_alloc(&arr, size: Integer): Integer: Allocates space of given size. Returns the offset in the array. The offset is never zero.
macro struct_raw_realloc(&arr, &size: Integer, &off: Integer, new_size: Integer): Resizes space to a new size.
macro struct_raw_free(&arr, size, off: Integer): Deallocates space.

Global functions

function struct_get_free_size(arr): Integer: Returns the overall free space.
function struct_get_occupancy(arr): Float: Returns how occupied the array is. The result is in the 0-1 range.
function struct_dump(arr): Dumps the visual overview of the allocations in the array.