IPC 扩展参考#

C API#

group nanoarrow_ipc

除非另有说明，否则对象不是线程安全的，客户端应注意序列化对方法的访问。

由于此库旨在作为供应商提供，因此它提供完整的类型定义，并鼓励客户端在方便的情况下进行堆叠或静态分配。

定义

NANOARROW_IPC_FEATURE_DICTIONARY_REPLACEMENT#: 使用字典替换的流的特性标志。

NANOARROW_IPC_FEATURE_COMPRESSED_BODY#: 使用压缩的流的特性标志。

枚举

enum ArrowIpcMetadataVersion#

元数据版本枚举器。

值

enumerator NANOARROW_IPC_METADATA_VERSION_V1#

enumerator NANOARROW_IPC_METADATA_VERSION_V2#

enumerator NANOARROW_IPC_METADATA_VERSION_V3#

enumerator NANOARROW_IPC_METADATA_VERSION_V4#

enumerator NANOARROW_IPC_METADATA_VERSION_V5#

enum ArrowIpcMessageType#

消息类型枚举器。

值

enumerator NANOARROW_IPC_MESSAGE_TYPE_UNINITIALIZED#

enumerator NANOARROW_IPC_MESSAGE_TYPE_SCHEMA#

enumerator NANOARROW_IPC_MESSAGE_TYPE_DICTIONARY_BATCH#

enumerator NANOARROW_IPC_MESSAGE_TYPE_RECORD_BATCH#

enumerator NANOARROW_IPC_MESSAGE_TYPE_TENSOR#

enumerator NANOARROW_IPC_MESSAGE_TYPE_SPARSE_TENSOR#

enum ArrowIpcEndianness#

字节序枚举器。

值

enumerator NANOARROW_IPC_ENDIANNESS_UNINITIALIZED#

enumerator NANOARROW_IPC_ENDIANNESS_LITTLE#

enumerator NANOARROW_IPC_ENDIANNESS_BIG#

enum ArrowIpcCompressionType#

压缩类型枚举器。

值

enumerator NANOARROW_IPC_COMPRESSION_TYPE_NONE#

enumerator NANOARROW_IPC_COMPRESSION_TYPE_LZ4_FRAME#

enumerator NANOARROW_IPC_COMPRESSION_TYPE_ZSTD#

功能

ArrowErrorCode ArrowIpcCheckRuntime(struct ArrowError *error)#: 检查 nanoarrow 运行时以确保运行/构建版本匹配。

static inline enum ArrowIpcEndianness ArrowIpcSystemEndianness(void)#: 获取当前运行时的字节序。

ArrowErrorCode ArrowIpcSharedBufferInit(struct ArrowIpcSharedBuffer *shared, struct ArrowBuffer *src)#

初始化 ArrowIpcSharedBuffer 结构的内容。

如果返回 NANOARROW_OK，则 ArrowIpcSharedBuffer 将获取 src 的所有权。

void ArrowIpcSharedBufferReset(struct ArrowIpcSharedBuffer *shared)#

释放调用者对共享缓冲区的副本。

完成之后，调用者必须使用此函数放弃其对共享数据的副本。原始缓冲区将继续存在，直到所有引用它的 ArrowArray 对象也被释放。

int ArrowIpcSharedBufferIsThreadSafe(void)#

检查共享缓冲区的线程安全性。

线程安全的共享缓冲区需要 C11 和 stdatomic.h 头文件。如果其中任何一个不可用，共享缓冲区仍然可以实现，但生成的数组不能传递给其他线程以进行释放。

ArrowErrorCode ArrowIpcDecoderInit(struct ArrowIpcDecoder *decoder)#: 初始化解码器。

void ArrowIpcDecoderReset(struct ArrowIpcDecoder *decoder)#: 释放与解码器关联的所有资源。

ArrowErrorCode ArrowIpcDecoderPeekHeader(struct ArrowIpcDecoder *decoder, struct ArrowBufferView data, int32_t *prefix_size_bytes, struct ArrowError *error)#

查看消息头。

Arrow IPC 消息的前 8 个字节是 0xFFFFFFFF，后面跟着头的大小，以小端 32 位整数表示。ArrowIpcDecoderPeekHeader() 读取这些字节并在 data 中没有足够的剩余字节来读取整个消息头时返回 ESPIPE，如果前 8 个字节无效则返回 EINVAL，如果已达到 Arrow 流结束指示符则返回 ENODATA，否则返回 NANOARROW_OK。

