Configuring garbage collection
Set up the garbage collector in your project.
Read time 3 minutesLast updated 13 days ago
The garbage collection mode can be configured in the following ways:
- Disable incremental garbage collection
- Use the APIs in the class to manually control the garbage collector, or disable it completely.
GarbageCollector - Use to perform a full, blocking garbage collection.
System.GC.Collect
Disabling incremental garbage collection
To disable incremental garbage collection:
- Open the Project Settings window (Edit > )Project Settings
?
- Navigate to the Configuration settings (Player > Other Settings > Configuration)
- Disable the Use Incremental GC checkbox.
Note
Incremental garbage collection isn't available for the CoreCLR scripting back end.
Incremental garbage collection is useful in most Unity projects, especially if the project has garbage collection spikes. However, incremental garbage collection adds write barriers to any calls that change references, so you might want to disable it if your project doesn't trigger garbage collection in performance critical sections. Disabling incremental garbage collection in this situation can improve the performance of your scripting code in your project.
Use the Profiler to verify that your application performs as you expect. If you analyze a Profiler capture in isolation, it can be difficult to find out how incremental garbage collection affects performance. It's best practice to profile the same performance critical section twice: once with incremental garbage collection enabled, and once with incremental garbage collection disabled. You can then compare both Profiler captures with the Profile Analyzer package. For CPU bound projects, the difference can be as much as 1 ms per frame.
For more information on disabling garbage collection, refer to Garbage collection modes.
Using the GarbageCollector API
You can use the APIs in the class to manually control or disable the garbage collector for the Mono and IL2CPP scripting back ends. You can use the following APIs to control the garbage collector:
GarbageCollector- : Setting GarbageCollector.GCMode to this fully disables the garbage collector. Using
GarbageCollector.Mode.Disabledin this mode has no effect.System.GC.Collect - : Setting GarbageCollector.GCMode to this fully disables automatic invocations of the garbage collector, but you can still use
GarbageCollector.Mode.Manualto run a full collection.System.GC.Collect - : Runs the garbage collector incrementally.
GarbageCollector.CollectIncremental
Note
The API isn't supported for the CoreCLR scritping back end.
GarbageCollectorDisabling the garbage collector
To disable the garbage collector completely, set to . When you disable the garbage collector, Unity doesn't perform any garbage collection. Calling has no effect and doesn't start a collection.
GarbageCollector.GCModeDisabledSystem.GC.CollectDisabling the garbage collector prevents CPU spikes, but the memory usage of your application never decreases, because the garbage collector doesn't collect objects that no longer have any references.
Disabling the garbage collector requires careful memory management. If you don't manage memory carefully, the managed heap continuously expands until your application runs out of memory, and the operating system shuts it down.
Ideally, you should allocate all memory before you disable the garbage collector and avoid additional allocations while it is disabled.
Manually run the garbage collector
Manual collection gives you control over when collections happen, so you can fine-tune the smoothness of your application's content or memory usage. Manual collections can be invoked regardless of whether is or not.
GarbageCollector.GCModeManualYou can trigger a manual garbage collection in one of the following ways:
- To perform a full, blocking collection on any scripting back end, call .
System.GC.Collect - To perform an incremental garbage collection on the Mono or IL2CPP scripting back ends, call .
GarbageCollector.CollectIncremental