/* GIO - GLib Input, Output and Streaming Library

 *

 * Copyright 2011 Red Hat, Inc.

 *

 * This library is free software; you can redistribute it and/or

 * modify it under the terms of the GNU Lesser General Public

 * License as published by the Free Software Foundation; either

 * version 2.1 of the License, or (at your option) any later version.

 *

 * This library is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

 * Lesser General Public License for more details.

 *

 * You should have received a copy of the GNU Lesser General

 * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.

 */

#include "config.h"

#include "gio_trace.h"

#include "gtask.h"

#include "gasyncresult.h"

#include "gcancellable.h"

#include "glib-private.h"

#include "glibintl.h"

/**

 * SECTION:gtask

 * @short_description: Cancellable synchronous or asynchronous task

 *     and result

 * @include: gio/gio.h

 * @see_also: #GAsyncResult

 *

 * 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

 * can use g_task_propagate_pointer() or the like to extract the

 * return value.

 *

 * Here is an example for using GTask as a GAsyncResult:

 * |[

 *     typedef struct {

 *       CakeFrostingType frosting;

 *       char *message;

 *     } DecorationData;

 *

 *     static void

 *     decoration_data_free (DecorationData *decoration)

 *     {

 *       g_free (decoration->message);

 *       g_slice_free (DecorationData, decoration);

 *     }

 *

 *     static void

 *     baked_cb (Cake     *cake,

 *               gpointer  user_data)

 *     {

 *       GTask *task = user_data;

 *       DecorationData *decoration = g_task_get_task_data (task);

 *       GError *error = NULL;

 *

 *       if (cake == NULL)

 *         {

 *           g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR,

 *                                    "Go to the supermarket");

 *           g_object_unref (task);

 *           return;

 *         }

 *

 *       if (!cake_decorate (cake, decoration->frosting, decoration->message, &error))

 *         {

 *           g_object_unref (cake);

 *           // g_task_return_error() takes ownership of error

 *           g_task_return_error (task, error);

 *           g_object_unref (task);

 *           return;

 *         }

 *

 *       g_task_return_pointer (task, cake, g_object_unref);

 *       g_object_unref (task);

 *     }

 *

 *     void

 *     baker_bake_cake_async (Baker               *self,

 *                            guint                radius,

 *                            CakeFlavor           flavor,

 *                            CakeFrostingType     frosting,

 *                            const char          *message,

 *                            GCancellable        *cancellable,

 *                            GAsyncReadyCallback  callback,

 *                            gpointer             user_data)

 *     {

 *       GTask *task;

 *       DecorationData *decoration;

 *       Cake  *cake;

 *

 *       task = g_task_new (self, cancellable, callback, user_data);

 *       if (radius < 3)

 *         {

 *           g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_TOO_SMALL,

 *                                    "%ucm radius cakes are silly",

 *                                    radius);

 *           g_object_unref (task);

 *           return;

 *         }

 *

 *       cake = _baker_get_cached_cake (self, radius, flavor, frosting, message);

 *       if (cake != NULL)

 *         {

 *           // _baker_get_cached_cake() returns a reffed cake

 *           g_task_return_pointer (task, cake, g_object_unref);

 *           g_object_unref (task);

 *           return;

 *         }

 *

 *       decoration = g_slice_new (DecorationData);

 *       decoration->frosting = frosting;

 *       decoration->message = g_strdup (message);

 *       g_task_set_task_data (task, decoration, (GDestroyNotify) decoration_data_free);

 *

 *       _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task);

 *     }

 *

 *     Cake *

 *     baker_bake_cake_finish (Baker         *self,

 *                             GAsyncResult  *result,

 *                             GError       **error)

 *     {

 *       g_return_val_if_fail (g_task_is_valid (result, self), NULL);

 *

 *       return g_task_propagate_pointer (G_TASK (result), error);

 *     }

 * ]|

 *

 * ## 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:

 *   |[

 *     typedef struct {

 *       Cake *cake;

 *       CakeFrostingType frosting;

 *       char *message;

 *     } BakingData;

 *

 *     static void

 *     decoration_data_free (BakingData *bd)

 *     {

 *       if (bd->cake)

 *         g_object_unref (bd->cake);

 *       g_free (bd->message);

 *       g_slice_free (BakingData, bd);

 *     }

 *

 *     static void

 *     decorated_cb (Cake         *cake,

 *                   GAsyncResult *result,

 *                   gpointer      user_data)

 *     {

 *       GTask *task = user_data;

 *       GError *error = NULL;

 *

 *       if (!cake_decorate_finish (cake, result, &error))

 *         {

 *           g_object_unref (cake);

 *           g_task_return_error (task, error);

 *           g_object_unref (task);

 *           return;

 *         }

 *

 *       // baking_data_free() will drop its ref on the cake, so we have to

 *       // take another here to give to the caller.

 *       g_task_return_pointer (task, g_object_ref (cake), g_object_unref);

 *       g_object_unref (task);

 *     }

 *

 *     static gboolean

 *     decorator_ready (gpointer user_data)

 *     {

 *       GTask *task = user_data;

 *       BakingData *bd = g_task_get_task_data (task);

 *

 *       cake_decorate_async (bd->cake, bd->frosting, bd->message,

 *                            g_task_get_cancellable (task),

 *                            decorated_cb, task);

 *

 *       return G_SOURCE_REMOVE;

 *     }

 *

 *     static void

 *     baked_cb (Cake     *cake,

 *               gpointer  user_data)

 *     {

 *       GTask *task = user_data;

 *       BakingData *bd = g_task_get_task_data (task);

 *       GError *error = NULL;

 *

 *       if (cake == NULL)

 *         {

 *           g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR,

 *                                    "Go to the supermarket");

 *           g_object_unref (task);

 *           return;

 *         }

 *

 *       bd->cake = cake;

 *

 *       // Bail out now if the user has already cancelled

 *       if (g_task_return_error_if_cancelled (task))

 *         {

 *           g_object_unref (task);

 *           return;

 *         }

 *

 *       if (cake_decorator_available (cake))

 *         decorator_ready (task);

 *       else

 *         {

 *           GSource *source;

 *

 *           source = cake_decorator_wait_source_new (cake);

 *           // Attach @source to @task's GMainContext and have it call

 *           // decorator_ready() when it is ready.

 *           g_task_attach_source (task, source, decorator_ready);

 *           g_source_unref (source);

 *         }

 *     }

 *

 *     void

 *     baker_bake_cake_async (Baker               *self,

 *                            guint                radius,

 *                            CakeFlavor           flavor,

 *                            CakeFrostingType     frosting,

 *                            const char          *message,

 *                            gint                 priority,

 *                            GCancellable        *cancellable,

 *                            GAsyncReadyCallback  callback,

 *                            gpointer             user_data)

 *     {

 *       GTask *task;

 *       BakingData *bd;

 *

 *       task = g_task_new (self, cancellable, callback, user_data);

 *       g_task_set_priority (task, priority);

 *

 *       bd = g_slice_new0 (BakingData);

 *       bd->frosting = frosting;

 *       bd->message = g_strdup (message);

 *       g_task_set_task_data (task, bd, (GDestroyNotify) baking_data_free);

 *

 *       _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task);

 *     }

 *

 *     Cake *

 *     baker_bake_cake_finish (Baker         *self,

 *                             GAsyncResult  *result,

 *                             GError       **error)

 *     {

 *       g_return_val_if_fail (g_task_is_valid (result, self), NULL);

 *

 *       return g_task_propagate_pointer (G_TASK (result), error);

 *     }

 * ]|

 *

 * ## 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:

 *   |[

 *     typedef struct {

 *       guint radius;

 *       CakeFlavor flavor;

 *       CakeFrostingType frosting;

 *       char *message;

 *     } CakeData;

 *

 *     static void

 *     cake_data_free (CakeData *cake_data)

 *     {

 *       g_free (cake_data->message);

 *       g_slice_free (CakeData, cake_data);

 *     }

 *

 *     static void

 *     bake_cake_thread (GTask         *task,

 *                       gpointer       source_object,

 *                       gpointer       task_data,

 *                       GCancellable  *cancellable)

 *     {

 *       Baker *self = source_object;

 *       CakeData *cake_data = task_data;

 *       Cake *cake;

 *       GError *error = NULL;

 *

 *       cake = bake_cake (baker, cake_data->radius, cake_data->flavor,

 *                         cake_data->frosting, cake_data->message,

 *                         cancellable, &error);

 *       if (cake)

 *         g_task_return_pointer (task, cake, g_object_unref);

 *       else

 *         g_task_return_error (task, error);

 *     }

 *

 *     void

 *     baker_bake_cake_async (Baker               *self,

 *                            guint                radius,

 *                            CakeFlavor           flavor,

 *                            CakeFrostingType     frosting,

 *                            const char          *message,

 *                            GCancellable        *cancellable,

 *                            GAsyncReadyCallback  callback,

 *                            gpointer             user_data)

 *     {

 *       CakeData *cake_data;

 *       GTask *task;

 *

 *       cake_data = g_slice_new (CakeData);

 *       cake_data->radius = radius;

 *       cake_data->flavor = flavor;

 *       cake_data->frosting = frosting;

 *       cake_data->message = g_strdup (message);

 *       task = g_task_new (self, cancellable, callback, user_data);

 *       g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);

 *       g_task_run_in_thread (task, bake_cake_thread);

 *       g_object_unref (task);

 *     }

 *

 *     Cake *

 *     baker_bake_cake_finish (Baker         *self,

 *                             GAsyncResult  *result,

 *                             GError       **error)

 *     {

 *       g_return_val_if_fail (g_task_is_valid (result, self), NULL);

 *

 *       return g_task_propagate_pointer (G_TASK (result), error);

 *     }

 * ]|

 *

 * ## 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:

 *   |[

 *     static void

 *     bake_cake_thread (GTask         *task,

 *                       gpointer       source_object,

 *                       gpointer       task_data,

 *                       GCancellable  *cancellable)

 *     {

 *       Baker *self = source_object;

 *       CakeData *cake_data = task_data;

 *       Cake *cake;

 *       GError *error = NULL;

 *

 *       cake = bake_cake (baker, cake_data->radius, cake_data->flavor,

 *                         cake_data->frosting, cake_data->message,

 *                         &error);

 *       if (error)

 *         {

 *           g_task_return_error (task, error);

 *           return;

 *         }

 *

 *       // If the task has already been cancelled, then we don't want to add

 *       // the cake to the cake cache. Likewise, we don't  want to have the

 *       // task get cancelled in the middle of updating the cache.

 *       // g_task_set_return_on_cancel() will return %TRUE here if it managed

 *       // to disable return-on-cancel, or %FALSE if the task was cancelled

 *       // before it could.

 *       if (g_task_set_return_on_cancel (task, FALSE))

 *         {

 *           // If the caller cancels at this point, their

 *           // GAsyncReadyCallback won't be invoked until we return,

 *           // so we don't have to worry that this code will run at

 *           // the same time as that code does. But if there were

 *           // other functions that might look at the cake cache,

 *           // then we'd probably need a GMutex here as well.

 *           baker_add_cake_to_cache (baker, cake);

 *           g_task_return_pointer (task, cake, g_object_unref);

 *         }

 *     }

 *

 *     void

 *     baker_bake_cake_async (Baker               *self,

 *                            guint                radius,

 *                            CakeFlavor           flavor,

 *                            CakeFrostingType     frosting,

 *                            const char          *message,

 *                            GCancellable        *cancellable,

 *                            GAsyncReadyCallback  callback,

 *                            gpointer             user_data)

 *     {

 *       CakeData *cake_data;

 *       GTask *task;

 *

 *       cake_data = g_slice_new (CakeData);

 *

 *       ...

 *

 *       task = g_task_new (self, cancellable, callback, user_data);

 *       g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);

 *       g_task_set_return_on_cancel (task, TRUE);

 *       g_task_run_in_thread (task, bake_cake_thread);

 *     }

 *

 *     Cake *

 *     baker_bake_cake_sync (Baker               *self,

 *                           guint                radius,

 *                           CakeFlavor           flavor,

 *                           CakeFrostingType     frosting,

 *                           const char          *message,

 *                           GCancellable        *cancellable,

 *                           GError             **error)

 *     {

 *       CakeData *cake_data;

 *       GTask *task;

 *       Cake *cake;

 *

 *       cake_data = g_slice_new (CakeData);

 *

 *       ...

 *

 *       task = g_task_new (self, cancellable, NULL, NULL);

 *       g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);

 *       g_task_set_return_on_cancel (task, TRUE);

 *       g_task_run_in_thread_sync (task, bake_cake_thread);

 *

 *       cake = g_task_propagate_pointer (task, error);

 *       g_object_unref (task);

 *       return cake;

 *     }

 * ]|

 *

 * ## 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][io-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()).

 */

