CANN/runtime执行控制API

12. 执行控制

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

本章节描述 CANN Runtime 的执行控制接口，包括回调函数启动、Host 函数订阅、超时设置及异步 Reduce 操作。

• aclError aclrtLaunchCallback(aclrtCallback fn, void *userData, aclrtCallbackBlockType blockType, aclrtStream stream)：在Stream的任务队列中下发一个Host回调任务，系统内部在执行到该回调任务时，会在Stream上注册的线程（该线程由用户自行创建，并通过aclrtSubscribeReport接口注册）中执行回调函数。
• aclError aclrtSubscribeReport(uint64_t threadId, aclrtStream stream)：注册处理Stream上回调函数的线程。
• aclError aclrtProcessReport(int32_t timeout)：调用本接口设置超时时间，等待aclrtLaunchCallback接口下发的回调任务执行。
• aclError aclrtUnSubscribeReport(uint64_t threadId, aclrtStream stream)：取消线程注册，Stream上的回调函数不再由指定线程处理。
• aclError aclrtSubscribeHostFunc(uint64_t hostFuncThreadId, aclrtStream exeStream)：调用本接口注册处理Stream上回调函数的线程（线程需由用户自行创建）。
• aclError aclrtProcessHostFunc(int32_t timeout)：等待指定时间后，触发回调处理，由aclrtSubscribeHostFunc接口指定的线程处理回调。
• aclError aclrtUnSubscribeHostFunc(uint64_t hostFuncThreadId, aclrtStream exeStream)：与aclrtSubscribeHostFunc接口配合使用，调用模型执行接口后，调用本接口取消线程注册，Stream上的回调函数不再由指定线程处理。
• aclError aclrtGetOpTimeoutInterval(uint64_t *interval)：获取硬件支持的算子超时配置的最短时间间隔interval，单位为微秒。
• aclError aclrtSetOpExecuteTimeOut(uint32_t timeout)：设置算子执行的超时时间，单位为秒。一个进程内多次调用本接口，则以最后一次设置的时间为准。
• aclError aclrtSetOpExecuteTimeOutV2(uint64_t timeout, uint64_t *actualTimeout)：设置算子执行的超时时间，单位为微秒。
• aclError aclrtSetOpExecuteTimeOutWithMs(uint32_t timeout)：设置算子执行的超时时间，单位为毫秒。
• aclError aclrtGetOpExecuteTimeout(uint32_t *const timeoutMs)：获取AI Core算子执行的超时时间。
• aclError aclrtGetThreadLastTaskId(uint32_t *taskId)：获取当前线程的最后一个下发的Task ID。
• aclError aclrtReduceAsync(void *dst, const void *src, uint64_t count, aclrtReduceKind kind, aclDataType type, aclrtStream stream, void *reserve)：执行Reduce操作，包括SUM、MIN、MAX等。异步接口。
• aclError aclrtLaunchHostFunc(aclrtStream stream, aclrtHostFunc fn, void *args)：在Stream的任务队列中下发一个Host回调任务，系统内部在执行到该回调任务时，会在Stream上注册的线程（该线程在本接口内部创建并注册）中执行回调函数，并且回调任务默认阻塞本Stream上后续任务的执行。
• aclError aclrtRandomNumAsync(const aclrtRandomNumTaskInfo *taskInfo, const aclrtStream stream, void *reserve)：下发并执行随机数生成任务。异步接口。
• aclError aclrtTaskUpdateAsync(aclrtStream taskStream, uint32_t taskId, aclrtTaskUpdateInfo *info, aclrtStream execStream)：刷新目标任务的信息。异步接口。

aclrtLaunchCallback

aclError aclrtLaunchCallback(aclrtCallback fn, void *userData, aclrtCallbackBlockType blockType, aclrtStream stream)

产品支持情况

功能说明

