Class OpenCLStreamConfiguration

Namespace

DotCompute.Backends.OpenCL.Configuration

Assembly

DotCompute.Backends.OpenCL.dll

Configuration for OpenCL stream (command queue) management.

public sealed class OpenCLStreamConfiguration

Inheritance

object

OpenCLStreamConfiguration

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This configuration controls how OpenCL command queues are pooled, created, and managed. Stream pooling reduces the overhead of queue creation and improves performance for workloads with many short-lived kernels.

Key features:

• Connection pooling pattern for command queues
• Automatic pool scaling based on usage patterns
• Queue property configuration (out-of-order, profiling)
• Priority-based queue management

Properties

Default

Gets the default stream configuration.

public static OpenCLStreamConfiguration Default { get; }

Property Value

OpenCLStreamConfiguration

A configuration suitable for general-purpose workloads with balanced performance and resource usage.

DefaultPriority

Gets the default priority for command queues.

public QueuePriority DefaultPriority { get; init; }

Property Value

QueuePriority

The default queue priority. Default is Normal.

Remarks

Queue priority affects scheduling on devices that support priority-based execution. Not all OpenCL implementations support queue priorities.

EnableAutoScaling

Gets a value indicating whether to enable automatic pool scaling.

public bool EnableAutoScaling { get; init; }

Property Value

bool

true if auto-scaling is enabled; otherwise, false. Default is true.

Remarks

When enabled, the pool size automatically adjusts based on usage patterns to maintain the target pool hit rate. The pool will grow up to MaxPoolSize and shrink down to MinPoolSize.

EnableOutOfOrder

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

public bool EnableOutOfOrder { get; init; }

Property Value

bool

true if out-of-order execution is enabled; otherwise, false. Default is false.

Remarks

Out-of-order execution allows the OpenCL runtime to reorder commands for better performance. This can improve throughput but may complicate synchronization. Only enable if your workload benefits from it and you have proper synchronization in place.

EnableProfiling

Gets a value indicating whether to enable profiling for command queues.

public bool EnableProfiling { get; init; }

Property Value

bool

true if profiling is enabled; otherwise, false. Default is false.

Remarks

Enabling profiling allows you to measure execution time of commands but may impact performance. Only enable this for development, debugging, or production monitoring scenarios.

HighThroughput

Gets a stream configuration optimized for high throughput.

public static OpenCLStreamConfiguration HighThroughput { get; }

Property Value

OpenCLStreamConfiguration

A configuration with larger pool sizes and out-of-order execution enabled.

Remarks

This configuration is suitable for workloads that submit many concurrent kernels and can benefit from out-of-order execution. Memory usage will be higher.

InitialPoolSize

Gets the initial size of the stream pool.

public int InitialPoolSize { get; init; }

Property Value

int

The number of command queues to create initially. Default is 4.

Remarks

This value determines how many command queues are pre-allocated when the pool is initialized. A higher value reduces initial latency but increases memory usage.

LowLatency

Gets a stream configuration optimized for low latency.

public static OpenCLStreamConfiguration LowLatency { get; }

Property Value

OpenCLStreamConfiguration

A configuration with smaller pool sizes and in-order execution for predictable latency.

Remarks

This configuration is suitable for latency-sensitive workloads where predictable execution order is more important than maximum throughput.

MaxPoolSize

Gets the maximum size of the stream pool.

public int MaxPoolSize { get; init; }

Property Value

int

The maximum number of command queues that can be pooled. Default is 16.

Remarks

Once this limit is reached, requests for new streams will wait for available queues or fail based on the configured timeout.

MinPoolSize

Gets the minimum size of the stream pool.

public int MinPoolSize { get; init; }

Property Value

int

The minimum number of command queues to keep alive. Default is 2.

Remarks

When auto-scaling is enabled, the pool will not shrink below this size. This ensures a baseline of immediately available queues.

PoolTimeout

Gets the timeout for acquiring a stream from the pool.

public TimeSpan PoolTimeout { get; init; }

Property Value

TimeSpan

The maximum time to wait for an available queue. Default is 30 seconds.

Remarks

If no queue becomes available within this timeout, the acquire operation will fail.

TargetPoolHitRate

Gets the target pool hit rate for auto-scaling.

public double TargetPoolHitRate { get; init; }

Property Value

double

The desired ratio of successful immediate acquisitions to total acquisition attempts. Default is 0.8 (80%).

Remarks

The auto-scaling algorithm attempts to maintain this hit rate by adjusting the pool size. A higher value means more queues kept available but higher memory usage. Valid range is 0.0 to 1.0.

Methods

Validate()

Validates the configuration values.

public void Validate()

Exceptions

ArgumentException

Thrown when one or more configuration values are invalid.