GoclEvent

GoclEvent — Object that represents the future completion of an asynchronous operation

Stability Level

Unstable, unless otherwise indicated

Functions

Properties

gpointer event Read / Write / Construct Only
GoclQueue * queue Read / Write / Construct Only

Object Hierarchy

    GObject
    ╰── GoclEvent

Description

A GoclEvent is created as the result of requesting an asynchronous operation on a GoclQueue (the command queue of a device). Examples of these operations are the execution of a kernel with gocl_kernel_run_in_device() and reading from / writing to GoclBuffer objects in a non-blocking fashion (not yet implemented).

A GoclEvent is used by applications to get a notification when the corresponding operation completes, by calling gocl_event_then().

GoclEvent's are also the building blocks of synchronization in OpenCL. The application developer will notice that most operations include a event_wait_list argument, which asks OpenCL to wait for the completion of all GoclEvent's in the list, before starting the operation in question. This pattern greatly simplifies the application logic and allows for complex algorithms to be splitted in smaller, synchronized routines.

A GoclEvent is always associated with a GoclQueue, which represents the command queue where the operation represented by the event was originally queued. The GoclQueue can be retrieved using gocl_event_get_queue().

Functions

GoclEventResolverFunc ()

void
(*GoclEventResolverFunc) (GoclEvent *self,
                          GError *error);

Prototype of the function that notifies the completion of an event. This function is not normally called directly by applications. The object that creates the event is responsible for stealing the resolver function with gocl_event_steal_resolver_func(), and then resolve the event with success or error by calling this method, when the related operation completes.

Parameters

self

The GoclEvent

 

error

A GError if an error ocurred, NULL otherwise

 

GoclEventCallback ()

void
(*GoclEventCallback) (GoclEvent *self,
                      GError *error,
                      gpointer user_data);

Prototype of the callback argument of gocl_event_then().

Parameters

self

The GoclEvent

 

error

A GError if an error ocurred, NULL otherwise

 

user_data

The arbitrary pointer passed in gocl_event_then(), or NULL

 

gocl_event_get_queue ()

GoclQueue *
gocl_event_get_queue (GoclEvent *self);

Retrieves the GoclQueue object where the operation that created this event was queued.

Parameters

self

The GoclEvent

 

Returns

The GoclQueue associated with the event.

[transfer none]


gocl_event_steal_resolver_func ()

GoclEventResolverFunc
gocl_event_steal_resolver_func (GoclEvent *self);

Steals the internal resolver function from this event and sets it to NULL, so that only the first caller is able to resolve this event. This is a rather low-level method that should not normally be called by applications.

This method is intended to secure the GoclEvent, to guarantee that the creator of the event has exclusive control over the triggering of the event.

[skip]

Parameters

self

The GoclEvent

 

Returns

The internal resolver function.

[transfer none]


gocl_event_then ()

void
gocl_event_then (GoclEvent *self,
                 GoclEventCallback callback,
                 gpointer user_data);

Requests for a notification when the operation represented by this event has finished. When this event triggers, callback will be called passing user_data as argument, if provided.

If the event already triggered when this method is called, the notification is immediately scheduled as an idle call.

Parameters

self

The GoclEvent

 

callback

A callback with a GoclEventCallback signature.

[scope async]

user_data

Arbitrary data to pass in callback , or NULL.

[allow-none]

gocl_event_set_event_wait_list ()

void
gocl_event_set_event_wait_list (GoclEvent *self,
                                GList *event_list);

Stores a copy of the given GList of GoclEvent's to take ownership over the list and guarantee that the events will remain alive until this event is destroyed.

This is a rather low-level method and should not normally be called by applications.

Parameters

self

The GoclEvent

 

event_list

List of GoclEvent events that this event should wait for, or NULL.

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

gocl_event_list_to_array ()

cl_event *
gocl_event_list_to_array (GList *event_list,
                          guint *len);

A convenient method to retrieve a GList of GoclEvent's as an array of cl_event's corresponding to the internal objects of each GoclEvent in the GList. This is a rather low-level method and should not normally be called by applications.

Parameters

event_list

A GList containing GoclEvent objects.

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

len

A pointer to a value to retrieve list length.

[out][allow-none]

Returns

An array of cl_event objects. Free with g_free().

[transfer container][array length=len]


gocl_event_idle_unref ()

void
gocl_event_idle_unref (GoclEvent *self);

Schedules an object de-reference in an idle call. This is a rather low-level method and should not normally be called by applications.

Parameters

self

The GoclEvent

 

Property Details

The “event” property

  “event”                    gpointer

The internal OpenCL cl_event object.

Owner: GoclEvent

Flags: Read / Write / Construct Only


The “queue” property

  “queue”                    GoclQueue *

The command queue associated with this event.

Owner: GoclEvent

Flags: Read / Write / Construct Only