Struct ocl::builders::BufferReadCmd

#[must_use = "commands do nothing unless enqueued"]
pub struct BufferReadCmd<'c, 'd, T> where
    T: 'c + 'd,  { /* fields omitted */ }

A buffer command builder used to enqueue reads.

See SDK docs for more details.

Methods

impl<'c, 'd, T> BufferReadCmd<'c, 'd, T> where
    T: OclPrm, 

fn queue(self, queue: &'c Queue) -> BufferReadCmd<'c, 'd, T>

Specifies a queue to use for this call only.

unsafe fn block(self, block: bool) -> BufferReadCmd<'c, 'd, T>

Specifies whether or not to block the current thread until completion.

Ignored if this is not a read or write operation.

Default is block = true.

Safety

When performing non-blocking reads or writes, the caller must ensure that the data being read from or written to is not accessed improperly until the command completes. Use events (Event::wait_for) or the command queue (Queue::finish) to synchronize.

If possible, prefer instead to use ::map with ::enq_async for optimal performance and data integrity.

fn offset(self, offset: usize) -> BufferReadCmd<'c, 'd, T>

Sets the linear offset for an operation.

Panics

The 'shape' may not have already been set to rectangular by the ::rect function.

fn dst_offset(self, dst_offset: usize) -> BufferReadCmd<'c, 'd, T>

Sets an offset into the destination data.

Equivalent to setting the start position of a slice into the destination data (e.g. dst_data[dst_offset..]). Use ::len to set the end position (resulting in dst_data[dst_offset..len]).

Defaults to 0 if not set. Panics if ::rect has been called.

fn len(self, len: usize) -> BufferReadCmd<'c, 'd, T>

Sets the total length of data to read.

Equivalent to setting the end position of a slice into the destination data (e.g. destination[..len]). Use ::dst_offset to set the start position (resulting in dst_data[dst_offset..len]).

Defaults to the total length of the read destination provided. Panics if ::rect has been called.

fn rect(
    self,
    src_origin: [usize; 3],
    dst_origin: [usize; 3],
    region: [usize; 3],
    src_row_pitch_bytes: usize,
    src_slc_pitch_bytes: usize,
    dst_row_pitch_bytes: usize,
    dst_slc_pitch_bytes: usize
) -> BufferReadCmd<'c, 'd, T>

Specifies that this will be a rectangularly shaped operation (the default being linear).

Row and slice pitches must all be expressed in bytes.

Panics if :offset, dst_offset, or ::len have been called.

fn ewait<'e, Ewl>(self, ewait: Ewl) -> BufferReadCmd<'c, 'd, T> where
    'e: 'c,
    Ewl: Into<ClWaitListPtrEnum<'e>>, 

Specifies a list of events to wait on before the command will run.

fn ewait_opt<'e, Ewl>(self, ewait: Option<Ewl>) -> BufferReadCmd<'c, 'd, T> where
    'e: 'c,
    Ewl: Into<ClWaitListPtrEnum<'e>>, 

Specifies a list of events to wait on before the command will run or resets it to None.

fn enew<'e, En>(self, enew: En) -> BufferReadCmd<'c, 'd, T> where
    'e: 'c,
    En: Into<ClNullEventPtrEnum<'e>>, 

Specifies the destination for a new, optionally created event associated with this command.

fn enew_opt<'e, En>(self, enew: Option<En>) -> BufferReadCmd<'c, 'd, T> where
    'e: 'c,
    En: Into<ClNullEventPtrEnum<'e>>, 

Specifies a destination for a new, optionally created event associated with this command or resets it to None.

fn enq(self) -> OclResult<()>

Enqueues this command, blocking the current thread until it is complete.

If an RwVec is being used as the data destination, the current thread will be blocked until an exclusive lock can be obtained before running the command (which will also block for its duration).

fn enq_async(self) -> OclResult<FutureRwGuard<T, WriteGuard<T>>>

Enqueues this command and returns a future representing its completion which resolves to a guard providing exclusive data access usable within subsequent futures.

A data destination container appropriate for an asynchronous operation (such as RwVec) must have been passed to ::read.