Sets our main struct and passes it to the parent class
Creates a GTask acting on source_object, which will eventually be used to invoke callback in the current thread-default main context. 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. Since 2.36
A utility function for dealing with async operations where you need to wait for a GSource to trigger. Attaches source to task's GMainContext with task's priority, and sets source's callback to callback, with task as the callback's user_data. This takes a reference on task until source is destroyed. Since 2.36
Gets task's GCancellable Since 2.36
Gets task's check-cancellable flag. See g_task_set_check_cancellable() for more details. Since 2.36
Gets the GMainContext that task will return its result in (that is, the context that was the thread-default main context 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. Since 2.36
Gets task's priority Since 2.36
Gets task's return-on-cancel flag. See g_task_set_return_on_cancel() for more details. Since 2.36
Gets task's source tag. See g_task_set_source_tag(). Since 2.36
the main Gtk struct as a void*
Gets task's task_data. Since 2.36
Tests if task resulted in an error. Since 2.36
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. Since 2.36
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. Since 2.36
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. Since 2.36
Sets task's result to result and completes the task (see g_task_return_pointer() for more discussion of exactly what this means). Since 2.36
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(). Since 2.36
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). Since 2.36
Sets task's result to result and completes the task (see g_task_return_pointer() for more discussion of exactly what this means). Since 2.36
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. Since 2.36
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. Since 2.36
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. Since 2.36
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. Since 2.36
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(). Since 2.36
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 uninterruptable 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. Since 2.36
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. Since 2.36
Sets task's task data (freeing the existing task data, if any). Since 2.36
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. Since 2.36
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(). Since 2.36
the main Gtk struct
the main Gtk struct
the main Gtk struct as a void*
Gets a D Object from the objects table of associations.
The notify signal is emitted on an object when one of its properties has been changed. Note that getting this signal doesn't guarantee that the value of the property has actually changed, it may also be emitted when the setter for the property is called to reinstate the previous value.
Installs a new property. This is usually done in the class initializer. Note that it is possible to redefine a property in a derived class, by installing a property with the same name. This can be useful at times, e.g. to change the range of allowed values or the default value.
Installs new properties from an array of GParamSpecs. This is usually done in the class initializer. The property id of each property is the index of each GParamSpec in the pspecs array. The property id of 0 is treated specially by GObject and it should not be used to store a GParamSpec. This function should be used if you plan to use a static array of GParamSpecs and g_object_notify_by_pspec(). For instance, this Since 2.26
Looks up the GParamSpec for a property of a class.
Get an array of GParamSpec* for all properties of a class.
Registers property_id as referring to a property with the name name in a parent class or in an interface implemented by oclass. This allows this class to override a property implementation in a parent class or to provide the implementation of a property from an interface. Note Internally, overriding is implemented by creating a property of type GParamSpecOverride; generally operations that query the properties of the object class, such as g_object_class_find_property() or g_object_class_list_properties() will return the overridden property. However, in one case, the construct_properties argument of the constructor virtual function, the GParamSpecOverride is passed instead, so that the param_id field of the GParamSpec will be correct. For virtually all uses, this makes no difference. If you need to get the overridden property, you can call g_param_spec_get_redirect_target(). Since 2.4
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. Since 2.4
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(). Since 2.4
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(). Since 2.4
Increases the reference count of object.
Decreases the reference count of object. When its reference count drops to 0, the object is finalized (i.e. its memory is freed).
Increase the reference count of object, and possibly remove the floating 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 2.10
Clears a reference to a GObject. object_ptr must not be NULL. If the reference is NULL then this function does nothing. Otherwise, the reference count of the object is decreased and the pointer is set to NULL. This function is threadsafe and modifies the pointer atomically, using memory barriers where needed. A macro is also included that allows this function to be used without pointer casts. Since 2.28
Checks whether object has a floating reference. Since 2.10
This function is intended for GObject implementations to re-enforce a floating 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(). Since 2.10
Adds a weak reference callback to an object. Weak references are used for notification when an object is finalized. They are called "weak references" because they allow you to safely hold a pointer to an object without calling g_object_ref() (g_object_ref() adds a strong reference, that is, forces the object to stay alive). Note that the weak references created by this method are not thread-safe: they cannot safely be used in one thread if the object's last g_object_unref() might happen in another thread. Use GWeakRef if thread-safety is required.
Removes a weak reference callback to an object.
Adds a weak reference from weak_pointer to object to indicate that the pointer located at weak_pointer_location is only valid during the lifetime of object. When the object is finalized, weak_pointer will be set to NULL. Note that as with g_object_weak_ref(), the weak references created by this method are not thread-safe: they cannot safely be used in one thread if the object's last g_object_unref() might happen in another thread. Use GWeakRef if thread-safety is required.
Removes a weak reference from object that was previously added using g_object_add_weak_pointer(). The weak_pointer_location has to match the one used with g_object_add_weak_pointer().
Increases the reference count of the object by one and sets a callback to be called when all other references to the object are dropped, or when this is already the last reference to the object and another reference is established. This functionality is intended for binding object to a proxy object managed by another memory manager. This is done with two paired references: the strong reference added by g_object_add_toggle_ref() and a reverse reference to the proxy object which is either a strong reference or weak reference. The setup is that when there are no other references to object, only a weak reference is held in the reverse direction from object to the proxy object, but when there are other references held to object, a strong reference is held. The notify callback is called when the reference from object to the proxy object should be toggled from strong to weak (is_last_ref true) or weak to strong (is_last_ref false). Since a (normal) reference must be held to the object before calling g_object_add_toggle_ref(), the initial state of the reverse link is always strong. Multiple toggle references may be added to the same gobject, however if there are multiple toggle references to an object, none of them will ever be notified until all but one are removed. For this reason, you should only ever use a toggle reference if there is important state in the proxy object. Since 2.8
Removes a reference added with g_object_add_toggle_ref(). The reference count of the object is decreased by one. Since 2.8
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.
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 Since 2.26
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 "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.
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 "notify" signal is emitted for each property. It is an error to call this function when the freeze count is zero.
Gets a named field from the objects table of associations (see g_object_set_data()).
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.
Like g_object_set_data() except it adds notification for when the association is destroyed, either by setting it to a different value or when the object is destroyed. Note that the destroy callback is not called if data is NULL.
Remove a specified datum from the object's data associations, without invoking the association's destroy handler.
This is a variant of g_object_get_data() which returns a 'duplicate' of the value. dup_func defines the meaning of 'duplicate' in this context, it could e.g. take a reference on a ref-counted object. If the key is not set on the object then dup_func will be called with a NULL argument. Note that dup_func is called while user data of object is locked. This function can be useful to avoid races when multiple threads are using object data on the same key on the same object. Since 2.34
Compares the user data for the key key on object with oldval, and if they are the same, replaces oldval with newval. This is like a typical atomic compare-and-exchange operation, for user data on an object. If the previous value was replaced then ownership of the old value (oldval) is passed to the caller, including the registered destroy notify for it (passed out in old_destroy). Its up to the caller to free this as he wishes, which may or may not include using old_destroy as sometimes replacement should not destroy the object in the normal way. Return: TRUE if the existing value for key was replaced by newval, FALSE otherwise. Since 2.34
This function gets back user data pointers stored via g_object_set_qdata().
This sets an opaque, named pointer on an object. The name is specified through a GQuark (retrived e.g. via g_quark_from_static_string()), and the pointer can be gotten back from the object with g_object_get_qdata() until the object is finalized. Setting a previously set user data pointer, overrides (frees) the old pointer set, using NULL as pointer essentially removes the data stored.
This function works like g_object_set_qdata(), but in addition, a void (*destroy) (gpointer) function may be specified which is called with data as argument when the object is finalized, or the data is being overwritten by a call to g_object_set_qdata() with the same quark.
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
This is a variant of g_object_get_qdata() which returns a 'duplicate' of the value. dup_func defines the meaning of 'duplicate' in this context, it could e.g. take a reference on a ref-counted object. If the quark is not set on the object then dup_func will be called with a NULL argument. Note that dup_func is called while user data of object is locked. This function can be useful to avoid races when multiple threads are using object data on the same key on the same object. Since 2.34
Compares the user data for the key quark on object with oldval, and if they are the same, replaces oldval with newval. This is like a typical atomic compare-and-exchange operation, for user data on an object. If the previous value was replaced then ownership of the old value (oldval) is passed to the caller, including the registered destroy notify for it (passed out in old_destroy). Its up to the caller to free this as he wishes, which may or may not include using old_destroy as sometimes replacement should not destroy the object in the normal way. Return: TRUE if the existing value for quark was replaced by newval, FALSE otherwise. Since 2.34
Sets a property on an object.
Gets a property of an object. value must have been initialized to the expected type of the property (or a type to which the expected type can be transformed) using g_value_init(). 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.
Sets properties on an object.
Gets properties of an object. In general, a copy is made of the property contents and the caller is responsible for freeing the memory in the appropriate manner for the type, for instance by calling g_free() or g_object_unref(). See g_object_get().
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.
Releases all references to other objects. This can be used to break reference cycles. This functions should only be called from object system implementations.
the main Gtk struct as a void*
Gets the user data from a GAsyncResult.
Gets the source object from a GAsyncResult.
Checks if res has the given source_tag (generally a function pointer indicating the function res was created by). Since 2.34
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. Since 2.34
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 (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.
<hr>
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 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).
<hr>
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 which will then dispatch the result back to the caller's GMainContext when it completes.
<hr>
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.
<hr>
Porting from GSimpleAsyncResult
GTask's API attempts to be simpler than GSimpleAsyncResult's in several ways:
You can save task-specific data with g_task_set_task_data(), and retrieve it later with g_task_get_task_data(). This replaces the abuse of g_simple_async_result_set_op_res_gpointer() for the same purpose with GSimpleAsyncResult.
In addition to the task data, GTask also keeps track of the priority, GCancellable, and GMainContext associated with the task, so tasks that consist of a chain of simpler asynchronous operations will have easy access to those values when starting each sub-task.
g_task_return_error_if_cancelled() provides simplified handling for cancellation. In addition, cancellation overrides any other GTask return value by default, like GSimpleAsyncResult does when g_simple_async_result_set_check_cancellable() is called. (You can use g_task_set_check_cancellable() to turn off that behavior.) On the other hand, g_task_run_in_thread() guarantees that it will always run your task_func, even if the task's GCancellable is already cancelled before the task gets a chance to run; you can start your task_func with a g_task_return_error_if_cancelled() check if you need the old behavior.
The "return" methods (eg, g_task_return_pointer()) automatically cause the task to be "completed" as well, and there is no need to worry about the "complete" vs "complete in idle" distinction. (GTask automatically figures out whether the task's callback can be invoked directly, or if it needs to be sent to another GMainContext, or delayed until the next iteration of the current GMainContext.)
The "finish" functions for GTask-based operations are generally much simpler than GSimpleAsyncResult ones, normally consisting of only a single call to g_task_propagate_pointer() or the like. Since g_task_propagate_pointer() "steals" the return value from the GTask, it is not necessary to juggle pointers around to prevent it from being freed twice.
With GSimpleAsyncResult, it was common to call g_simple_async_result_propagate_error() from the _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 appropriate g_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()).