UnityGame/Library/PackageCache/com.unity.collections/Documentation~/allocator-custom-use.md

Use a custom allocator

Once you've defined a custom allocator, you can add it to your structure or class.

Declare and create a custom allocator

The first step is to declare and create the custom allocator. You must do the following:

• Allocate memory to hold the custom allocator
• Register the allocator by adding an entry in a global allocator table
• Initialize the allocator if necessary.

The wrapper AllocatorHelper helps the process in creating a custom allocator. Examples are given below as how to declare and create a custom allocator defined in the Example custom allocator.

// Example user structure that contains the custom allocator
internal struct ExampleCustomAllocatorStruct
{
    // Use AllocatorHelper to help creating the example custom alloctor
    AllocatorHelper<ExampleCustomAllocator> customAllocatorHelper;

    // Custom allocator property for accessibility
    public ref ExampleCustomAllocator customAllocator => ref customAllocatorHelper.Allocator;

    // Create the example custom allocator
    void CreateCustomAllocator(AllocatorManager.AllocatorHandle backgroundAllocator, byte initialValue)
    {
        // Allocate the custom allocator from backgroundAllocator and register the allocator
        customAllocatorHelper = new AllocatorHelper<ExampleCustomAllocator>(backgroundAllocator);

        // Set the initial value to initialize the memory
        customAllocator.Initialize(initialValue);
    }
}

Use a custom allocator to allocate memory

For Native- collection types, allocation from a custom allocator is similar to a classic allocator, except you must use CollectionHelper.CreateNativeArray to create a NativeArray from a custom allocator and CollectionHelper.Dispose to deallocate a NativeArray from a custom allocator.

For Unsafe- collection types, you must use AllocatorManager.Allocate to allocate memory from a custom allocator and AllocatorManager.Free to deallocate the memory.

When you use a custom allocator to create a Native- collection type, its safety handle is added to the list of child safety handles of the custom allocator. When you rewind the allocator handle of a custom allocator, it invalidates and unregisters all its child allocators, and invalidates all its child safety handles. For Native- collection types, the disposal safety checks throw an exception if the allocator handle has rewound.

The following example method UseCustomAllocator shows how to use a custom allocator to create and allocate native containers:

[!code-csUse custom allocator to allocate memory]

Dispose a custom allocator

To dispose a custom allocator, the following must happen:

• The custom allocator must rewind its allocator handle which invalidates and unregisters all the allocator handle's child allocators, and invalidates all its child safety handles.
• You must unregister the allocator
• You must dispose the memory used to store the allocator.

Example method DisposeCustomAllocator in the user structure shows how to dispose a custom allocator.

[!code-csDispose a custom allocator]

Full example of a custom allocator

The following is a full example of how to use a custom allocator:

[!code-csAdd a custom allocator in user structure]