1 /* GIO - GLib Input, Output and Streaming Library
3 * Copyright (C) 2006-2007 Red Hat, Inc.
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.
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.
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.
20 * Author: Alexander Larsson <alexl@redhat.com>
26 #include "glib-private.h"
27 #include "gcancellable.h"
32 * SECTION:gcancellable
33 * @short_description: Thread-safe Operation Cancellation Stack
36 * GCancellable is a thread-safe operation cancellation stack used
37 * throughout GIO to allow for cancellation of synchronous and
38 * asynchronous operations.
46 struct _GCancellablePrivate
49 guint cancelled_running
: 1;
50 guint cancelled_running_waiting
: 1;
56 static guint signals
[LAST_SIGNAL
] = { 0 };
58 G_DEFINE_TYPE (GCancellable
, g_cancellable
, G_TYPE_OBJECT
);
60 static GPrivate current_cancellable
;
61 static GMutex cancellable_mutex
;
62 static GCond cancellable_cond
;
65 g_cancellable_finalize (GObject
*object
)
67 GCancellable
*cancellable
= G_CANCELLABLE (object
);
69 if (cancellable
->priv
->wakeup
)
70 GLIB_PRIVATE_CALL (g_wakeup_free
) (cancellable
->priv
->wakeup
);
72 G_OBJECT_CLASS (g_cancellable_parent_class
)->finalize (object
);
76 g_cancellable_class_init (GCancellableClass
*klass
)
78 GObjectClass
*gobject_class
= G_OBJECT_CLASS (klass
);
80 g_type_class_add_private (klass
, sizeof (GCancellablePrivate
));
82 gobject_class
->finalize
= g_cancellable_finalize
;
85 * GCancellable::cancelled:
86 * @cancellable: a #GCancellable.
88 * Emitted when the operation has been cancelled.
90 * Can be used by implementations of cancellable operations. If the
91 * operation is cancelled from another thread, the signal will be
92 * emitted in the thread that cancelled the operation, not the
93 * thread that is running the operation.
95 * Note that disconnecting from this signal (or any signal) in a
96 * multi-threaded program is prone to race conditions. For instance
97 * it is possible that a signal handler may be invoked even
98 * <emphasis>after</emphasis> a call to
99 * g_signal_handler_disconnect() for that handler has already
102 * There is also a problem when cancellation happen
103 * right before connecting to the signal. If this happens the
104 * signal will unexpectedly not be emitted, and checking before
105 * connecting to the signal leaves a race condition where this is
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
113 * An example of how to us this:
115 * /<!-- -->* Make sure we don't do any unnecessary work if already cancelled *<!-- -->/
116 * if (g_cancellable_set_error_if_cancelled (cancellable))
119 * /<!-- -->* Set up all the data needed to be able to
120 * * handle cancellation of the operation *<!-- -->/
121 * my_data = my_data_new (...);
125 * id = g_cancellable_connect (cancellable,
126 * G_CALLBACK (cancelled_handler)
129 * /<!-- -->* cancellable operation here... *<!-- -->/
131 * g_cancellable_disconnect (cancellable, id);
133 * /<!-- -->* cancelled_handler is never called after this, it
134 * * is now safe to free the data *<!-- -->/
135 * my_data_free (my_data);
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.
143 g_signal_new (I_("cancelled"),
144 G_TYPE_FROM_CLASS (gobject_class
),
146 G_STRUCT_OFFSET (GCancellableClass
, cancelled
),
148 g_cclosure_marshal_VOID__VOID
,
154 g_cancellable_init (GCancellable
*cancellable
)
156 cancellable
->priv
= G_TYPE_INSTANCE_GET_PRIVATE (cancellable
,
158 GCancellablePrivate
);
164 * Creates a new #GCancellable object.
166 * Applications that want to start one or more operations
167 * that should be cancellable should create a #GCancellable
168 * and pass it to the operations.
170 * One #GCancellable can be used in multiple consecutive
171 * operations or in multiple concurrent operations.
173 * Returns: a #GCancellable.
176 g_cancellable_new (void)
178 return g_object_new (G_TYPE_CANCELLABLE
, NULL
);
182 * g_cancellable_push_current:
183 * @cancellable: a #GCancellable object
185 * Pushes @cancellable onto the cancellable stack. The current
186 * cancellable can then be received using g_cancellable_get_current().
188 * This is useful when implementing cancellable operations in
189 * code that does not allow you to pass down the cancellable object.
191 * This is typically called automatically by e.g. #GFile operations,
192 * so you rarely have to call this yourself.
195 g_cancellable_push_current (GCancellable
*cancellable
)
199 g_return_if_fail (cancellable
!= NULL
);
201 l
= g_private_get (¤t_cancellable
);
202 l
= g_slist_prepend (l
, cancellable
);
203 g_private_set (¤t_cancellable
, l
);
207 * g_cancellable_pop_current:
208 * @cancellable: a #GCancellable object
210 * Pops @cancellable off the cancellable stack (verifying that @cancellable
211 * is on the top of the stack).
214 g_cancellable_pop_current (GCancellable
*cancellable
)
218 l
= g_private_get (¤t_cancellable
);
220 g_return_if_fail (l
!= NULL
);
221 g_return_if_fail (l
->data
== cancellable
);
223 l
= g_slist_delete_link (l
, l
);
224 g_private_set (¤t_cancellable
, l
);
228 * g_cancellable_get_current:
230 * Gets the top cancellable from the stack.
232 * Returns: (transfer none): a #GCancellable from the top of the stack, or %NULL
233 * if the stack is empty.
236 g_cancellable_get_current (void)
240 l
= g_private_get (¤t_cancellable
);
244 return G_CANCELLABLE (l
->data
);
248 * g_cancellable_reset:
249 * @cancellable: a #GCancellable object.
251 * Resets @cancellable to its uncancelled state.
253 * If cancellable is currently in use by any cancellable operation
254 * then the behavior of this function is undefined.
257 g_cancellable_reset (GCancellable
*cancellable
)
259 GCancellablePrivate
*priv
;
261 g_return_if_fail (G_IS_CANCELLABLE (cancellable
));
263 g_mutex_lock (&cancellable_mutex
);
265 priv
= cancellable
->priv
;
267 while (priv
->cancelled_running
)
269 priv
->cancelled_running_waiting
= TRUE
;
270 g_cond_wait (&cancellable_cond
, &cancellable_mutex
);
276 GLIB_PRIVATE_CALL (g_wakeup_acknowledge
) (priv
->wakeup
);
278 priv
->cancelled
= FALSE
;
281 g_mutex_unlock (&cancellable_mutex
);
285 * g_cancellable_is_cancelled:
286 * @cancellable: (allow-none): a #GCancellable or %NULL
288 * Checks if a cancellable job has been cancelled.
290 * Returns: %TRUE if @cancellable is cancelled,
291 * FALSE if called with %NULL or if item is not cancelled.
294 g_cancellable_is_cancelled (GCancellable
*cancellable
)
296 return cancellable
!= NULL
&& cancellable
->priv
->cancelled
;
300 * g_cancellable_set_error_if_cancelled:
301 * @cancellable: (allow-none): a #GCancellable or %NULL
302 * @error: #GError to append error state to
304 * If the @cancellable is cancelled, sets the error to notify
305 * that the operation was cancelled.
307 * Returns: %TRUE if @cancellable was cancelled, %FALSE if it was not
310 g_cancellable_set_error_if_cancelled (GCancellable
*cancellable
,
313 if (g_cancellable_is_cancelled (cancellable
))
315 g_set_error_literal (error
,
317 G_IO_ERROR_CANCELLED
,
318 _("Operation was cancelled"));
326 * g_cancellable_get_fd:
327 * @cancellable: a #GCancellable.
329 * Gets the file descriptor for a cancellable job. This can be used to
330 * implement cancellable operations on Unix systems. The returned fd will
331 * turn readable when @cancellable is cancelled.
333 * You are not supposed to read from the fd yourself, just check for
334 * readable status. Reading to unset the readable status is done
335 * with g_cancellable_reset().
337 * After a successful return from this function, you should use
338 * g_cancellable_release_fd() to free up resources allocated for
339 * the returned file descriptor.
341 * See also g_cancellable_make_pollfd().
343 * Returns: A valid file descriptor. %-1 if the file descriptor
344 * is not supported, or on errors.
347 g_cancellable_get_fd (GCancellable
*cancellable
)
351 if (cancellable
== NULL
)
357 g_cancellable_make_pollfd (cancellable
, &pollfd
);
364 * g_cancellable_make_pollfd:
365 * @cancellable: (allow-none): a #GCancellable or %NULL
366 * @pollfd: a pointer to a #GPollFD
368 * Creates a #GPollFD corresponding to @cancellable; this can be passed
369 * to g_poll() and used to poll for cancellation. This is useful both
370 * for unix systems without a native poll and for portability to
373 * When this function returns %TRUE, you should use
374 * g_cancellable_release_fd() to free up resources allocated for the
375 * @pollfd. After a %FALSE return, do not call g_cancellable_release_fd().
377 * If this function returns %FALSE, either no @cancellable was given or
378 * resource limits prevent this function from allocating the necessary
379 * structures for polling. (On Linux, you will likely have reached
380 * the maximum number of file descriptors.) The suggested way to handle
381 * these cases is to ignore the @cancellable.
383 * You are not supposed to read from the fd yourself, just check for
384 * readable status. Reading to unset the readable status is done
385 * with g_cancellable_reset().
387 * Returns: %TRUE if @pollfd was successfully initialized, %FALSE on
388 * failure to prepare the cancellable.
393 g_cancellable_make_pollfd (GCancellable
*cancellable
, GPollFD
*pollfd
)
395 g_return_val_if_fail (pollfd
!= NULL
, FALSE
);
396 if (cancellable
== NULL
)
398 g_return_val_if_fail (G_IS_CANCELLABLE (cancellable
), FALSE
);
400 g_mutex_lock (&cancellable_mutex
);
402 cancellable
->priv
->fd_refcount
++;
404 if (cancellable
->priv
->wakeup
== NULL
)
406 cancellable
->priv
->wakeup
= GLIB_PRIVATE_CALL (g_wakeup_new
) ();
408 if (cancellable
->priv
->cancelled
)
409 GLIB_PRIVATE_CALL (g_wakeup_signal
) (cancellable
->priv
->wakeup
);
412 GLIB_PRIVATE_CALL (g_wakeup_get_pollfd
) (cancellable
->priv
->wakeup
, pollfd
);
414 g_mutex_unlock (&cancellable_mutex
);
420 * g_cancellable_release_fd:
421 * @cancellable: a #GCancellable
423 * Releases a resources previously allocated by g_cancellable_get_fd()
424 * or g_cancellable_make_pollfd().
426 * For compatibility reasons with older releases, calling this function
427 * is not strictly required, the resources will be automatically freed
428 * when the @cancellable is finalized. However, the @cancellable will
429 * block scarce file descriptors until it is finalized if this function
430 * is not called. This can cause the application to run out of file
431 * descriptors when many #GCancellables are used at the same time.
436 g_cancellable_release_fd (GCancellable
*cancellable
)
438 GCancellablePrivate
*priv
;
440 if (cancellable
== NULL
)
443 g_return_if_fail (G_IS_CANCELLABLE (cancellable
));
444 g_return_if_fail (cancellable
->priv
->fd_refcount
> 0);
446 priv
= cancellable
->priv
;
448 g_mutex_lock (&cancellable_mutex
);
451 if (priv
->fd_refcount
== 0)
453 GLIB_PRIVATE_CALL (g_wakeup_free
) (priv
->wakeup
);
457 g_mutex_unlock (&cancellable_mutex
);
461 * g_cancellable_cancel:
462 * @cancellable: a #GCancellable object.
464 * Will set @cancellable to cancelled, and will emit the
465 * #GCancellable::cancelled signal. (However, see the warning about
466 * race conditions in the documentation for that signal if you are
467 * planning to connect to it.)
469 * This function is thread-safe. In other words, you can safely call
470 * it from a thread other than the one running the operation that was
471 * passed the @cancellable.
473 * The convention within gio is that cancelling an asynchronous
474 * operation causes it to complete asynchronously. That is, if you
475 * cancel the operation from the same thread in which it is running,
476 * then the operation's #GAsyncReadyCallback will not be invoked until
477 * the application returns to the main loop.
480 g_cancellable_cancel (GCancellable
*cancellable
)
482 GCancellablePrivate
*priv
;
484 if (cancellable
== NULL
||
485 cancellable
->priv
->cancelled
)
488 priv
= cancellable
->priv
;
490 g_mutex_lock (&cancellable_mutex
);
494 g_mutex_unlock (&cancellable_mutex
);
498 priv
->cancelled
= TRUE
;
499 priv
->cancelled_running
= TRUE
;
502 GLIB_PRIVATE_CALL (g_wakeup_signal
) (priv
->wakeup
);
504 g_mutex_unlock (&cancellable_mutex
);
506 g_object_ref (cancellable
);
507 g_signal_emit (cancellable
, signals
[CANCELLED
], 0);
509 g_mutex_lock (&cancellable_mutex
);
511 priv
->cancelled_running
= FALSE
;
512 if (priv
->cancelled_running_waiting
)
513 g_cond_broadcast (&cancellable_cond
);
514 priv
->cancelled_running_waiting
= FALSE
;
516 g_mutex_unlock (&cancellable_mutex
);
518 g_object_unref (cancellable
);
522 * g_cancellable_connect:
523 * @cancellable: A #GCancellable.
524 * @callback: The #GCallback to connect.
525 * @data: Data to pass to @callback.
526 * @data_destroy_func: (allow-none): Free function for @data or %NULL.
528 * Convenience function to connect to the #GCancellable::cancelled
529 * signal. Also handles the race condition that may happen
530 * if the cancellable is cancelled right before connecting.
532 * @callback is called at most once, either directly at the
533 * time of the connect if @cancellable is already cancelled,
534 * or when @cancellable is cancelled in some thread.
536 * @data_destroy_func will be called when the handler is
537 * disconnected, or immediately if the cancellable is already
540 * See #GCancellable::cancelled for details on how to use this.
542 * Returns: The id of the signal handler or 0 if @cancellable has already
548 g_cancellable_connect (GCancellable
*cancellable
,
551 GDestroyNotify data_destroy_func
)
555 g_return_val_if_fail (G_IS_CANCELLABLE (cancellable
), 0);
557 g_mutex_lock (&cancellable_mutex
);
559 if (cancellable
->priv
->cancelled
)
561 void (*_callback
) (GCancellable
*cancellable
,
564 _callback
= (void *)callback
;
567 _callback (cancellable
, data
);
569 if (data_destroy_func
)
570 data_destroy_func (data
);
574 id
= g_signal_connect_data (cancellable
, "cancelled",
576 (GClosureNotify
) data_destroy_func
,
580 g_mutex_unlock (&cancellable_mutex
);
586 * g_cancellable_disconnect:
587 * @cancellable: (allow-none): A #GCancellable or %NULL.
588 * @handler_id: Handler id of the handler to be disconnected, or %0.
590 * Disconnects a handler from a cancellable instance similar to
591 * g_signal_handler_disconnect(). Additionally, in the event that a
592 * signal handler is currently running, this call will block until the
593 * handler has finished. Calling this function from a
594 * #GCancellable::cancelled signal handler will therefore result in a
597 * This avoids a race condition where a thread cancels at the
598 * same time as the cancellable operation is finished and the
599 * signal handler is removed. See #GCancellable::cancelled for
600 * details on how to use this.
602 * If @cancellable is %NULL or @handler_id is %0 this function does
608 g_cancellable_disconnect (GCancellable
*cancellable
,
611 GCancellablePrivate
*priv
;
613 if (handler_id
== 0 || cancellable
== NULL
)
616 g_mutex_lock (&cancellable_mutex
);
618 priv
= cancellable
->priv
;
620 while (priv
->cancelled_running
)
622 priv
->cancelled_running_waiting
= TRUE
;
623 g_cond_wait (&cancellable_cond
, &cancellable_mutex
);
626 g_signal_handler_disconnect (cancellable
, handler_id
);
628 g_mutex_unlock (&cancellable_mutex
);
634 GCancellable
*cancellable
;
635 } GCancellableSource
;
638 cancellable_source_cancelled (GCancellable
*cancellable
,
641 GSource
*source
= user_data
;
643 g_main_context_wakeup (g_source_get_context (source
));
647 cancellable_source_prepare (GSource
*source
,
650 GCancellableSource
*cancellable_source
= (GCancellableSource
*)source
;
653 return g_cancellable_is_cancelled (cancellable_source
->cancellable
);
657 cancellable_source_check (GSource
*source
)
659 GCancellableSource
*cancellable_source
= (GCancellableSource
*)source
;
661 return g_cancellable_is_cancelled (cancellable_source
->cancellable
);
665 cancellable_source_dispatch (GSource
*source
,
666 GSourceFunc callback
,
669 GCancellableSourceFunc func
= (GCancellableSourceFunc
)callback
;
670 GCancellableSource
*cancellable_source
= (GCancellableSource
*)source
;
672 return (*func
) (cancellable_source
->cancellable
, user_data
);
676 cancellable_source_finalize (GSource
*source
)
678 GCancellableSource
*cancellable_source
= (GCancellableSource
*)source
;
680 if (cancellable_source
->cancellable
)
682 g_signal_handlers_disconnect_by_func (cancellable_source
->cancellable
,
683 G_CALLBACK (cancellable_source_cancelled
),
685 g_object_unref (cancellable_source
->cancellable
);
690 cancellable_source_closure_callback (GCancellable
*cancellable
,
693 GClosure
*closure
= data
;
695 GValue params
= G_VALUE_INIT
;
696 GValue result_value
= G_VALUE_INIT
;
699 g_value_init (&result_value
, G_TYPE_BOOLEAN
);
701 g_value_init (¶ms
, G_TYPE_CANCELLABLE
);
702 g_value_set_object (¶ms
, cancellable
);
704 g_closure_invoke (closure
, &result_value
, 1, ¶ms
, NULL
);
706 result
= g_value_get_boolean (&result_value
);
707 g_value_unset (&result_value
);
708 g_value_unset (¶ms
);
713 static GSourceFuncs cancellable_source_funcs
=
715 cancellable_source_prepare
,
716 cancellable_source_check
,
717 cancellable_source_dispatch
,
718 cancellable_source_finalize
,
719 (GSourceFunc
)cancellable_source_closure_callback
,
720 (GSourceDummyMarshal
)g_cclosure_marshal_generic
,
724 * g_cancellable_source_new: (skip)
725 * @cancellable: (allow-none): a #GCancellable, or %NULL
727 * Creates a source that triggers if @cancellable is cancelled and
728 * calls its callback of type #GCancellableSourceFunc. This is
729 * primarily useful for attaching to another (non-cancellable) source
730 * with g_source_add_child_source() to add cancellability to it.
732 * For convenience, you can call this with a %NULL #GCancellable,
733 * in which case the source will never trigger.
735 * Return value: (transfer full): the new #GSource.
740 g_cancellable_source_new (GCancellable
*cancellable
)
743 GCancellableSource
*cancellable_source
;
745 source
= g_source_new (&cancellable_source_funcs
, sizeof (GCancellableSource
));
746 g_source_set_name (source
, "GCancellable");
747 cancellable_source
= (GCancellableSource
*)source
;
751 cancellable_source
->cancellable
= g_object_ref (cancellable
);
752 g_signal_connect (cancellable
, "cancelled",
753 G_CALLBACK (cancellable_source_cancelled
),