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, 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 #ifdef HAVE_UNISTD_H
  25 #include <unistd.h>
  26 #endif
  27 #include <fcntl.h>
  28 #include <gioerror.h>
  29 #ifdef G_OS_WIN32
  30 #include <windows.h>
  31 #include <io.h>
  32 #endif
  33 #include "gcancellable.h"
  34 #include "glibintl.h"
  35
  36 #include "gioalias.h"
  37
  38 /**
  39  * SECTION:gcancellable
  40  * @short_description: Thread-safe Operation Cancellation Stack
  41  * @include: gio/gio.h
  42  *
  43  * GCancellable is a thread-safe operation cancellation stack used
  44  * throughout GIO to allow for cancellation of synchronous and
  45  * asynchronous operations.
  46  */
  47
  48 enum {
  49   CANCELLED,
  50   LAST_SIGNAL
  51 };
  52
  53 struct _GCancellablePrivate
  54 {
  55   GObject parent_instance;
  56
  57   guint cancelled : 1;
  58   guint cancelled_running : 1;
  59   guint cancelled_running_waiting : 1;
  60   int cancel_pipe[2];
  61
  62 #ifdef G_OS_WIN32
  63   HANDLE event;
  64 #endif
  65 };
  66
  67 static guint signals[LAST_SIGNAL] = { 0 };
  68
  69 G_DEFINE_TYPE (GCancellable, g_cancellable, G_TYPE_OBJECT);
  70
  71 static GStaticPrivate current_cancellable = G_STATIC_PRIVATE_INIT;
  72 G_LOCK_DEFINE_STATIC(cancellable);
  73 static GCond *cancellable_cond = NULL;
  74
  75 static void
  76 g_cancellable_finalize (GObject *object)
  77 {
  78   GCancellable *cancellable = G_CANCELLABLE (object);
  79   GCancellablePrivate *priv;
  80
  81   priv = cancellable->priv;
  82
  83   if (priv->cancel_pipe[0] != -1)
  84     close (priv->cancel_pipe[0]);
  85
  86   if (priv->cancel_pipe[1] != -1)
  87     close (priv->cancel_pipe[1]);
  88
  89 #ifdef G_OS_WIN32
  90   if (priv->event)
  91     CloseHandle (priv->event);
  92 #endif
  93
  94   G_OBJECT_CLASS (g_cancellable_parent_class)->finalize (object);
  95 }
  96
  97 static void
  98 g_cancellable_class_init (GCancellableClass *klass)
  99 {
 100   GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
 101
 102   g_type_class_add_private (klass, sizeof (GCancellablePrivate));
 103
 104   if (cancellable_cond == NULL && g_thread_supported ())
 105     cancellable_cond = g_cond_new ();
 106
 107   gobject_class->finalize = g_cancellable_finalize;
 108
 109   /**
 110    * GCancellable::cancelled:
 111    * @cancellable: a #GCancellable.
 112    *
 113    * Emitted when the operation has been cancelled.
 114    *
 115    * Can be used by implementations of cancellable operations. If the
 116    * operation is cancelled from another thread, the signal will be
 117    * emitted in the thread that cancelled the operation, not the
 118    * thread that is running the operation.
 119    *
 120    * Note that disconnecting from this signal (or any signal) in a
 121    * multi-threaded program is prone to race conditions. For instance
 122    * it is possible that a signal handler may be invoked even
 123    * <emphasis>after</emphasis> a call to
 124    * g_signal_handler_disconnect() for that handler has already
 125    * returned.
 126    *
 127    * There is also a problem when cancellation happen
 128    * right before connecting to the signal. If this happens the
 129    * signal will unexpectedly not be emitted, and checking before
 130    * connecting to the signal leaves a race condition where this is
 131    * still happening.
 132    *
 133    * In order to make it safe and easy to connect handlers there
 134    * are two helper functions: g_cancellable_connect() and
 135    * g_cancellable_disconnect() which protect against problems
 136    * like this.
 137    *
 138    * An example of how to us this:
 139    * |[
 140    *     /<!-- -->* Make sure we don't do any unnecessary work if already cancelled *<!-- -->/
 141    *     if (g_cancellable_set_error_if_cancelled (cancellable))
 142    *       return;
 143    *
 144    *     /<!-- -->* Set up all the data needed to be able to
 145    *      * handle cancellation of the operation *<!-- -->/
 146    *     my_data = my_data_new (...);
 147    *
 148    *     id = 0;
 149    *     if (cancellable)
 150    *       id = g_cancellable_connect (cancellable,
 151    *                                  G_CALLBACK (cancelled_handler)
 152    *                                  data, NULL);
 153    *
 154    *     /<!-- -->* cancellable operation here... *<!-- -->/
 155    *
 156    *     g_cancellable_disconnect (cancellable, id);
 157    *
 158    *     /<!-- -->* cancelled_handler is never called after this, it
 159    *      * is now safe to free the data *<!-- -->/
 160    *     my_data_free (my_data);
 161    * ]|
 162    *
 163    * Note that the cancelled signal is emitted in the thread that
 164    * the user cancelled from, which may be the main thread. So, the
 165    * cancellable signal should not do something that can block.
 166    */
 167   signals[CANCELLED] =
 168     g_signal_new (I_("cancelled"),
 169                   G_TYPE_FROM_CLASS (gobject_class),
 170                   G_SIGNAL_RUN_LAST,
 171                   G_STRUCT_OFFSET (GCancellableClass, cancelled),
 172                   NULL, NULL,
 173                   g_cclosure_marshal_VOID__VOID,
 174                   G_TYPE_NONE, 0);
 175
 176 }
 177
 178 #ifndef G_OS_WIN32
 179 static void
 180 set_fd_nonblocking (int fd)
 181 {
 182 #ifdef F_GETFL
 183   glong fcntl_flags;
 184   fcntl_flags = fcntl (fd, F_GETFL);
 185
 186 #ifdef O_NONBLOCK
 187   fcntl_flags |= O_NONBLOCK;
 188 #else
 189   fcntl_flags |= O_NDELAY;
 190 #endif
 191
 192   fcntl (fd, F_SETFL, fcntl_flags);
 193 #endif
 194 }
 195
 196 static void
 197 set_fd_close_exec (int fd)
 198 {
 199   int flags;
 200
 201   flags = fcntl (fd, F_GETFD, 0);
 202   if (flags != -1 && (flags & FD_CLOEXEC) == 0)
 203     {
 204       flags |= FD_CLOEXEC;
 205       fcntl (fd, F_SETFD, flags);
 206     }
 207 }
 208
 209
 210 static void
 211 g_cancellable_open_pipe (GCancellable *cancellable)
 212 {
 213   GCancellablePrivate *priv;
 214
 215   priv = cancellable->priv;
 216   if (pipe (priv->cancel_pipe) == 0)
 217     {
 218       /* Make them nonblocking, just to be sure we don't block
 219        * on errors and stuff
 220        */
 221       set_fd_nonblocking (priv->cancel_pipe[0]);
 222       set_fd_nonblocking (priv->cancel_pipe[1]);
 223       set_fd_close_exec (priv->cancel_pipe[0]);
 224       set_fd_close_exec (priv->cancel_pipe[1]);
 225     }
 226 }
 227 #endif
 228
 229 static void
 230 g_cancellable_init (GCancellable *cancellable)
 231 {
 232   cancellable->priv = G_TYPE_INSTANCE_GET_PRIVATE (cancellable,
 233                                                    G_TYPE_CANCELLABLE,
 234                                                    GCancellablePrivate);
 235   cancellable->priv->cancel_pipe[0] = -1;
 236   cancellable->priv->cancel_pipe[1] = -1;
 237 }
 238
 239 /**
 240  * g_cancellable_new:
 241  *
 242  * Creates a new #GCancellable object.
 243  *
 244  * Applications that want to start one or more operations
 245  * that should be cancellable should create a #GCancellable
 246  * and pass it to the operations.
 247  *
 248  * One #GCancellable can be used in multiple consecutive
 249  * operations, but not in multiple concurrent operations.
 250  *
 251  * Returns: a #GCancellable.
 252  **/
 253 GCancellable *
 254 g_cancellable_new (void)
 255 {
 256   return g_object_new (G_TYPE_CANCELLABLE, NULL);
 257 }
 258
 259 /**
 260  * g_cancellable_push_current:
 261  * @cancellable: a #GCancellable object
 262  *
 263  * Pushes @cancellable onto the cancellable stack. The current
 264  * cancllable can then be recieved using g_cancellable_get_current().
 265  *
 266  * This is useful when implementing cancellable operations in
 267  * code that does not allow you to pass down the cancellable object.
 268  *
 269  * This is typically called automatically by e.g. #GFile operations,
 270  * so you rarely have to call this yourself.
 271  **/
 272 void
 273 g_cancellable_push_current (GCancellable *cancellable)
 274 {
 275   GSList *l;
 276
 277   g_return_if_fail (cancellable != NULL);
 278
 279   l = g_static_private_get (&current_cancellable);
 280   l = g_slist_prepend (l, cancellable);
 281   g_static_private_set (&current_cancellable, l, NULL);
 282 }
 283
 284 /**
 285  * g_cancellable_pop_current:
 286  * @cancellable: a #GCancellable object
 287  *
 288  * Pops @cancellable off the cancellable stack (verifying that @cancellable
 289  * is on the top of the stack).
 290  **/
 291 void
 292 g_cancellable_pop_current (GCancellable *cancellable)
 293 {
 294   GSList *l;
 295
 296   l = g_static_private_get (&current_cancellable);
 297
 298   g_return_if_fail (l != NULL);
 299   g_return_if_fail (l->data == cancellable);
 300
 301   l = g_slist_delete_link (l, l);
 302   g_static_private_set (&current_cancellable, l, NULL);
 303 }
 304
 305 /**
 306  * g_cancellable_get_current:
 307  *
 308  * Gets the top cancellable from the stack.
 309  *
 310  * Returns: a #GCancellable from the top of the stack, or %NULL
 311  * if the stack is empty.
 312  **/
 313 GCancellable *
 314 g_cancellable_get_current  (void)
 315 {
 316   GSList *l;
 317
 318   l = g_static_private_get (&current_cancellable);
 319   if (l == NULL)
 320     return NULL;
 321
 322   return G_CANCELLABLE (l->data);
 323 }
 324
 325 /**
 326  * g_cancellable_reset:
 327  * @cancellable: a #GCancellable object.
 328  *
 329  * Resets @cancellable to its uncancelled state.
 330  **/
 331 void
 332 g_cancellable_reset (GCancellable *cancellable)
 333 {
 334   GCancellablePrivate *priv;
 335
 336   g_return_if_fail (G_IS_CANCELLABLE (cancellable));
 337
 338   G_LOCK(cancellable);
 339
 340   priv = cancellable->priv;
 341
 342   while (priv->cancelled_running)
 343     {
 344       priv->cancelled_running_waiting = TRUE;
 345       g_cond_wait (cancellable_cond,
 346                    g_static_mutex_get_mutex (& G_LOCK_NAME (cancellable)));
 347     }
 348
 349   if (priv->cancelled)
 350     {
 351       char ch;
 352
 353     /* Make sure we're not leaving old cancel state around */
 354
 355 #ifdef G_OS_WIN32
 356       if (priv->event)
 357         ResetEvent (priv->event);
 358       else
 359 #endif
 360       if (priv->cancel_pipe[0] != -1)
 361         read (priv->cancel_pipe[0], &ch, 1);
 362       priv->cancelled = FALSE;
 363     }
 364   G_UNLOCK(cancellable);
 365 }
 366
 367 /**
 368  * g_cancellable_is_cancelled:
 369  * @cancellable: a #GCancellable or NULL.
 370  *
 371  * Checks if a cancellable job has been cancelled.
 372  *
 373  * Returns: %TRUE if @cancellable is cancelled,
 374  * FALSE if called with %NULL or if item is not cancelled.
 375  **/
 376 gboolean
 377 g_cancellable_is_cancelled (GCancellable *cancellable)
 378 {
 379   return cancellable != NULL && cancellable->priv->cancelled;
 380 }
 381
 382 /**
 383  * g_cancellable_set_error_if_cancelled:
 384  * @cancellable: a #GCancellable object.
 385  * @error: #GError to append error state to.
 386  *
 387  * If the @cancellable is cancelled, sets the error to notify
 388  * that the operation was cancelled.
 389  *
 390  * Returns: %TRUE if @cancellable was cancelled, %FALSE if it was not.
 391  **/
 392 gboolean
 393 g_cancellable_set_error_if_cancelled (GCancellable  *cancellable,
 394                                       GError       **error)
 395 {
 396   if (g_cancellable_is_cancelled (cancellable))
 397     {
 398       g_set_error_literal (error,
 399                            G_IO_ERROR,
 400                            G_IO_ERROR_CANCELLED,
 401                            _("Operation was cancelled"));
 402       return TRUE;
 403     }
 404
 405   return FALSE;
 406 }
 407
 408 /**
 409  * g_cancellable_get_fd:
 410  * @cancellable: a #GCancellable.
 411  *
 412  * Gets the file descriptor for a cancellable job. This can be used to
 413  * implement cancellable operations on Unix systems. The returned fd will
 414  * turn readable when @cancellable is cancelled.
 415  *
 416  * You are not supposed to read from the fd yourself, just check for
 417  * readable status. Reading to unset the readable status is done
 418  * with g_cancellable_reset().
 419  *
 420  * See also g_cancellable_make_pollfd().
 421  *
 422  * Returns: A valid file descriptor. %-1 if the file descriptor
 423  * is not supported, or on errors.
 424  **/
 425 int
 426 g_cancellable_get_fd (GCancellable *cancellable)
 427 {
 428   GCancellablePrivate *priv;
 429
 430   int fd;
 431   if (cancellable == NULL)
 432     return -1;
 433
 434   priv = cancellable->priv;
 435
 436 #ifdef G_OS_WIN32
 437   return -1;
 438 #else
 439   G_LOCK(cancellable);
 440   if (priv->cancel_pipe[0] == -1)
 441     g_cancellable_open_pipe (cancellable);
 442
 443   fd = priv->cancel_pipe[0];
 444   G_UNLOCK(cancellable);
 445 #endif
 446
 447   return fd;
 448 }
 449
 450 /**
 451  * g_cancellable_make_pollfd:
 452  * @cancellable: a #GCancellable or %NULL
 453  * @pollfd: a pointer to a #GPollFD
 454  *
 455  * Creates a #GPollFD corresponding to @cancellable; this can be passed
 456  * to g_poll() and used to poll for cancellation. This is useful both
 457  * for unix systems without a native poll and for portability to
 458  * windows.
 459  *
 460  * If this function returns %FALSE, either no @cancellable was given or
 461  * resource limits prevent this function from allocating the necessary
 462  * structures for polling. (On Linux, you will likely have reached
 463  * the maximum number of file descriptors.) The suggested way to handle
 464  * these cases is to ignore the @cancellable.
 465  *
 466  * You are not supposed to read from the fd yourself, just check for
 467  * readable status. Reading to unset the readable status is done
 468  * with g_cancellable_reset().
 469  *
 470  * @Returns: %TRUE if @pollfd was successfully initialized, %FALSE on
 471  *           failure to prepare the cancellable.
 472  *
 473  * @Since: 2.22
 474  **/
 475 gboolean
 476 g_cancellable_make_pollfd (GCancellable *cancellable, GPollFD *pollfd)
 477 {
 478   GCancellablePrivate *priv;
 479   int fd;
 480
 481   g_return_val_if_fail (pollfd != NULL, FALSE);
 482   if (cancellable == NULL)
 483     return FALSE;
 484   g_return_val_if_fail (G_IS_CANCELLABLE (cancellable), FALSE);
 485
 486   priv = cancellable->priv;
 487
 488 #ifdef G_OS_WIN32
 489   if (!priv->event)
 490     {
 491       /* A manual reset anonymous event, starting unset */
 492       priv->event = CreateEvent (NULL, TRUE, FALSE, NULL);
 493       if (priv->event == NULL)
 494         return FALSE;
 495     }
 496   pollfd->fd = (gintptr)priv->event;
 497 #else /* !G_OS_WIN32 */
 498   fd = g_cancellable_get_fd (cancellable);
 499   if (fd == -1)
 500     return -1;
 501   pollfd->fd = fd;
 502 #endif /* G_OS_WIN32 */
 503   pollfd->events = G_IO_IN;
 504   pollfd->revents = 0;
 505 }
 506
 507 /**
 508  * g_cancellable_cancel:
 509  * @cancellable: a #GCancellable object.
 510  *
 511  * Will set @cancellable to cancelled, and will emit the
 512  * #GCancellable::cancelled signal. (However, see the warning about
 513  * race conditions in the documentation for that signal if you are
 514  * planning to connect to it.)
 515  *
 516  * This function is thread-safe. In other words, you can safely call
 517  * it from a thread other than the one running the operation that was
 518  * passed the @cancellable.
 519  *
 520  * The convention within gio is that cancelling an asynchronous
 521  * operation causes it to complete asynchronously. That is, if you
 522  * cancel the operation from the same thread in which it is running,
 523  * then the operation's #GAsyncReadyCallback will not be invoked until
 524  * the application returns to the main loop.
 525  **/
 526 void
 527 g_cancellable_cancel (GCancellable *cancellable)
 528 {
 529   static const char ch = 'x';
 530   gboolean cancel;
 531   GCancellablePrivate *priv;
 532
 533   if (cancellable == NULL ||
 534       cancellable->priv->cancelled)
 535     return;
 536
 537   priv = cancellable->priv;
 538   cancel = FALSE;
 539
 540   G_LOCK(cancellable);
 541   cancel = TRUE;
 542   priv->cancelled = TRUE;
 543   priv->cancelled_running = TRUE;
 544 #ifdef G_OS_WIN32
 545   if (priv->event)
 546     SetEvent(priv->event);
 547 #endif
 548   if (priv->cancel_pipe[1] != -1)
 549     write (priv->cancel_pipe[1], &ch, 1);
 550   G_UNLOCK(cancellable);
 551
 552   if (cancel)
 553     {
 554       g_object_ref (cancellable);
 555       g_signal_emit (cancellable, signals[CANCELLED], 0);
 556
 557       G_LOCK(cancellable);
 558
 559       priv->cancelled_running = FALSE;
 560       if (priv->cancelled_running_waiting)
 561         g_cond_broadcast (cancellable_cond);
 562       priv->cancelled_running_waiting = FALSE;
 563
 564       G_UNLOCK(cancellable);
 565
 566       g_object_unref (cancellable);
 567     }
 568 }
 569
 570 /**
 571  * g_cancellable_connect:
 572  * @cancellable: A #GCancellable.
 573  * @callback: The #GCallback to connect.
 574  * @data: Data to pass to @callback.
 575  * @data_destroy_func: Free function for @data or %NULL.
 576  *
 577  * Convenience function to connect to the #GCancellable::cancelled
 578  * signal. Also handles the race condition that may happen
 579  * if the cancellable is cancelled right before connecting.
 580  *
 581  * @callback is called at most once, either directly at the
 582  * time of the connect if @cancellable is already cancelled,
 583  * or when @cancellable is cancelled in some thread.
 584  *
 585  * @data_destroy_func will be called when the handler is
 586  * disconnected, or immediately if the cancellable is already
 587  * cancelled.
 588  *
 589  * See #GCancellable::cancelled for details on how to use this.
 590  *
 591  * Returns: The id of the signal handler or 0 if @cancellable has already
 592  *          been cancelled.
 593  *
 594  * Since: 2.22
 595  */
 596 gulong
 597 g_cancellable_connect (GCancellable   *cancellable,
 598                        GCallback       callback,
 599                        gpointer        data,
 600                        GDestroyNotify  data_destroy_func)
 601 {
 602   gulong id;
 603
 604   g_return_val_if_fail (G_IS_CANCELLABLE (cancellable), 0);
 605
 606   G_LOCK (cancellable);
 607
 608   if (cancellable->priv->cancelled)
 609     {
 610       void (*_callback) (GCancellable *cancellable,
 611                          gpointer      user_data);
 612
 613       _callback = (void *)callback;
 614       id = 0;
 615
 616       _callback (cancellable, data);
 617
 618       if (data_destroy_func)
 619         data_destroy_func (data);
 620     }
 621   else
 622     {
 623       id = g_signal_connect_data (cancellable, "cancelled",
 624                                   callback, data,
 625                                   (GClosureNotify) data_destroy_func,
 626                                   0);
 627     }
 628   G_UNLOCK (cancellable);
 629
 630   return id;
 631 }
 632
 633 /**
 634  * g_cancellable_disconnect:
 635  * @cancellable: A #GCancellable or %NULL.
 636  * @handler_id: Handler id of the handler to be disconnected, or %0.
 637  *
 638  * Disconnects a handler from an cancellable instance similar to
 639  * g_signal_handler_disconnect() but ensures that once this
 640  * function returns the handler will not run anymore in any thread.
 641  *
 642  * This avoids a race condition where a thread cancels at the
 643  * same time as the cancellable operation is finished and the
 644  * signal handler is removed. See #GCancellable::cancelled for
 645  * details on how to use this.
 646  *
 647  * If @cancellable is %NULL or @handler_id is %0 this function does
 648  * nothing.
 649  *
 650  * Since: 2.22
 651  */
 652 void
 653 g_cancellable_disconnect (GCancellable  *cancellable,
 654                           gulong         handler_id)
 655 {
 656   GCancellablePrivate *priv;
 657
 658   if (handler_id == 0 ||  cancellable == NULL)
 659     return;
 660
 661   G_LOCK (cancellable);
 662
 663   priv = cancellable->priv;
 664
 665   while (priv->cancelled_running)
 666     {
 667       priv->cancelled_running_waiting = TRUE;
 668       g_cond_wait (cancellable_cond,
 669                    g_static_mutex_get_mutex (& G_LOCK_NAME (cancellable)));
 670     }
 671
 672   g_signal_handler_disconnect (cancellable, handler_id);
 673   G_UNLOCK (cancellable);
 674 }
 675
 676 #define __G_CANCELLABLE_C__
 677 #include "gioaliasdef.c"