stats | An array to receive the count of free blocks grouped by power of two sizes. Given a small array, Unity counts the larger free blocks together in the final array element. |
long Returns the total number of free blocks in the dynamic heap.
Returns heap memory fragmentation information.
Heap fragmentation is a measure of how much space is potentially unusable in the dynamic heap. If your application has too much heap fragmentation it can lead to memory allocation failures.
There might be more total free memory than your application needs for an allocation, but because this free memory is composed of two or more separate smaller memory blocks, then the allocation might fail.
Some memory usage patterns at runtime can cause the number of free blocks to grow over time, which results in fragmentation of the heap.
As an example, consider when Unity frees a large allocation, a single large free block is returned to the heap. This large free block could then later be used to satisfy many more smaller allocations if no smaller blocks are available.
If all these small allocations other than a single allocation in the middle of this block are freed, then the heap now has two smaller free blocks either side of the single remaining allocation. A new allocation of the original large size might fail if there are no larger blocks available to use.
As Unity dynamically allocates and frees memory, it manages the heap area by keeping track of free memory blocks. Internally, Unity groups these free memory blocks into lists of similar sizes - grouped in power of two sizes, between one power of two and the next, specifically [ (2^n) .. (2^(n+1) - 1) ].
e.g. blocks of sizes [1], [2..3], [4..7], [8..15], [16..31], [32..63], [64..127], [128..256] ... bytes.
This design gives quick and constant time allocator performance for all allocations regardless of allocation size or heap capacity.
You can use Profiler.GetTotalFragmentationInfo to keep track of the heap's free memory blocks over time.
using Unity.Collections; using UnityEngine; using UnityEngine.Profiling;
public class Example : MonoBehaviour { const int kFreeBlockPow2Buckets = 24;
void Update() { var freeStats = new NativeArray<int>(kFreeBlockPow2Buckets, Allocator.Temp); var freeBlocks = Profiler.GetTotalFragmentationInfo(freeStats);
Debug.Log(string.Format("Total Free Blocks: {0}", freeBlocks)); for (int i = 0; i < kFreeBlockPow2Buckets; i++) { Debug.Log(string.Format(" size[2^{0}] = {1} blocks", i, freeStats[i])); } } }
Did you find this page useful? Please give it a rating:
Thanks for rating this page!
What kind of problem would you like to report?
Thanks for letting us know! This page has been marked for review based on your feedback.
If you have time, you can provide more information to help us fix the problem faster.
Provide more information
You've told us this page needs code samples. If you'd like to help us further, you could provide a code sample, or tell us about what kind of code sample you'd like to see:
You've told us there are code samples on this page which don't work. If you know how to fix it, or have something better we could use instead, please let us know:
You've told us there is information missing from this page. Please tell us more about what's missing:
You've told us there is incorrect information on this page. If you know what we should change to make it correct, please tell us:
You've told us this page has unclear or confusing information. Please tell us more about what you found unclear or confusing, or let us know how we could make it clearer:
You've told us there is a spelling or grammar error on this page. Please tell us what's wrong:
You've told us this page has a problem. Please tell us more about what's wrong:
Thank you for helping to make the Unity documentation better!
Your feedback has been submitted as a ticket for our documentation team to review.
We are not able to reply to every ticket submitted.