gio/gtask.c

   1 /* GIO - GLib Input, Output and Streaming Library
   2  *
   3  * Copyright 2011 Red Hat, Inc.
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Lesser General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2 of the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Lesser General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Lesser General
  16  * Public License along with this library; if not, write to the
  17  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  18  * Boston, MA 02111-1307, USA.
  19  */
  20
  21 #include "config.h"
  22
  23 #include "gtask.h"
  24
  25 #include "gasyncresult.h"
  26 #include "gcancellable.h"
  27
  28 /**
  29  * SECTION:gtask
  30  * @short_description: Cancellable synchronous or asynchronous task and result
  31  * @include: gio/gio.h
  32  * @see_also: #GAsyncResult
  33  *
  34  * <para>
  35  *   A #GTask represents and manages a cancellable "task".
  36  * </para>
  37  * <refsect2>
  38  *   <title>Asynchronous operations</title>
  39  *   <para>
  40  *     The most common usage of #GTask is as a #GAsyncResult, to
  41  *     manage data during an asynchronous operation. You call
  42  *     g_task_new() in the "start" method, followed by
  43  *     g_task_set_task_data() and the like if you need to keep some
  44  *     additional data associated with the task, and then pass the
  45  *     task object around through your asynchronous operation.
  46  *     Eventually, you will call a method such as
  47  *     g_task_return_pointer() or g_task_return_error(), which will
  48  *     save the value you give it and then invoke the task's callback
  49  *     function (waiting until the next iteration of the main
  50  *     loop first, if necessary). The caller will pass the #GTask back
  51  *     to the operation's finish function (as a #GAsyncResult), and
  52  *     you can use g_task_propagate_pointer() or the like to extract
  53  *     the return value.
  54  *   </para>
  55  *   <example id="gtask-async"><title>GTask as a GAsyncResult</title>
  56  *   <programlisting>
  57  *     typedef struct {
  58  *       CakeFrostingType frosting;
  59  *       char *message;
  60  *     } DecorationData;
  61  *
  62  *     static void
  63  *     decoration_data_free (DecorationData *decoration)
  64  *     {
  65  *       g_free (decoration->message);
  66  *       g_slice_free (DecorationData, decoration);
  67  *     }
  68  *
  69  *     static void
  70  *     baked_cb (Cake     *cake,
  71  *               gpointer  user_data)
  72  *     {
  73  *       GTask *task = user_data;
  74  *       DecorationData *decoration = g_task_get_task_data (task);
  75  *       GError *error = NULL;
  76  *
  77  *       if (cake == NULL)
  78  *         {
  79  *           g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR,
  80  *                                    "Go to the supermarket");
  81  *           g_object_unref (task);
  82  *           return;
  83  *         }
  84  *
  85  *       if (!cake_decorate (cake, decoration->frosting, decoration->message, &error))
  86  *         {
  87  *           g_object_unref (cake);
  88  *           /&ast; g_task_return_error() takes ownership of error &ast;/
  89  *           g_task_return_error (task, error);
  90  *           g_object_unref (task);
  91  *           return;
  92  *         }
  93  *
  94  *       g_task_return_pointer (task, cake, g_object_unref);
  95  *       g_object_unref (task);
  96  *     }
  97  *
  98  *     void
  99  *     baker_bake_cake_async (Baker               *self,
 100  *                            guint                radius,
 101  *                            CakeFlavor           flavor,
 102  *                            CakeFrostingType     frosting,
 103  *                            const char          *message,
 104  *                            GCancellable        *cancellable,
 105  *                            GAsyncReadyCallback  callback,
 106  *                            gpointer             user_data)
 107  *     {
 108  *       GTask *task;
 109  *       DecorationData *decoration;
 110  *       Cake  *cake;
 111  *
 112  *       task = g_task_new (self, cancellable, callback, user_data);
 113  *       if (radius < 3)
 114  *         {
 115  *           g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_TOO_SMALL,
 116  *                                    "%ucm radius cakes are silly",
 117  *                                    radius);
 118  *           g_object_unref (task);
 119  *           return;
 120  *         }
 121  *
 122  *       cake = _baker_get_cached_cake (self, radius, flavor, frosting, message);
 123  *       if (cake != NULL)
 124  *         {
 125  *           /&ast; _baker_get_cached_cake() returns a reffed cake &ast;/
 126  *           g_task_return_pointer (task, cake, g_object_unref);
 127  *           g_object_unref (task);
 128  *           return;
 129  *         }
 130  *
 131  *       decoration = g_slice_new (DecorationData);
 132  *       decoration->frosting = frosting;
 133  *       decoration->message = g_strdup (message);
 134  *       g_task_set_task_data (task, decoration, (GDestroyNotify) decoration_data_free);
 135  *
 136  *       _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task);
 137  *     }
 138  *
 139  *     Cake *
 140  *     baker_bake_cake_finish (Baker         *self,
 141  *                             GAsyncResult  *result,
 142  *                             GError       **error)
 143  *     {
 144  *       g_return_val_if_fail (g_task_is_valid (result, self), NULL);
 145  *
 146  *       return g_task_propagate_pointer (G_TASK (result), error);
 147  *     }
 148  *   </programlisting>
 149  *   </example>
 150  * </refsect2>
 151  * <refsect2>
 152  *   <title>Chained asynchronous operations</title>
 153  *   <para>
 154  *     #GTask also tries to simplify asynchronous operations that
 155  *     internally chain together several smaller asynchronous
 156  *     operations. g_task_get_cancellable(), g_task_get_context(), and
 157  *     g_task_get_priority() allow you to get back the task's
 158  *     #GCancellable, #GMainContext, and <link
 159  *     linkend="io-priority">I/O priority</link> when starting a new
 160  *     subtask, so you don't have to keep track of them yourself.
 161  *     g_task_attach_source() simplifies the case of waiting for a
 162  *     source to fire (automatically using the correct #GMainContext
 163  *     and priority).
 164  *   </para>
 165  *   <example id="gtask-chained"><title>Chained asynchronous operations</title>
 166  *   <programlisting>
 167  *     typedef struct {
 168  *       Cake *cake;
 169  *       CakeFrostingType frosting;
 170  *       char *message;
 171  *     } BakingData;
 172  *
 173  *     static void
 174  *     decoration_data_free (BakingData *bd)
 175  *     {
 176  *       if (bd->cake)
 177  *         g_object_unref (bd->cake);
 178  *       g_free (bd->message);
 179  *       g_slice_free (BakingData, bd);
 180  *     }
 181  *
 182  *     static void
 183  *     decorated_cb (Cake         *cake,
 184  *                   GAsyncResult *result,
 185  *                   gpointer      user_data)
 186  *     {
 187  *       GTask *task = user_data;
 188  *       GError *error = NULL;
 189  *
 190  *       if (!cake_decorate_finish (cake, result, &error))
 191  *         {
 192  *           g_object_unref (cake);
 193  *           g_task_return_error (task, error);
 194  *           g_object_unref (task);
 195  *           return;
 196  *         }
 197  *
 198  *       /&ast; baking_data_free() will drop its ref on the cake, so
 199  *        &ast; we have to take another here to give to the caller.
 200  *        &ast;/
 201  *       g_task_return_pointer (result, g_object_ref (cake), g_object_unref);
 202  *       g_object_unref (task);
 203  *     }
 204  *
 205  *     static void
 206  *     decorator_ready (gpointer user_data)
 207  *     {
 208  *       GTask *task = user_data;
 209  *       BakingData *bd = g_task_get_task_data (task);
 210  *
 211  *       cake_decorate_async (bd->cake, bd->frosting, bd->message,
 212  *                            g_task_get_cancellable (task),
 213  *                            decorated_cb, task);
 214  *     }
 215  *
 216  *     static void
 217  *     baked_cb (Cake     *cake,
 218  *               gpointer  user_data)
 219  *     {
 220  *       GTask *task = user_data;
 221  *       BakingData *bd = g_task_get_task_data (task);
 222  *       GError *error = NULL;
 223  *
 224  *       if (cake == NULL)
 225  *         {
 226  *           g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR,
 227  *                                    "Go to the supermarket");
 228  *           g_object_unref (task);
 229  *           return;
 230  *         }
 231  *
 232  *       bd->cake = cake;
 233  *
 234  *       /&ast; Bail out now if the user has already cancelled &ast;/
 235  *       if (g_task_return_error_if_cancelled (g_task_get_cancellable (task)))
 236  *         {
 237  *           g_object_unref (task);
 238  *           return;
 239  *         }
 240  *
 241  *       if (cake_decorator_available (cake))
 242  *         decorator_ready (task);
 243  *       else
 244  *         {
 245  *           GSource *source;
 246  *
 247  *           source = cake_decorator_wait_source_new (cake);
 248  *           /&ast; Attach @source to @task's GMainContext and have it call
 249  *            &ast; decorator_ready() when it is ready.
 250  *            &ast;/
 251  *           g_task_attach_source (task, source,
 252  *                                 G_CALLBACK (decorator_ready));
 253  *           g_source_unref (source);
 254  *         }
 255  *     }
 256  *
 257  *     void
 258  *     baker_bake_cake_async (Baker               *self,
 259  *                            guint                radius,
 260  *                            CakeFlavor           flavor,
 261  *                            CakeFrostingType     frosting,
 262  *                            const char          *message,
 263  *                            gint                 priority,
 264  *                            GCancellable        *cancellable,
 265  *                            GAsyncReadyCallback  callback,
 266  *                            gpointer             user_data)
 267  *     {
 268  *       GTask *task;
 269  *       BakingData *bd;
 270  *
 271  *       task = g_task_new (self, cancellable, callback, user_data);
 272  *       g_task_set_priority (task, priority);
 273  *
 274  *       bd = g_slice_new0 (BakingData);
 275  *       bd->frosting = frosting;
 276  *       bd->message = g_strdup (message);
 277  *       g_task_set_task_data (task, bd, (GDestroyNotify) baking_data_free);
 278  *
 279  *       _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task);
 280  *     }
 281  *
 282  *     Cake *
 283  *     baker_bake_cake_finish (Baker         *self,
 284  *                             GAsyncResult  *result,
 285  *                             GError       **error)
 286  *     {
 287  *       g_return_val_if_fail (g_task_is_valid (result, self), NULL);
 288  *
 289  *       return g_task_propagate_pointer (G_TASK (result), error);
 290  *     }
 291  *   </programlisting>
 292  *   </example>
 293  * </refsect2>
 294  * <refsect2>
 295  *   <title>Asynchronous operations from synchronous ones</title>
 296  *   <para>
 297  *     You can use g_task_run_in_thread() to turn a synchronous
 298  *     operation into an asynchronous one, by running it in a thread
 299  *     which will then dispatch the result back to the caller's
 300  *     #GMainContext when it completes.
 301  *   </para>
 302  *   <example id="gtask-run-in-thread"><title>g_task_run_in_thread()</title>
 303  *   <programlisting>
 304  *     typedef struct {
 305  *       guint radius;
 306  *       CakeFlavor flavor;
 307  *       CakeFrostingType frosting;
 308  *       char *message;
 309  *     } CakeData;
 310  *
 311  *     static void
 312  *     cake_data_free (CakeData *cake_data)
 313  *     {
 314  *       g_free (cake_data->message);
 315  *       g_slice_free (CakeData, cake_data);
 316  *     }
 317  *
 318  *     static void
 319  *     bake_cake_thread (GTask         *task,
 320  *                       gpointer       source_object,
 321  *                       gpointer       task_data,
 322  *                       GCancellable  *cancellable)
 323  *     {
 324  *       Baker *self = source_object;
 325  *       CakeData *cake_data = task_data;
 326  *       Cake *cake;
 327  *       GError *error = NULL;
 328  *
 329  *       cake = bake_cake (baker, cake_data->radius, cake_data->flavor,
 330  *                         cake_data->frosting, cake_data->message,
 331  *                         cancellable, &error);
 332  *       if (cake)
 333  *         g_task_return_pointer (task, cake, g_object_unref);
 334  *       else
 335  *         g_task_return_error (task, error);
 336  *     }
 337  *
 338  *     void
 339  *     baker_bake_cake_async (Baker               *self,
 340  *                            guint                radius,
 341  *                            CakeFlavor           flavor,
 342  *                            CakeFrostingType     frosting,
 343  *                            const char          *message,
 344  *                            GCancellable        *cancellable,
 345  *                            GAsyncReadyCallback  callback,
 346  *                            gpointer             user_data)
 347  *     {
 348  *       CakeData *cake_data;
 349  *       GTask *task;
 350  *
 351  *       cake_data = g_slice_new (CakeData);
 352  *       cake_data->radius = radius;
 353  *       cake_data->flavor = flavor;
 354  *       cake_data->frosting = frosting;
 355  *       cake_data->message = g_strdup (message);
 356  *       task = g_task_new (self, cancellable, callback, user_data);
 357  *       g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
 358  *       g_task_run_in_thread (task, bake_cake_thread);
 359  *     }
 360  *
 361  *     Cake *
 362  *     baker_bake_cake_finish (Baker         *self,
 363  *                             GAsyncResult  *result,
 364  *                             GError       **error)
 365  *     {
 366  *       g_return_val_if_fail (g_task_is_valid (result, self), NULL);
 367  *
 368  *       return g_task_propagate_pointer (G_TASK (result), error);
 369  *     }
 370  *   </programlisting>
 371  *   </example>
 372  * </refsect2>
 373  * <refsect2>
 374  *   <title>Adding cancellability to uncancellable tasks</title>
 375  *   <para>
 376  *     Finally, g_task_run_in_thread() and g_task_run_in_thread_sync()
 377  *     can be used to turn an uncancellable operation into a
 378  *     cancellable one. If you call g_task_set_return_on_cancel(),
 379  *     passing %TRUE, then if the task's #GCancellable is cancelled,
 380  *     it will return control back to the caller immediately, while
 381  *     allowing the task thread to continue running in the background
 382  *     (and simply discarding its result when it finally does finish).
 383  *     Provided that the task thread is careful about how it uses
 384  *     locks and other externally-visible resources, this allows you
 385  *     to make "GLib-friendly" asynchronous and cancellable
 386  *     synchronous variants of blocking APIs.
 387  *   </para>
 388  *   <example id="gtask-cancellable"><title>g_task_set_return_on_cancel()</title>
 389  *   <programlisting>
 390  *     static void
 391  *     bake_cake_thread (GTask         *task,
 392  *                       gpointer       source_object,
 393  *                       gpointer       task_data,
 394  *                       GCancellable  *cancellable)
 395  *     {
 396  *       Baker *self = source_object;
 397  *       CakeData *cake_data = task_data;
 398  *       Cake *cake;
 399  *       GError *error = NULL;
 400  *
 401  *       cake = bake_cake (baker, cake_data->radius, cake_data->flavor,
 402  *                         cake_data->frosting, cake_data->message,
 403  *                         &error);
 404  *       if (error)
 405  *         {
 406  *           g_task_return_error (task, error);
 407  *           return;
 408  *         }
 409  *
 410  *       /&ast; If the task has already been cancelled, then we don't
 411  *        &ast; want to add the cake to the cake cache. Likewise, we don't
 412  *        &ast; want to have the task get cancelled in the middle of
 413  *        &ast; updating the cache. g_task_set_return_on_cancel() will
 414  *        &ast; return %TRUE here if it managed to disable return-on-cancel,
 415  *        &ast; or %FALSE if the task was cancelled before it could.
 416  *        &ast;/
 417  *       if (g_task_set_return_on_cancel (task, FALSE))
 418  *         {
 419  *           /&ast; If the caller cancels at this point, their
 420  *            &ast; GAsyncReadyCallback won't be invoked until we return,
 421  *            &ast; so we don't have to worry that this code will run at
 422  *            &ast; the same time as that code does. But if there were
 423  *            &ast; other functions that might look at the cake cache,
 424  *            &ast; then we'd probably need a GMutex here as well.
 425  *            &ast;/
 426  *           baker_add_cake_to_cache (baker, cake);
 427  *           g_task_return_pointer (task, cake, g_object_unref);
 428  *         }
 429  *     }
 430  *
 431  *     void
 432  *     baker_bake_cake_async (Baker               *self,
 433  *                            guint                radius,
 434  *                            CakeFlavor           flavor,
 435  *                            CakeFrostingType     frosting,
 436  *                            const char          *message,
 437  *                            GCancellable        *cancellable,
 438  *                            GAsyncReadyCallback  callback,
 439  *                            gpointer             user_data)
 440  *     {
 441  *       CakeData *cake_data;
 442  *       GTask *task;
 443  *
 444  *       cake_data = g_slice_new (CakeData);
 445  *       /&ast; ... &ast;/
 446  *
 447  *       task = g_task_new (self, cancellable, callback, user_data);
 448  *       g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
 449  *       g_task_set_return_on_cancel (task, TRUE);
 450  *       g_task_run_in_thread (task, bake_cake_thread);
 451  *     }
 452  *
 453  *     Cake *
 454  *     baker_bake_cake_sync (Baker               *self,
 455  *                           guint                radius,
 456  *                           CakeFlavor           flavor,
 457  *                           CakeFrostingType     frosting,
 458  *                           const char          *message,
 459  *                           GCancellable        *cancellable,
 460  *                           GError             **error)
 461  *     {
 462  *       CakeData *cake_data;
 463  *       GTask *task;
 464  *       Cake *cake;
 465  *
 466  *       cake_data = g_slice_new (CakeData);
 467  *       /&ast; ... &ast;/
 468  *
 469  *       task = g_task_new (self, cancellable, NULL, NULL);
 470  *       g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
 471  *       g_task_set_return_on_cancel (task, TRUE);
 472  *       g_task_run_in_thread_sync (task, bake_cake_thread);
 473  *
 474  *       cake = g_task_propagate_pointer (task, error);
 475  *       g_object_unref (task);
 476  *       return cake;
 477  *     }
 478  *   </programlisting>
 479  *   </example>
 480  * </refsect2>
 481  * <refsect2>
 482  *   <title>Porting from <literal>GSimpleAsyncResult</literal></title>
 483  *   <para>
 484  *     #GTask's API attempts to be simpler than #GSimpleAsyncResult's
 485  *     in several ways:
 486  *   </para>
 487  *   <itemizedlist>
 488  *     <listitem><para>
 489  *       You can save task-specific data with g_task_set_task_data(), and
 490  *       retrieve it later with g_task_get_task_data(). This replaces the
 491  *       abuse of g_simple_async_result_set_op_res_gpointer() for the same
 492  *       purpose with #GSimpleAsyncResult.
 493  *     </para></listitem>
 494  *     <listitem><para>
 495  *       In addition to the task data, #GTask also keeps track of the
 496  *       <link linkend="io-priority">priority</link>, #GCancellable, and
 497  *       #GMainContext associated with the task, so tasks that consist of
 498  *       a chain of simpler asynchronous operations will have easy access
 499  *       to those values when starting each sub-task.
 500  *     </para></listitem>
 501  *     <listitem><para>
 502  *       g_task_return_error_if_cancelled() provides simplified
 503  *       handling for cancellation. In addition, cancellation
 504  *       overrides any other #GTask return value by default, like
 505  *       #GSimpleAsyncResult does when
 506  *       g_simple_async_result_set_check_cancellable() is called.
 507  *       (You can use g_task_set_check_cancellable() to turn off that
 508  *       behavior.) On the other hand, g_task_run_in_thread()
 509  *       guarantees that it will always run your
 510  *       <literal>task_func</literal>, even if the task's #GCancellable
 511  *       is already cancelled before the task gets a chance to run;
 512  *       you can start your <literal>task_func</literal> with a
 513  *       g_task_return_error_if_cancelled() check if you need the
 514  *       old behavior.
 515  *     </para></listitem>
 516  *     <listitem><para>
 517  *       The "return" methods (eg, g_task_return_pointer())
 518  *       automatically cause the task to be "completed" as well, and
 519  *       there is no need to worry about the "complete" vs "complete
 520  *       in idle" distinction. (#GTask automatically figures out
 521  *       whether the task's callback can be invoked directly, or
 522  *       if it needs to be sent to another #GMainContext, or delayed
 523  *       until the next iteration of the current #GMainContext.)
 524  *     </para></listitem>
 525  *     <listitem><para>
 526  *       The "finish" functions for #GTask-based operations are generally
 527  *       much simpler than #GSimpleAsyncResult ones, normally consisting
 528  *       of only a single call to g_task_propagate_pointer() or the like.
 529  *       Since g_task_propagate_pointer() "steals" the return value from
 530  *       the #GTask, it is not necessary to juggle pointers around to
 531  *       prevent it from being freed twice.
 532  *     </para></listitem>
 533  *     <listitem><para>
 534  *       With #GSimpleAsyncResult, it was common to call
 535  *       g_simple_async_result_propagate_error() from the
 536  *       <literal>_finish()</literal> wrapper function, and have
 537  *       virtual method implementations only deal with successful
 538  *       returns. This behavior is deprecated, because it makes it
 539  *       difficult for a subclass to chain to a parent class's async
 540  *       methods. Instead, the wrapper function should just be a
 541  *       simple wrapper, and the virtual method should call an
 542  *       appropriate <literal>g_task_propagate_</literal> function.
 543  *       Note that wrapper methods can now use
 544  *       g_async_result_legacy_propagate_error() to do old-style
 545  *       #GSimpleAsyncResult error-returning behavior, and
 546  *       g_async_result_is_tagged() to check if a result is tagged as
 547  *       having come from the <literal>_async()</literal> wrapper
 548  *       function (for "short-circuit" results, such as when passing
 549  *       0 to g_input_stream_read_async()).
 550  *     </para></listitem>
 551  *   </itemizedlist>
 552  * </refsect2>
 553  */
 554
 555 /**
 556  * GTask:
 557  *
 558  * The opaque object representing a synchronous or asynchronous task
 559  * and its result.
 560  */
 561
 562 struct _GTask {
 563   GObject parent_instance;
 564
 565   gpointer source_object;
 566   gpointer source_tag;
 567
 568   gpointer task_data;
 569   GDestroyNotify task_data_destroy;
 570
 571   GMainContext *context;
 572   guint64 creation_time;
 573   gint priority;
 574   GCancellable *cancellable;
 575   gboolean check_cancellable;
 576
 577   GAsyncReadyCallback callback;
 578   gpointer callback_data;
 579
 580   GTaskThreadFunc task_func;
 581   GMutex lock;
 582   GCond cond;
 583   gboolean return_on_cancel;
 584   gboolean thread_cancelled;
 585   gboolean synchronous;
 586   gboolean thread_complete;
 587   gboolean blocking_other_task;
 588
 589   GError *error;
 590   union {
 591     gpointer pointer;
 592     gssize   size;
 593     gboolean boolean;
 594   } result;
 595   GDestroyNotify result_destroy;
 596   gboolean result_set;
 597 };
 598
 599 #define G_TASK_IS_THREADED(task) ((task)->task_func != NULL)
 600
 601 struct _GTaskClass
 602 {
 603   GObjectClass parent_class;
 604 };
 605
 606 static void g_task_thread_pool_resort (void);
 607
 608 static void g_task_async_result_iface_init (GAsyncResultIface *iface);
 609 static void g_task_thread_pool_init (void);
 610
 611 G_DEFINE_TYPE_WITH_CODE (GTask, g_task, G_TYPE_OBJECT,
 612                          G_IMPLEMENT_INTERFACE (G_TYPE_ASYNC_RESULT,
 613                                                 g_task_async_result_iface_init);
 614                          g_task_thread_pool_init ();)
 615
 616 static GThreadPool *task_pool;
 617 static GMutex task_pool_mutex;
 618 static GPrivate task_private = G_PRIVATE_INIT (NULL);
 619
 620 static void
 621 g_task_init (GTask *task)
 622 {
 623   task->check_cancellable = TRUE;
 624 }
 625
 626 static void
 627 g_task_finalize (GObject *object)
 628 {
 629   GTask *task = G_TASK (object);
 630
 631   g_clear_object (&task->source_object);
 632   g_clear_object (&task->cancellable);
 633
 634   if (task->context)
 635     g_main_context_unref (task->context);
 636
 637   if (task->task_data_destroy)
 638     task->task_data_destroy (task->task_data);
 639
 640   if (task->result_destroy && task->result.pointer)
 641     task->result_destroy (task->result.pointer);
 642
 643   if (task->error)
 644       g_error_free (task->error);
 645
 646   if (G_TASK_IS_THREADED (task))
 647     {
 648       g_mutex_clear (&task->lock);
 649       g_cond_clear (&task->cond);
 650     }
 651
 652   G_OBJECT_CLASS (g_task_parent_class)->finalize (object);
 653 }
 654
 655 /**
 656  * g_task_new:
 657  * @source_object: (allow-none) (type GObject): the #GObject that owns
 658  *   this task, or %NULL.
 659  * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
 660  * @callback: (scope async): a #GAsyncReadyCallback.
 661  * @callback_data: (closure): user data passed to @callback.
 662  *
 663  * Creates a #GTask acting on @source_object, which will eventually be
 664  * used to invoke @callback in the current <link
 665  * linkend="g-main-context-push-thread-default">thread-default main
 666  * context</link>.
 667  *
 668  * Call this in the "start" method of your asynchronous method, and
 669  * pass the #GTask around throughout the asynchronous operation. You
 670  * can use g_task_set_task_data() to attach task-specific data to the
 671  * object, which you can retrieve later via g_task_get_task_data().
 672  *
 673  * By default, if @cancellable is cancelled, then the return value of
 674  * the task will always be %G_IO_ERROR_CANCELLED, even if the task had
 675  * already completed before the cancellation. This allows for
 676  * simplified handling in cases where cancellation may imply that
 677  * other objects that the task depends on have been destroyed. If you
 678  * do not want this behavior, you can use
 679  * g_task_set_check_cancellable() to change it.
 680  *
 681  * Returns: a #GTask.
 682  *
 683  * Since: 2.36
 684  */
 685 GTask *
 686 g_task_new (gpointer              source_object,
 687             GCancellable         *cancellable,
 688             GAsyncReadyCallback   callback,
 689             gpointer              callback_data)
 690 {
 691   GTask *task;
 692   GSource *source;
 693
 694   task = g_object_new (G_TYPE_TASK, NULL);
 695   task->source_object = source_object ? g_object_ref (source_object) : NULL;
 696   task->cancellable = cancellable ? g_object_ref (cancellable) : NULL;
 697   task->callback = callback;
 698   task->callback_data = callback_data;
 699   task->context = g_main_context_ref_thread_default ();
 700
 701   source = g_main_current_source ();
 702   if (source)
 703     task->creation_time = g_source_get_time (source);
 704
 705   return task;
 706 }
 707
 708 /**
 709  * g_task_report_error:
 710  * @source_object: (allow-none) (type GObject): the #GObject that owns
 711  *   this task, or %NULL.
 712  * @callback: (scope async): a #GAsyncReadyCallback.
 713  * @callback_data: (closure): user data passed to @callback.
 714  * @source_tag: an opaque pointer indicating the source of this task
 715  * @error: (transfer full): error to report
 716  *
 717  * Creates a #GTask and then immediately calls g_task_return_error()
 718  * on it. Use this in the wrapper function of an asynchronous method
 719  * when you want to avoid even calling the virtual method. You can
 720  * then use g_async_result_is_tagged() in the finish method wrapper to
 721  * check if the result there is tagged as having been created by the
 722  * wrapper method, and deal with it appropriately if so.
 723  *
 724  * See also g_task_report_new_error().
 725  *
 726  * Since: 2.36
 727  */
 728 void
 729 g_task_report_error (gpointer             source_object,
 730                      GAsyncReadyCallback  callback,
 731                      gpointer             callback_data,
 732                      gpointer             source_tag,
 733                      GError              *error)
 734 {
 735   GTask *task;
 736
 737   task = g_task_new (source_object, NULL, callback, callback_data);
 738   g_task_set_source_tag (task, source_tag);
 739   g_task_return_error (task, error);
 740   g_object_unref (task);
 741 }
 742
 743 /**
 744  * g_task_report_new_error:
 745  * @source_object: (allow-none) (type GObject): the #GObject that owns
 746  *   this task, or %NULL.
 747  * @callback: (scope async): a #GAsyncReadyCallback.
 748  * @callback_data: (closure): user data passed to @callback.
 749  * @source_tag: an opaque pointer indicating the source of this task
 750  * @domain: a #GQuark.
 751  * @code: an error code.
 752  * @format: a string with format characters.
 753  * @...: a list of values to insert into @format.
 754  *
 755  * Creates a #GTask and then immediately calls
 756  * g_task_return_new_error() on it. Use this in the wrapper function
 757  * of an asynchronous method when you want to avoid even calling the
 758  * virtual method. You can then use g_async_result_is_tagged() in the
 759  * finish method wrapper to check if the result there is tagged as
 760  * having been created by the wrapper method, and deal with it
 761  * appropriately if so.
 762  *
 763  * See also g_task_report_error().
 764  *
 765  * Since: 2.36
 766  */
 767 void
 768 g_task_report_new_error (gpointer             source_object,
 769                          GAsyncReadyCallback  callback,
 770                          gpointer             callback_data,
 771                          gpointer             source_tag,
 772                          GQuark               domain,
 773                          gint                 code,
 774                          const char          *format,
 775                          ...)
 776 {
 777   GError *error;
 778   va_list ap;
 779
 780   va_start (ap, format);
 781   error = g_error_new_valist (domain, code, format, ap);
 782   va_end (ap);
 783
 784   g_task_report_error (source_object, callback, callback_data,
 785                        source_tag, error);
 786 }
 787
 788 /**
 789  * g_task_set_task_data:
 790  * @task: the #GTask
 791  * @task_data: (allow-none): task-specific data
 792  * @task_data_destroy: (allow-none): #GDestroyNotify for @task_data
 793  *
 794  * Sets @task's task data (freeing the existing task data, if any).
 795  *
 796  * Since: 2.36
 797  */
 798 void
 799 g_task_set_task_data (GTask          *task,
 800                       gpointer        task_data,
 801                       GDestroyNotify  task_data_destroy)
 802 {
 803   if (task->task_data_destroy)
 804     task->task_data_destroy (task->task_data);
 805
 806   task->task_data = task_data;
 807   task->task_data_destroy = task_data_destroy;
 808 }
 809
 810 /**
 811  * g_task_set_priority:
 812  * @task: the #GTask
 813  * @priority: the <link linkend="io-priority">priority</link>
 814  *   of the request.
 815  *
 816  * Sets @task's priority. If you do not call this, it will default to
 817  * %G_PRIORITY_DEFAULT.
 818  *
 819  * This will affect the priority of #GSources created with
 820  * g_task_attach_source() and the scheduling of tasks run in threads,
 821  * and can also be explicitly retrieved later via
 822  * g_task_get_priority().
 823  *
 824  * Since: 2.36
 825  */
 826 void
 827 g_task_set_priority (GTask *task,
 828                      gint   priority)
 829 {
 830   task->priority = priority;
 831 }
 832
 833 /**
 834  * g_task_set_check_cancellable:
 835  * @task: the #GTask
 836  * @check_cancellable: whether #GTask will check the state of
 837  *   its #GCancellable for you.
 838  *
 839  * Sets or clears @task's check-cancellable flag. If this is %TRUE
 840  * (the default), then g_task_propagate_pointer(), etc, and
 841  * g_task_had_error() will check the task's #GCancellable first, and
 842  * if it has been cancelled, then they will consider the task to have
 843  * returned an "Operation was cancelled" error
 844  * (%G_IO_ERROR_CANCELLED), regardless of any other error or return
 845  * value the task may have had.
 846  *
 847  * If @check_cancellable is %FALSE, then the #GTask will not check the
 848  * cancellable itself, and it is up to @task's owner to do this (eg,
 849  * via g_task_return_error_if_cancelled()).
 850  *
 851  * If you are using g_task_set_return_on_cancel() as well, then
 852  * you must leave check-cancellable set %TRUE.
 853  *
 854  * Since: 2.36
 855  */
 856 void
 857 g_task_set_check_cancellable (GTask    *task,
 858                               gboolean  check_cancellable)
 859 {
 860   g_return_if_fail (check_cancellable || !task->return_on_cancel);
 861
 862   task->check_cancellable = check_cancellable;
 863 }
 864
 865 static void g_task_thread_complete (GTask *task);
 866
 867 /**
 868  * g_task_set_return_on_cancel:
 869  * @task: the #GTask
 870  * @return_on_cancel: whether the task returns automatically when
 871  *   it is cancelled.
 872  *
 873  * Sets or clears @task's return-on-cancel flag. This is only
 874  * meaningful for tasks run via g_task_run_in_thread() or
 875  * g_task_run_in_thread_sync().
 876  *
 877  * If @return_on_cancel is %TRUE, then cancelling @task's
 878  * #GCancellable will immediately cause it to return, as though the
 879  * task's #GTaskThreadFunc had called
 880  * g_task_return_error_if_cancelled() and then returned.
 881  *
 882  * This allows you to create a cancellable wrapper around an
 883  * uninterruptable function. The #GTaskThreadFunc just needs to be
 884  * careful that it does not modify any externally-visible state after
 885  * it has been cancelled. To do that, the thread should call
 886  * g_task_set_return_on_cancel() again to (atomically) set
 887  * return-on-cancel %FALSE before making externally-visible changes;
 888  * if the task gets cancelled before the return-on-cancel flag could
 889  * be changed, g_task_set_return_on_cancel() will indicate this by
 890  * returning %FALSE.
 891  *
 892  * You can disable and re-enable this flag multiple times if you wish.
 893  * If the task's #GCancellable is cancelled while return-on-cancel is
 894  * %FALSE, then calling g_task_set_return_on_cancel() to set it %TRUE
 895  * again will cause the task to be cancelled at that point.
 896  *
 897  * If the task's #GCancellable is already cancelled before you call
 898  * g_task_run_in_thread()/g_task_run_in_thread_sync(), then the
 899  * #GTaskThreadFunc will still be run (for consistency), but the task
 900  * will also be completed right away.
 901  *
 902  * Returns: %TRUE if @task's return-on-cancel flag was changed to
 903  *   match @return_on_cancel. %FALSE if @task has already been
 904  *   cancelled.
 905  *
 906  * Since: 2.36
 907  */
 908 gboolean
 909 g_task_set_return_on_cancel (GTask    *task,
 910                              gboolean  return_on_cancel)
 911 {
 912   g_return_val_if_fail (task->check_cancellable || !return_on_cancel, FALSE);
 913
 914   if (!G_TASK_IS_THREADED (task))
 915     {
 916       task->return_on_cancel = return_on_cancel;
 917       return TRUE;
 918     }
 919
 920   g_mutex_lock (&task->lock);
 921   if (task->thread_cancelled)
 922     {
 923       if (return_on_cancel && !task->return_on_cancel)
 924         {
 925           g_mutex_unlock (&task->lock);
 926           g_task_thread_complete (task);
 927         }
 928       else
 929         g_mutex_unlock (&task->lock);
 930       return FALSE;
 931     }
 932   task->return_on_cancel = return_on_cancel;
 933   g_mutex_unlock (&task->lock);
 934
 935   return TRUE;
 936 }
 937
 938 /**
 939  * g_task_set_source_tag:
 940  * @task: the #GTask
 941  * @source_tag: an opaque pointer indicating the source of this task
 942  *
 943  * Sets @task's source tag. You can use this to tag a task return
 944  * value with a particular pointer (usually a pointer to the function
 945  * doing the tagging) and then later check it using
 946  * g_task_get_source_tag() (or g_async_result_is_tagged()) in the
 947  * task's "finish" function, to figure out if the response came from a
 948  * particular place.
 949  *
 950  * Since: 2.36
 951  */
 952 void
 953 g_task_set_source_tag (GTask    *task,
 954                        gpointer  source_tag)
 955 {
 956   task->source_tag = source_tag;
 957 }
 958
 959 /**
 960  * g_task_get_source_object:
 961  * @task: a #GTask
 962  *
 963  * Gets the source object from @task. Like
 964  * g_async_result_get_source_object(), but does not ref the object.
 965  *
 966  * Returns: (transfer none) (type GObject): @task's source object, or %NULL
 967  *
 968  * Since: 2.36
 969  */
 970 gpointer
 971 g_task_get_source_object (GTask *task)
 972 {
 973   return task->source_object;
 974 }
 975
 976 static GObject *
 977 g_task_ref_source_object (GAsyncResult *res)
 978 {
 979   GTask *task = G_TASK (res);
 980
 981   if (task->source_object)
 982     return g_object_ref (task->source_object);
 983   else
 984     return NULL;
 985 }
 986
 987 /**
 988  * g_task_get_task_data:
 989  * @task: a #GTask
 990  *
 991  * Gets @task's <literal>task_data</literal>.
 992  *
 993  * Returns: (transfer none): @task's <literal>task_data</literal>.
 994  *
 995  * Since: 2.36
 996  */
 997 gpointer
 998 g_task_get_task_data (GTask *task)
 999 {
1000   return task->task_data;
1001 }
1002
1003 /**
1004  * g_task_get_priority:
1005  * @task: a #GTask
1006  *
1007  * Gets @task's priority
1008  *
1009  * Returns: @task's priority
1010  *
1011  * Since: 2.36
1012  */
1013 gint
1014 g_task_get_priority (GTask *task)
1015 {
1016   return task->priority;
1017 }
1018
1019 /**
1020  * g_task_get_context:
1021  * @task: a #GTask
1022  *
1023  * Gets the #GMainContext that @task will return its result in (that
1024  * is, the context that was the <link
1025  * linkend="g-main-context-push-thread-default">thread-default main
1026  * context</link> at the point when @task was created).
1027  *
1028  * This will always return a non-%NULL value, even if the task's
1029  * context is the default #GMainContext.
1030  *
1031  * Returns: (transfer none): @task's #GMainContext
1032  *
1033  * Since: 2.36
1034  */
1035 GMainContext *
1036 g_task_get_context (GTask *task)
1037 {
1038   return task->context;
1039 }
1040
1041 /**
1042  * g_task_get_cancellable:
1043  * @task: a #GTask
1044  *
1045  * Gets @task's #GCancellable
1046  *
1047  * Returns: (transfer none): @task's #GCancellable
1048  *
1049  * Since: 2.36
1050  */
1051 GCancellable *
1052 g_task_get_cancellable (GTask *task)
1053 {
1054   return task->cancellable;
1055 }
1056
1057 /**
1058  * g_task_get_check_cancellable:
1059  * @task: the #GTask
1060  *
1061  * Gets @task's check-cancellable flag. See
1062  * g_task_set_check_cancellable() for more details.
1063  *
1064  * Since: 2.36
1065  */
1066 gboolean
1067 g_task_get_check_cancellable (GTask *task)
1068 {
1069   return task->check_cancellable;
1070 }
1071
1072 /**
1073  * g_task_get_return_on_cancel:
1074  * @task: the #GTask
1075  *
1076  * Gets @task's return-on-cancel flag. See
1077  * g_task_set_return_on_cancel() for more details.
1078  *
1079  * Since: 2.36
1080  */
1081 gboolean
1082 g_task_get_return_on_cancel (GTask *task)
1083 {
1084   return task->return_on_cancel;
1085 }
1086
1087 /**
1088  * g_task_get_source_tag:
1089  * @task: a #GTask
1090  *
1091  * Gets @task's source tag. See g_task_set_source_tag().
1092  *
1093  * Return value: (transfer none): @task's source tag
1094  *
1095  * Since: 2.36
1096  */
1097 gpointer
1098 g_task_get_source_tag (GTask *task)
1099 {
1100   return task->source_tag;
1101 }
1102
1103
1104 static void
1105 g_task_return_now (GTask *task)
1106 {
1107   g_main_context_push_thread_default (task->context);
1108   task->callback (task->source_object,
1109                   G_ASYNC_RESULT (task),
1110                   task->callback_data);
1111   g_main_context_pop_thread_default (task->context);
1112 }
1113
1114 static gboolean
1115 complete_in_idle_cb (gpointer task)
1116 {
1117   g_task_return_now (task);
1118   g_object_unref (task);
1119   return FALSE;
1120 }
1121
1122 typedef enum {
1123   G_TASK_RETURN_SUCCESS,
1124   G_TASK_RETURN_ERROR,
1125   G_TASK_RETURN_FROM_THREAD
1126 } GTaskReturnType;
1127
1128 static void
1129 g_task_return (GTask           *task,
1130                GTaskReturnType  type)
1131 {
1132   GSource *source;
1133
1134   if (type == G_TASK_RETURN_SUCCESS)
1135     task->result_set = TRUE;
1136
1137   if (task->synchronous || !task->callback)
1138     return;
1139
1140   /* Normally we want to invoke the task's callback when its return
1141    * value is set. But if the task is running in a thread, then we
1142    * want to wait until after the task_func returns, to simplify
1143    * locking/refcounting/etc.
1144    */
1145   if (G_TASK_IS_THREADED (task) && type != G_TASK_RETURN_FROM_THREAD)
1146     return;
1147
1148   g_object_ref (task);
1149
1150   /* See if we can complete the task immediately. First, we have to be
1151    * running inside the task's thread/GMainContext.
1152    */
1153   source = g_main_current_source ();
1154   if (source && g_source_get_context (source) == task->context)
1155     {
1156       /* Second, we can only complete immediately if this is not the
1157        * same iteration of the main loop that the task was created in.
1158        */
1159       if (g_source_get_time (source) > task->creation_time)
1160         {
1161           g_task_return_now (task);
1162           g_object_unref (task);
1163           return;
1164         }
1165     }
1166
1167   /* Otherwise, complete in the next iteration */
1168   source = g_idle_source_new ();
1169   g_task_attach_source (task, source, complete_in_idle_cb);
1170   g_source_unref (source);
1171 }
1172
1173
1174 /**
1175  * GTaskThreadFunc:
1176  * @task: the #GTask
1177  * @source_object: (type GObject): @task's source object
1178  * @task_data: @task's task data
1179  * @cancellable: @task's #GCancellable, or %NULL
1180  *
1181  * The prototype for a task function to be run in a thread via
1182  * g_task_run_in_thread() or g_task_run_in_thread_sync().
1183  *
1184  * If the return-on-cancel flag is set on @task, and @cancellable gets
1185  * cancelled, then the #GTask will be completed immediately (as though
1186  * g_task_return_error_if_cancelled() had been called), without
1187  * waiting for the task function to complete. However, the task
1188  * function will continue running in its thread in the background. The
1189  * function therefore needs to be careful about how it uses
1190  * externally-visible state in this case. See
1191  * g_task_set_return_on_cancel() for more details.
1192  *
1193  * Other than in that case, @task will be completed when the
1194  * #GTaskThreadFunc returns, <emphasis>not</emphasis> when it calls
1195  * a <literal>g_task_return_</literal> function.
1196  *
1197  * Since: 2.36
1198  */
1199
1200 static void task_thread_cancelled (GCancellable *cancellable,
1201                                    gpointer      user_data);
1202
1203 static void
1204 g_task_thread_complete (GTask *task)
1205 {
1206   g_mutex_lock (&task->lock);
1207   if (task->thread_complete)
1208     {
1209       /* The task belatedly completed after having been cancelled
1210        * (or was cancelled in the midst of being completed).
1211        */
1212       g_mutex_unlock (&task->lock);
1213       return;
1214     }
1215
1216   task->thread_complete = TRUE;
1217
1218   if (task->blocking_other_task)
1219     {
1220       g_mutex_lock (&task_pool_mutex);
1221       g_thread_pool_set_max_threads (task_pool,
1222                                      g_thread_pool_get_max_threads (task_pool) - 1,
1223                                      NULL);
1224       g_mutex_unlock (&task_pool_mutex);
1225     }
1226   g_mutex_unlock (&task->lock);
1227
1228   if (task->cancellable)
1229     g_signal_handlers_disconnect_by_func (task->cancellable, task_thread_cancelled, task);
1230
1231   if (task->synchronous)
1232     g_cond_signal (&task->cond);
1233   else
1234     g_task_return (task, G_TASK_RETURN_FROM_THREAD);
1235 }
1236
1237 static void
1238 g_task_thread_pool_thread (gpointer thread_data,
1239                            gpointer pool_data)
1240 {
1241   GTask *task = thread_data;
1242
1243   g_private_set (&task_private, task);
1244
1245   task->task_func (task, task->source_object, task->task_data,
1246                    task->cancellable);
1247   g_task_thread_complete (task);
1248
1249   g_private_set (&task_private, NULL);
1250   g_object_unref (task);
1251 }
1252
1253 static void
1254 task_thread_cancelled (GCancellable *cancellable,
1255                        gpointer      user_data)
1256 {
1257   GTask *task = user_data;
1258
1259   g_task_thread_pool_resort ();
1260
1261   g_mutex_lock (&task->lock);
1262   task->thread_cancelled = TRUE;
1263
1264   if (!task->return_on_cancel)
1265     {
1266       g_mutex_unlock (&task->lock);
1267       return;
1268     }
1269
1270   /* We don't actually set task->error; g_task_return_error() doesn't
1271    * use a lock, and g_task_propagate_error() will call
1272    * g_cancellable_set_error_if_cancelled() anyway.
1273    */
1274   g_mutex_unlock (&task->lock);
1275   g_task_thread_complete (task);
1276 }
1277
1278 static void
1279 task_thread_cancelled_disconnect_notify (gpointer  task,
1280                                          GClosure *closure)
1281 {
1282   g_object_unref (task);
1283 }
1284
1285 static void
1286 g_task_start_task_thread (GTask           *task,
1287                           GTaskThreadFunc  task_func)
1288 {
1289   g_mutex_init (&task->lock);
1290   g_cond_init (&task->cond);
1291
1292   g_mutex_lock (&task->lock);
1293
1294   task->task_func = task_func;
1295
1296   if (task->cancellable)
1297     {
1298       if (task->return_on_cancel &&
1299           g_cancellable_set_error_if_cancelled (task->cancellable,
1300                                                 &task->error))
1301         {
1302           task->thread_cancelled = task->thread_complete = TRUE;
1303           g_thread_pool_push (task_pool, g_object_ref (task), NULL);
1304           return;
1305         }
1306
1307       g_signal_connect_data (task->cancellable, "cancelled",
1308                              G_CALLBACK (task_thread_cancelled),
1309                              g_object_ref (task),
1310                              task_thread_cancelled_disconnect_notify, 0);
1311     }
1312
1313   g_thread_pool_push (task_pool, g_object_ref (task), &task->error);
1314   if (task->error)
1315     task->thread_complete = TRUE;
1316   else if (g_private_get (&task_private))
1317     {
1318       /* This thread is being spawned from another GTask thread, so
1319        * bump up max-threads so we don't starve.
1320        */
1321       g_mutex_lock (&task_pool_mutex);
1322       if (g_thread_pool_set_max_threads (task_pool,
1323                                          g_thread_pool_get_max_threads (task_pool) + 1,
1324                                          NULL))
1325         task->blocking_other_task = TRUE;
1326       g_mutex_unlock (&task_pool_mutex);
1327     }
1328 }
1329
1330 /**
1331  * g_task_run_in_thread:
1332  * @task: a #GTask
1333  * @task_func: a #GTaskThreadFunc
1334  *
1335  * Runs @task_func in another thread. When @task_func returns, @task's
1336  * #GAsyncReadyCallback will be invoked in @task's #GMainContext.
1337  *
1338  * This takes a ref on @task until the task completes.
1339  *
1340  * See #GTaskThreadFunc for more details about how @task_func is handled.
1341  *
1342  * Since: 2.36
1343  */
1344 void
1345 g_task_run_in_thread (GTask           *task,
1346                       GTaskThreadFunc  task_func)
1347 {
1348   g_return_if_fail (G_IS_TASK (task));
1349
1350   g_object_ref (task);
1351   g_task_start_task_thread (task, task_func);
1352
1353   /* The task may already be cancelled, or g_thread_pool_push() may
1354    * have failed.
1355    */
1356   if (task->thread_complete)
1357     {
1358       g_mutex_unlock (&task->lock);
1359       g_task_return (task, G_TASK_RETURN_FROM_THREAD);
1360     }
1361   else
1362     g_mutex_unlock (&task->lock);
1363
1364   g_object_unref (task);
1365 }
1366
1367 /**
1368  * g_task_run_in_thread_sync:
1369  * @task: a #GTask
1370  * @task_func: a #GTaskThreadFunc
1371  *
1372  * Runs @task_func in another thread, and waits for it to return or be
1373  * cancelled. You can use g_task_propagate_pointer(), etc, afterward
1374  * to get the result of @task_func.
1375  *
1376  * See #GTaskThreadFunc for more details about how @task_func is handled.
1377  *
1378  * Normally this is used with tasks created with a %NULL
1379  * <literal>callback</literal>, but note that even if the task does
1380  * have a callback, it will not be invoked when @task_func returns.
1381  *
1382  * Since: 2.36
1383  */
1384 void
1385 g_task_run_in_thread_sync (GTask           *task,
1386                            GTaskThreadFunc  task_func)
1387 {
1388   g_return_if_fail (G_IS_TASK (task));
1389
1390   g_object_ref (task);
1391
1392   task->synchronous = TRUE;
1393   g_task_start_task_thread (task, task_func);
1394
1395   while (!task->thread_complete)
1396     g_cond_wait (&task->cond, &task->lock);
1397
1398   g_mutex_unlock (&task->lock);
1399   g_object_unref (task);
1400 }
1401
1402 /**
1403  * g_task_attach_source:
1404  * @task: a #GTask
1405  * @source: the source to attach
1406  * @callback: the callback to invoke when @source triggers
1407  *
1408  * A utility function for dealing with async operations where you need
1409  * to wait for a #GSource to trigger. Attaches @source to @task's
1410  * #GMainContext with @task's <link
1411  * linkend="io-priority">priority</link>, and sets @source's callback
1412  * to @callback, with @task as the callback's
1413  * <literal>user_data</literal>.
1414  *
1415  * This takes a reference on @task until @source is destroyed.
1416  *
1417  * Since: 2.36
1418  */
1419 void
1420 g_task_attach_source (GTask       *task,
1421                       GSource     *source,
1422                       GSourceFunc  callback)
1423 {
1424   g_source_set_callback (source, callback,
1425                          g_object_ref (task), g_object_unref);
1426   g_source_set_priority (source, task->priority);
1427   g_source_attach (source, task->context);
1428 }
1429
1430
1431 static gboolean
1432 g_task_propagate_error (GTask   *task,
1433                         GError **error)
1434 {
1435   if (task->check_cancellable &&
1436       g_cancellable_set_error_if_cancelled (task->cancellable, error))
1437     return TRUE;
1438   else if (task->error)
1439     {
1440       g_propagate_error (error, task->error);
1441       task->error = NULL;
1442       return TRUE;
1443     }
1444   else
1445     return FALSE;
1446 }
1447
1448 /**
1449  * g_task_return_pointer:
1450  * @task: a #GTask
1451  * @result: (allow-none) (transfer full): the pointer result of a task
1452  *     function
1453  * @result_destroy: (allow-none): a #GDestroyNotify function.
1454  *
1455  * Sets @task's result to @result and completes the task. If @result
1456  * is not %NULL, then @result_destroy will be used to free @result if
1457  * the caller does not take ownership of it with
1458  * g_task_propagate_pointer().
1459  *
1460  * "Completes the task" means that for an ordinary asynchronous task
1461  * it will either invoke the task's callback, or else queue that
1462  * callback to be invoked in the proper #GMainContext, or in the next
1463  * iteration of the current #GMainContext. For a task run via
1464  * g_task_run_in_thread() or g_task_run_in_thread_sync(), calling this
1465  * method will save @result to be returned to the caller later, but
1466  * the task will not actually be completed until the #GTaskThreadFunc
1467  * exits.
1468  *
1469  * Note that since the task may be completed before returning from
1470  * g_task_return_pointer(), you cannot assume that @result is still
1471  * valid after calling this, unless you are still holding another
1472  * reference on it.
1473  *
1474  * Since: 2.36
1475  */
1476 void
1477 g_task_return_pointer (GTask          *task,
1478                        gpointer        result,
1479                        GDestroyNotify  result_destroy)
1480 {
1481   g_return_if_fail (task->result_set == FALSE);
1482
1483   task->result.pointer = result;
1484   task->result_destroy = result_destroy;
1485
1486   g_task_return (task, G_TASK_RETURN_SUCCESS);
1487 }
1488
1489 /**
1490  * g_task_propagate_pointer:
1491  * @task: a #GTask
1492  * @error: return location for a #GError
1493  *
1494  * Gets the result of @task as a pointer, and transfers ownership
1495  * of that value to the caller.
1496  *
1497  * If the task resulted in an error, or was cancelled, then this will
1498  * instead return %NULL and set @error.
1499  *
1500  * Since this method transfers ownership of the return value (or
1501  * error) to the caller, you may only call it once.
1502  *
1503  * Returns: (transfer full): the task result, or %NULL on error
1504  *
1505  * Since: 2.36
1506  */
1507 gpointer
1508 g_task_propagate_pointer (GTask   *task,
1509                           GError **error)
1510 {
1511   if (g_task_propagate_error (task, error))
1512     return NULL;
1513
1514   g_return_val_if_fail (task->result_set == TRUE, NULL);
1515
1516   task->result_destroy = NULL;
1517   task->result_set = FALSE;
1518   return task->result.pointer;
1519 }
1520
1521 /**
1522  * g_task_return_int:
1523  * @task: a #GTask.
1524  * @result: the integer (#gssize) result of a task function.
1525  *
1526  * Sets @task's result to @result and completes the task (see
1527  * g_task_return_pointer() for more discussion of exactly what this
1528  * means).
1529  *
1530  * Since: 2.36
1531  */
1532 void
1533 g_task_return_int (GTask  *task,
1534                    gssize  result)
1535 {
1536   g_return_if_fail (task->result_set == FALSE);
1537
1538   task->result.size = result;
1539
1540   g_task_return (task, G_TASK_RETURN_SUCCESS);
1541 }
1542
1543 /**
1544  * g_task_propagate_int:
1545  * @task: a #GTask.
1546  * @error: return location for a #GError
1547  *
1548  * Gets the result of @task as an integer (#gssize).
1549  *
1550  * If the task resulted in an error, or was cancelled, then this will
1551  * instead return -1 and set @error.
1552  *
1553  * Since this method transfers ownership of the return value (or
1554  * error) to the caller, you may only call it once.
1555  *
1556  * Returns: the task result, or -1 on error
1557  *
1558  * Since: 2.36
1559  */
1560 gssize
1561 g_task_propagate_int (GTask   *task,
1562                       GError **error)
1563 {
1564   if (g_task_propagate_error (task, error))
1565     return -1;
1566
1567   g_return_val_if_fail (task->result_set == TRUE, -1);
1568
1569   task->result_set = FALSE;
1570   return task->result.size;
1571 }
1572
1573 /**
1574  * g_task_return_boolean:
1575  * @task: a #GTask.
1576  * @result: the #gboolean result of a task function.
1577  *
1578  * Sets @task's result to @result and completes the task (see
1579  * g_task_return_pointer() for more discussion of exactly what this
1580  * means).
1581  *
1582  * Since: 2.36
1583  */
1584 void
1585 g_task_return_boolean (GTask    *task,
1586                        gboolean  result)
1587 {
1588   g_return_if_fail (task->result_set == FALSE);
1589
1590   task->result.boolean = result;
1591
1592   g_task_return (task, G_TASK_RETURN_SUCCESS);
1593 }
1594
1595 /**
1596  * g_task_propagate_boolean:
1597  * @task: a #GTask.
1598  * @error: return location for a #GError
1599  *
1600  * Gets the result of @task as a #gboolean.
1601  *
1602  * If the task resulted in an error, or was cancelled, then this will
1603  * instead return %FALSE and set @error.
1604  *
1605  * Since this method transfers ownership of the return value (or
1606  * error) to the caller, you may only call it once.
1607  *
1608  * Returns: the task result, or %FALSE on error
1609  *
1610  * Since: 2.36
1611  */
1612 gboolean
1613 g_task_propagate_boolean (GTask   *task,
1614                           GError **error)
1615 {
1616   if (g_task_propagate_error (task, error))
1617     return FALSE;
1618
1619   g_return_val_if_fail (task->result_set == TRUE, FALSE);
1620
1621   task->result_set = FALSE;
1622   return task->result.boolean;
1623 }
1624
1625 /**
1626  * g_task_return_error:
1627  * @task: a #GTask.
1628  * @error: (transfer full): the #GError result of a task function.
1629  *
1630  * Sets @task's result to @error (which @task assumes ownership of)
1631  * and completes the task (see g_task_return_pointer() for more
1632  * discussion of exactly what this means).
1633  *
1634  * Note that since the task takes ownership of @error, and since the
1635  * task may be completed before returning from g_task_return_error(),
1636  * you cannot assume that @error is still valid after calling this.
1637  * Call g_error_copy() on the error if you need to keep a local copy
1638  * as well.
1639  *
1640  * See also g_task_return_new_error().
1641  *
1642  * Since: 2.36
1643  */
1644 void
1645 g_task_return_error (GTask  *task,
1646                      GError *error)
1647 {
1648   g_return_if_fail (task->result_set == FALSE);
1649   g_return_if_fail (error != NULL);
1650
1651   task->error = error;
1652
1653   g_task_return (task, G_TASK_RETURN_ERROR);
1654 }
1655
1656 /**
1657  * g_task_return_new_error:
1658  * @task: a #GTask.
1659  * @domain: a #GQuark.
1660  * @code: an error code.
1661  * @format: a string with format characters.
1662  * @...: a list of values to insert into @format.
1663  *
1664  * Sets @task's result to a new #GError created from @domain, @code,
1665  * @format, and the remaining arguments, and completes the task (see
1666  * g_task_return_pointer() for more discussion of exactly what this
1667  * means).
1668  *
1669  * See also g_task_return_error().
1670  *
1671  * Since: 2.36
1672  */
1673 void
1674 g_task_return_new_error (GTask           *task,
1675                          GQuark           domain,
1676                          gint             code,
1677                          const char      *format,
1678                          ...)
1679 {
1680   GError *error;
1681   va_list args;
1682
1683   va_start (args, format);
1684   error = g_error_new_valist (domain, code, format, args);
1685   va_end (args);
1686
1687   g_task_return_error (task, error);
1688 }
1689
1690 /**
1691  * g_task_return_error_if_cancelled:
1692  * @task: a #GTask
1693  *
1694  * Checks if @task's #GCancellable has been cancelled, and if so, sets
1695  * @task's error accordingly and completes the task (see
1696  * g_task_return_pointer() for more discussion of exactly what this
1697  * means).
1698  *
1699  * Return value: %TRUE if @task has been cancelled, %FALSE if not
1700  *
1701  * Since: 2.36
1702  */
1703 gboolean
1704 g_task_return_error_if_cancelled (GTask *task)
1705 {
1706   GError *error = NULL;
1707
1708   g_return_val_if_fail (task->result_set == FALSE, FALSE);
1709
1710   if (g_cancellable_set_error_if_cancelled (task->cancellable, &error))
1711     {
1712       /* We explicitly set task->error so this works even when
1713        * check-cancellable is not set.
1714        */
1715       g_clear_error (&task->error);
1716       task->error = error;
1717
1718       g_task_return (task, G_TASK_RETURN_ERROR);
1719       return TRUE;
1720     }
1721   else
1722     return FALSE;
1723 }
1724
1725 /**
1726  * g_task_had_error:
1727  * @task: a #GTask.
1728  *
1729  * Tests if @task resulted in an error.
1730  *
1731  * Returns: %TRUE if the task resulted in an error, %FALSE otherwise.
1732  *
1733  * Since: 2.36
1734  */
1735 gboolean
1736 g_task_had_error (GTask *task)
1737 {
1738   if (task->error != NULL)
1739     return TRUE;
1740
1741   if (task->check_cancellable && g_cancellable_is_cancelled (task->cancellable))
1742     return TRUE;
1743
1744   return FALSE;
1745 }
1746
1747 /**
1748  * g_task_is_valid:
1749  * @result: (type Gio.AsyncResult): A #GAsyncResult
1750  * @source_object: (allow-none) (type GObject): the source object
1751  *   expected to be associated with the task
1752  *
1753  * Checks that @result is a #GTask, and that @source_object is its
1754  * source object (or that @source_object is %NULL and @result has no
1755  * source object). This can be used in g_return_if_fail() checks.
1756  *
1757  * Return value: %TRUE if @result and @source_object are valid, %FALSE
1758  * if not
1759  *
1760  * Since: 2.36
1761  */
1762 gboolean
1763 g_task_is_valid (gpointer result,
1764                  gpointer source_object)
1765 {
1766   if (!G_IS_TASK (result))
1767     return FALSE;
1768
1769   return G_TASK (result)->source_object == source_object;
1770 }
1771
1772 static gint
1773 g_task_compare_priority (gconstpointer a,
1774                          gconstpointer b,
1775                          gpointer      user_data)
1776 {
1777   const GTask *ta = a;
1778   const GTask *tb = b;
1779   gboolean a_cancelled, b_cancelled;
1780
1781   /* Tasks that are causing other tasks to block have higher
1782    * priority.
1783    */
1784   if (ta->blocking_other_task && !tb->blocking_other_task)
1785     return -1;
1786   else if (tb->blocking_other_task && !ta->blocking_other_task)
1787     return 1;
1788
1789   /* Let already-cancelled tasks finish right away */
1790   a_cancelled = (ta->check_cancellable &&
1791                  g_cancellable_is_cancelled (ta->cancellable));
1792   b_cancelled = (tb->check_cancellable &&
1793                  g_cancellable_is_cancelled (tb->cancellable));
1794   if (a_cancelled && !b_cancelled)
1795     return -1;
1796   else if (b_cancelled && !a_cancelled)
1797     return 1;
1798
1799   /* Lower priority == run sooner == negative return value */
1800   return ta->priority - tb->priority;
1801 }
1802
1803 static void
1804 g_task_thread_pool_init (void)
1805 {
1806   task_pool = g_thread_pool_new (g_task_thread_pool_thread, NULL,
1807                                  10, FALSE, NULL);
1808   g_assert (task_pool != NULL);
1809
1810   g_thread_pool_set_sort_function (task_pool, g_task_compare_priority, NULL);
1811 }
1812
1813 static void
1814 g_task_thread_pool_resort (void)
1815 {
1816   g_thread_pool_set_sort_function (task_pool, g_task_compare_priority, NULL);
1817 }
1818
1819 static void
1820 g_task_class_init (GTaskClass *klass)
1821 {
1822   GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
1823
1824   gobject_class->finalize = g_task_finalize;
1825 }
1826
1827 static gpointer
1828 g_task_get_user_data (GAsyncResult *res)
1829 {
1830   return G_TASK (res)->callback_data;
1831 }
1832
1833 static gboolean
1834 g_task_is_tagged (GAsyncResult *res,
1835                   gpointer      source_tag)
1836 {
1837   return G_TASK (res)->source_tag == source_tag;
1838 }
1839
1840 static void
1841 g_task_async_result_iface_init (GAsyncResultIface *iface)
1842 {
1843   iface->get_user_data = g_task_get_user_data;
1844   iface->get_source_object = g_task_ref_source_object;
1845   iface->is_tagged = g_task_is_tagged;
1846 }