CANN opbase aclnn 公共接口 aclGetBoolArraySize 详解：获取 aclBoolArray 布尔数组长度

CANN opbase aclnn 公共接口 aclGetBoolArraySize 详解：获取 aclBoolArray 布尔数组长度

【免费下载链接】opbase本项目是CANN算子库的基础框架库，为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase

导读

本文深入解析 CANN 算子库基础框架（opbase）中 aclnn 公共接口aclGetBoolArraySize的声明、参数语义、返回值与源码级实现原理。该接口用于获取由 aclCreateBoolArray 创建的aclBoolArray布尔数组的大小（元素个数），是单算子 API 调用流程中校验与获取布尔型入参数组信息的关键一环。读完本文，你将掌握aclGetBoolArraySize的完整用法、空指针失败场景的返回码（161001）含义，以及它与创建、销毁接口配合的完整生命周期写法。

功能说明：布尔数组大小的读取入口

aclBoolArray是 CANN opbase 框架定义的一种用于管理和存储布尔型数据的数组结构，作为单算子 API（aclnn）执行接口的入参使用，开发者无需关注其内部实现细节，直接通过公共接口操作即可。

aclGetBoolArraySize用于获取一个已创建的aclBoolArray的大小（即其中 bool 元素的个数）。该接口通常与以下两个接口配套构成完整的生命周期：

• aclCreateBoolArray：创建aclBoolArray；
• aclDestroyBoolArray：销毁aclBoolArray。

在单算子调用场景中，aclBoolArray常被用作算子属性（如掩码 mask 数据）的载体传入执行接口；在组装参数或调试时，通过aclGetBoolArraySize可以反向确认数组实际承载的元素个数，例如校验创建时传入的 size 是否与预期一致。

函数原型

aclnnStatus aclGetBoolArraySize(const aclBoolArray *array, uint64_t *size)

该接口以 C 语言形式对外暴露，声明位于仓库头文件 include/nnopbase/aclnn/acl_meta.h 中：

ACL_FUNC_VISIBILITY aclnnStatus aclGetBoolArraySize(const aclBoolArray* array, uint64_t* size);

同时，aclBoolArray类型本身也在同一头文件中以不透明结构体（opaque struct）的形式声明：

typedef struct aclBoolArray aclBoolArray;

开发者只能通过公共接口操作该类型，无法直接访问其内部成员，这正是"无需关注内部实现"的设计体现。

参数说明

使用要点：

• array必须指向一个有效（已成功创建且尚未销毁）的aclBoolArray，传入空指针将导致接口失败，返回码见下文；
• size是输出型参数，不能传入nullptr，否则同样会被判定为参数非法；
• 返回的大小为创建该数组时指定的元素个数，即aclCreateBoolArray的第二个参数size的取值。

返回值说明

返回0（即ACLNN_SUCCESS）表示成功，返回其他值表示失败。返回码列表参见 公共接口返回码。

可能失败的原因：

• 返回161001（ACLNN_ERR_PARAM_NULLPTR）：参数array或size为空指针。

常见返回码对照如下：

说明：接口失败时，可通过《Runtime 运行时 API》中的aclGetRecentErrMsg接口获取更详细的异常信息，便于排查问题。

源码实现原理

从源码结构看，aclGetBoolArraySize的实际实现在 src/nnopbase/common/api/acl_op_api.cpp 中，逻辑非常简洁：

aclnnStatus aclGetBoolArraySize(const aclBoolArray* array, uint64_t* size) { if (array == nullptr || size == nullptr) { return ACLNN_ERR_PARAM_NULLPTR; } *size = array->Size(); return OK; }

该实现揭示了以下关键事实：

1. 空指针校验先行：接口在访问对象前会同时校验array与size两个指针，任一为nullptr即直接返回ACLNN_ERR_PARAM_NULLPTR（数值为 161001），与文档中"返回 161001：参数 array 或 size 为空指针"的描述完全一致；
2. 大小来源于对象内部Size()方法：成功时直接通过array->Size()获取元素个数并写入输出参数，不涉及任何内存分配，因此本接口是 O(1) 时间复杂度的轻量读取操作；
3. 返回值语义统一：OK即宏常量0（定义于 include/nnopbase/aclnn/acl_meta.h），与"返回 0 表示成功"的文档约定对应。

