# Struct ocl::Kernel [−] [src]

    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`
[src]

#### `pub fn builder<'p>() -> KernelBuilder<'p>`
[src]

Returns a new `KernelBuilder`.

#### `pub fn named_arg_idx(&self, name: &'static str) -> Option<u32>`
[src]

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<()>`
[src]

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>>,`
[src]

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

### Example

ⓘThis example is not tested

    // 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,`
[src]

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,`
[src]

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<()>`
[src]

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>,`
[src]

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>,`
[src]

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>,`
[src]

Sets the value of a named sampler argument.

#### `pub fn cmd(&self) -> KernelCmd`
[src]

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

#### `pub unsafe fn enq(&self) -> OclResult<()>`
[src]

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`
[src]

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`
[src]

Deprecated since 0.18.0

: Use `::global_work_offset` instead.

Returns the default global work offset.

#### `pub fn get_gws(&self) -> SpatialDims`
[src]

Deprecated since 0.18.0

: Use `::global_work_size` instead.

Returns the default global work size.

#### `pub fn get_lws(&self) -> SpatialDims`
[src]

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`
[src]

Sets the default global work offset.

#### `pub fn set_default_global_work_size(&mut self, gws: SpatialDims) -> &mut Kernel`
[src]

Sets the default global work size.

#### `pub fn set_default_local_work_size(&mut self, lws: SpatialDims) -> &mut Kernel`
[src]

Sets the default local work size.

#### `pub fn default_queue<'a>(&'a self) -> Option<&'a Queue>`
[src]

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

#### `pub fn default_global_work_offset(&self) -> SpatialDims`
[src]

Returns the default global work offset.

#### `pub fn default_global_work_size(&self) -> SpatialDims`
[src]

Returns the default global work size.

#### `pub fn default_local_work_size(&self) -> SpatialDims`
[src]

Returns the default local work size.

#### `pub fn as_core<'a>(&'a self) -> &'a KernelCore`
[src]

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

#### `pub fn info(&self, info_kind: KernelInfo) -> OclCoreResult<KernelInfoResult>`
[src]

Returns information about this kernel.

#### `pub fn wg_info(
&self,
device: Device,
info_kind: KernelWorkGroupInfo
) -> OclCoreResult<KernelWorkGroupInfoResult>`
[src]

Returns work group information for this kernel.

#### `pub fn arg_info(
&self,
arg_idx: u32,
info_kind: KernelArgInfo
) -> OclCoreResult<KernelArgInfoResult>`
[src]

Returns argument information for this kernel.

#### `pub fn name(&self) -> OclCoreResult<String>`
[src]

Returns the name of this kernel.

#### `pub fn num_args(&self) -> OclCoreResult<u32>`
[src]

Returns the number of arguments this kernel has.

## Methods from Deref<Target = KernelCore>

#### `pub fn as_ptr(&self) -> *mut c_void`
[src]

Returns a pointer, do not store it.

#### `pub fn program(&self) -> Result<Program, Error>`
[src]

Returns the program associated with this kernel.

#### `pub fn devices(&self) -> Result<Vec<DeviceId>, Error>`
[src]

## Trait Implementations

### `impl Debug for Kernel`
[src]

#### `fn fmt(&self, __arg_0: &mut Formatter) -> Result`
[src]

Formats the value using the given formatter. Read more

### `impl Display for Kernel`
[src]

#### `fn fmt(&self, f: &mut Formatter) -> Result`
[src]

Formats the value using the given formatter. Read more

### `impl Deref for Kernel`
[src]

#### `type Target = KernelCore`

The resulting type after dereferencing.

#### `fn deref<'a>(&'a self) -> &'a KernelCore`
[src]

Dereferences the value.

### `impl Clone for Kernel`
[src]

#### `fn clone(&self) -> Kernel`
[src]

Creates a new, identical kernel.

#### `fn clone_from(&mut self, source: &Self)`
1.0.0
[src]

Performs copy-assignment from `source`. Read more

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)