Top | ![]() |
![]() |
![]() |
![]() |
IdeTask is meant to be an improved form of GTask. There are a few deficiencies in GTask that have made it unsuitable for certain use cases.
GTask does not provide a way to guarantee that the source object, task data, and unused results are freed with in a given GMainContext. IdeTask addresses this by having a more flexible result and object ownership control.
Furthermore, IdeTask allows consumers to force disposal from a given thread so that the data is released there.
IdeTask also supports chaining tasks together which makes it simpler to avoid doing duplicate work by instead simply chaining the tasks.
There are some costs to this design. It uses the main context a bit more than GTask may use it.
IdeTask allows setting a task kind which determines which thread pool the task will be executed (and throttled) on.
Because IdeTask needs more control over result life-cycles (for chaining
results), additional return methods have been provided. Consumers should
use ide_task_return_boxed()
when working with boxed types as it allows us
to copy the result to another task. Additionally, ide_task_return_object()
provides a simplified API over ide_task_return_pointer()
which also allows
copying the result to chained tasks.
void (*IdeTaskThreadFunc) (IdeTask *task
,gpointer source_object
,gpointer task_data
,GCancellable *cancellable
);
IdeTask * ide_task_new (gpointer source_object
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
);
Creates a new IdeTask.
IdeTask is similar to GTask but provides some additional guarantees such that by default, the source object, task data, and unused results are guaranteed to be finalized in the GMainContext associated with the task itself.
source_object |
[type GObject.Object][nullable] | |
cancellable |
a GCancellable or |
[nullable] |
callback |
a GAsyncReadyCallback or |
[scope async][nullable] |
user_data |
closure data for |
Since: 3.32
void ide_task_chain (IdeTask *self
,IdeTask *other_task
);
Causes the result of self
to also be delivered to other_task
.
This API is useful in situations when you want to avoid doing the same work multiple times, and can share the result between mutliple async operations requesting the same work.
Users of this API must make sure one of two things is true. Either they
have called ide_task_set_release_on_propagate()
with self
and set
release_on_propagate to FALSE
, or self
has not yet completed.
Since: 3.32
GCancellable *
ide_task_get_cancellable (IdeTask *self
);
Gets the GCancellable for the task.
Since: 3.32
gboolean
ide_task_get_completed (IdeTask *self
);
Gets the "completed" property. This is TRUE
after the callback used when
creating the task has been executed.
The property will be notified using g_object_notify()
exactly once in the
same GMainContext as the callback.
Since: 3.32
const gchar *
ide_task_get_name (IdeTask *self
);
Gets the name assigned for the task.
Since: 3.32
gpointer
ide_task_get_source_object (IdeTask *self
);
Gets the GObject used when creating the source object.
As this does not provide ownership transfer of the GObject, it is a
programmer error to call this function outside of a thread worker called
from ide_task_run_in_thread()
or outside the GMainContext that is
associated with the task.
If you need to access the object in other scenarios, you must use the
g_async_result_get_source_object()
which provides a full reference to the
source object, safely. You are responsible for ensuring that you do not
release the object in a manner that is unsafe for the source object.
[skip]
Since: 3.32
gpointer
ide_task_get_task_data (IdeTask *self
);
Gets the task data previously set with ide_task_set_task_data()
.
[skip]
Since: 3.32
gboolean
ide_task_had_error (IdeTask *self
);
Checks to see if the task had an error.
Since: 3.32
gboolean ide_task_is_valid (gpointer self
,gpointer source_object
);
Checks if source_object
matches the object the task was created with.
Since: 3.32
gpointer ide_task_propagate_object (IdeTask *self
,GError **error
);
Returns an object if the task completed with an object. Otherwise, NULL
is returned.
error
is set if the task completed with an error.
Since: 3.32
void ide_task_return_boolean (IdeTask *self
,gboolean result
);
Sets the result of the task to result
.
Other tasks depending on the result will be notified after returning to the GMainContext of the task.
Since: 3.32
void ide_task_return_boxed (IdeTask *self
,GType result_type
,gpointer result
);
This is similar to ide_task_return_pointer()
, but allows the task to
know the boxed GType so that the result may be propagated to chained
tasks.
[skip]
Since: 3.32
void ide_task_return_error (IdeTask *self
,GError *error
);
Sets error
as the result of the IdeTask
Since: 3.32
gboolean
ide_task_return_error_if_cancelled (IdeTask *self
);
Returns a new GError if the cancellable associated with the task
has been cancelled. If so, TRUE
is returned, otherwise FALSE
.
If the source object related to the task is an IdeObject and that object has had been requested to destroy, it too will be considered a cancellation state.
Since: 3.32
void ide_task_return_int (IdeTask *self
,gssize result
);
Sets the result of the task to result
.
Other tasks depending on the result will be notified after returning to the GMainContext of the task.
Since: 3.32
gboolean
ide_task_get_return_on_cancel (IdeTask *self
);
Gets the return_on_cancel value, which means the task will return immediately when the GCancellable is cancelled.
Since: 3.32
void ide_task_return_new_error (IdeTask *self
,GQuark error_domain
,gint error_code
,const gchar *format
,...
);
Creates a new GError and sets it as the result for the task.
Since: 3.32
void ide_task_return_object (IdeTask *self
,gpointer instance
);
Returns a new object instance.
Takes ownership of instance
to allow saving a reference increment and
decrement by the caller.
Since: 3.32
void ide_task_return_pointer (IdeTask *self
,gpointer data
,GDestroyNotify destroy
);
Returns a new raw pointer.
Note that pointers cannot be chained to other tasks, so you may not
use ide_task_chain()
in conjunction with a task returning a pointer
using ide_task_return_pointer()
.
If you need task chaining with pointers, see ide_task_return_boxed()
or ide_task_return_object()
.
[skip]
self |
a IdeTask |
|
data |
the data to return |
|
destroy |
an optional GDestroyNotify to cleanup data if no handler propagates the result |
Since: 3.32
void ide_task_run_in_thread (IdeTask *self
,IdeTaskThreadFunc thread_func
);
Scheules thread_func
to be executed on a worker thread.
thread_func
must complete the task from the worker thread using one of
ide_task_return_boolean()
, ide_task_return_int()
, or
ide_task_return_pointer()
.
[skip]
Since: 3.32
void ide_task_set_check_cancellable (IdeTask *self
,gboolean check_cancellable
);
Setting check_cancellable
to TRUE
(the default) ensures that the
GCancellable used when creating the IdeTask is checked for cancellation
before propagating a result. If cancelled, an error will be returned
instead of the result.
Since: 3.32
void ide_task_set_name (IdeTask *self
,const gchar *name
);
Sets a useful name for the task.
This string is interned, so it is best to avoid dynamic names as that can result in lots of unnecessary strings being interned for the lifetime of the process.
This name may be used in various g_critical()
messages which can
be useful in troubleshooting.
If using IdeTask from C, a default name is set using the source file name and line number.
Since: 3.32
void ide_task_set_complete_priority (IdeTask *self
,gint complete_priority
);
void ide_task_set_release_on_propagate (IdeTask *self
,gboolean release_on_propagate
);
Setting this to TRUE
(the default) ensures that the task will release all
task data and source_object references after executing the configured
callback. This is useful to ensure that dependent objects are finalized
in the thread-default GMainContext the task was created in.
Generally, you want to leave this as TRUE
to ensure thread-safety on the
dependent objects and task data.
Since: 3.32
void ide_task_set_return_on_cancel (IdeTask *self
,gboolean return_on_cancel
);
Setting return_on_cancel
to TRUE
ensures that the task will cancel
immediately when “cancelled” is emitted by the configured
cancellable.
Setting this requires that the caller can ensure the configured GMainContext will outlive the threaded worker so that task state can be freed in a delayed fashion.
self |
a IdeTask |
|
return_on_cancel |
if the task should return immediately when the GCancellable has been cancelled. |
Since: 3.32
void ide_task_set_source_tag (IdeTask *self
,gpointer source_tag
);
Sets the source tag for the task. Generally this is a function pointer of the function that created the task.
Since: 3.32
void ide_task_set_task_data (IdeTask *self
,gpointer task_data
,GDestroyNotify task_data_destroy
);
“completed”
property“completed” gboolean
If the task has completed.
Owner: IdeTask
Flags: Read
Default value: FALSE