CANN opbase 算子开发指南aclOpExecutor::AllocScalarList 标量列表申请接口详解【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase导读AllocScalarList是 CANN opbase 算子库中aclOpExecutor执行器提供的内存申请接口之一用于一次性申请一个aclScalarList对象并把一组已存在的aclScalar标量组装进该列表。它在以 aclnn 协议开发自定义算子、构造多标量参数例如算子同时接收一组阈值、轴或系数时是核心工具。读完本文你将掌握该接口的函数原型、参数语义、失败处理规则并能结合仓库源码理解其底层实现与生命周期管理方式直接用于算子参数组装代码的编写。一、背景为什么需要 aclScalarList在 CANN 算子开发中算子入参除了张量aclTensor和数组aclIntArray、aclFloatArray等还可能包含一组标量。标量aclScalar用于表达单个数值型参数而aclScalarList则用于把多个标量组织成一个整体作为算子的一个入参单元。从源码结构看aclScalar定义在 include/nnopbase/opdev/common_types.h其内部通过联合体union支持 int8/uint8、int16/uint16、int32/uint32、int64/uint64、float、double、fp16、bf16 以及 Float8/Float6/Float4 等扩展浮点类型并提供了ToInt32()、ToFloat()、ToDouble()、ToString()等一系列取值转换方法。aclScalarList则位于同一头文件的 include/nnopbase/opdev/common_types.h内部维护一个aclScalar** scalars_指针数组和uint64_t size_元素个数对外提供operator[]下标访问、Size()、GetData()与ToString()等方法。由于aclScalarList的构造函数是私有的friend class aclOpExecutor普通代码无法直接new一个列表对象必须通过aclOpExecutor暴露的AllocScalarList接口申请这正是该接口存在的意义由执行器统一管理标量列表的创建与生命周期。二、函数原型AllocScalarList是aclOpExecutor的成员函数声明位于 include/nnopbase/opdev/op_executor.haclScalarList *AllocScalarList(const aclScalar *const *scalars, uint64_t size)接口语义为申请一个aclScalarList并指定其内部包含的aclScalar。三、参数说明参数输入/输出说明scalars输入源数据用于初始化 aclScalarList。即指向aclScalar*指针数组首元素的指针数组中的每个元素是一个已存在的aclScalar对象指针。size输入源数据的元素个数即scalars数组中aclScalar指针的数量。其中scalars的类型为const aclScalar *const *表示它是一个指向指向常量aclScalar的常量指针的指针即调用者传入的aclScalar*数组本身及数组内指针指向的对象在接口内部均不会被修改。size的类型为uint64_t与列表内部size_字段类型一致。四、返回值说明成功返回申请到的aclScalarList对象失败返回nullptr。因此调用方在拿到返回值后应先判空再继续后续的参数组装或算子下发逻辑。五、约束说明入参指针不能为空scalars必须指向合法的aclScalar*数组且数组内每个元素应指向有效的aclScalar对象传入空指针属于非法调用。传入的aclScalar对象应通过executor-AllocScalar(...)等执行器接口创建而非自行构造以便执行器统一登记和管理这些对象。六、源码级实现原理AllocScalarList的实现位于 src/nnopbase/composite_op/aclnn_engine/op_executor.cppaclScalarList* aclOpExecutor::AllocScalarList(const aclScalar* const* scalars, uint64_t size) { aclScalarList* list nullptr; ADD_TRY_CATCH(list new aclScalarList(scalars, size); allocatedObjList_.push_back(list); return list; , OP_LOGE(ACLNN_ERR_INNER, aclOpExecutor::AllocScalarList failed.); delete list; return nullptr;); }从实现可以看出三个关键点构造内部执行new aclScalarList(scalars, size)即调用aclScalarList的私有构造函数将传入的标量指针数组与元素个数复制进列表对象对应头文件中的scalars_与size_字段。生命周期登记创建成功后列表指针被推入执行器的allocatedObjList_容器。结合头文件中的allocatedObjList_、allocatedTensorList_等成员见 include/nnopbase/opdev/op_executor.h可以推断执行器会在析构阶段统一释放这些由它申请的对象即谁申请、谁释放开发者无需也不应手动 delete 通过该接口返回的列表。异常兜底ADD_TRY_CATCH宏对构造过程做异常捕获一旦分配失败会记录ACLNN_ERR_INNER错误日志并释放已构造对象最终返回nullptr。同样的申请-登记-返回模式也出现在同文件中的AllocIntArray、AllocFloatArray、AllocBoolArray、AllocTensorList等接口上op_executor.cpp说明AllocScalarList是执行器统一的对象工厂体系中的一员。七、调用示例以下示例来自接口文档AllocScalarList.md完整演示了先逐个申请标量再组装成标量列表的典型用法// 初始化5个aclScalar并将他们组装为一个aclScalarList void Func(aclOpExecutor *executor) { int64_t val 5; std::vectoraclScalar * scalars; for (int64_t i 1; i 5; i) { aclScalar *scalar executor-AllocScalar(val); scalars.push_back(scalar); } aclScalarList *scalarList executor-AllocScalarList(scalars.data(), scalars.size()); }示例要点说明循环内通过executor-AllocScalar(val)申请了 5 个值相同均为 5的aclScalar对象。AllocScalar提供多种重载以支持不同的数据类型例如int32_t、int64_t、float、double、op::fp16_t、op::bfloat16及各类无符号整型原型见 AllocScalar.md 与 op_executor.h。实际使用时可以让每个标量携带不同的数值。scalars.data()返回std::vector内部数组的首地址scalars.size()为 5两者作为scalars与size实参传入。返回值scalarList在使用前建议判空若需要将其作为算子入参可结合ConvertToTensor系列接口或直接传入后续的算子执行流程。八、相关接口与使用建议AllocScalarList属于aclOpExecutor的对象申请接口族与其紧密相关的接口包括AllocScalar单个标量申请接口是构造列表元素的前置步骤支持十余种数据类型的重载见 AllocScalar.md。AllocTensorList功能对称的张量列表申请接口用于组装多个aclTensor见 AllocTensorList.md。ConvertToTensor将标量或数组转换为aclTensor的转换接口可实现标量参数与张量参数之间的形态互换见 ConvertToTensor.md。AllocIntArray / AllocFloatArray / AllocBoolArray同族的定长数组申请接口适用于整型、浮点、布尔数组参数见 AllocIntArray.md、AllocFloatArray.md、AllocBoolArray.md。完整接口清单可参考 op_executor.md 与 0_opdev_api_list.md。使用建议先通过AllocScalar准备元素再一次性调用AllocScalarList组装避免多次手动管理数组申请前确认scalars数组非空且所有元素有效符合接口的指针非空约束对返回值做判空处理异常路径下返回nullptr时按错误处理即可列表及其中标量的释放由执行器统一管理不要对返回指针自行delete以免与执行器的生命周期管理冲突。九、总结AllocScalarList以极简的接口形态解决了算子开发中多标量参数打包的问题(const aclScalar* const* scalars, uint64_t size)两个入参即可将一组标量组织为一个可整体传递的aclScalarList。通过 op_executor.cpp 的实现可以看到它依托执行器的对象工厂与ADD_TRY_CATCH异常兜底机制实现了申请、登记、异常回收的一体化生命周期管理。掌握了该接口及其姊妹接口即可在 CANN opbase 框架下高效完成算子参数对象的组装与传参。【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考