gc.ContinuousIncrementalGC

gc.ContinuousIncrementalGC

#Overview

name: gc.ContinuousIncrementalGC

This variable is created as a Console Variable (cvar).

• type: Var
• help: Used to debug garbage collection...Kicks off Incremental Garbage Collection as soon as the previous one finishes.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of gc.ContinuousIncrementalGC is to debug the garbage collection system in Unreal Engine. It is designed to trigger Incremental Garbage Collection continuously, starting a new cycle as soon as the previous one finishes.

This setting variable is primarily used by the garbage collection subsystem within Unreal Engine’s core runtime. Based on the callsites, it is referenced in the Engine module, specifically in the UnrealEngine.cpp file.

The value of this variable is set through a console variable system. It is initialized with a default value of 0, which means the continuous incremental garbage collection is disabled by default.

The associated variable CVarContinuousIncrementalGC interacts directly with gc.ContinuousIncrementalGC. It is an instance of TAutoConsoleVariable that wraps the console variable and provides an interface for accessing its value.

Developers must be aware that enabling this variable (setting it to a value greater than 0) will cause the garbage collector to run continuously, which can significantly impact performance. This should only be used for debugging purposes and not in production environments.

Best practices when using this variable include:

1. Only enable it when specifically debugging garbage collection issues.
2. Monitor performance closely when it’s enabled, as it can cause significant overhead.
3. Remember to disable it after debugging is complete.
4. Use in conjunction with other garbage collection debugging tools and metrics for a comprehensive analysis.

Regarding the associated variable CVarContinuousIncrementalGC:

The purpose of CVarContinuousIncrementalGC is to provide a programmatic interface to the gc.ContinuousIncrementalGC console variable within the C++ code.

This variable is used in the Engine module, specifically in the garbage collection logic of the UEngine class.

The value of CVarContinuousIncrementalGC is set when the gc.ContinuousIncrementalGC console variable is modified, either through console commands or configuration files.

CVarContinuousIncrementalGC interacts directly with the gc.ContinuousIncrementalGC console variable, acting as a proxy for its value in the C++ code.

Developers should be aware that this variable is used in the ConditionalCollectGarbage function of the UEngine class to determine whether to force garbage collection.

Best practices for using CVarContinuousIncrementalGC include:

1. Access its value using the GetValueOnGameThread() method to ensure thread-safety.
2. Be cautious about modifying its value at runtime, as it can have significant performance implications.
3. Use it in conjunction with other garbage collection-related variables and functions for comprehensive garbage collection control and debugging.

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/UnrealEngine.cpp:1595

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarContinuousIncrementalGC(
	TEXT("gc.ContinuousIncrementalGC"),
	0,
	TEXT("Used to debug garbage collection...Kicks off Incremental Garbage Collection as soon as the previous one finishes."));

static float GTimeBetweenPurgingPendingKillObjects = 60.0f;
static FAutoConsoleVariableRef CVarTimeBetweenPurgingPendingKillObjects(
	TEXT("gc.TimeBetweenPurgingPendingKillObjects"),

#Associated Variable and Callsites

This variable is associated with another variable named CVarContinuousIncrementalGC. They share the same value. See the following C++ source code.

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/UnrealEngine.cpp:1594

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarContinuousIncrementalGC(
	TEXT("gc.ContinuousIncrementalGC"),
	0,
	TEXT("Used to debug garbage collection...Kicks off Incremental Garbage Collection as soon as the previous one finishes."));

static float GTimeBetweenPurgingPendingKillObjects = 60.0f;
static FAutoConsoleVariableRef CVarTimeBetweenPurgingPendingKillObjects(

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/UnrealEngine.cpp:1898

Scope (from outer to inner):

file
function     void UEngine::ConditionalCollectGarbage

Source code excerpt:

			}
		}
		else if (CVarContinuousIncrementalGC.GetValueOnGameThread() > 0 && !IsIncrementalReachabilityAnalysisPending() && !IsIncrementalUnhashPending() && !IsIncrementalPurgePending())
		{
			ForceGarbageCollection(false);
		}

		LastGCFrame = GFrameCounter;
	}