Class StreamConfiguration

Namespace

DotCompute.Backends.OpenCL.Configuration

Assembly

DotCompute.Backends.OpenCL.dll

Configuration for OpenCL command queue (stream) management and pooling behavior.

public sealed class StreamConfiguration

Inheritance

object

StreamConfiguration

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This configuration controls how command queues are created, managed, and pooled within the OpenCL backend. Command queues are the primary mechanism for submitting work to OpenCL devices and managing execution order.

Properties

Default

Creates a default stream configuration instance.

public static StreamConfiguration Default { get; }

Property Value

StreamConfiguration

A new StreamConfiguration instance with default settings.

Development

Creates a development stream configuration.

public static StreamConfiguration Development { get; }

Property Value

StreamConfiguration

A new StreamConfiguration instance optimized for development.

Remarks

This configuration:

• Uses minimal pool sizes to reduce resource usage
• Enables profiling for debugging
• Prefers in-order queues for deterministic behavior
• Uses short idle timeouts to release resources quickly

EnableOnDeviceQueue

Gets a value indicating whether to enable on-device queue support (OpenCL 2.0+).

public bool EnableOnDeviceQueue { get; init; }

Property Value

bool

true to enable on-device queues; otherwise, false. Default is false.

Remarks

On-device queues (CL_QUEUE_ON_DEVICE) allow kernels to enqueue other kernels directly on the device without host intervention. This is only available in OpenCL 2.0 and later, and not all devices support it.

EnableProfilingByDefault

Gets a value indicating whether to enable profiling on command queues by default.

public bool EnableProfilingByDefault { get; init; }

Property Value

bool

true to enable profiling; otherwise, false. Default is false.

Remarks

When enabled, all command queues are created with CL_QUEUE_PROFILING_ENABLE, allowing collection of timing information for commands. This incurs a small performance overhead (~5-10%).

HighThroughput

Creates a high-throughput stream configuration.

public static StreamConfiguration HighThroughput { get; }

Property Value

StreamConfiguration

A new StreamConfiguration instance optimized for throughput.

Remarks

This configuration:

• Uses larger pool sizes for high concurrency
• Enables out-of-order execution
• Disables profiling for minimal overhead
• Uses longer idle timeouts to keep queues warm

IdleTimeout

Gets the idle timeout for pooled command queues.

public TimeSpan IdleTimeout { get; init; }

Property Value

TimeSpan

The idle timeout. Must be greater than TimeSpan.Zero. Default is 5 minutes.

Remarks

Command queues that have been idle for longer than this duration may be released from the pool to conserve resources, but the pool will never shrink below MinimumQueuePoolSize.

Exceptions

ArgumentOutOfRangeException

Thrown when the value is less than or equal to TimeSpan.Zero.

MaximumQueuePoolSize

Gets the maximum number of command queues that can exist in the pool per device.

public int MaximumQueuePoolSize { get; init; }

Property Value

int

The maximum pool size. Must be greater than or equal to MinimumQueuePoolSize. Default is 16.

Remarks

This limit prevents unbounded queue creation. When the limit is reached, requests for new queues will block until an existing queue is returned to the pool.

Exceptions

ArgumentOutOfRangeException

Thrown when the value is less than MinimumQueuePoolSize.

MinimumQueuePoolSize

Gets the minimum number of command queues to maintain in the pool per device.

public int MinimumQueuePoolSize { get; init; }

Property Value

int

The minimum pool size. Must be greater than 0. Default is 2.

Remarks

Each OpenCL device gets its own pool of command queues. This value determines the baseline number of queues that are pre-allocated and kept warm.

Exceptions

ArgumentOutOfRangeException

Thrown when the value is less than 1.

OnDeviceQueueSize

Gets the maximum size of on-device queues in bytes (OpenCL 2.0+).

public int OnDeviceQueueSize { get; init; }

Property Value

int

The on-device queue size. Must be greater than 0. Default is 1 MB (1048576 bytes).

Remarks

This value is only used when EnableOnDeviceQueue is true. It determines the size of the queue that kernels can use for device-side enqueuing.

Exceptions

ArgumentOutOfRangeException

Thrown when the value is less than 1.

PreferOutOfOrderQueues

Gets a value indicating whether to prefer out-of-order execution queues.

public bool PreferOutOfOrderQueues { get; init; }

Property Value

bool

true to prefer out-of-order queues; otherwise, false. Default is true.

Remarks

Out-of-order queues (CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE) allow the OpenCL runtime to reorder commands for better performance. In-order queues provide simpler semantics but may have lower throughput.

QueuePriority

Gets the priority mapping for command queues.

public string QueuePriority { get; init; }

Property Value

string

The queue priority. Valid values are "low", "normal", "high". Default is "normal".

Remarks

This maps to OpenCL queue priorities if supported by the implementation:

• "low": CL_QUEUE_PRIORITY_LOW_KHR
• "normal": Default priority
• "high": CL_QUEUE_PRIORITY_HIGH_KHR Not all OpenCL implementations support queue priorities.

Exceptions

ArgumentException

Thrown when the value is not "low", "normal", or "high".