LogGameThreadMallocChurn.SampleFrequency

LogGameThreadMallocChurn.SampleFrequency

#Overview

name: LogGameThreadMallocChurn.SampleFrequency

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

• type: Var
• help: Number of allocs to skip between samples. This is used to prevent churn sampling from slowing the game down too much.

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of LogGameThreadMallocChurn.SampleFrequency is to control the frequency of memory allocation sampling for monitoring memory churn on the game thread in Unreal Engine 5.

This setting variable is primarily used in the engine’s performance monitoring and debugging system, specifically for tracking memory allocations and deallocations (churn) on the game thread. It’s part of Unreal Engine’s core runtime system, implemented in the Launch module.

The value of this variable is set through a console variable (CVar) system, which allows it to be changed at runtime. It’s defined using TAutoConsoleVariable, meaning it can be modified through console commands or configuration files.

LogGameThreadMallocChurn.SampleFrequency interacts closely with other related variables like CVarLogGameThreadMallocChurn and CVarLogGameThreadMallocChurn_PrintFrequency. These variables work together to control the sampling, thresholding, and reporting of memory churn.

Developers should be aware that this variable directly impacts the performance overhead of the memory churn tracking system. A lower value will result in more frequent sampling, potentially providing more accurate data but at the cost of increased performance impact.

Best practices when using this variable include:

1. Setting it to a value that balances the need for accurate data with acceptable performance impact.
2. Adjusting it in conjunction with other related variables for optimal memory churn tracking.
3. Using it primarily in development and debugging scenarios, not in shipping builds.

The associated variable CVarLogGameThreadMallocChurn_SampleFrequency is the actual CVar object that holds and manages the value of LogGameThreadMallocChurn.SampleFrequency. It’s initialized with a default value of 100, meaning it will sample every 100th allocation by default.

This CVar is used in the FScopedSampleMallocChurn class, which is responsible for the actual sampling process. The value is retrieved at the beginning of each sampling period and used to set the countdown for the next sample.

When working with CVarLogGameThreadMallocChurn_SampleFrequency, developers should:

1. Understand that changing this value will directly affect the granularity of memory churn tracking.
2. Be cautious about setting very low values in performance-critical scenarios.
3. Consider using it in conjunction with other memory profiling tools for a comprehensive view of memory usage patterns.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Launch/Private/LaunchEngineLoop.cpp:5407

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarLogGameThreadMallocChurn_SampleFrequency(
	TEXT("LogGameThreadMallocChurn.SampleFrequency"),
	100,
	TEXT("Number of allocs to skip between samples. This is used to prevent churn sampling from slowing the game down too much."));

static TAutoConsoleVariable<int32> CVarLogGameThreadMallocChurn_StackIgnore(
	TEXT("LogGameThreadMallocChurn.StackIgnore"),
	2,

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Launch/Private/LaunchEngineLoop.cpp:5406

Scope: file

Source code excerpt:

	TEXT("Minimum average number of allocs per frame to include in the report."));

static TAutoConsoleVariable<int32> CVarLogGameThreadMallocChurn_SampleFrequency(
	TEXT("LogGameThreadMallocChurn.SampleFrequency"),
	100,
	TEXT("Number of allocs to skip between samples. This is used to prevent churn sampling from slowing the game down too much."));

static TAutoConsoleVariable<int32> CVarLogGameThreadMallocChurn_StackIgnore(
	TEXT("LogGameThreadMallocChurn.StackIgnore"),

#Loc: <Workspace>/Engine/Source/Runtime/Launch/Private/LaunchEngineLoop.cpp:5440

Scope (from outer to inner):

file
function     FScopedSampleMallocChurn

Source code excerpt:

	FScopedSampleMallocChurn()
		: bEnabled(CVarLogGameThreadMallocChurn.GetValueOnGameThread() > 0)
		, CountDown(CVarLogGameThreadMallocChurn_SampleFrequency.GetValueOnGameThread())
		, Hook(
		[this](int32 Index)
	{
		if (--CountDown <= 0)
		{
			CountDown = CVarLogGameThreadMallocChurn_SampleFrequency.GetValueOnGameThread();
			CollectSample();
		}
	}
	)
	{
		if (bEnabled)

#Loc: <Workspace>/Engine/Source/Runtime/Launch/Private/LaunchEngineLoop.cpp:5500

Scope (from outer to inner):

file
function     void PrintResultsAndReset

Source code excerpt:

		DumpFrame = GFrameCounter + CVarLogGameThreadMallocChurn_PrintFrequency.GetValueOnGameThread();
		FOutputDeviceRedirector* Log = FOutputDeviceRedirector::Get();
		float SampleAndFrameCorrection = float(CVarLogGameThreadMallocChurn_SampleFrequency.GetValueOnGameThread()) / float(CVarLogGameThreadMallocChurn_PrintFrequency.GetValueOnGameThread());
		GGameThreadMallocChurnTracker.DumpStackTraces(CVarLogGameThreadMallocChurn_Threshhold.GetValueOnGameThread(), *Log, SampleAndFrameCorrection);
		GGameThreadMallocChurnTracker.ResetTracking();
	}
};
FStackTracker FScopedSampleMallocChurn::GGameThreadMallocChurnTracker;
uint64 FScopedSampleMallocChurn::DumpFrame = 0;