CUDA Driver API :: CUDA Toolkit Documentation

6.19. 事件管理

本节介绍底层CUDA驱动程序应用程序编程接口的事件管理功能。

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 cuEventElapsedTime_v2 ( 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 )

创建一个事件。

参数

phEvent: - Returns newly created event
Flags: - Event creation flags

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_OUT_OF_MEMORY

描述

为当前上下文创建一个事件*phEvent，并通过Flags指定标志。有效标志包括：

CU_EVENT_DEFAULT: 默认事件创建标志。
CU_EVENT_BLOCKING_SYNC: 指定创建的事件应使用阻塞同步。使用cuEventSynchronize()等待以此标志创建的事件的CPU线程将被阻塞，直到事件实际被记录完成。
CU_EVENT_DISABLE_TIMING: 指定创建的事件不需要记录计时数据。使用此标志创建且未指定CU_EVENT_BLOCKING_SYNC标志的事件，在与cuStreamWaitEvent()和cuEventQuery()一起使用时将提供最佳性能。
CU_EVENT_INTERPROCESS: 指定创建的事件可以通过cuIpcGetEventHandle()用作进程间事件。CU_EVENT_INTERPROCESS必须与CU_EVENT_DISABLE_TIMING一起指定。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。

另请参阅：

cuEventRecord, cuEventQuery, cuEventSynchronize, cuEventDestroy, cuEventElapsedTime, cudaEventCreate, cudaEventCreateWithFlags

CUresult cuEventDestroy ( CUevent hEvent )

销毁一个事件。

参数

hEvent: - Event to destroy

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_HANDLE

描述

销毁由hEvent指定的事件。

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

Note:

请注意，此函数也可能返回之前异步启动的错误代码。

另请参阅：

cuEventCreate, cuEventRecord, cuEventQuery, cuEventSynchronize, cuEventElapsedTime, cudaEventDestroy

CUresult cuEventElapsedTime ( float* pMilliseconds, CUevent hStart, CUevent hEnd )

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

参数

pMilliseconds: - Time between hStart and hEnd in ms
hStart: - Starting event
hEnd: - Ending event

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_NOT_READY, CUDA_ERROR_UNKNOWN

描述

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

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

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

请注意，此API有一个更新版本cuEventElapsedTime_v2。它将在CUDA 13.0中取代当前版本，当前版本保留是为了保持小版本兼容性。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。

另请参阅：

cuEventCreate, cuEventRecord, cuEventQuery, cuEventSynchronize, cuEventDestroy, cudaEventElapsedTime

CUresult cuEventElapsedTime_v2 ( float* pMilliseconds, CUevent hStart, CUevent hEnd )

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

参数

pMilliseconds: - Time between hStart and hEnd in ms
hStart: - Starting event
hEnd: - Ending event

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_NOT_READY, CUDA_ERROR_UNKNOWN

描述

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

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

Note:

请注意，此函数也可能返回之前异步启动的错误代码。

另请参阅：

cuEventCreate, cuEventRecord, cuEventQuery, cuEventSynchronize, cuEventDestroy, cudaEventElapsedTime

CUresult cuEventQuery ( CUevent hEvent )

查询事件的状态。

参数

hEvent: - Event to query

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_NOT_READY

描述

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

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

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

Note:

请注意，此函数也可能返回之前异步启动的错误代码。

另请参阅：

cuEventCreate, cuEventRecord, cuEventSynchronize, cuEventDestroy, cuEventElapsedTime, cudaEventQuery

CUresult cuEventRecord ( CUevent hEvent, CUstream hStream )

记录一个事件。

参数

hEvent: - Event to record
hStream: - Stream to record event for

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_INVALID_VALUE

描述

在此调用时捕获hStream的内容到hEvent中。hEvent和hStream必须来自相同的上下文，否则将返回CUDA_ERROR_INVALID_HANDLE。随后调用如cuEventQuery()或cuStreamWaitEvent()将检查或等待被捕获工作的完成。此调用后对hStream的使用不会修改hEvent。有关默认情况下捕获内容的说明，请参阅默认流行为的注释。

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

Note:

此函数使用标准的默认流语义。
请注意，此函数也可能返回之前异步启动的错误代码。

另请参阅：

cuEventCreate, cuEventQuery, cuEventSynchronize, cuStreamWaitEvent, cuEventDestroy, cuEventElapsedTime, cudaEventRecord, cuEventRecordWithFlags

CUresult cuEventRecordWithFlags ( CUevent hEvent, CUstream hStream, unsigned int flags )

记录一个事件。

参数

hEvent: - Event to record
hStream: - Stream to record event for
flags: - See CUevent_capture_flags

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_INVALID_VALUE

描述

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

标志包括：