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.

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 ArrowDeviceArrayInitAsync(struct ArrowDevice *device, struct ArrowDeviceArray *device_array, struct ArrowArray *array, void *sync_event, void *stream)#

Initialize an ArrowDeviceArray.

Given an ArrowArray whose buffers/release callback has been set appropriately, initialize an ArrowDeviceArray. If sync_event is non-null, ownership is transferred to the output array. If stream is non-null, the event must be recorded such that it captures the work done on stream. If NANOARROW_OK is returned, ownership of array and sync_event is transferred to device_array. The caller retains ownership of stream.

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

Initialize an ArrowDeviceArray without a stream.

Convenience wrapper to initialize an ArrowDeviceArray without a stream.

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.

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 ArrowDeviceArrayViewSetArrayAsync(struct ArrowDeviceArrayView *device_array_view, struct ArrowDeviceArray *device_array, void *stream, 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 if needed. If stream is provided it will be used to do any copying required to resolve buffer sizes.

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

Set ArrowArrayView buffer information from a device array without a stream.

Convenience wrapper for the case where no stream is provided.

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

Copy an ArrowDeviceArrayView to a device.

If stream is provided, it will be used to launch copies asynchronously. Note that this implies that all pointers in src will remain valid until the stream is synchronized.

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

Copy an ArrowDeviceArrayView to a device without a stream.

Convenience wrapper for the case where no stream is provided.

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. Returns ENOTSUP if a zero-copy move between devices is not possible.

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

Allocate a device buffer and copying existing content.

If stream is provided, it will be used to launch copies asynchronously. Note that this implies that src will remain valid until the stream is synchronized.

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

Allocate a device buffer and copying existing content without a stream.

Convenience wrapper for the case where no stream is provided.

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

Move a buffer to a device without copying if possible.

Returns ENOTSUP if a zero-copy move between devices is not possible.

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

Copy a buffer into preallocated device memory.

If stream is provided, it will be used to launch copies asynchronously. Note that this implies that src will remain valid until the stream is synchronized.

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

Copy a buffer into preallocated devie memory.

Returns ENOTSUP if a zero-copy move between devices is not possible.

struct ArrowDeviceArrayView#

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, void *sync_event, void *stream)#

Initialize an ArrowDeviceArray from a previously allocated ArrowArray.

Given a device and an uninitialized device_array, populate the fields of the device_array appropriately. If sync_event is non-null, ownership is transferred to the output array. If stream is non-null, the event must be recorded such that it captures the work done on stream. If NANOARROW_OK is returned, ownership of array and sync_event is transferred to device_array. The caller retains ownership of stream.

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. Implementations must check device_src and device_dst and return ENOTSUP if not prepared to handle this operation.

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

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 use the provided stream if non-null; implementations may error if they require a stream to be provided. 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, void *stream)#

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 use the provided stream if non-null; implementations may error if they require a stream to be provided. 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, void *stream, struct ArrowError *error)#

Synchronize an event and/or stream.

If both sync_event and stream are non-null, ensures that the stream waits on the event. If only sync_event is non-null, ensures that the work captured by the event is synchronized with the CPU. If only stream is non-null, ensures that stream is synchronized with the CPU.

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

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

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#