Device Extension Reference#

C API#

group nanoarrow_device

Except where noted, objects are not thread-safe and clients should take care to serialize accesses to methods.

Functions

ArrowErrorCode ArrowDeviceCheckRuntime(struct ArrowError *error)#: Checks the nanoarrow runtime to make sure the run/build versions match.

ArrowErrorCode ArrowDeviceArrayInit(struct ArrowDevice *device, struct ArrowDeviceArray *device_array, struct ArrowArray *array)#

Initialize an ArrowDeviceArray.

Given an ArrowArray whose buffers/release callback has been set appropriately, initialize an ArrowDeviceArray.

void ArrowDeviceArrayViewInit(struct ArrowDeviceArrayView *device_array_view)#

Initialize an ArrowDeviceArrayView.

Zeroes memory for the device array view struct. Callers must initialize the array_view member using nanoarrow core functions that can initialize from a type identifier or schema.

void ArrowDeviceArrayViewReset(struct ArrowDeviceArrayView *device_array_view)#: Release the underlying ArrowArrayView.

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

Set minimal ArrowArrayView buffer information from a device array.

A thin wrapper around ArrowArrayViewSetArrayMinimal() that does not attempt to resolve buffer sizes of variable-length buffers by copying data from the device.

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

Set ArrowArrayView buffer information from a device array.

Runs ArrowDeviceArrayViewSetArrayMinimal() but also sets buffer sizes for variable-length buffers by copying data from the device. This function will block on the device_array’s sync_event.

ArrowErrorCode ArrowDeviceArrayViewCopy(struct ArrowDeviceArrayView *src, struct ArrowDevice *device_dst, struct ArrowDeviceArray *dst)#: Copy an ArrowDeviceArrayView to a device.

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

Move an ArrowDeviceArray to a device if possible.

Will attempt to move a device array to a device without copying buffers. This may result in a device array with different performance charateristics than an array that was copied.

struct ArrowDevice *ArrowDeviceCpu(void)#: Pointer to a statically-allocated CPU device singleton.

void ArrowDeviceInitCpu(struct ArrowDevice *device)#: Initialize a user-allocated device struct with a CPU device.

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

Resolve a device pointer from a type + identifier.

Depending on which libraries this build of the device extension was built with, some device types may or may not be supported. The CPU type is always supported. Returns NULL for device that does not exist or cannot be returned as a singleton. Callers must not release the pointed-to device.

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

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

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

Initialize an ArrowDeviceArrayStream from an existing ArrowArrayStream.

Wrap an ArrowArrayStream of ArrowDeviceArray objects already allocated by the specified device as an ArrowDeviceArrayStream. This function moves the ownership of array_stream to the device_array_stream. If this function returns NANOARROW_OK, the caller is responsible for releasing the ArrowDeviceArrayStream.

struct ArrowDevice#

#include <nanoarrow_device.h>

A Device wrapper with callbacks for basic memory management tasks.

All device objects are currently implemented as singletons; however, this may change as implementations progress.

Public Members

ArrowDeviceType device_type#: The device type integer identifier (see ArrowDeviceArray)

int64_t device_id#: The device identifier (see ArrowDeviceArray)

ArrowErrorCode (*array_init)(struct ArrowDevice *device, struct ArrowDeviceArray *device_array, struct ArrowArray *array)#

Initialize an ArrowDeviceArray from a previously allocated ArrowArray.

Given a device and an uninitialized device_array, populate the fields of the device_array (including sync_event) appropriately. If NANOARROW_OK is returned, ownership of array is transferred to device_array. This function must allocate the appropriate sync_event and make its address available as device_array->sync_event (if sync_event applies to this device type).

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

Move an ArrowDeviceArray between devices without copying buffers.

Some devices can move an ArrowDeviceArray without an explicit buffer copy, although the performance characteristics of the moved array may be different than that of an explicitly copied one depending on the device.

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

Initialize an owning buffer from existing content.

Creates a new buffer whose data member can be accessed by the GPU by copying existing content. Implementations must check device_src and device_dst and return ENOTSUP if not prepared to handle this operation.

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

Move an owning buffer to a device.

Creates a new buffer whose data member can be accessed by the GPU by moving an existing buffer. If NANOARROW_OK is returned, src will have been released or moved by the implementation and dst must be released by the caller. Implementations must check device_src and device_dst and return ENOTSUP if not prepared to handle this operation.

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

Copy a section of memory into a preallocated buffer.

As opposed to the other buffer operations, this is designed to support copying very small slices of memory. Implementations must check device_src and device_dst and return ENOTSUP if not prepared to handle this operation.

ArrowErrorCode (*synchronize_event)(struct ArrowDevice *device, void *sync_event, struct ArrowError *error)#: Wait for an event on the CPU host.

void (*release)(struct ArrowDevice *device)#: Release this device and any resources it holds.

void *private_data#: Opaque, implementation-specific data.

struct ArrowDeviceArrayView#

C++ Helpers#

group nanoarrow_device_hpp-unique

Extends the unique object wrappers in nanoarrow.hpp to include C structs defined in the nanoarrow_device.h header.

Typedefs

using UniqueDeviceArray = internal::Unique<struct ArrowDeviceArray>#: Class wrapping a unique struct ArrowDeviceArray.

using UniqueDeviceArrayStream = internal::Unique<struct ArrowDeviceArrayStream>#: Class wrapping a unique struct ArrowDeviceArrayStream.

using UniqueDevice = internal::Unique<struct ArrowDevice>#: Class wrapping a unique struct ArrowDevice.

using UniqueDeviceArrayView = internal::Unique<struct ArrowDeviceArrayView>#: Class wrapping a unique struct ArrowDeviceArrayView.

Arrow C Device Interface#

group nanoarrow_device-arrow-cdata

The Arrow Device and Stream interfaces are part of the Arrow C Device Data and Arrow C Device stream interfaces (https://arrow.apache.org/docs/dev/format/CDeviceDataInterface.html). See the Arrow documentation for detailed documentation of these structures.

Defines

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#

Typedefs

typedef int32_t ArrowDeviceType#

Functions

static inline void ArrowDeviceArrayMove(struct ArrowDeviceArray *src, struct ArrowDeviceArray *dst)#: Move the contents of src into dst and set src->array.release to NULL.

struct ArrowDeviceArray#

Public Members

struct ArrowArray array#

int64_t device_id#

ArrowDeviceType device_type#

void *sync_event#

int64_t reserved[3]#

struct ArrowDeviceArrayStream#

Public Members

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#