作为对照，同头文件中aclGetIntArraySize、aclGetFloatArraySize、aclGetTensorListSize、aclGetScalarListSize等接口的实现模式完全一致，均采用"空指针校验 + 调用对象Size()方法"的结构，aclGetBoolArraySize是这一组元数据读取接口家族中的一员。

在 opbase 的算子框架内部，aclBoolArray还被广泛用于算子属性组装：例如 include/nnopbase/opdev/op_arg_def.h 中提供了从aclBoolArray*/const aclBoolArray*构造OpArgValue的隐式转换，include/nnopbase/opdev/aicpu/aicpu_task.h 中则提供了将aclBoolArray追加到缓存键（cache key）与 Aicpu 属性的工具函数，体现了该结构在参数传递链路中的实际用途。

调用示例

以下关键代码示例仅供参考，完整工程中不支持直接拷贝运行，请结合单算子 API 的真实接口名与参数调整。

// 1. 创建 aclBoolArray bool maskData[] = {true, false}; aclBoolArray *mask = aclCreateBoolArray(maskData, sizeof(maskData) / sizeof(maskData[0])); // 2. 使用 aclGetBoolArraySize 接口获取 mask 的大小 uint64_t size = 0; auto ret = aclGetBoolArraySize(mask, &size); // 获取到的 mask 的 size 为 2 if (ret != 0) { // 处理失败：ret 可能为 161001（array 或 size 为空指针） } // 3. aclBoolArray 作为单算子 API 执行接口的入参 // ret = aclxxXxxGetWorkspaceSize(srcTensor, mask, ..., outTensor, ..., &workspaceSize, &executor); // ret = aclxxXxx(...); // 4. 销毁 aclBoolArray ret = aclDestroyBoolArray(mask);

代码流程拆解：

1. 创建阶段：以bool数组{true, false}及元素个数 2 调用aclCreateBoolArray，获得aclBoolArray*指针。注意aclCreateBoolArray会将 Host 侧指针value指向的值拷贝进对象内部（详见 aclCreateBoolArray 的参数说明），因此原始数组在创建后可以被安全复用或释放；
2. 读取阶段：声明并初始化uint64_t size = 0后调用aclGetBoolArraySize，接口将元素个数 2 写入size，实现上等价于读取mask->Size()；
3. 使用阶段：aclBoolArray可直接作为单算子 API 执行接口的入参传入（示例中为示意性的aclxxXxxGetWorkspaceSize/aclxxXxx调用）；
4. 销毁阶段：调用 aclDestroyBoolArray 释放对象。从 acl_op_api.cpp 的实现可见，aclDestroyBoolArray对空指针入参是安全的（直接返回成功），且在开启 aclnn 调试（IsAclnnDebugEnabled）时会通过CheckDoubleFree检测可能的重复释放（double-free）并输出告警日志，因此务必保证"一创一销、不重复销毁"。

约束说明与使用建议

aclGetBoolArraySize本身的约束为"无"，但围绕其完整使用场景，有以下实践建议：

• 生命周期配对：aclBoolArray必须与 aclDestroyBoolArray 配套使用，分别完成创建与销毁（参见 aclCreateBoolArray 的约束说明）；
• 先判空再使用输出值：接口失败时size输出值不可信赖，应先检查返回值是否为 0（ACLNN_SUCCESS）再使用size；
• 调试辅助：在算子参数组装链路中，若传入的aclBoolArray由框架内部（例如通过 AllocBoolArray 等接口）生成，可借助本接口快速确认元素个数，避免出现掩码长度与算子预期不符的隐性问题。

小结

aclGetBoolArraySize是 CANN opbase aclnn 公共接口中针对布尔数组的轻量查询接口：入参为aclBoolArray与输出指针size，成功返回 0，空指针时返回 161001。其源码实现在 src/nnopbase/common/api/acl_op_api.cpp，本质是对array->Size()的封装。将它与 aclCreateBoolArray、aclDestroyBoolArray 组合使用，即可完整覆盖布尔型掩码数据在单算子调用中的创建、读取与销毁全流程。

【免费下载链接】opbase本项目是CANN算子库的基础框架库，为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase