r.XGEController.AvoidUsingLocalMachine

r.XGEController.AvoidUsingLocalMachine

#Overview

name: r.XGEController.AvoidUsingLocalMachine

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.XGEController.AvoidUsingLocalMachine is to control whether XGE (Xoreax Grid Engine) tasks should avoid running on the local machine to reduce oversubscription with local async and out-of-process work. This setting is part of the XGEController plugin in Unreal Engine 5, which is responsible for managing distributed compilation tasks.

This setting variable is primarily used by the XGEController plugin, which is part of Unreal Engine’s build system and compilation infrastructure. It affects how tasks are distributed across machines when using XGE for distributed compilation.

The value of this variable is set through the FAutoConsoleVariableRef system, which allows it to be changed at runtime. It is initialized with a default value of 1.

The associated variable AvoidUsingLocalMachine interacts directly with r.XGEController.AvoidUsingLocalMachine. It’s an int32 variable that shares the same value and is used within the XGEController namespace to determine the behavior of task distribution.

Developers must be aware that this variable has three possible values: 0: Do not avoid using the local machine. This can cause oversubscription on the initiator machine. 1: Avoid spawning tasks on the local machine except when running a commandlet or when -buildmachine is passed (default). 2: Always avoid spawning tasks on the local machine.

Best practices when using this variable include:

  1. Consider the available resources on the local machine and the network when deciding which setting to use.
  2. Use the default setting (1) for most scenarios, as it provides a balance between local and distributed compilation.
  3. Monitor performance and adjust the setting if you notice oversubscription issues on the local machine.
  4. Be cautious when setting it to 0, as it may impact local machine performance during compilation.

Regarding the associated variable AvoidUsingLocalMachine:

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Plugins/XGEController/Source/Private/XGEControllerModule.cpp:65

Scope (from outer to inner):

file
namespace    XGEControllerVariables

Source code excerpt:

	int32 AvoidUsingLocalMachine = 1;
	FAutoConsoleVariableRef CVarXGEControllerAvoidUsingLocalMachine(
		TEXT("r.XGEController.AvoidUsingLocalMachine"),
		AvoidUsingLocalMachine,
		TEXT("Whether XGE tasks should avoid running on the local machine (to reduce the oversubscription with local async and out-of-process work).\n")
		TEXT("0: Do not avoid. Distributed tasks will be spawned on all available XGE agents. Can cause oversubscription on the initiator machine. \n")
		TEXT("1: Avoid spawning tasks on the local (initiator) machine except when running a commandlet or -buildmachine is passed (default).\n")
		TEXT("2: Avoid spawning tasks on the local (initiator) machine."),
		ECVF_Default); // This can be flipped any time XGEControlWorker is restarted

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Plugins/XGEController/Source/Private/XGEControllerModule.cpp:63

Scope (from outer to inner):

file
namespace    XGEControllerVariables

Source code excerpt:

		ECVF_Default);

	int32 AvoidUsingLocalMachine = 1;
	FAutoConsoleVariableRef CVarXGEControllerAvoidUsingLocalMachine(
		TEXT("r.XGEController.AvoidUsingLocalMachine"),
		AvoidUsingLocalMachine,
		TEXT("Whether XGE tasks should avoid running on the local machine (to reduce the oversubscription with local async and out-of-process work).\n")
		TEXT("0: Do not avoid. Distributed tasks will be spawned on all available XGE agents. Can cause oversubscription on the initiator machine. \n")
		TEXT("1: Avoid spawning tasks on the local (initiator) machine except when running a commandlet or -buildmachine is passed (default).\n")
		TEXT("2: Avoid spawning tasks on the local (initiator) machine."),
		ECVF_Default); // This can be flipped any time XGEControlWorker is restarted

#Loc: <Workspace>/Engine/Plugins/XGEController/Source/Private/XGEControllerModule.cpp:78

Scope (from outer to inner):

file
namespace    XGEController
function     bool AvoidUsingLocalMachine

Source code excerpt:

{
	/** Whether XGE tasks should avoid using the local machine to reduce oversubscription */
	bool AvoidUsingLocalMachine()
	{
		switch (XGEControllerVariables::AvoidUsingLocalMachine)
		{
			case 0:
				return false;
			case 2:
				return true;
			default:

#Loc: <Workspace>/Engine/Plugins/XGEController/Source/Private/XGEControllerModule.cpp:354

Scope (from outer to inner):

file
function     void FXGEControllerModule::InitializeController

Source code excerpt:


			UE_LOG(LogXGEController, Display, TEXT("Initialized XGE controller. XGE tasks will %sbe spawned on this machine."),
				XGEController::AvoidUsingLocalMachine() ? TEXT("not ") : TEXT("")
				);

		}
	}
}

#Loc: <Workspace>/Engine/Plugins/XGEController/Source/Private/XGEControllerModule.cpp:383

Scope (from outer to inner):

file
function     void FXGEControllerModule::WriteOutThreadProc

Source code excerpt:

		FString XGConsoleArgs = FString::Printf(TEXT("/VIRTUALIZEDIRECTX /allowremote=\"%s\" %s /allowintercept=\"%s\" /title=\"Unreal Engine XGE Tasks\" /monitordirs=\"%s\" /command=\"%s -xgecontroller %s\""),
			XGE_INTERCEPT_EXE_NAMES,
			(XGEController::AvoidUsingLocalMachine() && (IsRunningCommandlet() || !GShaderCompilingManager->IgnoreAllThrottling())) ? TEXT("/avoidlocal=ON") : TEXT(""),
			XGE_CONTROL_WORKER_NAME,
			*WorkingDirectory,
			XGE_CONTROL_WORKER_FILENAME,
			*PipeName);

		// Create the output pipe as a server...