Struct ocl::builders::BufferBuilder

#[must_use = "builders do nothing unless \'::build\' is called"]
pub struct BufferBuilder<'a, T> where
    T: OclPrm,  { /* fields omitted */ }

A buffer builder.

Methods

impl<'a, T> BufferBuilder<'a, T> where
    T: 'a + OclPrm, 

pub fn new() -> BufferBuilder<'a, T>

Returns a new buffer builder.

pub fn context<'o>(self, context: &'o Context) -> BufferBuilder<'a, T> where
    'o: 'a, 

Sets the context with which to associate the buffer.

May not be used in conjunction with ::queue (use one or the other).

pub fn queue<'b>(self, default_queue: Queue) -> BufferBuilder<'a, T>

Specifies the default queue used to be used by the buffer for all command enqueue operations (reads, writes, etc.).

The default queue is the queue which will be used when enqueuing commands if no queue is specified.

Without a default queue:

buffer.read(data).queue(&queue).enq()?;

With a default queue:

buffer.read(data).enq()?;

If this is set, the context associated with the default_queue will be used when creating the buffer. Attempting to specify the context separately (by calling ::context) will cause a panic.

pub fn flags<'b>(self, flags: MemFlags) -> BufferBuilder<'a, T>

Sets the flags used when creating the buffer.

Defaults to flags::MEM_READ_WRITE aka. MemFlags::new().read_write() if this is not set. See the SDK Docs for more information about flags. Note that the names of all flags in this library have the CL_ prefix removed for brevity.

Panics

Due to its unsafety, setting the MEM_USE_HOST_PTR/MemFlags::new()::use_host_ptr() flag will cause a panic. Use the ::use_host_slice method instead.

pub unsafe fn use_host_slice<'d>(
    self,
    host_slice: &'d [T]
) -> BufferBuilder<'a, T> where
    'd: 'a, 

Specifies a region of host memory to use as storage for the buffer.

OpenCL implementations are allowed to cache the buffer contents pointed to by host_slice in device memory. This cached copy can be used when kernels are executed on a device.

The result of OpenCL commands that operate on multiple buffer objects created with the same host_slice or overlapping host regions is considered to be undefined

Refer to the description of the alignment rules for host_slice for memory objects (buffer and images) created using this method.

Automatically sets the flags::MEM_USE_HOST_PTR aka. MemFlags::new().use_host_ptr() flag.

Panics

::copy_host_slice or ::use_host_slice must not have already been called.

Safety

The caller must ensure that host_slice lives until the buffer is destroyed. The caller must also ensure that only one buffer uses host_slice and that it is not tampered with inappropriately.

pub fn copy_host_slice<'d>(self, host_slice: &'d [T]) -> BufferBuilder<'a, T> where
    'd: 'a, 

Specifies a region of memory to copy into the buffer upon creation.

Automatically sets the flags::MEM_COPY_HOST_PTR aka. MemFlags::new().copy_host_ptr() flag.

Panics

::copy_host_slice or ::use_host_slice must not have already been called.

pub fn len<'b, D>(self, len: D) -> BufferBuilder<'a, T> where
    D: Into<SpatialDims>, 

Sets the length for this buffer.

Note that although sizes in the standard OpenCL API are expressed in bytes, sizes, lengths, and dimensions in this library are always specified in bytes / sizeof(T) (like everything else in Rust) unless otherwise noted.

pub fn fill_val(self, fill_val: T) -> BufferBuilder<'a, T>

Allows the caller to automatically fill the buffer with a value (such as zero) immediately after creation.

Use ::fill_event to set an event associated with the completion of the fill command if you want it to execute asynchronously (it will otherwise block the calling thread).

Platforms that have trouble with clEnqueueFillBuffer such as pocl should not use this option and should handle initializing buffers manually (using a kernel or copy host data flag).

Examples

• TODO: Provide examples once this stabilizes.

[UNSTABLE]: May be changed or removed.

pub fn fill_event<'b, 'e, En>(self, enew: En) -> BufferBuilder<'a, T> where
    'e: 'a,
    En: Into<ClNullEventPtrEnum<'e>>, 

Specifies the (empty) event to use for association with the completion of the fill command.

enew specifies an empty event (generally a &mut Event) to be associated with the fill command which will be enqueued after creation and just before returning the new buffer. It is up to the caller to ensure that the command has completed before performing any other operations on the buffer. Failure to do so may cause the fill command to run after subsequently queued commands if multiple or out-of-order queues are being used.

Not calling this method at all will cause the fill command to block before returning the new buffer and is the safe option if you don't want to worry about it.

pub fn build(self) -> OclResult<Buffer<T>>

Creates a buffer and returns it.

Dimensions and either a context or default queue must be specified before calling ::build.

Trait Implementations

impl<'a, T: Debug> Debug for BufferBuilder<'a, T> where
    T: OclPrm, 

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.