HIP: Heterogenous-computing Interface for Portability: Event Management

HIP: Heterogenous-computing Interface for Portability

Functions
Event Management
HIP API

This section describes the event management functions of HIP runtime API. More...

Collaboration diagram for Event Management:

## Functions
hipError_t | hipEventCreateWithFlags (hipEvent_t *event, unsigned flags)
| Create an event with the specified flags. More...
hipError_t | hipEventCreate (hipEvent_t *event)
hipError_t | hipEventRecord (hipEvent_t event, hipStream_t stream)
| Record an event in the specified stream. More...
hipError_t | hipEventDestroy (hipEvent_t event)
| Destroy the specified event. More...
hipError_t | hipEventSynchronize (hipEvent_t event)
| Wait for an event to complete. More...
hipError_t | hipEventElapsedTime (float *ms, hipEvent_t start, hipEvent_t stop)
| Return the elapsed time between two events. More...
hipError_t | hipEventQuery (hipEvent_t event)
| Query event status. More...

## Detailed Description

This section describes the event management functions of HIP runtime API.

## Function Documentation

## ◆ hipEventCreate()

hipError_t hipEventCreate | ( | hipEvent_t * | event | ) |

Create an event

Parameters

  [in,out] | event | Returns the newly created event.

Returns
  hipSuccess, #hipErrorNotInitialized, hipErrorInvalidValue, hipErrorLaunchFailure, #hipErrorOutOfMemory

See also
  hipEventCreateWithFlags, hipEventRecord, hipEventQuery, hipEventSynchronize, hipEventDestroy, hipEventElapsedTime

## ◆ hipEventCreateWithFlags()

hipError_t hipEventCreateWithFlags | ( | hipEvent_t * | event,
|  | unsigned | flags
| ) |  |

Create an event with the specified flags.

Parameters

  [in,out] | event | Returns the newly created event.
  [in] | flags | Flags to control event behavior. Valid values are hipEventDefault, hipEventBlockingSync, hipEventDisableTiming, hipEventInterprocess hipEventDefault : Default flag. The event will use active synchronization and will support timing. Blocking synchronization provides lowest possible latency at the expense of dedicating a CPU to poll on the event. hipEventBlockingSync : The event will use blocking synchronization : if hipEventSynchronize is called on this event, the thread will block until the event completes. This can increase latency for the synchroniation but can result in lower power and more resources for other CPU threads. hipEventDisableTiming : Disable recording of timing information. Events created with this flag would not record profiling data and provide best performance if used for synchronization.

Warning
  On AMD platform, hipEventInterprocess support is under development. Use of this flag will return an error.

Returns
  hipSuccess, #hipErrorNotInitialized, hipErrorInvalidValue, hipErrorLaunchFailure, #hipErrorOutOfMemory

See also
  hipEventCreate, hipEventSynchronize, hipEventDestroy, hipEventElapsedTime

## ◆ hipEventDestroy()

hipError_t hipEventDestroy | ( | hipEvent_t | event | ) |

Destroy the specified event.

Parameters

  [in] | event | Event to destroy.

Returns
  hipSuccess, #hipErrorNotInitialized, hipErrorInvalidValue, hipErrorLaunchFailure

Releases memory associated with the event. If the event is recording but has not completed recording when hipEventDestroy() is called, the function will return immediately and the completion_future resources will be released later, when the hipDevice is synchronized.

See also
  hipEventCreate, hipEventCreateWithFlags, hipEventQuery, hipEventSynchronize, hipEventRecord, hipEventElapsedTime

Returns
  hipSuccess

## ◆ hipEventElapsedTime()

hipError_t hipEventElapsedTime | ( | float * | ms,
|  | hipEvent_t | start,
|  | hipEvent_t | stop
| ) |  |

Return the elapsed time between two events.

Parameters

  [out] | ms | : Return time between start and stop in ms.
  [in] | start | : Start event.
  [in] | stop | : Stop event.

Returns
  hipSuccess, hipErrorInvalidValue, hipErrorNotReady, #hipErrorInvalidHandle, #hipErrorNotInitialized, hipErrorLaunchFailure

