Struct opencl3::svm::SvmVec

pub struct SvmVec<'a, T> { /* fields omitted */ }

An OpenCL Shared Virtual Memory (SVM) vector. It has the lifetime of the Context that it was constructed from.
Note: T cannot be a “zero sized type” (ZST).

There are three types of Shared Virtual Memory:

• CL_DEVICE_SVM_COARSE_GRAIN_BUFFER: OpenCL buffer memory objects can be shared.
• CL_DEVICE_SVM_FINE_GRAIN_BUFFER: individual memory objects in an OpenCL buffer can be shared.
• CL_DEVICE_SVM_FINE_GRAIN_SYSTEM: individual memory objects anywhere in host memory can be shared.

This SvmVec struct is designed to support CL_DEVICE_SVM_COARSE_GRAIN_BUFFER and CL_DEVICE_SVM_FINE_GRAIN_BUFFER.
A Context that supports CL_DEVICE_SVM_FINE_GRAIN_SYSTEM can (and should!) use a standard Rust vector instead.

Intel provided an excellent overview of Shared Virtual Memory here: OpenCL 2.0 Shared Virtual Memory Overview.
A PDF version is available here: SVM Overview.

To summarise, a CL_DEVICE_SVM_COARSE_GRAIN_BUFFER requires the SVM to be mapped before being read or written by the host and unmapped afterward, while CL_DEVICE_SVM_FINE_GRAIN_BUFFER can be used like a standard Rust vector.

The is_fine_grained method can be used to determine whether an SvmVec supports CL_DEVICE_SVM_FINE_GRAIN_BUFFER and should be used to control SVM map and unmap operations, e.g.:

// The input data
const ARRAY_SIZE: usize = 8;
let value_array: [cl_int; ARRAY_SIZE] = [3, 2, 5, 9, 7, 1, 4, 2];

// Create an OpenCL SVM vector
let mut test_values = SvmVec::<cl_int>::allocate(&context, ARRAY_SIZE)?;

// Map test_values if not an CL_MEM_SVM_FINE_GRAIN_BUFFER
if !test_values.is_fine_grained() {
    queue.enqueue_svm_map(CL_BLOCKING, CL_MAP_WRITE, &mut test_values, &[])?;
}

// Copy input data into the OpenCL SVM vector
test_values.clone_from_slice(&value_array);

// Unmap test_values if not an CL_MEM_SVM_FINE_GRAIN_BUFFER
if !test_values.is_fine_grained() {
    let unmap_test_values_event = queue.enqueue_svm_unmap(&test_values, &[])?;
    unmap_test_values_event.wait()?;
}

Implementations

impl<'a, T> SvmVec<'a, T>

pub fn cap(&self) -> usize

The capacity of the vector.

pub fn len(&self) -> usize

The length of the vector.

pub fn is_empty(&self) -> bool

Whether the vector is empty

pub fn is_fine_grained(&self) -> bool

Whether the vector is fine grained

pub fn has_atomics(&self) -> bool

Whether the vector can use atomics

pub fn clear(&mut self)

Clear the vector, i.e. empty it.

pub fn set_len(&mut self, new_len: usize) -> Result<()>

Set the length of the vector. If new_len > len, the new memory will be uninitialised.

Safety

May fail to grow buf if memory is not available for new_len.

pub fn new(context: &'a Context) -> Self

Construct an empty SvmVec from a Context.
The SvmVec has the lifetime of the Context.

Panics

The cl_device_svm_capabilities of the Context must include CL_DEVICE_SVM_COARSE_GRAIN_BUFFER or CL_DEVICE_SVM_FINE_GRAIN_BUFFER.
The cl_device_svm_capabilities must not include CL_DEVICE_SVM_FINE_GRAIN_SYSTEM, a standard Rust Vec! should be used instead.

pub fn allocate(context: &'a Context, len: usize) -> Result<Self>

Construct an SvmVec with the given len of values from a Context.

returns a Result containing an SvmVec with len values of uninitialised memory, or the OpenCL error.

Panics

The cl_device_svm_capabilities of the Context must include CL_DEVICE_SVM_COARSE_GRAIN_BUFFER or CL_DEVICE_SVM_FINE_GRAIN_BUFFER.
The cl_device_svm_capabilities must not include CL_DEVICE_SVM_FINE_GRAIN_SYSTEM, a standard Rust Vec! should be used instead.

pub fn with_capacity(context: &'a Context, capacity: usize) -> Result<Self>

Construct an empty SvmVec with the given capacity from a Context.

returns a Result containing an empty SvmVec, or the OpenCL error.

Panics

The cl_device_svm_capabilities of the Context must include CL_DEVICE_SVM_COARSE_GRAIN_BUFFER or CL_DEVICE_SVM_FINE_GRAIN_BUFFER.
The cl_device_svm_capabilities must not include CL_DEVICE_SVM_FINE_GRAIN_SYSTEM, a standard Rust Vec! should be used instead.

pub fn allocate_zeroed(context: &'a Context, len: usize) -> Result<Self>

Construct an SvmVec with the given len of values from a Context and the svm_capabilities of the device (or devices) in the Context.

Panics

The function will panic if the cl_device_svm_capabilities of the Context does not include CL_DEVICE_SVM_FINE_GRAIN_BUFFER.

returns a Result containing an SvmVec with len values of zeroed memory, or the OpenCL error.

pub fn reserve(&mut self, capacity: usize) -> Result<()>

Reserve vector capacity.
returns an empty Result or the OpenCL error.

pub fn push(&mut self, elem: T)

Push a value onto the vector.

Panics

The function will panic if a coarse grain buffer attempts to grow the vector.

pub fn pop(&mut self) -> Option<T>

Pop a value from the vector.

pub fn insert(&mut self, index: usize, elem: T)

Insert a value into the vector at index.

Panics

The function will panic if the index is out of bounds or if a coarse grain buffer attempts to grow the vector.

pub fn remove(&mut self, index: usize) -> T

Remove a value from the vector at index.

Panics

The function will panic if the index is out of bounds.

pub fn drain(&mut self) -> Drain<'_, T>

Drain the vector.

Trait Implementations

impl<'a, T: Debug> Debug for SvmVec<'a, T>

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

Formats the value using the given formatter.

impl<'a, T> Deref for SvmVec<'a, T>

type Target = [T]

The resulting type after dereferencing.

fn deref(&self) -> &[T]

Dereferences the value.

impl<'a, T> DerefMut for SvmVec<'a, T>

fn deref_mut(&mut self) -> &mut [T]

Mutably dereferences the value.

impl<'a, T> Drop for SvmVec<'a, T>

fn drop(&mut self)

Executes the destructor for this type.

impl<'a, T> IntoIterator for SvmVec<'a, T>

type Item = T

The type of the elements being iterated over.

type IntoIter = IntoIter<'a, Self::Item>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.