csv.BlockOnCaptureEnd

csv.BlockOnCaptureEnd

#Overview

name: csv.BlockOnCaptureEnd

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 csv.BlockOnCaptureEnd is to control the behavior of the game thread when a CSV capture is ended in Unreal Engine’s profiling and debugging system.

This setting variable is primarily used in the CSV Profiler subsystem, which is part of Unreal Engine’s core profiling and debugging tools. It’s specifically referenced in the CsvProfiler.cpp file, which is part of the Core module of the engine.

The value of this variable is set through the Unreal Engine console variable system. It’s defined as a TAutoConsoleVariable with a default value of 1.

The associated variable CVarCsvBlockOnCaptureEnd directly interacts with csv.BlockOnCaptureEnd. They share the same value and purpose.

Developers must be aware that this variable affects the performance and responsiveness of the game thread when CSV captures are ended. When set to 1 (default), it will cause the game thread to block until the CSV file is completely written. When set to 0, the game thread will not block, allowing for potentially smoother performance but with the risk of incomplete data capture.

Best practices when using this variable include:

  1. Keep it at the default value (1) during development and debugging to ensure complete data capture.
  2. Consider setting it to 0 in release builds or when performance is critical, but be aware of the potential for incomplete data.
  3. Use in conjunction with other CSV profiling tools and settings for comprehensive performance analysis.

Regarding the associated variable CVarCsvBlockOnCaptureEnd:

The purpose of CVarCsvBlockOnCaptureEnd is identical to csv.BlockOnCaptureEnd. It’s the actual console variable implementation that controls the blocking behavior of the game thread when CSV captures end.

This variable is used directly in the FCsvProfiler::EndFrame function to determine whether to block the game thread or not. When the value is 1, it suspends hang and hitch heartbeats and blocks the game thread while the CSV file is written.

The value of CVarCsvBlockOnCaptureEnd can be accessed at runtime using the GetValueOnGameThread() method.

Developers should be aware that changing this variable at runtime will immediately affect the behavior of CSV captures. They should also note that this variable interacts with other profiling systems like the hang and hitch detectors.

Best practices for CVarCsvBlockOnCaptureEnd are the same as for csv.BlockOnCaptureEnd, as they are essentially the same variable. Developers should consider the trade-off between complete data capture and game thread responsiveness when deciding how to set this variable.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Core/Private/ProfilingDebugging/CsvProfiler.cpp:81

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> CVarCsvBlockOnCaptureEnd(
	TEXT("csv.BlockOnCaptureEnd"), 
	1,
	TEXT("When 1, blocks the game thread until the CSV file has been written completely when the capture is ended.\r\n")
	TEXT("When 0, the game thread is not blocked whilst the file is written."),
	ECVF_Default
);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Core/Private/ProfilingDebugging/CsvProfiler.cpp:80

Scope: file

Source code excerpt:

const char * GIgnoreWaitStatName =  "[IGNORE]";

TAutoConsoleVariable<int32> CVarCsvBlockOnCaptureEnd(
	TEXT("csv.BlockOnCaptureEnd"), 
	1,
	TEXT("When 1, blocks the game thread until the CSV file has been written completely when the capture is ended.\r\n")
	TEXT("When 0, the game thread is not blocked whilst the file is written."),
	ECVF_Default
);

#Loc: <Workspace>/Engine/Source/Runtime/Core/Private/ProfilingDebugging/CsvProfiler.cpp:3213

Scope (from outer to inner):

file
function     void FCsvProfiler::EndFrame

Source code excerpt:

					bCaptureComplete = true;
				}
				else if (CVarCsvBlockOnCaptureEnd.GetValueOnGameThread() == 1)
				{
					// Suspend the hang and hitch heartbeats, as this is a long running task.
					FSlowHeartBeatScope SuspendHeartBeat;
					FDisableHitchDetectorScope SuspendGameThreadHitch;

					// Block the game thread here whilst the result file is written out.