/**

 * GTask:

 *

 * The opaque object representing a synchronous or asynchronous task

 * and its result.

 */

struct _GTask {

  GObject parent_instance;

  gpointer source_object;

  gpointer source_tag;

  gpointer task_data;

  GDestroyNotify task_data_destroy;

  GMainContext *context;

  gint64 creation_time;

  gint priority;

  GCancellable *cancellable;

  gboolean check_cancellable;

  GAsyncReadyCallback callback;

  gpointer callback_data;

  gboolean completed;

  GTaskThreadFunc task_func;

  GMutex lock;

  GCond cond;

  gboolean return_on_cancel;

  gboolean thread_cancelled;

  gboolean synchronous;

  gboolean thread_complete;

  gboolean blocking_other_task;

  GError *error;

  union {

    gpointer pointer;

    gssize   size;

    gboolean boolean;

  } result;

  GDestroyNotify result_destroy;

  gboolean had_error;

  gboolean result_set;

};

#define G_TASK_IS_THREADED(task) ((task)->task_func != NULL)

struct _GTaskClass

{

  GObjectClass parent_class;

};

typedef enum

{

  PROP_COMPLETED = 1,

} GTaskProperty;

static void g_task_async_result_iface_init (GAsyncResultIface *iface);

static void g_task_thread_pool_init (void);