在Stream的任务队列中下发一个Host回调任务，系统内部在执行到该回调任务时，会在Stream上注册的线程（该线程由用户自行创建，并通过aclrtSubscribeReport接口注册）中执行回调函数。异步接口。

本接口需与以下其它接口配合使用，以便实现异步场景下的callback功能：

1. 定义并实现回调函数，函数原型为：typedef void (*aclrtCallback)(void *userData)；
2. 新建线程，在线程函数内，调用aclrtProcessReport接口设置超时时间（需循环调用），等待回调任务执行；
3. 调用aclrtSubscribeReport接口建立第2步中的线程和Stream的绑定关系，该Stream下发的回调函数将在绑定的线程中执行；
4. 在指定Stream上执行异步任务（例如异步推理任务）；
5. 调用aclrtLaunchCallback接口在Stream的任务队列中下发回调任务，触发第2步中注册的线程处理回调函数，每调用一次aclrtLaunchCallback接口，就会触发一次回调函数的执行；
6. 异步任务全部执行完成后，取消线程注册（aclrtUnSubscribeReport接口）。

本接口可用于实现异步场景下的callback功能，与另一个实现异步场景下的callback功能接口aclrtLaunchHostFunc的差别在于：使用aclrtLaunchHostFunc接口时，会在Stream上注册的线程（该线程在本接口内部创建并注册）中执行回调函数，并且回调任务默认阻塞本Stream上后续任务的执行。

对于同一个Stream，两套实现异步场景下的callback功能的接口不能混用，否则可能出现异常。

参数说明

返回值说明

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

约束说明

回调函数涉及共享资源（例如锁），因此在使用回调函数需慎重，不应该调用资源申请、资源释放、Stream同步、Device同步、任务下发、任务终止等接口，否则可能导致错误或死锁。

aclrtSubscribeReport

aclError aclrtSubscribeReport(uint64_t threadId, aclrtStream stream)

产品支持情况

功能说明

注册处理Stream上回调函数的线程。

本接口需与以下其它接口配合使用，以便实现异步场景下的callback功能：

1. 定义并实现回调函数，函数原型为：typedef void (*aclrtCallback)(void *userData)；
2. 新建线程，在线程函数内，调用aclrtProcessReport接口设置超时时间（需循环调用），等待回调任务执行；
3. 调用aclrtSubscribeReport接口建立第2步中的线程和Stream的绑定关系，该Stream下发的回调函数将在绑定的线程中执行；
4. 在指定Stream上执行异步任务（例如异步推理任务）；
5. 调用aclrtLaunchCallback接口在Stream的任务队列中下发回调任务，触发第2步中注册的线程处理回调函数，每调用一次aclrtLaunchCallback接口，就会触发一次回调函数的执行；
6. 异步任务全部执行完成后，取消线程注册（aclrtUnSubscribeReport接口）。

参数说明

返回值说明

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

约束说明

支持多次调用aclrtSubscribeReport接口给多个Stream（仅支持同一Device内的多个Stream）注册同一个处理回调函数的线程；为确保Stream内的任务按调用顺序执行，不支持调用aclrtSubscribeReport接口给同一个Stream注册多个处理回调函数的线程；同一个进程内，在不同的Device上注册回调函数的线程时，不能指定同一个线程ID。

单进程内调用本接口注册的线程数量超过一定限制，则接口返回失败。考虑操作系统的线程切换性能开销，建议调用aclrtSubscribeReport接口注册的线程数量控制在32个以下（包括32）。各产品型号支持的线程数量最大值不同，如下表所示。

aclrtProcessReport

aclError aclrtProcessReport(int32_t timeout)

产品支持情况

功能说明

调用本接口设置超时时间，等待aclrtLaunchCallback接口下发的回调任务执行。

本接口需与以下其它接口配合使用，以便实现异步场景下的callback功能：

