collections-c 基础示例
源码位置: samples/libraries/collections-c 查看源码
功能说明
演示如何使用 collections-c 库的 Array（动态数组）数据结构。本示例展示了如何创建数组、添加元素、使用销毁回调函数自动释放元素内存等基本操作。
collections-c 是一个 C 语言通用数据结构库，提供了数组、列表、哈希表、双端队列等多种数据结构。
硬件连接
无需外部连接，collections-c 为纯软件数据结构库。
示例内容
创建动态数组（Array）
初始化数组迭代器
循环添加 10 个元素（0-9），每个元素动态分配内存
使用销毁回调函数释放数组及其所有元素的内存
打印完成信息
编译
重要提示：编译前需要先确认当前示例支持的目标板型，然后将板型标识传给 -DBOARD。请按以下方式选择：
确认示例限制：查看当前示例
README中的硬件连接和注意事项，确认是否限定板型。参考示例配置：查看相关示例目录下的
sample.yaml，确认支持的板型。填写板型标识：SDK 内置板型的标识为
boards/下的目录名。例如实际使用的板型目录为boards/<板型名称>/，则编译参数填写为-DBOARD=<板型名称>。
在 SDK 根目录执行编译，并将命令中的 <示例路径> 和 <板型名称> 替换为实际值。
Linux 使用 build.sh：
# 通用命令
./build.sh -C -S samples/<示例路径> -DBOARD=<板型名称>
# 示例：使用 arcs_evb 开发板
./build.sh -C -S samples/<示例路径> -DBOARD=arcs_evb
Windows PowerShell 使用 build.ps1：
# 通用命令
.\build.ps1 -C -S samples/<示例路径> -DBOARD=<板型名称>
# 示例：使用 arcs_evb 开发板
.\build.ps1 -C -S samples/<示例路径> -DBOARD=arcs_evb
Note
确保已安装对应平台的工具链和 ListenAI 开发工具包。Windows 环境请先执行 .\env.ps1 或直接使用 .\build.ps1 自动加载环境。
注意事项：-DBOARD 填写的是板型标识，不是芯片系列名称。如果示例有板型专用配置或额外编译参数，以示例 README 中的说明为准。
烧录
编译完成后，使用 SDK tools/burn 目录下的 cskburn 工具烧录固件。请先根据目标板型和当前示例确定芯片系列、串口设备、烧录地址和固件路径。
Linux：
# 通用命令
./tools/burn/cskburn -C <芯片系列> -s <串口设备> -b 3000000 <烧录地址> <固件路径>
# 示例：使用 arcs_evb 开发板
./tools/burn/cskburn -s /dev/ttyUSB0 -b 3000000 0x0 build/arcs.bin -C arcs
Windows PowerShell：
# 通用命令
.\tools\burn\cskburn.exe -C <芯片系列> -s <串口号> -b 3000000 <烧录地址> <固件路径>
# 示例：使用 arcs_evb 开发板
.\tools\burn\cskburn.exe -C arcs -s COM7 -b 3000000 0x0 .\build\arcs.bin
Note
烧录参数说明：
-s /dev/ttyUSB0/-s COM7：串口设备路径，需要根据实际情况修改 - Linux 系统：通常是/dev/ttyUSB0或/dev/ttyACM0- 可通过ls /dev/tty*命令查看可用串口设备 - Windows 系统：通常是COM7、COM8等，可在“设备管理器”的“端口”中查看 - 不同开发板或 USB 转串口芯片可能使用不同的设备名-b 3000000：烧录波特率（3Mbps）0x0：烧录起始地址build/arcs.bin/.\build\arcs.bin：编译生成的固件路径-C arcs：芯片类型
注意事项：
确保开发板已正确连接到电脑
如果无法识别串口设备，请检查 USB 连接线是否正常，或尝试其他 USB 端口
预期输出
********Arcs SDK 0.1.0 @ v0.0.23.temp.docs-96-gf56c5084660d********
Running on hart-id: 1
I/elog [1034:42:44.159 1 elog_async] EasyLogger V2.2.99 is initialize success.
cc_custom_malloc(xx)
cc_custom_malloc(xx)
cc_custom_malloc(xx)
Destroying 0
Destroying 1
Destroying 2
Destroying 3
Destroying 4
Destroying 5
Destroying 6
Destroying 7
Destroying 8
Destroying 9
cc_custom_malloc(xx)
cc_custom_malloc(xx)
cc_custom_malloc(xx)
...
collections-c sample done
说明：
输出开头包含系统启动信息和日志系统初始化信息
由于启用了自定义内存分配器（‘CONFIG_SDK_MODULE_COLLECTIONS_C_CUSTOM_INCLUDE=y’）,输出中会显示内存分配和释放的调试信息（‘cc_custom_malloc’,‘cc_custom_free’,‘cc_custom_calloc’）
Destroying X信息由销毁回调函数array_destroy_cb_handle输出，X 为元素值（0-9）销毁顺序可能与添加顺序不同，取决于数组内部实现
核心 API
API |
说明 |
|---|---|
|
创建新的动态数组 |
|
初始化数组迭代器 |
|
向数组添加元素 |
|
销毁数组并调用回调函数处理每个元素 |
|
销毁数组（不调用回调） |
关键代码
/* 创建数组 */
Array *ar;
enum cc_stat st;
st = array_new(&ar);
assert(st == CC_OK);
/* 初始化迭代器 */
ArrayIter it;
array_iter_init(&it, ar);
/* 添加元素 */
for (uint8_t i = 0; i < 10; ++i) {
uint32_t *n = malloc(sizeof(uint32_t));
assert(n);
*n = i;
array_add(ar, n);
}
/* 销毁回调函数 */
void array_destroy_cb_handle(void *item)
{
uint32_t *n = item;
printf("Destroying %u\n", *n);
free(n);
}
/* 销毁数组并释放元素内存 */
array_destroy_cb(ar, array_destroy_cb_handle);
配置说明
自定义内存分配器
本示例支持使用自定义内存分配器，通过以下配置启用：
CONFIG_SDK_MODULE_COLLECTIONS_C_CUSTOM_INCLUDE: 启用自定义内存分配器CONFIG_SDK_MODULE_COLLECTIONS_C_CUSTOM_INCLUDE_PATH: 自定义头文件路径（默认："cc_custom_include.h"）
启用后，collections-c 将使用 cc_custom.c 中定义的内存分配函数（cc_custom_malloc、cc_custom_free、cc_custom_calloc）替代标准库的 malloc、free、calloc。
本示例的自定义内存分配器使用外部 RAM（exram_malloc、exram_free、exram_calloc），适用于需要从特定内存区域分配的场景。
启用后，collections-c 将使用自定义的内存分配函数替代标准库函数。自定义内存分配器可以使用外部 RAM（exram_malloc、exram_free、exram_calloc）或其他内存管理方案，适用于需要从特定内存区域分配的场景。
注意事项
内存管理: 使用
array_destroy_cb()时，回调函数负责释放每个元素的内存；如果元素不需要特殊处理，可以使用array_destroy()直接销毁数组返回值检查:
array_new()和array_add()返回enum cc_stat状态码，应检查返回值是否为CC_OK元素所有权: 数组不拥有元素的所有权，销毁数组时不会自动释放元素内存，必须使用
array_destroy_cb()并提供回调函数来释放元素迭代器使用: 本示例初始化了迭代器但未使用，实际使用时可以通过迭代器遍历数组元素
自定义分配器: 如果使用自定义内存分配器，确保分配和释放函数配对使用，避免内存泄漏
线程安全: collections-c 库本身不是线程安全的，在多线程环境中使用时需要额外的同步机制