Creates a #GTask acting on source_object, which will eventually be
used to invoke callback in the current
[thread-default main context][g-main-context-push-thread-default].
Call this in the "start" method of your asynchronous method, and pass the #GTask around throughout the asynchronous operation. You can use g_task_set_task_data() to attach task-specific data to the object, which you can retrieve later via g_task_get_task_data().
By default, if cancellable is cancelled, then the return value of
the task will always be %G_IO_ERROR_CANCELLED, even if the task had
already completed before the cancellation. This allows for
simplified handling in cases where cancellation may imply that
other objects that the task depends on have been destroyed. If you
do not want this behavior, you can use
g_task_set_check_cancellable() to change it.
the #GObject that owns this task, or %NULL.
optional #GCancellable object, %NULL to ignore.
a #GAsyncReadyCallback.
Whether 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.
This property is guaranteed to change from %FALSE to %TRUE exactly once.
The #GObject::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 instance to be updated with the same value of the "active" property of the action #GObject instance.
If flags contains %G_BINDING_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
#GBinding 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 can have multiple bindings.
the property on source to bind
the target #GObject
the property on target to bind
flags to pass to #GBinding
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 target #GObject
the property on target to bind
flags to pass to #GBinding
a #GClosure wrapping the transformation function from the source to the target, or %NULL to use the default
a #GClosure wrapping the transformation function from the target to the source, or %NULL to use the default
This function is intended for #GObject 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::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 #GCancellable
Gets task's check-cancellable flag. See
g_task_set_check_cancellable() for more details.
Gets the value of #GTask:completed. This changes from %FALSE to %TRUE after the task’s callback is invoked, and will return %FALSE if called from inside the callback.
Gets the #GMainContext that task will return its result in (that
is, the context that was the
[thread-default main context][g-main-context-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 #GMainContext.
Gets a named field from the objects table of associations (see g_object_set_data()).
name of the key for that association
Gets task’s name. See g_task_set_name().
Gets 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 g_value_unset().
Note that g_object_get_property() is really intended for language bindings, g_object_get() is much more convenient for C programming.
the name of the property to get
return location for the property value
This function gets back user data pointers stored via g_object_set_qdata().
A #GQuark, naming the user data pointer
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().
Gets task's task_data.
Gets the user data from a #GAsyncResult.
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.
Checks whether object has a [floating][floating-ref] reference.
Checks if res has the given source_tag (generally a function
pointer indicating the function res was created by).
an application-defined tag
If res is a #GSimpleAsyncResult, this is equivalent to
g_simple_async_result_propagate_error(). Otherwise it returns
%FALSE.
This can be used for legacy error handling in async *_finish() wrapper functions that traditionally handled #GSimpleAsyncResult error returns themselves rather than calling into the virtual method. This should not be used in new code; #GAsyncResult errors that are set by virtual methods should also be extracted by virtual methods, to enable subclasses to chain up correctly.
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.:
enum
{
PROP_0,
PROP_FOO,
PROP_LAST
};
static GParamSpec *properties[PROP_LAST];
static void
my_object_class_init (MyObjectClass *klass)
{
properties[PROP_FOO] = g_param_spec_int ("foo", "Foo", "The foo",
0, 100,
50,
G_PARAM_READWRITE);
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 #GParamSpec 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.
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.
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.
Gets the result of task as a #GValue, 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.
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().
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 g_task_return_new_error().
Checks if task's #GCancellable 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).
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 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 #GMainContext, or in the next
iteration of the current #GMainContext. 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 #GTaskThreadFunc
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.
the pointer result of a task function
a #GDestroyNotify function.
Sets task's result to result (by copying it) and completes the task.
If result is %NULL then a #GValue 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.
the #GValue 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
#GAsyncReadyCallback will be invoked in task's #GMainContext.
This takes a ref on task until the task completes.
See #GTaskThreadFunc 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.
a #GTaskThreadFunc
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 #GTaskThreadFunc 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.
#GTask: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.
a #GTaskThreadFunc
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 #GCancellable first, and
if it has been cancelled, then they will consider the task to have
returned an "Operation was cancelled" error
(%G_IO_ERROR_CANCELLED), regardless of any other error or return
value the task may have had.
If check_cancellable is %FALSE, then the #GTask 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 #GTask will check the state of its #GCancellable 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 #GQuark 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 #GQuark storage growing unbounded.
name of the key
data 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 #GSource 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. It is called automatically by
g_task_set_source_tag() if not called already.
a 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][io-priority] of the request
Sets a property on an object.
the name of the property to set
the value
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
#GCancellable will immediately cause it to return, as though the
task's #GTaskThreadFunc had called
g_task_return_error_if_cancelled() and then returned.
This allows you to create a cancellable wrapper around an uninterruptible function. The #GTaskThreadFunc 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 #GCancellable 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 #GCancellable is already cancelled before you call g_task_run_in_thread()/g_task_run_in_thread_sync(), then the #GTaskThreadFunc will still be run (for consistency), but the task will also be completed right away.
whether the task returns automatically when it is 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.
an opaque pointer indicating the source of this task
Sets task's task data (freeing the existing task data, if any).
task-specific data
#GDestroyNotify for task_data
Remove a specified datum from the object's data associations, without invoking the association's destroy handler.
name of the key
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 #GQuark, naming the user data pointer
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::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.
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 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 instance. Use g_clear_object() for this.
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.
#GClosure to watch
Find the #GParamSpec 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.
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 #GParamSpec, 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
#GTypeInfo.) 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 #GParamSpec for the new property
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
Checks that result is a #GTask, 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.
A #GAsyncResult
the source object expected to be associated with the task
Creates a #GTask acting on source_object, which will eventually be
used to invoke callback in the current
[thread-default main context][g-main-context-push-thread-default].
Call this in the "start" method of your asynchronous method, and pass the #GTask around throughout the asynchronous operation. You can use g_task_set_task_data() to attach task-specific data to the object, which you can retrieve later via g_task_get_task_data().
By default, if cancellable is cancelled, then the return value of
the task will always be %G_IO_ERROR_CANCELLED, even if the task had
already completed before the cancellation. This allows for
simplified handling in cases where cancellation may imply that
other objects that the task depends on have been destroyed. If you
do not want this behavior, you can use
g_task_set_check_cancellable() to change it.
the #GObject that owns this task, or %NULL.
optional #GCancellable object, %NULL to ignore.
a #GAsyncReadyCallback.
Creates a new instance of a #GObject subtype and sets its properties.
Construction parameters (see %G_PARAM_CONSTRUCT, %G_PARAM_CONSTRUCT_ONLY) which are not explicitly specified are set to their default values.
the type id of the #GObject subtype to instantiate
an array of #GParameter
Creates a #GTask 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 that owns this task, or %NULL.
a #GAsyncReadyCallback.
an opaque pointer indicating the source of this task
error to report
A #GTask represents and manages a cancellable "task".
Asynchronous operations
The most common usage of #GTask is as a #GAsyncResult, to manage data during an asynchronous operation. You call g_task_new() in the "start" method, followed by g_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 g_task_return_pointer() or g_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][g-main-context-push-thread-default] where it was created (waiting until the next iteration of the main loop first, if necessary). The caller will pass the #GTask back to the operation's finish function (as a #GAsyncResult), and you can use g_task_propagate_pointer() or the like to extract the return value.
Using #GTask requires the thread-default #GMainContext from when the #GTask was constructed to be running at least until the task has completed and its data has been freed.
Here is an example for using GTask as a GAsyncResult:
Chained asynchronous operations
#GTask also tries to simplify asynchronous operations that internally chain together several smaller asynchronous operations. g_task_get_cancellable(), g_task_get_context(), and g_task_get_priority() allow you to get back the task's #GCancellable, #GMainContext, and [I/O priority][io-priority] when starting a new subtask, so you don't have to keep track of them yourself. g_task_attach_source() simplifies the case of waiting for a source to fire (automatically using the correct #GMainContext and priority).
Here is an example for chained asynchronous operations:
Asynchronous operations from synchronous ones
You can use g_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][g-main-context-push-thread-default] where the #GTask was created.
Running a task in a thread:
Adding cancellability to uncancellable tasks
Finally, g_task_run_in_thread() and g_task_run_in_thread_sync() can be used to turn an uncancellable operation into a cancellable one. If you call g_task_set_return_on_cancel(), passing %TRUE, then if the task's #GCancellable 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 GSimpleAsyncResult
#GTask's API attempts to be simpler than #GSimpleAsyncResult's in several ways:
task_func, even if the task's #GCancellable is already cancelled before the task gets a chance to run; you can start yourtask_funcwith a g_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 g_async_result_legacy_propagate_error() to do old-style #GSimpleAsyncResult error-returning behavior, and g_async_result_is_tagged() to check if a result is tagged as having come from the_async()wrapper function (for "short-circuit" results, such as when passing 0 to g_input_stream_read_async()).