IdeTask

IdeTask — asynchronous task management

Functions

Properties

Types and Values

Object Hierarchy

    GObject
    ╰── IdeTask

Implemented Interfaces

IdeTask implements GAsyncResult.

Description

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.

Functions

IdeTaskThreadFunc ()

void
(*IdeTaskThreadFunc) (IdeTask *task,
                      gpointer source_object,
                      gpointer task_data,
                      GCancellable *cancellable);

ide_task_new ()

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.

Parameters

source_object

a GObject or NULL.

[type GObject.Object][nullable]

cancellable

a GCancellable or NULL.

[nullable]

callback

a GAsyncReadyCallback or NULL.

[scope async][nullable]

user_data

closure data for callback

 

Returns

an IdeTask.

[transfer full]

Since: 3.32


ide_task_chain ()

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.

Parameters

self

a IdeTask

 

other_task

a IdeTask

 

Since: 3.32


ide_task_get_cancellable ()

GCancellable *
ide_task_get_cancellable (IdeTask *self);

Gets the GCancellable for the task.

Parameters

self

a IdeTask

 

Returns

a GCancellable or NULL.

[transfer none][nullable]

Since: 3.32


ide_task_get_completed ()

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.

Parameters

self

a IdeTask

 

Returns

TRUE if the task has completed

Since: 3.32


ide_task_get_kind ()

IdeTaskKind
ide_task_get_kind (IdeTask *self);

ide_task_get_name ()

const gchar *
ide_task_get_name (IdeTask *self);

Gets the name assigned for the task.

Parameters

self

a IdeTask

 

Returns

a string or NULL.

[nullable]

Since: 3.32


ide_task_get_priority ()

gint
ide_task_get_priority (IdeTask *self);

ide_task_get_complete_priority ()

gint
ide_task_get_complete_priority (IdeTask *self);

ide_task_get_source_object ()

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]

Parameters

self

a IdeTask

 

Returns

a GObject or NULL.

[transfer none][nullable][type GObject.Object]

Since: 3.32


ide_task_get_source_tag ()

gpointer
ide_task_get_source_tag (IdeTask *self);

ide_task_get_task_data ()

gpointer
ide_task_get_task_data (IdeTask *self);

Gets the task data previously set with ide_task_set_task_data().

[skip]

Parameters

self

a IdeTask

 

Returns

previously registered task data or NULL.

[transfer none]

Since: 3.32


ide_task_had_error ()

gboolean
ide_task_had_error (IdeTask *self);

Checks to see if the task had an error.

Parameters

self

a IdeTask

 

Returns

TRUE if an error has occurred

Since: 3.32


ide_task_is_valid ()

gboolean
ide_task_is_valid (gpointer self,
                   gpointer source_object);

Checks if source_object matches the object the task was created with.

Parameters

self

a IdeTask.

[nullable][type IdeTask]

source_object

a GObject or NULL.

[nullable]

Returns

TRUE is source_object matches

Since: 3.32


ide_task_propagate_boolean ()

gboolean
ide_task_propagate_boolean (IdeTask *self,
                            GError **error);

ide_task_propagate_boxed ()

gpointer
ide_task_propagate_boxed (IdeTask *self,
                          GError **error);

ide_task_propagate_int ()

gssize
ide_task_propagate_int (IdeTask *self,
                        GError **error);

ide_task_propagate_object ()

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.

Parameters

self

a IdeTask

 

error

a location for a GError, or NULL

 

Returns

a GObject or NULL and error may be set.

[transfer full][type GObject.Object]

Since: 3.32


ide_task_propagate_pointer ()

gpointer
ide_task_propagate_pointer (IdeTask *self,
                            GError **error);

ide_task_return_boolean ()

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.

Parameters

self

a IdeTask

 

result

the result for the task

 

Since: 3.32


ide_task_return_boxed ()

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]

Parameters

self

a IdeTask

 

result_type

the GType of the boxed type

 

result

the result to be returned.

[transfer full]

Since: 3.32


ide_task_return_error ()

void
ide_task_return_error (IdeTask *self,
                       GError *error);

Sets error as the result of the IdeTask

Parameters

self

a IdeTask

 

error

a GError.

[transfer full]

Since: 3.32


ide_task_return_error_if_cancelled ()

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.

Parameters

self

a IdeTask

 

Returns

TRUE if the task was cancelled and error returned.

Since: 3.32


ide_task_return_int ()

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.

Parameters

self

a IdeTask

 

result

the result for the task

 

Since: 3.32


ide_task_get_return_on_cancel ()

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.

Parameters

self

a IdeTask

 

Since: 3.32


ide_task_return_new_error ()

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.

Parameters

self

a IdeTask

 

error_domain

the error domain of the GError

 

error_code

the error code for the GError

 

format

the printf-style format string

 

Since: 3.32


ide_task_return_object ()

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.

Parameters

self

a IdeTask

 

instance

a GObject instance.

[transfer full][type GObject.Object]

Since: 3.32


ide_task_return_pointer ()

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]

Parameters

self

a IdeTask

 

data

the data to return

 

destroy

an optional GDestroyNotify to cleanup data if no handler propagates the result

 

Since: 3.32


ide_task_run_in_thread ()

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]

Parameters

self

a IdeTask

 

thread_func

a function to execute on a worker thread

 

Since: 3.32


ide_task_set_check_cancellable ()

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.

Parameters

self

a IdeTask

 

check_cancellable

TRUE if the cancellable should be checked

 

Since: 3.32


ide_task_set_kind ()

void
ide_task_set_kind (IdeTask *self,
                   IdeTaskKind kind);

ide_task_set_name ()

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.

Parameters

self

a IdeTask

 

Since: 3.32


ide_task_set_priority ()

void
ide_task_set_priority (IdeTask *self,
                       gint priority);

ide_task_set_complete_priority ()

void
ide_task_set_complete_priority (IdeTask *self,
                                gint complete_priority);

ide_task_set_release_on_propagate ()

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.

Parameters

self

a IdeTask

 

release_on_propagate

if data should be released on propagate

 

Since: 3.32


ide_task_set_return_on_cancel ()

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.

Parameters

self

a IdeTask

 

return_on_cancel

if the task should return immediately when the GCancellable has been cancelled.

 

Since: 3.32


ide_task_set_source_tag ()

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.

Parameters

self

a IdeTask

 

source_tag

a tag to identify the task, usual a function pointer

 

Since: 3.32


ide_task_set_task_data ()

void
ide_task_set_task_data (IdeTask *self,
                        gpointer task_data,
                        GDestroyNotify task_data_destroy);

ide_task_report_new_error ()

void
ide_task_report_new_error (gpointer source_object,
                           GAsyncReadyCallback callback,
                           gpointer callback_data,
                           gpointer source_tag,
                           GQuark domain,
                           gint code,
                           const gchar *format,
                           ...);

Types and Values

IDE_TYPE_TASK

#define IDE_TYPE_TASK (ide_task_get_type())

enum IdeTaskKind

Members

IDE_TASK_KIND_DEFAULT

   

IDE_TASK_KIND_COMPILER

   

IDE_TASK_KIND_INDEXER

   

IDE_TASK_KIND_IO

   

IDE_TASK_KIND_LAST

   

struct IdeTaskClass

struct IdeTaskClass {
  GObjectClass parent;

  gpointer _reserved[16];
};

IdeTask

typedef struct _IdeTask IdeTask;

Property Details

The “completed” property

  “completed”                gboolean

If the task has completed.

Flags: Read

Default value: FALSE