66 lines
3.7 KiB
Markdown
66 lines
3.7 KiB
Markdown
|
# Use a custom allocator
|
||
|
|
|
||
|
|
Once you've [defined a custom allocator](allocator-custom-define.md), 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`](xref:Unity.Collections.AllocatorHelper`1) 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](allocator-custom-define.md).
|
||
|
|
|
||
|
|
```c#
|
||
|
|
// 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`](xref:Unity.Collections.CollectionHelper.CreateNativeArray*) to create a `NativeArray` from a custom allocator and [`CollectionHelper.Dispose`](xref:Unity.Collections.CollectionHelper.Dispose*) to deallocate a `NativeArray` from a custom allocator.
|
||
|
|
|
||
|
|
For `Unsafe-` collection types, you must use [`AllocatorManager.Allocate`](xref:Unity.Collections.AllocatorManager.Allocate*) to allocate memory from a custom allocator and [`AllocatorManager.Free`](xref:Unity.Collections.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-cs[Use custom allocator to allocate memory](../Unity.Collections.Tests/AllocatorCustomTests.cs#allocator-custom-use)]
|
||
|
|
|
||
|
|
## 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-cs[Dispose a custom allocator](../Unity.Collections.Tests/AllocatorCustomTests.cs#allocator-custom-dispose)]
|
||
|
|
|
||
|
|
## Full example of a custom allocator
|
||
|
|
The following is a full example of how to use a custom allocator:
|
||
|
|
|
||
|
|
[!code-cs[Add a custom allocator in user structure](../Unity.Collections.Tests/AllocatorCustomTests.cs#allocator-custom-user-struct)]
|
||
|
|
|