Class OpenCLConfiguration

Namespace

DotCompute.Backends.OpenCL.Configuration

Assembly

DotCompute.Backends.OpenCL.dll

Root configuration class for the OpenCL backend providing comprehensive control over backend behavior, resource management, and performance tuning.

public sealed class OpenCLConfiguration

Inheritance

object

OpenCLConfiguration

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This configuration class serves as the central point for all OpenCL backend settings, including pool sizes, timeout values, performance optimizations, and vendor-specific overrides. All properties are init-only and include validation to ensure correctness.

Properties

BuildOptions

Gets the OpenCL build options to use for kernel compilation.

public string? BuildOptions { get; init; }

Property Value

string

The build options string. Can be null or empty for default behavior.

Remarks

Common options include:

• "-cl-fast-relaxed-math": Enable aggressive optimizations (may reduce precision)
• "-cl-mad-enable": Enable mad (multiply-add) instruction
• "-cl-no-signed-zeros": Allow optimizations for signed zero
• "-cl-std=CL2.0": Specify OpenCL C version

Default

Creates a default OpenCL configuration instance.

public static OpenCLConfiguration Default { get; }

Property Value

OpenCLConfiguration

A new OpenCLConfiguration instance with default settings.

Development

Creates a development configuration optimized for debugging and profiling.

public static OpenCLConfiguration Development { get; }

Property Value

OpenCLConfiguration

A new OpenCLConfiguration instance optimized for development.

Remarks

This configuration:

• Enables validation and profiling
• Uses smaller pool sizes to reduce resource usage
• Prefers in-order execution for deterministic behavior

EnableKernelCache

Gets a value indicating whether to enable kernel caching.

public bool EnableKernelCache { get; init; }

Property Value

bool

true to enable kernel caching; otherwise, false. Default is true.

Remarks

When enabled, compiled kernels are cached to avoid recompilation on subsequent uses. This significantly improves performance for repeated kernel executions.

EnableProfiling

Gets a value indicating whether to enable automatic performance profiling.

public bool EnableProfiling { get; init; }

Property Value

bool

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

Remarks

When enabled, command queues are created with CL_QUEUE_PROFILING_ENABLE, allowing timing information to be collected. This incurs a small performance overhead.

EnableValidation

Gets a value indicating whether to validate all inputs before execution.

public bool EnableValidation { get; init; }

Property Value

bool

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

Remarks

When enabled, all kernel arguments, buffer sizes, and work dimensions are validated before execution. Disabling this can improve performance in production after thorough testing.

Event

Gets the event configuration for OpenCL event management.

public EventConfiguration Event { get; init; }

Property Value

EventConfiguration

The event configuration instance. Never null.

Remarks

This configuration controls event pooling, profiling, and wait timeout settings.

HighPerformance

Creates a high-performance configuration optimized for throughput.

public static OpenCLConfiguration HighPerformance { get; }

Property Value

OpenCLConfiguration

A new OpenCLConfiguration instance optimized for performance.

Remarks

This configuration:

• Disables validation for maximum throughput
• Uses larger pool sizes
• Enables out-of-order execution
• Disables profiling

KernelCacheSize

Gets the maximum number of compiled kernels to cache.

public int KernelCacheSize { get; init; }

Property Value

int

The kernel cache size. Must be greater than 0. Default is 256.

Remarks

When the cache reaches this size, the least recently used kernels are evicted. A larger cache reduces compilation overhead but uses more memory.

Exceptions

ArgumentOutOfRangeException

Thrown when the value is less than 1.

MaximumPoolSize

Gets the maximum number of command queues that can be created in the pool.

public int MaximumPoolSize { get; init; }

Property Value

int

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

Remarks

This limit prevents unbounded resource consumption. When the pool reaches this size, additional queue requests will wait for an available queue to be returned.

Exceptions

ArgumentOutOfRangeException

Thrown when the value is less than MinimumPoolSize.

Memory

Gets the memory configuration for buffer management and P2P transfers.

public MemoryConfiguration Memory { get; init; }

Property Value

MemoryConfiguration

The memory configuration instance. Never null.

Remarks

This configuration controls buffer pooling, alignment, pinned memory, and peer-to-peer transfer settings for multi-device scenarios.

MinimumPoolSize

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

public int MinimumPoolSize { get; init; }

Property Value

int

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

Remarks

Setting this value too low may result in queue allocation overhead during bursts. Setting it too high wastes system resources. A value of 2-4 is recommended for most applications.

Exceptions

ArgumentOutOfRangeException

Thrown when the value is less than 1.

OperationTimeout

Gets the timeout duration for command queue operations.

public TimeSpan OperationTimeout { get; init; }

Property Value

TimeSpan

The operation timeout. Must be greater than TimeSpan.Zero. Default is 60 seconds.

Remarks

This timeout applies to individual operations like kernel execution, memory transfers, and event waits. Long-running kernels may need a higher value.

Exceptions

ArgumentOutOfRangeException

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

PreferOutOfOrderExecution

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

public bool PreferOutOfOrderExecution { get; init; }

Property Value

bool

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

Remarks

Out-of-order queues can provide better performance by allowing the OpenCL runtime to reorder commands for optimal execution. However, they require explicit event-based synchronization to maintain correctness.

QueueAcquisitionTimeout

Gets the timeout duration for acquiring a command queue from the pool.

public TimeSpan QueueAcquisitionTimeout { get; init; }

Property Value

TimeSpan

The acquisition timeout. Must be greater than TimeSpan.Zero. Default is 30 seconds.

Remarks

If a queue cannot be acquired within this timeout, an exception is thrown. This prevents indefinite blocking when the pool is exhausted.

Exceptions

ArgumentOutOfRangeException

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

Stream

Gets the stream configuration for command queue management.

public StreamConfiguration Stream { get; init; }

Property Value

StreamConfiguration

The stream configuration instance. Never null.

Remarks

This configuration controls command queue pooling, priority mapping, and profiling settings.

VendorOverrides

Gets vendor-specific configuration overrides.

public IReadOnlyDictionary<string, object> VendorOverrides { get; init; }

Property Value

IReadOnlyDictionary<string, object>

A dictionary of vendor-specific settings. Never null.

Remarks

This allows customization for specific OpenCL implementations:

• "NVIDIA": CUDA-specific optimizations
• "AMD": ROCm/PAL-specific settings
• "Intel": NEO driver optimizations
• "Apple": Metal interop settings