1.0 之前的消息没有以 0xFFFFFFFF 为前缀。对于这些消息，将把值 4 放入 prefix_size_bytes 中；否则将把值 8 放入 prefix_size_bytes 中。

ArrowErrorCode ArrowIpcDecoderVerifyHeader(struct ArrowIpcDecoder *decoder, struct ArrowBufferView data, struct ArrowError *error)#

验证消息头。

运行 ArrowIpcDecoderPeekHeader() 以确保 data 的大小足够大，但此外还运行 flatbuffer 验证以确保解码数据不会访问 data 指定的缓冲区之外的内存。ArrowIpcDecoderVerifyHeader() 还会设置 decoder.header_size_bytes、decoder.body_size_bytes、decoder.metadata_version 和 decoder.message_type。

返回结果与 ArrowIpcDecoderPeekHeader() 相同，此外如果 flatbuffer 验证失败，还会返回 EINVAL。

ArrowErrorCode ArrowIpcDecoderDecodeHeader(struct ArrowIpcDecoder *decoder, struct ArrowBufferView data, struct ArrowError *error)#

解码消息头。

运行 ArrowIpcDecoderPeekHeader() 以确保数据足够大，并解码消息头的内容。如果数据包含模式消息，则会设置 decoder.endianness 和 decoder.feature_flags，并且可以使用 ArrowIpcDecoderDecodeSchema() 获取解码后的模式。如果数据包含记录批处理消息，则会设置 decoder.codec，并且成功调用后可以接着调用 ArrowIpcDecoderDecodeArray()。

在几乎所有情况下，此操作应在调用 ArrowIpcDecoderVerifyHeader() 之后进行，以确保解码不会访问指定缓冲区之外的数据。

如果消息内容无法解码，则返回 EINVAL；如果消息内容使用此库不支持的功能，则返回 ENOTSUP。

ArrowErrorCode ArrowIpcDecoderDecodeSchema(struct ArrowIpcDecoder *decoder, struct ArrowSchema *out, struct ArrowError *error)#

解码 ArrowSchema。

在成功调用 ArrowIpcDecoderDecodeHeader() 之后，检索 ArrowSchema。如果返回 NANOARROW_OK，则调用者负责释放该模式。

如果解码器没有刚刚解码模式消息，则返回 EINVAL；否则返回 NANOARROW_OK。

ArrowErrorCode ArrowIpcDecoderSetSchema(struct ArrowIpcDecoder *decoder, struct ArrowSchema *schema, struct ArrowError *error)#

设置用于解码未来记录批处理消息的 ArrowSchema。

为未来此类型的记录批处理消息准备解码器。如果返回 NANOARROW_OK，则解码器将拥有该模式。请注意，您必须在解码模式消息后显式调用此方法（即，解码器不会假设上次解码的模式消息适用于未来的记录批处理消息）。

如果模式验证失败，则返回 EINVAL；否则返回 NANOARROW_OK。

ArrowErrorCode ArrowIpcDecoderSetEndianness(struct ArrowIpcDecoder *decoder, enum ArrowIpcEndianness endianness)#

设置用于解码未来记录批处理消息的字节序。

为使用指定字节序的未来记录批处理消息准备解码器。请注意，您必须在解码模式消息后显式调用此方法（即，解码器不会假设上次解码的模式消息适用于未来的记录批处理消息）。

成功时返回 NANOARROW_OK。

ArrowErrorCode ArrowIpcDecoderDecodeArrayView(struct ArrowIpcDecoder *decoder, struct ArrowBufferView body, int64_t i, struct ArrowArrayView **out, struct ArrowError *error)#

解码 ArrowArrayView。

在成功调用 ArrowIpcDecoderDecodeHeader() 之后，将 body 的内容反序列化到内部管理的 ArrowArrayView 中，并将其返回。请注意，如果任何列包含嵌套类型，则字段索引不等于列索引。使用 -1 的值将整个数组解码为结构。指向的 ArrowArrayView 由 ArrowIpcDecoder 拥有，不能释放。

对于与系统字节序匹配且不使用压缩的流，此操作不会执行任何堆分配；但是，返回的 ArrowArrayView 所引用的缓冲区仅在 body 引用的缓冲区保持有效时才有效。

