gio/giostream.c

   1 /* GIO - GLib Input, Output and Streaming Library
   2  *
   3  * Copyright © 2008 codethink
   4  * Copyright © 2009 Red Hat, Inc.
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General
  17  * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
  18  *
  19  * Authors: Ryan Lortie <desrt@desrt.ca>
  20  *          Alexander Larsson <alexl@redhat.com>
  21  */
  22
  23 #include "config.h"
  24 #include <glib.h>
  25 #include "glibintl.h"
  26
  27 #include "giostream.h"
  28 #include "gasyncresult.h"
  29 #include "gtask.h"
  30
  31 /**
  32  * SECTION:giostream
  33  * @short_description: Base class for implementing read/write streams
  34  * @include: gio/gio.h
  35  * @see_also: #GInputStream, #GOutputStream
  36  *
  37  * GIOStream represents an object that has both read and write streams.
  38  * Generally the two streams acts as separate input and output streams,
  39  * but they share some common resources and state. For instance, for
  40  * seekable streams they may use the same position in both streams.
  41  *
  42  * Examples of #GIOStream objects are #GSocketConnection which represents
  43  * a two-way network connection, and #GFileIOStream which represent a
  44  * file handle opened in read-write mode.
  45  *
  46  * To do the actual reading and writing you need to get the substreams
  47  * with g_io_stream_get_input_stream() and g_io_stream_get_output_stream().
  48  *
  49  * The #GIOStream object owns the input and the output streams, not the other
  50  * way around, so keeping the substreams alive will not keep the #GIOStream
  51  * object alive. If the #GIOStream object is freed it will be closed, thus
  52  * closing the substream, so even if the substreams stay alive they will
  53  * always just return a %G_IO_ERROR_CLOSED for all operations.
  54  *
  55  * To close a stream use g_io_stream_close() which will close the common
  56  * stream object and also the individual substreams. You can also close
  57  * the substreams themselves. In most cases this only marks the
  58  * substream as closed, so further I/O on it fails but common state in the
  59  * #GIOStream may still be open. However, some streams may support
  60  * "half-closed" states where one direction of the stream is actually shut down.
  61  *
  62  * Since: 2.22
  63  */
  64
  65 enum
  66 {
  67   PROP_0,
  68   PROP_INPUT_STREAM,
  69   PROP_OUTPUT_STREAM,
  70   PROP_CLOSED
  71 };
  72
  73 struct _GIOStreamPrivate {
  74   guint closed : 1;
  75   guint pending : 1;
  76 };
  77
  78 static gboolean g_io_stream_real_close        (GIOStream            *stream,
  79                                                GCancellable         *cancellable,
  80                                                GError              **error);
  81 static void     g_io_stream_real_close_async  (GIOStream            *stream,
  82                                                int                   io_priority,
  83                                                GCancellable         *cancellable,
  84                                                GAsyncReadyCallback   callback,
  85                                                gpointer              user_data);
  86 static gboolean g_io_stream_real_close_finish (GIOStream            *stream,
  87                                                GAsyncResult         *result,
  88                                                GError              **error);
  89
  90 G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GIOStream, g_io_stream, G_TYPE_OBJECT)
  91
  92 static void
  93 g_io_stream_dispose (GObject *object)
  94 {
  95   GIOStream *stream;
  96
  97   stream = G_IO_STREAM (object);
  98
  99   if (!stream->priv->closed)
 100     g_io_stream_close (stream, NULL, NULL);
 101
 102   G_OBJECT_CLASS (g_io_stream_parent_class)->dispose (object);
 103 }
 104
 105 static void
 106 g_io_stream_init (GIOStream *stream)
 107 {
 108   stream->priv = g_io_stream_get_instance_private (stream);
 109 }
 110
 111 static void
 112 g_io_stream_get_property (GObject    *object,
 113                           guint       prop_id,
 114                           GValue     *value,
 115                           GParamSpec *pspec)
 116 {
 117   GIOStream *stream = G_IO_STREAM (object);
 118
 119   switch (prop_id)
 120     {
 121       case PROP_CLOSED:
 122         g_value_set_boolean (value, stream->priv->closed);
 123         break;
 124
 125       case PROP_INPUT_STREAM:
 126         g_value_set_object (value, g_io_stream_get_input_stream (stream));
 127         break;
 128
 129       case PROP_OUTPUT_STREAM:
 130         g_value_set_object (value, g_io_stream_get_output_stream (stream));
 131         break;
 132
 133       default:
 134         G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 135     }
 136 }
 137
 138 static void
 139 g_io_stream_class_init (GIOStreamClass *klass)
 140 {
 141   GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
 142
 143   gobject_class->dispose = g_io_stream_dispose;
 144   gobject_class->get_property = g_io_stream_get_property;
 145
 146   klass->close_fn = g_io_stream_real_close;
 147   klass->close_async = g_io_stream_real_close_async;
 148   klass->close_finish = g_io_stream_real_close_finish;
 149
 150   g_object_class_install_property (gobject_class, PROP_CLOSED,
 151                                    g_param_spec_boolean ("closed",
 152                                                          P_("Closed"),
 153                                                          P_("Is the stream closed"),
 154                                                          FALSE,
 155                                                          G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
 156
 157   g_object_class_install_property (gobject_class, PROP_INPUT_STREAM,
 158                                    g_param_spec_object ("input-stream",
 159                                                         P_("Input stream"),
 160                                                         P_("The GInputStream to read from"),
 161                                                         G_TYPE_INPUT_STREAM,
 162                                                         G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
 163   g_object_class_install_property (gobject_class, PROP_OUTPUT_STREAM,
 164                                    g_param_spec_object ("output-stream",
 165                                                         P_("Output stream"),
 166                                                         P_("The GOutputStream to write to"),
 167                                                         G_TYPE_OUTPUT_STREAM,
 168                                                         G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
 169 }
 170
 171 /**
 172  * g_io_stream_is_closed:
 173  * @stream: a #GIOStream
 174  *
 175  * Checks if a stream is closed.
 176  *
 177  * Returns: %TRUE if the stream is closed.
 178  *
 179  * Since: 2.22
 180  */
 181 gboolean
 182 g_io_stream_is_closed (GIOStream *stream)
 183 {
 184   g_return_val_if_fail (G_IS_IO_STREAM (stream), TRUE);
 185
 186   return stream->priv->closed;
 187 }
 188
 189 /**
 190  * g_io_stream_get_input_stream:
 191  * @stream: a #GIOStream
 192  *
 193  * Gets the input stream for this object. This is used
 194  * for reading.
 195  *
 196  * Returns: (transfer none): a #GInputStream, owned by the #GIOStream.
 197  * Do not free.
 198  *
 199  * Since: 2.22
 200  */
 201 GInputStream *
 202 g_io_stream_get_input_stream (GIOStream *stream)
 203 {
 204   GIOStreamClass *klass;
 205
 206   klass = G_IO_STREAM_GET_CLASS (stream);
 207
 208   g_assert (klass->get_input_stream != NULL);
 209
 210   return klass->get_input_stream (stream);
 211 }
 212
 213 /**
 214  * g_io_stream_get_output_stream:
 215  * @stream: a #GIOStream
 216  *
 217  * Gets the output stream for this object. This is used for
 218  * writing.
 219  *
 220  * Returns: (transfer none): a #GOutputStream, owned by the #GIOStream.
 221  * Do not free.
 222  *
 223  * Since: 2.22
 224  */
 225 GOutputStream *
 226 g_io_stream_get_output_stream (GIOStream *stream)
 227 {
 228   GIOStreamClass *klass;
 229
 230   klass = G_IO_STREAM_GET_CLASS (stream);
 231
 232   g_assert (klass->get_output_stream != NULL);
 233   return klass->get_output_stream (stream);
 234 }
 235
 236 /**
 237  * g_io_stream_has_pending:
 238  * @stream: a #GIOStream
 239  *
 240  * Checks if a stream has pending actions.
 241  *
 242  * Returns: %TRUE if @stream has pending actions.
 243  *
 244  * Since: 2.22
 245  **/
 246 gboolean
 247 g_io_stream_has_pending (GIOStream *stream)
 248 {
 249   g_return_val_if_fail (G_IS_IO_STREAM (stream), FALSE);
 250
 251   return stream->priv->pending;
 252 }
 253
 254 /**
 255  * g_io_stream_set_pending:
 256  * @stream: a #GIOStream
 257  * @error: a #GError location to store the error occurring, or %NULL to
 258  *     ignore
 259  *
 260  * Sets @stream to have actions pending. If the pending flag is
 261  * already set or @stream is closed, it will return %FALSE and set
 262  * @error.
 263  *
 264  * Returns: %TRUE if pending was previously unset and is now set.
 265  *
 266  * Since: 2.22
 267  */
 268 gboolean
 269 g_io_stream_set_pending (GIOStream  *stream,
 270                          GError    **error)
 271 {
 272   g_return_val_if_fail (G_IS_IO_STREAM (stream), FALSE);
 273
 274   if (stream->priv->closed)
 275     {
 276       g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_CLOSED,
 277                            _("Stream is already closed"));
 278       return FALSE;
 279     }
 280
 281   if (stream->priv->pending)
 282     {
 283       g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_PENDING,
 284                            /* Translators: This is an error you get if there is
 285                             * already an operation running against this stream when
 286                             * you try to start one */
 287                            _("Stream has outstanding operation"));
 288       return FALSE;
 289     }
 290
 291   stream->priv->pending = TRUE;
 292   return TRUE;
 293 }
 294
 295 /**
 296  * g_io_stream_clear_pending:
 297  * @stream: a #GIOStream
 298  *
 299  * Clears the pending flag on @stream.
 300  *
 301  * Since: 2.22
 302  */
 303 void
 304 g_io_stream_clear_pending (GIOStream *stream)
 305 {
 306   g_return_if_fail (G_IS_IO_STREAM (stream));
 307
 308   stream->priv->pending = FALSE;
 309 }
 310
 311 static gboolean
 312 g_io_stream_real_close (GIOStream     *stream,
 313                         GCancellable  *cancellable,
 314                         GError       **error)
 315 {
 316   gboolean res;
 317
 318   res = g_output_stream_close (g_io_stream_get_output_stream (stream),
 319                                cancellable, error);
 320
 321   /* If this errored out, unset error so that we don't report
 322      further errors, but still do the following ops */
 323   if (error != NULL && *error != NULL)
 324     error = NULL;
 325
 326   res &= g_input_stream_close (g_io_stream_get_input_stream (stream),
 327                                cancellable, error);
 328
 329   return res;
 330 }
 331
 332 /**
 333  * g_io_stream_close:
 334  * @stream: a #GIOStream
 335  * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
 336  * @error: location to store the error occurring, or %NULL to ignore
 337  *
 338  * Closes the stream, releasing resources related to it. This will also
 339  * closes the individual input and output streams, if they are not already
 340  * closed.
 341  *
 342  * Once the stream is closed, all other operations will return
 343  * %G_IO_ERROR_CLOSED. Closing a stream multiple times will not
 344  * return an error.
 345  *
 346  * Closing a stream will automatically flush any outstanding buffers
 347  * in the stream.
 348  *
 349  * Streams will be automatically closed when the last reference
 350  * is dropped, but you might want to call this function to make sure
 351  * resources are released as early as possible.
 352  *
 353  * Some streams might keep the backing store of the stream (e.g. a file
 354  * descriptor) open after the stream is closed. See the documentation for
 355  * the individual stream for details.
 356  *
 357  * On failure the first error that happened will be reported, but the
 358  * close operation will finish as much as possible. A stream that failed
 359  * to close will still return %G_IO_ERROR_CLOSED for all operations.
 360  * Still, it is important to check and report the error to the user,
 361  * otherwise there might be a loss of data as all data might not be written.
 362  *
 363  * If @cancellable is not NULL, then the operation can be cancelled by
 364  * triggering the cancellable object from another thread. If the operation
 365  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
 366  * Cancelling a close will still leave the stream closed, but some streams
 367  * can use a faster close that doesn't block to e.g. check errors.
 368  *
 369  * The default implementation of this method just calls close on the
 370  * individual input/output streams.
 371  *
 372  * Returns: %TRUE on success, %FALSE on failure
 373  *
 374  * Since: 2.22
 375  */
 376 gboolean
 377 g_io_stream_close (GIOStream     *stream,
 378                    GCancellable  *cancellable,
 379                    GError       **error)
 380 {
 381   GIOStreamClass *class;
 382   gboolean res;
 383
 384   g_return_val_if_fail (G_IS_IO_STREAM (stream), FALSE);
 385
 386   class = G_IO_STREAM_GET_CLASS (stream);
 387
 388   if (stream->priv->closed)
 389     return TRUE;
 390
 391   if (!g_io_stream_set_pending (stream, error))
 392     return FALSE;
 393
 394   if (cancellable)
 395     g_cancellable_push_current (cancellable);
 396
 397   res = TRUE;
 398   if (class->close_fn)
 399     res = class->close_fn (stream, cancellable, error);
 400
 401   if (cancellable)
 402     g_cancellable_pop_current (cancellable);
 403
 404   stream->priv->closed = TRUE;
 405   g_io_stream_clear_pending (stream);
 406
 407   return res;
 408 }
 409
 410 static void
 411 async_ready_close_callback_wrapper (GObject      *source_object,
 412                                     GAsyncResult *res,
 413                                     gpointer      user_data)
 414 {
 415   GIOStream *stream = G_IO_STREAM (source_object);
 416   GIOStreamClass *klass = G_IO_STREAM_GET_CLASS (stream);
 417   GTask *task = user_data;
 418   GError *error = NULL;
 419   gboolean success;
 420
 421   stream->priv->closed = TRUE;
 422   g_io_stream_clear_pending (stream);
 423
 424   if (g_async_result_legacy_propagate_error (res, &error))
 425     success = FALSE;
 426   else
 427     success = klass->close_finish (stream, res, &error);
 428
 429   if (error)
 430     g_task_return_error (task, error);
 431   else
 432     g_task_return_boolean (task, success);
 433
 434   g_object_unref (task);
 435 }
 436
 437 /**
 438  * g_io_stream_close_async:
 439  * @stream: a #GIOStream
 440  * @io_priority: the io priority of the request
 441  * @cancellable: (allow-none): optional cancellable object
 442  * @callback: (scope async): callback to call when the request is satisfied
 443  * @user_data: (closure): the data to pass to callback function
 444  *
 445  * Requests an asynchronous close of the stream, releasing resources
 446  * related to it. When the operation is finished @callback will be
 447  * called. You can then call g_io_stream_close_finish() to get
 448  * the result of the operation.
 449  *
 450  * For behaviour details see g_io_stream_close().
 451  *
 452  * The asynchronous methods have a default fallback that uses threads
 453  * to implement asynchronicity, so they are optional for inheriting
 454  * classes. However, if you override one you must override all.
 455  *
 456  * Since: 2.22
 457  */
 458 void
 459 g_io_stream_close_async (GIOStream           *stream,
 460                          int                  io_priority,
 461                          GCancellable        *cancellable,
 462                          GAsyncReadyCallback  callback,
 463                          gpointer             user_data)
 464 {
 465   GIOStreamClass *class;
 466   GError *error = NULL;
 467   GTask *task;
 468
 469   g_return_if_fail (G_IS_IO_STREAM (stream));
 470
 471   task = g_task_new (stream, cancellable, callback, user_data);
 472
 473   if (stream->priv->closed)
 474     {
 475       g_task_return_boolean (task, TRUE);
 476       g_object_unref (task);
 477       return;
 478     }
 479
 480   if (!g_io_stream_set_pending (stream, &error))
 481     {
 482       g_task_return_error (task, error);
 483       g_object_unref (task);
 484       return;
 485     }
 486
 487   class = G_IO_STREAM_GET_CLASS (stream);
 488
 489   class->close_async (stream, io_priority, cancellable,
 490                       async_ready_close_callback_wrapper, task);
 491 }
 492
 493 /**
 494  * g_io_stream_close_finish:
 495  * @stream: a #GIOStream
 496  * @result: a #GAsyncResult
 497  * @error: a #GError location to store the error occurring, or %NULL to
 498  *    ignore
 499  *
 500  * Closes a stream.
 501  *
 502  * Returns: %TRUE if stream was successfully closed, %FALSE otherwise.
 503  *
 504  * Since: 2.22
 505  */
 506 gboolean
 507 g_io_stream_close_finish (GIOStream     *stream,
 508                           GAsyncResult  *result,
 509                           GError       **error)
 510 {
 511   g_return_val_if_fail (G_IS_IO_STREAM (stream), FALSE);
 512   g_return_val_if_fail (g_task_is_valid (result, stream), FALSE);
 513
 514   return g_task_propagate_boolean (G_TASK (result), error);
 515 }
 516
 517
 518 static void
 519 close_async_thread (GTask        *task,
 520                     gpointer      source_object,
 521                     gpointer      task_data,
 522                     GCancellable *cancellable)
 523 {
 524   GIOStream *stream = source_object;
 525   GIOStreamClass *class;
 526   GError *error = NULL;
 527   gboolean result;
 528
 529   class = G_IO_STREAM_GET_CLASS (stream);
 530   if (class->close_fn)
 531     {
 532       result = class->close_fn (stream,
 533                                 g_task_get_cancellable (task),
 534                                 &error);
 535       if (!result)
 536         {
 537           g_task_return_error (task, error);
 538           return;
 539         }
 540     }
 541
 542   g_task_return_boolean (task, TRUE);
 543 }
 544
 545 static void
 546 g_io_stream_real_close_async (GIOStream           *stream,
 547                               int                  io_priority,
 548                               GCancellable        *cancellable,
 549                               GAsyncReadyCallback  callback,
 550                               gpointer             user_data)
 551 {
 552   GTask *task;
 553
 554   task = g_task_new (stream, cancellable, callback, user_data);
 555   g_task_set_check_cancellable (task, FALSE);
 556   g_task_set_priority (task, io_priority);
 557
 558   g_task_run_in_thread (task, close_async_thread);
 559   g_object_unref (task);
 560 }
 561
 562 static gboolean
 563 g_io_stream_real_close_finish (GIOStream     *stream,
 564                                GAsyncResult  *result,
 565                                GError       **error)
 566 {
 567   g_return_val_if_fail (g_task_is_valid (result, stream), FALSE);
 568
 569   return g_task_propagate_boolean (G_TASK (result), error);
 570 }
 571
 572 typedef struct
 573 {
 574   GIOStream *stream1;
 575   GIOStream *stream2;
 576   GIOStreamSpliceFlags flags;
 577   gint io_priority;
 578   GCancellable *cancellable;
 579   gulong cancelled_id;
 580   GCancellable *op1_cancellable;
 581   GCancellable *op2_cancellable;
 582   guint completed;
 583   GError *error;
 584 } SpliceContext;
 585
 586 static void
 587 splice_context_free (SpliceContext *ctx)
 588 {
 589   g_object_unref (ctx->stream1);
 590   g_object_unref (ctx->stream2);
 591   if (ctx->cancellable != NULL)
 592     g_object_unref (ctx->cancellable);
 593   g_object_unref (ctx->op1_cancellable);
 594   g_object_unref (ctx->op2_cancellable);
 595   g_clear_error (&ctx->error);
 596   g_slice_free (SpliceContext, ctx);
 597 }
 598
 599 static void
 600 splice_complete (GTask         *task,
 601                  SpliceContext *ctx)
 602 {
 603   if (ctx->cancelled_id != 0)
 604     g_cancellable_disconnect (ctx->cancellable, ctx->cancelled_id);
 605   ctx->cancelled_id = 0;
 606
 607   if (ctx->error != NULL)
 608     {
 609       g_task_return_error (task, ctx->error);
 610       ctx->error = NULL;
 611     }
 612   else
 613     g_task_return_boolean (task, TRUE);
 614 }
 615
 616 static void
 617 splice_close_cb (GObject      *iostream,
 618                  GAsyncResult *res,
 619                  gpointer      user_data)
 620 {
 621   GTask *task = user_data;
 622   SpliceContext *ctx = g_task_get_task_data (task);
 623   GError *error = NULL;
 624
 625   g_io_stream_close_finish (G_IO_STREAM (iostream), res, &error);
 626
 627   ctx->completed++;
 628
 629   /* Keep the first error that occurred */
 630   if (error != NULL && ctx->error == NULL)
 631     ctx->error = error;
 632   else
 633     g_clear_error (&error);
 634
 635   /* If all operations are done, complete now */
 636   if (ctx->completed == 4)
 637     splice_complete (task, ctx);
 638
 639   g_object_unref (task);
 640 }
 641
 642 static void
 643 splice_cb (GObject      *ostream,
 644            GAsyncResult *res,
 645            gpointer      user_data)
 646 {
 647   GTask *task = user_data;
 648   SpliceContext *ctx = g_task_get_task_data (task);
 649   GError *error = NULL;
 650
 651   g_output_stream_splice_finish (G_OUTPUT_STREAM (ostream), res, &error);
 652
 653   ctx->completed++;
 654
 655   /* ignore cancellation error if it was not requested by the user */
 656   if (error != NULL &&
 657       g_error_matches (error, G_IO_ERROR, G_IO_ERROR_CANCELLED) &&
 658       (ctx->cancellable == NULL ||
 659        !g_cancellable_is_cancelled (ctx->cancellable)))
 660     g_clear_error (&error);
 661
 662   /* Keep the first error that occurred */
 663   if (error != NULL && ctx->error == NULL)
 664     ctx->error = error;
 665   else
 666     g_clear_error (&error);
 667
 668    if (ctx->completed == 1 &&
 669        (ctx->flags & G_IO_STREAM_SPLICE_WAIT_FOR_BOTH) == 0)
 670     {
 671       /* We don't want to wait for the 2nd operation to finish, cancel it */
 672       g_cancellable_cancel (ctx->op1_cancellable);
 673       g_cancellable_cancel (ctx->op2_cancellable);
 674     }
 675   else if (ctx->completed == 2)
 676     {
 677       if (ctx->cancellable == NULL ||
 678           !g_cancellable_is_cancelled (ctx->cancellable))
 679         {
 680           g_cancellable_reset (ctx->op1_cancellable);
 681           g_cancellable_reset (ctx->op2_cancellable);
 682         }
 683
 684       /* Close the IO streams if needed */
 685       if ((ctx->flags & G_IO_STREAM_SPLICE_CLOSE_STREAM1) != 0)
 686         {
 687           g_io_stream_close_async (ctx->stream1,
 688                                    g_task_get_priority (task),
 689                                    ctx->op1_cancellable,
 690                                    splice_close_cb, g_object_ref (task));
 691         }
 692       else
 693         ctx->completed++;
 694
 695       if ((ctx->flags & G_IO_STREAM_SPLICE_CLOSE_STREAM2) != 0)
 696         {
 697           g_io_stream_close_async (ctx->stream2,
 698                                    g_task_get_priority (task),
 699                                    ctx->op2_cancellable,
 700                                    splice_close_cb, g_object_ref (task));
 701         }
 702       else
 703         ctx->completed++;
 704
 705       /* If all operations are done, complete now */
 706       if (ctx->completed == 4)
 707         splice_complete (task, ctx);
 708     }
 709
 710   g_object_unref (task);
 711 }
 712
 713 static void
 714 splice_cancelled_cb (GCancellable *cancellable,
 715                      GTask        *task)
 716 {
 717   SpliceContext *ctx;
 718
 719   ctx = g_task_get_task_data (task);
 720   g_cancellable_cancel (ctx->op1_cancellable);
 721   g_cancellable_cancel (ctx->op2_cancellable);
 722 }
 723
 724 /**
 725  * g_io_stream_splice_async:
 726  * @stream1: a #GIOStream.
 727  * @stream2: a #GIOStream.
 728  * @flags: a set of #GIOStreamSpliceFlags.
 729  * @io_priority: the io priority of the request.
 730  * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
 731  * @callback: (scope async): a #GAsyncReadyCallback.
 732  * @user_data: (closure): user data passed to @callback.
 733  *
 734  * Asyncronously splice the output stream of @stream1 to the input stream of
 735  * @stream2, and splice the output stream of @stream2 to the input stream of
 736  * @stream1.
 737  *
 738  * When the operation is finished @callback will be called.
 739  * You can then call g_io_stream_splice_finish() to get the
 740  * result of the operation.
 741  *
 742  * Since: 2.28
 743  **/
 744 void
 745 g_io_stream_splice_async (GIOStream            *stream1,
 746                           GIOStream            *stream2,
 747                           GIOStreamSpliceFlags  flags,
 748                           gint                  io_priority,
 749                           GCancellable         *cancellable,
 750                           GAsyncReadyCallback   callback,
 751                           gpointer              user_data)
 752 {
 753   GTask *task;
 754   SpliceContext *ctx;
 755   GInputStream *istream;
 756   GOutputStream *ostream;
 757
 758   if (cancellable != NULL && g_cancellable_is_cancelled (cancellable))
 759     {
 760       g_task_report_new_error (NULL, callback, user_data,
 761                                g_io_stream_splice_async,
 762                                G_IO_ERROR, G_IO_ERROR_CANCELLED,
 763                                "Operation has been cancelled");
 764       return;
 765     }
 766
 767   ctx = g_slice_new0 (SpliceContext);
 768   ctx->stream1 = g_object_ref (stream1);
 769   ctx->stream2 = g_object_ref (stream2);
 770   ctx->flags = flags;
 771   ctx->op1_cancellable = g_cancellable_new ();
 772   ctx->op2_cancellable = g_cancellable_new ();
 773   ctx->completed = 0;
 774
 775   task = g_task_new (NULL, cancellable, callback, user_data);
 776   g_task_set_task_data (task, ctx, (GDestroyNotify) splice_context_free);
 777
 778   if (cancellable != NULL)
 779     {
 780       ctx->cancellable = g_object_ref (cancellable);
 781       ctx->cancelled_id = g_cancellable_connect (cancellable,
 782           G_CALLBACK (splice_cancelled_cb), g_object_ref (task),
 783           g_object_unref);
 784     }
 785
 786   istream = g_io_stream_get_input_stream (stream1);
 787   ostream = g_io_stream_get_output_stream (stream2);
 788   g_output_stream_splice_async (ostream, istream, G_OUTPUT_STREAM_SPLICE_NONE,
 789       io_priority, ctx->op1_cancellable, splice_cb,
 790       g_object_ref (task));
 791
 792   istream = g_io_stream_get_input_stream (stream2);
 793   ostream = g_io_stream_get_output_stream (stream1);
 794   g_output_stream_splice_async (ostream, istream, G_OUTPUT_STREAM_SPLICE_NONE,
 795       io_priority, ctx->op2_cancellable, splice_cb,
 796       g_object_ref (task));
 797
 798   g_object_unref (task);
 799 }
 800
 801 /**
 802  * g_io_stream_splice_finish:
 803  * @result: a #GAsyncResult.
 804  * @error: a #GError location to store the error occurring, or %NULL to
 805  * ignore.
 806  *
 807  * Finishes an asynchronous io stream splice operation.
 808  *
 809  * Returns: %TRUE on success, %FALSE otherwise.
 810  *
 811  * Since: 2.28
 812  **/
 813 gboolean
 814 g_io_stream_splice_finish (GAsyncResult  *result,
 815                            GError       **error)
 816 {
 817   g_return_val_if_fail (g_task_is_valid (result, NULL), FALSE);
 818
 819   return g_task_propagate_boolean (G_TASK (result), error);
 820 }