Struct DeviceBox

Source
pub struct DeviceBox<T> { /* private fields */ }
Expand description

A pointer type for heap-allocation in CUDA device memory.

See the module-level documentation for more information on device memory.

Implementations§

Source§

impl<T: DeviceCopy> DeviceBox<T>

Source

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

Allocate device memory and place val into it.

This doesn’t actually allocate if T is zero-sized.

§Errors

If a CUDA error occurs, return the error.

§Examples
use rustacuda::memory::*;
let five = DeviceBox::new(&5).unwrap();
Source§

impl<T> DeviceBox<T>

Source

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

Allocate device memory, but do not initialize it.

This doesn’t actually allocate if T is zero-sized.

§Safety

Since the backing memory is not initialized, this function is not safe. The caller must ensure that the backing memory is set to a valid value before it is read, else undefined behavior may occur.

§Examples
use rustacuda::memory::*;
let mut five = unsafe { DeviceBox::uninitialized().unwrap() };
five.copy_from(&5u64).unwrap();
Source

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

Allocate device memory and fill it with zeroes (0u8).

This doesn’t actually allocate if T is zero-sized.

§Safety

The backing memory is zeroed, which may not be a valid bit-pattern for type T. The caller must ensure either that all-zeroes is a valid bit-pattern for type T or that the backing memory is set to a valid value before it is read.

§Examples
use rustacuda::memory::*;
let mut zero = unsafe { DeviceBox::zeroed().unwrap() };
let mut value = 5u64;
zero.copy_to(&mut value).unwrap();
assert_eq!(0, value);
Source

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

Constructs a DeviceBox from a raw pointer.

After calling this function, the raw pointer and the memory it points to is owned by the DeviceBox. The DeviceBox destructor will free the allocated memory, but will not call the destructor of T. This function may accept any pointer produced by the cuMemAllocManaged CUDA API call.

§Safety

This function is unsafe because improper use may lead to memory problems. For example, a double free may occur if this function is called twice on the same pointer, or a segfault may occur if the pointer is not one returned by the appropriate API call.

§Examples
use rustacuda::memory::*;
let x = DeviceBox::new(&5).unwrap();
let ptr = DeviceBox::into_device(x).as_raw_mut();
let x = unsafe { DeviceBox::from_raw(ptr) };
Source

pub unsafe fn from_device(ptr: DevicePointer<T>) -> Self

Constructs a DeviceBox from a DevicePointer.

After calling this function, the pointer and the memory it points to is owned by the DeviceBox. The DeviceBox destructor will free the allocated memory, but will not call the destructor of T. This function may accept any pointer produced by the cuMemAllocManaged CUDA API call, such as one taken from DeviceBox::into_device.

§Safety

This function is unsafe because improper use may lead to memory problems. For example, a double free may occur if this function is called twice on the same pointer, or a segfault may occur if the pointer is not one returned by the appropriate API call.

§Examples
use rustacuda::memory::*;
let x = DeviceBox::new(&5).unwrap();
let ptr = DeviceBox::into_device(x);
let x = unsafe { DeviceBox::from_device(ptr) };
Source

pub fn into_device(b: DeviceBox<T>) -> DevicePointer<T>

Consumes the DeviceBox, returning the wrapped DevicePointer.

After calling this function, the caller is responsible for the memory previously managed by the DeviceBox. In particular, the caller should properly destroy T and deallocate the memory. The easiest way to do so is to create a new DeviceBox using the DeviceBox::from_device function.

Note: This is an associated function, which means that you have to all it as DeviceBox::into_device(b) instead of b.into_device() This is so that there is no conflict with a method on the inner type.

§Examples
use rustacuda::memory::*;
let x = DeviceBox::new(&5).unwrap();
let ptr = DeviceBox::into_device(x);
Source

pub fn as_device_ptr(&mut self) -> DevicePointer<T>

Returns the contained device pointer without consuming the box.

This is useful for passing the box to a kernel launch.

§Examples
use rustacuda::memory::*;
let mut x = DeviceBox::new(&5).unwrap();
let ptr = x.as_device_ptr();
println!("{:p}", ptr);
Source

pub fn drop(dev_box: DeviceBox<T>) -> DropResult<DeviceBox<T>>

Destroy a DeviceBox, returning an error.

Deallocating device memory can return errors from previous asynchronous work. This function destroys the given box and returns the error and the un-destroyed box on failure.

§Example
use rustacuda::memory::*;
let x = DeviceBox::new(&5).unwrap();
match DeviceBox::drop(x) {
    Ok(()) => println!("Successfully destroyed"),
    Err((e, dev_box)) => {
        println!("Failed to destroy box: {:?}", e);
        // Do something with dev_box
    },
}

Trait Implementations§

Source§

impl<T: DeviceCopy> AsyncCopyDestination<DeviceBox<T>> for DeviceBox<T>

Source§

unsafe fn async_copy_from( &mut self, val: &DeviceBox<T>, stream: &Stream, ) -> CudaResult<()>

Asynchronously copy data from source. source must be the same size as self. Read more
Source§

unsafe fn async_copy_to( &self, val: &mut DeviceBox<T>, stream: &Stream, ) -> CudaResult<()>

Asynchronously copy data to dest. dest must be the same size as self. Read more
Source§

impl<T: DeviceCopy> CopyDestination<DeviceBox<T>> for DeviceBox<T>

Source§

fn copy_from(&mut self, val: &DeviceBox<T>) -> CudaResult<()>

Copy data from source. source must be the same size as self. Read more
Source§

fn copy_to(&self, val: &mut DeviceBox<T>) -> CudaResult<()>

Copy data to dest. dest must be the same size as self. Read more
Source§

impl<T: DeviceCopy> CopyDestination<T> for DeviceBox<T>

Source§

fn copy_from(&mut self, val: &T) -> CudaResult<()>

Copy data from source. source must be the same size as self. Read more
Source§

fn copy_to(&self, val: &mut T) -> CudaResult<()>

Copy data to dest. dest must be the same size as self. Read more
Source§

impl<T: Debug> Debug for DeviceBox<T>

Source§

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

Formats the value using the given formatter. Read more
Source§

impl<T> Drop for DeviceBox<T>

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

impl<T> Pointer for DeviceBox<T>

Source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl<T> Freeze for DeviceBox<T>

§

impl<T> RefUnwindSafe for DeviceBox<T>
where T: RefUnwindSafe,

§

impl<T> !Send for DeviceBox<T>

§

impl<T> !Sync for DeviceBox<T>

§

impl<T> Unpin for DeviceBox<T>

§

impl<T> UnwindSafe for DeviceBox<T>
where T: RefUnwindSafe,

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.