ImageWriteQueue.MaxQueueSize

ImageWriteQueue.MaxQueueSize

#Overview

name: ImageWriteQueue.MaxQueueSize

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

• type: Var
• help: The maximum number of queued image write tasks allowable before the queue will block when adding more.Default is to use 4 times the number of cores available or 16 when multithreading is disabled on the command line.

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of ImageWriteQueue.MaxQueueSize is to control the maximum number of queued image write tasks allowed in the image write queue before it starts blocking when adding more tasks.

This setting variable is primarily used by the ImageWriteQueue subsystem, which is part of Unreal Engine’s image processing and I/O operations. It’s specifically designed for managing asynchronous image writing tasks to disk.

The value of this variable is set through a console variable (CVar) named CVarImageWriteQueueMaxQueueSize. It’s initialized with a default value of -1, which means it will use a dynamic value based on the system’s capabilities.

The associated variable CVarImageWriteQueueMaxQueueSize interacts directly with ImageWriteQueue.MaxQueueSize. They share the same value, and changes to the CVar will affect the behavior of the image write queue.

Developers should be aware that:

1. The default behavior (-1) sets the queue size to 4 times the number of available CPU cores, or 16 if multithreading is disabled.
2. Setting this value too low might cause frequent blocking when adding new tasks, while setting it too high might consume excessive memory.

Best practices when using this variable include:

1. Monitor performance and adjust the value based on your specific use case and hardware capabilities.
2. Consider the trade-off between memory usage and task queueing efficiency.
3. Use in conjunction with ImageWriteQueue.MaxConcurrency for fine-tuning the image write queue performance.

Regarding the associated variable CVarImageWriteQueueMaxQueueSize:

• It’s a console variable that directly controls ImageWriteQueue.MaxQueueSize.
• It’s defined using TAutoConsoleVariable, allowing runtime modification.
• The value is retrieved using GetValueOnAnyThread(), indicating it’s designed for multi-threaded access.
• Changes to this CVar trigger the OnCVarsChanged function, which updates the MaxQueueSize and potentially recreates the thread pool.

When working with CVarImageWriteQueueMaxQueueSize, developers should:

1. Use console commands or configuration files to adjust the value at runtime or startup.
2. Be aware that changes will trigger a reconfiguration of the image write queue system.
3. Consider the impact on both performance and resource usage when modifying this value.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarImageWriteQueueMaxQueueSize(
	TEXT("ImageWriteQueue.MaxQueueSize"),
	-1,
	TEXT("The maximum number of queued image write tasks allowable before the queue will block when adding more.")
	TEXT("Default is to use 4 times the number of cores available or 16 when multithreading is disabled on the command line."),
	ECVF_Default);

/**

#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 CVarImageWriteQueueMaxQueueSize. They share the same value. See the following C++ source code.

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

Scope: file

Source code excerpt:

	ECVF_Default);

static TAutoConsoleVariable<int32> CVarImageWriteQueueMaxQueueSize(
	TEXT("ImageWriteQueue.MaxQueueSize"),
	-1,
	TEXT("The maximum number of queued image write tasks allowable before the queue will block when adding more.")
	TEXT("Default is to use 4 times the number of cores available or 16 when multithreading is disabled on the command line."),
	ECVF_Default);

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

Scope (from outer to inner):

file
function     void FImageWriteQueue::OnCVarsChanged

Source code excerpt:

{
	RecreateThreadPool();
	const int32 ConfiguredMaxQueueSize = CVarImageWriteQueueMaxQueueSize.GetValueOnAnyThread();
	MaxQueueSize = ConfiguredMaxQueueSize == -1 ? (ThreadPool ? ThreadPool->GetNumThreads() * 4 : 16) : ConfiguredMaxQueueSize;
}

void FImageWriteQueue::RecreateThreadPool()
{
	if (!FPlatformProcess::SupportsMultithreading())