Class EventConfiguration

Namespace

DotCompute.Backends.OpenCL.Configuration

Assembly

DotCompute.Backends.OpenCL.dll

Configuration for OpenCL event management, pooling, and profiling behavior.

public sealed class EventConfiguration

Inheritance

object

EventConfiguration

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

OpenCL events are the primary synchronization mechanism for coordinating command execution across queues and devices. This configuration controls event lifecycle, pooling strategies, and profiling capabilities.

Properties

AutoReleaseCompletedEvents

Gets a value indicating whether to automatically release completed events.

public bool AutoReleaseCompletedEvents { get; init; }

Property Value

bool

true to auto-release events; otherwise, false. Default is true.

Remarks

When enabled, events are automatically returned to the pool once they complete and all event callbacks have executed. This reduces manual resource management but requires care to avoid use-after-free scenarios.

Debugging

Creates an event configuration optimized for debugging.

public static EventConfiguration Debugging { get; }

Property Value

EventConfiguration

A new EventConfiguration instance optimized for debugging.

Remarks

This configuration:

• Uses smaller pool sizes to track event usage
• Enables profiling for detailed timing information
• Uses short polling intervals for responsive debugging
• Disables automatic release for explicit resource management
• Uses shorter timeouts to detect hung operations quickly

Default

Creates a default event configuration instance.

public static EventConfiguration Default { get; }

Property Value

EventConfiguration

A new EventConfiguration instance with default settings.

DefaultWaitTimeout

Gets the default timeout for waiting on events.

public TimeSpan DefaultWaitTimeout { get; init; }

Property Value

TimeSpan

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

Remarks

This timeout is used when waiting for events to complete using clWaitForEvents or event.Wait(). If an event does not complete within this duration, a timeout exception is thrown. Set to a higher value for long-running kernels.

Exceptions

ArgumentOutOfRangeException

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

EnableEventProfiling

Gets a value indicating whether to enable event profiling by default.

public bool EnableEventProfiling { get; init; }

Property Value

bool

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

Remarks

When enabled, timing information is collected for all events, allowing measurement of kernel execution time, memory transfer time, etc. This requires command queues to be created with CL_QUEUE_PROFILING_ENABLE.

MaximumEventCallbacks

Gets the maximum number of event callbacks that can be registered per event.

public int MaximumEventCallbacks { get; init; }

Property Value

int

The maximum callbacks. Must be greater than 0. Default is 16.

Remarks

OpenCL allows multiple callbacks to be registered for event completion. This limit prevents unbounded callback registration which could impact performance and memory usage.

Exceptions

ArgumentOutOfRangeException

Thrown when the value is less than 1.

MaximumEventPoolSize

Gets the maximum number of events that can exist in the pool.

public int MaximumEventPoolSize { get; init; }

Property Value

int

The maximum pool size. Must be greater than or equal to MinimumEventPoolSize. Default is 128.

Remarks

This limit prevents unbounded event creation. When the pool is exhausted, callers must wait for events to be returned to the pool or create events outside the pool with potential performance implications.

Exceptions

ArgumentOutOfRangeException

Thrown when the value is less than MinimumEventPoolSize.

MinimalOverhead

Creates an event configuration optimized for minimal overhead.

public static EventConfiguration MinimalOverhead { get; }

Property Value

EventConfiguration

A new EventConfiguration instance optimized for performance.

Remarks

This configuration:

• Uses larger pool sizes to reduce allocation overhead
• Disables profiling for minimal CPU overhead
• Uses longer polling intervals to reduce CPU usage
• Enables automatic event release for reduced manual management

MinimumEventPoolSize

Gets the minimum number of events to maintain in the pool.

public int MinimumEventPoolSize { get; init; }

Property Value

int

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

Remarks

Events are pooled to avoid the overhead of creating and destroying them for every operation. This value ensures a baseline number of events are always available for immediate use.

Exceptions

ArgumentOutOfRangeException

Thrown when the value is less than 1.

PollingInterval

Gets the polling interval for event status checks.

public TimeSpan PollingInterval { get; init; }

Property Value

TimeSpan

The polling interval. Must be greater than TimeSpan.Zero. Default is 1 millisecond.

Remarks

When waiting for events asynchronously, the status is checked at this interval. Shorter intervals provide lower latency but higher CPU usage. Longer intervals reduce CPU overhead but may delay event completion detection.

Exceptions

ArgumentOutOfRangeException

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