Computes the elapsed time between two events. Time is computed in ms, with a resolution of approximately 1 us.

Events which are recorded in a NULL stream will block until all commands on all other streams complete execution, and then record the timestamp.

Events which are recorded in a non-NULL stream will record their timestamp when they reach the head of the specified stream, after all previous commands in that stream have completed executing. Thus the time that the event recorded may be significantly after the host calls hipEventRecord().

If hipEventRecord() has not been called on either event, then #hipErrorInvalidHandle is returned. If hipEventRecord() has been called on both events, but the timestamp has not yet been recorded on one or both events (that is, hipEventQuery() would return hipErrorNotReady on at least one of the events), then hipErrorNotReady is returned.

Note, for HIP Events used in kernel dispatch using hipExtLaunchKernelGGL/hipExtLaunchKernel, events passed in hipExtLaunchKernelGGL/hipExtLaunchKernel are not explicitly recorded and should only be used to get elapsed time for that specific launch. In case events are used across multiple dispatches, for example, start and stop events from different hipExtLaunchKernelGGL/ hipExtLaunchKernel calls, they will be treated as invalid unrecorded events, HIP will throw error "hipErrorInvalidHandle" from hipEventElapsedTime.

See also
  hipEventCreate, hipEventCreateWithFlags, hipEventQuery, hipEventDestroy, hipEventRecord, hipEventSynchronize

## ◆ hipEventQuery()

hipError_t hipEventQuery | ( | hipEvent_t | event | ) |

Query event status.

Parameters

  [in] | event | Event to query.

Returns
  hipSuccess, hipErrorNotReady, #hipErrorInvalidHandle, hipErrorInvalidValue, #hipErrorNotInitialized, hipErrorLaunchFailure

Query the status of the specified event. This function will return hipErrorNotReady if all commands in the appropriate stream (specified to hipEventRecord()) have completed. If that work has not completed, or if hipEventRecord() was not called on the event, then hipSuccess is returned.

See also
  hipEventCreate, hipEventCreateWithFlags, hipEventRecord, hipEventDestroy, hipEventSynchronize, hipEventElapsedTime

## ◆ hipEventRecord()

hipError_t hipEventRecord | ( | hipEvent_t | event,
|  | hipStream_t | stream
| ) |  |

Record an event in the specified stream.

Parameters

  [in] | event | event to record.
  [in] | stream | stream in which to record event.

Returns
  hipSuccess, hipErrorInvalidValue, #hipErrorNotInitialized, #hipErrorInvalidHandle, hipErrorLaunchFailure

hipEventQuery() or hipEventSynchronize() must be used to determine when the event transitions from "recording" (after hipEventRecord() is called) to "recorded" (when timestamps are set, if requested).

Events which are recorded in a non-NULL stream will transition to from recording to "recorded" state when they reach the head of the specified stream, after all previous commands in that stream have completed executing.

If hipEventRecord() has been previously called on this event, then this call will overwrite any existing state in event.

If this function is called on an event that is currently being recorded, results are undefined

- either outstanding recording may save state into the event, and the order is not guaranteed.

See also
  hipEventCreate, hipEventCreateWithFlags, hipEventQuery, hipEventSynchronize, hipEventDestroy, hipEventElapsedTime

## ◆ hipEventSynchronize()

hipError_t hipEventSynchronize | ( | hipEvent_t | event | ) |

Wait for an event to complete.

This function will block until the event is ready, waiting for all previous work in the stream specified when event was recorded with hipEventRecord().

If hipEventRecord() has not been called on `event`, this function returns immediately.

TODO-hip- This function needs to support hipEventBlockingSync parameter.

Parameters

  [in] | event | Event on which to wait.

Returns
  hipSuccess, hipErrorInvalidValue, #hipErrorNotInitialized, #hipErrorInvalidHandle, hipErrorLaunchFailure

See also
  hipEventCreate, hipEventCreateWithFlags, hipEventQuery, hipEventDestroy, hipEventRecord, hipEventElapsedTime