G_DEFINE_TYPE_WITH_CODE (GTask, g_task, G_TYPE_OBJECT,

                         G_IMPLEMENT_INTERFACE (G_TYPE_ASYNC_RESULT,

                                                g_task_async_result_iface_init);

                         g_task_thread_pool_init ();)

static GThreadPool *task_pool;

static GMutex task_pool_mutex;

static GPrivate task_private = G_PRIVATE_INIT (NULL);

static GSource *task_pool_manager;

static guint64 task_wait_time;

static gint tasks_running;

/* When the task pool fills up and blocks, and the program keeps

 * queueing more tasks, we will slowly add more threads to the pool

 * (in case the existing tasks are trying to queue subtasks of their

 * own) until tasks start completing again. These "overflow" threads

 * will only run one task apiece, and then exit, so the pool will

 * eventually get back down to its base size.

 *

 * The base and multiplier below gives us 10 extra threads after about

 * a second of blocking, 30 after 5 seconds, 100 after a minute, and

 * 200 after 20 minutes.

 */

#define G_TASK_POOL_SIZE 10

#define G_TASK_WAIT_TIME_BASE 100000

#define G_TASK_WAIT_TIME_MULTIPLIER 1.03

#define G_TASK_WAIT_TIME_MAX (30 * 60 * 1000000)

