p.Chaos.Solver.IslandGroups.MaxWorkers

p.Chaos.Solver.IslandGroups.MaxWorkers

#Overview

name: p.Chaos.Solver.IslandGroups.MaxWorkers

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 p.Chaos.Solver.IslandGroups.MaxWorkers is to control the maximum number of worker threads used in the Chaos physics solver’s island group system. This setting is part of Unreal Engine’s physics simulation subsystem, specifically the Chaos physics engine.

The Chaos physics solver, which is part of the Experimental Chaos module in Unreal Engine 5, relies on this setting variable. It’s used to manage the parallelization of physics computations across multiple threads.

The value of this variable is set through the Unreal Engine’s console variable system. It’s initialized to 0 by default, which means there’s no limit on the number of worker threads.

This variable interacts closely with GIslandGroupsMaxWorkers, which is the associated C++ variable that directly holds the value set by p.Chaos.Solver.IslandGroups.MaxWorkers.

Developers must be aware that:

  1. Setting this to 0 allows unlimited worker threads, which might not always be optimal.
  2. This variable affects the physics simulation performance and should be tuned carefully based on the target hardware and the complexity of the physics scene.
  3. It works in conjunction with other physics solver settings, such as MinConstraintsPerWorker.

Best practices when using this variable include:

  1. Profiling the physics performance with different values to find the optimal setting for your specific game and target hardware.
  2. Considering the balance between this setting and the MinConstraintsPerWorker setting to ensure efficient distribution of work.
  3. Being cautious about setting it too high on systems with many cores, as it might lead to overhead from task management.

Regarding the associated variable GIslandGroupsMaxWorkers:

The purpose of GIslandGroupsMaxWorkers is to serve as the actual storage for the value set by p.Chaos.Solver.IslandGroups.MaxWorkers. It’s an internal variable used by the Chaos physics engine to determine the maximum number of worker threads.

This variable is used directly in the FPBDIslandGroupManager constructor to calculate the number of island groups for physics computation. It’s part of the core logic that determines how physics tasks are distributed across available processing resources.

The value of GIslandGroupsMaxWorkers is set by the console variable system when p.Chaos.Solver.IslandGroups.MaxWorkers is modified.

Developers should be aware that modifying GIslandGroupsMaxWorkers directly in code is not recommended. Instead, they should use the console variable p.Chaos.Solver.IslandGroups.MaxWorkers to ensure proper synchronization and management by the engine.

Best practices for GIslandGroupsMaxWorkers include:

  1. Treating it as a read-only variable in most scenarios.
  2. Using it for conditional logic in physics-related code where the maximum number of workers needs to be known.
  3. Ensuring that any code depending on this value can handle the case where it’s set to 0 (unlimited workers).

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/Island/IslandGroupManager.cpp:40

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:

		// Do not use more worker threads than this for the main solve (0 for unlimited)
		int32 GIslandGroupsMaxWorkers = 0;
		FAutoConsoleVariableRef GCVarIslandGroupsMaxWorkers(TEXT("p.Chaos.Solver.IslandGroups.MaxWorkers"), GIslandGroupsMaxWorkers, TEXT("The maximum number of worker threads to use (0 means unlimited)"));

		// We want a minimum number of constraints to gather/solve/scatter on each thread. This prevents us running too many tiny tasks on a many-core machine
		int32 GIslandGroupsMinConstraintsPerWorker = 50;
		FAutoConsoleVariableRef GCVarIslandGroupsMinConstraintsPerWorker(TEXT("p.Chaos.Solver.IslandGroups.MinConstraintsPerWorker"), GIslandGroupsMinConstraintsPerWorker, TEXT("The minimum number of constraints we want per worker thread"));

		// We want a minimum number of bodies to gather on each thread. This prevents us running too many tiny tasks on a many-core machine

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/Island/IslandGroupManager.cpp:39

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:


		// Do not use more worker threads than this for the main solve (0 for unlimited)
		int32 GIslandGroupsMaxWorkers = 0;
		FAutoConsoleVariableRef GCVarIslandGroupsMaxWorkers(TEXT("p.Chaos.Solver.IslandGroups.MaxWorkers"), GIslandGroupsMaxWorkers, TEXT("The maximum number of worker threads to use (0 means unlimited)"));

		// We want a minimum number of constraints to gather/solve/scatter on each thread. This prevents us running too many tiny tasks on a many-core machine
		int32 GIslandGroupsMinConstraintsPerWorker = 50;
		FAutoConsoleVariableRef GCVarIslandGroupsMinConstraintsPerWorker(TEXT("p.Chaos.Solver.IslandGroups.MinConstraintsPerWorker"), GIslandGroupsMinConstraintsPerWorker, TEXT("The minimum number of constraints we want per worker thread"));

		// We want a minimum number of bodies to gather on each thread. This prevents us running too many tiny tasks on a many-core machine

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/Island/IslandGroupManager.cpp:67

Scope (from outer to inner):

file
namespace    Chaos
namespace    Private
function     FPBDIslandGroupManager::FPBDIslandGroupManager

Source code excerpt:

			// @todo(chaos): is the number of worker threads a good indicator of how many threads we get in the solver loop? (Currently uses ParallelFor)
			NumWorkerThreads = (FApp::ShouldUseThreadingForPerformance() && !GSingleThreadedPhysics) ? FMath::Min(FTaskGraphInterface::Get().GetNumWorkerThreads(), Chaos::MaxNumWorkers) : 0;
			const int32 MaxIslandGroups = (CVars::GIslandGroupsMaxWorkers > 0) ? CVars::GIslandGroupsMaxWorkers : TNumericLimits<int32>::Max();
			const int32 NumIslandGroups = FMath::Clamp(FMath::CeilToInt32(FReal(NumWorkerThreads) * CVars::GIslandGroupsWorkerMultiplier), 1, MaxIslandGroups);

			IslandGroups.Reserve(NumIslandGroups);
			for (int32 GroupIndex = 0; GroupIndex < NumIslandGroups; ++GroupIndex)
			{
				IslandGroups.Emplace(MakeUnique<FPBDIslandConstraintGroupSolver>(IslandManager));