Apache Arrow C ABI 详解C Data Interface 与 C Stream Interface 的结构、语义与实战【免费下载链接】arrowApache Arrow is a multi-language toolbox for accelerated data interchange and in-memory processing项目地址: https://gitcode.com/gh_mirrors/arrow12/arrowApache Arrow 的 C ABIdocs/source/cpp/api/c_abi.rst以三个自包含的 C 结构体ArrowSchema、ArrowArray、ArrowArrayStream为基石定义了跨语言、跨运行时的列式数据零拷贝交换协议。本文以此为骨架结合 C Data Interface 规范 与 C Stream Interface 规范 的完整定义以及 cpp/src/arrow/c/abi.h 与 cpp/src/arrow/c/bridge.cc 的源码实现系统讲解格式字符串编码、结构体字段语义、内存管理与 release 回调约定、流式接口协议并给出可直接复制的 C 生产者/消费者代码示例。读完本文你将能够在自己的项目中不依赖 Arrow 库直接实现 Arrow 数据的导出、导入与流式传输。什么是 Arrow C ABI三个结构体组成的“列式数据通用语”C ABI 页面文档的核心是一句话只要三个 C 结构体就能让任何项目与 Arrow 格式进行列式数据交换。这三个结构体定义在 cpp/src/arrow/c/abi.h并被设计为可以原样拷贝进任意项目的源码约 50 行 C 代码因此也被称为“Arrow C data interface 的自由站立定义”。#ifndef ARROW_C_DATA_INTERFACE #define ARROW_C_DATA_INTERFACE #define ARROW_FLAG_DICTIONARY_ORDERED 1 #define ARROW_FLAG_NULLABLE 2 #define ARROW_FLAG_MAP_KEYS_SORTED 4 struct ArrowSchema { // Array type description const char* format; const char* name; const char* metadata; int64_t flags; int64_t n_children; struct ArrowSchema** children; struct ArrowSchema* dictionary; // Release callback void (*release)(struct ArrowSchema*); // Opaque producer-specific data void* private_data; }; struct ArrowArray { // Array data description int64_t length; int64_t null_count; int64_t offset; int64_t n_buffers; int64_t n_children; const void** buffers; struct ArrowArray** children; struct ArrowArray* dictionary; // Release callback void (*release)(struct ArrowArray*); // Opaque producer-specific data void* private_data; }; #endif // ARROW_C_DATA_INTERFACE从源码结构看abi.h 中的定义与规范文档完全一致并用#pragma once与extern C包裹以兼容 C/C 混编。同一头文件还顺带定义了ArrowDeviceArray设备数据接口用于 CUDA/ROCm 等非 CPU 内存与ArrowDeviceArrayStream本文聚焦 CPU 侧的三个核心结构体。设计目标与边界依据 C Data Interface 规范 中的 Goals 与 Non-goals 章节这套接口的设计意图非常明确目标暴露 ABI 稳定的接口让第三方项目能以极小的投入实现支持包括部分支持实现同一进程内独立运行时与组件之间的零拷贝共享紧贴 Arrow 数组概念避免再造一层编组层无需编译期或运行期依赖 Arrow 软件项目本身。非目标不提供模仿高级运行时C/Java操作的 C API不涉及跨进程数据共享与持久化存储那是 IPC 格式的职责。与 IPC 格式的取舍规范文档明确比较了两条路线选择 C data interface 的理由包括无 Flatbuffers 依赖、无需缓冲区重组数据已经是逻辑 Arrow 格式、天然零拷贝、易于从零重实现、C 定义极小可拷贝、通过自定义 release 回调管理资源生命周期而 IPC 格式的优势则是跨进程与跨机器、支持持久化、可流式组合更多特性校验、压缩等、不要求显式 C 数据访问。简言之进程内共享数据用 C ABI跨进程/持久化用 IPC。类型描述format 字符串全表ArrowSchema.format是一个 UTF-8 的 null 结尾字符串只描述顶层类型嵌套类型的子类型在children中分别描述元数据在metadata中单独编码。format 字符串设计为极易解析哪怕用纯 C。基础类型单字符格式串FormatArrow 类型FormatArrow 类型nnulllint64bbooleanLuint64cint8efloat16Cuint8ffloat32sint16gfloat64Suint16zbinaryiint32Zlarge binaryIuint32uutf-8 stringUlarge utf-8 string视图与变长类型FormatArrow 类型vzbinary viewvuutf-8 viewd:19,10decimal128 [precision 19, scale 10]d:19,10,NNNdecimal位宽 NNN [precision 19, scale 10]w:42fixed-width binary [42 bytes]时间类型以t开头FormatArrow 类型FormatArrow 类型tdDdate32 [days]tDuduration [microseconds]tdmdate64 [milliseconds]tDnduration [nanoseconds]ttstime32 [seconds]tiMinterval [months]ttmtime32 [milliseconds]tiDinterval [days, time]ttutime64 [microseconds]tininterval [month, day, nanoseconds]ttntime64 [nanoseconds]tss:.../tsm:...timestamp [秒/毫秒] 时区tDsduration [seconds]tsu:.../tsn:...timestamp [微秒/纳秒] 时区注意timestamp 的时区字符串在冒号:后原样附加、不加引号即使时区为空冒号也必须保留如tsm:。嵌套类型以开头FormatArrow 类型FormatArrow 类型llistsstructLlarge listmmapvllist-viewud:I,J,...dense uniontype ids I,J...vLlarge list-viewus:I,J,...sparse uniontype ids I,J...w:123fixed-sized list [123 items]rrun-end encoded嵌套类型的两个特殊约定map 类型唯一子类型必须命名为entries其本身是(key, value)双子的 structrun-end encoded 类型有两个子类型第一个是整型的run_ends第二个是values。格式串实例规范文档给出的实例是理解嵌套编码的最佳路径字典编码的decimal128(precision12, scale5)数组索引类型为int16父数组 format 为s其dictionary指向的字典值数组 format 为d:12,5listuint64父 format 为l唯一子类型 format 为Llarge_list_viewuint64父 format 为vL唯一子类型 format 为Lstructints: int32, floats: float32format 为s两个子类型名字为ints、floatsformat 分别为i、fmapstring, float64format 为m子类型名为entriesformats孙类型名为keyu与valuegsparse_unionints: int32, floats: float32type ids 4,5format 为us:4,5run_end_encodedint32, float32format 为r子类型run_endsi与valuesf。字典编码没有专属格式串父 format 编码的是索引类型字典值类型读取自ArrowSchema.dictionary。扩展类型Extension Array的 format 编码的是存储类型扩展类型信息编码在 metadata 中——ARROW:extension:name键记录扩展名ARROW:extension:metadata键记录参数化扩展类型的序列化信息与 IPC 格式的约定一致。字段语义逐项拆解ArrowSchema 字段format必填null 结尾 UTF-8 类型描述字符串嵌套类型的子类型不在此编码而在children中。消费者可以只支持部分类型但应明确文档化该限制。name可选字段或数组名主要用于重建嵌套类型的子字段。可省略为 NULL 或空串。metadata可选二进制字符串非null 结尾编码类型元数据。格式为int32键值对数量 N随后每对键值按“int32字节长度 原始字节”交替排列整数使用本机字节序。例如元数据[(key1, value1)]在小端机器上编码为\x01\x00\x00\x00\x04\x00\x00\x00key1\x06\x00\x00\x00value1。若省略该字段必须为 NULL而非空字符串。flags可选按位或组合。ARROW_FLAG_NULLABLE(2) 表示字段语义上可空与实际是否含 null 值无关ARROW_FLAG_DICTIONARY_ORDERED(1) 表示字典索引顺序语义有意义ARROW_FLAG_MAP_KEYS_SORTED(4) 表示 map 每个 value 内的键已排序。省略时必须为 0。n_children必填子类型数量。children可选指向每个子类型的指针数组必须有n_children个指针仅当n_children为 0 时可为 NULL。dictionary可选指向字典值类型的指针仅当该 schema 表示字典编码类型时必须存在否则必须为 NULL。release必填生产者提供的释放回调。private_data可选生产者私有数据的不透明指针消费者不得处理其生命周期由生产者的 release 回调管理。ArrowArray 字段length必填数组的逻辑长度条目数。null_count必填null 条目数尚未计算时可为 -1。offset必填逻辑偏移量缓冲区物理起点之前的条目数必须为 0 或正数。生产者可以声明只产出 0 偏移数组消费者可以不支持非 0 偏移但需文档化。n_buffers必填物理缓冲区数量由数据类型决定参见 Columnar 格式规范binary/utf-8 view 类型比 Columnar 规范多一个缓冲区见下文“Binary view 数组”。子数组的缓冲区不计入。buffers必填指向每个物理缓冲区起始位置的指针数组共n_buffers个。生产者必须保证每个连续缓冲区大到足以容纳length offset个按 Columnar 规范编码的值建议非强制按原始数据类型对齐内存地址。缓冲区指针仅可在两种情况下为 NULLnull 位图且null_count为 0或对应缓冲区字节大小为 0。n_children/children/dictionary语义同 ArrowSchema 对应字段children 数量由数据类型决定dictionary 指向字典值数组。release必填生产者提供的释放回调。private_data可选同 ArrowSchema。Binary view 数组的额外缓冲区规范特别注明binary/utf-8 view 数组会追加一个缓冲区以int64_t记录每个变长数据缓冲区的长度。该缓冲区是必需的因为这类数组的缓冲区长度无法从数组其他数据中平凡推导。为什么需要两个结构体规范文档专辟一节回答同一类型/模式描述往往适用于多个可能很短的数据批次。把ArrowSchema在对话开始时单独传递一次避免每个批次都重复导出/导入类型描述的开销某些生产者 API 的类型固定甚至无需传递类型而一次性交换数据时也可以在同一 API 调用中同时传递ArrowSchema与ArrowArray。内存管理与 release 回调谁分配、谁释放ArrowSchema与ArrowArray遵循相同的内存管理约定。规范中把在生产者和消费者之间传递的那个结构称为“基础结构体”base structure不含子结构。分配规则基础结构体应由消费者在栈上或堆上分配生产者 API 接收指向消费者分配结构体的指针。结构体指向的所有数据format/metadata 字符串、缓冲区指针数组、children 指针数组等必须由生产者分配和维护。消费者不得干预这些成员的生命周期唯一影响数据生命周期的方式是调用基础结构体的release回调。已释放状态结构体已释放的标志是release回调被置为 NULL。消费者在读取和解释结构体数据之前应检查release是否为 NULL并按需报错。这与 helpers.h 中ArrowSchemaIsReleased/ArrowSchemaMarkReleased等内联辅助函数一一对应ArrowSchemaRelease在非 released 时调用回调并断言回调确实把release置空。消费者视角消费者在不再使用基础结构体时必须调用其release但绝不能调用任何子结构体包括可选的 dictionary的 release——子结构体的释放由生产者负责。调用 release 之后消费者不得再访问基础结构体及其关联数据。生产者视角生产者的 release 回调必须遵守四条硬性规则必须遍历所有子结构体含 dictionary并调用它们各自的 release 回调必须释放结构体直接拥有的所有数据区域buffers、children 成员等必须通过把release置 NULL 标记结构体已释放不得假设结构体仍位于最初产出时的内存位置消费者可以移动结构体见下节因此需要额外生命周期信息如 C 的shared_ptr时必须通过private_data承载。规范给出了一个可直接套用的 release 回调模板static void ReleaseExportedArray(struct ArrowArray* array) { // This should not be called on already released array assert(array-release ! NULL); // Release children for (int64_t i 0; i array-n_children; i) { struct ArrowArray* child array-children[i]; if (child-release ! NULL) { child-release(child); assert(child-release NULL); } } // Release dictionary struct ArrowArray* dict array-dictionary; if (dict ! NULL dict-release ! NULL) { dict-release(dict); assert(dict-release NULL); } // TODO here: release and/or deallocate all data directly owned by // the ArrowArray struct, such as the private_data. // Mark array released array-release NULL; }在 Arrow C 实现中bridge.cc 的ReleaseExportedSchema正是按这套约定编写的先递归释放所有 children 与 dictionary并断言每个子结构在回调后确实已标记 released再释放private_data指向的导出私有数据对象最后ArrowSchemaMarkReleased。该私有数据通过PoolAllocationMixinbridge.cc从默认内存池分配便于内存记账与泄漏检测。移动数组Moving消费者可以通过位拷贝或浅成员拷贝“移动”ArrowArray结构体然后把源结构体标记为 released置release为 NULL但不调用其 release 回调从而保证任意时刻只有一个存活副本。此后 release 回调将在目标结构体上被调用。也可以移动一个或多个子数组但父ArrowArray必须立即释放它指向的子数组已失效典型场景是只保留感兴趣的若干列子数组而释放其余列。移动能够成立的前提是ArrowArray可平凡重定位——因此结构体内部指针成员含private_data不得指向结构体自身生产者也不得在外部单独保存指向该结构体的指针必须用private_data记录簿记信息。这正解释了 helpers.h 中ArrowArrayMove的实现memcpy后ArrowArrayMarkReleased(src)。不可变性约定生产者和消费者都应把通过buffers成员可达的导出数据视为不可变否则一方可能在另一方变更数据时看到不一致内容。C Data Interface 实战手写生产者导出代码规范文档提供了可直接复制的完整 C 生产者示例覆盖从最简 int32 到嵌套 struct 的导出全部基于标准malloc/free不依赖任何 Arrow 头文件。导出非空 int32 类型静态数据类型的所有成员都指向静态分配数据release 回调是平凡的static void release_int32_type(struct ArrowSchema* schema) { // Mark released schema-release NULL; } void export_int32_type(struct ArrowSchema* schema) { *schema (struct ArrowSchema) { .format i, .name , .metadata NULL, .flags 0, .n_children 0, .children NULL, .dictionary NULL, .release release_int32_type }; }导出 C-malloc() 的 int32 数组所有权转移通过 release 回调把buffers的所有权转移给消费者static void release_int32_array(struct ArrowArray* array) { assert(array-n_buffers 2); // Free the buffers and the buffers array free((void *) array-buffers[1]); free(array-buffers); // Mark released array-release NULL; } void export_int32_array(const int32_t* data, int64_t nitems, struct ArrowArray* array) { *array (struct ArrowArray) { .length nitems, .offset 0, .null_count 0, .n_buffers 2, .n_children 0, .children NULL, .dictionary NULL, .release release_int32_array }; // Allocate list of buffers array-buffers (const void**) malloc(sizeof(void*) * array-n_buffers); assert(array-buffers ! NULL); array-buffers[0] NULL; // no nulls, null bitmap can be omitted array-buffers[1] data; }注意int32数组有两个缓冲区null 位图 数据无 null 时位图缓冲区可为 NULL偏移为 0、null_count 为 0。导出 structfloat32, utf8 类型C-malloc() 子类型s结构类型需要递归初始化每个子类型并用一个会递归释放的 release 回调static void release_malloced_type(struct ArrowSchema* schema) { int i; for (i 0; i schema-n_children; i) { struct ArrowSchema* child schema-children[i]; if (child-release ! NULL) { child-release(child); } free(child); } free(schema-children); // Mark released schema-release NULL; } void export_float32_utf8_type(struct ArrowSchema* schema) { struct ArrowSchema* child; *schema (struct ArrowSchema) { .format s, .name , .metadata NULL, .flags 0, .n_children 2, .dictionary NULL, .release release_malloced_type }; schema-children malloc(sizeof(struct ArrowSchema*) * schema-n_children); // child type #0: float32 child schema-children[0] malloc(sizeof(struct ArrowSchema)); *child (struct ArrowSchema) { .format f, .name floats, .metadata NULL, .flags ARROW_FLAG_NULLABLE, .n_children 0, .dictionary NULL, .children NULL, .release release_malloced_type }; // child type #1: utf8 child schema-children[1] malloc(sizeof(struct ArrowSchema)); *child (struct ArrowSchema) { .format u, .name strings, .metadata NULL, .flags ARROW_FLAG_NULLABLE, .n_children 0, .dictionary NULL, .children NULL, .release release_malloced_type }; }对应地规范还给出了export_float32_utf8_array的完整实现父数组n_buffers1struct 无自身数据缓冲区仅buffers[0]NULL、n_children2子数组 #0float32n_buffers2null 位图 数据、null_count-1未计算子数组 #1utf8n_buffers3null 位图 offsets data。释放回调release_malloced_array递归释放所有子数组、全部缓冲区与指针数组。实战要点子数组缓冲区的布局int32/float 2 个、utf8 3 个与 Columnar 格式规范完全一致null_count -1表示尚未计算消费者需自行扫描。C Stream Interface进程内流式传输规范 指出C stream interface 建立在 C data interface 之上把ArrowSchema/ArrowArray组合成更高级的规范便于同一进程内流式数据的通信一个 C 流暴露同 schema 的数据块chunk流式来源通过阻塞的拉取式迭代函数获取数据块。ArrowArrayStream 结构体#ifndef ARROW_C_STREAM_INTERFACE #define ARROW_C_STREAM_INTERFACE struct ArrowArrayStream { // Callbacks providing stream functionality int (*get_schema)(struct ArrowArrayStream*, struct ArrowSchema* out); int (*get_next)(struct ArrowArrayStream*, struct ArrowArray* out); const char* (*get_last_error)(struct ArrowArrayStream*); // Release callback void (*release)(struct ArrowArrayStream*); // Opaque producer-specific data void* private_data; }; #endif // ARROW_C_STREAM_INTERFACE字段语义get_schema必填查询流中所有数据块共用的 schema返回 0 表示成功否则返回非零错误码。不能在已释放的流上调用。get_next必填获取下一个数据块返回 0 表示成功。成功时消费者必须检查ArrowArray是否标记为 released——若已释放则到达流末尾否则该ArrowArray是一个有效数据块。get_last_error必填仅在最后一次流操作返回错误后调用返回指向 UTF-8 null 结尾字符串的指针无详细描述时可为 NULL。返回的指针仅在流的下一次回调调用前有效需要长期持有必须拷贝到消费者管理的存储。release必填释放回调用法与 C data interface 相同。private_data可选同前。错误码约定get_schema与get_next返回的非零整数应按本平台errno解释符号常量跨平台稳定数值平台相关。规范建议至少识别EINVAL参数/输入校验错误、ENOMEM内存分配失败、EIO通用 I/O 错误。结果与流的生命周期get_schema与get_next返回的数据必须独立释放其生命周期与ArrowArrayStream无关。流的生命周期同样通过 release 回调管理。此外流源不保证线程安全消费者若从多线程调用get_next必须自行串行化。C 消费者示例遍历查询结果假设某数据库提供如下 C API 执行 SQL 并把结果集导出为 Arrow C 流void MyDB_Query(const char* query, struct ArrowArrayStream* result_set);消费者代码如下static void handle_error(int errcode, struct ArrowArrayStream* stream) { // Print stream error const char* errdesc stream-get_last_error(stream); if (errdesc ! NULL) { fputs(errdesc, stderr); } else { fputs(strerror(errcode), stderr); } // Release stream and abort stream-release(stream), exit(1); } void run_query() { struct ArrowArrayStream stream; struct ArrowSchema schema; struct ArrowArray chunk; int errcode; MyDB_Query(SELECT * FROM my_table, stream); // Query result set schema errcode stream.get_schema(stream, schema); if (errcode ! 0) { handle_error(errcode, stream); } int64_t num_rows 0; // Iterate over results: loop until error or end of stream while ((errcode stream.get_next(stream, chunk) 0) chunk.release ! NULL) { // Do something with chunk... fprintf(stderr, Result chunk: got %lld rows\n, chunk.length); num_rows chunk.length; // Release chunk chunk.release(chunk); } // Was it an error? if (errcode ! 0) { handle_error(errcode, stream); } fprintf(stderr, Result stream ended: total %lld rows\n, num_rows); // Release schema and stream schema.release(schema); stream.release(stream); }这段代码完整演示了三条协议规则用get_schema取一次 schema、循环get_next直到chunk.release NULL流结束、每个 chunk、schema、stream 各自独立释放。从源码看 C ABI 在 Arrow C 中的落地导出/导入的对称 APIbridge.h 定义了与规范一一对应的Export*/Import*系列 API均属于arrow命名空间导出ExportType、ExportField、ExportSchema写ArrowSchemaExportArray、ExportRecordBatch写ArrowArray可选同时写ArrowSchema。导入ImportType、ImportField、ImportSchemaImportArray、ImportRecordBatch。导入函数会按规范“移动”结构体内容——即使失败给定的ArrowSchema也会被释放。流接口方面bridge.hExportRecordBatchReader、ExportChunkedArray把 C 对象导出为ArrowArrayStreamImportRecordBatchReader、ImportChunkedArray反向导入后者会把流完整消费掉再返回ChunkedArray。另有一组实验性的 Device 接口ExportDeviceArray等对应ArrowDeviceArray/ArrowDeviceArrayStream。从实现看导出时会创建ExportedSchemaPrivateDatabridge.cc持有 format/name/metadata 字符串、子结构数组与字典结构用内存池分配以便记账元数据则按规范编码为“键值对数量 逐对长度前缀”的二进制串EncodeMetadatabridge.cc 起先预计算总大小再写入。测试验证bridge_test.cc 用 5000 余行测试覆盖了这套接口。以流导出为例TestArrayStreamExport.Simplebridge_test.cc构造int32列的 RecordBatchReaderExportRecordBatchReader导出后依次get_schema校验 schema、两次get_next分别与两个批次比较、再断言流结束AssertStreamEnd最后重复断言流结束以验证幂等性。TestArrayStreamExport.ArrayLifetimebridge_test.cc导出流后在流被释放的情况下仍能通过ImportRecordBatch导入之前取出的两个 chunk并断言内存池占用高于导出前——直接验证了“get_next 返回的数据独立于流生命周期”的约定。TestArrayExport.ExportRecordBatchbridge_test.cc 起验证 record batch 以 struct 数组形式导出后可用ImportRecordBatch无损还原。这些测试是阅读规范时极佳的对照材料每个语义约定都能在测试里找到对应的验证点。面向其他语言的落地PyCapsule 接口速览PyCapsule 接口规范 是 C data/stream interface 在 Python 生态的标准化封装官方标注为实验性。它解决的是“Python 库之间如何暴露这些 C 结构体”的问题用带名字与析构函数的PyCapsule包装结构体指针避免裸指针传整数的不安全与泄漏。胶囊命名约定ArrowSchema→arrow_schema、ArrowArray→arrow_array、ArrowArrayStream→arrow_array_stream、ArrowDeviceArray→arrow_device_array、ArrowDeviceArrayStream→arrow_device_array_stream。导出协议为三个鸭子类型方法__arrow_c_schema__、__arrow_c_array__可带requested_schema协商表示形式、__arrow_c_stream__设备接口另有__arrow_c_device_array__与__arrow_c_device_stream__。胶囊的析构函数应调用结构体的 release 回调若非空消费者移走数据后把 release 置空避免双重释放。规范的稳定性承诺规范文档明确一旦 C data interface 进入官方 Arrow 发布C ABI 即冻结——ArrowSchema与ArrowArray的结构定义不得以任何方式改变包括新增成员。仅允许向后兼容的变更例如新增ArrowSchema.flags取值或扩展 format 字符串的可能性任何不兼容变更应放入新规范如 Arrow C data interface v2。这一承诺是整个生态可以放心把这三个结构体拷进自己代码的前提。设计灵感则来自 Python buffer protocolPEP 3118——正是那个让各类 Python 库无需互相认识即可近乎零成本交换数值数据的协议。结语Arrow C ABI 以极小的 API 面三个结构体 三组 release 约定实现了极大的互操作价值它让 C 数据库引擎可以“不依赖 Arrow 库却输出 Arrow 格式结果”让 Python 库通过 PyCapsule 协议互通也让任何语言运行时只需翻译 50 行 C 定义即可接入整个 Arrow 生态。从 格式字符串 到 release 回调模板从 结构体定义 到 导出/导入实现 与 测试验证本文覆盖了从协议语义到实战代码的完整链路可作为你接入 Arrow C ABI 的实现参考。【免费下载链接】arrowApache Arrow is a multi-language toolbox for accelerated data interchange and in-memory processing项目地址: https://gitcode.com/gh_mirrors/arrow12/arrow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考