r.pso.evictiontime

r.pso.evictiontime

#Overview

name: r.pso.evictiontime

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.pso.evictiontime is to control the time interval between checks for removing stale objects from the Pipeline State Object (PSO) cache in Unreal Engine’s rendering system.

This setting variable is primarily used by the rendering subsystem, specifically the Pipeline State Cache module within the RHI (Rendering Hardware Interface) system. Based on the callsites, it’s evident that this variable is crucial for managing memory usage and performance optimization in the rendering pipeline.

The value of this variable is set through a console variable (CVarPSOEvictionTime) with a default value of 60 seconds. It can be modified at runtime through console commands or configuration files.

The associated variable CVarPSOEvictionTime directly interacts with r.pso.evictiontime. They share the same value and purpose, with CVarPSOEvictionTime being the actual TAutoConsoleVariable that stores and manages the setting.

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

  1. Setting it to 0 disables eviction, which may lead to out-of-memory (OOM) issues over time.
  2. The eviction check is performed in the RHICommandList::BeginFrame, affecting frame processing.
  3. The actual eviction occurs at half the specified time due to the two-cycle nature of the eviction process (main -> backfill -> gone).

Best practices when using this variable include:

  1. Carefully tuning the value based on the game’s memory usage patterns and available resources.
  2. Monitoring memory usage and performance to find the optimal balance between cache retention and memory consumption.
  3. Consider adjusting this value dynamically based on the game’s state or platform limitations.

Regarding the associated variable CVarPSOEvictionTime:

Its purpose is identical to r.pso.evictiontime, serving as the actual implementation of the console variable in the engine’s code.

It is used directly in the PipelineStateCache::FlushResources() function to determine when to perform the eviction check.

The value is set through the TAutoConsoleVariable constructor and can be accessed using the GetValueOnAnyThread() method.

Developers should be aware that this variable is marked as read-only and render thread safe, meaning it shouldn’t be modified frequently during runtime.

Best practices for CVarPSOEvictionTime include using it for reading the current eviction time value in code that interacts with the PSO cache system, and ensuring that any modifications to this value are done safely and with consideration for potential impacts on rendering performance and memory usage.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RHI/Private/PipelineStateCache.cpp:143

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarPSOEvictionTime(
	TEXT("r.pso.evictiontime"),
	60,
	TEXT("Time between checks to remove stale objects from the cache. 0 = no eviction (which may eventually OOM...)"),
	ECVF_ReadOnly | ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarPSORuntimeCreationHitchThreshold(

#Loc: <Workspace>/Engine/Source/Runtime/RHI/Public/PipelineStateCache.h:130

Scope (from outer to inner):

file
namespace    PipelineStateCache

Source code excerpt:

	extern RHI_API FRayTracingPipelineState* GetRayTracingPipelineState(const FRayTracingPipelineStateSignature& Signature);

	/* Evicts unused state entries based on r.pso.evictiontime time. Called in RHICommandList::BeginFrame */
	extern RHI_API void FlushResources();

	extern RHI_API void ReportFrameHitchToCSV();

	/* Clears all pipeline cached state. Called on shutdown, calling GetAndOrCreate after this will recreate state */
	extern RHI_API void Shutdown();

#Loc: <Workspace>/Engine/Source/Runtime/RHI/Public/RHICommandList.inl:57

Scope (from outer to inner):

file
namespace    PipelineStateCache

Source code excerpt:

namespace PipelineStateCache
{
	/* Evicts unused state entries based on r.pso.evictiontime time. Called in RHICommandList::BeginFrame */
	extern RHI_API void FlushResources();
}

inline void FRHIComputeCommandList::SubmitCommandsHint()
{
	if (IsImmediate())

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RHI/Private/PipelineStateCache.cpp:142

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarPSOEvictionTime(
	TEXT("r.pso.evictiontime"),
	60,
	TEXT("Time between checks to remove stale objects from the cache. 0 = no eviction (which may eventually OOM...)"),
	ECVF_ReadOnly | ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/RHI/Private/PipelineStateCache.cpp:2190

Scope (from outer to inner):

file
function     void PipelineStateCache::FlushResources

Source code excerpt:

	// because it takes two cycles for an object to move from main->backfill->gone we check
	// at half the desired eviction time
	int32 EvictionPeriod = CVarPSOEvictionTime.GetValueOnAnyThread();

	if (EvictionPeriod == 0 || CurrentTime - LastEvictionTime < EvictionPeriod)
	{
		return;
	}