pub struct Kernel { /* private fields */ }
Expand description
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:
- Type-checked arguments (not just size-checked)
- Named arguments (with a
&'static str
name) - Prevention of a potential (difficult to debug) segfault if a buffer or image used by a kernel is dropped prematurely.
- 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).
Implementations§
source§impl Kernel
impl Kernel
sourcepub fn builder<'p>() -> KernelBuilder<'p>
pub fn builder<'p>() -> KernelBuilder<'p>
Returns a new KernelBuilder
.
sourcepub fn named_arg_idx(&self, name: &'static str) -> Option<u32>
pub fn named_arg_idx(&self, name: &'static str) -> Option<u32>
Returns the argument index of a named argument if it exists.
sourcepub unsafe fn set_arg_unchecked(
&self,
arg_idx: u32,
arg_val: ArgVal<'_>
) -> OclResult<()>
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.
sourcepub fn set_arg<'a, T, Ai, Av>(&self, idx: Ai, arg: Av) -> OclResult<()>
pub fn set_arg<'a, T, Ai, Av>(&self, idx: Ai, arg: Av) -> OclResult<()>
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)?;
sourcepub fn set_arg_buf_named<'a, T, M>(
&'a self,
name: &'static str,
buffer_opt: Option<M>
) -> OclResult<()>
👎Deprecated since 0.18.0: Use ::set_arg
instead.
pub fn set_arg_buf_named<'a, T, M>( &'a self, name: &'static str, buffer_opt: Option<M> ) -> OclResult<()>
::set_arg
instead.Modifies the kernel argument named: name
.
sourcepub fn set_arg_img_named<'a, T, M>(
&'a self,
name: &'static str,
image_opt: Option<M>
) -> OclResult<()>
👎Deprecated since 0.18.0: Use ::set_arg
instead.
pub fn set_arg_img_named<'a, T, M>( &'a self, name: &'static str, image_opt: Option<M> ) -> OclResult<()>
::set_arg
instead.Modifies the kernel argument named: name
.
sourcepub 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.
pub fn set_arg_smp_named<'a>( &'a self, name: &'static str, sampler_opt: Option<&Sampler> ) -> OclResult<()>
::set_arg_sampler_named
instead.Sets the value of a named sampler argument.
sourcepub fn set_arg_scl_named<'a, T, B>(
&'a self,
name: &'static str,
scalar: B
) -> OclResult<()>
👎Deprecated since 0.18.0: Use ::set_arg
instead.
pub fn set_arg_scl_named<'a, T, B>( &'a self, name: &'static str, scalar: B ) -> OclResult<()>
::set_arg
instead.Modifies the kernel argument named: name
.
sourcepub fn set_arg_vec_named<'a, T, B>(
&'a self,
name: &'static str,
vector: B
) -> OclResult<()>
👎Deprecated since 0.18.0: Use ::set_arg
instead.
pub fn set_arg_vec_named<'a, T, B>( &'a self, name: &'static str, vector: B ) -> OclResult<()>
::set_arg
instead.Modifies the kernel argument named: name
.
sourcepub fn set_arg_sampler_named<'a, Ai>(
&'a self,
idx: Ai,
sampler_opt: Option<&Sampler>
) -> OclResult<()>where
Ai: Into<ArgIdxSpecifier>,
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.
sourcepub fn cmd(&self) -> KernelCmd<'_>
pub fn cmd(&self) -> KernelCmd<'_>
Returns a command builder which is used to chain parameters of an ‘enqueue’ command together.
sourcepub unsafe fn enq(&self) -> OclResult<()>
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.
sourcepub fn set_default_queue(&mut self, queue: Queue) -> &mut Kernel
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.
sourcepub fn get_gwo(&self) -> SpatialDims
👎Deprecated since 0.18.0: Use ::global_work_offset
instead.
pub fn get_gwo(&self) -> SpatialDims
::global_work_offset
instead.Returns the default global work offset.
sourcepub fn get_gws(&self) -> SpatialDims
👎Deprecated since 0.18.0: Use ::global_work_size
instead.
pub fn get_gws(&self) -> SpatialDims
::global_work_size
instead.Returns the default global work size.
sourcepub fn get_lws(&self) -> SpatialDims
👎Deprecated since 0.18.0: Use ::local_work_size
instead.
pub fn get_lws(&self) -> SpatialDims
::local_work_size
instead.Returns the default local work size.
sourcepub fn set_default_global_work_offset(
&mut self,
gwo: SpatialDims
) -> &mut Kernel
pub fn set_default_global_work_offset( &mut self, gwo: SpatialDims ) -> &mut Kernel
Sets the default global work offset.
sourcepub fn set_default_global_work_size(&mut self, gws: SpatialDims) -> &mut Kernel
pub fn set_default_global_work_size(&mut self, gws: SpatialDims) -> &mut Kernel
Sets the default global work size.
sourcepub fn set_default_local_work_size(&mut self, lws: SpatialDims) -> &mut Kernel
pub fn set_default_local_work_size(&mut self, lws: SpatialDims) -> &mut Kernel
Sets the default local work size.
sourcepub fn default_queue(&self) -> Option<&Queue>
pub fn default_queue(&self) -> Option<&Queue>
Returns the default queue for this kernel if one has been set.
sourcepub fn default_global_work_offset(&self) -> SpatialDims
pub fn default_global_work_offset(&self) -> SpatialDims
Returns the default global work offset.
sourcepub fn default_global_work_size(&self) -> SpatialDims
pub fn default_global_work_size(&self) -> SpatialDims
Returns the default global work size.
sourcepub fn default_local_work_size(&self) -> SpatialDims
pub fn default_local_work_size(&self) -> SpatialDims
Returns the default local work size.
sourcepub fn as_core(&self) -> &KernelCore
pub fn as_core(&self) -> &KernelCore
Returns a reference to the core pointer wrapper, usable by functions in
the core
module.
sourcepub fn info(&self, info_kind: KernelInfo) -> OclResult<KernelInfoResult>
pub fn info(&self, info_kind: KernelInfo) -> OclResult<KernelInfoResult>
Returns information about this kernel.
sourcepub fn wg_info(
&self,
device: Device,
info_kind: KernelWorkGroupInfo
) -> OclResult<KernelWorkGroupInfoResult>
pub fn wg_info( &self, device: Device, info_kind: KernelWorkGroupInfo ) -> OclResult<KernelWorkGroupInfoResult>
Returns work group information for this kernel.
sourcepub fn arg_info(
&self,
arg_idx: u32,
info_kind: KernelArgInfo
) -> OclResult<KernelArgInfoResult>
pub fn arg_info( &self, arg_idx: u32, info_kind: KernelArgInfo ) -> OclResult<KernelArgInfoResult>
Returns argument information for this kernel.
Methods from Deref<Target = KernelCore>§
sourcepub fn program(&self) -> Result<Program, Error>
pub fn program(&self) -> Result<Program, Error>
Returns the program associated with this kernel.