Optionalproperties: Partial<Gio.Task.ConstructorProps>Internal$signalsCompile-time signal type information.
This instance property is generated only for TypeScript type checking. It is not defined at runtime and should not be accessed in JS code.
Static$gtypeRead-OnlySince 2.44completedWhether the task has completed, meaning its callback (if set) has been invoked.
This can only happen after g_task_return_pointer(),
g_task_return_error() or one of the other return functions have been called
on the task. However, it is not guaranteed to happen immediately after
those functions are called, as the task’s callback may need to be scheduled
to run in a different thread.
That means it is not safe to use this property to track whether a return function has been called on the Gio.Task. Callers must do that tracking themselves, typically by linking the lifetime of the Gio.Task to the control flow of their code.
This property is guaranteed to change from false to true exactly once.
The GObject.Object::notify signal for this change is emitted in the same main context as the task’s callback, immediately after that callback is invoked.
Creates a binding between source_property on source and target_property
on target.
Whenever the source_property is changed the target_property is
updated using the same value. For instance:
g_object_bind_property (action, "active", widget, "sensitive", 0);
Will result in the "sensitive" property of the widget GObject.Object instance to be updated with the same value of the "active" property of the action GObject.Object instance.
If flags contains GObject.BindingFlags.BIDIRECTIONAL then the binding will be mutual:
if target_property on target changes then the source_property on source
will be updated as well.
The binding will automatically be removed when either the source or the
target instances are finalized. To remove the binding without affecting the
source and the target you can just call g_object_unref() on the returned
GObject.Binding instance.
Removing the binding by calling g_object_unref() on it must only be done if
the binding, source and target are only used from a single thread and it
is clear that both source and target outlive the binding. Especially it
is not safe to rely on this if the binding, source or target can be
finalized from different threads. Keep another reference to the binding and
use g_binding_unbind() instead to be on the safe side.
A GObject.Object can have multiple bindings.
the property on source to bind
the target GObject.Object
the property on target to bind
flags to pass to GObject.Binding
the GObject.Binding instance representing the binding between the two GObject.Object instances. The binding is released whenever the GObject.Binding reference count reaches zero.
Complete version of g_object_bind_property().
Creates a binding between source_property on source and target_property
on target, allowing you to set the transformation functions to be used by
the binding.
If flags contains GObject.BindingFlags.BIDIRECTIONAL then the binding will be mutual:
if target_property on target changes then the source_property on source
will be updated as well. The transform_from function is only used in case
of bidirectional bindings, otherwise it will be ignored
The binding will automatically be removed when either the source or the
target instances are finalized. This will release the reference that is
being held on the GObject.Binding instance; if you want to hold on to the
GObject.Binding instance, you will need to hold a reference to it.
To remove the binding, call g_binding_unbind().
A GObject.Object can have multiple bindings.
The same user_data parameter will be used for both transform_to
and transform_from transformation functions; the notify function will
be called once, when the binding is removed. If you need different data
for each transformation function, please use
g_object_bind_property_with_closures() instead.
the property on source to bind
the target GObject.Object
the property on target to bind
flags to pass to GObject.Binding
Optionaltransform_to: BindingTransformFuncthe transformation function from the source to the target, or null to use the default
Optionaltransform_from: BindingTransformFuncthe transformation function from the target to the source, or null to use the default
Optionalnotify: DestroyNotifya function to call when disposing the binding, to free resources used by the transformation functions, or null if not required
the GObject.Binding instance representing the binding between the two GObject.Object instances. The binding is released whenever the GObject.Binding reference count reaches zero.
Creates a binding between source_property on source and target_property
on target, allowing you to set the transformation functions to be used by
the binding.
This function is the language bindings friendly version of
g_object_bind_property_full(), using GClosures instead of
function pointers.
the property on source to bind
the GObject.Binding instance representing the binding between the two GObject.Object instances. The binding is released whenever the GObject.Binding reference count reaches zero.
Blocks a handler of an instance so it will not be called during any signal emissions
Handler ID of the handler to be blocked
SignalconnectSignalconnect_Disconnects a handler from an instance so it will not be called during any future or currently ongoing emissions of the signal it has been connected to.
Handler ID of the handler to be disconnected
SignalemitThis function is intended for GObject.Object implementations to re-enforce
a [floating][floating-ref] object reference. Doing this is seldom
required: all GInitiallyUnowneds are created with a floating reference
which usually just needs to be sunken by calling g_object_ref_sink().
Increases the freeze count on object. If the freeze count is
non-zero, the emission of "notify" signals on object is
stopped. The signals are queued until the freeze count is decreased
to zero. Duplicate notifications are squashed so that at most one
GObject.Object::notify signal is emitted for each property modified while the
object is frozen.
This is necessary for accessors that modify multiple properties to prevent premature notification while the object is still being modified.
Gets task's check-cancellable flag. See
g_task_set_check_cancellable() for more details.
Gets the value of Gio.Task.completed. This changes from false to true after
the task’s callback is invoked, and will return false if called from inside
the callback.
true if the task has completed, false otherwise.
Gets the GLib.MainContext that task will return its result in (that
is, the context that was the thread-default main context
(see GLib.MainContext.push_thread_default)
at the point when task was created).
This will always return a non-null value, even if the task's
context is the default GLib.MainContext.
task's GLib.MainContext
Gets a named field from the objects table of associations (see g_object_set_data()).
name of the key for that association
the data if found, or null if no such data exists.
Gets task’s name. See g_task_set_name().
task’s name, or null
Gets task's priority
task's priority
Gets a property of an object.
The value can be:
In general, a copy is made of the property contents and the caller is responsible for freeing the memory by calling GObject.Value.unset.
Note that GObject.Object.get_property is really intended for language bindings, GObject.Object.get is much more convenient for C programming.
The name of the property to get
Return location for the property value. Can be an empty GObject.Value initialized by G_VALUE_INIT (auto-initialized with expected type since GLib 2.60), a GObject.Value initialized with the expected property type, or a GObject.Value initialized with a transformable type
This function gets back user data pointers stored via
g_object_set_qdata().
A GLib.Quark, naming the user data pointer
The user data pointer set, or null
Gets task's return-on-cancel flag. See
g_task_set_return_on_cancel() for more details.
Gets task's source tag. See g_task_set_source_tag().
task's source tag
Gets task's task_data.
task's task_data.
Gets n_properties properties for an object.
Obtained properties will be set to values. All properties must be valid.
Warnings will be emitted and undefined behaviour may result if invalid
properties are passed in.
the names of each property to get
the values of each property to get
Tests if task resulted in an error.
true if the task resulted in an error, false otherwise.
Checks whether object has a [floating][floating-ref] reference.
true if object has a floating reference
Checks if res has the given source_tag (generally a function
pointer indicating the function res was created by).
Optionalsource_tag: anyan application-defined tag
TRUE if res has the indicated source_tag, FALSE if not.
If res is a Gio.SimpleAsyncResult, this is equivalent to
Gio.SimpleAsyncResult.propagate_error. Otherwise it returns
FALSE.
This can be used for legacy error handling in async *_finish()
wrapper functions that traditionally handled Gio.SimpleAsyncResult
error returns themselves rather than calling into the virtual method.
This should not be used in new code; Gio.AsyncResult errors that are
set by virtual methods should also be extracted by virtual methods,
to enable subclasses to chain up correctly.
TRUE if error is has been filled in with an error from res, FALSE if not.
Emits a "notify" signal for the property property_name on object.
When possible, eg. when signaling a property change from within the class
that registered the property, you should use g_object_notify_by_pspec()
instead.
Note that emission of the notify signal may be blocked with
g_object_freeze_notify(). In this case, the signal emissions are queued
and will be emitted (in reverse order) when g_object_thaw_notify() is
called.
the name of a property installed on the class of object.
Emits a "notify" signal for the property specified by pspec on object.
This function omits the property name lookup, hence it is faster than
g_object_notify().
One way to avoid using g_object_notify() from within the
class that registered the properties, and using g_object_notify_by_pspec()
instead, is to store the GParamSpec used with
g_object_class_install_property() inside a static array, e.g.:
typedef enum
{
PROP_FOO = 1,
PROP_LAST
} MyObjectProperty;
static GParamSpec *properties[PROP_LAST];
static void
my_object_class_init (MyObjectClass *klass)
{
properties[PROP_FOO] = g_param_spec_int ("foo", NULL, NULL,
0, 100,
50,
G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
g_object_class_install_property (gobject_class,
PROP_FOO,
properties[PROP_FOO]);
}
and then notify a change on the "foo" property with:
g_object_notify_by_pspec (self, properties[PROP_FOO]);
the GObject.ParamSpec of a property installed on the class of object.
Gets the result of task as a gboolean.
If the task resulted in an error, or was cancelled, then this will
instead return false and set error.
Since this method transfers ownership of the return value (or error) to the caller, you may only call it once.
the task result, or false on error
Gets the result of task as an integer (gssize).
If the task resulted in an error, or was cancelled, then this will
instead return -1 and set error.
Since this method transfers ownership of the return value (or error) to the caller, you may only call it once.
the task result, or -1 on error
Gets the result of task as a pointer, and transfers ownership
of that value to the caller.
If the task resulted in an error, or was cancelled, then this will
instead return null and set error.
Since this method transfers ownership of the return value (or error) to the caller, you may only call it once.
the task result, or null on error
Gets the result of task as a GObject.Value, and transfers ownership of
that value to the caller. As with g_task_return_value(), this is
a generic low-level method; g_task_propagate_pointer() and the like
will usually be more useful for C code.
If the task resulted in an error, or was cancelled, then this will
instead set error and return false.
Since this method transfers ownership of the return value (or error) to the caller, you may only call it once.
true if task succeeded, false on error.
Increases the reference count of object.
Since GLib 2.56, if GLIB_VERSION_MAX_ALLOWED is 2.56 or greater, the type
of object will be propagated to the return type (using the GCC typeof()
extension), so any casting the caller needs to do on the return type must be
explicit.
the same object
Increase the reference count of object, and possibly remove the
[floating][floating-ref] reference, if object has a floating reference.
In other words, if the object is floating, then this call "assumes ownership" of the floating reference, converting it to a normal reference by clearing the floating flag while leaving the reference count unchanged. If the object is not floating, then this call adds a new normal reference increasing the reference count by one.
Since GLib 2.56, the type of object will be propagated to the return type
under the same conditions as for g_object_ref().
object
Sets task's result to result and completes the task (see
g_task_return_pointer() for more discussion of exactly what this
means).
the gboolean result of a task function.
Sets task's result to error (which task assumes ownership of)
and completes the task (see g_task_return_pointer() for more
discussion of exactly what this means).
Note that since the task takes ownership of error, and since the
task may be completed before returning from g_task_return_error(),
you cannot assume that error is still valid after calling this.
Call g_error_copy() on the error if you need to keep a local copy
as well.
See also Gio.Task.return_new_error, Gio.Task.return_new_error_literal.
the GLib.Error result of a task function.
Checks if task's Gio.Cancellable has been cancelled, and if so, sets
task's error accordingly and completes the task (see
g_task_return_pointer() for more discussion of exactly what this
means).
true if task has been cancelled, false if not
Sets task's result to result and completes the task (see
g_task_return_pointer() for more discussion of exactly what this
means).
the integer (gssize) result of a task function.
Sets task’s result to a new GLib.Error created from domain, code,
message and completes the task.
See Gio.Task.return_pointer for more discussion of exactly what ‘completing the task’ means.
See also Gio.Task.return_new_error.
a GLib.Quark.
an error code.
an error message
Sets task's result to result and completes the task. If result
is not null, then result_destroy will be used to free result if
the caller does not take ownership of it with
g_task_propagate_pointer().
"Completes the task" means that for an ordinary asynchronous task
it will either invoke the task's callback, or else queue that
callback to be invoked in the proper GLib.MainContext, or in the next
iteration of the current GLib.MainContext. For a task run via
g_task_run_in_thread() or g_task_run_in_thread_sync(), calling this
method will save result to be returned to the caller later, but
the task will not actually be completed until the Gio.TaskThreadFunc
exits.
Note that since the task may be completed before returning from
g_task_return_pointer(), you cannot assume that result is still
valid after calling this, unless you are still holding another
reference on it.
Optionalresult: anythe pointer result of a task function
Optionalresult_destroy: DestroyNotifya GLib.DestroyNotify function.
Sets task's result to result (by copying it) and completes the task.
If result is null then a GObject.Value of type G_TYPE_POINTER
with a value of null will be used for the result.
This is a very generic low-level method intended primarily for use
by language bindings; for C code, g_task_return_pointer() and the
like will normally be much easier to use.
Optionalresult: GObject.Valuethe GObject.Value result of a task function
Releases all references to other objects. This can be used to break reference cycles.
This function should only be called from object system implementations.
Runs task_func in another thread. When task_func returns, task's
Gio.AsyncReadyCallback will be invoked in task's GLib.MainContext.
This takes a ref on task until the task completes.
See Gio.TaskThreadFunc for more details about how task_func is handled.
Although GLib currently rate-limits the tasks queued via
g_task_run_in_thread(), you should not assume that it will always
do this. If you have a very large number of tasks to run (several tens of
tasks), but don't want them to all run at once, you should only queue a
limited number of them (around ten) at a time.
Be aware that if your task depends on other tasks to complete, use of this
function could lead to a livelock if the other tasks also use this function
and enough of them (around 10) execute in a dependency chain, as that will
exhaust the thread pool. If this situation is possible, consider using a
separate worker thread or thread pool explicitly, rather than using
g_task_run_in_thread().
Runs task_func in another thread, and waits for it to return or be
cancelled. You can use g_task_propagate_pointer(), etc, afterward
to get the result of task_func.
See Gio.TaskThreadFunc for more details about how task_func is handled.
Normally this is used with tasks created with a null
callback, but note that even if the task does
have a callback, it will not be invoked when task_func returns.
Gio.Task.completed will be set to true just before this function returns.
Although GLib currently rate-limits the tasks queued via
g_task_run_in_thread_sync(), you should not assume that it will
always do this. If you have a very large number of tasks to run,
but don't want them to all run at once, you should only queue a
limited number of them at a time.
Sets multiple properties of an object at once. The properties argument should be a dictionary mapping property names to values.
Object containing the properties to set
Sets or clears task's check-cancellable flag. If this is true
(the default), then g_task_propagate_pointer(), etc, and
g_task_had_error() will check the task's Gio.Cancellable first, and
if it has been cancelled, then they will consider the task to have
returned an "Operation was cancelled" error
(Gio.IOErrorEnum.CANCELLED), regardless of any other error or return
value the task may have had.
If check_cancellable is false, then the Gio.Task will not check the
cancellable itself, and it is up to task's owner to do this (eg,
via g_task_return_error_if_cancelled()).
If you are using g_task_set_return_on_cancel() as well, then
you must leave check-cancellable set true.
whether Gio.Task will check the state of its Gio.Cancellable for you.
Each object carries around a table of associations from strings to pointers. This function lets you set an association.
If the object already had an association with that name, the old association will be destroyed.
Internally, the key is converted to a GLib.Quark using g_quark_from_string().
This means a copy of key is kept permanently (even after object has been
finalized) — so it is recommended to only use a small, bounded set of values
for key in your program, to avoid the GLib.Quark storage growing unbounded.
name of the key
Optionaldata: anydata to associate with that key
Sets task’s name, used in debugging and profiling. The name defaults to
null.
The task name should describe in a human readable way what the task does. For example, ‘Open file’ or ‘Connect to network host’. It is used to set the name of the GLib.Source used for idle completion of the task.
This function may only be called before the task is first used in a thread
other than the one it was constructed in.
Optionalname: stringa human readable name for the task, or null to unset it
Sets task's priority. If you do not call this, it will default to
G_PRIORITY_DEFAULT.
This will affect the priority of GSources created with
g_task_attach_source() and the scheduling of tasks run in threads,
and can also be explicitly retrieved later via
g_task_get_priority().
the priority of the request
Sets a property on an object.
The name of the property to set
The value to set the property to
Sets or clears task's return-on-cancel flag. This is only
meaningful for tasks run via g_task_run_in_thread() or
g_task_run_in_thread_sync().
If return_on_cancel is true, then cancelling task's
Gio.Cancellable will immediately cause it to return, as though the
task's Gio.TaskThreadFunc had called
g_task_return_error_if_cancelled() and then returned.
This allows you to create a cancellable wrapper around an
uninterruptible function. The Gio.TaskThreadFunc just needs to be
careful that it does not modify any externally-visible state after
it has been cancelled. To do that, the thread should call
g_task_set_return_on_cancel() again to (atomically) set
return-on-cancel false before making externally-visible changes;
if the task gets cancelled before the return-on-cancel flag could
be changed, g_task_set_return_on_cancel() will indicate this by
returning false.
You can disable and re-enable this flag multiple times if you wish.
If the task's Gio.Cancellable is cancelled while return-on-cancel is
false, then calling g_task_set_return_on_cancel() to set it true
again will cause the task to be cancelled at that point.
If the task's Gio.Cancellable is already cancelled before you call
g_task_run_in_thread()/g_task_run_in_thread_sync(), then the
Gio.TaskThreadFunc will still be run (for consistency), but the task
will also be completed right away.
whether the task returns automatically when it is cancelled.
true if task's return-on-cancel flag was changed to match return_on_cancel. false if task has already been cancelled.
Sets task's source tag.
You can use this to tag a task return
value with a particular pointer (usually a pointer to the function
doing the tagging) and then later check it using
g_task_get_source_tag() (or g_async_result_is_tagged()) in the
task's "finish" function, to figure out if the response came from a
particular place.
A macro wrapper around this function will automatically set the
task’s name to the string form of source_tag if it’s not already
set, for convenience.
Optionalsource_tag: anyan opaque pointer indicating the source of this task
Sets task’s name, used in debugging and profiling.
This is a variant of g_task_set_name() that avoids copying name.
This function is called automatically by Gio.Task.set_source_tag unless a name is set.
Optionalname: stringa human readable name for the task. Must be a string literal
Sets task's task data (freeing the existing task data, if any).
Optionaltask_data: anytask-specific data
Optionaltask_data_destroy: DestroyNotifyGLib.DestroyNotify for task_data
Remove a specified datum from the object's data associations, without invoking the association's destroy handler.
name of the key
the data if found, or null if no such data exists.
This function gets back user data pointers stored via
g_object_set_qdata() and removes the data from object
without invoking its destroy() function (if any was
set).
Usually, calling this function is only required to update
user data pointers with a destroy notifier, for example:
void
object_add_to_user_list (GObject *object,
const gchar *new_string)
{
// the quark, naming the object data
GQuark quark_string_list = g_quark_from_static_string ("my-string-list");
// retrieve the old string list
GList *list = g_object_steal_qdata (object, quark_string_list);
// prepend new string
list = g_list_prepend (list, g_strdup (new_string));
// this changed 'list', so we need to set it again
g_object_set_qdata_full (object, quark_string_list, list, free_string_list);
}
static void
free_string_list (gpointer data)
{
GList *node, *list = data;
for (node = list; node; node = node->next)
g_free (node->data);
g_list_free (list);
}
Using g_object_get_qdata() in the above example, instead of
g_object_steal_qdata() would have left the destroy function set,
and thus the partial string list would have been freed upon
g_object_set_qdata_full().
A GLib.Quark, naming the user data pointer
The user data pointer set, or null
Stops a signal's emission by the given signal name. This will prevent the default handler and any subsequent signal handlers from being invoked.
Name of the signal to stop emission of
Reverts the effect of a previous call to
g_object_freeze_notify(). The freeze count is decreased on object
and when it reaches zero, queued "notify" signals are emitted.
Duplicate notifications for each property are squashed so that at most one GObject.Object::notify signal is emitted for each property, in the reverse order in which they have been queued.
It is an error to call this function when the freeze count is zero.
Unblocks a handler so it will be called again during any signal emissions
Handler ID of the handler to be unblocked
Decreases the reference count of object. When its reference count
drops to 0, the object is finalized (i.e. its memory is freed).
If the pointer to the GObject.Object may be reused in future (for example, if it is
an instance variable of another object), it is recommended to clear the
pointer to null rather than retain a dangling pointer to a potentially
invalid GObject.Object instance. Use g_clear_object() for this.
Virtualvfunc_the constructed function is called by g_object_new() as the
final step of the object creation process. At the point of the call, all
construction properties have been set on the object. The purpose of this
call is to allow for object initialisation steps that can only be performed
after construction properties have been set. constructed implementors
should chain up to the constructed call of their parent class to allow it
to complete its initialisation.
Virtualvfunc_Virtualvfunc_the dispose function is supposed to drop all references to other
objects, but keep the instance otherwise intact, so that client method
invocations still work. It may be run multiple times (due to reference
loops). Before returning, dispose should chain up to the dispose method
of the parent class.
Virtualvfunc_instance finalization function, should finish the finalization of
the instance begun in dispose and chain up to the finalize method of the
parent class.
Virtualvfunc_Virtualvfunc_Virtualvfunc_Gets the user data from a Gio.AsyncResult.
Virtualvfunc_Checks if res has the given source_tag (generally a function
pointer indicating the function res was created by).
Optionalsource_tag: anyan application-defined tag
Virtualvfunc_Emits a "notify" signal for the property property_name on object.
When possible, eg. when signaling a property change from within the class
that registered the property, you should use g_object_notify_by_pspec()
instead.
Note that emission of the notify signal may be blocked with
g_object_freeze_notify(). In this case, the signal emissions are queued
and will be emitted (in reverse order) when g_object_thaw_notify() is
called.
Virtualvfunc_the generic setter for all properties of this type. Should be
overridden for every type with properties. If implementations of
set_property don't emit property change notification explicitly, this will
be done implicitly by the type system. However, if the notify signal is
emitted explicitly, the type system will not emit it a second time.
This function essentially limits the life time of the closure to
the life time of the object. That is, when the object is finalized,
the closure is invalidated by calling g_closure_invalidate() on
it, in order to prevent invocations of the closure with a finalized
(nonexisting) object. Also, g_object_ref() and g_object_unref() are
added as marshal guards to the closure, to ensure that an extra
reference count is held on object during invocation of the
closure. Usually, this function will be called on closures that
use this object as closure data.
GObject.Closure to watch
Staticis_Checks that result is a Gio.Task, and that source_object is its
source object (or that source_object is null and result has no
source object). This can be used in g_return_if_fail() checks.
Optionalsource_object: GObject.Objectthe source object expected to be associated with the task
StaticnewOptionalsource_object: GObject.ObjectOptionalcancellable: Gio.CancellableOptionalcallback: AsyncReadyCallback<GObject.Object>Staticreport_Creates a Gio.Task and then immediately calls g_task_return_error()
on it. Use this in the wrapper function of an asynchronous method
when you want to avoid even calling the virtual method. You can
then use g_async_result_is_tagged() in the finish method wrapper to
check if the result there is tagged as having been created by the
wrapper method, and deal with it appropriately if so.
See also g_task_report_new_error().
the GObject.Object that owns this task, or null.
an opaque pointer indicating the source of this task
error to report
Static_Staticcompat_Optionaldata: anyStaticfind_Staticinstall_Staticinstall_the id for the new property
the GObject.ParamSpec for the new property
Staticinterface_Find the GObject.ParamSpec with the given name for an
interface. Generally, the interface vtable passed in as g_iface
will be the default vtable from g_type_default_interface_ref(), or,
if you know the interface has already been loaded,
g_type_default_interface_peek().
any interface vtable for the interface, or the default vtable for the interface
name of a property to look up.
Staticinterface_Add a property to an interface; this is only useful for interfaces
that are added to GObject-derived types. Adding a property to an
interface forces all objects classes with that interface to have a
compatible property. The compatible property could be a newly
created GObject.ParamSpec, but normally
g_object_class_override_property() will be used so that the object
class only needs to provide an implementation and inherits the
property description, default value, bounds, and so forth from the
interface property.
This function is meant to be called from the interface's default
vtable initialization function (the class_init member of
GObject.TypeInfo.) It must not be called after after class_init has
been called for any object types implementing this interface.
If pspec is a floating reference, it will be consumed.
any interface vtable for the interface, or the default vtable for the interface.
the GObject.ParamSpec for the new property
Staticinterface_Lists the properties of an interface.Generally, the interface
vtable passed in as g_iface will be the default vtable from
g_type_default_interface_ref(), or, if you know the interface has
already been loaded, g_type_default_interface_peek().
any interface vtable for the interface, or the default vtable for the interface
Staticlist_StaticnewvStaticoverride_the new property ID
the name of a property registered in a parent class or in an interface of this class.
A Gio.Task represents and manages a cancellable ‘task’.
Asynchronous operations
The most common usage of Gio.Task is as a Gio.AsyncResult, to manage data during an asynchronous operation. You call Gio.Task.new in the ‘start’ method, followed by Gio.Task.set_task_data and the like if you need to keep some additional data associated with the task, and then pass the task object around through your asynchronous operation. Eventually, you will call a method such as Gio.Task.return_pointer or Gio.Task.return_error, which will save the value you give it and then invoke the task’s callback function in the thread-default main context (see GLib.MainContext.push_thread_default) where it was created (waiting until the next iteration of the main loop first, if necessary). The caller will pass the Gio.Task back to the operation’s finish function (as a Gio.AsyncResult), and you can use Gio.Task.propagate_pointer or the like to extract the return value.
Using Gio.Task requires the thread-default GLib.MainContext from when the Gio.Task was constructed to be running at least until the task has completed and its data has been freed.
If a Gio.Task has been constructed and its callback set, it is an error to not call
g_task_return_*()on it. GLib will warn at runtime if this happens (since 2.76).Here is an example for using Gio.Task as a Gio.AsyncResult:
Chained asynchronous operations
Gio.Task also tries to simplify asynchronous operations that internally chain together several smaller asynchronous operations. Gio.Task.get_cancellable, Gio.Task.get_context, and Gio.Task.get_priority allow you to get back the task’s Gio.Cancellable, GLib.MainContext, and I/O priority when starting a new subtask, so you don’t have to keep track of them yourself. Gio.Task.attach_source simplifies the case of waiting for a source to fire (automatically using the correct GLib.MainContext and priority).
Here is an example for chained asynchronous operations:
Asynchronous operations from synchronous ones
You can use Gio.Task.run_in_thread to turn a synchronous operation into an asynchronous one, by running it in a thread. When it completes, the result will be dispatched to the thread-default main context (see GLib.MainContext.push_thread_default) where the Gio.Task was created.
Running a task in a thread:
Adding cancellability to uncancellable tasks
Finally, Gio.Task.run_in_thread and Gio.Task.run_in_thread_sync can be used to turn an uncancellable operation into a cancellable one. If you call Gio.Task.set_return_on_cancel, passing
TRUE, then if the task’s Gio.Cancellable is cancelled, it will return control back to the caller immediately, while allowing the task thread to continue running in the background (and simply discarding its result when it finally does finish). Provided that the task thread is careful about how it uses locks and other externally-visible resources, this allows you to make ‘GLib-friendly’ asynchronous and cancellable synchronous variants of blocking APIs.Cancelling a task:
Porting from Gio.SimpleAsyncResult
Gio.Task’s API attempts to be simpler than Gio.SimpleAsyncResult’s in several ways:
task_func, even if the task’s Gio.Cancellable is already cancelled before the task gets a chance to run; you can start yourtask_funcwith a Gio.Task.return_error_if_cancelled check if you need the old behavior._finish()wrapper function, and have virtual method implementations only deal with successful returns. This behavior is deprecated, because it makes it difficult for a subclass to chain to a parent class’s async methods. Instead, the wrapper function should just be a simple wrapper, and the virtual method should call an appropriateg_task_propagate_function. Note that wrapper methods can now use Gio.AsyncResult.legacy_propagate_error to do old-style Gio.SimpleAsyncResult error-returning behavior, and Gio.AsyncResult.is_tagged to check if a result is tagged as having come from the_async()wrapper function (for ‘short-circuit’ results, such as when passing0to Gio.InputStream.read_async).Thread-safety considerations
Due to some infelicities in the API design, there is a thread-safety concern that users of Gio.Task have to be aware of:
If the
mainthread drops its last reference to the source object or the task data before the task is finalized, then the finalizers of these objects may be called on the worker thread.This is a problem if the finalizers use non-threadsafe API, and can lead to hard-to-debug crashes. Possible workarounds include:
notify::completed