Rewindable allocator

A rewindable allocator is a custom allocator that works in a similar way to a linear allocator. A rewindable allocator pre-allocates blocks of memory in advance. To rewind in this context means resetting the allocator back to its starting point so that all memory previously allocated can be used again.

A rewindable allocator is useful when you make many temporary allocations that all share the same lifetime. For example, all the scratch data created during a single frame, a single job batch, or one pass of an algorithm.

Instead of freeing each allocation one by one, you allocate throughout your work, and then rewind the allocator once at the end to reclaim everything in a single operation. Freeing allocations in a single operation means you don’t have to track any allocation individually, which reduces the risk of memory leaks. This is a thread-safe operation that multiple threads can allocate from concurrently.

A typical pattern looks like this:

1. Allocate a rewindable allocator once.
2. During the frame or pass, make as many temporary allocations from it as you need.
3. At the end of the frame or pass, rewind the allocator to reclaim all of them at once.
4. Repeat for the next frame or pass, reusing the same memory blocks.

When you request memory from a rewindable allocator, it selects a range of memory from its pre-allocated block and assigns it to use. The minimum alignment of rewindable allocations is 64 bytes. After it uses all the existing blocks of memory, the rewindable allocator allocates another block of memory. It doubles the size of the new block until it reaches a maximum block size. When it reaches this point, the rewindable allocator adds the maximum block size to its previous block size to increase its block size linearly.

When you rewind an allocator, the allocator keeps the memory blocks that it used before to improve performance and disposes the rest of the blocks. When you request to free or dispose a memory allocation from a rewindable allocator, nothing happens unless you set RewindableAllocation.EnableBlockFree to true. When this property is true, the rewindable allocator rewinds a memory block when it frees the last allocation from the block.

Declare and create a rewindable allocator

To create a rewindable allocator, you must do the following:

1. Allocate memory to hold the rewindable allocator.
2. Add an entry in the global allocator table to register the allocator.
3. Pre-allocate the allocator’s first memory block to initialize it.

You can use the wrapper AllocatorHelper to create a rewindable allocator.

The following example declares and creates a rewindable allocator:

// Example user structure
internal struct ExampleStruct
{
    // Use AllocatorHelper to help creating a rewindable alloctor
    AllocatorHelper<RewindableAllocator> rwdAllocatorHelper;

    // Rewindable allocator property for accessibility
    public ref RewindableAllocator RwdAllocator => ref rwdAllocatorHelper.Allocator;

    // Create the rewindable allocator
    void CreateRewindableAllocator(AllocatorManager.AllocatorHandle backgroundAllocator, int initialBlockSize, bool enableBlockFree = false)
    {
        // Allocate the rewindable allocator from backgroundAllocator and register the allocator
        rwdAllocatorHelper = new AllocatorHelper<RewindableAllocator>(backgroundAllocator);

        // Allocate the first memory block with initialBlockSize in bytes, and indicate whether
        // to enable the rewindable allocator with individual block free through enableBlockFree
        RwdAllocator.Initialize(initialBlockSize, enableBlockFree);
    }
}

Use a rewindable allocator to allocate memory

For Native- collection types, allocation from a rewindable allocator is similar to a built-in allocator, except you must use CollectionHelper.CreateNativeArray to create a NativeArray from a rewindable allocator. When you use a rewindable allocator to create a native collection type, its safety handle is added to the list of child safety handles of the rewindable allocator.

For Unsafe- collection types, you must use AllocatorManager.Allocate to allocate memory from a rewindable allocator.

You don’t need to dispose individual allocations. When all allocations aren’t needed anymore, call the Rewind method of a rewindable allocator to free all its allocations. When you rewind the rewindable allocator, it invalidates and unregisters its child allocators, and invalidates all its child safety handles. For native collection types, the disposal safety checks throw an exception if the rewindable allocator has rewound.

This example method UseRewindableAllocator shows how to use a rewindable allocator to create and allocate native containers:

// Sample code to use rewindable allocator to allocate containers
public unsafe void UseRewindableAllocator(out NativeArray<int> nativeArray, out NativeList<int> nativeList, out byte* bytePtr)
{
    // Use rewindable allocator to allocate a native array, no need to dispose the array manually
    // CollectionHelper is required to create/allocate native array from a custom allocator.
    nativeArray = CollectionHelper.CreateNativeArray<int, RewindableAllocator>(100, ref RwdAllocator);
    nativeArray[0] = 0xFE;

    // Use rewindable allocator to allocate a native list, do not need to dispose the list manually
    nativeList = new NativeList<int>(RwdAllocator.Handle);
    for (int i = 0; i < 50; i++)
    {
        nativeList.Add(i);
    }

    // Use custom allocator to allocate a byte buffer.
    bytePtr = (byte*)AllocatorManager.Allocate(ref RwdAllocator, sizeof(byte), sizeof(byte), 10);
    bytePtr[0] = 0xAB;
}

Free all allocated memory of a rewindable allocator

When you call RewindableAllocator.Rewind on the rewindable allocator, it performs the following operations:

• Invalidates and unregisters all the allocator handle’s child allocators.
• Invalidates all its child safety handles.

The example method FreeRewindableAllocator shows how to free all allocations from the rewindable allocator by calling RewindableAllocator.Rewind.

// Free all allocations from the rewindable allocator
public void FreeRewindableAllocator()
{
    RwdAllocator.Rewind();
}

Dispose a rewindable allocator

To dispose a rewindable allocator, you must do the following:

1. Dispose all the memory blocks of the rewindable allocator from Allocator.Persistent.
2. Unregister the allocator.
3. Dispose the memory used to store the allocator.

The following example adds a method DisposeRewindableAllocatorthat disposes a rewindable allocator using Dispose:

// Dispose the rewindable allocator
void DisposeRewindableAllocator()
{
    // Dispose all the memory blocks in the rewindable allocator
    RwdAllocator.Dispose();
    // Unregister the rewindable allocator and dispose it
    rwdAllocatorHelper.Dispose();
}

Full example of a rewindable allocator

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

using System;
using NUnit.Framework;
using Unity.Collections;

// Example user structure
internal struct ExampleStruct
{
    // Use AllocatorHelper to help creating a rewindable alloctor
    AllocatorHelper<RewindableAllocator> rwdAllocatorHelper;

    // Rewindable allocator property for accessibility
    public ref RewindableAllocator RwdAllocator => ref rwdAllocatorHelper.Allocator;

    // Create the rewindable allocator
    void CreateRewindableAllocator(AllocatorManager.AllocatorHandle backgroundAllocator, int initialBlockSize, bool enableBlockFree = false)
    {
        // Allocate the rewindable allocator from backgroundAllocator and register the allocator
        rwdAllocatorHelper = new AllocatorHelper<RewindableAllocator>(backgroundAllocator);

        // Allocate the first memory block with initialBlockSize in bytes, and indicate whether
        // to enable the rewindable allocator with individual block free through enableBlockFree
        RwdAllocator.Initialize(initialBlockSize, enableBlockFree);
    }

    // Constructor of user structure
    public ExampleStruct(int initialBlockSize)
    {
        this = default;
        CreateRewindableAllocator(Allocator.Persistent, initialBlockSize, false);
    }

    // Dispose the user structure
    public void Dispose()
    {
        DisposeRewindableAllocator();
    }

    #region allocator-rewindable-use
    // Sample code to use rewindable allocator to allocate containers
    public unsafe void UseRewindableAllocator(out NativeArray<int> nativeArray, out NativeList<int> nativeList, out byte* bytePtr)
    {
        // Use rewindable allocator to allocate a native array, no need to dispose the array manually
        // CollectionHelper is required to create/allocate native array from a custom allocator.
        nativeArray = CollectionHelper.CreateNativeArray<int, RewindableAllocator>(100, ref RwdAllocator);
        nativeArray[0] = 0xFE;

        // Use rewindable allocator to allocate a native list, do not need to dispose the list manually
        nativeList = new NativeList<int>(RwdAllocator.Handle);
        for (int i = 0; i < 50; i++)
        {
            nativeList.Add(i);
        }

        // Use custom allocator to allocate a byte buffer.
        bytePtr = (byte*)AllocatorManager.Allocate(ref RwdAllocator, sizeof(byte), sizeof(byte), 10);
        bytePtr[0] = 0xAB;
    }

Additional resources

• Introduction to allocators
• Aliasing allocators
• Custom allocator
• Create and use a custom allocator