CANN Runtime事件管理API参考

# 7. Event管理

【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime

本章节描述 CANN Runtime 的 Event 管理接口，用于事件的创建、记录、同步、计时及 IPC 跨进程共享。

• aclError aclrtCreateEvent(aclrtEvent *event)：创建Event，创建出来的Event可用于统计两个Event之间的耗时、多Stream之间的任务同步等场景。
• aclError aclrtCreateEventWithFlag(aclrtEvent *event, uint32_t flag)：创建带flag的Event，不同flag的Event用于不同的功能。支持创建Event时携带多个flag（按位进行或操作），从而同时使能对应flag的功能。
• aclError aclrtCreateEventExWithFlag(aclrtEvent *event, uint32_t flag)：创建带flag的Event，不同flag的Event用于不同的功能。
• aclError aclrtDestroyEvent(aclrtEvent event)：销毁Event，支持在Event未完成前调用本接口销毁Event。此时，本接口不会阻塞线程等Event完成，Event相关资源会在Event完成时被自动释放。
• aclError aclrtRecordEvent(aclrtEvent event, aclrtStream stream)：在指定Stream中记录一个Event。异步接口。
• aclError aclrtResetEvent(aclrtEvent event, aclrtStream stream)：复位Event，恢复Event初始状态，便于Event对象重复使用。异步接口。
• aclError aclrtQueryEvent(aclrtEvent event, aclrtEventStatus *status)：查询与本接口在同一线程中的aclrtRecordEvent接口所记录的Event是否执行完成。
• aclError aclrtQueryEventStatus(aclrtEvent event, aclrtEventRecordedStatus *status)：查询该Event捕获的所有任务的执行状态。具体见aclrtRecordEvent接口参考Event捕获的细节。
• aclError aclrtQueryEventWaitStatus(aclrtEvent event, aclrtEventWaitStatus *status)：调用aclrtStreamWaitEvent接口后查询该Event对应的等待任务是否都执行完成。
• aclError aclrtSynchronizeEvent(aclrtEvent event)：阻塞当前线程运行直到Event捕获的所有任务都执行完成。
• aclError aclrtSynchronizeEventWithTimeout(aclrtEvent event, int32_t timeout)：阻塞当前线程运行直到Event捕获的所有任务都执行完成（具体见aclrtRecordEvent接口参考Event捕获的细节），该接口是在接口aclrtSynchronizeEvent基础上进行了增强，支持用户设置永久等待、或配置具体的超时时间，若配置具体的超时时间，则当应用程序异常时可根据所设置的超时时间自行退出。
• aclError aclrtEventElapsedTime(float *ms, aclrtEvent startEvent, aclrtEvent endEvent)：统计两个Event之间的耗时。
• aclError aclrtStreamWaitEvent(aclrtStream stream, aclrtEvent event)：阻塞指定Stream的运行，直到指定的Event完成，支持多个Stream等待同一个Event的场景。异步接口。
• aclError aclrtStreamWaitEventWithTimeout(aclrtStream stream, aclrtEvent event, int32_t timeout)：获取算子二进制数据在Device上的内存地址及内存大小。
• aclError aclrtSetOpWaitTimeout(uint32_t timeout)：本接口用于设置等待Event完成的超时时间。
• aclError aclrtEventGetTimestamp(aclrtEvent event, uint64_t *timestamp)：获取Event的执行结束时间点（表示从AI处理器系统启动以来的时间）。
• aclError aclrtGetEventId(aclrtEvent event, uint32_t *eventId)：获取指定Event的ID。
• aclError aclrtGetEventAvailNum(uint32_t *eventCount)：查询当前Device上可用的Event数量。
• aclError aclrtIpcGetEventHandle(aclrtEvent event, aclrtIpcEventHandle *handle)：将本进程中的指定Event设置为IPC（Inter-Process Communication） Event，并返回其handle（即Event句柄），用于在跨进程场景下实现任务同步，支持同一个Device内的多个进程以及跨Device的多个进程。
• aclError aclrtIpcOpenEventHandle(aclrtIpcEventHandle handle, aclrtEvent *event)：在本进程中获取handle的信息，并返回本进程可以使用的Event指针。