1. 定义并实现回调函数，函数原型为：typedef void (*aclrtCallback)(void *userData)；
2. 新建线程，在线程函数内，调用aclrtProcessReport接口设置超时时间（需循环调用），等待回调任务执行；
3. 调用aclrtSubscribeReport接口建立第2步中的线程和Stream的绑定关系，该Stream下发的回调函数将在绑定的线程中执行；
4. 在指定Stream上执行异步任务（例如异步推理任务）；
5. 调用aclrtLaunchCallback接口在Stream的任务队列中下发回调任务，触发第2步中注册的线程处理回调函数，每调用一次aclrtLaunchCallback接口，就会触发一次回调函数的执行；
6. 异步任务全部执行完成后，取消线程注册（aclrtUnSubscribeReport接口）。

参数说明

返回值说明

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

aclrtUnSubscribeReport

aclError aclrtUnSubscribeReport(uint64_t threadId, aclrtStream stream)

产品支持情况

功能说明

取消线程注册，Stream上的回调函数不再由指定线程处理。

本接口需与以下其它接口配合使用，以便实现异步场景下的callback功能：

1. 定义并实现回调函数，函数原型为：typedef void (*aclrtCallback)(void *userData)；
2. 新建线程，在线程函数内，调用aclrtProcessReport接口设置超时时间（需循环调用），等待回调任务执行；
3. 调用aclrtSubscribeReport接口建立第2步中的线程和Stream的绑定关系，该Stream下发的回调函数将在绑定的线程中执行；
4. 在指定Stream上执行异步任务（例如异步推理任务）；
5. 调用aclrtLaunchCallback接口在Stream的任务队列中下发回调任务，触发第2步中注册的线程处理回调函数，每调用一次aclrtLaunchCallback接口，就会触发一次回调函数的执行；
6. 异步任务全部执行完成后，取消线程注册（aclrtUnSubscribeReport接口）。

参数说明

返回值说明

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

aclrtSubscribeHostFunc

aclError aclrtSubscribeHostFunc(uint64_t hostFuncThreadId, aclrtStream exeStream)

产品支持情况

功能说明

调用本接口注册处理Stream上回调函数的线程（线程需由用户自行创建）。

参数说明

返回值说明

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

约束说明

• 支持多次调用aclrtSubscribeHostFunc接口给多个Stream（仅支持同一Device内的多个Stream）注册同一个处理回调函数的线程。
• 为确保Stream内的任务按调用顺序执行，不支持调用aclrtSubscribeHostFunc接口给同一个Stream注册多个处理回调函数的线程。

aclrtProcessHostFunc

aclError aclrtProcessHostFunc(int32_t timeout)

产品支持情况

功能说明

等待指定时间后，触发回调处理，由aclrtSubscribeHostFunc接口指定的线程处理回调。

线程需由用户提前自行创建，并自定义线程函数，在线程函数内调用本接口，等待指定时间后通过系统内部进行算子计算。

参数说明

返回值说明

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

aclrtUnSubscribeHostFunc

aclError aclrtUnSubscribeHostFunc(uint64_t hostFuncThreadId, aclrtStream exeStream)

产品支持情况

功能说明

与aclrtSubscribeHostFunc接口配合使用，调用模型执行接口后，调用本接口取消线程注册，Stream上的回调函数不再由指定线程处理。

参数说明

返回值说明

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

aclrtGetOpTimeoutInterval

aclError aclrtGetOpTimeoutInterval(uint64_t *interval)

功能说明

获取硬件支持的算子超时配置的最短时间间隔interval，单位为微秒。

参数说明

返回值说明

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

aclrtSetOpExecuteTimeOut

aclError aclrtSetOpExecuteTimeOut(uint32_t timeout)

产品支持情况

功能说明

设置算子执行的超时时间，单位为秒。一个进程内多次调用本接口，则以最后一次设置的时间为准。
如果算子下发时携带了超时时间，则该超时时间优先级高于本接口设置的超时时间。
对于以下产品型号，建议使用aclrtSetOpExecuteTimeOutV2接口，该接口会返回实际生效的超时时间：
Ascend 950PR/Ascend 950DT
Atlas A3 训练系列产品/Atlas A3 推理系列产品
Atlas A2 训练系列产品/Atlas A2 推理系列产品

