p.Chaos.DisablePhysicsParallelFor

p.Chaos.DisablePhysicsParallelFor

#Overview

name: p.Chaos.DisablePhysicsParallelFor

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

It is referenced in 7 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.Chaos.DisablePhysicsParallelFor is to disable parallel execution in Chaos Evolution, which is part of Unreal Engine’s physics simulation system.

This setting variable is primarily used in the Chaos physics system, which is an experimental physics engine in Unreal Engine 5. It’s specifically related to the parallelization of physics calculations.

Based on the callsites, this variable is used in the Chaos namespace, particularly in the Parallel.cpp file. It’s part of the Experimental/Chaos module of Unreal Engine.

The value of this variable is set through a console variable (CVar) system, as evidenced by the FAutoConsoleVariableRef declaration. This allows the value to be changed at runtime through console commands or configuration files.

This variable interacts closely with other similar variables like bDisableParticleParallelFor and bDisableCollisionParallelFor. Together, these variables control different aspects of parallel execution in the Chaos physics system.

Developers should be aware that enabling this variable (setting it to true) will force physics calculations to run in a single thread, which can significantly impact performance, especially in scenes with complex physics interactions.

Best practices for using this variable include:

  1. Keeping it disabled (false) in most cases for better performance.
  2. Only enabling it for debugging purposes or when investigating specific physics-related issues.
  3. Being aware of its performance implications when enabled.

Regarding the associated variable bDisablePhysicsParallelFor:

This is the actual boolean variable that stores the state of the physics parallel execution setting. It’s directly manipulated by the console variable p.Chaos.DisablePhysicsParallelFor.

It’s used in various physics-related functions to determine whether to use parallel execution or not. For example, in the PhysicsParallelFor and PhysicsParallelForRange functions, it’s checked along with other conditions to decide whether to use single-threaded or multi-threaded execution.

The variable is defined differently in shipping builds (where it’s a constant false) versus non-shipping builds (where it’s a mutable boolean), allowing for runtime changes in development builds but ensuring optimal performance in shipping builds.

Developers should note that this variable is only modifiable in non-shipping builds, which allows for easier debugging and testing without affecting final game performance.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/Framework/Parallel.cpp:18

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	CHAOS_API bool bDisableCollisionParallelFor = false;

	FAutoConsoleVariableRef CVarDisablePhysicsParallelFor(TEXT("p.Chaos.DisablePhysicsParallelFor"), bDisablePhysicsParallelFor, TEXT("Disable parallel execution in Chaos Evolution"));
	FAutoConsoleVariableRef CVarDisableParticleParallelFor(TEXT("p.Chaos.DisableParticleParallelFor"), bDisableParticleParallelFor, TEXT("Disable parallel execution for Chaos Particles (Collisions, "));
	FAutoConsoleVariableRef CVarDisableCollisionParallelFor(TEXT("p.Chaos.DisableCollisionParallelFor"), bDisableCollisionParallelFor, TEXT("Disable parallel execution for Chaos Collisions (also disabled by DisableParticleParallelFor)"));
	FAutoConsoleVariableRef CVarInnerPhysicsBatchSize(TEXT("p.Chaos.InnerParallelForBatchSize"), InnerParallelForBatchSize, TEXT("Set the batch size threshold for inner parallel fors"));
	FAutoConsoleVariableRef CVarMinRangeBatchSize(TEXT("p.Chaos.MinRangeBatchSize"), MinRangeBatchSize, TEXT("Set the min range batch size for parallel for"));
	FAutoConsoleVariableRef CVarMaxRangeBatchWorkers(TEXT("p.Chaos.MaxNumWorkers"), MaxNumWorkers, TEXT("Set the max number of workers for physics"));
	FAutoConsoleVariableRef CVarSmallBatchSize(TEXT("p.Chaos.SmallBatchSize"), SmallBatchSize, TEXT("Small batch size for chaos parallel loops"));

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Programs/HeadlessChaos/Private/HeadlessChaosTestPerf.cpp:115

Scope (from outer to inner):

file
namespace    ChaosTest
function     GTEST_TEST

