r.ShaderPipelineCache.AutoSaveTimeBoundPSO

r.ShaderPipelineCache.AutoSaveTimeBoundPSO

#Overview

name: r.ShaderPipelineCache.AutoSaveTimeBoundPSO

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 r.ShaderPipelineCache.AutoSaveTimeBoundPSO is to control the automatic saving of logged Pipeline State Objects (PSOs) when the -logpso command line option is used. It is primarily related to the rendering system in Unreal Engine 5, specifically the shader pipeline caching mechanism.

This setting variable is utilized by the RenderCore module of Unreal Engine 5, particularly within the ShaderPipelineCache subsystem. The variable is defined and used in the ShaderPipelineCache.cpp file.

The value of this variable is set through a console variable (CVarPSOFileCacheAutoSaveTimeBoundPSO) using the TAutoConsoleVariable template. It is initialized with MAX_int32, which effectively disables the auto-save feature due to known issues.

The associated variable CVarPSOFileCacheAutoSaveTimeBoundPSO directly interacts with r.ShaderPipelineCache.AutoSaveTimeBoundPSO, as they share the same value and purpose.

Developers must be aware of several important aspects when using this variable:

  1. The auto-save feature is currently disabled by default due to a known issue (FORT-430086).
  2. The issue involves a broad lock taken during the Save function, which can lead to deadlocks on low-core CPUs.
  3. Enabling this feature may cause performance problems or hangs on systems with limited CPU resources.

Best practices when using this variable include:

  1. Keep the auto-save feature disabled (default setting) unless absolutely necessary.
  2. If enabling the feature, thoroughly test on various hardware configurations, especially those with limited CPU cores.
  3. Monitor performance and potential deadlocks when the feature is enabled.
  4. Consider alternative methods for saving PSOs if frequent saves are required.

Regarding the associated variable CVarPSOFileCacheAutoSaveTimeBoundPSO:

The purpose of CVarPSOFileCacheAutoSaveTimeBoundPSO is to provide a programmatic interface for controlling the auto-save time bound for PSOs. It is used internally by the ShaderPipelineCache system to determine when to trigger an auto-save of logged PSOs.

This variable is part of the RenderCore module and is specifically used in the FShaderPipelineCache::Tick function. It determines the interval at which bound PSOs are automatically saved.

The value of this variable is set through the console variable system and can be modified at runtime.

Developers should be aware that:

  1. Changing this value affects the frequency of auto-saves for bound PSOs.
  2. Lower values may increase I/O operations and potentially impact performance.
  3. The auto-save feature is disabled by default due to the aforementioned issues.

Best practices for using CVarPSOFileCacheAutoSaveTimeBoundPSO include:

  1. Leave the value at MAX_int32 unless there’s a specific need for frequent auto-saves.
  2. If enabling auto-saves, choose a reasonable interval that balances data safety with performance considerations.
  3. Monitor system performance when modifying this value, especially on lower-end hardware.
  4. Consider the potential impact on disk I/O and overall game performance when adjusting this setting.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/ShaderPipelineCache.cpp:115

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarPSOFileCacheAutoSaveTimeBoundPSO(
	TEXT("r.ShaderPipelineCache.AutoSaveTimeBoundPSO"),
	MAX_int32, // This effictively disables auto-save, since the feature is broken. See FORT-430086 for details, but in short, Save function takes a broad lock, and while holding it attempts to execute async tasks (reading from pak files). 
			   // These task may not be executed if all the worker threads are blocked trying to acquire the same lock that the saving thread is holding, which happens on a low-core CPUs.
	TEXT("Set the time where any logged PSO's will be saved when -logpso is on the command line."),
	ECVF_Default | ECVF_RenderThreadSafe
);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/ShaderPipelineCache.cpp:114

Scope: file

Source code excerpt:

																);

static TAutoConsoleVariable<int32> CVarPSOFileCacheAutoSaveTimeBoundPSO(
	TEXT("r.ShaderPipelineCache.AutoSaveTimeBoundPSO"),
	MAX_int32, // This effictively disables auto-save, since the feature is broken. See FORT-430086 for details, but in short, Save function takes a broad lock, and while holding it attempts to execute async tasks (reading from pak files). 
			   // These task may not be executed if all the worker threads are blocked trying to acquire the same lock that the saving thread is holding, which happens on a low-core CPUs.
	TEXT("Set the time where any logged PSO's will be saved when -logpso is on the command line."),
	ECVF_Default | ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/ShaderPipelineCache.cpp:1832

Scope (from outer to inner):

file
function     void FShaderPipelineCache::Tick

Source code excerpt:

			const double TimeSinceSave = FPlatformTime::Seconds() - LastAutoSaveTimeLogBoundPSO;

			if (TimeSinceSave >= CVarPSOFileCacheAutoSaveTimeBoundPSO.GetValueOnAnyThread())
			{
				SavePipelineFileCache(FPipelineFileCacheManager::SaveMode::BoundPSOsOnly);
				LastAutoSaveTimeLogBoundPSO = FPlatformTime::Seconds();
				LastAutoSaveNum = FPipelineFileCacheManager::NumPSOsLogged();
			}
		}