设备扩展参考

C API

group Nanoarrow 设备 扩展

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

函数

NANOARROW_DLL ArrowErrorCode ArrowDeviceCheckRuntime (struct ArrowError *error)

检查 nanoarrow 运行时，以确保运行/构建版本匹配。

NANOARROW_DLL struct ArrowDevice * ArrowDeviceCpu (void)

指向静态分配的 CPU 设备单例的指针。

NANOARROW_DLL void ArrowDeviceInitCpu (struct ArrowDevice *device)

使用 CPU 设备初始化用户分配的设备结构体。

NANOARROW_DLL struct ArrowDevice * ArrowDeviceResolve (ArrowDeviceType device_type, int64_t device_id)

从类型 + 标识符解析设备指针。

根据此版本的设备扩展是与哪些库一起构建的，某些设备类型可能受支持，也可能不受支持。CPU 类型始终受支持。对于不存在或无法作为单例返回的设备，返回 NULL。调用者不得释放所指向的设备。

NANOARROW_DLL ArrowErrorCode ArrowDeviceArrayInitAsync (struct ArrowDevice *device, struct ArrowDeviceArray *device_array, struct ArrowArray *array, void *sync_event, void *stream)

初始化一个 ArrowDeviceArray。

给定一个其缓冲区/释放回调已适当设置的 ArrowArray，初始化一个 ArrowDeviceArray。如果 sync_event 不为 null，则其所有权将转移到输出数组。如果 stream 不为 null，则必须记录事件，以便它捕获在流上完成的工作。如果返回 NANOARROW_OK，则 array 和 sync_event 的所有权将转移到 device_array。调用者保留 stream 的所有权。

static inline ArrowErrorCode ArrowDeviceArrayInit(struct ArrowDevice *device, struct ArrowDeviceArray *device_array, struct ArrowArray *array, void *sync_event)

不使用流初始化一个 ArrowDeviceArray。

不使用流初始化 ArrowDeviceArray 的便捷包装器。

NANOARROW_DLL ArrowErrorCode ArrowDeviceBasicArrayStreamInit (struct ArrowDeviceArrayStream *device_array_stream, struct ArrowArrayStream *array_stream, struct ArrowDevice *device)

从现有的 ArrowArrayStream 初始化一个 ArrowDeviceArrayStream。

将一个包含已由指定设备分配的 ArrowDeviceArray 对象的 ArrowArrayStream 包装为 ArrowDeviceArrayStream。此函数将 array_stream 的所有权移动到 device_array_stream。如果此函数返回 NANOARROW_OK，调用者负责释放 ArrowDeviceArrayStream。

NANOARROW_DLL void ArrowDeviceArrayViewInit (struct ArrowDeviceArrayView *device_array_view)

初始化一个 ArrowDeviceArrayView。

将设备数组视图结构体的内存清零。调用者必须使用 nanoarrow 核心函数来初始化 array_view 成员，这些函数可以从类型标识符或模式初始化。

NANOARROW_DLL void ArrowDeviceArrayViewReset (struct ArrowDeviceArrayView *device_array_view)

释放底层的 ArrowArrayView。

NANOARROW_DLL ArrowErrorCode ArrowDeviceArrayViewSetArrayMinimal (struct ArrowDeviceArrayView *device_array_view, struct ArrowDeviceArray *device_array, struct ArrowError *error)

从设备数组中设置最小的 ArrowArrayView 缓冲区信息。

ArrowArrayViewSetArrayMinimal() 的一个薄包装，它不尝试通过从设备复制数据来解析可变长度缓冲区的缓冲区大小。

NANOARROW_DLL ArrowErrorCode ArrowDeviceArrayViewSetArrayAsync (struct ArrowDeviceArrayView *device_array_view, struct ArrowDeviceArray *device_array, void *stream, struct ArrowError *error)

从设备数组中设置 ArrowArrayView 缓冲区信息。

运行 ArrowDeviceArrayViewSetArrayMinimal()，但如果需要，还会通过从设备复制数据来设置可变长度缓冲区的缓冲区大小。如果提供了流，它将用于执行解析缓冲区大小所需的任何复制操作。

static inline ArrowErrorCode ArrowDeviceArrayViewSetArray(struct ArrowDeviceArrayView *device_array_view, struct ArrowDeviceArray *device_array, struct ArrowError *error)

在不使用流的情况下，从设备数组设置 ArrowArrayView 缓冲区信息。

未提供流的情况下的便捷包装器。

NANOARROW_DLL ArrowErrorCode ArrowDeviceArrayViewCopyAsync (struct ArrowDeviceArrayView *src, struct ArrowDevice *device_dst, struct ArrowDeviceArray *dst, void *stream)

