GoclProgram

GoclProgram — Object that represents an OpenCL program

Stability Level

Unstable, unless otherwise indicated

Functions

Properties

GoclContext * context Read / Write / Construct Only

Object Hierarchy

    GObject
    ╰── GoclProgram

Description

A GoclProgram allows to transform OpenCL source code into kernel objects that can run on OpenCL runtimes.

A GoclProgram is created with gocl_program_new(), provinding a null-terminated array of strings, each one representing OpenCL source code. Alternative;y, gocl_program_new_from_file_sync() can be used for simple cases when source code is in a single file.

Currently, creating a program from pre-compiled, binary code is not supported, but will be in the future.

Once a program is created, it needs to be built before kernels can be created from it. To build a program asynchronously, gocl_program_build() and gocl_program_build_finish() methods are provided. For building synchronously, gocl_program_build_sync() is used.

Once a program is successfully built, kernels can be obtained from it using gocl_program_get_kernel() method.

Functions

gocl_program_new ()

GoclProgram *
gocl_program_new (GoclContext *context,
                  const gchar **sources,
                  guint num_sources);

Creates and returns a new GoclProgram. Upon error, NULL is returned.

Parameters

context

The GoclContext

 

sources

Array of source code null-terminated strings.

[array length=num_sources][type utf8]

num_sources

The number of elements in sources

 

Returns

A newly created GoclProgram.

[transfer full]


gocl_program_new_from_file_sync ()

GoclProgram *
gocl_program_new_from_file_sync (GoclContext *context,
                                 const gchar *filename);

Creates and returns a new GoclProgram. This is a convenient constructor for cases when there is only one file containing the source code. Upon error, NULL is returned.

Parameters

context

The GoclContext

 

filename

The source code file

 

Returns

A newly created GoclProgram, or NULL on error.

[transfer full]


gocl_program_get_context ()

GoclContext *
gocl_program_get_context (GoclProgram *self);

Obtain the GoclContext the program belongs to.

Parameters

self

The GoclProgram

 

Returns

A GoclContext. The returned object is owned by the program, do not free.

[transfer none]


gocl_program_get_kernel ()

GoclKernel *
gocl_program_get_kernel (GoclProgram *self,
                         const gchar *kernel_name);

Creates and retrieves a new GoclKernel object from a kernel function in the source code, specified by kernel_name string. Upon success, a new GoclKernel is returned, otherwise NULL is returned.

Parameters

self

The GoclProgram

 

kernel_name

A string representing the name of a kernel function

 

Returns

A newly created GoclKernel object.

[transfer full]


gocl_program_build_sync ()

gboolean
gocl_program_build_sync (GoclProgram *self,
                         const gchar *options);

Builds the program using the build options specified in options . This method is blocking. For an asynchronous version, gocl_program_build() is provided. On error, FALSE is returned.

A detailed description of the build options is available at Kronos documentation website: http://www.khronos.org/registry/cl/sdk/1.0/docs/man/xhtml/clBuildProgram.html

Parameters

self

The GoclProgram

 

options

A string specifying OpenCL program build options

 

Returns

TRUE on success or FALSE on error


gocl_program_build ()

void
gocl_program_build (GoclProgram *self,
                    const gchar *options,
                    GCancellable *cancellable,
                    GAsyncReadyCallback callback,
                    gpointer user_data);

Builds the program using the build options specified in options . This method is non-blocking. If callback is provided, it will be called when the operation completes, and gocl_program_build_finish() can be used within the callback to retrieve the result of the operation.

A GCancellable object can be passed in cancellable to allow cancelling the operation.

Parameters

self

The GoclProgram

 

options

A string specifying OpenCL program build options

 

cancellable

A GCancellable object, or NULL.

[allow-none]

callback

Callback to be called upon completion, or NULL.

[allow-none]

user_data

Arbitrary data to pass in callback , or NULL.

[allow-none]

gocl_program_build_finish ()

gboolean
gocl_program_build_finish (GoclProgram *self,
                           GAsyncResult *result,
                           GError **error);

Retrieves the result of a gocl_program_build() asynchronous operation. On error, FALSE is returned and error is filled accordingly.

Parameters

self

The GoclProgram

 

result

The GAsyncResult object from callback's arguments

 

error

A pointer to a GError, or NULL.

[out][allow-none]

Returns

TRUE on success, or FALSE on error

Property Details

The “context” property

  “context”                  GoclContext *

The OpenCL context.

Owner: GoclProgram

Flags: Read / Write / Construct Only