6.16. Event Management
This section describes the event management functions of the low-level CUDA driver application programming interface.
Functions
- CUresult cuEventCreate ( CUevent* phEvent, unsigned int Flags )
- Creates an event.
- CUresult cuEventDestroy ( CUevent hEvent )
- Destroys an event.
- CUresult cuEventElapsedTime ( float* pMilliseconds, CUevent hStart, CUevent hEnd )
- Computes the elapsed time between two events.
- CUresult cuEventQuery ( CUevent hEvent )
- Queries an event's status.
- CUresult cuEventRecord ( CUevent hEvent, CUstream hStream )
- Records an event.
- CUresult cuEventRecordWithFlags ( CUevent hEvent, CUstream hStream, unsigned int flags )
- Records an event.
- CUresult cuEventSynchronize ( CUevent hEvent )
- Waits for an event to complete.
Functions
- CUresult cuEventCreate ( CUevent* phEvent, unsigned int Flags )
-
Creates an event.
Parameters
- phEvent
- - Returns newly created event
- Flags
- - Event creation flags
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_OUT_OF_MEMORY
Description
Creates an event *phEvent for the current context with the flags specified via Flags. Valid flags include:
-
CU_EVENT_DEFAULT: Default event creation flag.
-
CU_EVENT_BLOCKING_SYNC: Specifies that the created event should use blocking synchronization. A CPU thread that uses cuEventSynchronize() to wait on an event created with this flag will block until the event has actually been recorded.
-
CU_EVENT_DISABLE_TIMING: Specifies that the created event does not need to record timing data. Events created with this flag specified and the CU_EVENT_BLOCKING_SYNC flag not specified will provide the best performance when used with cuStreamWaitEvent() and cuEventQuery().
-
CU_EVENT_INTERPROCESS: Specifies that the created event may be used as an interprocess event by cuIpcGetEventHandle(). CU_EVENT_INTERPROCESS must be specified along with CU_EVENT_DISABLE_TIMING.
Note:Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuEventRecord, cuEventQuery, cuEventSynchronize, cuEventDestroy, cuEventElapsedTime, cudaEventCreate, cudaEventCreateWithFlags
- CUresult cuEventDestroy ( CUevent hEvent )
-
Destroys an event.
Parameters
- hEvent
- - Event to destroy
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_HANDLE
Description
Destroys the event specified by hEvent.
An event may be destroyed before it is complete (i.e., while cuEventQuery() would return CUDA_ERROR_NOT_READY). In this case, the call does not block on completion of the event, and any associated resources will automatically be released asynchronously at completion.
Note:Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuEventCreate, cuEventRecord, cuEventQuery, cuEventSynchronize, cuEventElapsedTime, cudaEventDestroy
- CUresult cuEventElapsedTime ( float* pMilliseconds, CUevent hStart, CUevent hEnd )
-
Computes the elapsed time between two events.
Parameters
- pMilliseconds
- - Time between hStart and hEnd in ms
- hStart
- - Starting event
- hEnd
- - Ending event
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_NOT_READY, CUDA_ERROR_UNKNOWN
Description
Computes the elapsed time between two events (in milliseconds with a resolution of around 0.5 microseconds).
If either event was last recorded in a non-NULL stream, the resulting time may be greater than expected (even if both used the same stream handle). This happens because the cuEventRecord() operation takes place asynchronously and there is no guarantee that the measured latency is actually just between the two events. Any number of other different stream operations could execute in between the two measured events, thus altering the timing in a significant way.
If cuEventRecord() has not been called on either event then CUDA_ERROR_INVALID_HANDLE is returned. If cuEventRecord() has been called on both events but one or both of them has not yet been completed (that is, cuEventQuery() would return CUDA_ERROR_NOT_READY on at least one of the events), CUDA_ERROR_NOT_READY is returned. If either event was created with the CU_EVENT_DISABLE_TIMING flag, then this function will return CUDA_ERROR_INVALID_HANDLE.
Note:Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuEventCreate, cuEventRecord, cuEventQuery, cuEventSynchronize, cuEventDestroy, cudaEventElapsedTime
- CUresult cuEventQuery ( CUevent hEvent )
-
Queries an event's status.
Parameters
- hEvent
- - Event to query
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_NOT_READY
Description
Queries the status of all work currently captured by hEvent. See cuEventRecord() for details on what is captured by an event.
Returns CUDA_SUCCESS if all captured work has been completed, or CUDA_ERROR_NOT_READY if any captured work is incomplete.
For the purposes of Unified Memory, a return value of CUDA_SUCCESS is equivalent to having called cuEventSynchronize().
Note:Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuEventCreate, cuEventRecord, cuEventSynchronize, cuEventDestroy, cuEventElapsedTime, cudaEventQuery
- CUresult cuEventRecord ( CUevent hEvent, CUstream hStream )
-
Records an event.
Parameters
- hEvent
- - Event to record
- hStream
- - Stream to record event for
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_INVALID_VALUE
Description
Captures in hEvent the contents of hStream at the time of this call. hEvent and hStream must be from the same context. Calls such as cuEventQuery() or cuStreamWaitEvent() will then examine or wait for completion of the work that was captured. Uses of hStream after this call do not modify hEvent. See note on default stream behavior for what is captured in the default case.
cuEventRecord() can be called multiple times on the same event and will overwrite the previously captured state. Other APIs such as cuStreamWaitEvent() use the most recently captured state at the time of the API call, and are not affected by later calls to cuEventRecord(). Before the first call to cuEventRecord(), an event represents an empty set of work, so for example cuEventQuery() would return CUDA_SUCCESS.
Note:-
This function uses standard default stream semantics.
-
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuEventCreate, cuEventQuery, cuEventSynchronize, cuStreamWaitEvent, cuEventDestroy, cuEventElapsedTime, cudaEventRecord, cuEventRecordWithFlags
- CUresult cuEventRecordWithFlags ( CUevent hEvent, CUstream hStream, unsigned int flags )
-
Records an event.
Parameters
- hEvent
- - Event to record
- hStream
- - Stream to record event for
- flags
- - See CUevent_capture_flags
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_INVALID_VALUE
Description
Captures in hEvent the contents of hStream at the time of this call. hEvent and hStream must be from the same context. Calls such as cuEventQuery() or cuStreamWaitEvent() will then examine or wait for completion of the work that was captured. Uses of hStream after this call do not modify hEvent. See note on default stream behavior for what is captured in the default case.
cuEventRecordWithFlags() can be called multiple times on the same event and will overwrite the previously captured state. Other APIs such as cuStreamWaitEvent() use the most recently captured state at the time of the API call, and are not affected by later calls to cuEventRecordWithFlags(). Before the first call to cuEventRecordWithFlags(), an event represents an empty set of work, so for example cuEventQuery() would return CUDA_SUCCESS.
flags include:
-
CU_EVENT_RECORD_DEFAULT: Default event creation flag.
-
CU_EVENT_RECORD_EXTERNAL: Event is captured in the graph as an external event node when performing stream capture. This flag is invalid outside of stream capture.
Note:-
This function uses standard default stream semantics.
-
Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuEventCreate, cuEventQuery, cuEventSynchronize, cuStreamWaitEvent, cuEventDestroy, cuEventElapsedTime, cuEventRecord, cudaEventRecord
- CUresult cuEventSynchronize ( CUevent hEvent )
-
Waits for an event to complete.
Parameters
- hEvent
- - Event to wait for
Returns
CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_HANDLE
Description
Waits until the completion of all work currently captured in hEvent. See cuEventRecord() for details on what is captured by an event.
Waiting for an event that was created with the CU_EVENT_BLOCKING_SYNC flag will cause the calling CPU thread to block until the event has been completed by the device. If the CU_EVENT_BLOCKING_SYNC flag has not been set, then the CPU thread will busy-wait until the event has been completed by the device.
Note:Note that this function may also return error codes from previous, asynchronous launches.
See also:
cuEventCreate, cuEventRecord, cuEventQuery, cuEventDestroy, cuEventElapsedTime, cudaEventSynchronize