Struct rustacuda_core::UnifiedPointer
source · #[repr(transparent)]pub struct UnifiedPointer<T: DeviceCopy>(_);
Expand description
A pointer to unified memory.
UnifiedPointer
can be safely dereferenced by the CPU, as the memory allocation it points to is
shared between the CPU and the GPU. It can also be safely copied to the device (eg. as part of
a kernel launch).
UnifiedPointer
is guaranteed to have an equivalent internal representation to a raw pointer.
Thus, it can be safely reinterpreted or transmuted to *mut T
. It is also safe to pass a
UnifiedPointer
through an FFI boundary to C code expecting a *mut T
. It is
thus possible to pass a UnifiedPointer
to a CUDA kernel written in C.
Implementations
sourceimpl<T: DeviceCopy> UnifiedPointer<T>
impl<T: DeviceCopy> UnifiedPointer<T>
sourcepub fn null() -> Self
pub fn null() -> Self
Returns a null unified pointer.
Examples:
use rustacuda::memory::*;
let ptr : UnifiedPointer<u64> = UnifiedPointer::null();
assert!(ptr.is_null());
sourcepub unsafe fn wrap(ptr: *mut T) -> Self
pub unsafe fn wrap(ptr: *mut T) -> Self
Wrap the given raw pointer in a UnifiedPointer. The given pointer is assumed to be a valid, unified-memory pointer or null.
Safety
The given pointer must have been allocated with
cuda_malloc_unified
or be null.
Examples:
use rustacuda::memory::*;
use std::ptr;
unsafe {
let null : *mut u64 = ptr::null_mut();
assert!(UnifiedPointer::wrap(null).is_null());
}
sourcepub fn as_raw(self) -> *const T
pub fn as_raw(self) -> *const T
Returns the contained pointer as a raw pointer.
Examples:
use rustacuda::memory::*;
unsafe {
let unified_ptr = cuda_malloc_unified::<u64>(1).unwrap();
let ptr: *const u64 = unified_ptr.as_raw();
cuda_free_unified(unified_ptr);
}
sourcepub fn as_raw_mut(&mut self) -> *mut T
pub fn as_raw_mut(&mut self) -> *mut T
Returns the contained pointer as a mutable raw pointer.
Examples:
use rustacuda::memory::*;
unsafe {
let mut unified_ptr = cuda_malloc_unified::<u64>(1).unwrap();
let ptr: *mut u64 = unified_ptr.as_raw_mut();
*ptr = 5u64;
cuda_free_unified(unified_ptr);
}
sourcepub fn is_null(self) -> bool
pub fn is_null(self) -> bool
Returns true if the pointer is null.
Examples:
use rustacuda::memory::*;
use std::ptr;
unsafe {
let null : *mut u64 = ptr::null_mut();
assert!(UnifiedPointer::wrap(null).is_null());
}
sourcepub unsafe fn offset(self, count: isize) -> Self
pub unsafe fn offset(self, count: isize) -> Self
Calculates the offset from a unified pointer.
count
is in units of T; eg. a count
of 3 represents a pointer offset of
3 * size_of::<T>()
bytes.
Safety
If any of the following conditions are violated, the result is Undefined Behavior:
-
Both the starting and resulting pointer must be either in bounds or one byte past the end of the same allocated object.
-
The computed offset, in bytes, cannot overflow an
isize
. -
The offset being in bounds cannot rely on “wrapping around” the address space. That is, the infinite-precision sum, in bytes must fit in a usize.
Consider using wrapping_offset
instead if these constraints are
difficult to satisfy. The only advantage of this method is that it
enables more aggressive compiler optimizations.
Examples
use rustacuda::memory::*;
unsafe {
let mut unified_ptr = cuda_malloc_unified::<u64>(5).unwrap();
let offset = unified_ptr.offset(1); // Points to the 2nd u64 in the buffer
cuda_free_unified(unified_ptr); // Must free the buffer using the original pointer
}
sourcepub fn wrapping_offset(self, count: isize) -> Self
pub fn wrapping_offset(self, count: isize) -> Self
Calculates the offset from a unified pointer using wrapping arithmetic.
count
is in units of T; eg. a count
of 3 represents a pointer offset of
3 * size_of::<T>()
bytes.
Safety
The resulting pointer does not need to be in bounds, but it is
potentially hazardous to dereference (which requires unsafe
).
In particular, the resulting pointer may not be used to access a
different allocated object than the one self
points to. In other
words, x.wrapping_offset(y.wrapping_offset_from(x))
is
not the same as y
, and dereferencing it is undefined behavior
unless x
and y
point into the same allocated object.
Always use .offset(count)
instead when possible, because offset
allows the compiler to optimize better. If you need to cross object
boundaries, cast the pointer to an integer and do the arithmetic there.
Examples
use rustacuda::memory::*;
unsafe {
let mut unified_ptr = cuda_malloc_unified::<u64>(5).unwrap();
let offset = unified_ptr.wrapping_offset(1); // Points to the 2nd u64 in the buffer
cuda_free_unified(unified_ptr); // Must free the buffer using the original pointer
}
sourcepub unsafe fn add(self, count: usize) -> Selfwhere
T: Sized,
pub unsafe fn add(self, count: usize) -> Selfwhere
T: Sized,
Calculates the offset from a pointer (convenience for .offset(count as isize)
).
count
is in units of T; e.g. a count
of 3 represents a pointer
offset of 3 * size_of::<T>()
bytes.
Safety
If any of the following conditions are violated, the result is Undefined Behavior:
-
Both the starting and resulting pointer must be either in bounds or one byte past the end of an allocated object.
-
The computed offset, in bytes, cannot overflow an
isize
. -
The offset being in bounds cannot rely on “wrapping around” the address space. That is, the infinite-precision sum must fit in a
usize
.
Consider using wrapping_offset
instead if these constraints are
difficult to satisfy. The only advantage of this method is that it
enables more aggressive compiler optimizations.
Examples
use rustacuda::memory::*;
unsafe {
let mut unified_ptr = cuda_malloc_unified::<u64>(5).unwrap();
let offset = unified_ptr.add(1); // Points to the 2nd u64 in the buffer
cuda_free_unified(unified_ptr); // Must free the buffer using the original pointer
}
sourcepub unsafe fn sub(self, count: usize) -> Selfwhere
T: Sized,
pub unsafe fn sub(self, count: usize) -> Selfwhere
T: Sized,
Calculates the offset from a pointer (convenience for
.offset((count as isize).wrapping_neg())
).
count
is in units of T; e.g. a count
of 3 represents a pointer
offset of 3 * size_of::<T>()
bytes.
Safety
If any of the following conditions are violated, the result is Undefined Behavior:
-
Both the starting and resulting pointer must be either in bounds or one byte past the end of an allocated object.
-
The computed offset, in bytes, cannot overflow an
isize
. -
The offset being in bounds cannot rely on “wrapping around” the address space. That is, the infinite-precision sum must fit in a
usize
.
Consider using wrapping_offset
instead if these constraints are
difficult to satisfy. The only advantage of this method is that it
enables more aggressive compiler optimizations.
Examples
use rustacuda::memory::*;
unsafe {
let mut unified_ptr = cuda_malloc_unified::<u64>(5).unwrap();
let offset = unified_ptr.add(4).sub(3); // Points to the 2nd u64 in the buffer
cuda_free_unified(unified_ptr); // Must free the buffer using the original pointer
}
sourcepub fn wrapping_add(self, count: usize) -> Selfwhere
T: Sized,
pub fn wrapping_add(self, count: usize) -> Selfwhere
T: Sized,
Calculates the offset from a pointer using wrapping arithmetic.
(convenience for .wrapping_offset(count as isize)
)
count
is in units of T; e.g. a count
of 3 represents a pointer
offset of 3 * size_of::<T>()
bytes.
Safety
The resulting pointer does not need to be in bounds, but it is potentially hazardous to dereference.
Always use .add(count)
instead when possible, because add
allows the compiler to optimize better.
Examples
use rustacuda::memory::*;
unsafe {
let mut unified_ptr = cuda_malloc_unified::<u64>(5).unwrap();
let offset = unified_ptr.wrapping_add(1); // Points to the 2nd u64 in the buffer
cuda_free_unified(unified_ptr); // Must free the buffer using the original pointer
}
sourcepub fn wrapping_sub(self, count: usize) -> Selfwhere
T: Sized,
pub fn wrapping_sub(self, count: usize) -> Selfwhere
T: Sized,
Calculates the offset from a pointer using wrapping arithmetic.
(convenience for .wrapping_offset((count as isize).wrapping_sub())
)
count
is in units of T; e.g. a count
of 3 represents a pointer
offset of 3 * size_of::<T>()
bytes.
Safety
The resulting pointer does not need to be in bounds, but it is
potentially hazardous to dereference (which requires unsafe
).
Always use .sub(count)
instead when possible, because sub
allows the compiler to optimize better.
Examples
use rustacuda::memory::*;
unsafe {
let mut unified_ptr = cuda_malloc_unified::<u64>(5).unwrap();
let offset = unified_ptr.wrapping_add(4).wrapping_sub(3); // Points to the 2nd u64 in the buffer
cuda_free_unified(unified_ptr); // Must free the buffer using the original pointer
}
Trait Implementations
sourceimpl<T: DeviceCopy> Clone for UnifiedPointer<T>
impl<T: DeviceCopy> Clone for UnifiedPointer<T>
sourceimpl<T: Debug + DeviceCopy> Debug for UnifiedPointer<T>
impl<T: Debug + DeviceCopy> Debug for UnifiedPointer<T>
sourceimpl<T: Hash + DeviceCopy> Hash for UnifiedPointer<T>
impl<T: Hash + DeviceCopy> Hash for UnifiedPointer<T>
sourceimpl<T: Ord + DeviceCopy> Ord for UnifiedPointer<T>
impl<T: Ord + DeviceCopy> Ord for UnifiedPointer<T>
sourcefn cmp(&self, other: &UnifiedPointer<T>) -> Ordering
fn cmp(&self, other: &UnifiedPointer<T>) -> Ordering
1.21.0 · sourcefn max(self, other: Self) -> Selfwhere
Self: Sized,
fn max(self, other: Self) -> Selfwhere
Self: Sized,
1.21.0 · sourcefn min(self, other: Self) -> Selfwhere
Self: Sized,
fn min(self, other: Self) -> Selfwhere
Self: Sized,
1.50.0 · sourcefn clamp(self, min: Self, max: Self) -> Selfwhere
Self: Sized + PartialOrd<Self>,
fn clamp(self, min: Self, max: Self) -> Selfwhere
Self: Sized + PartialOrd<Self>,
sourceimpl<T: PartialEq + DeviceCopy> PartialEq<UnifiedPointer<T>> for UnifiedPointer<T>
impl<T: PartialEq + DeviceCopy> PartialEq<UnifiedPointer<T>> for UnifiedPointer<T>
sourcefn eq(&self, other: &UnifiedPointer<T>) -> bool
fn eq(&self, other: &UnifiedPointer<T>) -> bool
sourceimpl<T: PartialOrd + DeviceCopy> PartialOrd<UnifiedPointer<T>> for UnifiedPointer<T>
impl<T: PartialOrd + DeviceCopy> PartialOrd<UnifiedPointer<T>> for UnifiedPointer<T>
sourcefn partial_cmp(&self, other: &UnifiedPointer<T>) -> Option<Ordering>
fn partial_cmp(&self, other: &UnifiedPointer<T>) -> Option<Ordering>
1.0.0 · sourcefn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read more