aclrtCreateEvent

aclError aclrtCreateEvent(aclrtEvent *event)

产品支持情况

功能说明

创建Event，创建出来的Event可用于统计两个Event之间的耗时、多Stream之间的任务同步等场景。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

约束说明

采用本API创建的Event不支持在aclrtResetEvent接口中使用，否则会导致未定义的行为。

调用本接口创建Event时，并不会实际申请Event资源，只有在调用aclrtRecordEvent接口时，才会进行资源申请，因此在调用aclrtRecordEvent时，可能会出现线程阻塞，等待Event资源的释放。

不同型号的硬件支持的Event数量不同，如下表所示：

aclrtCreateEventWithFlag

aclError aclrtCreateEventWithFlag(aclrtEvent *event, uint32_t flag)

产品支持情况

功能说明

创建带flag的Event，不同flag的Event用于不同的功能。支持创建Event时携带多个flag（按位进行或操作），从而同时使能对应flag的功能。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

约束说明

调用本接口创建Event时，flag为bitmap，支持将flag设置为单个宏、或者对多个宏进行或操作。

若flag参数值不包含ACL_EVENT_SYNC宏，则不支持在以下API中使用本接口创建的Event：aclrtResetEvent、aclrtStreamWaitEvent、aclrtQueryEventWaitStatus。若flag参数值包含ACL_EVENT_SYNC宏或者flag设置为ACL_EVENT_EXTERNAL时，则创建出来的Event数量受限，具体如下：

aclrtCreateEventExWithFlag

aclError aclrtCreateEventExWithFlag(aclrtEvent *event, uint32_t flag)

产品支持情况

功能说明

创建带flag的Event，不同flag的Event用于不同的功能。支持创建Event时携带多个flag（按位进行或操作），从而同时使能对应flag的功能。创建Event时，Event资源不受硬件限制。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

约束说明

采用本API创建的Event，不支持在以下接口中使用：aclrtResetEvent、aclrtQueryEvent、aclrtQueryEventWaitStatus，否则返回报错。

调用本接口创建Event时，flag为bitmap，支持将flag设置为单个宏、或者对多个宏进行或操作。若flag参数值不包含ACL_EVENT_SYNC宏，则不支持在aclrtStreamWaitEvent接口中使用本接口创建的Event。若flag参数值包含ACL_EVENT_SYNC宏，并不会实际申请Event资源，只有在调用aclrtRecordEvent接口时，才会进行资源申请，因此在调用aclrtRecordEvent时，可能会出现线程阻塞，等待Event资源的释放。

不同型号的硬件支持的Event数量不同，如下表所示：

aclrtDestroyEvent

aclError aclrtDestroyEvent(aclrtEvent event)

产品支持情况

功能说明

销毁Event，支持在Event未完成前调用本接口销毁Event。此时，本接口不会阻塞线程等Event完成，Event相关资源会在Event完成时被自动释放。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

约束说明

在调用aclrtDestroyEvent接口销毁指定Event时，需确保其它接口没有正在使用该Event。

aclrtRecordEvent

aclError aclrtRecordEvent(aclrtEvent event, aclrtStream stream)

产品支持情况

功能说明

在指定Stream中记录一个Event。异步接口。

aclrtRecordEvent接口与aclrtStreamWaitEvent接口配合使用时，主要用于多Stream之间同步等待的场景。

调用aclrtRecordEvent接口时，会捕获当前Stream上已下发的任务，并记录到Event事件中，因此后续若调用aclrtQueryEventStatus或aclrtStreamWaitEvent接口时，会检查或等待该Event事件中所捕获的任务都已经完成。

另外，对于使用aclrtCreateEventExWithFlag创建的Event：

