AllowAsyncRenderThreadUpdatesDuringGamethreadUpdates

AllowAsyncRenderThreadUpdatesDuringGamethreadUpdates

#Overview

name: AllowAsyncRenderThreadUpdatesDuringGamethreadUpdates

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

• type: Var
• help: If > 0 then we do the gamethread updates _while_ doing parallel updates.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of AllowAsyncRenderThreadUpdatesDuringGamethreadUpdates is to control whether asynchronous render thread updates can occur concurrently with game thread updates in Unreal Engine 5.

This setting variable is primarily used by the Engine module, specifically in the level tick system. It affects the performance and threading behavior of the engine during frame updates.

The value of this variable is set through a console variable (CVar) named CVarAllowAsyncRenderThreadUpdatesDuringGamethreadUpdates. It’s initialized with a default value of 1, meaning it’s enabled by default.

The associated variable CVarAllowAsyncRenderThreadUpdatesDuringGamethreadUpdates directly interacts with AllowAsyncRenderThreadUpdatesDuringGamethreadUpdates. They share the same value and purpose.

Developers must be aware that this variable significantly impacts the engine’s threading behavior. When enabled (value > 0), it allows game thread updates to occur simultaneously with parallel updates, which can improve performance but may also introduce potential race conditions or synchronization issues if not properly managed.

Best practices when using this variable include:

1. Testing thoroughly with both enabled and disabled states to ensure game stability.
2. Monitoring performance metrics to determine if enabling this feature benefits your specific game.
3. Being cautious when modifying this setting in production, as it can have wide-ranging effects on game performance and stability.

Regarding the associated variable CVarAllowAsyncRenderThreadUpdatesDuringGamethreadUpdates:

Its purpose is identical to AllowAsyncRenderThreadUpdatesDuringGamethreadUpdates - controlling asynchronous render thread updates during game thread updates.

This CVar is used in the Engine module, specifically in the LevelTick.cpp file, which handles the game world’s tick logic.

The value is set when the engine initializes the console variable system, with a default value of 1.

It directly interacts with AllowAsyncRenderThreadUpdatesDuringGamethreadUpdates, as they represent the same setting.

Developers should be aware that this CVar can be changed at runtime through console commands, which allows for real-time adjustments to threading behavior.

Best practices include:

1. Using this CVar for debugging and performance tuning.
2. Documenting any changes made to this CVar in project settings or configuration files.
3. Considering the implications on multi-threaded code when modifying this value.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/LevelTick.cpp:778

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarAllowAsyncRenderThreadUpdatesDuringGamethreadUpdates(
	TEXT("AllowAsyncRenderThreadUpdatesDuringGamethreadUpdates"),
	1,
	TEXT("If > 0 then we do the gamethread updates _while_ doing parallel updates."));

static TAutoConsoleVariable<int32> CVarAllowAsyncRenderThreadUpdatesEditorGameWorld(
	TEXT("AllowAsyncRenderThreadUpdatesEditorGameWorld"),
	0,

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/LevelTick.cpp:777

Scope: file

Source code excerpt:

	TEXT("Used to control async renderthread updates. Also gated on FApp::ShouldUseThreadingForPerformance()."));

static TAutoConsoleVariable<int32> CVarAllowAsyncRenderThreadUpdatesDuringGamethreadUpdates(
	TEXT("AllowAsyncRenderThreadUpdatesDuringGamethreadUpdates"),
	1,
	TEXT("If > 0 then we do the gamethread updates _while_ doing parallel updates."));

static TAutoConsoleVariable<int32> CVarAllowAsyncRenderThreadUpdatesEditorGameWorld(
	TEXT("AllowAsyncRenderThreadUpdatesEditorGameWorld"),

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/LevelTick.cpp:1071

Scope (from outer to inner):

file
function     void UWorld::SendAllEndOfFrameUpdates

Source code excerpt:

	}

	const bool IsUsingParallelNotifyEvents = CVarAllowAsyncRenderThreadUpdatesDuringGamethreadUpdates.GetValueOnGameThread() > 0 && 
		LocalComponentsThatNeedEndOfFrameUpdate.Num() > FTaskGraphInterface::Get().GetNumWorkerThreads() &&
		FTaskGraphInterface::Get().GetNumWorkerThreads() > 2;

	auto ParallelWork = [IsUsingParallelNotifyEvents](int32 Index)
	{
		TRACE_CPUPROFILER_EVENT_SCOPE(DeferredRenderUpdates);