Struct DevicePointer

pub struct DevicePointer<T>
where
    T: DeviceCopy + ?Sized,
{ /* private fields */ }

A pointer to device memory.

DevicePointer cannot be dereferenced by the CPU, as it is a pointer to a memory allocation in the device. It can be safely copied to the device (eg. as part of a kernel launch) and either unwrapped or transmuted to an appropriate pointer.

DevicePointer 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 safe to pass a DevicePointer through an FFI boundary to C code expecting a *mut T, so long as the code on the other side of that boundary does not attempt to dereference the pointer on the CPU. It is thus possible to pass a DevicePointer to a CUDA kernel written in C.

Implementations

impl<T> DevicePointer<T>

where T: DeviceCopy + ?Sized,

pub fn as_ptr(&self) -> *const T

Returns a rust pointer created from this pointer, meant for FFI purposes. The pointer is not dereferenceable from the CPU!

pub fn as_mut_ptr(&self) -> *mut T

Returns a rust pointer created from this pointer, meant for FFI purposes. The pointer is not dereferenceable from the CPU!

pub fn as_raw(&self) -> u64

Returns the contained CUdeviceptr.

pub fn from_raw(ptr: u64) -> DevicePointer<T>

Create a DevicePointer from a raw CUDA pointer

pub fn is_null(self) -> bool

Returns true if the pointer is null.

Examples

use cust::memory::*;
use std::ptr;
unsafe {
    let null : *mut u64 = ptr::null_mut();
    assert!(DevicePointer::wrap(null).is_null());
}

pub fn null() -> DevicePointer<T>

Returns a null device pointer.

pub unsafe fn offset(self, count: isize) -> DevicePointer<T>

Calculates the offset from a device 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 cust::memory::*;
unsafe {
    let mut dev_ptr = cuda_malloc::<u64>(5).unwrap();
    let offset = dev_ptr.offset(1); // Points to the 2nd u64 in the buffer
    cuda_free(dev_ptr); // Must free the buffer using the original pointer
}

pub fn wrapping_offset(self, count: isize) -> DevicePointer<T>

Calculates the offset from a device 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 cust::memory::*;
unsafe {
    let mut dev_ptr = cuda_malloc::<u64>(5).unwrap();
    let offset = dev_ptr.wrapping_offset(1); // Points to the 2nd u64 in the buffer
    cuda_free(dev_ptr); // Must free the buffer using the original pointer
}

pub unsafe fn add(self, count: usize) -> DevicePointer<T>

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 cust::memory::*;
unsafe {
    let mut dev_ptr = cuda_malloc::<u64>(5).unwrap();
    let offset = dev_ptr.add(1); // Points to the 2nd u64 in the buffer
    cuda_free(dev_ptr); // Must free the buffer using the original pointer
}

pub unsafe fn sub(self, count: usize) -> DevicePointer<T>

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 cust::memory::*;
unsafe {
    let mut dev_ptr = cuda_malloc::<u64>(5).unwrap();
    let offset = dev_ptr.add(4).sub(3); // Points to the 2nd u64 in the buffer
    cuda_free(dev_ptr); // Must free the buffer using the original pointer
}

pub fn wrapping_add(self, count: usize) -> DevicePointer<T>

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 cust::memory::*;
unsafe {
    let mut dev_ptr = cuda_malloc::<u64>(5).unwrap();
    let offset = dev_ptr.wrapping_add(1); // Points to the 2nd u64 in the buffer
    cuda_free(dev_ptr); // Must free the buffer using the original pointer
}

pub fn wrapping_sub(self, count: usize) -> DevicePointer<T>

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 cust::memory::*;
unsafe {
    let mut dev_ptr = cuda_malloc::<u64>(5).unwrap();
    let offset = dev_ptr.wrapping_add(4).wrapping_sub(3); // Points to the 2nd u64 in the buffer
    cuda_free(dev_ptr); // Must free the buffer using the original pointer
}

pub fn cast<U>(self) -> DevicePointer<U>

where U: DeviceCopy,

Casts this device pointer to another type.

Trait Implementations

impl<T> Clone for DevicePointer<T>

where T: Clone + DeviceCopy + ?Sized,

fn clone(&self) -> DevicePointer<T>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Debug for DevicePointer<T>

where T: Debug + DeviceCopy + ?Sized,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<T> Hash for DevicePointer<T>

where T: Hash + DeviceCopy + ?Sized,

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

where __H: Hasher,

Feeds this value into the given Hasher.

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

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T> Ord for DevicePointer<T>

where T: Ord + DeviceCopy + ?Sized,

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

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<T> PartialEq for DevicePointer<T>

where T: PartialEq + DeviceCopy + ?Sized,

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

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PartialOrd for DevicePointer<T>

where T: PartialOrd + DeviceCopy + ?Sized,

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

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

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

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

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

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

impl<T> Pointer for DevicePointer<T>

where T: DeviceCopy,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<T> Copy for DevicePointer<T>

where T: Copy + DeviceCopy + ?Sized,

impl<T> DeviceCopy for DevicePointer<T>

where T: DeviceCopy + ?Sized,

impl<T> Eq for DevicePointer<T>

where T: Eq + DeviceCopy + ?Sized,

impl<T> StructuralPartialEq for DevicePointer<T>

where T: DeviceCopy + ?Sized,