• aclrtRecordEvent接口支持对同一个Event多次record实现Event复用，每次Record会重新捕获当前Stream上已下发的任务，并覆盖保存到Event中。在调用aclrtStreamWaitEvent接口时，会使用最近一次Event中所保存的任务，且不会被后续的aclrtRecordEvent调用影响。
• 在首次调用aclrtRecordEvent接口前，由于Event中没有任务，因此调用aclrtQueryEventStatus接口时会返回ACL_EVENT_RECORDED_STATUS_COMPLETE。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

aclrtResetEvent

aclError aclrtResetEvent(aclrtEvent event, aclrtStream stream)

产品支持情况

功能说明

复位Event，恢复Event初始状态，便于Event对象重复使用。异步接口。

对于多个Stream间任务同步的场景，通常在调用aclrtStreamWaitEvent接口之后再复位Event。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

约束说明

仅支持复位由aclrtCreateEventWithFlag接口创建的、带有ACL_EVENT_SYNC标志的Event。

注意，在多个Stream中的任务需要等待同一个Event的情况下，不建议使用调用此接口来复位Event。如图所示，如果在stream2中的aclrtStreamWaitEvent接口之后调用aclrtResetEvent接口，Event将被复位，这会导致stream3中的aclrtStreamWaitEvent接口无法成功。

aclrtQueryEvent（废弃）

aclError aclrtQueryEvent(aclrtEvent event, aclrtEventStatus *status)

须知：此接口后续版本会废弃，请使用aclrtQueryEventStatus接口。

产品支持情况

功能说明

查询与本接口在同一线程中的aclrtRecordEvent接口所记录的Event是否执行完成。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

aclrtQueryEventStatus

aclError aclrtQueryEventStatus(aclrtEvent event, aclrtEventRecordedStatus *status)

产品支持情况

功能说明

查询该Event捕获的所有任务的执行状态。具体见aclrtRecordEvent接口参考Event捕获的细节。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

约束说明

如果用户在不同线程上分别调用aclrtRecordEvent和aclrtQueryEventStatus，可能由于多线程导致这两个API的执行时间乱序，进而导致查询到的Event对象的完成状态不符合预期。

aclrtQueryEventWaitStatus

aclError aclrtQueryEventWaitStatus(aclrtEvent event, aclrtEventWaitStatus *status)

产品支持情况

功能说明

调用aclrtStreamWaitEvent接口后查询该Event对应的等待任务是否都执行完成。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

约束说明

通过aclrtCreateEventExWithFlag接口创建的Event，不支持调用本接口。

aclrtSynchronizeEvent

aclError aclrtSynchronizeEvent(aclrtEvent event)

产品支持情况

功能说明

阻塞当前线程运行直到Event捕获的所有任务都执行完成。具体见aclrtRecordEvent接口参考Event捕获的细节。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

aclrtSynchronizeEventWithTimeout

aclError aclrtSynchronizeEventWithTimeout(aclrtEvent event, int32_t timeout)

产品支持情况

功能说明

阻塞当前线程运行直到Event捕获的所有任务都执行完成（具体见aclrtRecordEvent接口参考Event捕获的细节），该接口是在接口aclrtSynchronizeEvent基础上进行了增强，支持用户设置永久等待、或配置具体的超时时间，若配置具体的超时时间，则当应用程序异常时可根据所设置的超时时间自行退出。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

aclrtEventElapsedTime

aclError aclrtEventElapsedTime(float *ms, aclrtEvent startEvent, aclrtEvent endEvent)

产品支持情况

功能说明

统计两个Event之间的耗时。

本接口需与其它关键接口配合使用，接口调用顺序：调用aclrtCreateEvent/aclrtCreateEventWithFlag接口创建Event**-->调用aclrtRecordEvent接口在同一个Stream中记录起始Event、结尾Event-->调用aclrtSynchronizeStream接口阻塞应用程序运行，直到指定Stream中的所有任务都完成-->**调用aclrtEventElapsedTime接口统计两个Event之间的耗时

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

aclrtStreamWaitEvent

