Struct ocl::Kernel

pub struct Kernel { /* fields omitted */ }

A kernel which represents a 'procedure'.

Corresponds to code which must have already been compiled into a program.

Set arguments using ::set_arg or any of the ::set_arg... methods.

Kernel includes features that a raw OpenCL kernel does not, including:

1. Type-checked arguments (not just size-checked)
2. Named arguments (with a &'static str name)
3. Prevention of a potential (difficult to debug) segfault if a buffer or image used by a kernel is dropped prematurely.
4. Stored defaults for the:
   • Queue
   • Global Work Offset
   • Global Work Size
   • Local Work Size

Clone and Send

A Kernel may not be cloned but may be sent between threads. This ensures that no two threads create a race condition by attempting to set an argument and enqueue a kernel at the same time. Use the KernelBuilder to create multiple identical kernels (KernelBuilder is clonable and re-usable).

Methods

impl Kernel

pub fn builder<'p>() -> KernelBuilder<'p>

Returns a new KernelBuilder.

pub fn named_arg_idx(&self, name: &'static str) -> Option<u32>

Returns the argument index of a named argument if it exists.

pub unsafe fn set_arg_unchecked(
    &self,
    arg_idx: u32,
    arg_val: ArgVal
) -> OclResult<()>

Sets an argument by index without checks of any kind.

Setting buffer or image (cl_mem) arguments this way may cause segfaults or errors if the buffer goes out of scope at any point before this kernel is dropped.

This also bypasses the check to determine if the type of the value you pass here matches the type defined in your kernel.

pub fn set_arg<'a, T, Ai, Av>(&self, idx: Ai, arg: Av) -> OclResult<()> where
    T: OclPrm,
    Ai: Into<ArgIdxSpecifier>,
    Av: Into<ArgValConverter<'a, T>>, 

Sets a Buffer, Image, scalar, or vector argument by index or by name.

Example

// Create a kernel with arguments corresponding to those in the kernel.
// Just for fun, one argument will be 'named':
let kern = ocl_pq.kernel_builder("multiply_by_scalar")
    .arg(&0)
    .arg(None::<&Buffer<f32>>)
    .arg_named("result", None::<&Buffer<f32>>)
    .build()?;

// Set our named argument. The Option<_> wrapper is, well... optional:
kern.set_arg("result", &result_buffer)?;
// We can also set arguments (named or not) by index. Just for
// demonstration, we'll set one using an option:
kern.set_arg(0, &COEFF)?;
kern.set_arg(1, Some(&source_buffer))?;
kern.set_arg(2, &result_buffer)?;

pub fn set_arg_buf_named<'a, T, M>(
    &'a self,
    name: &'static str,
    buffer_opt: Option<M>
) -> OclResult<()> where
    T: OclPrm,
    M: AsMem<T> + MemCmdAll, 

Deprecated since 0.18.0

: Use ::set_arg instead.

Modifies the kernel argument named: name.

pub fn set_arg_img_named<'a, T, M>(
    &'a self,
    name: &'static str,
    image_opt: Option<M>
) -> OclResult<()> where
    T: OclPrm,
    M: AsMem<T> + MemCmdAll, 

Deprecated since 0.18.0

: Use ::set_arg instead.

Modifies the kernel argument named: name.

pub fn set_arg_smp_named<'a>(
    &'a self,
    name: &'static str,
    sampler_opt: Option<&Sampler>
) -> OclResult<()>

Deprecated since 0.18.0

: Use ::set_arg_sampler_named instead.

Sets the value of a named sampler argument.

pub fn set_arg_scl_named<'a, T, B>(
    &'a self,
    name: &'static str,
    scalar: B
) -> OclResult<()> where
    T: OclPrm,
    B: Borrow<T>, 

Deprecated since 0.18.0

: Use ::set_arg instead.

Modifies the kernel argument named: name.

pub fn set_arg_vec_named<'a, T, B>(
    &'a self,
    name: &'static str,
    vector: B
) -> OclResult<()> where
    T: OclPrm,
    B: Borrow<T>, 

