Struct BufferHandle 

pub struct BufferHandle(/* private fields */);

A handle to a buffer allocation.

There are two kinds of buffer allocations supported:

• host allocations, which were allocated by the global allocator and reside in main memory
• device allocations, which are remote to the CPU and live on a GPU or other external device.

A device allocation can be copied to the host, yielding a new ByteBuffer containing the copied data. Copying can fail at runtime, error recovery is system-dependent.

Implementations

impl BufferHandle

pub fn new_host(byte_buffer: ByteBuffer) -> Self

Create a new handle to a host ByteBuffer.

pub fn new_device(device: Arc<dyn DeviceBuffer>) -> Self

Create a new handle to a memory allocation that exists on an external device.

Allocations on external devices are not cheaply accessible from the CPU and most be copied into new memory when we read them.

impl BufferHandle

pub fn is_on_device(&self) -> bool

Returns true if this buffer resides on the device (GPU).

pub fn is_on_host(&self) -> bool

Returns true if this buffer resides on the host (CPU).

pub fn len(&self) -> usize

Gets the size of the buffer, in bytes.

pub fn alignment(&self) -> Alignment

Returns the alignment of the buffer.

pub fn is_aligned_to(&self, alignment: Alignment) -> bool

Returns true if the buffer is aligned to the given alignment.

pub fn ensure_aligned(self, alignment: Alignment) -> VortexResult<Self>

Ensure the buffer satisfies the requested alignment.

Both host and device buffers will be copied if necessary to satisfy the alignment.

pub fn is_empty(&self) -> bool

Check if the buffer is empty.

pub fn slice(&self, range: Range<usize>) -> Self

Creates a new handle to a subrange of memory at the given bind range.

Example

let handle1 = BufferHandle::new_host(buffer![1u8,2,3,4]);
let handle2 = handle1.slice(1..4);
assert_eq!(handle2.unwrap_host(), buffer![2u8,3,4]);

pub fn slice_typed<T: Sized>(&self, range: Range<usize>) -> Self

Reinterpret the pointee as a buffer of T and slice the provided element range.

Example

let values = buffer![1u32, 2u32, 3u32, 4u32];
let handle = BufferHandle::new_host(values.into_byte_buffer());
let sliced = handle.slice_typed::<u32>(1..4);
let result = Buffer::<u32>::from_byte_buffer(sliced.to_host_sync());
assert_eq!(result, buffer![2, 3, 4]);

pub fn unwrap_host(self) -> ByteBuffer

Unwraps the handle as host memory.

Panics

This will panic if the handle points to device memory.

pub fn unwrap_device(self) -> Arc<dyn DeviceBuffer>

Unwraps the handle as device memory.

Panics

This will panic if the handle points to host memory.

pub fn as_host_opt(&self) -> Option<&ByteBuffer>

Downcast this handle as a handle to a host-resident buffer, or None.

pub fn as_device_opt(&self) -> Option<&Arc<dyn DeviceBuffer>>

Downcast this handle as a handle to a device buffer, or None.

pub fn as_host(&self) -> &ByteBuffer

A version of as_host_opt that panics if the allocation is not a host allocation.

pub fn as_device(&self) -> &Arc<dyn DeviceBuffer>

A version of as_device_opt that panics if the allocation is not a device allocation.

pub fn to_host_sync(&self) -> ByteBuffer

Returns a host-resident copy of the data in the buffer.

If the data was already host-resident, this is trivial.

If the data was device-resident, data will be copied from the device to a new allocation on the host.

Panics

This function will never panic if the data is already host-resident.

For a device-resident handle, any errors triggered by the copying from device to host will result in a panic.

See also: try_to_host.

pub fn into_host_sync(self) -> ByteBuffer

Returns a host-resident copy of the data behind the handle, consuming the handle.

If the data was already host-resident, this completes trivially.

See also to_host.

Panics

See the panic documentation on to_host.

pub fn try_to_host_sync(&self) -> VortexResult<ByteBuffer>

Attempts to load this buffer into a host-resident allocation.

If the allocation is already host-resident, this trivially completes with success.

If it is a device allocation, then this issues an operation that attempts to copy the data from the device into a host-resident buffer, and returns a handle to that buffer.

pub fn try_into_host_sync(self) -> VortexResult<ByteBuffer>

Attempts to load this buffer into a host-resident allocation, consuming the handle.

See also try_to_host.

pub fn try_to_host( &self, ) -> VortexResult<BoxFuture<'static, VortexResult<ByteBuffer>>>

Asynchronously copies the buffer to the host.

This is a no-op if the buffer is already on the host.

Returns

A future that resolves to the host buffer when the copy completes.

Errors

Returns an error if the async copy operation fails.

pub fn try_into_host( self, ) -> VortexResult<BoxFuture<'static, VortexResult<ByteBuffer>>>

Asynchronously copies the buffer to the host, consuming the handle.

This is a no-op if the buffer is already on the host.

Returns

A future that resolves to the host buffer when the copy completes.

Errors

Returns an error if the async copy operation fails.

pub fn to_host(&self) -> BoxFuture<'static, ByteBuffer>

Asynchronously copies the buffer to the host.

Panics

Any errors triggered by the copying from device to host will result in a panic.

pub fn into_host(self) -> BoxFuture<'static, ByteBuffer>

Asynchronously copies the buffer to the host, consuming the handle.

Panics

Any errors triggered by the copying from device to host will result in a panic.

Trait Implementations

impl ArrayEq for BufferHandle

fn array_eq(&self, other: &Self, precision: Precision) -> bool

impl ArrayHash for BufferHandle

fn array_hash<H: Hasher>(&self, state: &mut H, precision: Precision)

impl Clone for BufferHandle

fn clone(&self) -> BufferHandle

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BufferHandle

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl TryFrom<BufferHandle> for ArrayParts

type Error = VortexError

The type returned in the event of a conversion error.

fn try_from(value: BufferHandle) -> Result<Self, Self::Error>

Performs the conversion.