Struct ocl::builders::BufferWriteCmd

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

A buffer command builder used to enqueue writes.

See SDK docs for more details.

Methods

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

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

Specifies a queue to use for this call only.

Overrides the buffer's default queue if one is set. If no default queue is set, this method must be called before enqueuing the command.

pub unsafe fn block(self, block: bool) -> BufferWriteCmd<'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.

pub fn offset(self, offset: usize) -> BufferWriteCmd<'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.

pub fn src_offset(self, src_offset: usize) -> BufferWriteCmd<'c, 'd, T>

Sets an offset into the source data.

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

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

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

Sets the total length of data to write.

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

Defaults to the length of the write source provided. Panics if ::rect has been called.

pub 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
) -> BufferWriteCmd<'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, src_offset, or ::len have been called.

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

Specifies an event or list of events to wait on before the command will run.

When events generated using the ::enew method of other, previously enqueued commands are passed here (either individually or as part of an EventList), this command will not execute until those commands have completed.

Using events can compliment the use of queues to order commands by creating temporal dependencies between them (where commands in one queue must wait for the completion of commands in another). Events can also supplant queues altogether when, for example, using out-of-order queues.

Example

// Create an event list:
let mut event_list = EventList::new();
// Enqueue a kernel on `queue_1`, creating an event representing the kernel
// command in our list:
kernel.cmd().queue(&queue_1).enew(&mut event_list).enq()?;
// Write to a buffer using `queue_2`, ensuring the write does not begin until
// after the kernel command has completed:
buffer.write(rwvec.clone()).queue(&queue_2).ewait(&event_list).enq_async()?;

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

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

The destination can be a mutable reference to an empty event (created using Event::empty) or a mutable reference to an event list.

After this command is enqueued, the event in the destination can be passed to the ::ewait method of another command. Doing so will cause the other command to wait until this command has completed before executing.

Using events can compliment the use of queues to order commands by creating temporal dependencies between them (where commands in one queue must wait for the completion of commands in another). Events can also supplant queues altogether when, for example, using out-of-order queues.

Example

// Create an event list:
let mut event = Event::empty();
// Enqueue a kernel on `queue_1`, creating an event representing the kernel
// command in our list:
kernel.cmd().queue(&queue_1).enew(&mut event).enq()?;
// Write to a buffer using `queue_2`, ensuring the write does not begin until
// after the kernel command has completed:
buffer.write(rwvec.clone()).queue(&queue_2).ewait(&event).enq_async()?;

pub 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).

pub fn enq_async(self) -> OclResult<FutureReadGuard<Vec<T>>>

Enqueues this command and returns a future representing its completion which resolves to a read guard usable within subsequent futures.

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

The returned future must be resolved.

pub fn enq_async_then_write(self) -> OclResult<FutureWriteGuard<Vec<T>>>

Enqueues this command and returns a future representing its completion.

The returned future resolves to a write guard providing exclusive data access available within subsequent futures. This is important when a write must occur at the correct time in the global read/write order.

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

The returned future must be resolved.