Struct ocl::Buffer
[−]
[src]
pub struct Buffer<T: OclNum> { // some fields omitted }
A buffer with an optional built-in vector.
Data is stored both remotely in a memory buffer on the device associated with
queue and optionally in a vector (self.vec) in host (local) memory for
convenient use as a workspace etc.
The host side vector must be manually synchronized with the device side buffer
using ::fill_vec, ::flush_vec, etc. Data within the contained vector
should generally be considered stale except immediately after a fill/flush
(exception: pinned memory).
Fill/flush methods are for convenience and are equivalent to the psuedocode: read_into(self.vec) and write_from(self.vec).
Stability
Read/write/fill/flush methods will eventually be returning a result instead of panicing upon error.
Methods
impl<T: OclNum> Buffer<T>[src]
Panics
All methods will panic upon any OpenCL error.
fn new<E: BufferDims>(dims: &E, queue: &Queue) -> Buffer<T>
Creates a new read/write Buffer with dimensions: dims which will use the
command queue: queue (and its associated device and context) for all operations.
The device side buffer will be allocated a size based on the maximum workgroup
size of the device. This helps ensure that kernels do not attempt to read
from or write to memory beyond the length of the buffer (see crate level
documentation for more details about how dimensions are used). The buffer
will be initialized with a sensible default value (probably 0).
Other Method Panics
The returned Buffer contains no host side vector. Functions associated with
one such as .enqueue_flush_vec(), enqueue_fill_vec(), etc. will panic.
[FIXME]: Return result.
fn with_vec<E: BufferDims>(dims: &E, queue: &Queue) -> Buffer<T>
Creates a new read/write Buffer with a host side working copy of data. Host vector and device buffer are initialized with a sensible default value. [FIXME]: Return result.
fn with_vec_initialized_to<E: BufferDims>(init_val: T, dims: &E, queue: &Queue) -> Buffer<T>
[UNSTABLE]: Convenience method.
Creates a new read/write Buffer with a host side working copy of data.
Host vector and device buffer are initialized with the value, init_val.
[FIXME]: Return result.
fn with_vec_shuffled<E: BufferDims>(vals: (T, T), dims: &E, queue: &Queue) -> Buffer<T>
[UNSTABLE]: Convenience method.
Creates a new read/write Buffer with a vector initialized with a series of
integers ranging from vals.0 to vals.1 (closed) which are shuffled
randomly.
Note: Even if the Buffer type is a floating point type, the values returned will still be integral values (e.g.: 1.0, 2.0, 3.0, etc.).
Security
Resulting values are not cryptographically secure. [FIXME]: Return result.
fn with_vec_scrambled<E: BufferDims>(vals: (T, T), dims: &E, queue: &Queue) -> Buffer<T>
[UNSTABLE]: Convenience method.
Creates a new read/write Buffer with a vector initialized with random values
within the (half-open) range vals.0..vals.1.
Security
Resulting values are not cryptographically secure. [FIXME]: Return result.
unsafe fn new_core_unchecked(flags: MemFlags, len: usize, host_ptr: Option<&[T]>, queue: &Queue) -> Buffer<T>
Creates a new Buffer with caller-managed buffer length, type, flags, and initialization.
Examples
See examples/buffer_unchecked.rs.
Parameter Reference Documentation
Refer to the following page for information about how to configure flags and other options for the buffer. https://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clCreateBuffer.html
Safety
No creation time checks are made to help prevent device buffer overruns,
etc. Caller should be sure to initialize the device side memory with a
write. Any host side memory pointed to by host_ptr is at even greater
risk if used with CL_MEM_USE_HOST_PTR (see below).
[IMPORTANT] Practically every read and write to an Buffer created in this way is
potentially unsafe. Because .enqueue_read() and .enqueue_write() do not require an
unsafe block, their implied promises about safety may be broken at any time.
You need to know what you're doing and be extra careful using an Buffer created with this method because it badly breaks Rust's usual safety promises even outside of an unsafe block.
This is horribly un-idiomatic Rust. You have been warned.
NOTE: The above important warnings probably only apply to buffers created with
the CL_MEM_USE_HOST_PTR flag because the memory is considered 'pinned' but
there may also be implementation specific issues which haven't been considered
or are unknown.
[FIXME]: Return result.
fn write(&self, data: &[T], offset: usize) -> OclResult<()>
Writes data.len() * mem::size_of::<T>() bytes from data to the (remote)
device buffer with a remote offset of offset and blocks until complete.
Panics
offset must be less than the length of the buffer.
The length of data must be less than the length of the buffer minus offset.
Errors upon any OpenCL error.
fn read(&self, data: &mut [T], offset: usize) -> OclResult<()>
Reads data.len() * mem::size_of::<T>() bytes from the (remote) device buffer
into data with a remote offset of offset and blocks until complete.
Errors
offset must be less than the length of the buffer.
The length of data must be less than the length of the buffer minus offset.
Errors upon any OpenCL error.
fn enqueue_write(&self, data: &[T], offset: usize, block: bool, wait_list: Option<&EventList>, dest_list: Option<&mut EventList>) -> OclResult<()>
Enqueues writing data.len() * mem::size_of::<T>() bytes from data to the
device buffer with a remote offset of offset.
Will optionally wait for events in wait_list to finish before writing.
Will also optionally add a new event associated with the write to dest_list.
[UPDATE] If the dest_list event list is None, the write will be blocking, otherwise
returns immediately.
Data Integrity
Ensure that the memory referred to by data is unmolested until the
write completes if passing a dest_list.
Errors
offset must be less than the length of the buffer.
The length of data must be less than the length of the buffer minus offset.
Errors upon any OpenCL error.
unsafe fn enqueue_read(&self, data: &mut [T], offset: usize, block: bool, wait_list: Option<&EventList>, dest_list: Option<&mut EventList>) -> OclResult<()>
Enqueues reading data.len() * mem::size_of::<T>() bytes from the device
buffer into data with a remote offset of offset.
Will optionally wait for events in wait_list to finish
before reading. Will also optionally add a new event associated with
the read to dest_list.
[UPDATE] If the dest_list event list is None, the read will be blocking, otherwise
returns immediately.
Safety
Bad things will happen if the memory referred to by data is freed and
reallocated before the read completes. It's up to the caller to make
sure that the new event added to dest_list completes. Use
'dest_list.last()' right after the calling ::read_async to get a.
reference to the event associated with the read. [NOTE: Improved ease
of use is coming to the event api eventually]
Errors
offset must be less than the length of the buffer.
The length of data must be less than the length of the buffer minus offset.
Errors upon any OpenCL error.
fn enqueue_flush_vec(&mut self, block: bool, wait_list: Option<&EventList>, dest_list: Option<&mut EventList>) -> OclResult<()>
After waiting on events in wait_list to finish, writes the contents of
'self.vec' to the remote device data buffer and adds a new event to dest_list.
Data Integrity
Ensure that this Buffer lives until until the write completes if
passing a dest_list.
[UPDATE] Will block until the write is complete if dest_list is None.
Errors
Errors if this Buffer contains no vector or upon any OpenCL error.
unsafe fn enqueue_fill_vec(&mut self, block: bool, wait_list: Option<&EventList>, dest_list: Option<&mut EventList>) -> OclResult<()>
After waiting on events in wait_list to finish, reads the remote device
data buffer into 'self.vec' and adds a new event to dest_list.
[UPDATE] Will block until the read is complete and the internal vector is filled if
dest_list is None.
Safety
Currently up to the caller to ensure this Buffer lives long enough
for the read to complete.
TODO: Keep an internal eventlist to track pending reads and cancel them
if this Buffer is destroyed beforehand.
Errors
Errors if this Buffer contains no vector or upon any OpenCL error.
fn flush_vec(&mut self)
Writes the contents of self.vec to the remote device data buffer and
blocks until completed.
Equivalent to .enqueue_flush_vec(true, None, None).
Panics
Panics if this Buffer contains no vector or upon any OpenCL error.
fn fill_vec(&mut self)
Reads the remote device data buffer into self.vec and blocks until completed.
Equivalent to .enqueue_fill_vec(true, None, None).
Panics
Panics if this Buffer contains no vector or upon any OpenCL error.
fn wait(&self)
Blocks until the underlying command queue has completed all commands.
fn set_all_to(&mut self, val: T) -> OclResult<()>
[UNSTABLE]: Convenience method.
Panics [UPDATE ME]
Panics if this Buffer contains no vector. [FIXME]: GET WORKING EVEN WITH NO CONTAINED VECTOR
fn set_range_to(&mut self, val: T, range: Range<usize>) -> OclResult<()>
[UNSTABLE]: Convenience method.
Panics [UPDATE ME]
Panics if this Buffer contains no vector.
[FIXME]: GET WORKING EVEN WITH NO CONTAINED VECTOR
fn len(&self) -> usize
Returns the length of the Buffer.
This is the length of both the device side buffer and the host side vector, if any. This may not agree with desired dataset size because it will have been rounded up to the nearest maximum workgroup size of the device on which it was created.
unsafe fn resize<B: BufferDims>(&mut self, new_dims: &B, queue: &Queue)
Resizes Buffer. Recreates device side buffer and dangles any references kernels may have had to the old buffer.
Safety
[IMPORTANT]: You must manually reassign any kernel arguments which may have had a reference to the (device side) buffer associated with this Buffer. [FIXME]: Return result.
fn vec(&self) -> &Vec<T>
Returns a reference to the local vector associated with this buffer.
Contents of this vector may change during use due to previously enqueued reads. ([FIXME]: Is this a safety issue?)
Failures
[FIXME: UPDATE DOC] Returns an error if this buffer contains no vector.
unsafe fn vec_mut(&mut self) -> &mut Vec<T>
Returns a mutable reference to the local vector associated with this buffer.
Contents of this vector may change during use due to previously enqueued read.
Failures
[FIXME: UPDATE DOC] Returns an error if this buffer contains no vector.
Safety
Could cause data collisions, etc. May not be unsafe strictly speaking (is it?) but marked as such to alert the caller to any potential synchronization issues from previously enqueued reads.
unsafe fn get_unchecked(&self, idx: usize) -> &T
Returns an immutable reference to the value located at index idx, bypassing
bounds and enum variant checks.
Safety
Assumes self.vec is a VecOption::Vec and that the index idx is within
the vector bounds.
unsafe fn get_unchecked_mut(&mut self, idx: usize) -> &mut T
Returns a mutable reference to the value located at index idx, bypassing
bounds and enum variant checks.
Safety
Assumes self.vec is a VecOption::Vec and that the index idx is within
bounds. Might eat all the laundry.
fn core_as_ref(&self) -> &MemCore
Returns a copy of the core buffer object reference.
fn set_queue<'a>(&'a mut self, queue: Queue) -> &'a mut Buffer<T>
Changes the queue used by this Buffer for reads and writes, etc.
Returns a ref for chaining i.e.:
buffer.set_queue(queue).flush_vec(....);
Safety
[FIXME]: Update this. Safety is pretty much fine.
Not all implications of changing the queue, particularly if the new queue
is associated with a new device which has different workgroup size dimensions,
have been considered or are dealt with. For now, considering these cases is
left to the caller. It's probably a good idea to at least call .resize()
after calling this method.
fn iter<'a>(&'a self) -> Iter<'a, T>
fn iter_mut<'a>(&'a mut self) -> IterMut<'a, T>
fn print_simple(&mut self)
[UNSTABLE]: Convenience method.
Panics
Panics if this Buffer contains no vector. [FIXME]: GET WORKING EVEN WITH NO CONTAINED VECTOR
fn print_val_range(&mut self, every: usize, val_range: Option<(T, T)>)
[UNSTABLE]: Convenience method.
Panics
Panics if this Buffer contains no vector. [FIXME]: GET WORKING EVEN WITH NO CONTAINED VECTOR
fn print(&mut self, every: usize, val_range: Option<(T, T)>, idx_range_opt: Option<Range<usize>>, zeros: bool)
[UNSTABLE]: Convenience/debugging method. May be moved/renamed/deleted. [FIXME]: CREATE AN EMPTY VECTOR FOR PRINTING IF NONE EXISTS INSTEAD OF PANICING.
Panics
Panics if this Buffer contains no vector. [FIXME]: GET WORKING EVEN WITH NO CONTAINED VECTOR
fn mem_info(&self, info_kind: MemInfo) -> MemInfoResult
Returns info about this buffer.
fn fmt_mem_info(&self, f: &mut Formatter) -> Result
Trait Implementations
impl<T: OclNum> BufferTest<T> for Buffer<T>[src]
fn read_idx_direct(&self, idx: usize) -> T
impl<T: Clone + OclNum> Clone for Buffer<T>[src]
fn clone(&self) -> Buffer<T>
Returns a copy of the value. Read more
fn clone_from(&mut self, source: &Self)1.0.0
Performs copy-assignment from source. Read more
impl<T: Debug + OclNum> Debug for Buffer<T>[src]
impl<T: OclNum> Display for Buffer<T>[src]
impl<T: OclNum> Index<usize> for Buffer<T>[src]
type Output = T
The returned type after indexing
fn index<'a>(&'a self, index: usize) -> &'a T
Panics
Panics if this Buffer contains no vector.
impl<T: OclNum> IndexMut<usize> for Buffer<T>[src]
fn index_mut<'a>(&'a mut self, index: usize) -> &'a mut T
Panics
Panics if this Buffer contains no vector.
impl<'b, T: OclNum> Index<&'b usize> for Buffer<T>[src]
type Output = T
The returned type after indexing
fn index<'a>(&'a self, index: &'b usize) -> &'a T
Panics
Panics if this Buffer contains no vector.
impl<'b, T: OclNum> IndexMut<&'b usize> for Buffer<T>[src]
fn index_mut<'a>(&'a mut self, index: &'b usize) -> &'a mut T
Panics
Panics if this Buffer contains no vector.
impl<T: OclNum> Index<Range<usize>> for Buffer<T>[src]
type Output = [T]
The returned type after indexing
fn index<'a>(&'a self, range: Range<usize>) -> &'a [T]
Panics
Panics if this Buffer contains no vector.
impl<T: OclNum> IndexMut<Range<usize>> for Buffer<T>[src]
fn index_mut<'a>(&'a mut self, range: Range<usize>) -> &'a mut [T]
Panics
Panics if this Buffer contains no vector.
impl<T: OclNum> Index<RangeFull> for Buffer<T>[src]
type Output = [T]
The returned type after indexing
fn index<'a>(&'a self, range: RangeFull) -> &'a [T]
Panics
Panics if this Buffer contains no vector.