aclError aclrtStreamWaitEvent(aclrtStream stream, aclrtEvent event)

产品支持情况

功能说明

阻塞指定Stream的运行，直到指定的Event完成，支持多个Stream等待同一个Event的场景。异步接口。

提交到Stream上的所有后续任务都需要等待Event捕获的任务都完成后才能开始执行。具体见aclrtRecordEvent接口了解Event捕获的细节。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

约束说明

一个进程内，调用aclInit接口初始化后，若再调用aclrtSetOpWaitTimeout接口设置超时时间，那么本进程内后续调用aclrtStreamWaitEvent接口下发的任务支持在所设置的超时时间内等待，若等待的时间超过所设置的超时时间，则在调用同步等待接口（例如，aclrtSynchronizeStream）后，会返回报错。

aclrtStreamWaitEventWithTimeout

aclError aclrtStreamWaitEventWithTimeout(aclrtStream stream, aclrtEvent event, int32_t timeout)

产品支持情况

功能说明

获取算子二进制数据在Device上的内存地址及内存大小。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

aclrtSetOpWaitTimeout

aclError aclrtSetOpWaitTimeout(uint32_t timeout)

产品支持情况

功能说明

本接口用于设置等待Event完成的超时时间。

不调用本接口，则默认不超时；一个进程内多次调用本接口，则以最后一次设置的时间为准。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

约束说明

一个进程内，调用aclInit接口初始化后，若再调用aclrtSetOpWaitTimeout接口设置超时时间，那么本进程内后续调用aclrtStreamWaitEvent接口下发的任务支持在所设置的超时时间内等待，若等待的时间超过所设置的超时时间，则在调用同步等待接口（例如，aclrtSynchronizeStream）后，会返回报错。

aclrtEventGetTimestamp

aclError aclrtEventGetTimestamp(aclrtEvent event, uint64_t *timestamp)

产品支持情况

功能说明

获取Event的执行结束时间点（表示从AI处理器系统启动以来的时间）。

本接口需与其它关键接口配合使用，接口调用顺序：调用aclrtCreateEvent/aclrtCreateEventWithFlag接口创建Event**-->调用aclrtRecordEvent接口在Stream中记录Event>调用aclrtSynchronizeStream接口阻塞应用程序运行，直到指定Stream中的所有任务都完成-->**调用aclrtEventGetTimestamp接口获取Event的执行时间。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

aclrtGetEventId

aclError aclrtGetEventId(aclrtEvent event, uint32_t *eventId)

产品支持情况

功能说明

获取指定Event的ID。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

aclrtGetEventAvailNum

aclError aclrtGetEventAvailNum(uint32_t *eventCount)

产品支持情况

功能说明

查询当前Device上可用的Event数量。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

aclrtIpcGetEventHandle

aclError aclrtIpcGetEventHandle(aclrtEvent event, aclrtIpcEventHandle *handle)

产品支持情况

功能说明

将本进程中的指定Event设置为IPC（Inter-Process Communication） Event，并返回其handle（即Event句柄），用于在跨进程场景下实现任务同步，支持同一个Device内的多个进程以及跨Device的多个进程。

本接口需与以下其它关键接口配合使用，此处以A进程、B进程为例：

1. A进程中：

   1. 调用aclrtCreateEventExWithFlag接口创建flag为ACL_EVENT_IPC的Event。
   2. 调用aclrtIpcGetEventHandle接口获取用于进程间通信的Event句柄。
   3. 调用aclrtRecordEvent接口在Stream中插入1.a中创建的Event。

2. B进程中：

   1. 调用aclrtIpcOpenEventHandle接口获取A进程中的Event句柄信息，并返回本进程可以使用的Event指针。
   2. 调用aclrtStreamWaitEvent接口阻塞指定Stream的运行，直到指定的Event完成。
   3. Event使用完成后，调用aclrtDestroyEvent接口销毁Event。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

aclError aclrtIpcOpenEventHandle(aclrtIpcEventHandle handle, aclrtEvent *event)