ArrowErrorCode ArrowIpcDecoderDecodeArray(struct ArrowIpcDecoder *decoder, struct ArrowBufferView body, int64_t i, struct ArrowArray *out, enum ArrowValidationLevel validation_level, struct ArrowError *error)#

解码 ArrowArray。

在成功调用 ArrowIpcDecoderDecodeHeader() 之后，使用消息主体和字段索引组装 ArrowArray。请注意，如果任何列包含嵌套类型，则字段索引不等于列索引。使用 -1 的值将整个数组解码为结构。如果返回 NANOARROW_OK，则调用者负责释放该数组。

如果解码器没有刚刚解码记录批处理消息，则返回 EINVAL；如果消息使用此库不支持的功能，则返回 ENOTSUP；否则返回 NANOARROW_OK。

ArrowErrorCode ArrowIpcDecoderDecodeArrayFromShared(struct ArrowIpcDecoder *decoder, struct ArrowIpcSharedBuffer *shared, int64_t i, struct ArrowArray *out, enum ArrowValidationLevel validation_level, struct ArrowError *error)#

从拥有缓冲区解码 ArrowArray。

此实现利用了可以避免复制单个缓冲区的事实。在所有情况下，调用者都必须在一次或多次调用ArrowIpcDecoderDecodeArrayFromShared()后，使用ArrowIpcSharedBufferReset()释放 body。如果ArrowIpcSharedBufferIsThreadSafe() 返回 0，则 out 必须不能由其他线程释放。

void ArrowIpcInputStreamMove(struct ArrowIpcInputStream *src, struct ArrowIpcInputStream *dst)#: 将 ArrowIpcInputStream 的所有权转移。

ArrowErrorCode ArrowIpcInputStreamInitBuffer(struct ArrowIpcInputStream *stream, struct ArrowBuffer *input)#

从 ArrowBuffer 创建输入流。

该流拥有缓冲区的所有权，并从中读取字节。

ArrowErrorCode ArrowIpcInputStreamInitFile(struct ArrowIpcInputStream *stream, void *file_ptr, int close_on_release)#

从 C FILE* 指针创建输入流。

请注意，ArrowIpcInputStream 没有机制来通信错误，如果 file_ptr 无法关闭。如果需要此行为，请将 false 传递给 close_on_release，并独立于 stream 处理文件关闭。

ArrowErrorCode ArrowIpcArrayStreamReaderInit(struct ArrowArrayStream *out, struct ArrowIpcInputStream *input_stream, struct ArrowIpcArrayStreamReaderOptions *options)#

从字节输入流初始化 ArrowArrayStream。

字节流必须以 Schema 消息开头，后跟零个或多个 RecordBatch 消息，如 Arrow IPC 流格式规范中所述。成功返回 NANOARROW_OK。如果返回 NANOARROW_OK，则 ArrowArrayStream 将拥有 input_stream 的所有权，调用者负责释放 out。

ArrowErrorCode ArrowIpcEncoderInit(struct ArrowIpcEncoder *encoder)#

初始化编码器。

如果返回 NANOARROW_OK，则调用者必须调用ArrowIpcEncoderReset()来释放此函数分配的资源。

void ArrowIpcEncoderReset(struct ArrowIpcEncoder *encoder)#: 释放与编码器关联的所有资源。

ArrowErrorCode ArrowIpcEncoderFinalizeBuffer(struct ArrowIpcEncoder *encoder, char encapsulate, struct ArrowBuffer *out)#

将最近编码的消息最终确定到缓冲区中。

如果指定，则消息将被封装（以延续标记和标题大小为前缀，并以 0 填充到 8 字节的倍数）。

编码消息的字节将追加到提供的缓冲区。

ArrowErrorCode ArrowIpcEncoderEncodeSchema(struct ArrowIpcEncoder *encoder, const struct ArrowSchema *schema, struct ArrowError *error)#

编码 ArrowSchema。

如果分配失败，则返回 ENOMEM，否则返回 NANOARROW_OK。

ArrowErrorCode ArrowIpcEncoderEncodeSimpleRecordBatch(struct ArrowIpcEncoder *encoder, const struct ArrowArrayView *array_view, struct ArrowBuffer *body_buffer, struct ArrowError *error)#

将结构化类型的 ArrayView 编码为 flatbuffer RecordBatch，嵌入到 Message 中。

主体缓冲区被连接成一个连续的、填充的 body_buffer。

如果分配失败，则返回 ENOMEM，否则返回 NANOARROW_OK。

