Official Memory Allocator Customization in Unity 2021 LTS

Efficient memory access patterns are a key factor in creating high performance software applications. The Performance Optimization Team have recently taken a deeper look at the memory allocation systems within Unity. We identified settings that could be used to optimize for a specific applications unique needs and verified the gains in a selection of games and demos. We exposed these settings so now you too can make sure you’re getting the best memory utilization for your game. Measure how much memory is used by different allocators, then customize their size to suit your game. Check out the documentation, and let us know how it’s going – we’d love to hear about your experience.

 

Hi Hyp-X
You can call Application.Quit() to make the app exit and print the report, but I agree; we should have an api that either prints the report to the log or returns a string with the report so that you can print, parse or handle it in the way you want. I'll add that to our list.
Thanks for the feedback

 

Hi,

"ALLOC_TEMP_TLS" is the name, where "TLS Allocator" is a type of the allocator.
If you search on the page that you shared `TLS` you will get section:
Thread Local Storage (TLS) stack allocator

How TLS works, it is not single allocator but it have separate instance per different thread, where each of them is categorise in some configuration groups. Lets look on your log and we have:

• ALLOC_TEMP_MAIN
  • what it mean: Temp Allocator for main thread
  • config: Thread Local Storage (TLS) stack allocator :: Main Thread Block Size
• ALLOC_TEMP_Job.Worker 18
  • what it mean: Temp Allocator for job worker thread 18
  • config: Thread Local Storage (TLS) stack allocator :: Job Worker Block Size

Sadly this is not so easy. What you see at the shutdown is just summary of allocator use in single application run. This is very important as every run can have a little bit different characteristics and return different values based on the things that will happen in it.

Our recommendation would be to tweak this values carefully. I would say that our guide would be to do it close to release where estimation of memory should be close to final product. You should then collect informations from multiple longer runs and base on them decide if you want to lower or increase values.

In reality there is no one way of handling it that is why we gave example for every allocator where we describe logic behind changes we would do in given case.

We tried to make whole thing as logical as we could be but sadly Unity memory system is complicated. That is why I would say that this feature has high entry point as it require some knowledge about our native memory system.

If after this explanation you are still lost, feel free to drop some of yours examples and what you would change based on them. We will then discuss if this would work and in case not why.

 

I will start with side note:

I created task to add this API and also task to think about explicit mentioning setting that corresponding to given allocator. This should resolve the issue in the future.

Till then let's look on final stats printed at the end of run and search for `ALLOC_TEMP_MAIN`. I got single result:

[ALLOC_TEMP_TLS] TLS Allocator
StackAllocators :
[ALLOC_TEMP_CurlRequest]
Initial Block Size 64.0 KB
Current Block Size 64.0 KB
Peak Allocated Bytes 0 B
Overflow Count 0
[ALLOC_TEMP_MAIN]
Peak usage frame count: [8.0 MB-16.0 MB]: 1 frames
Initial Block Size 16.0 MB
Current Block Size 16.0 MB
Peak Allocated Bytes 9.3 MB
Overflow Count 0
[ALLOC_TEMP_Background Job.worker 6]
Initial Block Size 32.0 KB
Current Block Size 32.0 KB
Peak Allocated Bytes 0 B
Overflow Count 0
[.......​

As you can see it is Stack Allocators entry under [ALLOC_TEMP_TLS] TLS Allocator. Quick check on page https://docs.unity3d.com/2021.3/Documentation/Manual/memory-allocator-customization.html for TLS we getting section of Thread Local Storage (TLS) stack allocator with Fast Per Thread Temporary Allocators.

In this case it is ALLOC_TEMP_MAIN so Main Thread Block Size would be my choice. Some of the others are also not hard to connect:

• ALLOC_TEMP_Background Job.worker #
  
  • Background Job Worker Block Size
• ALLOC_TEMP_BakingJobs.worker #.
  
  • Gl Baking Block Size
• ALLOC_TEMP_AUDIO_Audio Mixer Thread
  
  • Audio Worker Block Size
• ALLOC_TEMP_Job.worker #
  
  • Job Worker Block Size
• ALLOC_TEMP_UnityGfxDeviceWorker
  • Gfx Thread Block Size

There are only few that are less obvious but you can always ask about them if you are not sure.

Fast Thread Shared Temporary Allocators are only this 4 allocators

• [ALLOC_TEMP_JOB_1_FRAME]
  • Job Allocator Block Size
• [ALLOC_TEMP_JOB_2_FRAMES]
  • Job Allocator Block Size
• [ALLOC_TEMP_JOB_4_FRAMES (JobTemp)]
  • Job Allocator Block Size
• [ALLOC_TEMP_JOB_ASYNC (Background)]
  
  • Background Job Allocator Block Size

Lastly Job Allocator Block Sizes on low memory platforms is used in place of Job Allocator Block Size when device memory is smaller than 2GB.

We will work on giving more explicit information about it but till then I want to believe that this make it more clear.

It is correct. If you have high overflow count you may increase this size. Important here, is that this number is accumulation of overflows over whole run. This is important because you can have situation where overflow can happen mostly while loading and not a lot while running game. In such a place your suggestion of having API to dump it at any time would be super useful.

I understand argument of polluting the profiling and this is fair point. In case of the fallback allocator the issue is a little bit less oblivious. We recommend to not have them because they are slower. But in grand scale of things they are not that slow. What we do, when we cannot allocate memory we just fallback to less specialised allocator. In the game it should not be really noticeable till there is large quantity of them happening in one frame.

Reasons behind overflow is not always large amount of allocations. In case of Thread Local Storage (TLS) stack allocator very important is the way how we allocate memory. If someone misuse it, it can very fast overflow while holding as little as 1 byte of data. In case of Fast Thread Shared Temporary Allocators there is similar case where just bunch of small allocations which are hold for longer period of time could result in overflow on every allocation. This is of course not always possible to track by Unity users but if you see information about leaks or large amount of overflows it is worth to contact us so we could look and see what happening there.

Finally recommendation to tweak this value closer to the end of production is just recommendation. In my opinion this is a way to gain a little bit extra boos in product performance. When allocations becoming large performance issue in meantime of production, I would first look for the reasons why we get overflow.

Of course at the end of the day, this is just a guide. Every production is different and have different requirement. That is why we are giving you generic tool which you can use however you want.