ImageWriteQueue.MaxConcurrency

ImageWriteQueue.MaxConcurrency

#Overview

name: ImageWriteQueue.MaxConcurrency

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of ImageWriteQueue.MaxConcurrency is to control the maximum number of asynchronous image write operations that can occur simultaneously in Unreal Engine 5. This setting is primarily used by the image writing subsystem, which is part of the engine’s file I/O and asset handling capabilities.

The ImageWriteQueue module relies on this setting variable. It is used to manage the concurrency of image write operations, which is crucial for optimizing performance and resource usage when dealing with image file operations.

The value of this variable is set through a console variable (CVar) named CVarImageWriteQueueMaxConcurrency. It can be configured at runtime or through configuration files. By default, it is set to -1, which means it will use the number of available CPU cores as the maximum concurrency value.

This variable interacts with the engine’s thread pool system. When the ImageWriteQueue.MaxConcurrency is set to -1 (default), it uses FPlatformMisc::NumberOfCores() to determine the number of threads to use. If set to a specific value, it will use that number instead.

Developers must be aware that setting this value too high might lead to excessive resource consumption, while setting it too low could result in suboptimal performance for image writing operations. It’s important to find the right balance based on the target hardware and the specific needs of the project.

Best practices when using this variable include:

  1. Leave it at the default value (-1) unless there’s a specific reason to change it.
  2. If changing, consider the target hardware specifications and the frequency of image write operations in your project.
  3. Monitor performance and adjust as necessary, especially on different hardware configurations.
  4. Be cautious when increasing this value, as it might lead to increased memory usage and potential system instability if set too high.

Regarding the associated variable CVarImageWriteQueueMaxConcurrency:

This is the actual console variable that controls the ImageWriteQueue.MaxConcurrency setting. It is defined using the TAutoConsoleVariable template, which allows for runtime configuration of engine behavior.

The purpose of CVarImageWriteQueueMaxConcurrency is to provide a configurable interface for the ImageWriteQueue.MaxConcurrency setting. It allows developers and users to adjust the concurrency setting without recompiling the engine.

This variable is used directly in the FImageWriteQueue::RecreateThreadPool() function to determine the number of threads to use in the image write thread pool.

Developers should be aware that changes to this CVar will take effect when the thread pool is recreated, which happens when the configured value changes or when the engine determines it needs to adjust the thread pool size.

Best practices for using CVarImageWriteQueueMaxConcurrency include:

  1. Use console commands or configuration files to adjust this value for testing or specific deployment scenarios.
  2. Document any non-default values used in a project to ensure consistency across development and deployment environments.
  3. Consider exposing this setting in user-facing graphics options if your application has varying image writing workloads that might benefit from user adjustment.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/ImageWriteQueue/Private/ImageWriteQueue.cpp:15

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarImageWriteQueueMaxConcurrency(
	TEXT("ImageWriteQueue.MaxConcurrency"),
	-1,
	TEXT("The maximum number of async image writes allowable at any given time.")
	TEXT("Default is to use the number of cores available."),
	ECVF_Default);

static TAutoConsoleVariable<int32> CVarImageWriteQueueMaxQueueSize(

#Loc: <Workspace>/Engine/Source/Runtime/ImageWriteQueue/Public/ImageWriteQueue.h:19

Scope: file

Source code excerpt:

 * Public interface for an asynchronous queue of work dedicated to writing images to disk
 *
 * Concurrency metrics are controllable by ImageWriteQueue.MaxConcurrency and ImageWriteQueue.MaxQueueSize
 * Dispatched tasks can contain callbacks that are called on the main thread when completed.
 * It is possible to wait on completion of the current queue state by creating a 'fence' that can be waited upon
 */
class IImageWriteQueue
{
public:

	virtual ~IImageWriteQueue(){}

	/**
	 * (thread-safe) Enqueue a new asynchronous image write task.
	 *

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/ImageWriteQueue/Private/ImageWriteQueue.cpp:14

Scope: file

Source code excerpt:

DEFINE_LOG_CATEGORY(LogImageWriteQueue);

static TAutoConsoleVariable<int32> CVarImageWriteQueueMaxConcurrency(
	TEXT("ImageWriteQueue.MaxConcurrency"),
	-1,
	TEXT("The maximum number of async image writes allowable at any given time.")
	TEXT("Default is to use the number of cores available."),
	ECVF_Default);

#Loc: <Workspace>/Engine/Source/Runtime/ImageWriteQueue/Private/ImageWriteQueue.cpp:256

Scope (from outer to inner):

file
function     void FImageWriteQueue::RecreateThreadPool

Source code excerpt:

	const int32 MaxConcurrency = GIOThreadPool->GetNumThreads();
#else
	const int32 ConfiguredMaxConcurrency = CVarImageWriteQueueMaxConcurrency.GetValueOnAnyThread();
	const int32 MaxConcurrency = ConfiguredMaxConcurrency == -1 ? FPlatformMisc::NumberOfCores() : ConfiguredMaxConcurrency;
#endif

	if (ThreadPool && MaxConcurrency != ThreadPool->GetNumThreads())
	{
		CreateFence().Wait();