gio/gsimpleasyncresult.c

   1 /* GIO - GLib Input, Output and Streaming Library
   2  *
   3  * Copyright (C) 2006-2007 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  * Author: Alexander Larsson <alexl@redhat.com>
  21  */
  22
  23 #include "config.h"
  24
  25 #include <sys/types.h>
  26 #include <sys/stat.h>
  27 #include <string.h>
  28 #include <errno.h>
  29 #include <fcntl.h>
  30 #ifdef HAVE_UNISTD_H
  31 #include <unistd.h>
  32 #endif
  33
  34 #include "gsimpleasyncresult.h"
  35 #include "gasyncresult.h"
  36 #include "gcancellable.h"
  37 #include "gioscheduler.h"
  38 #include <gio/gioerror.h>
  39 #include "glibintl.h"
  40
  41 #include "gioalias.h"
  42
  43 /**
  44  * SECTION:gsimpleasyncresult
  45  * @short_description: Simple asynchronous results implementation
  46  * @include: gio/gio.h
  47  * @see_also: #GAsyncResult
  48  *
  49  * Implements #GAsyncResult for simple cases. Most of the time, this
  50  * will be all an application needs, and will be used transparently.
  51  * Because of this, #GSimpleAsyncResult is used throughout GIO for
  52  * handling asynchronous functions.
  53  *
  54  * GSimpleAsyncResult handles #GAsyncReadyCallback<!-- -->s, error
  55  * reporting, operation cancellation and the final state of an operation,
  56  * completely transparent to the application. Results can be returned
  57  * as a pointer e.g. for functions that return data that is collected
  58  * asynchronously, a boolean value for checking the success or failure
  59  * of an operation, or a #gssize for operations which return the number
  60  * of bytes modified by the operation; all of the simple return cases
  61  * are covered.
  62  *
  63  * Most of the time, an application will not need to know of the details
  64  * of this API; it is handled transparently, and any necessary operations
  65  * are handled by #GAsyncResult's interface. However, if implementing a
  66  * new GIO module, for writing language bindings, or for complex
  67  * applications that need better control of how asynchronous operations
  68  * are completed, it is important to understand this functionality.
  69  *
  70  * GSimpleAsyncResults are tagged with the calling function to ensure
  71  * that asynchronous functions and their finishing functions are used
  72  * together correctly.
  73  *
  74  * To create a new #GSimpleAsyncResult, call g_simple_async_result_new().
  75  * If the result needs to be created for a #GError, use
  76  * g_simple_async_result_new_from_error(). If a #GError is not available
  77  * (e.g. the asynchronous operation's doesn't take a #GError argument),
  78  * but the result still needs to be created for an error condition, use
  79  * g_simple_async_result_new_error() (or g_simple_async_result_set_error_va()
  80  * if your application or binding requires passing a variable argument list
  81  * directly), and the error can then be propegated through the use of
  82  * g_simple_async_result_propagate_error().
  83  *
  84  * An asynchronous operation can be made to ignore a cancellation event by
  85  * calling g_simple_async_result_set_handle_cancellation() with a
  86  * #GSimpleAsyncResult for the operation and %FALSE. This is useful for
  87  * operations that are dangerous to cancel, such as close (which would
  88  * cause a leak if cancelled before being run).
  89  *
  90  * GSimpleAsyncResult can integrate into GLib's event loop, #GMainLoop,
  91  * or it can use #GThread<!-- -->s if available.
  92  * g_simple_async_result_complete() will finish an I/O task directly within
  93  * the main event loop. g_simple_async_result_complete_in_idle() will
  94  * integrate the I/O task into the main event loop as an idle function and
  95  * g_simple_async_result_run_in_thread() will run the job in a separate
  96  * thread.
  97  *
  98  * To set the results of an asynchronous function,
  99  * g_simple_async_result_set_op_res_gpointer(),
 100  * g_simple_async_result_set_op_res_gboolean(), and
 101  * g_simple_async_result_set_op_res_gssize()
 102  * are provided, setting the operation's result to a gpointer, gboolean, or
 103  * gssize, respectively.
 104  *
 105  * Likewise, to get the result of an asynchronous function,
 106  * g_simple_async_result_get_op_res_gpointer(),
 107  * g_simple_async_result_get_op_res_gboolean(), and
 108  * g_simple_async_result_get_op_res_gssize() are
 109  * provided, getting the operation's result as a gpointer, gboolean, and
 110  * gssize, respectively.
 111  **/
 112
 113 static void g_simple_async_result_async_result_iface_init (GAsyncResultIface       *iface);
 114
 115 struct _GSimpleAsyncResult
 116 {
 117   GObject parent_instance;
 118
 119   GObject *source_object;
 120   GAsyncReadyCallback callback;
 121   gpointer user_data;
 122   GError *error;
 123   gboolean failed;
 124   gboolean handle_cancellation;
 125
 126   gpointer source_tag;
 127
 128   union {
 129     gpointer v_pointer;
 130     gboolean v_boolean;
 131     gssize   v_ssize;
 132   } op_res;
 133
 134   GDestroyNotify destroy_op_res;
 135 };
 136
 137 struct _GSimpleAsyncResultClass
 138 {
 139   GObjectClass parent_class;
 140 };
 141
 142
 143 G_DEFINE_TYPE_WITH_CODE (GSimpleAsyncResult, g_simple_async_result, G_TYPE_OBJECT,
 144                          G_IMPLEMENT_INTERFACE (G_TYPE_ASYNC_RESULT,
 145                                                 g_simple_async_result_async_result_iface_init))
 146
 147 static void
 148 clear_op_res (GSimpleAsyncResult *simple)
 149 {
 150   if (simple->destroy_op_res)
 151     simple->destroy_op_res (simple->op_res.v_pointer);
 152   simple->destroy_op_res = NULL;
 153   simple->op_res.v_ssize = 0;
 154 }
 155
 156 static void
 157 g_simple_async_result_finalize (GObject *object)
 158 {
 159   GSimpleAsyncResult *simple;
 160
 161   simple = G_SIMPLE_ASYNC_RESULT (object);
 162
 163   if (simple->source_object)
 164     g_object_unref (simple->source_object);
 165
 166   clear_op_res (simple);
 167
 168   if (simple->error)
 169     g_error_free (simple->error);
 170
 171   G_OBJECT_CLASS (g_simple_async_result_parent_class)->finalize (object);
 172 }
 173
 174 static void
 175 g_simple_async_result_class_init (GSimpleAsyncResultClass *klass)
 176 {
 177   GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
 178
 179   gobject_class->finalize = g_simple_async_result_finalize;
 180 }
 181
 182 static void
 183 g_simple_async_result_init (GSimpleAsyncResult *simple)
 184 {
 185   simple->handle_cancellation = TRUE;
 186 }
 187
 188 /**
 189  * g_simple_async_result_new:
 190  * @source_object: a #GObject the asynchronous function was called with,
 191  * or %NULL.
 192  * @callback: a #GAsyncReadyCallback.
 193  * @user_data: user data passed to @callback.
 194  * @source_tag: the asynchronous function.
 195  *
 196  * Creates a #GSimpleAsyncResult.
 197  *
 198  * Returns: a #GSimpleAsyncResult.
 199  **/
 200 GSimpleAsyncResult *
 201 g_simple_async_result_new (GObject             *source_object,
 202                            GAsyncReadyCallback  callback,
 203                            gpointer             user_data,
 204                            gpointer             source_tag)
 205 {
 206   GSimpleAsyncResult *simple;
 207
 208   g_return_val_if_fail (!source_object || G_IS_OBJECT (source_object), NULL);
 209
 210   simple = g_object_new (G_TYPE_SIMPLE_ASYNC_RESULT, NULL);
 211   simple->callback = callback;
 212   if (source_object)
 213     simple->source_object = g_object_ref (source_object);
 214   else
 215     simple->source_object = NULL;
 216   simple->user_data = user_data;
 217   simple->source_tag = source_tag;
 218
 219   return simple;
 220 }
 221
 222 /**
 223  * g_simple_async_result_new_from_error:
 224  * @source_object: a #GObject, or %NULL.
 225  * @callback: a #GAsyncReadyCallback.
 226  * @user_data: user data passed to @callback.
 227  * @error: a #GError location.
 228  *
 229  * Creates a #GSimpleAsyncResult from an error condition.
 230  *
 231  * Returns: a #GSimpleAsyncResult.
 232  **/
 233 GSimpleAsyncResult *
 234 g_simple_async_result_new_from_error (GObject             *source_object,
 235                                       GAsyncReadyCallback  callback,
 236                                       gpointer             user_data,
 237                                       GError              *error)
 238 {
 239   GSimpleAsyncResult *simple;
 240
 241   g_return_val_if_fail (!source_object || G_IS_OBJECT (source_object), NULL);
 242
 243   simple = g_simple_async_result_new (source_object,
 244                                       callback,
 245                                       user_data, NULL);
 246   g_simple_async_result_set_from_error (simple, error);
 247
 248   return simple;
 249 }
 250
 251 /**
 252  * g_simple_async_result_new_error:
 253  * @source_object: a #GObject, or %NULL.
 254  * @callback: a #GAsyncReadyCallback.
 255  * @user_data: user data passed to @callback.
 256  * @domain: a #GQuark.
 257  * @code: an error code.
 258  * @format: a string with format characters.
 259  * @...: a list of values to insert into @format.
 260  *
 261  * Creates a new #GSimpleAsyncResult with a set error.
 262  *
 263  * Returns: a #GSimpleAsyncResult.
 264  **/
 265 GSimpleAsyncResult *
 266 g_simple_async_result_new_error (GObject             *source_object,
 267                                  GAsyncReadyCallback  callback,
 268                                  gpointer             user_data,
 269                                  GQuark               domain,
 270                                  gint                 code,
 271                                  const char          *format,
 272                                  ...)
 273 {
 274   GSimpleAsyncResult *simple;
 275   va_list args;
 276
 277   g_return_val_if_fail (!source_object || G_IS_OBJECT (source_object), NULL);
 278   g_return_val_if_fail (domain != 0, NULL);
 279   g_return_val_if_fail (format != NULL, NULL);
 280
 281   simple = g_simple_async_result_new (source_object,
 282                                       callback,
 283                                       user_data, NULL);
 284
 285   va_start (args, format);
 286   g_simple_async_result_set_error_va (simple, domain, code, format, args);
 287   va_end (args);
 288
 289   return simple;
 290 }
 291
 292
 293 static gpointer
 294 g_simple_async_result_get_user_data (GAsyncResult *res)
 295 {
 296   return G_SIMPLE_ASYNC_RESULT (res)->user_data;
 297 }
 298
 299 static GObject *
 300 g_simple_async_result_get_source_object (GAsyncResult *res)
 301 {
 302   if (G_SIMPLE_ASYNC_RESULT (res)->source_object)
 303     return g_object_ref (G_SIMPLE_ASYNC_RESULT (res)->source_object);
 304   return NULL;
 305 }
 306
 307 static void
 308 g_simple_async_result_async_result_iface_init (GAsyncResultIface *iface)
 309 {
 310   iface->get_user_data = g_simple_async_result_get_user_data;
 311   iface->get_source_object = g_simple_async_result_get_source_object;
 312 }
 313
 314 /**
 315  * g_simple_async_result_set_handle_cancellation:
 316  * @simple: a #GSimpleAsyncResult.
 317  * @handle_cancellation: a #gboolean.
 318  *
 319  * Sets whether to handle cancellation within the asynchronous operation.
 320  *
 321  **/
 322 void
 323 g_simple_async_result_set_handle_cancellation (GSimpleAsyncResult *simple,
 324                                                gboolean            handle_cancellation)
 325 {
 326   g_return_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple));
 327   simple->handle_cancellation = handle_cancellation;
 328 }
 329
 330 /**
 331  * g_simple_async_result_get_source_tag:
 332  * @simple: a #GSimpleAsyncResult.
 333  *
 334  * Gets the source tag for the #GSimpleAsyncResult.
 335  *
 336  * Returns: a #gpointer to the source object for the #GSimpleAsyncResult.
 337  **/
 338 gpointer
 339 g_simple_async_result_get_source_tag (GSimpleAsyncResult *simple)
 340 {
 341   g_return_val_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple), NULL);
 342   return simple->source_tag;
 343 }
 344
 345 /**
 346  * g_simple_async_result_propagate_error:
 347  * @simple: a #GSimpleAsyncResult.
 348  * @dest: a location to propegate the error to.
 349  *
 350  * Propagates an error from within the simple asynchronous result to
 351  * a given destination.
 352  *
 353  * Returns: %TRUE if the error was propegated to @dest. %FALSE otherwise.
 354  **/
 355 gboolean
 356 g_simple_async_result_propagate_error (GSimpleAsyncResult  *simple,
 357                                        GError             **dest)
 358 {
 359   g_return_val_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple), FALSE);
 360
 361   if (simple->failed)
 362     {
 363       g_propagate_error (dest, simple->error);
 364       simple->error = NULL;
 365       return TRUE;
 366     }
 367
 368   return FALSE;
 369 }
 370
 371 /**
 372  * g_simple_async_result_set_op_res_gpointer:
 373  * @simple: a #GSimpleAsyncResult.
 374  * @op_res: a pointer result from an asynchronous function.
 375  * @destroy_op_res: a #GDestroyNotify function.
 376  *
 377  * Sets the operation result within the asynchronous result to a pointer.
 378  **/
 379 void
 380 g_simple_async_result_set_op_res_gpointer (GSimpleAsyncResult *simple,
 381                                            gpointer            op_res,
 382                                            GDestroyNotify      destroy_op_res)
 383 {
 384   g_return_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple));
 385
 386   clear_op_res (simple);
 387   simple->op_res.v_pointer = op_res;
 388   simple->destroy_op_res = destroy_op_res;
 389 }
 390
 391 /**
 392  * g_simple_async_result_get_op_res_gpointer:
 393  * @simple: a #GSimpleAsyncResult.
 394  *
 395  * Gets a pointer result as returned by the asynchronous function.
 396  *
 397  * Returns: a pointer from the result.
 398  **/
 399 gpointer
 400 g_simple_async_result_get_op_res_gpointer (GSimpleAsyncResult *simple)
 401 {
 402   g_return_val_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple), NULL);
 403   return simple->op_res.v_pointer;
 404 }
 405
 406 /**
 407  * g_simple_async_result_set_op_res_gssize:
 408  * @simple: a #GSimpleAsyncResult.
 409  * @op_res: a #gssize.
 410  *
 411  * Sets the operation result within the asynchronous result to
 412  * the given @op_res.
 413  **/
 414 void
 415 g_simple_async_result_set_op_res_gssize (GSimpleAsyncResult *simple,
 416                                          gssize              op_res)
 417 {
 418   g_return_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple));
 419   clear_op_res (simple);
 420   simple->op_res.v_ssize = op_res;
 421 }
 422
 423 /**
 424  * g_simple_async_result_get_op_res_gssize:
 425  * @simple: a #GSimpleAsyncResult.
 426  *
 427  * Gets a gssize from the asynchronous result.
 428  *
 429  * Returns: a gssize returned from the asynchronous function.
 430  **/
 431 gssize
 432 g_simple_async_result_get_op_res_gssize (GSimpleAsyncResult *simple)
 433 {
 434   g_return_val_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple), 0);
 435   return simple->op_res.v_ssize;
 436 }
 437
 438 /**
 439  * g_simple_async_result_set_op_res_gboolean:
 440  * @simple: a #GSimpleAsyncResult.
 441  * @op_res: a #gboolean.
 442  *
 443  * Sets the operation result to a boolean within the asynchronous result.
 444  **/
 445 void
 446 g_simple_async_result_set_op_res_gboolean (GSimpleAsyncResult *simple,
 447                                            gboolean            op_res)
 448 {
 449   g_return_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple));
 450   clear_op_res (simple);
 451   simple->op_res.v_boolean = !!op_res;
 452 }
 453
 454 /**
 455  * g_simple_async_result_get_op_res_gboolean:
 456  * @simple: a #GSimpleAsyncResult.
 457  *
 458  * Gets the operation result boolean from within the asynchronous result.
 459  *
 460  * Returns: %TRUE if the operation's result was %TRUE, %FALSE
 461  *     if the operation's result was %FALSE.
 462  **/
 463 gboolean
 464 g_simple_async_result_get_op_res_gboolean (GSimpleAsyncResult *simple)
 465 {
 466   g_return_val_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple), FALSE);
 467   return simple->op_res.v_boolean;
 468 }
 469
 470 /**
 471  * g_simple_async_result_set_from_error:
 472  * @simple: a #GSimpleAsyncResult.
 473  * @error: #GError.
 474  *
 475  * Sets the result from a #GError.
 476  **/
 477 void
 478 g_simple_async_result_set_from_error (GSimpleAsyncResult *simple,
 479                                       GError             *error)
 480 {
 481   g_return_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple));
 482   g_return_if_fail (error != NULL);
 483
 484   if (simple->error)
 485     g_error_free (simple->error);
 486   simple->error = g_error_copy (error);
 487   simple->failed = TRUE;
 488 }
 489
 490 /**
 491  * g_simple_async_result_set_error_va:
 492  * @simple: a #GSimpleAsyncResult.
 493  * @domain: a #GQuark (usually #G_IO_ERROR).
 494  * @code: an error code.
 495  * @format: a formatted error reporting string.
 496  * @args: va_list of arguments.
 497  *
 498  * Sets an error within the asynchronous result without a #GError.
 499  * Unless writing a binding, see g_simple_async_result_set_error().
 500  **/
 501 void
 502 g_simple_async_result_set_error_va (GSimpleAsyncResult *simple,
 503                                     GQuark              domain,
 504                                     gint                code,
 505                                     const char         *format,
 506                                     va_list             args)
 507 {
 508   g_return_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple));
 509   g_return_if_fail (domain != 0);
 510   g_return_if_fail (format != NULL);
 511
 512   if (simple->error)
 513     g_error_free (simple->error);
 514   simple->error = g_error_new_valist (domain, code, format, args);
 515   simple->failed = TRUE;
 516 }
 517
 518 /**
 519  * g_simple_async_result_set_error:
 520  * @simple: a #GSimpleAsyncResult.
 521  * @domain: a #GQuark (usually #G_IO_ERROR).
 522  * @code: an error code.
 523  * @format: a formatted error reporting string.
 524  * @...: a list of variables to fill in @format.
 525  *
 526  * Sets an error within the asynchronous result without a #GError.
 527  **/
 528 void
 529 g_simple_async_result_set_error (GSimpleAsyncResult *simple,
 530                                  GQuark              domain,
 531                                  gint                code,
 532                                  const char         *format,
 533                                  ...)
 534 {
 535   va_list args;
 536
 537   g_return_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple));
 538   g_return_if_fail (domain != 0);
 539   g_return_if_fail (format != NULL);
 540
 541   va_start (args, format);
 542   g_simple_async_result_set_error_va (simple, domain, code, format, args);
 543   va_end (args);
 544 }
 545
 546 /**
 547  * g_simple_async_result_complete:
 548  * @simple: a #GSimpleAsyncResult.
 549  *
 550  * Completes an asynchronous I/O job.
 551  * Must be called in the main thread, as it invokes the callback that
 552  * should be called in the main thread. If you are in a different thread
 553  * use g_simple_async_result_complete_in_idle().
 554  **/
 555 void
 556 g_simple_async_result_complete (GSimpleAsyncResult *simple)
 557 {
 558   g_return_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple));
 559
 560   if (simple->callback)
 561     simple->callback (simple->source_object,
 562                       G_ASYNC_RESULT (simple),
 563                       simple->user_data);
 564 }
 565
 566 static gboolean
 567 complete_in_idle_cb (gpointer data)
 568 {
 569   GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (data);
 570
 571   g_simple_async_result_complete (simple);
 572
 573   return FALSE;
 574 }
 575
 576 /**
 577  * g_simple_async_result_complete_in_idle:
 578  * @simple: a #GSimpleAsyncResult.
 579  *
 580  * Completes an asynchronous function in the main event loop using
 581  * an idle function.
 582  **/
 583 void
 584 g_simple_async_result_complete_in_idle (GSimpleAsyncResult *simple)
 585 {
 586   GSource *source;
 587   guint id;
 588
 589   g_return_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple));
 590
 591   g_object_ref (simple);
 592
 593   source = g_idle_source_new ();
 594   g_source_set_priority (source, G_PRIORITY_DEFAULT);
 595   g_source_set_callback (source, complete_in_idle_cb, simple, g_object_unref);
 596
 597   id = g_source_attach (source, NULL);
 598   g_source_unref (source);
 599 }
 600
 601 typedef struct {
 602   GSimpleAsyncResult *simple;
 603   GCancellable *cancellable;
 604   GSimpleAsyncThreadFunc func;
 605 } RunInThreadData;
 606
 607
 608 static gboolean
 609 complete_in_idle_cb_for_thread (gpointer _data)
 610 {
 611   RunInThreadData *data = _data;
 612   GSimpleAsyncResult *simple;
 613
 614   simple = data->simple;
 615
 616   if (simple->handle_cancellation &&
 617       g_cancellable_is_cancelled (data->cancellable))
 618     g_simple_async_result_set_error (simple,
 619                                      G_IO_ERROR,
 620                                      G_IO_ERROR_CANCELLED,
 621                                      "%s", _("Operation was cancelled"));
 622
 623   g_simple_async_result_complete (simple);
 624
 625   if (data->cancellable)
 626     g_object_unref (data->cancellable);
 627   g_object_unref (data->simple);
 628   g_free (data);
 629
 630   return FALSE;
 631 }
 632
 633 static gboolean
 634 run_in_thread (GIOSchedulerJob *job,
 635                GCancellable    *c,
 636                gpointer         _data)
 637 {
 638   RunInThreadData *data = _data;
 639   GSimpleAsyncResult *simple = data->simple;
 640   GSource *source;
 641   guint id;
 642
 643   if (simple->handle_cancellation &&
 644       g_cancellable_is_cancelled (c))
 645     g_simple_async_result_set_error (simple,
 646                                      G_IO_ERROR,
 647                                      G_IO_ERROR_CANCELLED,
 648                                      "%s", _("Operation was cancelled"));
 649   else
 650     data->func (simple,
 651                 simple->source_object,
 652                 c);
 653
 654   source = g_idle_source_new ();
 655   g_source_set_priority (source, G_PRIORITY_DEFAULT);
 656   g_source_set_callback (source, complete_in_idle_cb_for_thread, data, NULL);
 657
 658   id = g_source_attach (source, NULL);
 659   g_source_unref (source);
 660
 661   return FALSE;
 662 }
 663
 664 /**
 665  * g_simple_async_result_run_in_thread:
 666  * @simple: a #GSimpleAsyncResult.
 667  * @func: a #GSimpleAsyncThreadFunc.
 668  * @io_priority: the io priority of the request.
 669  * @cancellable: optional #GCancellable object, %NULL to ignore.
 670  *
 671  * Runs the asynchronous job in a separated thread.
 672  **/
 673 void
 674 g_simple_async_result_run_in_thread (GSimpleAsyncResult     *simple,
 675                                      GSimpleAsyncThreadFunc  func,
 676                                      int                     io_priority,
 677                                      GCancellable           *cancellable)
 678 {
 679   RunInThreadData *data;
 680
 681   g_return_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple));
 682   g_return_if_fail (func != NULL);
 683
 684   data = g_new (RunInThreadData, 1);
 685   data->func = func;
 686   data->simple = g_object_ref (simple);
 687   data->cancellable = cancellable;
 688   if (cancellable)
 689     g_object_ref (cancellable);
 690   g_io_scheduler_push_job (run_in_thread, data, NULL, io_priority, cancellable);
 691 }
 692
 693 /**
 694  * g_simple_async_result_is_valid:
 695  * @result: the #GAsyncResult passed to the _finish function.
 696  * @source: the #GObject passed to the _finish function.
 697  * @source_tag: the asynchronous function.
 698  *
 699  * Ensures that the data passed to the _finish function of an async
 700  * operation is consistent.  Three checks are performed.
 701  *
 702  * First, @result is checked to ensure that it is really a
 703  * #GSimpleAsyncResult.  Second, @source is checked to ensure that it
 704  * matches the source object of @result.  Third, @source_tag is
 705  * checked to ensure that it is equal to the source_tag argument given
 706  * to g_simple_async_result_new() (which, by convention, is a pointer
 707  * to the _async function corresponding to the _finish function from
 708  * which this function is called).
 709  *
 710  * Returns: #TRUE if all checks passed or #FALSE if any failed.
 711  **/
 712 gboolean
 713 g_simple_async_result_is_valid (GAsyncResult *result,
 714                                 GObject      *source,
 715                                 gpointer      source_tag)
 716 {
 717   GSimpleAsyncResult *simple;
 718   GObject *cmp_source;
 719
 720   if (!G_IS_SIMPLE_ASYNC_RESULT (result))
 721     return FALSE;
 722   simple = (GSimpleAsyncResult *)result;
 723
 724   cmp_source = g_async_result_get_source_object (result);
 725   if (cmp_source != source)
 726     {
 727       g_object_unref (cmp_source);
 728       return FALSE;
 729     }
 730   g_object_unref (cmp_source);
 731
 732   return source_tag == g_simple_async_result_get_source_tag (simple);
 733 }
 734
 735 /**
 736  * g_simple_async_report_error_in_idle:
 737  * @object: a #GObject.
 738  * @callback: a #GAsyncReadyCallback.
 739  * @user_data: user data passed to @callback.
 740  * @domain: a #GQuark containing the error domain (usually #G_IO_ERROR).
 741  * @code: a specific error code.
 742  * @format: a formatted error reporting string.
 743  * @...: a list of variables to fill in @format.
 744  *
 745  * Reports an error in an asynchronous function in an idle function by
 746  * directly setting the contents of the #GAsyncResult with the given error
 747  * information.
 748  **/
 749 void
 750 g_simple_async_report_error_in_idle (GObject             *object,
 751                                      GAsyncReadyCallback  callback,
 752                                      gpointer             user_data,
 753                                      GQuark               domain,
 754                                      gint                 code,
 755                                      const char          *format,
 756                                      ...)
 757 {
 758   GSimpleAsyncResult *simple;
 759   va_list args;
 760
 761   g_return_if_fail (G_IS_OBJECT (object));
 762   g_return_if_fail (domain != 0);
 763   g_return_if_fail (format != NULL);
 764
 765   simple = g_simple_async_result_new (object,
 766                                       callback,
 767                                       user_data, NULL);
 768
 769   va_start (args, format);
 770   g_simple_async_result_set_error_va (simple, domain, code, format, args);
 771   va_end (args);
 772   g_simple_async_result_complete_in_idle (simple);
 773   g_object_unref (simple);
 774 }
 775
 776 /**
 777  * g_simple_async_report_gerror_in_idle:
 778  * @object: a #GObject.
 779  * @callback: a #GAsyncReadyCallback.
 780  * @user_data: user data passed to @callback.
 781  * @error: the #GError to report
 782  *
 783  * Reports an error in an idle function. Similar to
 784  * g_simple_async_report_error_in_idle(), but takes a #GError rather
 785  * than building a new one.
 786  **/
 787 void
 788 g_simple_async_report_gerror_in_idle (GObject *object,
 789                                       GAsyncReadyCallback callback,
 790                                       gpointer user_data,
 791                                       GError *error)
 792 {
 793   GSimpleAsyncResult *simple;
 794
 795   g_return_if_fail (G_IS_OBJECT (object));
 796   g_return_if_fail (error != NULL);
 797
 798   simple = g_simple_async_result_new_from_error (object,
 799                                                  callback,
 800                                                  user_data,
 801                                                  error);
 802   g_simple_async_result_complete_in_idle (simple);
 803   g_object_unref (simple);
 804 }
 805
 806 #define __G_SIMPLE_ASYNC_RESULT_C__
 807 #include "gioaliasdef.c"