Managed memory reservation in Unity

During my work, I always faced situations when at the initialization stage of the application there were lots of allocations. Of course, it evolved whenever the project got bigger and bigger.

Thus one question arose whenever a certain threshold was reached: is it possible to reserve memory before it is needed? ¹

Why even care?

To understand why this part is important we must return to the basics: how allocator and GC work for managed memory in Unity ².

I omit certain details about the guts of managed memory, those who want to know more can read in official documentation.

Get back to the allocation and garbage collection process:

1. When some memory is requested allocator tries to fit an object in the already allocated region(s) of the memory
2. If there is no region part where the new object could fit, the allocator can ³ start a garbage collection process to clean up memory from objects and find a place for a new allocation
3. If the previous step fails allocator will reserve a new memory region of a certain size
4. In the end if there is no memory: NotEnoughMemoryException will appear (in the managed region)

Thus this step happens for every single allocation in our application. This doesn’t seem much of an issue for tens or hundreds of allocations, but what if we talk about tens of thousands? Hundreds of thousands of allocations?

Official documentation

Official Unity documentation provides some information about controlling allocators. It gives us the ability to control block size, granularity, etc. of certain allocators but there is no ability to control preallocated size before it will be used.

Hence straightforward way to use public API is closed, nevertheless, it doesn’t mean we don’t have options.

First option that we, we can use is simple and dangerous in the same time - reserve memory through the manual creation of large blocks of data:

public class HeapAllocator : MonoBehaviour
{
	private const int MBByte = 1024 * 1024;

	private void Start()
	{
		ReserveMemory(100);
	}

	public void ReserveMemory(int megabytes)
	{
		_ = new long[MBByte * megabytes / 8]; //This is just an example, you can control granularity as you wish using different data types or data structures
	}
}

Thus using a blunt technique we can reserve as much memory as we need at the start of the application but still 1 garbage collection process will occur to clean up this memory.

But it has certain restrictions that prevent its usage in production:

1. The first dead end awaits in case there will be a necessity to reserver memory in the middle of runtime (for example after 5 minutes of running) because it isn’t determined how and where newly allocated objects will fit (in the already allocated region or a new one).
2. Because the garbage collection process isn’t deterministic making allocations right after reservation could lead to the allocation of a new region instead of fitting in the preallocated one because GC may not clean out preallocated objects.

Well, Unity has an interesting backdoor…

Private functionality

At one of the Unites, developers of The Elder Scrolls Blades mentioned that they controlled heap growth in Unity using heap growth divisor⁴. So, maybe there is a functionality to reserve memory in a managed region?

Because internally Unity uses open source Boehm-Demers-Weiser Garbage Collector (⁵ which has significant differences from Mono and especially from modern .Net GC) we can go straightly to the public GitHub repository, here is what we will see there among different public APIs:

GC_expand_hp(bytes) - Explicitly increase the heap size.

This is exactly what we need!

But before, almost everyone encountered the next attribute during their work:

[DllImport ("__Internal")]

Every piece of code that is out of the C# area and written in the native language will be exposed through it. But most importantly it can expose native unity code ⁶.

public static class HeapControl
{
    [DllImport ("__Internal")]
    private static extern int GC_expand_hp (int bytes);
    
    public static void ReserveMemory(int bytes)
    {
            GC_expand_hp(bytes);
    }
}

What we see:

Exactly the same picture as in the case with hacked reservation but without any drawbacks of the previous one. ⁷

In the end, by exposing of Boehm GC API we are able to reserve memory without any drawbacks.

One more thing: what other stuff is available to use in Unity using DLLImport?