r.Shaders.PropagateLocalWorkerOOMs

r.Shaders.PropagateLocalWorkerOOMs

#Overview

name: r.Shaders.PropagateLocalWorkerOOMs

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

• type: Var
• help: When set, out-of-memory conditions in a local shader compile worker will be treated as regular out-of-memory conditions and propagated to the main process.\nThis is useful when running in environment with hard memory limits, where it does not matter which process in particular caused us to violate the memory limit.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shaders.PropagateLocalWorkerOOMs is to control how out-of-memory (OOM) conditions are handled in local shader compile workers. This setting is related to the shader compilation system in Unreal Engine 5.

This setting variable is primarily used by the shader compilation subsystem within Unreal Engine. Based on the callsites, it’s implemented in the ShaderCompiler module, specifically in the ShaderCompiler.cpp file.

The value of this variable is set through a console variable (CVarShadersPropagateLocalWorkerOOMs) with a default value of false. It can be changed at runtime using console commands or through configuration files.

The associated variable CVarShadersPropagateLocalWorkerOOMs directly interacts with r.Shaders.PropagateLocalWorkerOOMs. They share the same value and purpose.

Developers must be aware that when this variable is set to true, out-of-memory conditions in local shader compile workers will be treated as regular out-of-memory conditions and propagated to the main process. This can be particularly useful in environments with hard memory limits, where it doesn’t matter which specific process caused the memory limit violation.

Best practices when using this variable include:

1. Carefully consider enabling this in production environments, as it may affect the stability of the main process.
2. Use this setting in conjunction with proper memory management and monitoring tools.
3. Test thoroughly in environments similar to the target deployment to understand the implications of enabling this setting.

Regarding the associated variable CVarShadersPropagateLocalWorkerOOMs:

• It’s an instance of TAutoConsoleVariable, which allows for runtime modification of the setting.
• It’s used in the HandleOutOfMemory function within the ShaderCompileWorkerError namespace to determine whether to propagate the OOM condition.
• When using this variable, developers should be aware that it’s accessed using the GetValueOnAnyThread() method, which suggests it can be safely read from any thread.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/ShaderCompiler/ShaderCompiler.cpp:2318

Scope: file

Source code excerpt:

static TAutoConsoleVariable<bool> CVarShadersPropagateLocalWorkerOOMs(
	TEXT("r.Shaders.PropagateLocalWorkerOOMs"),
	false,
	TEXT("When set, out-of-memory conditions in a local shader compile worker will be treated as regular out-of-memory conditions and propagated to the main process.\n")
	TEXT("This is useful when running in environment with hard memory limits, where it does not matter which process in particular caused us to violate the memory limit."),
	ECVF_Default);

#if ENABLE_COOK_STATS

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/ShaderCompiler/ShaderCompiler.cpp:2317

Scope: file

Source code excerpt:

	ECVF_ReadOnly);

static TAutoConsoleVariable<bool> CVarShadersPropagateLocalWorkerOOMs(
	TEXT("r.Shaders.PropagateLocalWorkerOOMs"),
	false,
	TEXT("When set, out-of-memory conditions in a local shader compile worker will be treated as regular out-of-memory conditions and propagated to the main process.\n")
	TEXT("This is useful when running in environment with hard memory limits, where it does not matter which process in particular caused us to violate the memory limit."),
	ECVF_Default);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/ShaderCompiler/ShaderCompiler.cpp:2481

Scope (from outer to inner):

file
namespace    ShaderCompileWorkerError
function     bool HandleOutOfMemory

Source code excerpt:

		else
		{
			if (CVarShadersPropagateLocalWorkerOOMs.GetValueOnAnyThread())
			{
				FPlatformMemory::OnOutOfMemory(0, 64);
			}
			ModalErrorOrLog(TEXT("ShaderCompileWorker failed"), ErrorReport);
			return false;
		}