Deprecated since 0.18.0

: Use ::set_arg instead.

Modifies the kernel argument named: name.

pub fn set_arg_sampler_named<'a, Ai>(
    &'a self,
    idx: Ai,
    sampler_opt: Option<&Sampler>
) -> OclResult<()> where
    Ai: Into<ArgIdxSpecifier>, 

Sets the value of a named sampler argument.

pub fn cmd(&self) -> KernelCmd

Returns a command builder which is used to chain parameters of an 'enqueue' command together.

pub unsafe fn enq(&self) -> OclResult<()>

Enqueues this kernel on the default queue using the default work sizes and offsets.

Shorthand for .cmd().enq()

Safety

All kernel code must be considered untrusted. Therefore the act of calling this function contains implied unsafety even though the API itself is safe.

pub fn set_default_queue(&mut self, queue: Queue) -> &mut Kernel

Changes the default queue.

Returns a ref for chaining i.e.:

kernel.set_default_queue(queue).enqueue(....);

Even when used as above, the queue is changed permanently, not just for the one call. Changing the queue is cheap so feel free to change as often as needed.

If you want to change the queue for only a single call, use: ::cmd.queue(...)...enq()...

The new queue must be associated with a device associated with the kernel's program.

pub fn get_gwo(&self) -> SpatialDims

Deprecated since 0.18.0

: Use ::global_work_offset instead.

Returns the default global work offset.

pub fn get_gws(&self) -> SpatialDims

Deprecated since 0.18.0

: Use ::global_work_size instead.

Returns the default global work size.

pub fn get_lws(&self) -> SpatialDims

Deprecated since 0.18.0

: Use ::local_work_size instead.

Returns the default local work size.

pub fn set_default_global_work_offset(
    &mut self,
    gwo: SpatialDims
) -> &mut Kernel

Sets the default global work offset.

pub fn set_default_global_work_size(&mut self, gws: SpatialDims) -> &mut Kernel

Sets the default global work size.

pub fn set_default_local_work_size(&mut self, lws: SpatialDims) -> &mut Kernel

Sets the default local work size.

pub fn default_queue<'a>(&'a self) -> Option<&'a Queue>

Returns the default queue for this kernel if one has been set.

pub fn default_global_work_offset(&self) -> SpatialDims

Returns the default global work offset.

pub fn default_global_work_size(&self) -> SpatialDims

Returns the default global work size.

pub fn default_local_work_size(&self) -> SpatialDims

Returns the default local work size.

pub fn as_core<'a>(&'a self) -> &'a KernelCore

Returns a reference to the core pointer wrapper, usable by functions in the core module.

pub fn info(&self, info_kind: KernelInfo) -> OclCoreResult<KernelInfoResult>

Returns information about this kernel.

pub fn wg_info(
    &self,
    device: Device,
    info_kind: KernelWorkGroupInfo
) -> OclCoreResult<KernelWorkGroupInfoResult>

Returns work group information for this kernel.

pub fn arg_info(
    &self,
    arg_idx: u32,
    info_kind: KernelArgInfo
) -> OclCoreResult<KernelArgInfoResult>

Returns argument information for this kernel.

pub fn name(&self) -> OclCoreResult<String>

Returns the name of this kernel.

pub fn num_args(&self) -> OclCoreResult<u32>

Returns the number of arguments this kernel has.

Methods from Deref<Target = KernelCore>

pub fn as_ptr(&self) -> *mut c_void

Returns a pointer, do not store it.

pub fn program(&self) -> Result<Program, Error>

Returns the program associated with this kernel.

pub fn devices(&self) -> Result<Vec<DeviceId>, Error>

Trait Implementations

impl Debug for Kernel

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

Formats the value using the given formatter.

impl Display for Kernel

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

Formats the value using the given formatter.

impl Deref for Kernel

type Target = KernelCore

The resulting type after dereferencing.

fn deref<'a>(&'a self) -> &'a KernelCore

Dereferences the value.

impl Clone for Kernel

fn clone(&self) -> Kernel

Creates a new, identical kernel.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.