参数说明

返回值说明

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

约束说明

不调用本接口，算子的默认超时时间如下表所示：

由于不同产品型号的架构差异，AI Core算子、AI CPU算子的最大超时时间有所不同：

aclrtSetOpExecuteTimeOutV2

aclError aclrtSetOpExecuteTimeOutV2(uint64_t timeout, uint64_t *actualTimeout)

产品支持情况

功能说明

设置算子执行的超时时间，单位为微秒。
如果算子下发时携带了超时时间，则该超时时间优先级高于本接口设置的超时时间。

参数说明

返回值说明

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

aclrtSetOpExecuteTimeOutWithMs

aclError aclrtSetOpExecuteTimeOutWithMs(uint32_t timeout)

产品支持情况

功能说明

设置算子执行的超时时间，单位为毫秒。

参数说明

返回值说明

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

aclrtGetOpExecuteTimeOut

aclError aclrtGetOpExecuteTimeout(uint32_t *const timeoutMs)

产品支持情况

功能说明

获取AI Core算子执行的超时时间。

参数说明

返回值说明

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

aclrtGetThreadLastTaskId

aclError aclrtGetThreadLastTaskId(uint32_t *taskId)

产品支持情况

功能说明

获取当前线程的最后一个下发的Task ID。

参数说明

返回值说明

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

aclrtReduceAsync

aclError aclrtReduceAsync(void *dst, const void *src, uint64_t count, aclrtReduceKind kind, aclDataType type, aclrtStream stream, void *reserve)

产品支持情况

功能说明

执行Reduce操作，包括SUM、MIN、MAX等。异步接口。

参数说明

返回值说明

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

约束说明

dts、src必须跟stream所在的Device是同一个设备。

aclrtLaunchHostFunc

aclError aclrtLaunchHostFunc(aclrtStream stream, aclrtHostFunc fn, void *args)

产品支持情况

功能说明

在Stream的任务队列中下发一个Host回调任务，系统内部在执行到该回调任务时，会在Stream上注册的线程（该线程在本接口内部创建并注册）中执行回调函数，并且回调任务默认阻塞本Stream上后续任务的执行。异步接口。

本接口可用于实现异步场景下的callback功能，与另一套实现异步场景下的callback功能接口（aclrtLaunchCallback、aclrtSubscribeReport、aclrtProcessReport、aclrtUnSubscribeReport）的差别在于：使用aclrtLaunchCallback等接口时，Stream上注册的线程需由用户自行创建并通过aclrtSubscribeReport接口注册，另外也可以指定回调任务是否阻塞本Stream上后续任务的执行。

对于同一个Stream，两套实现异步场景下的callback功能的接口不能混用，否则可能出现异常。

参数说明

返回值说明

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

约束说明

回调函数涉及共享资源（例如锁），因此在使用回调函数需慎重，不应该调用资源申请、资源释放、Stream同步、Device同步、任务下发、任务终止等接口，否则可能导致错误或死锁。

aclrtRandomNumAsync

aclError aclrtRandomNumAsync(const aclrtRandomNumTaskInfo *taskInfo, const aclrtStream stream, void *reserve)

产品支持情况

功能说明

下发并执行随机数生成任务。异步接口。

参数说明

返回值说明

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

aclrtTaskUpdateAsync

aclError aclrtTaskUpdateAsync(aclrtStream taskStream, uint32_t taskId, aclrtTaskUpdateInfo *info, aclrtStream execStream)

产品支持情况

功能说明

刷新目标任务的信息。异步接口。

参数说明

返回值说明

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

约束说明

Ascend 950PR/Ascend 950DT产品不支持更新ACL_RT_UPDATE_RANDOM_TASK(随机数生成任务)。

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