static void

g_task_init (GTask *task)

{

  task->check_cancellable = TRUE;

}

static void

g_task_finalize (GObject *object)

{

  GTask *task = G_TASK (object);

  g_clear_object (&task->source_object);

  g_clear_object (&task->cancellable);

  if (task->context)

    g_main_context_unref (task->context);

  if (task->task_data_destroy)

    task->task_data_destroy (task->task_data);

  if (task->result_destroy && task->result.pointer)

    task->result_destroy (task->result.pointer);

  if (task->error)

      g_error_free (task->error);

  if (G_TASK_IS_THREADED (task))

    {

      g_mutex_clear (&task->lock);

      g_cond_clear (&task->cond);

    }

  G_OBJECT_CLASS (g_task_parent_class)->finalize (object);

}

/**

 * g_task_new:

 * @source_object: (nullable) (type GObject): the #GObject that owns

 *   this task, or %NULL.

 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.

 * @callback: (scope async): a #GAsyncReadyCallback.

 * @callback_data: (closure): user data passed to @callback.

 *

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

 *

 * Returns: a #GTask.

 *

 * Since: 2.36

 */

GTask *

g_task_new (gpointer              source_object,

            GCancellable         *cancellable,

            GAsyncReadyCallback   callback,

            gpointer              callback_data)

