CANN Runtime 配置化 Stream 创建与属性查询实战:基于 `aclrtCreateStreamWithConfig` 与 ID/Flag/Priority 查询接口
CANN Runtime 配置化 Stream 创建与属性查询实战:基于 aclrtCreateStreamWithConfig 与 ID/Flag/Priority 查询接口
本篇文章以 CANN Runtime 开源仓库中的 3_stream_config_query 样例 为主线,系统讲解如何在单 Device 场景下使用 aclrtCreateStreamWithConfig 接口按指定的 Priority(优先级)与 Flag(标志)创建 Stream,并通过 aclrtStreamGetId、aclrtStreamGetFlags、aclrtStreamGetPriority 三个查询接口回读 Stream 的属性。读者学完后,将掌握配置化 Stream 创建、属性查询、同步销毁的完整调用链,并能结合源码理解 Flag 各取值对 Stream 运行行为的影响。
一、样例定位:为什么需要"配置化"创建 Stream
在 CANN Runtime 的 Stream 管理体系中,Stream 是任务下发与执行的核心载体。常规的 aclrtCreateStream 接口只负责创建一个"默认属性"的 Stream;而 aclrtCreateStreamWithConfig 接口则允许开发者在创建时直接注入优先级(priority)与功能标志(flag),从而定制 Stream 的行为特性,例如:
- 提升任务下发速度(
ACL_STREAM_FAST_LAUNCH); - 缩短同步等待时间(
ACL_STREAM_FAST_SYNC); - 用于模型绑定与模型构建场景(
ACL_STREAM_PERSISTENT)等。
根据官方接口文档 06_stream_management.md 的说明,相比 aclrtCreateStream,使用 aclrtCreateStreamWithConfig 可以创建一个快速下发任务的 Stream,但会增加内存消耗或 CPU 的性能消耗——这是"创建一次、使用多次"场景下以资源换性能的经典取舍。
本样例(main.cpp)正是这一能力的最小可运行演示:它在单个 Device 上创建带指定 Priority 和 Flag 的 Stream,随后查询并校验 Stream 的 ID、Flag、Priority,最后同步并销毁。它同时被收录于 stream 目录样例列表 中,与 0_simple_stream(基础创建)、1_stream_with_failure_mode(失败模式)、2_multi_stream(多流协同)、4_stream_resource_budget(资源预算)互为补充,构成完整的 Stream 主题矩阵。
二、产品支持情况
根据样例 README 及接口文档中的产品支持标注,aclrtCreateStreamWithConfig 及本样例涉及的全部查询接口(aclrtStreamGetId、aclrtStreamGetFlags、aclrtStreamGetPriority)在以下产品上支持运行:
| 产品 | 是否支持 |
|---|---|
| Ascend 950PR/Ascend 950DT | √ |
| Atlas A3 训练系列产品/Atlas A3 推理系列产品 | √ |
| Atlas A2 训练系列产品/Atlas A2 推理系列产品 | √ |
需要说明的是,接口文档(06_stream_management.md)显示这些接口在更广的产品范围内受支持(如 Atlas 200I/500 A2 推理产品、Atlas 推理系列产品、Atlas 训练系列产品),而本样例 README 仅声明了上述三类产品,实际部署时请以你当前 CANN 版本对应产品的支持矩阵为准。另外,个别 Flag 也有产品型号限制,例如 ACL_STREAM_DEVICE_USE_ONLY 仅支持 Ascend 950PR/Ascend 950DT、Atlas A3 系列、Atlas A2 系列及 Atlas 推理系列产品。
三、编译与运行
3.1 环境准备
样例要求运行环境已安装 CANN 软件包,并已配置环境变量。推荐按以下步骤操作:
# 1. 切换到样例目录(git_clone_path 为仓库克隆根目录)
cd ${git_clone_path}/example/1_basic_features/stream/3_stream_config_query
# 2. 设置 CANN 环境变量
# ${install_root} 替换为 CANN 安装根目录,默认安装在 /usr/local/Ascend 目录
source ${install_root}/cann/set_env.sh
从 run.sh 源码可见,脚本会优先读取 ASCEND_HOME_PATH 环境变量,若未设置则直接报错退出:
_ASCEND_CANN_PATH="${ASCEND_HOME_PATH:-}"
if [[ -z "${_ASCEND_CANN_PATH}" ]]; then
echo "[ERROR]: ASCEND_HOME_PATH is not set."
echo "[ERROR]: Please source CANN set_env.sh before running this sample."
exit 1
fi
因此,务必先执行 source ${install_root}/cann/set_env.sh,确保 ASCEND_HOME_PATH 已指向 CANN 安装目录(同时脚本还会校验 ${_ASCEND_CANN_PATH}/bin/setenv.bash 是否存在)。
3.2 编译与运行
bash run.sh
run.sh 内部完整执行了"清理 → CMake 配置 → 编译 → 运行 → 结果校验"全流程:
rm -rf build
cmake -B build \
-DASCEND_CANN_PACKAGE_PATH="${_ASCEND_CANN_PATH}"
cmake --build build -j
file_path=output_msg.txt
if ! ./build/main | tee "${file_path}"; then
echo "[FAILURE] Stream config query sample failed."
exit 1
fi
if grep -q "\[SUCCESS\] Stream config query sample completed successfully" "${file_path}"; then
echo "[SUCCESS] Stream config query sample executed successfully."
else
echo "[FAILURE] Stream config query sample did not print the expected success marker."
exit 1
fi
注意其中的两个细节:
- CMake 传参:通过
-DASCEND_CANN_PACKAGE_PATH指定 CANN 包路径,供 CMakeLists.txt 使用——它将该路径下的include目录加入头文件搜索路径,将lib64目录加入链接搜索路径,并最终链接${ASCEND_CANN_PACKAGE_PATH}/lib64/libacl_rt.so动态库。 - 自动化结果校验:程序运行输出同时写入
output_msg.txt(通过tee),随后脚本用grep检查是否包含[SUCCESS] Stream config query sample completed successfully这一成功标志,据此决定脚本整体成败。这意味着样例自带"自验证"能力,非常适合集成进 CI 流水线。
如果不想使用脚本,也可以手动执行:
cmake -B build -DASCEND_CANN_PACKAGE_PATH=${install_root}/cann
cmake --build build -j
./build/main
四、核心 CANN Runtime API 全解析
本样例涉及的接口可按功能分为三类(详见 06_stream_management.md):
4.1 初始化与 Device 管理
| 接口 | 作用 |
|---|---|
aclInit |
完成 ACL 初始化,样例中传入 nullptr 使用默认配置 |
aclrtSetDevice |
指定用于运算的 Device(样例使用 Device 0) |
aclrtResetDeviceForce |
复位当前 Device,强制回收该 Device 上的资源 |
aclFinalize |
完成 ACL 去初始化,释放全局资源 |
4.2 Stream 配置与创建:aclrtCreateStreamWithConfig
aclError aclrtCreateStreamWithConfig(aclrtStream *stream, uint32_t priority, uint32_t flag)
接口原型与参数说明(来自 acl_rt.h 及接口文档):
| 参数 | 输入/输出 | 说明 |
|---|---|---|
| stream | 输出 | 创建出的 Stream 的指针 |
| priority | 输入 | 优先级,取值范围 0~7(见 acl_rt.h 注释),数字越小优先级越高 |
| flag | 输入 | Stream 的功能标志。既支持配置单个宏,也支持多个宏按位或(bitwise OR);对于不支持位或的宏,接口会返回报错。配置其他值创建出的 Stream 等同于通过 aclrtCreateStream 创建 |
flag 支持的全部宏定义位于 acl_rt.h,其取值与业务语义整理如下:
| 宏 | 值 | 语义 | 注意事项 |
|---|---|---|---|
ACL_STREAM_FAST_LAUNCH |
0x00000001U |
下发任务速度更快 | 创建时预申请系统内部资源,创建耗时增加、内存消耗增加,但下发任务耗时缩短;适合"创建一次、使用多次"场景 |
ACL_STREAM_FAST_SYNC |
0x00000002U |
调用 aclrtSynchronizeStream 时主动查询任务状态,任务完成立即返回 |
免去被动等待通知,总时长缩短,但主动查询增加 CPU 消耗 |
ACL_STREAM_PERSISTENT |
0x00000004U |
任务不立即执行、执行完也不立即销毁,销毁 Stream 时才释放任务资源 | 用于模型绑定场景,配合 aclmdlRIBindStream 使用 |
ACL_STREAM_HUGE |
0x00000008U |
Stream 可容纳的最大 Task 数量更大 | 当前版本(对应接口文档标注的产品范围)设置该 flag 不生效 |
ACL_STREAM_CPU_SCHEDULE |
0x00000010U |
用于队列方式模型推理场景下承载 AI CPU 调度的相关任务 | 预留功能 |
ACL_STREAM_DEVICE_USE_ONLY |
0x00000020U |
表示该 Stream 仅在 Device 上调用 | 仅 Ascend 950PR/Ascend 950DT、Atlas A3 系列、Atlas A2 系列及 Atlas 推理系列产品支持 |
多个 Flag 可按位或组合,例如同时开启快速下发与快速同步可传入
ACL_STREAM_FAST_LAUNCH | ACL_STREAM_FAST_SYNC(0x03U)。查询时aclrtStreamGetFlags返回的也正是各 flag 按位或后的结果。
4.3 Stream 查询与同步
| 接口 | 原型 | 关键说明 |
|---|---|---|
aclrtStreamGetId |
aclError aclrtStreamGetId(aclrtStream stream, int32_t *streamId) |
获取指定 Stream 的 ID;传入 NULL 时获取默认 Stream 的 ID |
aclrtStreamGetFlags |
aclError aclrtStreamGetFlags(aclrtStream stream, uint32_t *flags) |
查询创建 Stream 时设置的 flag;多 flag 返回按位或结果,未配置则返回 0;默认 Stream 的 flag 值因产品型号而异,应以本接口查询到的值为准 |
aclrtStreamGetPriority |
aclError aclrtStreamGetPriority(aclrtStream stream, uint32_t *priority) |
查询 Stream 优先级,数字越小优先级越高 |
aclrtSynchronizeStream |
aclError aclrtSynchronizeStream(aclrtStream stream) |
阻塞 Host 侧当前线程,直到指定 Stream 上的所有任务完成 |
aclrtDestroyStream |
aclError aclrtDestroyStream(aclrtStream stream) |
销毁 Stream;若有未完成任务会等待完成后再销毁;销毁前应保证 Stream 在当前 Context 下 |
接口文档特别提示:aclrtDestroyStream 销毁前建议先调用 aclrtSynchronizeStream 确保任务全部完成(见 06_stream_management.md 约束说明),本样例正是遵循了这一顺序。
五、源码逐步拆解:从创建到查询的完整链路
main.cpp 全文件不足 150 行,却完整展示了"初始化 → 创建 → 查询 → 校验 → 同步 → 销毁 → 去初始化"的规范流程,可作为业务代码的模板。
5.1 常量与错误处理封装
constexpr int32_t kDeviceId = 0; // 使用 Device 0
constexpr uint32_t kStreamFlags = 0; // 创建时使用的 Flag
constexpr uint32_t kStreamPriority = 0; // 创建时使用的优先级
int CheckAcl(aclError ret, const char* expr)
{
if (ret != ACL_SUCCESS) {
fprintf(stderr, "[ERROR] Operation failed: %s returned error code %d\n", expr, static_cast<int32_t>(ret));
fflush(stderr);
return -1;
}
return 0;
}
CheckAcl 对每个 ACL 接口的返回值做统一检查,失败时打印接口名与错误码并返回 -1。日志宏(INFO_LOG、ERROR_LOG 等)来自仓库公共工具头文件 example/utils.h,输出格式统一为 [INFO]/[ERROR] 前缀,方便脚本解析。
5.2 用 RAII 守卫 Stream 生命周期
样例定义了 StreamGuard 类,将 aclrtDestroyStream 的调用封装进析构函数,实现"离开作用域自动销毁",避免异常路径下的资源泄漏:
class StreamGuard {
public:
explicit StreamGuard(aclrtStream stream) : stream_(stream) {}
~StreamGuard()
{
if (stream_ != nullptr) {
CHECK_ERROR_WITHOUT_RETURN(aclrtDestroyStream(stream_));
}
}
// 拷贝构造与赋值被 delete,禁止拷贝
aclError Destroy() { /* 显式销毁并将 stream_ 置空 */ }
private:
aclrtStream stream_;
};
这是典型的 RAII(Resource Acquisition Is Initialization)写法:StreamGuard streamGuard(stream); 创建守卫对象,函数末尾无论走正常返回还是提前 return -1,析构函数都会兜底销毁 Stream。Destroy() 方法则提供显式销毁入口,以便在正常路径中主动控制销毁时机并检查返回值。
5.3 配置化创建与属性查询
核心业务函数 RunStreamConfigQuerySample 完整实现了样例主线:
aclrtStream stream = nullptr;
// 1. 以指定的 priority 和 flag 创建 Stream
if (CheckAcl(aclrtCreateStreamWithConfig(&stream, kStreamPriority, kStreamFlags),
"aclrtCreateStreamWithConfig") != 0) {
return -1;
}
StreamGuard streamGuard(stream);
INFO_LOG("Create stream with priority=%u flags=%u successfully", kStreamPriority, kStreamFlags);
// 2. 查询 Stream 的 ID / Flag / Priority 并校验
if (QueryStreamInfo(stream) != 0) {
return -1;
}
// 3. 同步等待 Stream 上任务完成
if (CheckAcl(aclrtSynchronizeStream(stream), "aclrtSynchronizeStream") != 0) {
return -1;
}
// 4. 显式销毁 Stream
if (CheckAcl(streamGuard.Destroy(), "aclrtDestroyStream") != 0) {
return -1;
}
INFO_LOG("[SUCCESS] Stream config query sample completed successfully");
查询逻辑集中在 QueryStreamInfo 中,三个查询接口按固定顺序调用,并将结果打印后与创建参数比对:
int32_t streamId = -1;
if (CheckAcl(aclrtStreamGetId(stream, &streamId), "aclrtStreamGetId") != 0) { return -1; }
INFO_LOG("Stream id: %d", streamId);
uint32_t flags = 0;
if (CheckAcl(aclrtStreamGetFlags(stream, &flags), "aclrtStreamGetFlags") != 0) { return -1; }
INFO_LOG("Stream flags: %u", flags);
uint32_t priority = 0;
if (CheckAcl(aclrtStreamGetPriority(stream, &priority), "aclrtStreamGetPriority") != 0) { return -1; }
INFO_LOG("Stream priority: %u", priority);
// 回读结果必须与创建参数一致
if ((flags != kStreamFlags) || (priority != kStreamPriority)) {
ERROR_LOG("Unexpected stream attributes: flags=%u, priority=%u; expected flags=%u, priority=%u",
flags, priority, kStreamFlags, kStreamPriority);
return -1;
}
这里体现了一个重要原则:创建时指定的配置参数,应通过查询接口回读并做一致性校验,从而确认 Stream 的实际生效属性与预期相符。需要注意,Stream ID 由 Runtime 内部分配,样例输出中的 1 仅为该进程内实际分配的 ID,并非固定值。
5.4 main 函数:初始化与收尾
int32_t main()
{
if (CheckAcl(aclInit(nullptr), "aclInit") != 0) {
return -1;
}
if (CheckAcl(aclrtSetDevice(kDeviceId), "aclrtSetDevice") != 0) {
CHECK_ERROR(aclFinalize());
return -1;
}
int ret = RunStreamConfigQuerySample();
CHECK_ERROR(aclrtResetDeviceForce(kDeviceId));
CHECK_ERROR(aclFinalize());
return ret;
}
顺序为:aclInit 初始化 ACL → aclrtSetDevice(0) 绑定 Device → 执行业务 → aclrtResetDeviceForce(0) 复位 Device → aclFinalize 去初始化。若 aclrtSetDevice 失败,则跳过后续业务直接调用 aclFinalize 清理,避免资源悬挂。
六、示例输出解读
正常运行时,程序输出如下(与样例 README 的"示例输出"一致):
[INFO] Create stream with priority=0 flags=0 successfully
[INFO] Stream id: 1
[INFO] Stream flags: 0
[INFO] Stream priority: 0
[INFO] [SUCCESS] Stream config query sample completed successfully
[SUCCESS] Stream config query sample executed successfully.
逐行解读:
- 前四行来自
main程序本身:确认以priority=0 flags=0成功创建 Stream,随后回读到id=1、flags=0、priority=0,与创建参数一致,校验通过; - 第五行
[INFO] [SUCCESS] Stream config query sample completed successfully是程序内的业务成功标志; - 最后一行
[SUCCESS] Stream config query sample executed successfully.由 run.sh 在grep校验命中成功标志后打印,代表脚本级验证通过。
七、从样例到生产:Flag 选型与进阶方向
本样例以 flags=0 演示了最基础的配置化创建。在实际业务中,可根据场景组合使用 4.2 节的 Flag 宏:
- 高频反复下发任务的推理/训练循环:优先考虑
ACL_STREAM_FAST_LAUNCH,用创建时的一次性资源预申请换取每次下发任务的时延降低; - 对同步时延敏感:优先考虑
ACL_STREAM_FAST_SYNC,将同步等待从"被动等通知"变为"主动查状态",代价是更高的 CPU 占用; - 模型构建与绑定场景:使用
ACL_STREAM_PERSISTENT配合模型运行实例绑定接口(详见 15_model_running_instance_management.md 中的aclmdlRIBindStream),并在需要重新下发任务时通过aclrtPersistentTaskClean清理任务。
同时注意两点约束(详见接口文档):
ACL_STREAM_FAST_SYNC模式下调用aclrtSynchronizeStream的行为与默认 Stream 不同,需按实际语义设计同步策略;- 部分接口(如溢出检测开关、
aclrtStreamQuery的状态查询)对ACL_STREAM_PERSISTENT、ACL_STREAM_DEVICE_USE_ONLY、ACL_STREAM_CPU_SCHEDULE创建的 Stream 有特殊约束或不支持,组合使用时务必查阅 06_stream_management.md 中各接口的"约束说明"章节。
八、延伸阅读
- 接口权威说明:Stream 管理接口文档(
aclrtCreateStreamWithConfig、aclrtStreamGetId、aclrtStreamGetFlags、aclrtStreamGetPriority、aclrtSynchronizeStream、aclrtDestroyStream等) - 接口声明与 Flag 宏定义:include/external/acl/acl_rt.h
- 本样例完整源码:main.cpp、run.sh、CMakeLists.txt
- 同级 Stream 主题样例:0_simple_stream、1_stream_with_failure_mode、2_multi_stream、4_stream_resource_budget
- Stream 概念与编程模型:异步任务执行概述、Stream 管理开发指南