Struct cust::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
sourceimpl<T: DeviceCopy> UnifiedBox<T>
impl<T: DeviceCopy> UnifiedBox<T>
sourcepub fn new(val: T) -> CudaResult<Self>
pub fn new(val: T) -> CudaResult<Self>
sourcepub unsafe fn uninitialized() -> CudaResult<Self>
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 cust::memory::*;
let mut five = unsafe{ UnifiedBox::uninitialized().unwrap() };
*five = 5u64;
sourcepub unsafe fn from_raw(ptr: *mut T) -> Self
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 cust::memory::*;
let x = UnifiedBox::new(5).unwrap();
let ptr = UnifiedBox::into_unified(x).as_raw_mut();
let x = unsafe { UnifiedBox::from_raw(ptr) };
sourcepub unsafe fn from_unified(ptr: UnifiedPointer<T>) -> Self
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 cust::memory::*;
let x = UnifiedBox::new(5).unwrap();
let ptr = UnifiedBox::into_unified(x);
let x = unsafe { UnifiedBox::from_unified(ptr) };
sourcepub fn into_unified(b: UnifiedBox<T>) -> UnifiedPointer<T>
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 cust::memory::*;
let x = UnifiedBox::new(5).unwrap();
let ptr = UnifiedBox::into_unified(x);
sourcepub fn as_unified_ptr(&self) -> UnifiedPointer<T>
pub fn as_unified_ptr(&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 cust::memory::*;
let mut x = UnifiedBox::new(5).unwrap();
let ptr = x.as_unified_ptr();
println!("{:p}", ptr);
sourcepub fn leak<'a>(b: UnifiedBox<T>) -> &'a mut T where
T: 'a,
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.
sourcepub fn drop(uni_box: UnifiedBox<T>) -> DropResult<UnifiedBox<T>>
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 cust::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
sourceimpl<T: DeviceCopy> AsMut<T> for UnifiedBox<T>
impl<T: DeviceCopy> AsMut<T> for UnifiedBox<T>
sourceimpl<T: DeviceCopy> AsRef<T> for UnifiedBox<T>
impl<T: DeviceCopy> AsRef<T> for UnifiedBox<T>
sourceimpl<T: DeviceCopy> Borrow<T> for UnifiedBox<T>
impl<T: DeviceCopy> Borrow<T> for UnifiedBox<T>
sourceimpl<T: DeviceCopy> BorrowMut<T> for UnifiedBox<T>
impl<T: DeviceCopy> BorrowMut<T> for UnifiedBox<T>
sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T: Debug + DeviceCopy> Debug for UnifiedBox<T>
impl<T: Debug + DeviceCopy> Debug for UnifiedBox<T>
sourceimpl<T: DeviceCopy> Deref for UnifiedBox<T>
impl<T: DeviceCopy> Deref for UnifiedBox<T>
sourceimpl<T: DeviceCopy> DerefMut for UnifiedBox<T>
impl<T: DeviceCopy> DerefMut for UnifiedBox<T>
sourceimpl<T: Display + DeviceCopy> Display for UnifiedBox<T>
impl<T: Display + DeviceCopy> Display for UnifiedBox<T>
sourceimpl<T: DeviceCopy> Drop for UnifiedBox<T>
impl<T: DeviceCopy> Drop for UnifiedBox<T>
sourceimpl<T: DeviceCopy> GpuBox<T> for UnifiedBox<T>
impl<T: DeviceCopy> GpuBox<T> for UnifiedBox<T>
fn as_device_ptr(&self) -> DevicePointer<T>
sourceimpl<T: DeviceCopy + Hash> Hash for UnifiedBox<T>
impl<T: DeviceCopy + Hash> Hash for UnifiedBox<T>
sourceimpl<T: DeviceCopy> MemoryAdvise<T> for UnifiedBox<T>
impl<T: DeviceCopy> MemoryAdvise<T> for UnifiedBox<T>
fn as_slice(&self) -> &[T]ⓘNotable traits for &'_ mut [u8]impl Write for &'_ mut [u8]impl Read for &'_ [u8]
sourcefn prefetch_to_host(&self, stream: &Stream) -> CudaResult<()>
fn prefetch_to_host(&self, stream: &Stream) -> CudaResult<()>
Advises the driver to enqueue an operation on the stream to prefetch the memory to the CPU. This will cause the driver to fetch the data back to the CPU as soon as the operation is reached on the stream. Read more
sourcefn prefetch_to_device(&self, stream: &Stream, device: &Device) -> CudaResult<()>
fn prefetch_to_device(&self, stream: &Stream, device: &Device) -> CudaResult<()>
Advises the driver to enqueue an operation on the stream to prefetch the memory to a certain GPU. This will cause the driver to fetch the data to the specified device as soon as the operation is reached on the stream. Read more
sourcefn advise_read_mostly(&self, read_mostly: bool) -> CudaResult<()>
fn advise_read_mostly(&self, read_mostly: bool) -> CudaResult<()>
Advises the driver that this memory range is mostly going to be read to, and occasionally written to. Read more
sourcefn preferred_location(
&self,
preferred_location: Option<Device>
) -> CudaResult<()>
fn preferred_location(
&self,
preferred_location: Option<Device>
) -> CudaResult<()>
Advises the driver as to the preferred device for this memory range. Either
a device with Some(device)
or the CPU with None
. If the device is a GPU,
it must have DeviceAttribute::ConcurrentManagedAccess
. Read more
sourcefn unset_preferred_location(&self) -> CudaResult<()>
fn unset_preferred_location(&self) -> CudaResult<()>
Undoes the most recent changes by preferred_location
.
sourceimpl<T: DeviceCopy + Ord> Ord for UnifiedBox<T>
impl<T: DeviceCopy + Ord> Ord for UnifiedBox<T>
sourceimpl<T: DeviceCopy + PartialEq> PartialEq<UnifiedBox<T>> for UnifiedBox<T>
impl<T: DeviceCopy + PartialEq> PartialEq<UnifiedBox<T>> for UnifiedBox<T>
sourceimpl<T: DeviceCopy + PartialOrd> PartialOrd<UnifiedBox<T>> for UnifiedBox<T>
impl<T: DeviceCopy + PartialOrd> PartialOrd<UnifiedBox<T>> for UnifiedBox<T>
sourcefn partial_cmp(&self, other: &UnifiedBox<T>) -> Option<Ordering>
fn partial_cmp(&self, other: &UnifiedBox<T>) -> Option<Ordering>
This method returns an ordering between self
and other
values if one exists. Read more
sourcefn lt(&self, other: &UnifiedBox<T>) -> bool
fn lt(&self, other: &UnifiedBox<T>) -> bool
This method tests less than (for self
and other
) and is used by the <
operator. Read more
sourcefn le(&self, other: &UnifiedBox<T>) -> bool
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. Read more
sourcefn ge(&self, other: &UnifiedBox<T>) -> bool
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. Read more
sourcefn gt(&self, other: &UnifiedBox<T>) -> bool
fn gt(&self, other: &UnifiedBox<T>) -> bool
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
sourceimpl<T: DeviceCopy> Pointer for UnifiedBox<T>
impl<T: DeviceCopy> Pointer for UnifiedBox<T>
impl<T: DeviceCopy + Eq> Eq for UnifiedBox<T>
impl<T: Send + DeviceCopy> Send for UnifiedBox<T>
impl<T: Sync + DeviceCopy> Sync for UnifiedBox<T>
Auto Trait Implementations
impl<T> RefUnwindSafe for UnifiedBox<T> where
T: RefUnwindSafe,
impl<T> Unpin for UnifiedBox<T>
impl<T> UnwindSafe for UnifiedBox<T> where
T: RefUnwindSafe,
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcepub fn borrow_mut(&mut self) -> &mut T
pub fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more