Struct DeviceSlice

Source

pub struct DeviceSlice<T>(/* private fields */);

Expand description

Fixed-size device-side slice.

Implementations§

Source §

impl<T> DeviceSlice<T>

Source

pub fn len(&self) -> usize

Returns the number of elements in the slice.

§Examples

use rustacuda::memory::*;
let a = DeviceBuffer::from_slice(&[1, 2, 3]).unwrap();
assert_eq!(a.len(), 3);

Source

pub fn is_empty(&self) -> bool

Returns true if the slice has a length of 0.

§Examples

use rustacuda::memory::*;
let a : DeviceBuffer<u64> = unsafe { DeviceBuffer::uninitialized(0).unwrap() };
assert!(a.is_empty());

Source

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

Return a raw device-pointer to the slice’s buffer.

The caller must ensure that the slice outlives the pointer this function returns, or else it will end up pointing to garbage. The caller must also ensure that the pointer is not dereferenced by the CPU.

Examples:

use rustacuda::memory::*;
let a = DeviceBuffer::from_slice(&[1, 2, 3]).unwrap();
println!("{:p}", a.as_ptr());

Source

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

Returns an unsafe mutable device-pointer to the slice’s buffer.

The caller must ensure that the slice outlives the pointer this function returns, or else it will end up pointing to garbage. The caller must also ensure that the pointer is not dereferenced by the CPU.

Examples:

use rustacuda::memory::*;
let mut a = DeviceBuffer::from_slice(&[1, 2, 3]).unwrap();
println!("{:p}", a.as_mut_ptr());

Source

pub fn split_at(&self, mid: usize) -> (&DeviceSlice<T>, &DeviceSlice<T>)

Divides one DeviceSlice into two at a given index.

The first will contain all indices from [0, mid) (excluding the index mid itself) and the second will contain all indices from [mid, len) (excluding the index len itself).

§Panics

Panics if min > len.

Examples:

use rustacuda::memory::*;
let buf = DeviceBuffer::from_slice(&[0u64, 1, 2, 3, 4, 5]).unwrap();
let (left, right) = buf.split_at(3);
let mut left_host = [0u64, 0, 0];
let mut right_host = [0u64, 0, 0];
left.copy_to(&mut left_host).unwrap();
right.copy_to(&mut right_host).unwrap();
assert_eq!([0u64, 1, 2], left_host);
assert_eq!([3u64, 4, 5], right_host);

Source

pub fn split_at_mut( &mut self, mid: usize, ) -> (&mut DeviceSlice<T>, &mut DeviceSlice<T>)

Divides one mutable DeviceSlice into two at a given index.

The first will contain all indices from [0, mid) (excluding the index mid itself) and the second will contain all indices from [mid, len) (excluding the index len itself).

§Panics

Panics if min > len.

Examples:

use rustacuda::memory::*;
let mut buf = DeviceBuffer::from_slice(&[0u64, 0, 0, 0, 0, 0]).unwrap();

{
    let (left, right) = buf.split_at_mut(3);
    let left_host = [0u64, 1, 2];
    let right_host = [3u64, 4, 5];
    left.copy_from(&left_host).unwrap();
    right.copy_from(&right_host).unwrap();
}

let mut host_full = [0u64; 6];
buf.copy_to(&mut host_full).unwrap();
assert_eq!([0u64, 1, 2, 3, 4, 5], host_full);

Source

pub fn chunks(&self, chunk_size: usize) -> DeviceChunks<'_, T> ⓘ

Returns an iterator over chunk_size elements of the slice at a time. The chunks are device slices and do not overlap. If chunk_size does not divide the length of the slice, then the last chunk will not have length chunk_size.

See exact_chunks for a variant of this iterator that returns chunks of always exactly chunk_size elements.

§Panics

Panics if chunk_size is 0.

§Examples

use rustacuda::memory::*;
let slice = DeviceBuffer::from_slice(&[1u64, 2, 3, 4, 5]).unwrap();
let mut iter = slice.chunks(2);

assert_eq!(iter.next().unwrap().len(), 2);

let mut host_buf = [0u64, 0];
iter.next().unwrap().copy_to(&mut host_buf).unwrap();
assert_eq!([3, 4], host_buf);

assert_eq!(iter.next().unwrap().len(), 1);

Source

pub fn chunks_mut(&mut self, chunk_size: usize) -> DeviceChunksMut<'_, T> ⓘ

Returns an iterator over chunk_size elements of the slice at a time. The chunks are mutable device slices and do not overlap. If chunk_size does not divide the length of the slice, then the last chunk will not have length chunk_size.

See exact_chunks for a variant of this iterator that returns chunks of always exactly chunk_size elements.

§Panics

Panics if chunk_size is 0.

§Examples

use rustacuda::memory::*;
let mut slice = DeviceBuffer::from_slice(&[0u64, 0, 0, 0, 0]).unwrap();
{
    let mut iter = slice.chunks_mut(2);

    assert_eq!(iter.next().unwrap().len(), 2);

    let host_buf = [2u64, 3];
    iter.next().unwrap().copy_from(&host_buf).unwrap();

    assert_eq!(iter.next().unwrap().len(), 1);
}

let mut host_buf = [0u64, 0, 0, 0, 0];
slice.copy_to(&mut host_buf).unwrap();
assert_eq!([0u64, 0, 2, 3, 0], host_buf);

Source

pub fn as_device_ptr(&mut self) -> DevicePointer<T>

Returns a DevicePointer<T> to the buffer.

The caller must ensure that the buffer outlives the returned pointer, or it will end up pointing to garbage.

Modifying DeviceBuffer is guaranteed not to cause its buffer to be reallocated, so pointers cannot be invalidated in that manner, but other types may be added in the future which can reallocate.

Source

pub unsafe fn from_raw_parts<'a>( data: DevicePointer<T>, len: usize, ) -> &'a DeviceSlice<T>

Forms a slice from a DevicePointer and a length.

The len argument is the number of elements, not the number of bytes.

§Safety

This function is unsafe as there is no guarantee that the given pointer is valid for len elements, nor whether the lifetime inferred is a suitable lifetime for the returned slice.

§Caveat

The lifetime for the returned slice is inferred from its usage. To prevent accidental misuse, it’s suggested to tie the lifetime to whatever source lifetime is safe in the context, such as by providing a helper function taking the lifetime of a host value for the slice or by explicit annotation.

§Examples

use rustacuda::memory::*;
let mut x = DeviceBuffer::from_slice(&[0u64, 1, 2, 3, 4, 5]).unwrap();
// Manually slice the buffer (this is not recommended!)
let ptr = unsafe { x.as_device_ptr().offset(1) };
let slice = unsafe { DeviceSlice::from_raw_parts(ptr, 2) };
let mut host_buf = [0u64, 0];
slice.copy_to(&mut host_buf).unwrap();
assert_eq!([1u64, 2], host_buf);

Source

pub unsafe fn from_raw_parts_mut<'a>( data: DevicePointer<T>, len: usize, ) -> &'a mut DeviceSlice<T>

Performs the same functionality as from_raw_parts, except that a mutable slice is returned.

§Safety

This function is unsafe as there is no guarantee that the given pointer is valid for len elements, nor whether the lifetime inferred is a suitable lifetime for the returned slice.

This function is unsafe as there is no guarantee that the given pointer is valid for len elements, not whether the lifetime inferred is a suitable lifetime for the returned slice, as well as not being able to provide a non-aliasing guarantee of the returned mutable slice. data must be non-null and aligned even for zero-length slices as with from_raw_parts.

See the documentation of from_raw_parts for more details.