void ArrowIpcOutputStreamMove(struct ArrowIpcOutputStream *src, struct ArrowIpcOutputStream *dst)#: 将 ArrowIpcOutputStream 的所有权转移。

ArrowErrorCode ArrowIpcOutputStreamInitBuffer(struct ArrowIpcOutputStream *stream, struct ArrowBuffer *output)#

从 ArrowBuffer 创建一个输出流。

写入流的所有字节都将被追加到缓冲区。流不拥有缓冲区。

ArrowErrorCode ArrowIpcOutputStreamInitFile(struct ArrowIpcOutputStream *stream, void *file_ptr, int close_on_release)#

从 C FILE* 指针创建一个输出流。

请注意，ArrowIpcOutputStream 没有机制来通信错误，如果 file_ptr 无法关闭。如果需要这种行为，请将 close_on_release 传递为 false，并独立于流处理文件关闭。

ArrowErrorCode ArrowIpcOutputStreamWrite(struct ArrowIpcOutputStream *stream, struct ArrowBufferView data, struct ArrowError *error)#: 写入流，尝试再次写入，直到所有内容都被写入或流出错。

ArrowErrorCode ArrowIpcWriterInit(struct ArrowIpcWriter *writer, struct ArrowIpcOutputStream *output_stream)#

从 ArrowArrayStream 初始化字节输出流。

成功时返回 NANOARROW_OK。如果返回 NANOARROW_OK，则写入器将拥有输出字节流，调用者负责通过调用 ArrowIpcWriterReset() 来释放写入器。

void ArrowIpcWriterReset(struct ArrowIpcWriter *writer)#: 释放与写入器关联的所有资源。

ArrowErrorCode ArrowIpcWriterWriteSchema(struct ArrowIpcWriter *writer, const struct ArrowSchema *in, struct ArrowError *error)#

将模式写入输出字节流。

错误从底层编码器和输出字节流传播。

ArrowErrorCode ArrowIpcWriterWriteArrayView(struct ArrowIpcWriter *writer, const struct ArrowArrayView *in, struct ArrowError *error)#

将数组视图写入输出字节流。

数组视图可以是 NULL，在这种情况下，将写入 EOS。写入器不会检查是否已经写入模式。

错误从底层编码器和输出字节流传播，

ArrowErrorCode ArrowIpcWriterWriteArrayStream(struct ArrowIpcWriter *writer, struct ArrowArrayStream *in, struct ArrowError *error)#

将整个流（包括 EOS）写入输出字节流。

错误从底层编码器、数组流和输出字节流传播。

ArrowErrorCode ArrowIpcWriterStartFile(struct ArrowIpcWriter *writer, struct ArrowError *error)#

开始写入一个 IPC 文件。

写入 Arrow IPC 魔数并设置写入器以跟踪已写入的块。

ArrowErrorCode ArrowIpcWriterFinalizeFile(struct ArrowIpcWriter *writer, struct ArrowError *error)#

完成写入一个 IPC 文件。

写入 IPC 文件的页脚、页脚大小和结束魔数。

struct ArrowIpcSharedBuffer#: #include <nanoarrow_ipc.h>

表示一个引用计数缓冲区的结构，可以传递给 ArrowIpcDecoderDecodeArrayFromShared()。

struct ArrowIpcDecoder#

#include <nanoarrow_ipc.h>

Arrow IPC 消息的解码器。

此结构旨在由调用者分配，使用 ArrowIpcDecoderInit() 初始化，并使用 ArrowIpcDecoderReset() 释放。这些字段不应由调用者修改，但可以在调用 ArrowIpcDecoderPeekHeader()、ArrowIpcDecoderVerifyHeader() 或 ArrowIpcDecoderDecodeHeader() 后读取。

公共成员

enum ArrowIpcMessageType message_type#: 最后验证或解码的消息类型。

enum ArrowIpcMetadataVersion metadata_version#: 当前模式消息指示的元数据版本。

enum ArrowIpcEndianness endianness#: 当前模式消息指示的缓冲区字节序。

int32_t feature_flags#: 当前模式消息指示使用的 Arrow IPC 功能。

enum ArrowIpcCompressionType codec#: 当前记录批消息使用的压缩。

int32_t header_size_bytes#

当前头消息的字节数。

此值包括头消息内容开始前的 8 个字节以及使头消息大小为 8 个字节倍数所需的任何填充字节。

