demo.LoadCheckpointGarbageCollect

demo.LoadCheckpointGarbageCollect

#Overview

name: demo.LoadCheckpointGarbageCollect

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 demo.LoadCheckpointGarbageCollect is to control whether garbage collection is performed during the loading of a checkpoint in Unreal Engine’s demo playback system.

This setting variable is primarily used by the demo playback system, which is part of Unreal Engine’s networking and replication subsystem. It’s specifically related to the checkpoint loading process in demo recordings.

The value of this variable is set as a console variable, which means it can be changed at runtime. It’s initialized with a default value of 1 (enabled) in the source code.

The associated variable CVarDemoLoadCheckpointGarbageCollect directly interacts with demo.LoadCheckpointGarbageCollect. They share the same value and purpose.

Developers must be aware that enabling this variable (setting it to a non-zero value) will trigger a garbage collection after old actors and connections are cleaned up during checkpoint loading. This can have performance implications, as garbage collection can be a costly operation.

Best practices when using this variable include:

  1. Consider the performance impact of enabling garbage collection during checkpoint loading, especially for large or complex demos.
  2. Use this setting judiciously, balancing memory management needs with performance requirements.
  3. Test thoroughly with both enabled and disabled states to understand the impact on your specific use case.

Regarding the associated variable CVarDemoLoadCheckpointGarbageCollect:

This is the C++ representation of the demo.LoadCheckpointGarbageCollect console variable. It’s used in the UDemoNetDriver::LoadCheckpoint function to determine whether to perform garbage collection after cleaning up old actors and connections.

The variable is checked using GetValueOnGameThread() to ensure thread-safe access. If the value is non-zero, the engine forces garbage collection using GEngine->ForceGarbageCollection(true).

Developers should be aware that this variable directly affects the behavior of checkpoint loading in demo playback. Enabling it can help manage memory more aggressively but at the cost of potential performance overhead during checkpoint loading.

When working with this variable, consider the same best practices as mentioned for demo.LoadCheckpointGarbageCollect, as they are essentially the same setting exposed through different interfaces (console variable and C++ code).

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/DemoNetDriver.cpp:57

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarDemoAsyncLoadWorld( TEXT( "demo.AsyncLoadWorld" ), 0, TEXT( "If 1, we will use seamless server travel to load the replay world asynchronously" ) );
TAutoConsoleVariable<float> CVarCheckpointUploadDelayInSeconds( TEXT( "demo.CheckpointUploadDelayInSeconds" ), 30.0f, TEXT( "" ) );
static TAutoConsoleVariable<int32> CVarDemoLoadCheckpointGarbageCollect( TEXT( "demo.LoadCheckpointGarbageCollect" ), 1, TEXT("If nonzero, CollectGarbage will be called during LoadCheckpoint after the old actors and connection are cleaned up." ) );
TAutoConsoleVariable<float> CVarCheckpointSaveMaxMSPerFrameOverride( TEXT( "demo.CheckpointSaveMaxMSPerFrameOverride" ), -1.0f, TEXT( "If >= 0, this value will override the CheckpointSaveMaxMSPerFrame member variable, which is the maximum time allowed each frame to spend on saving a checkpoint. If 0, it will save the checkpoint in a single frame, regardless of how long it takes." ) );
TAutoConsoleVariable<int32> CVarDemoClientRecordAsyncEndOfFrame( TEXT( "demo.ClientRecordAsyncEndOfFrame" ), 0, TEXT( "If true, TickFlush will be called on a thread in parallel with Slate." ) );
static TAutoConsoleVariable<int32> CVarForceDisableAsyncPackageMapLoading( TEXT( "demo.ForceDisableAsyncPackageMapLoading" ), 0, TEXT( "If true, async package map loading of network assets will be disabled." ) );
TAutoConsoleVariable<int32> CVarDemoUseNetRelevancy( TEXT( "demo.UseNetRelevancy" ), 0, TEXT( "If 1, will enable relevancy checks and distance culling, using all connected clients as reference." ) );
static TAutoConsoleVariable<float> CVarDemoCullDistanceOverride( TEXT( "demo.CullDistanceOverride" ), 0.0f, TEXT( "If > 0, will represent distance from any viewer where actors will stop being recorded." ) );
static TAutoConsoleVariable<float> CVarDemoRecordHzWhenNotRelevant( TEXT( "demo.RecordHzWhenNotRelevant" ), 2.0f, TEXT( "Record at this frequency when actor is not relevant." ) );

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/DemoNetDriver.cpp:57

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarDemoAsyncLoadWorld( TEXT( "demo.AsyncLoadWorld" ), 0, TEXT( "If 1, we will use seamless server travel to load the replay world asynchronously" ) );
TAutoConsoleVariable<float> CVarCheckpointUploadDelayInSeconds( TEXT( "demo.CheckpointUploadDelayInSeconds" ), 30.0f, TEXT( "" ) );
static TAutoConsoleVariable<int32> CVarDemoLoadCheckpointGarbageCollect( TEXT( "demo.LoadCheckpointGarbageCollect" ), 1, TEXT("If nonzero, CollectGarbage will be called during LoadCheckpoint after the old actors and connection are cleaned up." ) );
TAutoConsoleVariable<float> CVarCheckpointSaveMaxMSPerFrameOverride( TEXT( "demo.CheckpointSaveMaxMSPerFrameOverride" ), -1.0f, TEXT( "If >= 0, this value will override the CheckpointSaveMaxMSPerFrame member variable, which is the maximum time allowed each frame to spend on saving a checkpoint. If 0, it will save the checkpoint in a single frame, regardless of how long it takes." ) );
TAutoConsoleVariable<int32> CVarDemoClientRecordAsyncEndOfFrame( TEXT( "demo.ClientRecordAsyncEndOfFrame" ), 0, TEXT( "If true, TickFlush will be called on a thread in parallel with Slate." ) );
static TAutoConsoleVariable<int32> CVarForceDisableAsyncPackageMapLoading( TEXT( "demo.ForceDisableAsyncPackageMapLoading" ), 0, TEXT( "If true, async package map loading of network assets will be disabled." ) );
TAutoConsoleVariable<int32> CVarDemoUseNetRelevancy( TEXT( "demo.UseNetRelevancy" ), 0, TEXT( "If 1, will enable relevancy checks and distance culling, using all connected clients as reference." ) );
static TAutoConsoleVariable<float> CVarDemoCullDistanceOverride( TEXT( "demo.CullDistanceOverride" ), 0.0f, TEXT( "If > 0, will represent distance from any viewer where actors will stop being recorded." ) );
static TAutoConsoleVariable<float> CVarDemoRecordHzWhenNotRelevant( TEXT( "demo.RecordHzWhenNotRelevant" ), 2.0f, TEXT( "Record at this frequency when actor is not relevant." ) );

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/DemoNetDriver.cpp:4233

Scope (from outer to inner):

file
function     bool UDemoNetDriver::LoadCheckpoint

Source code excerpt:


	// Optionally collect garbage after the old actors and connection are cleaned up - there could be a lot of pending-kill objects at this point.
	if (CVarDemoLoadCheckpointGarbageCollect.GetValueOnGameThread() != 0)
	{
		GEngine->ForceGarbageCollection(true);
	}

	FURL ConnectURL;
	ConnectURL.Map = ReplayHelper.DemoURL.Map;