CUDA Runtime API :: CUDA Toolkit Documentation

6.6. 事件管理

本节介绍CUDA运行时应用程序编程接口的事件管理功能。

Functions

__host__ cudaError_t cudaEventCreate ( cudaEvent_t* event ): Creates an event object.
__host__ __device__ cudaError_t cudaEventCreateWithFlags ( cudaEvent_t* event, unsigned int flags ): Creates an event object with the specified flags.
__host__ __device__ cudaError_t cudaEventDestroy ( cudaEvent_t event ): Destroys an event object.
__host__ cudaError_t cudaEventElapsedTime ( float* ms, cudaEvent_t start, cudaEvent_t end ): Computes the elapsed time between events.
__host__ cudaError_t cudaEventElapsedTime_v2 ( float* ms, cudaEvent_t start, cudaEvent_t end ): Computes the elapsed time between events.
__host__ cudaError_t cudaEventQuery ( cudaEvent_t event ): Queries an event's status.
__host__ __device__ cudaError_t cudaEventRecord ( cudaEvent_t event, cudaStream_t stream = 0 ): Records an event.
__host__ cudaError_t cudaEventRecordWithFlags ( cudaEvent_t event, cudaStream_t stream = 0, unsigned int flags = 0 ): Records an event.
__host__ cudaError_t cudaEventSynchronize ( cudaEvent_t event ): Waits for an event to complete.

Functions

__host__ cudaError_t cudaEventCreate ( cudaEvent_t* event )

创建一个事件对象。

参数

event: - Newly created event

cudaSuccess, cudaErrorInvalidValue, cudaErrorLaunchFailure, cudaErrorMemoryAllocation

描述

使用cudaEventDefault为当前设备创建一个事件对象。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaEventCreate ( C++ API), cudaEventCreateWithFlags, cudaEventRecord, cudaEventQuery, cudaEventSynchronize, cudaEventDestroy, cudaEventElapsedTime, cudaStreamWaitEvent, cuEventCreate

__host__ __device__ cudaError_t cudaEventCreateWithFlags ( cudaEvent_t* event, unsigned int flags )

创建一个具有指定标志的事件对象。

参数

event: - Newly created event
flags: - Flags for new event

cudaSuccess, cudaErrorInvalidValue, cudaErrorLaunchFailure, cudaErrorMemoryAllocation

描述

为当前设备创建一个具有指定标志的事件对象。有效标志包括：

cudaEventDefault: 默认事件创建标志。
cudaEventBlockingSync: 指定事件应使用阻塞同步方式。使用cudaEventSynchronize()等待以此标志创建的事件的宿主线程将被阻塞，直到事件实际完成。
cudaEventDisableTiming: 指定创建的事件不需要记录计时数据。使用此标志创建的事件（且未指定cudaEventBlockingSync标志）在与cudaStreamWaitEvent()和cudaEventQuery()一起使用时将提供最佳性能。
cudaEventInterprocess: 指定创建的事件可以通过cudaIpcGetEventHandle()用作进程间事件。cudaEventInterprocess必须与cudaEventDisableTiming同时指定。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaEventCreate ( C API), cudaEventSynchronize, cudaEventDestroy, cudaEventElapsedTime, cudaStreamWaitEvent, cuEventCreate

__host__ __device__ cudaError_t cudaEventDestroy ( cudaEvent_t event )

销毁一个事件对象。

参数

event: - Event to destroy

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle, cudaErrorLaunchFailure

描述

销毁由event指定的事件。

一个事件可能在完成之前被销毁（即当cudaEventQuery()返回cudaErrorNotReady时）。在这种情况下，调用不会阻塞等待事件完成，任何相关资源将在完成时自动异步释放。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。
在此调用后使用该句柄属于未定义行为。
如果传入NULL作为输入事件，则返回cudaErrorInvalidResourceHandle。

另请参阅：

