GTask

GTask — Asynchronous and callback-based execution

Synopsis

#define             G_TYPE_TASK_STATE
enum                GTaskState;
GValue*             (*GTaskFunc)                        (GTask *task,
                                                         gpointer user_data);
GValue*             (*GTaskCallback)                    (GTask *task,
                                                         const GValue *result,
                                                         gpointer user_data);
GValue*             (*GTaskErrback)                     (GTask *task,
                                                         const GError *error,
                                                         gpointer user_data);
                    GTask;
GType               g_task_get_type                     (void);
GTask*              g_task_new                          (GTaskFunc func,
                                                         gpointer func_data,
                                                         GDestroyNotify notify);
GTask*              g_task_new_from_closure             (GClosure *closure);
gboolean            g_task_get_async                    (GTask *self);
void                g_task_set_async                    (GTask *self,
                                                         gboolean is_async);
GTask*              g_task_execute                      (GTask *self);
GTask*              g_task_callback                     (GTask *self);
void                g_task_cancel                       (GTask *self);
gboolean            g_task_has_error                    (GTask *self);
const GError*       g_task_get_error                    (GTask *self);
void                g_task_set_error                    (GTask *self,
                                                         const GError *error);
void                g_task_take_error                   (GTask *self,
                                                         GError *error);
const GValue*       g_task_get_result                   (GTask *self);
void                g_task_set_result                   (GTask *self,
                                                         const GValue *result);
GTaskState          g_task_get_state                    (GTask *self);
void                g_task_set_state                    (GTask *self,
                                                         GTaskState state);
void                g_task_add_dependency               (GTask *self,
                                                         GTask *dependency);
void                g_task_remove_dependency            (GTask *self,
                                                         GTask *dependency);
void                g_task_add_callback                 (GTask *self,
                                                         GTaskCallback callback,
                                                         gpointer user_data,
                                                         GDestroyNotify notify);
void                g_task_add_errback                  (GTask *self,
                                                         GTaskErrback errback,
                                                         gpointer user_data,
                                                         GDestroyNotify notify);
void                g_task_add_both                     (GTask *self,
                                                         GTaskCallback callback,
                                                         GTaskErrback errback,
                                                         gpointer user_data,
                                                         GDestroyNotify notify);
void                g_task_add_callback_closure         (GTask *self,
                                                         GClosure *closure);
void                g_task_add_errback_closure          (GTask *self,
                                                         GClosure *closure);
void                g_task_add_both_closure             (GTask *self,
                                                         GClosure *callback,
                                                         GClosure *errback);

Object Hierarchy

  GObject
   +----GTask

Properties

  "state"                    GTaskState            : Read / Write

Signals

  "state-changed"                                  : Run First

Description

GTask is a GObject sublcass that encapsulates a work item. Tasks remove the concept of a standard stack, but more on that in a minute.

The power of GTask comes from the callback and errback handling strategy. You can, ahead of time, create complex callback chains for handling normal and extraordinary flow within your application.

Callbacks are run sequentially after task execution has completed. You may also have errbacks, which are like a callback but used to handle an error in task execution or previous callback.

If a callback creates an error, no more callbacks will be executed until we reach another errback.

This documentation sucks, I know it. I'll come back later and improve it. Read the section on twisted deferreds for now.

Details

G_TYPE_TASK_STATE

#define G_TYPE_TASK_STATE (g_task_state_get_type ())


enum GTaskState

typedef enum
{
	G_TASK_WAITING,
	G_TASK_READY,
	G_TASK_EXECUTING,
	G_TASK_CALLBACKS,
	G_TASK_FINISHED,
	G_TASK_CANCELLED
} GTaskState;


GTaskFunc ()

GValue*             (*GTaskFunc)                        (GTask *task,
                                                         gpointer user_data);

This delegate is used to perform the work for a particular task.

task :

the executing GTask

user_data :

the user data provided to g_task_new

Returns :

a GValue containing the result for the task

GTaskCallback ()

GValue*             (*GTaskCallback)                    (GTask *task,
                                                         const GValue *result,
                                                         gpointer user_data);

This delegate is used to perform a single callback.

task :

the executing GTask

result :

the current result of the task

user_data :

the user data provided to g_task_add_callback()

