Struct cust::memory::LockedBox

pub struct LockedBox<T: DeviceCopy> { /* private fields */ }

Page-locked box in host memory.

Page-locked memory

Modern OSes have the ability to page out memory pages to storage areas such as the disk to reduce RAM usage. However, this causes issues with certain things such as asynchronous memory copies because the memory may get paged out to disk while the driver is staging a DMA transfer. For this reason, CUDA provides functions for allocating page-locked memory that is pinned to RAM.

This memory is generally only used as a staging buffer for memory copies to the GPU. Significant use of pinned memory can reduce overall performance as the OS is forced to page out more memory to disk.

Implementations

impl<T: DeviceCopy> LockedBox<T>

pub unsafe fn uninitialized() -> CudaResult<Self>

Creates an uninitialized LockedBox. The contents must not be read until the box is written to.

Safety

The memory inside of the box is uninitialized, it must not be read in any way.

pub fn new(val: &T) -> CudaResult<Self>

Allocates page-locked memory and copies val into it.

Example

use cust::memory::LockedBox;

pub fn into_raw(self) -> *mut T

Consumes this box, returning the underlying allocation pointer. The backing memory will not be freed, it is up to the user to free it with either cuda_free_locked or LockedBox::from_raw.

pub unsafe fn from_raw(ptr: *mut T) -> Self

Creates a LockedBox from a raw pointer, taking ownership of the data backed behind the pointer.

Safety

The pointer must be a valid pinned memory allocation as obtained from LockedBox::into_raw or cuda_malloc_locked.

pub fn as_raw(&self) -> *mut T

Returns the underlying pointer backing this LockedBox without consuming the box, meaning that the box will still free the memory once out of scope. It is up to the user to make sure they don’t free the pointer.

Trait Implementations

impl<T: Debug + DeviceCopy> Debug for LockedBox<T>

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

Formats the value using the given formatter.

impl<T: DeviceCopy> Deref for LockedBox<T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T: DeviceCopy> DerefMut for LockedBox<T>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<T: DeviceCopy> Drop for LockedBox<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: Send + DeviceCopy> Send for LockedBox<T>

impl<T: Sync + DeviceCopy> Sync for LockedBox<T>