Struct opencl3::svm::SvmVec [−][src]
pub struct SvmVec<'a, T> { /* fields omitted */ }
Expand description
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
Whether the vector is fine grained
Whether the vector can use atomics
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.
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.
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.
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.
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.
Reserve vector capacity.
returns an empty Result or the OpenCL error.
Push a value onto the vector.
Panics
The function will panic if a coarse grain buffer attempts to grow the vector.
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.
Remove a value from the vector at index.
Panics
The function will panic if the index is out of bounds.