设备扩展参考#

C API#

group nanoarrow_device

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

函数

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

struct ArrowDevice *ArrowDeviceCpu(void)#: 指向静态分配的 CPU 设备单例的指针。

void ArrowDeviceInitCpu(struct ArrowDevice *device)#: 使用 CPU 设备初始化用户分配的设备结构。

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

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

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

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

初始化一个 ArrowDeviceArray.

给定一个 ArrowArray，其缓冲区/释放回调已适当地设置，初始化一个 ArrowDeviceArray。如果 sync_event 非空，则所有权将转移到输出数组。如果 stream 非空，则必须记录事件，以便它捕获在 stream 上完成的工作。如果返回 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，没有 stream。

便利包装器，用于初始化一个 ArrowDeviceArray，没有 stream。

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.

void ArrowDeviceArrayViewInit(struct ArrowDeviceArrayView *device_array_view)#

初始化一个 ArrowDeviceArrayView.

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

void ArrowDeviceArrayViewReset(struct ArrowDeviceArrayView *device_array_view)#: 释放底层的 ArrowArrayView。

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

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

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

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 缓冲区信息，不使用流。

当没有提供流时，这是便利包装器。

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 复制到设备，不使用流。

当没有提供流时，这是便利包装器。

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

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

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

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)#

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

当没有提供流时，这是便利包装器。

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

如果可能，将缓冲区移动到设备而不进行复制。

如果无法在设备之间进行零复制移动，则返回 ENOTSUP。

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 不为空，则所有权将转移到输出数组。如果 stream 不为空，则必须记录事件以使其捕获在 stream 上完成的工作。如果返回 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。实现必须使用提供的 stream（如果非空）；如果需要提供 stream，实现可能会出错。实现必须检查 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)#

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

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

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

同步事件和/或流。

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

void (*release)(struct ArrowDevice *device)#: 释放此设备及其持有的所有资源。

void *private_data#: 不透明的、特定于实现的数据。

C++ 帮助程序#

group nanoarrow_device_hpp-unique

将 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 nanoarrow_device-arrow-cdata

Arrow 设备和流接口是 Arrow C 设备数据和 Arrow C 设备流接口的一部分 (https://arrow.apache.org/docs/dev/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#