IdeTask: Builder SDK Reference

## IdeTask IdeTask — asynchronous task management |

## Functions

void | (*IdeTaskThreadFunc) ()
IdeTask * | ide_task_new ()
void | ide_task_chain ()
GCancellable * | ide_task_get_cancellable ()
gboolean | ide_task_get_completed ()
IdeTaskKind | ide_task_get_kind ()
const gchar * | ide_task_get_name ()
gint | ide_task_get_priority ()
gint | ide_task_get_complete_priority ()
gpointer | ide_task_get_source_object ()
gpointer | ide_task_get_source_tag ()
gpointer | ide_task_get_task_data ()
gboolean | ide_task_had_error ()
gboolean | ide_task_is_valid ()
gboolean | ide_task_propagate_boolean ()
gpointer | ide_task_propagate_boxed ()
gssize | ide_task_propagate_int ()
gpointer | ide_task_propagate_object ()
gpointer | ide_task_propagate_pointer ()
void | ide_task_return_boolean ()
void | ide_task_return_boxed ()
void | ide_task_return_error ()
gboolean | ide_task_return_error_if_cancelled ()
void | ide_task_return_int ()
gboolean | ide_task_get_return_on_cancel ()
void | ide_task_return_new_error ()
void | ide_task_return_object ()
void | ide_task_return_pointer ()
void | ide_task_run_in_thread ()
void | ide_task_set_check_cancellable ()
void | ide_task_set_kind ()
void | ide_task_set_name ()
void | ide_task_set_priority ()
void | ide_task_set_complete_priority ()
void | ide_task_set_release_on_propagate ()
void | ide_task_set_return_on_cancel ()
void | ide_task_set_source_tag ()
void | ide_task_set_task_data ()
void | ide_task_report_new_error ()

## Properties

gboolean | completed | Read

## Types and Values

#define | IDE_TYPE_TASK
enum | IdeTaskKind
struct | IdeTaskClass
| IdeTask

## 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.

Owner: IdeTask

Flags: Read

Default value: FALSE