1 /* GIO - GLib Input, Output and Streaming Library
3 * Copyright © 2008 codethink
4 * Copyright © 2009 Red Hat, Inc.
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.
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.
16 * You should have received a copy of the GNU Lesser General
17 * Public License along with this library; if not, write to the
18 * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
19 * Boston, MA 02111-1307, USA.
21 * Authors: Ryan Lortie <desrt@desrt.ca>
22 * Alexander Larsson <alexl@redhat.com>
29 #include "giostream.h"
30 #include <gio/gsimpleasyncresult.h>
31 #include <gio/gasyncresult.h>
34 G_DEFINE_ABSTRACT_TYPE (GIOStream
, g_io_stream
, G_TYPE_OBJECT
);
38 * @short_description: Base class for implementing read/write streams
40 * @see_also: #GInputStream, #GOutputStream
42 * GIOStream represents an object that has both read and write streams.
43 * Generally the two streams acts as separate input and output streams,
44 * but they share some common resources and state. For instance, for
45 * seekable streams they may use the same position in both streams.
47 * Examples of #GIOStream objects are #GSocketConnection which represents
48 * a two-way network connection, and #GFileIOStream which represent a
49 * file handle opened in read-write mode.
51 * To do the actual reading and writing you need to get the substreams
52 * with g_io_stream_get_input_stream() and g_io_stream_get_output_stream().
54 * The #GIOStream object owns the input and the output streams, not the other
55 * way around, so keeping the substreams alive will not keep the #GIOStream
56 * object alive. If the #GIOStream object is freed it will be closed, thus
57 * closing the substream, so even if the substreams stay alive they will
58 * always just return a %G_IO_ERROR_CLOSED for all operations.
60 * To close a stream use g_io_stream_close() which will close the common
61 * stream object and also the individual substreams. You can also close
62 * the substreams themselves. In most cases this only marks the
63 * substream as closed, so further I/O on it fails. However, some streams
64 * may support "half-closed" states where one direction of the stream
65 * is actually shut down.
78 struct _GIOStreamPrivate
{
81 GAsyncReadyCallback outstanding_callback
;
84 static gboolean
g_io_stream_real_close (GIOStream
*stream
,
85 GCancellable
*cancellable
,
87 static void g_io_stream_real_close_async (GIOStream
*stream
,
89 GCancellable
*cancellable
,
90 GAsyncReadyCallback callback
,
92 static gboolean
g_io_stream_real_close_finish (GIOStream
*stream
,
97 g_io_stream_finalize (GObject
*object
)
99 G_OBJECT_CLASS (g_io_stream_parent_class
)->finalize (object
);
103 g_io_stream_dispose (GObject
*object
)
107 stream
= G_IO_STREAM (object
);
109 if (!stream
->priv
->closed
)
110 g_io_stream_close (stream
, NULL
, NULL
);
112 G_OBJECT_CLASS (g_io_stream_parent_class
)->dispose (object
);
116 g_io_stream_init (GIOStream
*stream
)
118 stream
->priv
= G_TYPE_INSTANCE_GET_PRIVATE (stream
,
124 g_io_stream_get_property (GObject
*object
,
129 GIOStream
*stream
= G_IO_STREAM (object
);
134 g_value_set_boolean (value
, stream
->priv
->closed
);
137 case PROP_INPUT_STREAM
:
138 g_value_set_object (value
, g_io_stream_get_input_stream (stream
));
141 case PROP_OUTPUT_STREAM
:
142 g_value_set_object (value
, g_io_stream_get_output_stream (stream
));
146 G_OBJECT_WARN_INVALID_PROPERTY_ID (object
, prop_id
, pspec
);
151 g_io_stream_class_init (GIOStreamClass
*klass
)
153 GObjectClass
*gobject_class
= G_OBJECT_CLASS (klass
);
155 g_type_class_add_private (klass
, sizeof (GIOStreamPrivate
));
157 gobject_class
->finalize
= g_io_stream_finalize
;
158 gobject_class
->dispose
= g_io_stream_dispose
;
159 gobject_class
->get_property
= g_io_stream_get_property
;
161 klass
->close_fn
= g_io_stream_real_close
;
162 klass
->close_async
= g_io_stream_real_close_async
;
163 klass
->close_finish
= g_io_stream_real_close_finish
;
165 g_object_class_install_property (gobject_class
, PROP_CLOSED
,
166 g_param_spec_boolean ("closed",
168 P_("Is the stream closed"),
170 G_PARAM_READABLE
| G_PARAM_STATIC_STRINGS
));
172 g_object_class_install_property (gobject_class
, PROP_INPUT_STREAM
,
173 g_param_spec_object ("input-stream",
175 P_("The GInputStream to read from"),
177 G_PARAM_READABLE
| G_PARAM_STATIC_STRINGS
));
178 g_object_class_install_property (gobject_class
, PROP_OUTPUT_STREAM
,
179 g_param_spec_object ("output-stream",
181 P_("The GOutputStream to write to"),
182 G_TYPE_OUTPUT_STREAM
,
183 G_PARAM_READABLE
| G_PARAM_STATIC_STRINGS
));
187 * g_io_stream_is_closed:
188 * @stream: a #GIOStream
190 * Checks if a stream is closed.
192 * Returns: %TRUE if the stream is closed.
197 g_io_stream_is_closed (GIOStream
*stream
)
199 g_return_val_if_fail (G_IS_IO_STREAM (stream
), TRUE
);
201 return stream
->priv
->closed
;
205 * g_io_stream_get_input_stream:
206 * @stream: a #GIOStream
208 * Gets the input stream for this object. This is used
211 * Returns: (transfer none): a #GInputStream, owned by the #GIOStream.
217 g_io_stream_get_input_stream (GIOStream
*stream
)
219 GIOStreamClass
*klass
;
221 klass
= G_IO_STREAM_GET_CLASS (stream
);
223 g_assert (klass
->get_input_stream
!= NULL
);
225 return klass
->get_input_stream (stream
);
229 * g_io_stream_get_output_stream:
230 * @stream: a #GIOStream
232 * Gets the output stream for this object. This is used for
235 * Returns: (transfer none): a #GOutputStream, owned by the #GIOStream.
241 g_io_stream_get_output_stream (GIOStream
*stream
)
243 GIOStreamClass
*klass
;
245 klass
= G_IO_STREAM_GET_CLASS (stream
);
247 g_assert (klass
->get_output_stream
!= NULL
);
248 return klass
->get_output_stream (stream
);
252 * g_io_stream_has_pending:
253 * @stream: a #GIOStream
255 * Checks if a stream has pending actions.
257 * Returns: %TRUE if @stream has pending actions.
262 g_io_stream_has_pending (GIOStream
*stream
)
264 g_return_val_if_fail (G_IS_IO_STREAM (stream
), FALSE
);
266 return stream
->priv
->pending
;
270 * g_io_stream_set_pending:
271 * @stream: a #GIOStream
272 * @error: a #GError location to store the error occurring, or %NULL to
275 * Sets @stream to have actions pending. If the pending flag is
276 * already set or @stream is closed, it will return %FALSE and set
279 * Return value: %TRUE if pending was previously unset and is now set.
284 g_io_stream_set_pending (GIOStream
*stream
,
287 g_return_val_if_fail (G_IS_IO_STREAM (stream
), FALSE
);
289 if (stream
->priv
->closed
)
291 g_set_error_literal (error
, G_IO_ERROR
, G_IO_ERROR_CLOSED
,
292 _("Stream is already closed"));
296 if (stream
->priv
->pending
)
298 g_set_error_literal (error
, G_IO_ERROR
, G_IO_ERROR_PENDING
,
299 /* Translators: This is an error you get if there is
300 * already an operation running against this stream when
301 * you try to start one */
302 _("Stream has outstanding operation"));
306 stream
->priv
->pending
= TRUE
;
311 * g_io_stream_clear_pending:
312 * @stream: a #GIOStream
314 * Clears the pending flag on @stream.
319 g_io_stream_clear_pending (GIOStream
*stream
)
321 g_return_if_fail (G_IS_IO_STREAM (stream
));
323 stream
->priv
->pending
= FALSE
;
327 g_io_stream_real_close (GIOStream
*stream
,
328 GCancellable
*cancellable
,
333 res
= g_output_stream_close (g_io_stream_get_output_stream (stream
),
336 /* If this errored out, unset error so that we don't report
337 further errors, but still do the following ops */
338 if (error
!= NULL
&& *error
!= NULL
)
341 res
&= g_input_stream_close (g_io_stream_get_input_stream (stream
),
349 * @stream: a #GIOStream
350 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
351 * @error: location to store the error occurring, or %NULL to ignore
353 * Closes the stream, releasing resources related to it. This will also
354 * closes the individual input and output streams, if they are not already
357 * Once the stream is closed, all other operations will return
358 * %G_IO_ERROR_CLOSED. Closing a stream multiple times will not
361 * Closing a stream will automatically flush any outstanding buffers
364 * Streams will be automatically closed when the last reference
365 * is dropped, but you might want to call this function to make sure
366 * resources are released as early as possible.
368 * Some streams might keep the backing store of the stream (e.g. a file
369 * descriptor) open after the stream is closed. See the documentation for
370 * the individual stream for details.
372 * On failure the first error that happened will be reported, but the
373 * close operation will finish as much as possible. A stream that failed
374 * to close will still return %G_IO_ERROR_CLOSED for all operations.
375 * Still, it is important to check and report the error to the user,
376 * otherwise there might be a loss of data as all data might not be written.
378 * If @cancellable is not NULL, then the operation can be cancelled by
379 * triggering the cancellable object from another thread. If the operation
380 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
381 * Cancelling a close will still leave the stream closed, but some streams
382 * can use a faster close that doesn't block to e.g. check errors.
384 * The default implementation of this method just calls close on the
385 * individual input/output streams.
387 * Return value: %TRUE on success, %FALSE on failure
392 g_io_stream_close (GIOStream
*stream
,
393 GCancellable
*cancellable
,
396 GIOStreamClass
*class;
399 g_return_val_if_fail (G_IS_IO_STREAM (stream
), FALSE
);
401 class = G_IO_STREAM_GET_CLASS (stream
);
403 if (stream
->priv
->closed
)
406 if (!g_io_stream_set_pending (stream
, error
))
410 g_cancellable_push_current (cancellable
);
414 res
= class->close_fn (stream
, cancellable
, error
);
417 g_cancellable_pop_current (cancellable
);
419 stream
->priv
->closed
= TRUE
;
420 g_io_stream_clear_pending (stream
);
426 async_ready_close_callback_wrapper (GObject
*source_object
,
430 GIOStream
*stream
= G_IO_STREAM (source_object
);
432 stream
->priv
->closed
= TRUE
;
433 g_io_stream_clear_pending (stream
);
434 if (stream
->priv
->outstanding_callback
)
435 (*stream
->priv
->outstanding_callback
) (source_object
, res
, user_data
);
436 g_object_unref (stream
);
440 * g_io_stream_close_async:
441 * @stream: a #GIOStream
442 * @io_priority: the io priority of the request
443 * @cancellable: (allow-none): optional cancellable object
444 * @callback: (scope async): callback to call when the request is satisfied
445 * @user_data: (closure): the data to pass to callback function
447 * Requests an asynchronous close of the stream, releasing resources
448 * related to it. When the operation is finished @callback will be
449 * called. You can then call g_io_stream_close_finish() to get
450 * the result of the operation.
452 * For behaviour details see g_io_stream_close().
454 * The asynchronous methods have a default fallback that uses threads
455 * to implement asynchronicity, so they are optional for inheriting
456 * classes. However, if you override one you must override all.
461 g_io_stream_close_async (GIOStream
*stream
,
463 GCancellable
*cancellable
,
464 GAsyncReadyCallback callback
,
467 GIOStreamClass
*class;
468 GSimpleAsyncResult
*simple
;
469 GError
*error
= NULL
;
471 g_return_if_fail (G_IS_IO_STREAM (stream
));
473 if (stream
->priv
->closed
)
475 simple
= g_simple_async_result_new (G_OBJECT (stream
),
478 g_io_stream_close_async
);
479 g_simple_async_result_complete_in_idle (simple
);
480 g_object_unref (simple
);
484 if (!g_io_stream_set_pending (stream
, &error
))
486 g_simple_async_report_take_gerror_in_idle (G_OBJECT (stream
),
493 class = G_IO_STREAM_GET_CLASS (stream
);
494 stream
->priv
->outstanding_callback
= callback
;
495 g_object_ref (stream
);
496 class->close_async (stream
, io_priority
, cancellable
,
497 async_ready_close_callback_wrapper
, user_data
);
501 * g_io_stream_close_finish:
502 * @stream: a #GIOStream
503 * @result: a #GAsyncResult
504 * @error: a #GError location to store the error occurring, or %NULL to
509 * Returns: %TRUE if stream was successfully closed, %FALSE otherwise.
514 g_io_stream_close_finish (GIOStream
*stream
,
515 GAsyncResult
*result
,
518 GIOStreamClass
*class;
520 g_return_val_if_fail (G_IS_IO_STREAM (stream
), FALSE
);
521 g_return_val_if_fail (G_IS_ASYNC_RESULT (result
), FALSE
);
523 if (g_async_result_legacy_propagate_error (result
, error
))
525 else if (g_async_result_is_tagged (result
, g_io_stream_close_async
))
527 /* Special case already closed */
531 class = G_IO_STREAM_GET_CLASS (stream
);
532 return class->close_finish (stream
, result
, error
);
537 close_async_thread (GSimpleAsyncResult
*res
,
539 GCancellable
*cancellable
)
541 GIOStreamClass
*class;
542 GError
*error
= NULL
;
545 /* Auto handling of cancelation disabled, and ignore cancellation,
546 * since we want to close things anyway, although possibly in a
547 * quick-n-dirty way. At least we never want to leak open handles
549 class = G_IO_STREAM_GET_CLASS (object
);
552 result
= class->close_fn (G_IO_STREAM (object
), cancellable
, &error
);
554 g_simple_async_result_take_error (res
, error
);
559 g_io_stream_real_close_async (GIOStream
*stream
,
561 GCancellable
*cancellable
,
562 GAsyncReadyCallback callback
,
565 GSimpleAsyncResult
*res
;
567 res
= g_simple_async_result_new (G_OBJECT (stream
),
570 g_io_stream_real_close_async
);
572 g_simple_async_result_set_handle_cancellation (res
, FALSE
);
574 g_simple_async_result_run_in_thread (res
,
578 g_object_unref (res
);
582 g_io_stream_real_close_finish (GIOStream
*stream
,
583 GAsyncResult
*result
,
586 GSimpleAsyncResult
*simple
= G_SIMPLE_ASYNC_RESULT (result
);
588 g_warn_if_fail (g_simple_async_result_get_source_tag (simple
) ==
589 g_io_stream_real_close_async
);
591 if (g_simple_async_result_propagate_error (simple
, error
))
601 GIOStreamSpliceFlags flags
;
603 GCancellable
*cancellable
;
605 GCancellable
*op1_cancellable
;
606 GCancellable
*op2_cancellable
;
612 splice_context_free (SpliceContext
*ctx
)
614 g_object_unref (ctx
->stream1
);
615 g_object_unref (ctx
->stream2
);
616 if (ctx
->cancellable
!= NULL
)
617 g_object_unref (ctx
->cancellable
);
618 g_object_unref (ctx
->op1_cancellable
);
619 g_object_unref (ctx
->op2_cancellable
);
620 g_clear_error (&ctx
->error
);
621 g_slice_free (SpliceContext
, ctx
);
625 splice_complete (GSimpleAsyncResult
*simple
,
628 if (ctx
->cancelled_id
!= 0)
629 g_cancellable_disconnect (ctx
->cancellable
, ctx
->cancelled_id
);
630 ctx
->cancelled_id
= 0;
632 if (ctx
->error
!= NULL
)
633 g_simple_async_result_set_from_error (simple
, ctx
->error
);
634 g_simple_async_result_complete (simple
);
638 splice_close_cb (GObject
*iostream
,
642 GSimpleAsyncResult
*simple
= user_data
;
644 GError
*error
= NULL
;
646 g_io_stream_close_finish (G_IO_STREAM (iostream
), res
, &error
);
648 ctx
= g_simple_async_result_get_op_res_gpointer (simple
);
651 /* Keep the first error that occurred */
652 if (error
!= NULL
&& ctx
->error
== NULL
)
655 g_clear_error (&error
);
657 /* If all operations are done, complete now */
658 if (ctx
->completed
== 4)
659 splice_complete (simple
, ctx
);
661 g_object_unref (simple
);
665 splice_cb (GObject
*ostream
,
669 GSimpleAsyncResult
*simple
= user_data
;
671 GError
*error
= NULL
;
673 g_output_stream_splice_finish (G_OUTPUT_STREAM (ostream
), res
, &error
);
675 ctx
= g_simple_async_result_get_op_res_gpointer (simple
);
678 /* ignore cancellation error if it was not requested by the user */
680 g_error_matches (error
, G_IO_ERROR
, G_IO_ERROR_CANCELLED
) &&
681 (ctx
->cancellable
== NULL
||
682 !g_cancellable_is_cancelled (ctx
->cancellable
)))
683 g_clear_error (&error
);
685 /* Keep the first error that occurred */
686 if (error
!= NULL
&& ctx
->error
== NULL
)
689 g_clear_error (&error
);
691 if (ctx
->completed
== 1 &&
692 (ctx
->flags
& G_IO_STREAM_SPLICE_WAIT_FOR_BOTH
) == 0)
694 /* We don't want to wait for the 2nd operation to finish, cancel it */
695 g_cancellable_cancel (ctx
->op1_cancellable
);
696 g_cancellable_cancel (ctx
->op2_cancellable
);
698 else if (ctx
->completed
== 2)
700 if (ctx
->cancellable
== NULL
||
701 !g_cancellable_is_cancelled (ctx
->cancellable
))
703 g_cancellable_reset (ctx
->op1_cancellable
);
704 g_cancellable_reset (ctx
->op2_cancellable
);
707 /* Close the IO streams if needed */
708 if ((ctx
->flags
& G_IO_STREAM_SPLICE_CLOSE_STREAM1
) != 0)
709 g_io_stream_close_async (ctx
->stream1
, ctx
->io_priority
,
710 ctx
->op1_cancellable
, splice_close_cb
, g_object_ref (simple
));
714 if ((ctx
->flags
& G_IO_STREAM_SPLICE_CLOSE_STREAM2
) != 0)
715 g_io_stream_close_async (ctx
->stream2
, ctx
->io_priority
,
716 ctx
->op2_cancellable
, splice_close_cb
, g_object_ref (simple
));
720 /* If all operations are done, complete now */
721 if (ctx
->completed
== 4)
722 splice_complete (simple
, ctx
);
725 g_object_unref (simple
);
729 splice_cancelled_cb (GCancellable
*cancellable
,
730 GSimpleAsyncResult
*simple
)
734 ctx
= g_simple_async_result_get_op_res_gpointer (simple
);
735 g_cancellable_cancel (ctx
->op1_cancellable
);
736 g_cancellable_cancel (ctx
->op2_cancellable
);
740 * g_io_stream_splice_async:
741 * @stream1: a #GIOStream.
742 * @stream2: a #GIOStream.
743 * @flags: a set of #GIOStreamSpliceFlags.
744 * @io_priority: the io priority of the request.
745 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
746 * @callback: (scope async): a #GAsyncReadyCallback.
747 * @user_data: (closure): user data passed to @callback.
749 * Asyncronously splice the output stream of @stream1 to the input stream of
750 * @stream2, and splice the output stream of @stream2 to the input stream of
753 * When the operation is finished @callback will be called.
754 * You can then call g_io_stream_splice_finish() to get the
755 * result of the operation.
760 g_io_stream_splice_async (GIOStream
*stream1
,
762 GIOStreamSpliceFlags flags
,
764 GCancellable
*cancellable
,
765 GAsyncReadyCallback callback
,
768 GSimpleAsyncResult
*simple
;
770 GInputStream
*istream
;
771 GOutputStream
*ostream
;
773 if (cancellable
!= NULL
&& g_cancellable_is_cancelled (cancellable
))
775 g_simple_async_report_error_in_idle (NULL
, callback
,
776 user_data
, G_IO_ERROR
, G_IO_ERROR_CANCELLED
,
777 "Operation has been cancelled");
781 ctx
= g_slice_new0 (SpliceContext
);
782 ctx
->stream1
= g_object_ref (stream1
);
783 ctx
->stream2
= g_object_ref (stream2
);
785 ctx
->io_priority
= io_priority
;
786 ctx
->op1_cancellable
= g_cancellable_new ();
787 ctx
->op2_cancellable
= g_cancellable_new ();
790 simple
= g_simple_async_result_new (NULL
, callback
, user_data
,
791 g_io_stream_splice_finish
);
792 g_simple_async_result_set_op_res_gpointer (simple
, ctx
,
793 (GDestroyNotify
) splice_context_free
);
795 if (cancellable
!= NULL
)
797 ctx
->cancellable
= g_object_ref (cancellable
);
798 ctx
->cancelled_id
= g_cancellable_connect (cancellable
,
799 G_CALLBACK (splice_cancelled_cb
), g_object_ref (simple
),
803 istream
= g_io_stream_get_input_stream (stream1
);
804 ostream
= g_io_stream_get_output_stream (stream2
);
805 g_output_stream_splice_async (ostream
, istream
, G_OUTPUT_STREAM_SPLICE_NONE
,
806 io_priority
, ctx
->op1_cancellable
, splice_cb
,
807 g_object_ref (simple
));
809 istream
= g_io_stream_get_input_stream (stream2
);
810 ostream
= g_io_stream_get_output_stream (stream1
);
811 g_output_stream_splice_async (ostream
, istream
, G_OUTPUT_STREAM_SPLICE_NONE
,
812 io_priority
, ctx
->op2_cancellable
, splice_cb
,
813 g_object_ref (simple
));
815 g_object_unref (simple
);
819 * g_io_stream_splice_finish:
820 * @result: a #GAsyncResult.
821 * @error: a #GError location to store the error occurring, or %NULL to
824 * Finishes an asynchronous io stream splice operation.
826 * Returns: %TRUE on success, %FALSE otherwise.
831 g_io_stream_splice_finish (GAsyncResult
*result
,
834 GSimpleAsyncResult
*simple
;
836 g_return_val_if_fail (G_IS_SIMPLE_ASYNC_RESULT (result
), FALSE
);
838 simple
= G_SIMPLE_ASYNC_RESULT (result
);
840 if (g_simple_async_result_propagate_error (simple
, error
))
843 g_return_val_if_fail (g_simple_async_result_is_valid (result
, NULL
,
844 g_io_stream_splice_finish
), FALSE
);