r.ShaderPipelineCache.UserCacheUnusedElementCheckPeriod

r.ShaderPipelineCache.UserCacheUnusedElementCheckPeriod

#Overview

name: r.ShaderPipelineCache.UserCacheUnusedElementCheckPeriod

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

• type: Var
• help: The amount of time in days between running the garbage collection on unused PSOs in the user cache. Use a negative value to disable.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.ShaderPipelineCache.UserCacheUnusedElementCheckPeriod is to control the frequency of garbage collection for unused Pipeline State Objects (PSOs) in the user cache of the shader pipeline system. This setting is part of Unreal Engine’s rendering system, specifically the shader pipeline caching mechanism.

This setting variable is primarily used in the Runtime Hardware Interface (RHI) module of Unreal Engine, as evidenced by its location in the PipelineFileCache.cpp file within the RHI source directory.

The value of this variable is set through the console variable system (CVar) in Unreal Engine. It’s defined as a TAutoConsoleVariable, which means it can be changed at runtime through console commands or configuration files.

The associated variable CVarPSOFileCacheUserCacheUnusedElementCheckPeriod directly interacts with this setting. They share the same value and purpose.

Developers must be aware that:

1. The value represents the number of days between garbage collection runs.
2. A negative value disables the garbage collection process entirely.
3. This setting affects performance and storage usage, as it determines how frequently unused PSOs are removed from the user cache.

Best practices when using this variable include:

1. Set an appropriate value based on the project’s needs. Too frequent garbage collection may impact performance, while too infrequent may lead to unnecessary storage usage.
2. Monitor the size of the user cache and adjust this setting if it grows too large over time.
3. Consider disabling (setting to a negative value) during development if rapid iteration on shaders is necessary, but ensure it’s properly set for release builds.

Regarding the associated variable CVarPSOFileCacheUserCacheUnusedElementCheckPeriod:

• Its purpose is identical to r.ShaderPipelineCache.UserCacheUnusedElementCheckPeriod.
• It’s used directly in the GarbageCollectUserCache function to determine whether and how often to perform garbage collection.
• The value is retrieved using GetValueOnAnyThread(), indicating it can be safely accessed from any thread.
• If the value is negative, the garbage collection process is skipped entirely.

Developers should treat CVarPSOFileCacheUserCacheUnusedElementCheckPeriod as the internal representation of the r.ShaderPipelineCache.UserCacheUnusedElementCheckPeriod setting, and modify the setting through the console variable system rather than directly manipulating this variable.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RHI/Private/PipelineFileCache.cpp:147

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarPSOFileCacheUserCacheUnusedElementCheckPeriod(
                                                            TEXT("r.ShaderPipelineCache.UserCacheUnusedElementCheckPeriod"),
															-1,
                                                            TEXT("The amount of time in days between running the garbage collection on unused PSOs in the user cache. Use a negative value to disable."),
                                                            ECVF_Default
                                                            );

static TAutoConsoleVariable<int32> CVarLazyLoadShadersWhenPSOCacheIsPresent(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RHI/Private/PipelineFileCache.cpp:146

Scope: file

Source code excerpt:

                                                            );

static TAutoConsoleVariable<int32> CVarPSOFileCacheUserCacheUnusedElementCheckPeriod(
                                                            TEXT("r.ShaderPipelineCache.UserCacheUnusedElementCheckPeriod"),
															-1,
                                                            TEXT("The amount of time in days between running the garbage collection on unused PSOs in the user cache. Use a negative value to disable."),
                                                            ECVF_Default
                                                            );

#Loc: <Workspace>/Engine/Source/Runtime/RHI/Private/PipelineFileCache.cpp:1959

Scope (from outer to inner):

file
function     void GarbageCollectUserCache

Source code excerpt:

		ON_SCOPE_EXIT{ UE_LOG(LogRHI, Log, TEXT("FPipelineCacheFile: GarbageCollectUserCache() End")); };

		int32 GCPeriodInDays = CVarPSOFileCacheUserCacheUnusedElementCheckPeriod.GetValueOnAnyThread();
		if (GCPeriodInDays < 0)
		{
			UE_LOG(LogRHI, Log, TEXT("User cache GC is disabled"));
			return;
		}