{

  GTask *task;

  GSource *source;

  task = g_object_new (G_TYPE_TASK, NULL);

  task->source_object = source_object ? g_object_ref (source_object) : NULL;

  task->cancellable = cancellable ? g_object_ref (cancellable) : NULL;

  task->callback = callback;

  task->callback_data = callback_data;

  task->context = g_main_context_ref_thread_default ();

  source = g_main_current_source ();

  if (source)

    task->creation_time = g_source_get_time (source);

  TRACE (GIO_TASK_NEW (task, source_object, cancellable,

                       callback, callback_data));

  return task;

}

/**

 * g_task_report_error:

 * @source_object: (nullable) (type GObject): the #GObject that owns

 *   this task, or %NULL.

 * @callback: (scope async): a #GAsyncReadyCallback.

 * @callback_data: (closure): user data passed to @callback.

 * @source_tag: an opaque pointer indicating the source of this task

 * @error: (transfer full): error to report

 *

 * 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

 */

void

g_task_report_error (gpointer             source_object,

                     GAsyncReadyCallback  callback,

                     gpointer             callback_data,

                     gpointer             source_tag,

                     GError              *error)

{

  GTask *task;

  task = g_task_new (source_object, NULL, callback, callback_data);

  g_task_set_source_tag (task, source_tag);

  g_task_return_error (task, error);

  g_object_unref (task);

}

/**

 * g_task_report_new_error:

 * @source_object: (nullable) (type GObject): the #GObject that owns

 *   this task, or %NULL.

 * @callback: (scope async): a #GAsyncReadyCallback.

 * @callback_data: (closure): user data passed to @callback.

 * @source_tag: an opaque pointer indicating the source of this task

 * @domain: a #GQuark.

 * @code: an error code.

 * @format: a string with format characters.

 * @...: a list of values to insert into @format.

 *

 * Creates a #GTask and then immediately calls

 * g_task_return_new_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_error().

 *

 * Since: 2.36

 */

void

g_task_report_new_error (gpointer             source_object,

                         GAsyncReadyCallback  callback,

                         gpointer             callback_data,

                         gpointer             source_tag,

                         GQuark               domain,

                         gint                 code,

                         const char          *format,

                         ...)

{

  GError *error;

  va_list ap;

  va_start (ap, format);

  error = g_error_new_valist (domain, code, format, ap);

  va_end (ap);

  g_task_report_error (source_object, callback, callback_data,

                       source_tag, error);

}

/**

 * g_task_set_task_data:

 * @task: the #GTask

 * @task_data: (nullable): task-specific data

 * @task_data_destroy: (nullable): #GDestroyNotify for @task_data

 *

 * Sets @task's task data (freeing the existing task data, if any).

 *

 * Since: 2.36

 */

void

g_task_set_task_data (GTask          *task,

                      gpointer        task_data,

                      GDestroyNotify  task_data_destroy)

{

  g_return_if_fail (G_IS_TASK (task));

  if (task->task_data_destroy)

    task->task_data_destroy (task->task_data);

  task->task_data = task_data;

  task->task_data_destroy = task_data_destroy;

  TRACE (GIO_TASK_SET_TASK_DATA (task, task_data, task_data_destroy));

}

/**

 * g_task_set_priority:

 * @task: the #GTask

 * @priority: the [priority][io-priority] of the request

 *

 * 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

 */

void

g_task_set_priority (GTask *task,

                     gint   priority)

{

  g_return_if_fail (G_IS_TASK (task));

  task->priority = priority;

  TRACE (GIO_TASK_SET_PRIORITY (task, priority));

}

/**

 * g_task_set_check_cancellable:

 * @task: the #GTask

 * @check_cancellable: whether #GTask will check the state of

 *   its #GCancellable for you.

 *

 * 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

 */

void

g_task_set_check_cancellable (GTask    *task,

                              gboolean  check_cancellable)

{

  g_return_if_fail (G_IS_TASK (task));

  g_return_if_fail (check_cancellable || !task->return_on_cancel);

  task->check_cancellable = check_cancellable;

}

static void g_task_thread_complete (GTask *task);

/**