Struct DeviceBuffer

Source

pub struct DeviceBuffer<T: Copy> { /* private fields */ }

Expand description

A contiguous buffer of T elements allocated in GPU device memory.

The buffer owns the underlying CUdeviceptr allocation and frees it on drop. All copy operations validate that source and destination lengths match, returning CudaError::InvalidValue on mismatch.

Implementations§

Source §

impl<T: Copy> DeviceBuffer<T>

Source

pub fn view_as<U: Copy>(&self) -> CudaResult<BufferView<'_, U>>

Reinterprets this buffer as a different element type U (immutable).

The total byte size of the buffer must be evenly divisible by size_of::(). The resulting view has byte_size / size_of::() elements.

§Errors

Returns CudaError::InvalidValue if:

size_of::() is zero (ZST).
The buffer’s byte size is not divisible by size_of::().
The buffer’s device pointer is not aligned to align_of::().

Source

pub fn view_as_mut<U: Copy>(&mut self) -> CudaResult<BufferViewMut<'_, U>>

Reinterprets this buffer as a different element type U (mutable).

The total byte size of the buffer must be evenly divisible by size_of::(). The resulting view has byte_size / size_of::() elements.

§Errors

Returns CudaError::InvalidValue if:

size_of::() is zero (ZST).
The buffer’s byte size is not divisible by size_of::().
The buffer’s device pointer is not aligned to align_of::().

Source §

impl<T: Copy> DeviceBuffer<T>

Source

pub fn alloc(n: usize) -> CudaResult<Self>

Allocates a device buffer capable of holding n elements of type T.

§Errors

CudaError::InvalidValue if n is zero.
CudaError::OutOfMemory if the GPU cannot satisfy the request.
Other driver errors propagated from cuMemAlloc_v2.

Source

pub fn zeroed(n: usize) -> CudaResult<Self>

Allocates a device buffer of n elements and zero-initialises every byte.

This is equivalent to alloc followed by a cuMemsetD8_v2 call that writes 0 to every byte.

The zero-fill is fully completed on the device before this function returns: cuMemsetD8_v2 is issued on the legacy default stream and is asynchronous with respect to the host for device memory, so the returned buffer would otherwise not be guaranteed zeroed relative to work later submitted on a CU_STREAM_NON_BLOCKING stream (which does not implicitly synchronise with the default stream). A context synchronise after the memset makes the “every byte is 0” postcondition hold for any consumer stream, closing a data race where a kernel on a non-blocking stream could read/overwrite this buffer concurrently with the pending zero-fill.

§Errors

Same as alloc, plus any error from cuMemsetD8_v2 or the context synchronise.

Source

pub fn from_host(data: &[T]) -> CudaResult<Self>

Allocates a device buffer and copies the contents of data into it.

The resulting buffer has the same length as the input slice.

§Errors

CudaError::InvalidValue if data is empty.
Other driver errors from allocation or the host-to-device copy.

Source

pub unsafe fn from_raw(ptr: CUdeviceptr, len: usize) -> Self

Wraps an externally-owned device pointer in a non-owning DeviceBuffer view without allocating.

The returned buffer points at the existing allocation described by ptr and len, and exposes the full DeviceBuffer API (copies, slicing, as_device_ptr, and use as a matrix operand in oxicuda-blas) over that memory. Because the view does not own the allocation, its Drop is a no-op: it will not call cuMemFree_v2. Ownership and the lifetime of the underlying memory remain entirely with the original owner (e.g. another CUDA library, cudarc, or a foreign allocator).

This enables zero-copy interop: a consumer that already holds a resident device allocation can wrap it here and run OxiCUDA operations in place, with no host round-trip and no extra device allocation.

§Safety

The caller must guarantee all of the following:

ptr is a valid CUDA device pointer into an allocation of at least len * size_of::<T>() bytes, correctly aligned for T, and associated with the CUDA context that subsequent OxiCUDA operations run under.
The pointed-to memory contains a valid, initialised [T; len] (or is only used as a write target before being read).
The underlying allocation outlives this DeviceBuffer view: the original owner must not free, reallocate, or invalidate ptr while this view (or any DeviceSlice borrowed from it) is alive.
No other live DeviceBuffer owns the same ptr (to avoid a double-free) and aliasing rules are respected when the view is used mutably (e.g. as a MatrixDescMut output operand).

A zero len is permitted (unlike alloc) since no allocation is performed; a ptr of 0 is also permitted for a zero-length view, but pointer/length validity is the caller’s responsibility.

§Example

// `raw` is a device pointer owned elsewhere (e.g. obtained from another
// CUDA library) pointing at `n` resident `f32` elements.
// SAFETY: `raw` is valid for `n` f32s and outlives `view`.
let view = unsafe { DeviceBuffer::<f32>::from_raw(raw, n) };
// `view` can now be used with oxicuda-blas / copies; dropping it does
// NOT free `raw`.
assert_eq!(view.len(), n);

Source

pub fn copy_from_host(&mut self, src: &[T]) -> CudaResult<()>

Copies data from a host slice into this device buffer (synchronous).

The slice length must exactly match the buffer length.

§Errors

CudaError::InvalidValue if src.len() != self.len().
Other driver errors from cuMemcpyHtoD_v2.

Source

pub fn copy_to_host(&self, dst: &mut [T]) -> CudaResult<()>

Copies this device buffer’s contents into a host slice (synchronous).

The slice length must exactly match the buffer length.

§Errors

CudaError::InvalidValue if dst.len() != self.len().
Other driver errors from cuMemcpyDtoH_v2.

Source

pub fn copy_from_device(&mut self, src: &DeviceBuffer<T>) -> CudaResult<()>

Copies the entire contents of another device buffer into this one.

Both buffers must have the same length.

§Errors

CudaError::InvalidValue if src.len() != self.len().
Other driver errors from cuMemcpyDtoD_v2.

Source

pub fn copy_from_host_async( &mut self, src: &[T], stream: &Stream, ) -> CudaResult<()>

Asynchronously copies data from a host slice into this device buffer.

The copy is enqueued on stream and may not be complete when this function returns. The caller must ensure that src remains valid (i.e., is not moved or dropped) until the stream has been synchronised. For guaranteed correctness, prefer using a PinnedBuffer as the source.

§Errors

CudaError::InvalidValue if src.len() != self.len().
Other driver errors from cuMemcpyHtoDAsync_v2.

Source

pub fn copy_to_host_async( &self, dst: &mut [T], stream: &Stream, ) -> CudaResult<()>

Asynchronously copies this device buffer’s contents into a host slice.

The copy is enqueued on stream and may not be complete when this function returns. The caller must ensure that dst remains valid and is not read until the stream has been synchronised. For guaranteed correctness, prefer using a PinnedBuffer as the destination.