cudaEventCreate ( C API), cudaEventCreateWithFlags, cudaEventQuery, cudaEventSynchronize, cudaEventRecord, cudaEventElapsedTime, cuEventDestroy

__host__ cudaError_t cudaEventElapsedTime ( float* ms, cudaEvent_t start, cudaEvent_t end )

计算事件之间的经过时间。

参数

ms: - Time between start and end in ms
start: - Starting event
end: - Ending event

cudaSuccess, cudaErrorNotReady, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle, cudaErrorLaunchFailure, cudaErrorUnknown

描述

计算两个事件之间经过的时间（以毫秒为单位，分辨率约为0.5微秒）。

如果任一事件最后记录在非NULL流中，测得的时间可能比预期更长（即使两者使用了相同的流句柄）。这是因为cudaEventRecord()操作是异步执行的，无法保证测量的延迟实际上仅发生在两个事件之间。在两个被测量事件之间可能执行任意数量的其他不同流操作，从而显著改变计时结果。

如果未在任一事件上调用cudaEventRecord()，则将返回cudaErrorInvalidResourceHandle。如果在两个事件上都调用了cudaEventRecord()，但其中一个或两个尚未完成（即cudaEventQuery()会在至少一个事件上返回cudaErrorNotReady），则返回cudaErrorNotReady。如果任一事件是使用cudaEventDisableTiming标志创建的，则此函数将返回cudaErrorInvalidResourceHandle。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。
当传入NULL作为输入事件时，返回cudaErrorInvalidResourceHandle。

另请参阅：

cudaEventCreate ( C API), cudaEventCreateWithFlags, cudaEventQuery, cudaEventSynchronize, cudaEventDestroy, cudaEventRecord, cuEventElapsedTime

__host__ cudaError_t cudaEventElapsedTime_v2 ( float* ms, cudaEvent_t start, cudaEvent_t end )

计算事件之间的经过时间。

参数

ms: - Time between start and end in ms
start: - Starting event
end: - Ending event

cudaSuccess, cudaErrorNotReady, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle, cudaErrorLaunchFailure, cudaErrorUnknown

描述

计算两个事件之间的经过时间（以毫秒为单位，分辨率约为0.5微秒）。请注意此API不保证返回待处理工作的最新错误。因此该API仅用于计算经过时间，而应使用cudaEventQuery来轮询待比较事件的完成状态。

如果未在任一事件上调用cudaEventRecord()，则将返回cudaErrorInvalidResourceHandle。如果在两个事件上都调用了cudaEventRecord()，但其中一个或两个尚未完成（即cudaEventQuery()在至少一个事件上将返回cudaErrorNotReady），则返回cudaErrorNotReady。如果任一事件是使用cudaEventDisableTiming标志创建的，则此函数将返回cudaErrorInvalidResourceHandle。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。
当传入NULL作为输入事件时，返回cudaErrorInvalidResourceHandle。

另请参阅：

cudaEventCreate ( C API), cudaEventCreateWithFlags, cudaEventQuery, cudaEventSynchronize, cudaEventDestroy, cudaEventRecord, cuEventElapsedTime

__host__ cudaError_t cudaEventQuery ( cudaEvent_t event )

查询事件的状态。

参数

event: - Event to query

cudaSuccess, cudaErrorNotReady, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle, cudaErrorLaunchFailure

描述

查询当前由event捕获的所有工作状态。有关事件捕获内容的详细信息，请参阅cudaEventRecord()。

如果所有捕获的工作已完成，则返回cudaSuccess；如果任何捕获的工作未完成，则返回cudaErrorNotReady。

就统一内存管理而言，返回值cudaSuccess等同于调用了cudaEventSynchronize()函数。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。
当传入NULL作为输入事件时，返回cudaErrorInvalidResourceHandle。

另请参阅：

cudaEventCreate ( C API), cudaEventCreateWithFlags, cudaEventRecord, cudaEventSynchronize, cudaEventDestroy, cudaEventElapsedTime, cuEventQuery

