gc.StressTestGC

gc.StressTestGC

#Overview

name: gc.StressTestGC

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

• type: Var
• help: If set to 1, the engine will attempt to trigger GC each frame while async loading.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of gc.StressTestGC is to enable stress testing of the Garbage Collection (GC) system in Unreal Engine 5, specifically during asynchronous loading operations.

This setting variable is primarily used by the Engine’s garbage collection and memory management subsystem. It is referenced in the UnrealEngine.cpp file, which is part of the core Engine module.

The value of this variable is set through a console variable (CVarStressTestGCWhileStreaming) using the TAutoConsoleVariable template. It is initialized with a default value of 0, meaning the stress test is disabled by default.

The associated variable CVarStressTestGCWhileStreaming directly interacts with gc.StressTestGC. They share the same value and purpose.

Developers must be aware that this variable is only active in non-shipping and non-test builds (as indicated by the #if !(UE_BUILD_SHIPPING || UE_BUILD_TEST) preprocessor directive). When enabled (set to 1), it will attempt to trigger garbage collection each frame during asynchronous loading, which can significantly impact performance.

Best practices when using this variable include:

1. Only enable it for debugging and stress testing purposes.
2. Be cautious when enabling it in performance-critical scenarios.
3. Use it in conjunction with profiling tools to understand its impact on memory management and performance.

Regarding the associated variable CVarStressTestGCWhileStreaming:

The purpose of CVarStressTestGCWhileStreaming is to provide a programmatic way to control the gc.StressTestGC setting within the engine’s code.

This variable is used in the Engine module, specifically in the UEngine::ConditionalCollectGarbage() function. It’s checked each frame to determine whether to force garbage collection during async loading.

The value of CVarStressTestGCWhileStreaming is set through the console variable system and can be changed at runtime.

It interacts directly with the gc.StressTestGC setting, effectively controlling when and how the garbage collection stress test is performed.

Developers should be aware that using this variable can have a significant impact on performance and should only be used for testing and debugging purposes.

Best practices for using CVarStressTestGCWhileStreaming include:

1. Use it in development builds only.
2. Monitor its impact on performance and memory usage.
3. Consider using it in combination with other GC-related console variables for comprehensive testing.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

#if !(UE_BUILD_SHIPPING || UE_BUILD_TEST)
static TAutoConsoleVariable<int32> CVarStressTestGCWhileStreaming(
	TEXT("gc.StressTestGC"),
	0,
	TEXT("If set to 1, the engine will attempt to trigger GC each frame while async loading."));
static TAutoConsoleVariable<int32> CVarForceCollectGarbageEveryFrame(
	TEXT("gc.ForceCollectGarbageEveryFrame"),
	0,
	TEXT("If set to 1, the engine will force GC each frame."));

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

#if !(UE_BUILD_SHIPPING || UE_BUILD_TEST)
static TAutoConsoleVariable<int32> CVarStressTestGCWhileStreaming(
	TEXT("gc.StressTestGC"),
	0,
	TEXT("If set to 1, the engine will attempt to trigger GC each frame while async loading."));
static TAutoConsoleVariable<int32> CVarForceCollectGarbageEveryFrame(
	TEXT("gc.ForceCollectGarbageEveryFrame"),
	0,

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

Scope (from outer to inner):

file
function     void UEngine::ConditionalCollectGarbage

Source code excerpt:

#if !(UE_BUILD_SHIPPING || UE_BUILD_TEST)
		if (CVarStressTestGCWhileStreaming.GetValueOnGameThread() && IsAsyncLoading())
		{
			CollectGarbage(GARBAGE_COLLECTION_KEEPFLAGS, true);
		}
		else if (CVarForceCollectGarbageEveryFrame.GetValueOnGameThread())
		{
			CollectGarbage(GARBAGE_COLLECTION_KEEPFLAGS, true);