Source code excerpt:


		// let's make this serial
		//bDisablePhysicsParallelFor = true;
		//bDisableParticleParallelFor = true;
		//bDisableCollisionParallelFor = true;

		double MinTime = DBL_MAX;
		double MaxTime = DBL_MIN;
		double TotalTime = 0.;

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/Framework/Parallel.cpp:14

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	
#if !UE_BUILD_SHIPPING
	CHAOS_API bool bDisablePhysicsParallelFor = false;
	CHAOS_API bool bDisableParticleParallelFor = false;
	CHAOS_API bool bDisableCollisionParallelFor = false;

	FAutoConsoleVariableRef CVarDisablePhysicsParallelFor(TEXT("p.Chaos.DisablePhysicsParallelFor"), bDisablePhysicsParallelFor, TEXT("Disable parallel execution in Chaos Evolution"));
	FAutoConsoleVariableRef CVarDisableParticleParallelFor(TEXT("p.Chaos.DisableParticleParallelFor"), bDisableParticleParallelFor, TEXT("Disable parallel execution for Chaos Particles (Collisions, "));
	FAutoConsoleVariableRef CVarDisableCollisionParallelFor(TEXT("p.Chaos.DisableCollisionParallelFor"), bDisableCollisionParallelFor, TEXT("Disable parallel execution for Chaos Collisions (also disabled by DisableParticleParallelFor)"));
	FAutoConsoleVariableRef CVarInnerPhysicsBatchSize(TEXT("p.Chaos.InnerParallelForBatchSize"), InnerParallelForBatchSize, TEXT("Set the batch size threshold for inner parallel fors"));
	FAutoConsoleVariableRef CVarMinRangeBatchSize(TEXT("p.Chaos.MinRangeBatchSize"), MinRangeBatchSize, TEXT("Set the min range batch size for parallel for"));
	FAutoConsoleVariableRef CVarMaxRangeBatchWorkers(TEXT("p.Chaos.MaxNumWorkers"), MaxNumWorkers, TEXT("Set the max number of workers for physics"));
	FAutoConsoleVariableRef CVarSmallBatchSize(TEXT("p.Chaos.SmallBatchSize"), SmallBatchSize, TEXT("Small batch size for chaos parallel loops"));

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/Framework/Parallel.cpp:74

Scope (from outer to inner):

file
function     void Chaos::PhysicsParallelFor

Source code excerpt:

	};

	const bool bSingleThreaded = !!GSingleThreadedPhysics || bDisablePhysicsParallelFor || bForceSingleThreaded;
	const EParallelForFlags Flags = (bSingleThreaded ? EParallelForFlags::ForceSingleThread : EParallelForFlags::None);
	const int32 MinBatchSize = ((MaxNumWorkers > 0) && (InNum > MaxNumWorkers)) ? FMath::DivideAndRoundUp(InNum, MaxNumWorkers) : 1;

	ParallelFor(TEXT("PhysicsParallelFor"), InNum, MinBatchSize, PassThrough, Flags);
	//::ParallelFor(InNum, PassThrough, !!GSingleThreadedPhysics || bDisablePhysicsParallelFor || bForceSingleThreaded);
}

void Chaos::PhysicsParallelForRange(int32 InNum, TFunctionRef<void(int32, int32)> InCallable, const int32 InMinBatchSize, bool bForceSingleThreaded)
{
	TRACE_CPUPROFILER_EVENT_SCOPE(Chaos_PhysicsParallelFor);
	using namespace Chaos;

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/Framework/Parallel.cpp:145

Scope (from outer to inner):

file
function     void Chaos::PhysicsParallelForRange

Source code excerpt:

		InCallable(RangeIndex[ThreadId], RangeIndex[ThreadId + 1]);
	};
	::ParallelFor(RangeIndex.Num() - 1, PassThrough, !!GSingleThreadedPhysics || bDisablePhysicsParallelFor || bForceSingleThreaded);
}

void Chaos::PhysicsParallelForWithContext(int32 InNum, TFunctionRef<int32 (int32, int32)> InContextCreator, TFunctionRef<void(int32, int32)> InCallable, bool bForceSingleThreaded)
{
	TRACE_CPUPROFILER_EVENT_SCOPE(Chaos_PhysicsParallelFor);
	using namespace Chaos;

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/Framework/Parallel.cpp:171

Scope (from outer to inner):

file
function     void Chaos::PhysicsParallelForWithContext

Source code excerpt:

	};

	const bool bSingleThreaded = !!GSingleThreadedPhysics || bDisablePhysicsParallelFor || bForceSingleThreaded;
	const EParallelForFlags Flags = bSingleThreaded ? (EParallelForFlags::ForceSingleThread) : (EParallelForFlags::None);
	const int32 MinBatchSize = ((MaxNumWorkers > 0) && (InNum > MaxNumWorkers)) ? FMath::DivideAndRoundUp(InNum, MaxNumWorkers) : 1;

	// Unfortunately ParallelForWithTaskContext takes an array of context objects - we don't use it and in our case
	// it ends up being an array where array[index] = index.
	// The reason we don't need it is that our ContextCreator returns the context index we want to use on a given

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Public/Chaos/Framework/Parallel.h:18

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	CHAOS_API extern int32 LargeBatchSize;
#if UE_BUILD_SHIPPING
	const bool bDisablePhysicsParallelFor = false;
	const bool bDisableParticleParallelFor = false;
	const bool bDisableCollisionParallelFor = false;
#else
	CHAOS_API extern bool bDisablePhysicsParallelFor;
	CHAOS_API extern bool bDisableParticleParallelFor;
	CHAOS_API extern bool bDisableCollisionParallelFor;
#endif
}