__host__ __device__ cudaError_t cudaEventRecord ( cudaEvent_t event, cudaStream_t stream = 0 )

记录一个事件。

参数

event: - Event to record
stream: - Stream in which to record event

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle, cudaErrorLaunchFailure

描述

在本次调用时，将stream的内容捕获到event中。event和stream必须位于同一个CUDA上下文中。随后调用如cudaEventQuery()或cudaStreamWaitEvent()等函数将会检查或等待被捕获工作的完成。在此调用之后对stream的使用不会修改event。关于默认情况下捕获内容的说明，请参阅默认流行为的注释。

cudaEventRecord()可以在同一个事件上多次调用，并将覆盖之前捕获的状态。其他API如cudaStreamWaitEvent()会使用API调用时最近捕获的状态，不受后续cudaEventRecord()调用的影响。在首次调用cudaEventRecord()之前，事件表示一个空的工作集，因此例如cudaEventQuery()将返回cudaSuccess。

Note:

此函数使用标准的默认流语义。
请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。
当传入NULL作为输入事件时，返回cudaErrorInvalidResourceHandle。

另请参阅：

cudaEventCreate ( C API), cudaEventCreateWithFlags, cudaEventQuery, cudaEventSynchronize, cudaEventDestroy, cudaEventElapsedTime, cudaStreamWaitEvent, cudaEventRecordWithFlags, cuEventRecord

__host__ cudaError_t cudaEventRecordWithFlags ( cudaEvent_t event, cudaStream_t stream = 0, unsigned int flags = 0 )

记录一个事件。

参数

event: - Event to record
stream: - Stream in which to record event
flags: - Parameters for the operation(See above)

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle, cudaErrorLaunchFailure

描述

在本次调用时捕获stream的内容到event中。event和stream必须位于同一个CUDA上下文。后续调用如cudaEventQuery()或cudaStreamWaitEvent()将会检查或等待被捕获工作的完成。在此调用后对stream的使用不会修改event。关于默认情况下捕获内容的说明，请参阅默认流行为的注释。

cudaEventRecordWithFlags()可以在同一个事件上多次调用，并将覆盖之前捕获的状态。其他API如cudaStreamWaitEvent()会使用API调用时最近捕获的状态，不会受到后续调用cudaEventRecordWithFlags()的影响。在首次调用cudaEventRecordWithFlags()之前，事件表示一个空的工作集，因此例如cudaEventQuery()将返回cudaSuccess。

标志包括：

cudaEventRecordDefault: 默认事件创建标志。
cudaEventRecordExternal: 在执行流捕获时，事件在图中被捕获为外部事件节点。

Note:

此函数使用标准的默认流语义。
请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。
当传入NULL作为输入事件时，返回cudaErrorInvalidResourceHandle。

另请参阅：

cudaEventCreate ( C API), cudaEventCreateWithFlags, cudaEventQuery, cudaEventSynchronize, cudaEventDestroy, cudaEventElapsedTime, cudaStreamWaitEvent, cudaEventRecord, cuEventRecord,

__host__ cudaError_t cudaEventSynchronize ( cudaEvent_t event )

等待事件完成。

参数

event: - Event to wait for

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle, cudaErrorLaunchFailure

描述

等待直到event中当前捕获的所有工作完成。关于事件捕获内容的详细信息，请参阅cudaEventRecord()。

等待一个使用cudaEventBlockingSync标志创建的事件会导致调用CPU线程阻塞，直到设备完成该事件。如果未设置cudaEventBlockingSync标志，则CPU线程将忙等待，直到设备完成该事件。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。
当传入NULL作为输入事件时，返回cudaErrorInvalidResourceHandle。

另请参阅：

cudaEventCreate ( C API), cudaEventCreateWithFlags, cudaEventRecord, cudaEventQuery, cudaEventDestroy, cudaEventElapsedTime, cuEventSynchronize