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>
impl<T: DeviceCopy> DeviceBox<T>
source§impl<T> DeviceBox<T>
impl<T> DeviceBox<T>
sourcepub unsafe fn uninitialized() -> CudaResult<Self>
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();
sourcepub unsafe fn zeroed() -> CudaResult<Self>
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);
sourcepub unsafe fn from_raw(ptr: *mut T) -> Self
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) };
sourcepub unsafe fn from_device(ptr: DevicePointer<T>) -> Self
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) };
sourcepub fn into_device(b: DeviceBox<T>) -> DevicePointer<T>
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);
sourcepub fn as_device_ptr(&mut self) -> DevicePointer<T>
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);
sourcepub fn drop(dev_box: DeviceBox<T>) -> DropResult<DeviceBox<T>>
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
},
}