Returns :

a GValue that is the new result for the task

GTaskErrback ()

GValue*             (*GTaskErrback)                     (GTask *task,
                                                         const GError *error,
                                                         gpointer user_data);

This delegate is used to perform a single errback.

task :

the executing GTask

error :

the current error for task

user_data :

the user data provided to g_task_add_errback()

Returns :

a new GValue for the result or NULL if a new error was set or the existing error is still valid.

GTask

typedef struct _GTask GTask;


g_task_get_type ()

GType               g_task_get_type                     (void);

Returns :


g_task_new ()

GTask*              g_task_new                          (GTaskFunc func,
                                                         gpointer func_data,
                                                         GDestroyNotify notify);

Creates a new instance of GTask and sets the GTaskFunc to use when g_task_execute() is called. func will be called from a thread.

func :

A GTaskFunc to be executed during g_task_execute()

func_data :

The user data for func

notify :

The destroy notification for func_data

Returns :

A new instance of GTask.

g_task_new_from_closure ()

GTask*              g_task_new_from_closure             (GClosure *closure);

Creates a new instance of GTask and sets up the task to invoke closure when the task is executed. The closure will be called from a thread.

closure :

A GClosure

Returns :

A new instance of GTask.

g_task_get_async ()

gboolean            g_task_get_async                    (GTask *self);

Whether or not this task is asynchronous.

self :

A GTask

Returns :

TRUE if the task is asynchronous

g_task_set_async ()

void                g_task_set_async                    (GTask *self,
                                                         gboolean is_async);

Asynchronous tasks are tasks whose execution closure will return immediately but not be finished processing until later.

Note that asynchronous tasks need to update their state to G_TASK_FINISHED using g_task_set_state().

self :

A GTask

is_async :

if the task is asynchronous

g_task_execute ()

GTask*              g_task_execute                      (GTask *self);

Synchronously performs the task's worker delegate. Tasks that have more work to complete will return a new GTask. If they have completed then NULL is returned.

Scheduler implementors are highly encouraged to immediately execute the potentially returned task to reduce scheduling overhead.

It is also the GTaskSchedulers responsibility to invoke the callback chain after execution via g_task_callback().

self :

A GTask

Returns :

a new GTask to perform if additional work is required or NULL.

g_task_callback ()

GTask*              g_task_callback                     (GTask *self);

Works towards completing the execution of the callback chain. If the task contains an error, we will try to resolve the error by jumping to the next errback handler.

If a callback or errback return a new GTask to execute, the callback chain will pause and wait for this new task to be completed.

When the resulted task has been completed, the scheduler implementation should recall this method to work towards finishing the execution of the callbacks.

self :

A GTask

Returns :

A new GTask or NULL if the callback chain has completed.

g_task_cancel ()

void                g_task_cancel                       (GTask *self);

Cancels a task. If the task has not started, it will not be executed and tasks depending on it will be notified. If the task is being executed, it is up to the executing worker delegate to check for the cancellation request and terminate execution.

Callbacks and errbacks may still perform if they handle the error that will be created for the task.

self :

A GTask

g_task_has_error ()

gboolean            g_task_has_error                    (GTask *self);

This method checks to see if there is currently an error for the task.

self :

A GTask.

Returns :

TRUE if there is an error

g_task_get_error ()

const GError*       g_task_get_error                    (GTask *self);

This method will retrieve the current error for the task. It should not be modified directly.

self :

A GTask.

Returns :

A GError that should not be modified.

g_task_set_error ()

void                g_task_set_error                    (GTask *self,
                                                         const GError *error);

Sets the current error for the task. error is copied locally.

self :

A GTask

error :

a GError

g_task_take_error ()

void                g_task_take_error                   (GTask *self,
                                                         GError *error);

Like g_task_set_error() but the error is used directly and steals ownership of the error.

self :

A GTask

error :

A GError

g_task_get_result ()

const GValue*       g_task_get_result                   (GTask *self);

Retrieves the current value for the task. The value should not be modified or freed.

self :

A GTask

Returns :

The current result.

g_task_set_result ()

void                g_task_set_result                   (GTask *self,
                                                         const GValue *result);

Sets the current result for the task. The value is copied and stored to be passed as a parameter to the next callback.

