Skip to content

Event API

Markers recorded into a stream, used to wait for a point in that stream or to order another stream against it.

Contents

API Description
HaEventCreate Creates an event
HaEventDestroy Destroys an event and releases its resources
HaEventQuery Queries the completion status of an event without blocking
HaEventRecord Records an event on the specified stream
HaEventSynchronize Blocks the calling thread until the event completes

HaEventCreate

Creates an event.

Parameter Direction Default Description
event out — Output handle.

Returns — HaSuccess if the event was created successfully.

Signature · Example
1
HaError HaEventCreate(HaEvent_t *event);

Example

1
2
HaEvent_t done = nullptr;
HaEventCreate(&done);   // created unrecorded; it marks nothing until HaEventRecord()

HaEventDestroy

Destroys an event.

Parameter Direction Default Description
event in — Event to destroy.

Returns — HaSuccess if the event was destroyed successfully; HaEventInvalidHandle if event is not a live event; HaStreamNotReady if a pending record op did not drain within the timeout (event stays valid); another HaError if releasing the underlying device resource failed.

Signature · Example
1
HaError HaEventDestroy(HaEvent_t event);

Example

1
2
HaEventSynchronize(done);
HaEventDestroy(done);

Note

Do not destroy an event another stream is still waiting on via HaStreamWaitEvent().

Note

If a HaEventRecord() call on event is concurrently in flight but has not yet committed (the record has not yet been published onto the event), this succeeds immediately without blocking, in the spirit of cudaEventDestroy()'s "destroy before completion is legal" contract. event becomes invalid to every other call the instant this returns; the underlying resources are released asynchronously afterward, with no observable effect on the caller. The racing HaEventRecord() itself fails with HaEventInvalidHandle.

Note

An event that has already completed recording is destroyed differently: this blocks until its record op has drained on the recording stream (capped by an internal drain timeout, currently five minutes) and returns HaStreamNotReady if that confirmation times out. On that failure the event is NOT destroyed and stays valid, so the caller may retry. If the recording stream has already been destroyed, this does not block.


HaEventQuery

Queries the completion status of an event without blocking.

Parameter Direction Default Description
event in — Event to query.

Returns — HaSuccess if the event has completed; HaEventNotReady if it has not yet completed; HaEventNotRecorded if HaEventRecord() was never called; or another HaError on failure.

Signature · Example
1
HaError HaEventQuery(HaEvent_t event);

Example

1
2
3
4
5
6
7
switch (HaEventQuery(done)) {
  case HaError::HaSuccess:          // the recorded point has been reached
  case HaError::HaEventNotReady:    // recorded, still outstanding
  case HaError::HaEventNotRecorded: // HaEventRecord() was never called on this event
  default:                          // a real failure
    break;
}

HaEventRecord

Records an event into a stream.

Parameter Direction Default Description
event in — Event to record.
stream in — Stream to record into; pass HA_STREAM_DEFAULT to use the calling thread's default stream on the current device.

Returns — HaSuccess if the event was enqueued successfully.

Signature · Example
1
HaError HaEventRecord(HaEvent_t event, HaStream_t stream);

Example

1
2
3
4
5
HaLaunchKernelAsync(kernel_path, args, stream);
HaEventRecord(done, stream);   // marks the point after that launch
HaLaunchKernelAsync(other_path, args2, stream);

HaEventSynchronize(done);      // returns after the first launch, not the second

Note

The event is considered complete when all operations preceding it in the stream have finished.

Note

At most one HaEventRecord() may be in flight for a given event at a time: a second concurrent call targeting the same not-yet-recorded event fails immediately with HaEventInvalidArgument rather than racing the first.

Note

A concurrent HaEventDestroy() on event is legal and wins the race: it returns HaSuccess immediately and this call then fails with HaEventInvalidHandle, having already enqueued its record. The device resources are cleaned up on the stream afterward; the caller does not need to do anything.


HaEventSynchronize

Blocks the calling thread until an event has completed.

Parameter Direction Default Description
event in — Event to synchronize on.

Returns — HaSuccess if the event completed successfully; HaEventNotRecorded if HaEventRecord() has not yet been called on this event; HaEventInvalidHandle if event is not a live event; HaDeviceNotReady if the event's device is being reset concurrently, or was reset while this call was blocked; in that case the wait result is discarded rather than reported as completion.

Signature · Example
1
HaError HaEventSynchronize(HaEvent_t event);

Example

1
2
HaEventRecord(done, stream);
HaEventSynchronize(done);   // blocks until the marked point is reached

Note

Waiting on an event that was never recorded returns HaEventNotRecorded rather than blocking. Use HaEventSynchronize() to wait for one point in a pipeline instead of stalling on all of it with HaStreamSynchronize().