Sequencer.ThreadedEvaluation.AllocationThreshold

Sequencer.ThreadedEvaluation.AllocationThreshold

#Overview

name: Sequencer.ThreadedEvaluation.AllocationThreshold

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 Sequencer.ThreadedEvaluation.AllocationThreshold is to define the entity allocation fragmentation threshold above which threaded evaluation will be used in Unreal Engine’s Sequencer system.

This setting variable is primarily used by the MovieScene module, which is part of Unreal Engine’s cinematics and animation system. Specifically, it’s utilized in the entity system of the Sequencer, which is responsible for managing and evaluating animated elements in a scene.

The value of this variable is set through the Unreal Engine console variable system. It’s initialized with a default value of 32 and can be modified at runtime using console commands.

This variable interacts closely with another variable named GThreadedEvaluationEntityThreshold. Together, these variables determine when the system should switch to threaded evaluation for better performance.

Developers should be aware that this threshold is a performance-related setting. It’s part of a heuristic to determine when parallel processing becomes beneficial for scene evaluation. The optimal value may vary depending on the platform, hardware, and specific use case.

Best practices when using this variable include:

  1. Monitoring performance metrics to determine if the default value is suitable for your project.
  2. Experimenting with different values to find the optimal balance between single-threaded and multi-threaded evaluation for your specific scenes.
  3. Considering the target hardware when adjusting this value, as the optimal threshold may differ across different devices.

Regarding the associated variable GThreadedEvaluationAllocationThreshold:

The purpose of GThreadedEvaluationAllocationThreshold is to store the actual value used by the system for the allocation threshold. It’s the C++ variable that directly controls the behavior, while Sequencer.ThreadedEvaluation.AllocationThreshold is the console variable that allows runtime modification of this value.

This variable is used in the MovieScene module, specifically in the FEntityManager class, to determine the threading model for entity evaluation.

The value of GThreadedEvaluationAllocationThreshold is set by the console variable system when Sequencer.ThreadedEvaluation.AllocationThreshold is modified.

It interacts with GThreadedEvaluationEntityThreshold in the ComputeThreadingModel function to decide whether to use threaded evaluation.

Developers should be aware that modifying GThreadedEvaluationAllocationThreshold directly in code is not recommended. Instead, they should use the console variable Sequencer.ThreadedEvaluation.AllocationThreshold to ensure proper synchronization and runtime flexibility.

Best practices for GThreadedEvaluationAllocationThreshold include:

  1. Avoiding direct modification in code unless absolutely necessary.
  2. Using it in conjunction with GThreadedEvaluationEntityThreshold for performance tuning.
  3. Considering its impact on different hardware configurations when optimizing performance.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/MovieScene/Private/EntitySystem/MovieSceneEntityManager.cpp:40

Scope (from outer to inner):

file
namespace    UE
namespace    MovieScene

Source code excerpt:

int32 GThreadedEvaluationAllocationThreshold = 32;
FAutoConsoleVariableRef CVarThreadedEvaluationAllocationThreshold(
	TEXT("Sequencer.ThreadedEvaluation.AllocationThreshold"),
	GThreadedEvaluationAllocationThreshold,
	TEXT("(Default: 32) Defines the entity allocation fragmentation threshold above which threaded evaluation will be used.\n"),
	ECVF_Default
);
int32 GThreadedEvaluationEntityThreshold = 256;
FAutoConsoleVariableRef CVarThreadedEvaluationEntityThreshold(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/MovieScene/Private/EntitySystem/MovieSceneEntityManager.cpp:38

Scope (from outer to inner):

file
namespace    UE
namespace    MovieScene

Source code excerpt:

// @todo: this is a very rough initial guess at the break even point for when threaded evaluation becomes beneficial, and will vary highly between platforms and hardware.
// We may wish to make this more flexible in future (such as only threading hot paths such as float channel evaluation) by enabling threading per-task, but more data is required to make such decisions
int32 GThreadedEvaluationAllocationThreshold = 32;
FAutoConsoleVariableRef CVarThreadedEvaluationAllocationThreshold(
	TEXT("Sequencer.ThreadedEvaluation.AllocationThreshold"),
	GThreadedEvaluationAllocationThreshold,
	TEXT("(Default: 32) Defines the entity allocation fragmentation threshold above which threaded evaluation will be used.\n"),
	ECVF_Default
);
int32 GThreadedEvaluationEntityThreshold = 256;
FAutoConsoleVariableRef CVarThreadedEvaluationEntityThreshold(
	TEXT("Sequencer.ThreadedEvaluation.EntityThreshold"),

#Loc: <Workspace>/Engine/Source/Runtime/MovieScene/Private/EntitySystem/MovieSceneEntityManager.cpp:553

Scope (from outer to inner):

file
namespace    UE
namespace    MovieScene
function     EEntityThreadingModel FEntityManager::ComputeThreadingModel

Source code excerpt:


	const bool bShouldThread = bCanThread &&
		(EntityAllocations.Num() >= GThreadedEvaluationAllocationThreshold ||
		EntityLocations.Num() >= GThreadedEvaluationEntityThreshold);

	return bShouldThread ? EEntityThreadingModel::TaskGraph : EEntityThreadingModel::NoThreading;
}

EEntityThreadingModel FEntityManager::GetThreadingModel() const