Struct rustacuda::memory::UnifiedBox

source ·

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

Expand description

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.

Implementations§

source §

impl<T: DeviceCopy> UnifiedBox<T>

source

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();

source

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;

source

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) };

source

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) };

source

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);

source

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);

source

pub fn leak<'a>(b: UnifiedBox<T>) -> &'a mut Twhere
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.

source

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
    },
}