GoclEvent

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

Stability Level

Unstable, unless otherwise indicated

Synopsis

struct              GoclEvent;
void                (*GoclEventCallback)                (GoclEvent *self,
                                                         GError *error,
                                                         gpointer user_data);
struct              GoclEventClass;
void                (*GoclEventResolverFunc)            (GoclEvent *self,
                                                         GError *error);
cl_event            gocl_event_get_event                (GoclEvent *self);
GoclQueue *         gocl_event_get_queue                (GoclEvent *self);
void                gocl_event_idle_unref               (GoclEvent *self);
cl_event *          gocl_event_list_to_array            (GList *event_list,
                                                         gsize *len);
GoclEventResolverFunc gocl_event_steal_resolver_func    (GoclEvent *self);
void                gocl_event_then                     (GoclEvent *self,
                                                         GoclEventCallback callback,
                                                         gpointer user_data);

Object Hierarchy

  GObject
   +----GoclEvent

Properties

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

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().

Details

struct GoclEvent

struct GoclEvent;

GoclEventCallback ()

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

Prototype of the callback argument of gocl_event_then().

self :

 The GoclEvent

error :

 A GError if an error ocurred, NULL otherwise

user_data :

 The arbitrary pointer passed in gocl_event_then(), or NULL

struct GoclEventClass

struct GoclEventClass {
  GObjectClass parent_class;
};

The class for GoclEvent objects.

GObjectClass parent_class;

 The parent class

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.

self :

 The GoclEvent

error :

 A GError if an error ocurred, NULL otherwise

gocl_event_get_event ()

cl_event            gocl_event_get_event                (GoclEvent *self);

Retrieves the OpenCL internal cl_event object. This is a rather low-level method that should not normally be called by applications.

self :

 The GoclEvent

Returns :

 The internal cl_event object. [transfer none][type guint64]

gocl_event_get_queue ()

GoclQueue *         gocl_event_get_queue                (GoclEvent *self);

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

self :

 The GoclEvent

Returns :

 The GoclQueue associated with the event. [transfer none]

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.

self :

 The GoclEvent

gocl_event_list_to_array ()

cl_event *          gocl_event_list_to_array            (GList *event_list,
                                                         gsize *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.

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_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.

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.

self :

 The GoclEvent

callback :

 A callback with a GoclEventCallback signature. [scope async]

user_data :

 Arbitrary data to pass in callback, or NULL. [allow-none]

Property Details

The "event" property

  "event"                    gpointer              : Read / Write / Construct Only

The internal OpenCL cl_event object.

The "queue" property

  "queue"                    GoclQueue*            : Read / Write / Construct Only

The command queue associated with this event.

Generated by GTK-Doc V1.18