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