将 ArrowDeviceArrayView 复制到设备。

如果提供了流，它将用于异步启动复制。请注意，这意味着 src 中的所有指针在流同步之前都将保持有效。

static inline ArrowErrorCode ArrowDeviceArrayViewCopy(struct ArrowDeviceArrayView *src, struct ArrowDevice *device_dst, struct ArrowDeviceArray *dst)

在不使用流的情况下，将 ArrowDeviceArrayView 复制到设备。

未提供流的情况下的便捷包装器。

NANOARROW_DLL ArrowErrorCode ArrowDeviceArrayMoveToDevice (struct ArrowDeviceArray *src, struct ArrowDevice *device_dst, struct ArrowDeviceArray *dst)

如果可能，将 ArrowDeviceArray 移动到设备。

将尝试在不复制缓冲区的情况下将设备数组移动到设备。这可能会导致设备数组的性能特征与已复制的数组不同。如果设备之间无法进行零拷贝移动，则返回 ENOTSUP。

NANOARROW_DLL ArrowErrorCode ArrowDeviceBufferInitAsync (struct ArrowDevice *device_src, struct ArrowBufferView src, struct ArrowDevice *device_dst, struct ArrowBuffer *dst, void *stream)

分配设备缓冲区并复制现有内容。

如果提供了流，它将用于异步启动复制。请注意，这意味着 src 在流同步之前将保持有效。

static inline ArrowErrorCode ArrowDeviceBufferInit(struct ArrowDevice *device_src, struct ArrowBufferView src, struct ArrowDevice *device_dst, struct ArrowBuffer *dst)

不使用流分配设备缓冲区并复制现有内容。

未提供流的情况下的便捷包装器。

NANOARROW_DLL ArrowErrorCode ArrowDeviceBufferMove (struct ArrowDevice *device_src, struct ArrowBuffer *src, struct ArrowDevice *device_dst, struct ArrowBuffer *dst)

如果可能，在不复制的情况下将缓冲区移动到设备。

如果设备之间无法进行零拷贝移动，则返回 ENOTSUP。

NANOARROW_DLL ArrowErrorCode ArrowDeviceBufferCopyAsync (struct ArrowDevice *device_src, struct ArrowBufferView src, struct ArrowDevice *device_dst, struct ArrowBufferView dst, void *stream)

将缓冲区复制到预分配的设备内存中。

如果提供了流，它将用于异步启动复制。请注意，这意味着 src 在流同步之前将保持有效。

static inline ArrowErrorCode ArrowDeviceBufferCopy(struct ArrowDevice *device_src, struct ArrowBufferView src, struct ArrowDevice *device_dst, struct ArrowBufferView dst)

将缓冲区复制到预分配的设备内存中。

如果设备之间无法进行零拷贝移动，则返回 ENOTSUP。

struct ArrowDeviceArrayView

struct ArrowDevice

#include <nanoarrow_device.h>

一个设备包装器，带有用于基本内存管理任务的回调。

目前所有设备对象都实现为单例；但是，随着实现的进展，这种情况可能会改变。

公共成员

ArrowDeviceType device_type

设备类型整数标识符（参见 ArrowDeviceArray）

int64_t device_id

设备标识符（参见 ArrowDeviceArray）

ArrowErrorCode (*array_init)(struct ArrowDevice *device, struct ArrowDeviceArray *device_array, struct ArrowArray *array, void *sync_event, void *stream)

从先前分配的 ArrowArray 初始化 ArrowDeviceArray。

给定一个设备和一个未初始化的 device_array，适当地填充 device_array 的字段。如果 sync_event 不为 null，则其所有权将转移到输出数组。如果 stream 不为 null，则必须记录事件，以便它捕获在流上完成的工作。如果返回 NANOARROW_OK，则 array 和 sync_event 的所有权将转移到 device_array。调用者保留 stream 的所有权。

ArrowErrorCode (*array_move)(struct ArrowDevice *device_src, struct ArrowDeviceArray *src, struct ArrowDevice *device_dst, struct ArrowDeviceArray *dst)

在不复制缓冲区的情况下，在设备之间移动 ArrowDeviceArray。

一些设备可以在不进行显式缓冲区复制的情况下移动 ArrowDeviceArray，尽管移动后的数组的性能特征可能与显式复制的数组不同，具体取决于设备。实现必须检查 device_src 和 device_dst，如果未准备好处理此操作，则返回 ENOTSUP。

ArrowErrorCode (*buffer_init)(struct ArrowDevice *device_src, struct ArrowBufferView src, struct ArrowDevice *device_dst, struct ArrowBuffer *dst, void *stream)