int64_t body_size_bytes#: 即将到来的主体消息的字节数。

struct ArrowIpcFooter *footer#: 最后解码的页脚。

警告

此 API 目前仅供集成测试使用；风险自负。

void *private_data#: 此库管理的私有资源。

struct ArrowIpcInputStream#

#include <nanoarrow_ipc.h>

一个用户可扩展的输入数据源。

公共成员

ArrowErrorCode (*read)(struct ArrowIpcInputStream *stream, uint8_t *buf, int64_t buf_size_bytes, int64_t *size_read_out, struct ArrowError *error)#

从 stream 中读取最多 buf_size_bytes 到 buf 中。

实际读取的字节数放在 size_read_out 指向的值中。成功时返回 NANOARROW_OK。

void (*release)(struct ArrowIpcInputStream *stream)#

释放 stream 及其可能持有的任何资源。

释放回调实现必须将 release 成员设置为 NULL。调用者必须在调用 read() 或 release() 之前检查 release 回调是否为 NULL。

void *private_data#: 私有实现定义数据。

struct ArrowIpcArrayStreamReaderOptions#

#include <nanoarrow_ipc.h>

用于 ArrowIpcArrayStreamReaderInit() 的选项。

公共成员

int64_t field_index#

要提取的字段索引。

默认为 -1（即读取所有字段）。请注意，此字段索引引用子级的扁平化树，不一定与列索引相同。

int use_shared_buffers#

设置为非零值以在解码的数组之间共享消息体缓冲区。

当（1）使用内存映射 IO（因为未引用的文件部分通常不会加载到内存中）或（2）如果所有列的所有数据都将被引用时，共享缓冲区是一个不错的选择。在加载单个字段时，使用共享缓冲区可能没有任何优势。默认情况下，值为 ArrowIpcSharedBufferIsThreadSafe()。

struct ArrowIpcEncoder#

#include <nanoarrow_ipc.h>

用于 Arrow IPC 消息的编码器。

此结构旨在由调用者分配，使用 ArrowIpcEncoderInit() 初始化，并使用 ArrowIpcEncoderReset() 释放。

公共成员

void *private_data#: 此库管理的私有资源。

struct ArrowIpcOutputStream#

#include <nanoarrow_ipc.h>

用户可扩展的输出数据接收器。

公共成员

ArrowErrorCode (*write)(struct ArrowIpcOutputStream *stream, const void *buf, int64_t buf_size_bytes, int64_t *size_written_out, struct ArrowError *error)#

从流中写入最多 buf_size_bytes 到 buf。

实际写入的字节数将放置在 size_read_out 指向的值中。如果成功，则返回 NANOARROW_OK。

void (*release)(struct ArrowIpcOutputStream *stream)#

释放 stream 及其可能持有的任何资源。

释放回调实现必须将 release 成员设置为 NULL。调用者必须在调用 read() 或 release() 之前检查 release 回调是否为 NULL。

void *private_data#: 私有实现定义数据。

struct ArrowIpcWriter#

#include <nanoarrow_ipc.h>

一个流写入器，它将 Schema 和 ArrowArray 编码成 IPC 字节流。

此结构旨在由调用者分配，使用 ArrowIpcWriterInit() 初始化，并使用 ArrowIpcWriterReset() 释放。

公共成员

void *private_data#: 此库管理的私有资源。

C++ 助手#

group nanoarrow_ipc_hpp-unique

将 nanoarrow.hpp 中的唯一对象包装器扩展到包括在 nanoarrow_ipc.h 标头中定义的 C 结构。

类型定义

using UniqueDecoder = internal::Unique<struct ArrowIpcDecoder>#: 包装唯一结构 ArrowIpcDecoder 的类。

using UniqueFooter = internal::Unique<struct ArrowIpcFooter>#: 包装唯一结构 ArrowIpcFooter 的类。

using UniqueEncoder = internal::Unique<struct ArrowIpcEncoder>#: 包装唯一结构 ArrowIpcEncoder 的类。

using UniqueInputStream = internal::Unique<struct ArrowIpcInputStream>#: 包装唯一结构 ArrowIpcInputStream 的类。

using UniqueOutputStream = internal::Unique<struct ArrowIpcOutputStream>#: 封装了唯一结构体的类 ArrowIpcOutputStream。

using UniqueWriter = internal::Unique<struct ArrowIpcWriter>#: 封装了唯一结构体的类 ArrowIpcWriter。