Class CudaEventTimer

Namespace

DotCompute.Backends.CUDA.Timing

Assembly

DotCompute.Backends.CUDA.dll

Lightweight CUDA event timer for high-precision GPU execution timing.

public static class CudaEventTimer

Inheritance

object

CudaEventTimer

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This static utility provides simple async timing operations using CUDA events without requiring dependency injection infrastructure. Designed for use during kernel compilation, validation, and lightweight profiling scenarios.

For comprehensive timing with statistical analysis, use CudaEventManager instead.

Timing resolution: - CC 6.0+: ~1 nanosecond (hardware event timestamping) - CC 5.x: ~500 nanoseconds

Methods

CreateEventAsync(nint, CancellationToken)

Creates a CUDA event for high-precision timing.

public static Task<nint> CreateEventAsync(nint cudaContext, CancellationToken cancellationToken = default)

Parameters

cudaContext nint

The CUDA context to make current before creating the event.

cancellationToken CancellationToken

Optional cancellation token.

Returns

Task<nint>

A task that completes with the created event handle.

Remarks

Creates an event with default flags optimized for timing measurements. Events created with this method support cudaEventElapsedTime().

Exceptions

InvalidOperationException

Thrown when event creation fails or context cannot be set.

DestroyEventAsync(nint, nint, CancellationToken)

Destroys a CUDA event and releases resources.

public static Task DestroyEventAsync(nint eventPtr, nint cudaContext, CancellationToken cancellationToken = default)

Parameters

eventPtr nint

The event handle to destroy.

cudaContext nint

The CUDA context to make current before destroying.

cancellationToken CancellationToken

Optional cancellation token.

Returns

Task

A task that completes when the event is destroyed.

Remarks

The event should be synchronized before destruction to avoid undefined behavior.

Exceptions

InvalidOperationException

Thrown when event destruction fails or context cannot be set.

ElapsedTimeAsync(nint, nint, nint, CancellationToken)

Calculates elapsed time between two CUDA events in milliseconds.

public static Task<float> ElapsedTimeAsync(nint startEvent, nint endEvent, nint cudaContext, CancellationToken cancellationToken = default)

Parameters

startEvent nint

The start event handle.

endEvent nint

The end event handle.

cudaContext nint

The CUDA context to make current before measuring.

cancellationToken CancellationToken

Optional cancellation token.

Returns

Task<float>

A task that completes with the elapsed time in milliseconds.

Remarks

Both events must be created with timing enabled (default for CreateEventAsync). The end event should be synchronized before calling this method for accurate results.

Resolution: - CC 6.0+: ~0.5 milliseconds (hardware limitation) - CC 5.x: ~1 millisecond

Exceptions

InvalidOperationException

Thrown when elapsed time calculation fails or context cannot be set.

MeasureAsync(Func<nint, Task>, CudaStream, nint, CancellationToken)

Measures the execution time of a GPU operation using CUDA events.

public static Task<float> MeasureAsync(Func<nint, Task> operation, CudaStream stream, nint cudaContext, CancellationToken cancellationToken = default)

Parameters

operation Func<nint, Task>

The asynchronous operation to measure (receives stream handle).

stream CudaStream

The CUDA stream to record events in.

cudaContext nint

The CUDA context to make current.

cancellationToken CancellationToken

Optional cancellation token.

Returns

Task<float>

A task that completes with the elapsed time in milliseconds.

Remarks

This is a convenience method that: 1. Creates start and end events 2. Records start event 3. Executes the operation 4. Records end event 5. Synchronizes end event 6. Calculates elapsed time 7. Cleans up events

Example usage:

var kernelTime = await CudaEventTimer.MeasureAsync(
    async streamHandle => await kernel.LaunchAsync(gridDim, blockDim, streamHandle),
    stream,
    context);
Console.WriteLine($"Kernel executed in {kernelTime:F3} ms");

Exceptions

InvalidOperationException

Thrown when timing fails or context cannot be set.

RecordEventAsync(nint, CudaStream, nint, CancellationToken)

Records a CUDA event in the specified stream.

public static Task RecordEventAsync(nint eventPtr, CudaStream stream, nint cudaContext, CancellationToken cancellationToken = default)

Parameters

eventPtr nint

The event handle to record.

stream CudaStream

The CUDA stream to record the event in.

cudaContext nint

The CUDA context to make current before recording.

cancellationToken CancellationToken

Optional cancellation token.

Returns

Task

A task that completes when the event is recorded.

Remarks

The event will be recorded after all prior work in the stream completes. Use this to mark start/end points for timing measurements.

Exceptions

InvalidOperationException

Thrown when event recording fails or context cannot be set.

SynchronizeEventAsync(nint, nint, CancellationToken)

Synchronizes with a CUDA event, waiting for it to complete.

public static Task SynchronizeEventAsync(nint eventPtr, nint cudaContext, CancellationToken cancellationToken = default)

Parameters

eventPtr nint

The event handle to synchronize with.

cudaContext nint

The CUDA context to make current before synchronizing.

cancellationToken CancellationToken

Optional cancellation token.

Returns

Task

A task that completes when the event is synchronized.

Remarks

Blocks until all prior work in the stream (up to the event) completes. Required before calling ElapsedTimeAsync() to ensure accurate measurements.

Exceptions

InvalidOperationException

Thrown when event synchronization fails or context cannot be set.