从现有内容初始化一个拥有所有权的缓冲区。

通过复制现有内容创建一个新缓冲区，其数据成员可以被 GPU 访问。实现必须使用提供的流（如果非 null）；如果实现需要提供流，则可能会出错。实现必须检查 device_src 和 device_dst，如果未准备好处理此操作，则返回 ENOTSUP。

ArrowErrorCode (*buffer_move)(struct ArrowDevice *device_src, struct ArrowBuffer *src, struct ArrowDevice *device_dst, struct ArrowBuffer *dst)

将一个拥有所有权的缓冲区移动到设备。

通过移动现有缓冲区来创建一个新缓冲区，其数据成员可以被 GPU 访问。如果返回 NANOARROW_OK，src 将已被实现释放或移动，而 dst 必须由调用者释放。实现必须检查 device_src 和 device_dst，如果未准备好处理此操作，则返回 ENOTSUP。

ArrowErrorCode (*buffer_copy)(struct ArrowDevice *device_src, struct ArrowBufferView src, struct ArrowDevice *device_dst, struct ArrowBufferView dst, void *stream)

将一段内存复制到预分配的缓冲区中。

与其他缓冲区操作不同，此操作旨在支持复制非常小的内存片。实现必须使用提供的流（如果非 null）；如果实现需要提供流，则可能会出错。实现必须检查 device_src 和 device_dst，如果未准备好处理此操作，则返回 ENOTSUP。

ArrowErrorCode (*synchronize_event)(struct ArrowDevice *device, void *sync_event, void *stream, struct ArrowError *error)

同步事件和/或流。

如果 sync_event 和 stream 都不为 null，则确保流等待事件。如果只有 sync_event 不为 null，则确保事件捕获的工作与 CPU 同步。如果只有 stream 不为 null，则确保流与 CPU 同步。

void (*release)(struct ArrowDevice *device)

释放此设备及其持有的任何资源。

void *private_data

不透明的、特定于实现的数据。

C++ 辅助函数

group 唯一 对象 包装器

扩展 nanoarrow.hpp 中的唯一对象包装器，以包含在 nanoarrow_device.h 头文件中定义的 C 结构体。

类型定义

using UniqueDeviceArray = internal::Unique<struct ArrowDeviceArray>

包装唯一结构体 ArrowDeviceArray 的类。

using UniqueDeviceArrayStream = internal::Unique<struct ArrowDeviceArrayStream>

包装唯一结构体 ArrowDeviceArrayStream 的类。

using UniqueDevice = internal::Unique<struct ArrowDevice>

包装唯一结构体 ArrowDevice 的类。

using UniqueDeviceArrayView = internal::Unique<struct ArrowDeviceArrayView>

包装唯一结构体 ArrowDeviceArrayView 的类。

Arrow C 设备接口

group Arrow C 设备 接口

Arrow 设备和流接口是 Arrow C 设备数据和 Arrow C 设备流接口（https://arrow.apache.org/docs/format/CDeviceDataInterface.html）的一部分。有关这些结构的详细文档，请参阅 Arrow 文档。

宏定义

ARROW_C_DEVICE_DATA_INTERFACE

ARROW_DEVICE_CPU

ARROW_DEVICE_CUDA

ARROW_DEVICE_CUDA_HOST

ARROW_DEVICE_OPENCL

ARROW_DEVICE_VULKAN

ARROW_DEVICE_METAL

ARROW_DEVICE_VPI

ARROW_DEVICE_ROCM

ARROW_DEVICE_ROCM_HOST

ARROW_DEVICE_EXT_DEV

ARROW_DEVICE_CUDA_MANAGED

ARROW_DEVICE_ONEAPI

ARROW_DEVICE_WEBGPU

ARROW_DEVICE_HEXAGON

ARROW_C_DEVICE_STREAM_INTERFACE

类型定义

typedef int32_t ArrowDeviceType

函数

static inline void ArrowDeviceArrayMove(struct ArrowDeviceArray *src, struct ArrowDeviceArray *dst)

将 src 的内容移动到 dst 中，并将 src->array.release 设置为 NULL。

struct ArrowDeviceArray

公共成员

struct ArrowArray array

int64_t device_id

ArrowDeviceType device_type

void *sync_event

int64_t reserved[3]

struct ArrowDeviceArrayStream

公共成员

ArrowDeviceType device_type

int (*get_schema)(struct ArrowDeviceArrayStream*, struct ArrowSchema*)

int (*get_next)(struct ArrowDeviceArrayStream*, struct ArrowDeviceArray*)

const char *(*get_last_error)(struct ArrowDeviceArrayStream*)

void (*release)(struct ArrowDeviceArrayStream*)

void *private_data