RunAsyncTraceOnWorkerThread
RunAsyncTraceOnWorkerThread
#Overview
name: RunAsyncTraceOnWorkerThread
This variable is created as a Console Variable (cvar).
- type:
Var - help:
Whether to use worker thread for async trace functionality. This works if FApp::ShouldUseThreadingForPerformance is true. Otherwise it will always use game thread. \n0: Use game thread, 1: User worker thread
It is referenced in 4 C++ source files.
#Summary
#Usage in the C++ source code
The purpose of RunAsyncTraceOnWorkerThread is to control whether asynchronous trace functionality in Unreal Engine 5 runs on a worker thread or the game thread. This setting is primarily used for collision detection and physics calculations.
-
This setting variable is part of the collision system in Unreal Engine 5, specifically for asynchronous trace operations.
-
The Unreal Engine subsystem that relies on this setting variable is the collision system, which is part of the Engine module, as evident from the file path “Engine/Source/Runtime/Engine/Private/Collision/WorldCollisionAsync.cpp”.
-
The value of this variable is set to 1 by default, as shown in the code:
static int32 RunAsyncTraceOnWorkerThread = 1;. It can be modified at runtime through the console variable system. -
This variable interacts with the
FApp::ShouldUseThreadingForPerformance()function and theFForkProcessHelper::IsForkedMultithreadInstance()function to determine if async traces should run on worker threads. -
Developers must be aware that this setting only takes effect if
FApp::ShouldUseThreadingForPerformance()returns true or if the process is a forked multithreaded instance. If neither of these conditions is met, async traces will always run on the game thread regardless of this setting. -
Best practices when using this variable include:
- Consider the performance implications of running async traces on worker threads vs. the game thread.
- Test the game’s performance with both settings (0 and 1) to determine which works best for your specific use case.
- Be aware of potential threading issues when running async traces on worker threads.
Regarding the associated variable CVarRunAsyncTraceOnWorkerThread:
- This is a console variable that exposes RunAsyncTraceOnWorkerThread to the engine’s console system.
- It allows runtime modification of the RunAsyncTraceOnWorkerThread value.
- The description provided in the code explains its functionality and possible values: “Whether to use worker thread for async trace functionality. This works if FApp::ShouldUseThreadingForPerformance is true. Otherwise it will always use game thread. 0: Use game thread, 1: Use worker thread”
- Developers can use this console variable to toggle between using the game thread and worker threads for async traces during runtime, which can be useful for performance testing and debugging.
#References in C++ code
#Callsites
This variable is referenced in the following C++ source code:
#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Collision/WorldCollisionAsync.cpp:33
Scope (from outer to inner):
file
namespace AsyncTraceCVars
Source code excerpt:
namespace AsyncTraceCVars
{
static int32 RunAsyncTraceOnWorkerThread = 1;
static FAutoConsoleVariableRef CVarRunAsyncTraceOnWorkerThread(
TEXT("RunAsyncTraceOnWorkerThread"),
RunAsyncTraceOnWorkerThread,
TEXT("Whether to use worker thread for async trace functionality. This works if FApp::ShouldUseThreadingForPerformance is true. Otherwise it will always use game thread. \n")
TEXT("0: Use game thread, 1: User worker thread"),
ECVF_Default);
bool IsAsyncTraceOnWorkerThreads()
{
return RunAsyncTraceOnWorkerThread != 0 && (FApp::ShouldUseThreadingForPerformance() || FForkProcessHelper::IsForkedMultithreadInstance());
}
}
#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Collision/WorldCollisionAsync.cpp:31
Scope (from outer to inner):
file
namespace AsyncTraceCVars
Source code excerpt:
* @param UserData UserData
*/
namespace AsyncTraceCVars
{
static int32 RunAsyncTraceOnWorkerThread = 1;
static FAutoConsoleVariableRef CVarRunAsyncTraceOnWorkerThread(
TEXT("RunAsyncTraceOnWorkerThread"),
RunAsyncTraceOnWorkerThread,
TEXT("Whether to use worker thread for async trace functionality. This works if FApp::ShouldUseThreadingForPerformance is true. Otherwise it will always use game thread. \n")
TEXT("0: Use game thread, 1: User worker thread"),
ECVF_Default);
bool IsAsyncTraceOnWorkerThreads()
{
return RunAsyncTraceOnWorkerThread != 0 && (FApp::ShouldUseThreadingForPerformance() || FForkProcessHelper::IsForkedMultithreadInstance());
}
}
namespace
{
// Helper functions to return the right named member container based on a datum type
template <typename DatumType> FORCEINLINE TArray<TUniquePtr<TTraceThreadData<DatumType >>>& GetTraceContainer (AsyncTraceData& DataBuffer);
template <> FORCEINLINE TArray<TUniquePtr<TTraceThreadData<FTraceDatum >>>& GetTraceContainer<FTraceDatum> (AsyncTraceData& DataBuffer) { return DataBuffer.TraceData; }
template <> FORCEINLINE TArray<TUniquePtr<TTraceThreadData<FOverlapDatum>>>& GetTraceContainer<FOverlapDatum>(AsyncTraceData& DataBuffer) { return DataBuffer.OverlapData; }
// Helper functions to return the right named member trace index based on a datum type
#Associated Variable and Callsites
This variable is associated with another variable named RunAsyncTraceOnWorkerThread. They share the same value. See the following C++ source code.
#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Collision/WorldCollisionAsync.cpp:33
Scope (from outer to inner):
file
namespace AsyncTraceCVars
Source code excerpt:
namespace AsyncTraceCVars
{
static int32 RunAsyncTraceOnWorkerThread = 1;
static FAutoConsoleVariableRef CVarRunAsyncTraceOnWorkerThread(
TEXT("RunAsyncTraceOnWorkerThread"),
RunAsyncTraceOnWorkerThread,
TEXT("Whether to use worker thread for async trace functionality. This works if FApp::ShouldUseThreadingForPerformance is true. Otherwise it will always use game thread. \n")
TEXT("0: Use game thread, 1: User worker thread"),
ECVF_Default);
bool IsAsyncTraceOnWorkerThreads()
{
return RunAsyncTraceOnWorkerThread != 0 && (FApp::ShouldUseThreadingForPerformance() || FForkProcessHelper::IsForkedMultithreadInstance());
}
}
#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Collision/WorldCollisionAsync.cpp:31
Scope (from outer to inner):
file
namespace AsyncTraceCVars
Source code excerpt:
* @param UserData UserData
*/
namespace AsyncTraceCVars
{
static int32 RunAsyncTraceOnWorkerThread = 1;
static FAutoConsoleVariableRef CVarRunAsyncTraceOnWorkerThread(
TEXT("RunAsyncTraceOnWorkerThread"),
RunAsyncTraceOnWorkerThread,
TEXT("Whether to use worker thread for async trace functionality. This works if FApp::ShouldUseThreadingForPerformance is true. Otherwise it will always use game thread. \n")
TEXT("0: Use game thread, 1: User worker thread"),
ECVF_Default);
bool IsAsyncTraceOnWorkerThreads()
{
return RunAsyncTraceOnWorkerThread != 0 && (FApp::ShouldUseThreadingForPerformance() || FForkProcessHelper::IsForkedMultithreadInstance());
}
}
namespace
{
// Helper functions to return the right named member container based on a datum type
template <typename DatumType> FORCEINLINE TArray<TUniquePtr<TTraceThreadData<DatumType >>>& GetTraceContainer (AsyncTraceData& DataBuffer);
template <> FORCEINLINE TArray<TUniquePtr<TTraceThreadData<FTraceDatum >>>& GetTraceContainer<FTraceDatum> (AsyncTraceData& DataBuffer) { return DataBuffer.TraceData; }
template <> FORCEINLINE TArray<TUniquePtr<TTraceThreadData<FOverlapDatum>>>& GetTraceContainer<FOverlapDatum>(AsyncTraceData& DataBuffer) { return DataBuffer.OverlapData; }
// Helper functions to return the right named member trace index based on a datum type