Struct rustacuda::memory::UnifiedBox

pub struct UnifiedBox<T: DeviceCopy> { /* fields omitted */ }

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

See the module-level documentation for more information on unified memory. Should behave equivalently to std::boxed::Box, except that the allocated memory can be seamlessly shared between host and device.

Methods

impl<T: DeviceCopy> UnifiedBox<T>

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

Allocate unified memory and place val into it.

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

Errors

If a CUDA error occurs, returns that error.

Examples

use rustacuda::memory::*;
let five = UnifiedBox::new(5).unwrap();

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

Allocate unified memory without initializing 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.

Errors

If a CUDA error occurs, returns that error.

Examples

use rustacuda::memory::*;
let mut five = unsafe{ UnifiedBox::uninitialized().unwrap() };
*five = 5u64;

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

Constructs a UnifiedBox from a raw pointer.

After calling this function, the raw pointer and the memory it points to is owned by the UnifiedBox. The UnifiedBox 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 = UnifiedBox::new(5).unwrap();
let ptr = UnifiedBox::into_unified(x).as_raw_mut();
let x = unsafe { UnifiedBox::from_raw(ptr) };

pub unsafe fn from_unified(ptr: UnifiedPointer<T>) -> Self

Constructs a UnifiedBox from a UnifiedPointer.

After calling this function, the pointer and the memory it points to is owned by the UnifiedBox. The UnifiedBox 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 UnifiedBox::into_unified.

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 = UnifiedBox::new(5).unwrap();
let ptr = UnifiedBox::into_unified(x);
let x = unsafe { UnifiedBox::from_unified(ptr) };

pub fn into_unified(b: UnifiedBox<T>) -> UnifiedPointer<T>

Consumes the UnifiedBox, returning the wrapped UnifiedPointer.

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

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

Examples

use rustacuda::memory::*;
let x = UnifiedBox::new(5).unwrap();
let ptr = UnifiedBox::into_unified(x);

pub fn as_unified_ptr(&mut self) -> UnifiedPointer<T>

Returns the contained unified pointer without consuming the box.

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

Examples

use rustacuda::memory::*;
let mut x = UnifiedBox::new(5).unwrap();
let ptr = x.as_unified_ptr();
println!("{:p}", ptr);

pub fn leak<'a>(b: UnifiedBox<T>) -> &'a mut T where
    T: 'a, 

Consumes and leaks the UnifiedBox, returning a mutable reference, &'a mut T. Note that the type T must outlive the chosen lifetime 'a. If the type has only static references, or none at all, this may be chosen to be 'static.

This is mainly useful for data that lives for the remainder of the program's life. Dropping the returned reference will cause a memory leak. If this is not acceptable, the reference should be wrapped with the UnifiedBox::from_raw function to produce a new UnifiedBox. This UnifiedBox can then be dropped, which will properly destroy T and release the allocated memory.

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

pub fn drop(uni_box: UnifiedBox<T>) -> DropResult<UnifiedBox<T>>

Destroy a UnifiedBox, returning an error.

Deallocating unified 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 = UnifiedBox::new(5).unwrap();
match UnifiedBox::drop(x) {
    Ok(()) => println!("Successfully destroyed"),
    Err((e, uni_box)) => {
        println!("Failed to destroy box: {:?}", e);
        // Do something with uni_box
    },
}

Trait Implementations

impl<T: DeviceCopy> AsMut<T> for UnifiedBox<T>

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

Performs the conversion.

impl<T: DeviceCopy> AsRef<T> for UnifiedBox<T>

fn as_ref(&self) -> &T

Performs the conversion.

impl<T: DeviceCopy> Borrow<T> for UnifiedBox<T>

fn borrow(&self) -> &T

Immutably borrows from an owned value.

impl<T: DeviceCopy> BorrowMut<T> for UnifiedBox<T>

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

Mutably borrows from an owned value.

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

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

Formats the value using the given formatter.

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

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

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

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

Mutably dereferences the value.

impl<T: Display + DeviceCopy> Display for UnifiedBox<T>

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

Formats the value using the given formatter.

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

fn drop(&mut self)

Executes the destructor for this type.

impl<T: DeviceCopy + Eq> Eq for UnifiedBox<T>

impl<T: DeviceCopy + Hash> Hash for UnifiedBox<T>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].

impl<T: DeviceCopy + Ord> Ord for UnifiedBox<T>

fn cmp(&self, other: &UnifiedBox<T>) -> Ordering

This method returns an [Ordering] between self and other.

#[must_use] fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use] fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use] fn clamp(self, min: Self, max: Self) -> Self

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl<T: DeviceCopy + PartialEq> PartialEq<UnifiedBox<T>> for UnifiedBox<T>

fn eq(&self, other: &UnifiedBox<T>) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T: DeviceCopy + PartialOrd> PartialOrd<UnifiedBox<T>> for UnifiedBox<T>

fn partial_cmp(&self, other: &UnifiedBox<T>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &UnifiedBox<T>) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &UnifiedBox<T>) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn ge(&self, other: &UnifiedBox<T>) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

fn gt(&self, other: &UnifiedBox<T>) -> bool

This method tests greater than (for self and other) and is used by the > operator.

impl<T: DeviceCopy> Pointer for UnifiedBox<T>

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

Formats the value using the given formatter.