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 #include <unistd.h>
  31
  32 #include "gsimpleasyncresult.h"
  33 #include "gioscheduler.h"
  34 #include <gio/gioerror.h>
  35 #include "glibintl.h"
  36
  37 /**
  38  * SECTION:gsimpleasyncresult
  39  * @short_description: simple asynchronous results implementation.
  40  * @see_also: #GAsyncResult.
  41  *
  42  * Implements #GAsyncResult for simple cases. Most of the time, this
  43  * will be all an application needs, and will be used transparently.
  44  * Because of this, #GSimpleAsyncResult is used throughout GIO for
  45  * handling asynchronous functions.
  46  *
  47  * GSimpleAsyncResult handles #GAsyncReadyCallback<!-- -->s, error reporting,
  48  * operation cancellation and the final state of an operation, completely
  49  * transparent to the application. Results can be returned as a pointer e.g.
  50  * for functions that return data that is collected asynchronously,
  51  * a boolean value for checking the success or failure of an operation,
  52  * or a #gssize for operations which return the number of bytes modified
  53  * by the operation; all of the simple return cases are covered.
  54  *
  55  * Most of the time, an application will not need to know of the details
  56  * of this API; it is handled transparently, and any necessary operations are handled by
  57  * #GAsyncResult's interface. However, if implementing a new GIO module, for writing
  58  * language bindings, or for complex applications that need better control of how
  59  * asynchronous operations are completed, it is important to understand this functionality.
  60  *
  61  * To create a new #GSimpleAsyncResult, call g_simple_async_result_new(). If the
  62  * result needs to be created for a #GError, use g_simple_async_result_new_from_error().
  63  * If a #GError is not available (e.g. the asynchronous operation's doesn't take a #GError
  64  * argument), but the result still needs to be created for an error condition, use
  65  * g_simple_async_result_new_error() (or g_simple_async_result_set_error_va()
  66  * if your application or binding requires passing a variable argument list directly),
  67  * and the error can then be propegated through the use of g_simple_async_result_propagate_error().
  68  *
  69  * An asynchronous operation can be made to ignore a cancellation event by calling
  70  * g_simple_async_result_set_handle_cancellation() with a #GSimpleAsyncResult for the operation
  71  * and %FALSE.
  72  *
  73  * GSimpleAsyncResult can integrate into GLib's Main Event Loop <!-- TODO: Crosslink -->,
  74  * or it can use #GThread<!-- -->s if available. g_simple_async_result_complete() will finish an
  75  * I/O task directly within the main event loop. g_simple_async_result_complete_in_idle() will integrate
  76  * the I/O task into the main event loop as an idle function and g_simple_async_result_run_in_thread()
  77  * will run the job in a separate thread.
  78  *
  79  * To set the results of an asynchronous function, g_simple_async_result_set_op_res_gpointer(),
  80  * g_simple_async_result_set_op_res_gboolean(), and g_simple_async_result_set_op_res_gssize()
  81  * are provided, setting the operation's result to a gpointer, gboolean, or gssize, respectively.
  82  *
  83  * Likewise, to get the result of an asynchronous function, g_simple_async_result_get_op_res_gpointer(),
  84  * g_simple_async_result_get_op_res_gboolean(), and g_simple_async_result_get_op_res_gssize() are
  85  * provided, getting the operation's result as a gpointer, gboolean, and gssize, respectively.
  86  *
  87  **/
  88
  89 static void g_simple_async_result_async_result_iface_init (GAsyncResultIface       *iface);
  90
  91 struct _GSimpleAsyncResult
  92 {
  93   GObject parent_instance;
  94
  95   GObject *source_object;
  96   GAsyncReadyCallback callback;
  97   gpointer user_data;
  98   GError *error;
  99   gboolean failed;
 100   gboolean handle_cancellation;
 101
 102   gpointer source_tag;
 103
 104   union {
 105     gpointer v_pointer;
 106     gboolean v_boolean;
 107     gssize   v_ssize;
 108   } op_res;
 109
 110   GDestroyNotify destroy_op_res;
 111 };
 112
 113 struct _GSimpleAsyncResultClass
 114 {
 115   GObjectClass parent_class;
 116 };
 117
 118
 119 G_DEFINE_TYPE_WITH_CODE (GSimpleAsyncResult, g_simple_async_result, G_TYPE_OBJECT,
 120                          G_IMPLEMENT_INTERFACE (G_TYPE_ASYNC_RESULT,
 121                                                 g_simple_async_result_async_result_iface_init))
 122
 123 static void
 124 g_simple_async_result_finalize (GObject *object)
 125 {
 126   GSimpleAsyncResult *simple;
 127
 128   simple = G_SIMPLE_ASYNC_RESULT (object);
 129
 130   if (simple->source_object)
 131     g_object_unref (simple->source_object);
 132
 133   if (simple->destroy_op_res)
 134     simple->destroy_op_res (simple->op_res.v_pointer);
 135
 136   if (simple->error)
 137     g_error_free (simple->error);
 138
 139   if (G_OBJECT_CLASS (g_simple_async_result_parent_class)->finalize)
 140     (*G_OBJECT_CLASS (g_simple_async_result_parent_class)->finalize) (object);
 141 }
 142
 143 static void
 144 g_simple_async_result_class_init (GSimpleAsyncResultClass *klass)
 145 {
 146   GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
 147
 148   gobject_class->finalize = g_simple_async_result_finalize;
 149 }
 150
 151 static void
 152 g_simple_async_result_init (GSimpleAsyncResult *simple)
 153 {
 154   simple->handle_cancellation = TRUE;
 155 }
 156
 157 /**
 158  * g_simple_async_result_new:
 159  * @source_object: a #GObject.
 160  * @callback: a #GAsyncReadyCallback.
 161  * @user_data: user data passed to @callback.
 162  * @source_tag:
 163  *
 164  * Creates a #GSimpleAsyncResult.
 165  *
 166  * Returns: a #GSimpleAsyncResult.
 167  **/
 168 GSimpleAsyncResult *
 169 g_simple_async_result_new (GObject *source_object,
 170                            GAsyncReadyCallback callback,
 171                            gpointer user_data,
 172                            gpointer source_tag)
 173 {
 174   GSimpleAsyncResult *simple;
 175
 176   g_return_val_if_fail (G_IS_OBJECT (source_object), NULL);
 177
 178   simple = g_object_new (G_TYPE_SIMPLE_ASYNC_RESULT, NULL);
 179   simple->callback = callback;
 180   simple->source_object = g_object_ref (source_object);
 181   simple->user_data = user_data;
 182   simple->source_tag = source_tag;
 183
 184   return simple;
 185 }
 186
 187 /**
 188  * g_simple_async_result_new_from_error:
 189  * @source_object: a #GObject.
 190  * @callback: a #GAsyncReadyCallback.
 191  * @user_data: user data passed to @callback.
 192  * @error: a #GError location.
 193  *
 194  * Creates a #GSimpleAsyncResult from an error condition.
 195  *
 196  * Returns: a #GSimpleAsyncResult.
 197  **/
 198 GSimpleAsyncResult *
 199 g_simple_async_result_new_from_error (GObject *source_object,
 200                                       GAsyncReadyCallback callback,
 201                                       gpointer user_data,
 202                                       GError *error)
 203 {
 204   GSimpleAsyncResult *simple;
 205
 206   g_return_val_if_fail (G_IS_OBJECT (source_object), NULL);
 207
 208   simple = g_simple_async_result_new (source_object,
 209                                       callback,
 210                                       user_data, NULL);
 211   g_simple_async_result_set_from_error (simple, error);
 212
 213   return simple;
 214 }
 215
 216 /**
 217  * g_simple_async_result_new_error:
 218  * @source_object: a #GObject.
 219  * @callback: a #GAsyncReadyCallback.
 220  * @user_data: user data passed to @callback.
 221  * @domain: a #GQuark.
 222  * @code: an error code.
 223  * @format: a string with format characters.
 224  * @Varargs: a list of values to insert into @format.
 225  *
 226  * Creates a new #GSimpleAsyncResult with a set error.
 227  *
 228  * Returns: a #GSimpleAsyncResult.
 229  **/
 230 GSimpleAsyncResult *
 231 g_simple_async_result_new_error (GObject *source_object,
 232                                  GAsyncReadyCallback callback,
 233                                  gpointer user_data,
 234                                  GQuark         domain,
 235                                  gint           code,
 236                                  const char    *format,
 237                                  ...)
 238 {
 239   GSimpleAsyncResult *simple;
 240   va_list args;
 241
 242   g_return_val_if_fail (G_IS_OBJECT (source_object), NULL);
 243   g_return_val_if_fail (domain != 0, NULL);
 244   g_return_val_if_fail (format != NULL, NULL);
 245
 246   simple = g_simple_async_result_new (source_object,
 247                                       callback,
 248                                       user_data, NULL);
 249
 250   va_start (args, format);
 251   g_simple_async_result_set_error_va (simple, domain, code, format, args);
 252   va_end (args);
 253
 254   return simple;
 255 }
 256
 257
 258 static gpointer
 259 g_simple_async_result_get_user_data (GAsyncResult *res)
 260 {
 261   return G_SIMPLE_ASYNC_RESULT (res)->user_data;
 262 }
 263
 264 static GObject *
 265 g_simple_async_result_get_source_object (GAsyncResult *res)
 266 {
 267   if (G_SIMPLE_ASYNC_RESULT (res)->source_object)
 268     return g_object_ref (G_SIMPLE_ASYNC_RESULT (res)->source_object);
 269   return NULL;
 270 }
 271
 272 static void
 273 g_simple_async_result_async_result_iface_init (GAsyncResultIface *iface)
 274 {
 275   iface->get_user_data = g_simple_async_result_get_user_data;
 276   iface->get_source_object = g_simple_async_result_get_source_object;
 277 }
 278
 279 /**
 280  * g_simple_async_result_set_handle_cancellation:
 281  * @simple: a #GSimpleAsyncResult.
 282  * @handle_cancellation: a #gboolean.
 283  *
 284  * Sets whether to handle cancellation within the asynchronous operation.
 285  *
 286  **/
 287 void
 288 g_simple_async_result_set_handle_cancellation (GSimpleAsyncResult *simple,
 289                                                gboolean handle_cancellation)
 290 {
 291   g_return_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple));
 292   simple->handle_cancellation = handle_cancellation;
 293 }
 294
 295 /**
 296  * g_simple_async_result_get_source_tag:
 297  * @simple: a #GSimpleAsyncResult.
 298  *
 299  * Gets the source tag for the #GSimpleAsyncResult.
 300  *
 301  * Returns: a #gpointer to the source object for the #GSimpleAsyncResult.
 302  **/
 303 gpointer
 304 g_simple_async_result_get_source_tag (GSimpleAsyncResult *simple)
 305 {
 306   g_return_val_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple), NULL);
 307   return simple->source_tag;
 308 }
 309
 310 /**
 311  * g_simple_async_result_propagate_error:
 312  * @simple: a #GSimpleAsyncResult.
 313  * @dest: a location to propegate the error to.
 314  *
 315  * Propegates an error from within the simple asynchronous result to
 316  * a given destination.
 317  *
 318  * Returns: %TRUE if the error was propegated to @dest. %FALSE otherwise.
 319  **/
 320 gboolean
 321 g_simple_async_result_propagate_error (GSimpleAsyncResult *simple,
 322                                        GError **dest)
 323 {
 324   g_return_val_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple), FALSE);
 325
 326   if (simple->failed)
 327     {
 328       g_propagate_error (dest, simple->error);
 329       simple->error = NULL;
 330       return TRUE;
 331     }
 332   return FALSE;
 333 }
 334
 335 /**
 336  * g_simple_async_result_set_op_res_gpointer:
 337  * @simple: a #GSimpleAsyncResult.
 338  * @op_res: a pointer result from an asynchronous function.
 339  * @destroy_op_res: a #GDestroyNotify function.
 340  *
 341  * Sets the operation result within the asynchronous result to a pointer.
 342  **/
 343 void
 344 g_simple_async_result_set_op_res_gpointer (GSimpleAsyncResult      *simple,
 345                                            gpointer                 op_res,
 346                                            GDestroyNotify           destroy_op_res)
 347 {
 348   g_return_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple));
 349
 350   simple->op_res.v_pointer = op_res;
 351   simple->destroy_op_res = destroy_op_res;
 352 }
 353
 354 /**
 355  * g_simple_async_result_get_op_res_gpointer:
 356  * @simple: a #GSimpleAsyncResult.
 357  *
 358  * Gets a pointer result as returned by the asynchronous function.
 359  *
 360  * Returns: a pointer from the result.
 361  **/
 362 gpointer
 363 g_simple_async_result_get_op_res_gpointer (GSimpleAsyncResult      *simple)
 364 {
 365   g_return_val_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple), NULL);
 366   return simple->op_res.v_pointer;
 367 }
 368
 369 /**
 370  * g_simple_async_result_set_op_res_gssize:
 371  * @simple: a #GSimpleAsyncResult.
 372  * @op_res: a #gssize.
 373  *
 374  * Sets the operation result within the asynchronous result to the given @op_res.
 375  **/
 376 void
 377 g_simple_async_result_set_op_res_gssize   (GSimpleAsyncResult      *simple,
 378                                            gssize                   op_res)
 379 {
 380   g_return_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple));
 381   simple->op_res.v_ssize = op_res;
 382 }
 383
 384 /**
 385  * g_simple_async_result_get_op_res_gssize:
 386  * @simple: a #GSimpleAsyncResult.
 387  *
 388  * Gets a gssize from the asynchronous result.
 389  *
 390  * Returns: a gssize returned from the asynchronous function.
 391  **/
 392 gssize
 393 g_simple_async_result_get_op_res_gssize   (GSimpleAsyncResult      *simple)
 394 {
 395   g_return_val_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple), 0);
 396   return simple->op_res.v_ssize;
 397 }
 398
 399 /**
 400  * g_simple_async_result_set_op_res_gboolean:
 401  * @simple: a #GSimpleAsyncResult.
 402  * @op_res: a #gboolean.
 403  *
 404  * Sets the operation result to a boolean within the asynchronous result.
 405  *
 406  **/
 407 void
 408 g_simple_async_result_set_op_res_gboolean (GSimpleAsyncResult      *simple,
 409                                            gboolean                 op_res)
 410 {
 411   g_return_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple));
 412   simple->op_res.v_boolean = !!op_res;
 413 }
 414
 415 /**
 416  * g_simple_async_result_get_op_res_gboolean:
 417  * @simple: a #GSimpleAsyncResult.
 418  *
 419  * Gets the operation result boolean from within the asynchronous result.
 420  *
 421  * Returns: %TRUE if the operation's result was %TRUE, %FALSE if the operation's
 422  * result was %FALSE.
 423  **/
 424 gboolean
 425 g_simple_async_result_get_op_res_gboolean (GSimpleAsyncResult      *simple)
 426 {
 427   g_return_val_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple), FALSE);
 428   return simple->op_res.v_boolean;
 429 }
 430
 431 /**
 432  * g_simple_async_result_set_from_error:
 433  * @simple: a #GSimpleAsyncResult.
 434  * @error: #GError.
 435  *
 436  * Sets the result from a #GError.
 437  **/
 438 void
 439 g_simple_async_result_set_from_error (GSimpleAsyncResult *simple,
 440                                       GError *error)
 441 {
 442   g_return_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple));
 443   g_return_if_fail (error != NULL);
 444
 445   simple->error = g_error_copy (error);
 446   simple->failed = TRUE;
 447 }
 448
 449 static GError*
 450 _g_error_new_valist (GQuark         domain,
 451                     gint           code,
 452                     const char    *format,
 453                     va_list        args)
 454 {
 455   GError *error;
 456   char *message;
 457
 458   message = g_strdup_vprintf (format, args);
 459
 460   error = g_error_new_literal (domain, code, message);
 461   g_free (message);
 462
 463   return error;
 464 }
 465
 466 /**
 467  * g_simple_async_result_set_error_va:
 468  * @simple: a #GSimpleAsyncResult.
 469  * @domain: a #GQuark (usually #G_IO_ERROR).
 470  * @code: an error code.
 471  * @format: a formatted error reporting string.
 472  * @args: va_list of arguments.
 473  *
 474  * Sets an error within the asynchronous result without a #GError. Unless
 475  * writing a binding, see g_simple_async_result_set_error().
 476  **/
 477 void
 478 g_simple_async_result_set_error_va (GSimpleAsyncResult *simple,
 479                                     GQuark         domain,
 480                                     gint           code,
 481                                     const char    *format,
 482                                     va_list        args)
 483 {
 484   g_return_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple));
 485   g_return_if_fail (domain != 0);
 486   g_return_if_fail (format != NULL);
 487
 488   simple->error = _g_error_new_valist (domain, code, format, args);
 489   simple->failed = TRUE;
 490 }
 491
 492 /**
 493  * g_simple_async_result_set_error:
 494  * @simple: a #GSimpleAsyncResult.
 495  * @domain: a #GQuark (usually #G_IO_ERROR).
 496  * @code: an error code.
 497  * @format: a formatted error reporting string.
 498  * @Varargs: a list of variables to fill in @format.
 499  *
 500  * Sets an error within the asynchronous result without a #GError.
 501  *
 502  **/
 503 void
 504 g_simple_async_result_set_error (GSimpleAsyncResult *simple,
 505                                  GQuark         domain,
 506                                  gint           code,
 507                                  const char    *format,
 508                                  ...)
 509 {
 510   va_list args;
 511
 512   g_return_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple));
 513   g_return_if_fail (domain != 0);
 514   g_return_if_fail (format != NULL);
 515
 516   va_start (args, format);
 517   g_simple_async_result_set_error_va (simple, domain, code, format, args);
 518   va_end (args);
 519 }
 520
 521 /**
 522  * g_simple_async_result_complete:
 523  * @simple: a #GSimpleAsyncResult.
 524  *
 525  * Completes an asynchronous I/O job.
 526  *
 527  **/
 528 void
 529 g_simple_async_result_complete (GSimpleAsyncResult *simple)
 530 {
 531   g_return_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple));
 532
 533   if (simple->callback)
 534     simple->callback (simple->source_object,
 535                       G_ASYNC_RESULT (simple),
 536                       simple->user_data);
 537 }
 538
 539 static gboolean
 540 complete_in_idle_cb (gpointer data)
 541 {
 542   GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (data);
 543
 544   g_simple_async_result_complete (simple);
 545
 546   return FALSE;
 547 }
 548
 549 /**
 550  * g_simple_async_result_complete_in_idle:
 551  * @simple: a #GSimpleAsyncResult.
 552  *
 553  * Completes an asynchronous function in the main event loop using
 554  * an idle function.
 555  *
 556  **/
 557 void
 558 g_simple_async_result_complete_in_idle (GSimpleAsyncResult *simple)
 559 {
 560   GSource *source;
 561   guint id;
 562
 563   g_return_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple));
 564
 565   g_object_ref (simple);
 566
 567   source = g_idle_source_new ();
 568   g_source_set_priority (source, G_PRIORITY_DEFAULT);
 569   g_source_set_callback (source, complete_in_idle_cb, simple, g_object_unref);
 570
 571   id = g_source_attach (source, NULL);
 572   g_source_unref (source);
 573 }
 574
 575 typedef struct {
 576   GSimpleAsyncResult *simple;
 577   GSimpleAsyncThreadFunc func;
 578 } RunInThreadData;
 579
 580 static void
 581 run_in_thread (GIOJob *job,
 582                GCancellable *c,
 583                gpointer _data)
 584 {
 585   RunInThreadData *data = _data;
 586   GSimpleAsyncResult *simple = data->simple;
 587
 588   if (simple->handle_cancellation &&
 589       g_cancellable_is_cancelled (c))
 590     {
 591        g_simple_async_result_set_error (simple,
 592                                         G_IO_ERROR,
 593                                         G_IO_ERROR_CANCELLED,
 594                                        _("Operation was cancelled"));
 595     }
 596   else
 597     {
 598       data->func (simple,
 599                   simple->source_object,
 600                   c);
 601     }
 602
 603   g_simple_async_result_complete_in_idle (data->simple);
 604   g_object_unref (data->simple);
 605   g_free (data);
 606 }
 607
 608 /**
 609  * g_simple_async_result_run_in_thread:
 610  * @simple: a #GSimpleAsyncResult.
 611  * @func: a #GSimpleAsyncThreadFunc.
 612  * @io_priority: the io priority of the request.
 613  * @cancellable: optional #GCancellable object, %NULL to ignore.
 614  *
 615  * Runs the asynchronous job in a separated thread.
 616  *
 617  **/
 618 void
 619 g_simple_async_result_run_in_thread (GSimpleAsyncResult *simple,
 620                                      GSimpleAsyncThreadFunc func,
 621                                      int io_priority,
 622                                      GCancellable *cancellable)
 623 {
 624   RunInThreadData *data;
 625
 626   g_return_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple));
 627   g_return_if_fail (func != NULL);
 628
 629   data = g_new (RunInThreadData, 1);
 630   data->func = func;
 631   data->simple = g_object_ref (simple);
 632   g_schedule_io_job (run_in_thread, data, NULL, io_priority, cancellable);
 633 }
 634
 635 /**
 636  * g_simple_async_report_error_in_idle:
 637  * @object:
 638  * @callback: a #GAsyncReadyCallback.
 639  * @user_data: user data passed to @callback.
 640  * @domain: a #GQuark containing the error domain (usually #G_IO_ERROR).
 641  * @code: a specific error code.
 642  * @format: a formatted error reporting string.
 643  * @Varargs: a list of variables to fill in @format.
 644  *
 645  * Reports an error in an idle function.
 646  *
 647  **/
 648 void
 649 g_simple_async_report_error_in_idle (GObject *object,
 650                                      GAsyncReadyCallback callback,
 651                                      gpointer user_data,
 652                                      GQuark         domain,
 653                                      gint           code,
 654                                      const char    *format,
 655                                      ...)
 656 {
 657   GSimpleAsyncResult *simple;
 658   va_list args;
 659
 660   g_return_if_fail (G_IS_OBJECT (object));
 661   g_return_if_fail (domain != 0);
 662   g_return_if_fail (format != NULL);
 663
 664   simple = g_simple_async_result_new (object,
 665                                       callback,
 666                                       user_data, NULL);
 667
 668   va_start (args, format);
 669   g_simple_async_result_set_error_va (simple, domain, code, format, args);
 670   va_end (args);
 671   g_simple_async_result_complete_in_idle (simple);
 672   g_object_unref (simple);
 673 }