self :

A GTask

result :


g_task_get_state ()

GTaskState          g_task_get_state                    (GTask *self);

Retrieves the current state of a task.

self :

A GTask

Returns :

a GTaskState representing the current state.

g_task_set_state ()

void                g_task_set_state                    (GTask *self,
                                                         GTaskState state);

Updates the current state of a GTask. Changing the state will emit the state-changed signal.

self :

A GTask

state :

The new GTaskState for self

g_task_add_dependency ()

void                g_task_add_dependency               (GTask *self,
                                                         GTask *dependency);

Adds a GTask to the list of tasks that must be completed before this task may execute.

self :

A GTask

dependency :

A GTask which must complete before execution

g_task_remove_dependency ()

void                g_task_remove_dependency            (GTask *self,
                                                         GTask *dependency);

Removes a currently dependent task. If all dependencies have been met, the tasks state will move to G_TASK_READY.

If the task has a scheduler associated with it (priv->scheduler) then the task will be re-scheduled for execution on that scheduler.

self :

A GTask

dependency :

A GTask that is currently a dependency of self

g_task_add_callback ()

void                g_task_add_callback                 (GTask *self,
                                                         GTaskCallback callback,
                                                         gpointer user_data,
                                                         GDestroyNotify notify);

Adds a callback handler to the processing chain. This is executed in turn during the callback phase. If the callback generates an error, the first error handler left in the chain will run. If the callback does not generate an error, further callbacks may be called.

self :

A GTask

callback :

A GTaskFunc

user_data :

user data for callback

notify :

destroy notification for user_data

g_task_add_errback ()

void                g_task_add_errback                  (GTask *self,
                                                         GTaskErrback errback,
                                                         gpointer user_data,
                                                         GDestroyNotify notify);

Adds an errback handler to the processing chain. This is executed in turn during the callbacks phase. If the errback unsets the error, then callbacks added after the errback may continue to process. If the errback does not unset the error, further errback handlers may be processed.

To unset an error during an errback, use g_task_set_error() with a NULL error.

self :

A GTask

errback :

A GTaskFunc

user_data :

user data for errback

notify :

destroy notification for user_data

g_task_add_both ()

void                g_task_add_both                     (GTask *self,
                                                         GTaskCallback callback,
                                                         GTaskErrback errback,
                                                         gpointer user_data,
                                                         GDestroyNotify notify);

Adds both an errback and a callback to a handler in the callbacks phase. This means that one of these methods is garunteed to be executed during the callbacks phase. When the handler is reached, if the task currently has an error, errback will be called, otherwise, callback will be called.

self :

A GTask

callback :

A GTaskCallback

errback :

A GTaskErrback

user_data :

user data for callback and errback

notify :

destroy notification for user_data

g_task_add_callback_closure ()

void                g_task_add_callback_closure         (GTask *self,
                                                         GClosure *closure);

This method is similar to g_task_add_callback() except it allows the use of a closure. Binding authors should use this method to allow for greater control and flexibility.

self :

A GTask

closure :

A GClosure to execute

g_task_add_errback_closure ()

void                g_task_add_errback_closure          (GTask *self,
                                                         GClosure *closure);

This method is similar to g_task_add_errback() except it allows the use of a closure. Binding authors should be using this method to allow for greater control and flexibility.

self :

A GTask

closure :

A GClosure

g_task_add_both_closure ()

void                g_task_add_both_closure             (GTask *self,
                                                         GClosure *callback,
                                                         GClosure *errback);

This method is identical to g_task_add_both() except it allows the use of closures directly.

Use this for simple branching control of exceptions.

self :

A GTask

callback :

a GClosure for the GTaskCallback.

errback :

a GClosure for the GTaskErrback.

Property Details

The "state" property

  "state"                    GTaskState            : Read / Write

The current task state.

Default value: G_TASK_READY

Signal Details

The "state-changed" signal

void                user_function                      (GTask   *task,
                                                        gint     state,
                                                        gpointer user_data)      : Run First

The state-changed signal is emitted when a task moves into a new state. This is particularly useful if you want to alter the state of dependent tasks when this task changes state.

task :

the object which received the signal

state :

the new GTaskState

user_data :

user data set when the signal handler was connected.