![]() |
![]() |
![]() |
GTask Reference Manual | ![]() |
---|---|---|---|---|
#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);
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.
typedef enum { G_TASK_WAITING, G_TASK_READY, G_TASK_EXECUTING, G_TASK_CALLBACKS, G_TASK_FINISHED, G_TASK_CANCELLED } GTaskState;
GValue* (*GTaskFunc) (GTask *task, gpointer user_data);
This delegate is used to perform the work for a particular task.
GValue* (*GTaskCallback) (GTask *task, const GValue *result, gpointer user_data);
This delegate is used to perform a single callback.
|
the executing GTask |
|
the current result of the task |
|
the user data provided to g_task_add_callback()
|
Returns : |
a GValue that is the new result for the task |
GValue* (*GTaskErrback) (GTask *task, const GError *error, gpointer user_data);
This delegate is used to perform a single errback.
|
the executing GTask |
|
the current error for task
|
|
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* 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.
|
A GTaskFunc to be executed during g_task_execute()
|
|
The user data for func
|
|
The destroy notification for func_data
|
Returns : |
A new instance of GTask. |
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.
gboolean g_task_get_async (GTask *self);
Whether or not this task is asynchronous.
|
A GTask |
Returns : |
TRUE if the task is asynchronous |
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()
.
|
A GTask |
|
if the task is asynchronous |
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()
.
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.
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.
|
A GTask |
gboolean g_task_has_error (GTask *self);
This method checks to see if there is currently an error for the task.
|
A GTask. |
Returns : |
TRUE if there is an 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.
void g_task_set_error (GTask *self, const GError *error);
Sets the current error for the task. error
is copied locally.
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.
const GValue* g_task_get_result (GTask *self);
Retrieves the current value for the task. The value should not be modified or freed.
|
A GTask |
Returns : |
The current 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.
|
A GTask |
|
GTaskState g_task_get_state (GTask *self);
Retrieves the current state of a task.
|
A GTask |
Returns : |
a GTaskState representing the current 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.
|
A GTask |
|
The new GTaskState for self
|
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.
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.
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.
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.
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.
|
A GTask |
|
A GTaskCallback |
|
A GTaskErrback |
|
user data for callback and errback
|
|
destroy notification for user_data
|
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.
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.
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.
"state"
property"state" GTaskState : Read / Write
The current task state.
Default value: G_TASK_READY
"state-changed"
signalvoid 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.
|
the object which received the signal |
|
the new GTaskState |
|
user data set when the signal handler was connected. |