Class OpenCLProfiler

Namespace

DotCompute.Backends.OpenCL.Profiling

Assembly

DotCompute.Backends.OpenCL.dll

Production-grade OpenCL profiler with event-based profiling, hardware counter integration, and comprehensive statistical analysis.

public sealed class OpenCLProfiler : IAsyncDisposable

Inheritance

object

OpenCLProfiler

Implements

IAsyncDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This profiler provides detailed performance metrics for OpenCL operations including:

• Kernel execution timing with hardware counters
• Memory transfer profiling (host-to-device, device-to-host, device-to-device)
• Kernel compilation and buffer allocation tracking
• Statistical aggregation (min/max/avg/percentiles)
• Thread-safe session management
• JSON and CSV export capabilities

Constructors

OpenCLProfiler(OpenCLEventManager, ILogger<OpenCLProfiler>)

Initializes a new instance of the OpenCLProfiler class.

public OpenCLProfiler(OpenCLEventManager eventManager, ILogger<OpenCLProfiler> logger)

Parameters

eventManager OpenCLEventManager

The OpenCL event manager for profiling integration.

logger ILogger<OpenCLProfiler>

Logger for diagnostic information.

Exceptions

ArgumentNullException

Thrown if eventManager or logger is null.

Methods

BeginSessionAsync(string, CancellationToken)

Begins a new profiling session with the specified name.

public Task<ProfilingSession> BeginSessionAsync(string name, CancellationToken cancellationToken = default)

Parameters

name string

Descriptive name for the profiling session.

cancellationToken CancellationToken

Cancellation token for async operations.

Returns

Task<ProfilingSession>

A profiling session handle for recording events.

Exceptions

ArgumentException

Thrown if name is null or whitespace.

DisposeAsync()

Asynchronously disposes the profiler and releases all resources.

public ValueTask DisposeAsync()

Returns

ValueTask

EndSessionAsync(ProfilingSession, CancellationToken)

Ends a profiling session, finalizes statistics, and returns the session for export.

public Task<ProfilingSession> EndSessionAsync(ProfilingSession session, CancellationToken cancellationToken = default)

Parameters

session ProfilingSession

The profiling session to end.

cancellationToken CancellationToken

Cancellation token for async operations.

Returns

Task<ProfilingSession>

The completed profiling session with finalized statistics.

Exceptions

ArgumentNullException

Thrown if session is null.

ExportSessionToCsvAsync(ProfilingSession, string, CancellationToken)

Exports a profiling session to CSV format for analysis tools.

public Task ExportSessionToCsvAsync(ProfilingSession session, string filePath, CancellationToken cancellationToken = default)

Parameters

session ProfilingSession

The profiling session to export.

filePath string

Destination file path for CSV output.

cancellationToken CancellationToken

Cancellation token for async operations.

Returns

Task

Exceptions

ArgumentNullException

Thrown if session or filePath is null.

IOException

Thrown if file write fails.

ExportSessionToJsonAsync(ProfilingSession, string, CancellationToken)

Exports a profiling session to JSON format.

public Task ExportSessionToJsonAsync(ProfilingSession session, string filePath, CancellationToken cancellationToken = default)

Parameters

session ProfilingSession

The profiling session to export.

filePath string

Destination file path for JSON output.

cancellationToken CancellationToken

Cancellation token for async operations.

Returns

Task

Exceptions

ArgumentNullException

Thrown if session or filePath is null.

IOException

Thrown if file write fails.

GetStatistics()

Gets comprehensive profiler statistics.

public ProfilerStatistics GetStatistics()

Returns

ProfilerStatistics

Profiler statistics including session and event counts.

ProfileKernelExecutionAsync(OpenCLKernel, OpenCLEventHandle, Dictionary<string, object>?, CancellationToken)

Profiles kernel execution by extracting timing information from an OpenCL event.

public Task<ProfiledEvent> ProfileKernelExecutionAsync(OpenCLKernel kernel, OpenCLEventHandle executionEvent, Dictionary<string, object>? metadata = null, CancellationToken cancellationToken = default)

Parameters

kernel OpenCLKernel

The kernel handle being profiled.

executionEvent OpenCLEventHandle

The event associated with kernel execution.

metadata Dictionary<string, object>

Optional metadata to attach to the profiled event.

cancellationToken CancellationToken

Cancellation token for async operations.

Returns

Task<ProfiledEvent>

A profiled event containing detailed timing information.

Exceptions

ArgumentException

Thrown if kernel handle is invalid.

OpenCLProfilingException

Thrown if profiling information cannot be retrieved.

ProfileMemoryTransferAsync(ProfiledOperation, ulong, OpenCLEventHandle, Dictionary<string, object>?, CancellationToken)

Profiles memory transfer operations with bandwidth calculations.

public Task<ProfiledEvent> ProfileMemoryTransferAsync(ProfiledOperation transferType, ulong sizeBytes, OpenCLEventHandle transferEvent, Dictionary<string, object>? metadata = null, CancellationToken cancellationToken = default)

Parameters

transferType ProfiledOperation

Type of memory transfer (host-to-device, device-to-host, etc.).

sizeBytes ulong

Size of the memory transfer in bytes.

transferEvent OpenCLEventHandle

The event associated with the memory transfer.

metadata Dictionary<string, object>

Optional metadata to attach to the profiled event.

cancellationToken CancellationToken

Cancellation token for async operations.

Returns

Task<ProfiledEvent>

A profiled event with bandwidth information in metadata.

Exceptions

ArgumentException

Thrown if sizeBytes is zero or negative.

OpenCLProfilingException

Thrown if profiling information cannot be retrieved.

RecordOperation(ProfilingSession, ProfiledOperation, string, long, Dictionary<string, object>?)

Records a non-event-based profiled operation (e.g., kernel compilation, buffer allocation).

public void RecordOperation(ProfilingSession session, ProfiledOperation operation, string name, long durationNanoseconds, Dictionary<string, object>? metadata = null)

Parameters

session ProfilingSession

The profiling session to record to.

operation ProfiledOperation

Type of operation being profiled.

name string

Descriptive name for the operation.

durationNanoseconds long

Duration of the operation in nanoseconds.

metadata Dictionary<string, object>

Optional metadata to attach.

TryGetHardwareCounters(OpenCLDeviceId, out Dictionary<string, long>)

Attempts to query hardware counters from the OpenCL device (vendor-specific).

public bool TryGetHardwareCounters(OpenCLDeviceId device, out Dictionary<string, long> counters)

Parameters

device OpenCLDeviceId

The OpenCL device to query.

counters Dictionary<string, long>

Output dictionary of counter name-value pairs.

Returns

bool

True if hardware counters were successfully retrieved, false otherwise.

Remarks

This method attempts to query vendor-specific performance counters. Support varies by vendor (AMD, NVIDIA, Intel) and may require special extensions.