GoclKernel

GoclKernel — Object that represents an OpenCL kernel

Stability Level

Unstable, unless otherwise indicated

Functions

Properties

char * name Read / Write / Construct Only
GoclProgram * program Read / Write / Construct Only

Object Hierarchy

    GObject
    ╰── GoclKernel

Description

A GoclKernel object represents a special type of functions in OpenCL programs, that allows for host code to set its arguments and invoke the function.

A GoclKernel is not created directly. Instead, it is obtained from a GoclProgram by calling gocl_program_get_kernel() method.

Before a kernel object can be executed, all its arguments must be set. Several methods are provided for this purpose, and depending on the type of the argument to set, one or other is used. gocl_kernel_set_argument(), gocl_kernel_set_argument_int32() and gocl_kernel_set_argument_buffer() are examples of such methods. More will be added soon.

Once all arguments are set, the kernel is ready to be executed on a device. For this, the gocl_kernel_run_in_device() is used for non-blocking execution, and gocl_kernel_run_in_device_sync() for a blocking version. Notice that these methods will use the device's default command queue. In the future, methods will be provided to run the kernel on arbitrary command queues as well.

Functions

gocl_kernel_set_argument ()

gboolean
gocl_kernel_set_argument (GoclKernel *self,
                          guint index,
                          gsize size,
                          const gpointer *buffer);

Sets the value of the kernel argument at index , as an arbitrary block of memory.

Parameters

self

The GoclKernel

 

index

The index of this argument in the kernel function

 

size

The size of buffer , in bytes

 

buffer

A pointer to an arbitrary block of memory

 

Returns

TRUE on success, FALSE on error


gocl_kernel_set_argument_int32 ()

gboolean
gocl_kernel_set_argument_int32 (GoclKernel *self,
                                guint index,
                                gsize num_elements,
                                gint32 *buffer);

Sets the value of the kernel argument at index , as an array of int32.

Parameters

self

The GoclKernel

 

index

The index of this argument in the kernel function

 

num_elements

The number of int32 elements in buffer

 

buffer

Array of int32 values.

[array length=num_elements][element-type guint32]

Returns

TRUE on success, FALSE on error


gocl_kernel_set_argument_float ()

gboolean
gocl_kernel_set_argument_float (GoclKernel *self,
                                guint index,
                                gsize num_elements,
                                gfloat *buffer);

Sets the value of the kernel argument at index , as an array of floats.

Parameters

self

The GoclKernel

 

index

The index of this argument in the kernel function

 

num_elements

The number of float elements in buffer

 

buffer

Array of float values.

[array length=num_elements][element-type gfloat]

Returns

TRUE on success, FALSE on error


gocl_kernel_set_argument_buffer ()

gboolean
gocl_kernel_set_argument_buffer (GoclKernel *self,
                                 guint index,
                                 GoclBuffer *buffer);

Sets the value of the kernel argument at index , as a buffer object.

Parameters

self

The GoclKernel

 

index

The index of this argument in the kernel function

 

buffer

A GoclBuffer

 

Returns

TRUE on success, FALSE on error


gocl_kernel_run_in_device_sync ()

gboolean
gocl_kernel_run_in_device_sync (GoclKernel *self,
                                GoclDevice *device,
                                GList *event_wait_list);

Runs the kernel on the specified device, blocking the program until the kernel execution finishes. For non-blocking version, gocl_kernel_run_in_device() is provided.

If event_wait_list is provided, the kernel execution will start only when all the events in the list have triggered.

Parameters

self

The GoclKernel

 

device

A GoclDevice to run the kernel on

 

event_wait_list

List of GoclEvent events to wait for, or NULL.

[element-type Gocl.Event][allow-none]

Returns

TRUE on success, FALSE on error


gocl_kernel_run_in_device ()

GoclEvent *
gocl_kernel_run_in_device (GoclKernel *self,
                           GoclDevice *device,
                           GList *event_wait_list);

Runs the kernel on the specified device, asynchronously. A GoclEvent is returned, and can be used to get notified when the execution finishes, or as wait event input to other operations on the device.

If event_wait_list is provided, the kernel execution will start only when all the events in the list have triggered.

Parameters

self

The GoclKernel

 

device

A GoclDevice to run the kernel on

 

event_wait_list

List of GoclEvent events to wait for, or NULL.

[element-type Gocl.Event][allow-none]

Returns

A GoclEvent to get notified when execution finishes.

[transfer none]


gocl_kernel_set_work_dimension ()

void
gocl_kernel_set_work_dimension (GoclKernel *self,
                                guint8 work_dim);

Sets the work dimension (1, 2, 3) to use when executing the kernel.

Parameters

self

The GoclKernel

 

work_dim

The work dimension

 

gocl_kernel_set_global_work_size ()

void
gocl_kernel_set_global_work_size (GoclKernel *self,
                                  gsize size1,
                                  gsize size2,
                                  gsize size3);

Sets the global work sizes to use when executing the kernel, corresponding to the first, second, and third dimensions, respectively. By default, the sizes are all zeros.

If the size1 value is zero, it means no global work size is specified and NULL will be used when enqueuing the kernel.

Parameters

self

The GoclKernel

 

size1

global work size for the first dimension

 

size2

global work size for the second dimension

 

size3

global work size for the third dimension

 

gocl_kernel_set_local_work_size ()

void
gocl_kernel_set_local_work_size (GoclKernel *self,
                                 gsize size1,
                                 gsize size2,
                                 gsize size3);

Sets the local work sizes to use when executing the kernel, corresponding to the first, second, and third dimensions, respectively. By default, the sizes are all zeros.

If the size1 value is zero, it means no local work size is specified and NULL will be used when enqueuing the kernel.

Parameters

self

The GoclKernel

 

size1

local work size for the first dimension

 

size2

local work size for the second dimension

 

size3

local work size for the third dimension

 

Property Details

The “name” property

  “name”                     char *

The name of the kernel function.

Owner: GoclKernel

Flags: Read / Write / Construct Only

Default value: NULL


The “program” property

  “program”                  GoclProgram *

The program owning this kernel.

Owner: GoclKernel

Flags: Read / Write / Construct Only