gio/gcancellable.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, see <http://www.gnu.org/licenses/>.
  17  *
  18  * Author: Alexander Larsson <alexl@redhat.com>
  19  */
  20
  21 #include "config.h"
  22 #include "glib.h"
  23 #include <gioerror.h>
  24 #include "glib-private.h"
  25 #include "gcancellable.h"
  26 #include "glibintl.h"
  27
  28
  29 /**
  30  * SECTION:gcancellable
  31  * @short_description: Thread-safe Operation Cancellation Stack
  32  * @include: gio/gio.h
  33  *
  34  * GCancellable is a thread-safe operation cancellation stack used
  35  * throughout GIO to allow for cancellation of synchronous and
  36  * asynchronous operations.
  37  */
  38
  39 enum {
  40   CANCELLED,
  41   LAST_SIGNAL
  42 };
  43
  44 struct _GCancellablePrivate
  45 {
  46   guint cancelled : 1;
  47   guint cancelled_running : 1;
  48   guint cancelled_running_waiting : 1;
  49
  50   guint fd_refcount;
  51   GWakeup *wakeup;
  52 };
  53
  54 static guint signals[LAST_SIGNAL] = { 0 };
  55
  56 G_DEFINE_TYPE_WITH_PRIVATE (GCancellable, g_cancellable, G_TYPE_OBJECT)
  57
  58 static GPrivate current_cancellable;
  59 static GMutex cancellable_mutex;
  60 static GCond cancellable_cond;
  61
  62 static void
  63 g_cancellable_finalize (GObject *object)
  64 {
  65   GCancellable *cancellable = G_CANCELLABLE (object);
  66
  67   if (cancellable->priv->wakeup)
  68     GLIB_PRIVATE_CALL (g_wakeup_free) (cancellable->priv->wakeup);
  69
  70   G_OBJECT_CLASS (g_cancellable_parent_class)->finalize (object);
  71 }
  72
  73 static void
  74 g_cancellable_class_init (GCancellableClass *klass)
  75 {
  76   GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
  77
  78   gobject_class->finalize = g_cancellable_finalize;
  79
  80   /**
  81    * GCancellable::cancelled:
  82    * @cancellable: a #GCancellable.
  83    *
  84    * Emitted when the operation has been cancelled.
  85    *
  86    * Can be used by implementations of cancellable operations. If the
  87    * operation is cancelled from another thread, the signal will be
  88    * emitted in the thread that cancelled the operation, not the
  89    * thread that is running the operation.
  90    *
  91    * Note that disconnecting from this signal (or any signal) in a
  92    * multi-threaded program is prone to race conditions. For instance
  93    * it is possible that a signal handler may be invoked even after
  94    * a call to g_signal_handler_disconnect() for that handler has
  95    * already returned.
  96    *
  97    * There is also a problem when cancellation happens right before
  98    * connecting to the signal. If this happens the signal will
  99    * unexpectedly not be emitted, and checking before connecting to
 100    * the signal leaves a race condition where this is still happening.
 101    *
 102    * In order to make it safe and easy to connect handlers there
 103    * are two helper functions: g_cancellable_connect() and
 104    * g_cancellable_disconnect() which protect against problems
 105    * like this.
 106    *
 107    * An example of how to us this:
 108    * |[<!-- language="C" -->
 109    *     // Make sure we don't do unnecessary work if already cancelled
 110    *     if (g_cancellable_set_error_if_cancelled (cancellable, error))
 111    *       return;
 112    *
 113    *     // Set up all the data needed to be able to handle cancellation
 114    *     // of the operation
 115    *     my_data = my_data_new (...);
 116    *
 117    *     id = 0;
 118    *     if (cancellable)
 119    *       id = g_cancellable_connect (cancellable,
 120    *                                  G_CALLBACK (cancelled_handler)
 121    *                                  data, NULL);
 122    *
 123    *     // cancellable operation here...
 124    *
 125    *     g_cancellable_disconnect (cancellable, id);
 126    *
 127    *     // cancelled_handler is never called after this, it is now safe
 128    *     // to free the data
 129    *     my_data_free (my_data);
 130    * ]|
 131    *
 132    * Note that the cancelled signal is emitted in the thread that
 133    * the user cancelled from, which may be the main thread. So, the
 134    * cancellable signal should not do something that can block.
 135    */
 136   signals[CANCELLED] =
 137     g_signal_new (I_("cancelled"),
 138                   G_TYPE_FROM_CLASS (gobject_class),
 139                   G_SIGNAL_RUN_LAST,
 140                   G_STRUCT_OFFSET (GCancellableClass, cancelled),
 141                   NULL, NULL,
 142                   g_cclosure_marshal_VOID__VOID,
 143                   G_TYPE_NONE, 0);
 144
 145 }
 146
 147 static void
 148 g_cancellable_init (GCancellable *cancellable)
 149 {
 150   cancellable->priv = g_cancellable_get_instance_private (cancellable);
 151 }
 152
 153 /**
 154  * g_cancellable_new:
 155  *
 156  * Creates a new #GCancellable object.
 157  *
 158  * Applications that want to start one or more operations
 159  * that should be cancellable should create a #GCancellable
 160  * and pass it to the operations.
 161  *
 162  * One #GCancellable can be used in multiple consecutive
 163  * operations or in multiple concurrent operations.
 164  *
 165  * Returns: a #GCancellable.
 166  **/
 167 GCancellable *
 168 g_cancellable_new (void)
 169 {
 170   return g_object_new (G_TYPE_CANCELLABLE, NULL);
 171 }
 172
 173 /**
 174  * g_cancellable_push_current:
 175  * @cancellable: a #GCancellable object
 176  *
 177  * Pushes @cancellable onto the cancellable stack. The current
 178  * cancellable can then be received using g_cancellable_get_current().
 179  *
 180  * This is useful when implementing cancellable operations in
 181  * code that does not allow you to pass down the cancellable object.
 182  *
 183  * This is typically called automatically by e.g. #GFile operations,
 184  * so you rarely have to call this yourself.
 185  **/
 186 void
 187 g_cancellable_push_current (GCancellable *cancellable)
 188 {
 189   GSList *l;
 190
 191   g_return_if_fail (cancellable != NULL);
 192
 193   l = g_private_get (&current_cancellable);
 194   l = g_slist_prepend (l, cancellable);
 195   g_private_set (&current_cancellable, l);
 196 }
 197
 198 /**
 199  * g_cancellable_pop_current:
 200  * @cancellable: a #GCancellable object
 201  *
 202  * Pops @cancellable off the cancellable stack (verifying that @cancellable
 203  * is on the top of the stack).
 204  **/
 205 void
 206 g_cancellable_pop_current (GCancellable *cancellable)
 207 {
 208   GSList *l;
 209
 210   l = g_private_get (&current_cancellable);
 211
 212   g_return_if_fail (l != NULL);
 213   g_return_if_fail (l->data == cancellable);
 214
 215   l = g_slist_delete_link (l, l);
 216   g_private_set (&current_cancellable, l);
 217 }
 218
 219 /**
 220  * g_cancellable_get_current:
 221  *
 222  * Gets the top cancellable from the stack.
 223  *
 224  * Returns: (nullable) (transfer none): a #GCancellable from the top
 225  * of the stack, or %NULL if the stack is empty.
 226  **/
 227 GCancellable *
 228 g_cancellable_get_current  (void)
 229 {
 230   GSList *l;
 231
 232   l = g_private_get (&current_cancellable);
 233   if (l == NULL)
 234     return NULL;
 235
 236   return G_CANCELLABLE (l->data);
 237 }
 238
 239 /**
 240  * g_cancellable_reset:
 241  * @cancellable: a #GCancellable object.
 242  *
 243  * Resets @cancellable to its uncancelled state.
 244  *
 245  * If cancellable is currently in use by any cancellable operation
 246  * then the behavior of this function is undefined.
 247  *
 248  * Note that it is generally not a good idea to reuse an existing
 249  * cancellable for more operations after it has been cancelled once,
 250  * as this function might tempt you to do. The recommended practice
 251  * is to drop the reference to a cancellable after cancelling it,
 252  * and let it die with the outstanding async operations. You should
 253  * create a fresh cancellable for further async operations.
 254  **/
 255 void
 256 g_cancellable_reset (GCancellable *cancellable)
 257 {
 258   GCancellablePrivate *priv;
 259
 260   g_return_if_fail (G_IS_CANCELLABLE (cancellable));
 261
 262   g_mutex_lock (&cancellable_mutex);
 263
 264   priv = cancellable->priv;
 265
 266   while (priv->cancelled_running)
 267     {
 268       priv->cancelled_running_waiting = TRUE;
 269       g_cond_wait (&cancellable_cond, &cancellable_mutex);
 270     }
 271
 272   if (priv->cancelled)
 273     {
 274       if (priv->wakeup)
 275         GLIB_PRIVATE_CALL (g_wakeup_acknowledge) (priv->wakeup);
 276
 277       priv->cancelled = FALSE;
 278     }
 279
 280   g_mutex_unlock (&cancellable_mutex);
 281 }
 282
 283 /**
 284  * g_cancellable_is_cancelled:
 285  * @cancellable: (allow-none): a #GCancellable or %NULL
 286  *
 287  * Checks if a cancellable job has been cancelled.
 288  *
 289  * Returns: %TRUE if @cancellable is cancelled,
 290  * FALSE if called with %NULL or if item is not cancelled.
 291  **/
 292 gboolean
 293 g_cancellable_is_cancelled (GCancellable *cancellable)
 294 {
 295   return cancellable != NULL && cancellable->priv->cancelled;
 296 }
 297
 298 /**
 299  * g_cancellable_set_error_if_cancelled:
 300  * @cancellable: (allow-none): a #GCancellable or %NULL
 301  * @error: #GError to append error state to
 302  *
 303  * If the @cancellable is cancelled, sets the error to notify
 304  * that the operation was cancelled.
 305  *
 306  * Returns: %TRUE if @cancellable was cancelled, %FALSE if it was not
 307  */
 308 gboolean
 309 g_cancellable_set_error_if_cancelled (GCancellable  *cancellable,
 310                                       GError       **error)
 311 {
 312   if (g_cancellable_is_cancelled (cancellable))
 313     {
 314       g_set_error_literal (error,
 315                            G_IO_ERROR,
 316                            G_IO_ERROR_CANCELLED,
 317                            _("Operation was cancelled"));
 318       return TRUE;
 319     }
 320
 321   return FALSE;
 322 }
 323
 324 /**
 325  * g_cancellable_get_fd:
 326  * @cancellable: a #GCancellable.
 327  *
 328  * Gets the file descriptor for a cancellable job. This can be used to
 329  * implement cancellable operations on Unix systems. The returned fd will
 330  * turn readable when @cancellable is cancelled.
 331  *
 332  * You are not supposed to read from the fd yourself, just check for
 333  * readable status. Reading to unset the readable status is done
 334  * with g_cancellable_reset().
 335  *
 336  * After a successful return from this function, you should use
 337  * g_cancellable_release_fd() to free up resources allocated for
 338  * the returned file descriptor.
 339  *
 340  * See also g_cancellable_make_pollfd().
 341  *
 342  * Returns: A valid file descriptor. %-1 if the file descriptor
 343  * is not supported, or on errors.
 344  **/
 345 int
 346 g_cancellable_get_fd (GCancellable *cancellable)
 347 {
 348   GPollFD pollfd;
 349
 350   if (cancellable == NULL)
 351           return -1;
 352
 353 #ifdef G_OS_WIN32
 354   pollfd.fd = -1;
 355 #else
 356   g_cancellable_make_pollfd (cancellable, &pollfd);
 357 #endif
 358
 359   return pollfd.fd;
 360 }
 361
 362 /**
 363  * g_cancellable_make_pollfd:
 364  * @cancellable: (allow-none): a #GCancellable or %NULL
 365  * @pollfd: a pointer to a #GPollFD
 366  *
 367  * Creates a #GPollFD corresponding to @cancellable; this can be passed
 368  * to g_poll() and used to poll for cancellation. This is useful both
 369  * for unix systems without a native poll and for portability to
 370  * windows.
 371  *
 372  * When this function returns %TRUE, you should use
 373  * g_cancellable_release_fd() to free up resources allocated for the
 374  * @pollfd. After a %FALSE return, do not call g_cancellable_release_fd().
 375  *
 376  * If this function returns %FALSE, either no @cancellable was given or
 377  * resource limits prevent this function from allocating the necessary
 378  * structures for polling. (On Linux, you will likely have reached
 379  * the maximum number of file descriptors.) The suggested way to handle
 380  * these cases is to ignore the @cancellable.
 381  *
 382  * You are not supposed to read from the fd yourself, just check for
 383  * readable status. Reading to unset the readable status is done
 384  * with g_cancellable_reset().
 385  *
 386  * Returns: %TRUE if @pollfd was successfully initialized, %FALSE on
 387  *          failure to prepare the cancellable.
 388  *
 389  * Since: 2.22
 390  **/
 391 gboolean
 392 g_cancellable_make_pollfd (GCancellable *cancellable, GPollFD *pollfd)
 393 {
 394   g_return_val_if_fail (pollfd != NULL, FALSE);
 395   if (cancellable == NULL)
 396     return FALSE;
 397   g_return_val_if_fail (G_IS_CANCELLABLE (cancellable), FALSE);
 398
 399   g_mutex_lock (&cancellable_mutex);
 400
 401   cancellable->priv->fd_refcount++;
 402
 403   if (cancellable->priv->wakeup == NULL)
 404     {
 405       cancellable->priv->wakeup = GLIB_PRIVATE_CALL (g_wakeup_new) ();
 406
 407       if (cancellable->priv->cancelled)
 408         GLIB_PRIVATE_CALL (g_wakeup_signal) (cancellable->priv->wakeup);
 409     }
 410
 411   GLIB_PRIVATE_CALL (g_wakeup_get_pollfd) (cancellable->priv->wakeup, pollfd);
 412
 413   g_mutex_unlock (&cancellable_mutex);
 414
 415   return TRUE;
 416 }
 417
 418 /**
 419  * g_cancellable_release_fd:
 420  * @cancellable: a #GCancellable
 421  *
 422  * Releases a resources previously allocated by g_cancellable_get_fd()
 423  * or g_cancellable_make_pollfd().
 424  *
 425  * For compatibility reasons with older releases, calling this function
 426  * is not strictly required, the resources will be automatically freed
 427  * when the @cancellable is finalized. However, the @cancellable will
 428  * block scarce file descriptors until it is finalized if this function
 429  * is not called. This can cause the application to run out of file
 430  * descriptors when many #GCancellables are used at the same time.
 431  *
 432  * Since: 2.22
 433  **/
 434 void
 435 g_cancellable_release_fd (GCancellable *cancellable)
 436 {
 437   GCancellablePrivate *priv;
 438
 439   if (cancellable == NULL)
 440     return;
 441
 442   g_return_if_fail (G_IS_CANCELLABLE (cancellable));
 443   g_return_if_fail (cancellable->priv->fd_refcount > 0);
 444
 445   priv = cancellable->priv;
 446
 447   g_mutex_lock (&cancellable_mutex);
 448
 449   priv->fd_refcount--;
 450   if (priv->fd_refcount == 0)
 451     {
 452       GLIB_PRIVATE_CALL (g_wakeup_free) (priv->wakeup);
 453       priv->wakeup = NULL;
 454     }
 455
 456   g_mutex_unlock (&cancellable_mutex);
 457 }
 458
 459 /**
 460  * g_cancellable_cancel:
 461  * @cancellable: a #GCancellable object.
 462  *
 463  * Will set @cancellable to cancelled, and will emit the
 464  * #GCancellable::cancelled signal. (However, see the warning about
 465  * race conditions in the documentation for that signal if you are
 466  * planning to connect to it.)
 467  *
 468  * This function is thread-safe. In other words, you can safely call
 469  * it from a thread other than the one running the operation that was
 470  * passed the @cancellable.
 471  *
 472  * The convention within gio is that cancelling an asynchronous
 473  * operation causes it to complete asynchronously. That is, if you
 474  * cancel the operation from the same thread in which it is running,
 475  * then the operation's #GAsyncReadyCallback will not be invoked until
 476  * the application returns to the main loop.
 477  **/
 478 void
 479 g_cancellable_cancel (GCancellable *cancellable)
 480 {
 481   GCancellablePrivate *priv;
 482
 483   if (cancellable == NULL ||
 484       cancellable->priv->cancelled)
 485     return;
 486
 487   priv = cancellable->priv;
 488
 489   g_mutex_lock (&cancellable_mutex);
 490
 491   if (priv->cancelled)
 492     {
 493       g_mutex_unlock (&cancellable_mutex);
 494       return;
 495     }
 496
 497   priv->cancelled = TRUE;
 498   priv->cancelled_running = TRUE;
 499
 500   if (priv->wakeup)
 501     GLIB_PRIVATE_CALL (g_wakeup_signal) (priv->wakeup);
 502
 503   g_mutex_unlock (&cancellable_mutex);
 504
 505   g_object_ref (cancellable);
 506   g_signal_emit (cancellable, signals[CANCELLED], 0);
 507
 508   g_mutex_lock (&cancellable_mutex);
 509
 510   priv->cancelled_running = FALSE;
 511   if (priv->cancelled_running_waiting)
 512     g_cond_broadcast (&cancellable_cond);
 513   priv->cancelled_running_waiting = FALSE;
 514
 515   g_mutex_unlock (&cancellable_mutex);
 516
 517   g_object_unref (cancellable);
 518 }
 519
 520 /**
 521  * g_cancellable_connect:
 522  * @cancellable: A #GCancellable.
 523  * @callback: The #GCallback to connect.
 524  * @data: Data to pass to @callback.
 525  * @data_destroy_func: (allow-none): Free function for @data or %NULL.
 526  *
 527  * Convenience function to connect to the #GCancellable::cancelled
 528  * signal. Also handles the race condition that may happen
 529  * if the cancellable is cancelled right before connecting.
 530  *
 531  * @callback is called at most once, either directly at the
 532  * time of the connect if @cancellable is already cancelled,
 533  * or when @cancellable is cancelled in some thread.
 534  *
 535  * @data_destroy_func will be called when the handler is
 536  * disconnected, or immediately if the cancellable is already
 537  * cancelled.
 538  *
 539  * See #GCancellable::cancelled for details on how to use this.
 540  *
 541  * Since GLib 2.40, the lock protecting @cancellable is not held when
 542  * @callback is invoked.  This lifts a restriction in place for
 543  * earlier GLib versions which now makes it easier to write cleanup
 544  * code that unconditionally invokes e.g. g_cancellable_cancel().
 545  *
 546  * Returns: The id of the signal handler or 0 if @cancellable has already
 547  *          been cancelled.
 548  *
 549  * Since: 2.22
 550  */
 551 gulong
 552 g_cancellable_connect (GCancellable   *cancellable,
 553                        GCallback       callback,
 554                        gpointer        data,
 555                        GDestroyNotify  data_destroy_func)
 556 {
 557   gulong id;
 558
 559   g_return_val_if_fail (G_IS_CANCELLABLE (cancellable), 0);
 560
 561   g_mutex_lock (&cancellable_mutex);
 562
 563   if (cancellable->priv->cancelled)
 564     {
 565       void (*_callback) (GCancellable *cancellable,
 566                          gpointer      user_data);
 567
 568       g_mutex_unlock (&cancellable_mutex);
 569
 570       _callback = (void *)callback;
 571       id = 0;
 572
 573       _callback (cancellable, data);
 574
 575       if (data_destroy_func)
 576         data_destroy_func (data);
 577     }
 578   else
 579     {
 580       id = g_signal_connect_data (cancellable, "cancelled",
 581                                   callback, data,
 582                                   (GClosureNotify) data_destroy_func,
 583                                   0);
 584
 585       g_mutex_unlock (&cancellable_mutex);
 586     }
 587
 588
 589   return id;
 590 }
 591
 592 /**
 593  * g_cancellable_disconnect:
 594  * @cancellable: (allow-none): A #GCancellable or %NULL.
 595  * @handler_id: Handler id of the handler to be disconnected, or %0.
 596  *
 597  * Disconnects a handler from a cancellable instance similar to
 598  * g_signal_handler_disconnect().  Additionally, in the event that a
 599  * signal handler is currently running, this call will block until the
 600  * handler has finished.  Calling this function from a
 601  * #GCancellable::cancelled signal handler will therefore result in a
 602  * deadlock.
 603  *
 604  * This avoids a race condition where a thread cancels at the
 605  * same time as the cancellable operation is finished and the
 606  * signal handler is removed. See #GCancellable::cancelled for
 607  * details on how to use this.
 608  *
 609  * If @cancellable is %NULL or @handler_id is %0 this function does
 610  * nothing.
 611  *
 612  * Since: 2.22
 613  */
 614 void
 615 g_cancellable_disconnect (GCancellable  *cancellable,
 616                           gulong         handler_id)
 617 {
 618   GCancellablePrivate *priv;
 619
 620   if (handler_id == 0 ||  cancellable == NULL)
 621     return;
 622
 623   g_mutex_lock (&cancellable_mutex);
 624
 625   priv = cancellable->priv;
 626
 627   while (priv->cancelled_running)
 628     {
 629       priv->cancelled_running_waiting = TRUE;
 630       g_cond_wait (&cancellable_cond, &cancellable_mutex);
 631     }
 632
 633   g_signal_handler_disconnect (cancellable, handler_id);
 634
 635   g_mutex_unlock (&cancellable_mutex);
 636 }
 637
 638 typedef struct {
 639   GSource       source;
 640
 641   GCancellable *cancellable;
 642   guint         cancelled_handler;
 643 } GCancellableSource;
 644
 645 static void
 646 cancellable_source_cancelled (GCancellable *cancellable,
 647                               gpointer      user_data)
 648 {
 649   GSource *source = user_data;
 650
 651   if (!g_source_is_destroyed (source))
 652     g_source_set_ready_time (source, 0);
 653 }
 654
 655 static gboolean
 656 cancellable_source_dispatch (GSource     *source,
 657                              GSourceFunc  callback,
 658                              gpointer     user_data)
 659 {
 660   GCancellableSourceFunc func = (GCancellableSourceFunc)callback;
 661   GCancellableSource *cancellable_source = (GCancellableSource *)source;
 662
 663   g_source_set_ready_time (source, -1);
 664   return (*func) (cancellable_source->cancellable, user_data);
 665 }
 666
 667 static void
 668 cancellable_source_finalize (GSource *source)
 669 {
 670   GCancellableSource *cancellable_source = (GCancellableSource *)source;
 671
 672   if (cancellable_source->cancellable)
 673     {
 674       g_cancellable_disconnect (cancellable_source->cancellable,
 675                                 cancellable_source->cancelled_handler);
 676       g_object_unref (cancellable_source->cancellable);
 677     }
 678 }
 679
 680 static gboolean
 681 cancellable_source_closure_callback (GCancellable *cancellable,
 682                                      gpointer      data)
 683 {
 684   GClosure *closure = data;
 685
 686   GValue params = G_VALUE_INIT;
 687   GValue result_value = G_VALUE_INIT;
 688   gboolean result;
 689
 690   g_value_init (&result_value, G_TYPE_BOOLEAN);
 691
 692   g_value_init (&params, G_TYPE_CANCELLABLE);
 693   g_value_set_object (&params, cancellable);
 694
 695   g_closure_invoke (closure, &result_value, 1, &params, NULL);
 696
 697   result = g_value_get_boolean (&result_value);
 698   g_value_unset (&result_value);
 699   g_value_unset (&params);
 700
 701   return result;
 702 }
 703
 704 static GSourceFuncs cancellable_source_funcs =
 705 {
 706   NULL,
 707   NULL,
 708   cancellable_source_dispatch,
 709   cancellable_source_finalize,
 710   (GSourceFunc)cancellable_source_closure_callback,
 711 };
 712
 713 /**
 714  * g_cancellable_source_new: (skip)
 715  * @cancellable: (allow-none): a #GCancellable, or %NULL
 716  *
 717  * Creates a source that triggers if @cancellable is cancelled and
 718  * calls its callback of type #GCancellableSourceFunc. This is
 719  * primarily useful for attaching to another (non-cancellable) source
 720  * with g_source_add_child_source() to add cancellability to it.
 721  *
 722  * For convenience, you can call this with a %NULL #GCancellable,
 723  * in which case the source will never trigger.
 724  *
 725  * The new #GSource will hold a reference to the #GCancellable.
 726  *
 727  * Returns: (transfer full): the new #GSource.
 728  *
 729  * Since: 2.28
 730  */
 731 GSource *
 732 g_cancellable_source_new (GCancellable *cancellable)
 733 {
 734   GSource *source;
 735   GCancellableSource *cancellable_source;
 736
 737   source = g_source_new (&cancellable_source_funcs, sizeof (GCancellableSource));
 738   g_source_set_name (source, "GCancellable");
 739   cancellable_source = (GCancellableSource *)source;
 740
 741   if (cancellable)
 742     {
 743       cancellable_source->cancellable = g_object_ref (cancellable);
 744
 745       /* We intentionally don't use g_cancellable_connect() here,
 746        * because we don't want the "at most once" behavior.
 747        */
 748       cancellable_source->cancelled_handler =
 749         g_signal_connect (cancellable, "cancelled",
 750                           G_CALLBACK (cancellable_source_cancelled),
 751                           source);
 752       if (g_cancellable_is_cancelled (cancellable))
 753         g_source_set_ready_time (source, 0);
 754     }
 755
 756   return source;
 757 }