gc.GarbageEliminationEnabled

gc.GarbageEliminationEnabled

#Overview

name: gc.GarbageEliminationEnabled

The value of this variable can be defined or overridden in .ini config files. 2 .ini config files referencing this setting variable.

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of gc.GarbageEliminationEnabled is to control the automatic nulling and destruction of objects marked as Garbage by the Unreal Engine’s Garbage Collector.

This setting variable is primarily used by the Unreal Engine’s CoreUObject module, specifically within the garbage collection system. It is referenced in the UObjectBaseUtility class, which is a core part of Unreal Engine’s object management system.

The value of this variable is set through multiple mechanisms:

  1. It is initially set as a console variable with a default value of 1 (enabled).
  2. It can be overridden by project settings in the GEngineIni file under the [/Script/Engine.GarbageCollectionSettings] section.
  3. It can be disabled via command-line arguments “DisablePendingKill” or “DisableGarbageElimination”.

This variable interacts with a deprecated setting called “gc.PendingKillEnabled”. There’s an upgrade path in place to transition from the old setting to the new “gc.GarbageEliminationEnabled” setting.

Developers must be aware of the following when using this variable:

  1. Changing this setting can significantly impact memory management and performance.
  2. There’s a deprecated setting (gc.PendingKillEnabled) that takes precedence if present in the project settings.
  3. Command-line arguments can override this setting, which is useful for testing purposes.

Best practices when using this variable include:

  1. Generally, keep it enabled unless there’s a specific reason to disable it.
  2. If using the old “gc.PendingKillEnabled” setting, update to “gc.GarbageEliminationEnabled” for future compatibility.
  3. Be cautious when disabling this feature, as it may lead to memory leaks if objects aren’t manually destroyed.
  4. When testing different garbage collection behaviors, use command-line arguments for temporary changes rather than modifying the project settings.
  5. Monitor performance and memory usage when adjusting this setting, especially in large or complex projects.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseEngine.ini:1534, section: [/Script/Engine.GarbageCollectionSettings]

Location: <Workspace>/Projects/Lyra/Config/DefaultEngine.ini:76, section: [/Script/Engine.GarbageCollectionSettings]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/CoreUObject/Private/UObject/ObjectBaseUtility.cpp:169

Scope: file

Source code excerpt:

int32 GGarbageEliminationEnabled = 1;
static FAutoConsoleVariableRef CVarGarbageEliminationEnabled(
	TEXT("gc.GarbageEliminationEnabled"),
	GGarbageEliminationEnabled,
	TEXT("If true, objects marked as Garbage will be automatically nulled and destroyed by Garbage Collector."),
	ECVF_Default
);
bool UObjectBaseUtility::bGarbageEliminationEnabled = !!GGarbageEliminationEnabled;

#Loc: <Workspace>/Engine/Source/Runtime/CoreUObject/Private/UObject/ObjectBaseUtility.cpp:182

Scope (from outer to inner):

file
function     void InitGarbageElimination

Source code excerpt:

	if (GConfig->GetBool(TEXT("/Script/Engine.GarbageCollectionSettings"), TEXT("gc.PendingKillEnabled"), bGarbageEliminationEnabled, GEngineIni))
	{
		// The old gc.PendingKillEnabled will always take precedence over gc.GarbageEliminationEnabled because the new setting is always present in BaseEngine.ini
		// so until the project-level setting is renamed we assume the upgrade hasn't happened yet and the old setting should be used
		UE_LOG(LogObj, Warning, TEXT("Deprecated ini setting [/Script/Engine.GarbageCollectionSettings] gc.PendingKillEnabled=%s found. Please rename it to gc.GarbageEliminationEnabled"),
			bGarbageEliminationEnabled ? TEXT("true") : TEXT("false"));
	}
	else
	{
		GConfig->GetBool(TEXT("/Script/Engine.GarbageCollectionSettings"), TEXT("gc.GarbageEliminationEnabled"), bGarbageEliminationEnabled, GEngineIni);
	}

	// Allow command-line overrides for easy testing without unique builds.
	if (FParse::Param(FCommandLine::Get(), TEXT("DisablePendingKill")) || FParse::Param(FCommandLine::Get(), TEXT("DisableGarbageElimination")))
	{
		bGarbageEliminationEnabled = false;

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/CoreSettings.cpp:226

Scope (from outer to inner):

file
function     void UGarbageCollectionSettings::PostInitProperties

Source code excerpt:

		ImportConsoleVariableValues();

		// Upgrade path for gc.PendingKillEnabled -> gc.GarbageEliminationEnabled
		bool bGarbageEliminationEnabledIni = false;
		if (GConfig->GetBool(TEXT("/Script/Engine.GarbageCollectionSettings"), TEXT("gc.PendingKillEnabled"), bGarbageEliminationEnabledIni, GEngineIni))
		{
			// No need to warn to upgrade to "gc.GarbageEliminationEnabled" as we've already done this in ObjectBaseUtility.cpp InitGarbageElimination()
			GarbageEliminationEnabled = bGarbageEliminationEnabledIni;
		}
	}
#endif // #if WITH_EDITOR
}