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 GSimpleAsyncResult
*simple
;
519 GIOStreamClass
*class;
521 g_return_val_if_fail (G_IS_IO_STREAM (stream
), FALSE
);
522 g_return_val_if_fail (G_IS_ASYNC_RESULT (result
), FALSE
);
524 if (G_IS_SIMPLE_ASYNC_RESULT (result
))
526 simple
= G_SIMPLE_ASYNC_RESULT (result
);
527 if (g_simple_async_result_propagate_error (simple
, error
))
530 /* Special case already closed */
531 if (g_simple_async_result_get_source_tag (simple
) == g_io_stream_close_async
)
535 class = G_IO_STREAM_GET_CLASS (stream
);
536 return class->close_finish (stream
, result
, error
);
541 close_async_thread (GSimpleAsyncResult
*res
,
543 GCancellable
*cancellable
)
545 GIOStreamClass
*class;
546 GError
*error
= NULL
;
549 /* Auto handling of cancelation disabled, and ignore cancellation,
550 * since we want to close things anyway, although possibly in a
551 * quick-n-dirty way. At least we never want to leak open handles
553 class = G_IO_STREAM_GET_CLASS (object
);
556 result
= class->close_fn (G_IO_STREAM (object
), cancellable
, &error
);
558 g_simple_async_result_take_error (res
, error
);
563 g_io_stream_real_close_async (GIOStream
*stream
,
565 GCancellable
*cancellable
,
566 GAsyncReadyCallback callback
,
569 GSimpleAsyncResult
*res
;
571 res
= g_simple_async_result_new (G_OBJECT (stream
),
574 g_io_stream_real_close_async
);
576 g_simple_async_result_set_handle_cancellation (res
, FALSE
);
578 g_simple_async_result_run_in_thread (res
,
582 g_object_unref (res
);
586 g_io_stream_real_close_finish (GIOStream
*stream
,
587 GAsyncResult
*result
,
590 GSimpleAsyncResult
*simple
= G_SIMPLE_ASYNC_RESULT (result
);
591 g_warn_if_fail (g_simple_async_result_get_source_tag (simple
) ==
592 g_io_stream_real_close_async
);
600 GIOStreamSpliceFlags flags
;
602 GCancellable
*cancellable
;
604 GCancellable
*op1_cancellable
;
605 GCancellable
*op2_cancellable
;
611 splice_context_free (SpliceContext
*ctx
)
613 g_object_unref (ctx
->stream1
);
614 g_object_unref (ctx
->stream2
);
615 if (ctx
->cancellable
!= NULL
)
616 g_object_unref (ctx
->cancellable
);
617 g_object_unref (ctx
->op1_cancellable
);
618 g_object_unref (ctx
->op2_cancellable
);
619 g_clear_error (&ctx
->error
);
620 g_slice_free (SpliceContext
, ctx
);
624 splice_complete (GSimpleAsyncResult
*simple
,
627 if (ctx
->cancelled_id
!= 0)
628 g_cancellable_disconnect (ctx
->cancellable
, ctx
->cancelled_id
);
629 ctx
->cancelled_id
= 0;
631 if (ctx
->error
!= NULL
)
632 g_simple_async_result_set_from_error (simple
, ctx
->error
);
633 g_simple_async_result_complete (simple
);
637 splice_close_cb (GObject
*iostream
,
641 GSimpleAsyncResult
*simple
= user_data
;
643 GError
*error
= NULL
;
645 g_io_stream_close_finish (G_IO_STREAM (iostream
), res
, &error
);
647 ctx
= g_simple_async_result_get_op_res_gpointer (simple
);
650 /* Keep the first error that occurred */
651 if (error
!= NULL
&& ctx
->error
== NULL
)
654 g_clear_error (&error
);
656 /* If all operations are done, complete now */
657 if (ctx
->completed
== 4)
658 splice_complete (simple
, ctx
);
660 g_object_unref (simple
);
664 splice_cb (GObject
*ostream
,
668 GSimpleAsyncResult
*simple
= user_data
;
670 GError
*error
= NULL
;
672 g_output_stream_splice_finish (G_OUTPUT_STREAM (ostream
), res
, &error
);
674 ctx
= g_simple_async_result_get_op_res_gpointer (simple
);
677 /* ignore cancellation error if it was not requested by the user */
679 g_error_matches (error
, G_IO_ERROR
, G_IO_ERROR_CANCELLED
) &&
680 (ctx
->cancellable
== NULL
||
681 !g_cancellable_is_cancelled (ctx
->cancellable
)))
682 g_clear_error (&error
);
684 /* Keep the first error that occurred */
685 if (error
!= NULL
&& ctx
->error
== NULL
)
688 g_clear_error (&error
);
690 if (ctx
->completed
== 1 &&
691 (ctx
->flags
& G_IO_STREAM_SPLICE_WAIT_FOR_BOTH
) == 0)
693 /* We don't want to wait for the 2nd operation to finish, cancel it */
694 g_cancellable_cancel (ctx
->op1_cancellable
);
695 g_cancellable_cancel (ctx
->op2_cancellable
);
697 else if (ctx
->completed
== 2)
699 if (ctx
->cancellable
== NULL
||
700 !g_cancellable_is_cancelled (ctx
->cancellable
))
702 g_cancellable_reset (ctx
->op1_cancellable
);
703 g_cancellable_reset (ctx
->op2_cancellable
);
706 /* Close the IO streams if needed */
707 if ((ctx
->flags
& G_IO_STREAM_SPLICE_CLOSE_STREAM1
) != 0)
708 g_io_stream_close_async (ctx
->stream1
, ctx
->io_priority
,
709 ctx
->op1_cancellable
, splice_close_cb
, g_object_ref (simple
));
713 if ((ctx
->flags
& G_IO_STREAM_SPLICE_CLOSE_STREAM2
) != 0)
714 g_io_stream_close_async (ctx
->stream2
, ctx
->io_priority
,
715 ctx
->op2_cancellable
, splice_close_cb
, g_object_ref (simple
));
719 /* If all operations are done, complete now */
720 if (ctx
->completed
== 4)
721 splice_complete (simple
, ctx
);
724 g_object_unref (simple
);
728 splice_cancelled_cb (GCancellable
*cancellable
,
729 GSimpleAsyncResult
*simple
)
733 ctx
= g_simple_async_result_get_op_res_gpointer (simple
);
734 g_cancellable_cancel (ctx
->op1_cancellable
);
735 g_cancellable_cancel (ctx
->op2_cancellable
);
739 * g_io_stream_splice_async:
740 * @stream1: a #GIOStream.
741 * @stream2: a #GIOStream.
742 * @flags: a set of #GIOStreamSpliceFlags.
743 * @io_priority: the io priority of the request.
744 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
745 * @callback: (scope async): a #GAsyncReadyCallback.
746 * @user_data: (closure): user data passed to @callback.
748 * Asyncronously splice the output stream of @stream1 to the input stream of
749 * @stream2, and splice the output stream of @stream2 to the input stream of
752 * When the operation is finished @callback will be called.
753 * You can then call g_io_stream_splice_finish() to get the
754 * result of the operation.
759 g_io_stream_splice_async (GIOStream
*stream1
,
761 GIOStreamSpliceFlags flags
,
763 GCancellable
*cancellable
,
764 GAsyncReadyCallback callback
,
767 GSimpleAsyncResult
*simple
;
769 GInputStream
*istream
;
770 GOutputStream
*ostream
;
772 if (cancellable
!= NULL
&& g_cancellable_is_cancelled (cancellable
))
774 g_simple_async_report_error_in_idle (NULL
, callback
,
775 user_data
, G_IO_ERROR
, G_IO_ERROR_CANCELLED
,
776 "Operation has been cancelled");
780 ctx
= g_slice_new0 (SpliceContext
);
781 ctx
->stream1
= g_object_ref (stream1
);
782 ctx
->stream2
= g_object_ref (stream2
);
784 ctx
->io_priority
= io_priority
;
785 ctx
->op1_cancellable
= g_cancellable_new ();
786 ctx
->op2_cancellable
= g_cancellable_new ();
789 simple
= g_simple_async_result_new (NULL
, callback
, user_data
,
790 g_io_stream_splice_finish
);
791 g_simple_async_result_set_op_res_gpointer (simple
, ctx
,
792 (GDestroyNotify
) splice_context_free
);
794 if (cancellable
!= NULL
)
796 ctx
->cancellable
= g_object_ref (cancellable
);
797 ctx
->cancelled_id
= g_cancellable_connect (cancellable
,
798 G_CALLBACK (splice_cancelled_cb
), g_object_ref (simple
),
802 istream
= g_io_stream_get_input_stream (stream1
);
803 ostream
= g_io_stream_get_output_stream (stream2
);
804 g_output_stream_splice_async (ostream
, istream
, G_OUTPUT_STREAM_SPLICE_NONE
,
805 io_priority
, ctx
->op1_cancellable
, splice_cb
,
806 g_object_ref (simple
));
808 istream
= g_io_stream_get_input_stream (stream2
);
809 ostream
= g_io_stream_get_output_stream (stream1
);
810 g_output_stream_splice_async (ostream
, istream
, G_OUTPUT_STREAM_SPLICE_NONE
,
811 io_priority
, ctx
->op2_cancellable
, splice_cb
,
812 g_object_ref (simple
));
814 g_object_unref (simple
);
818 * g_io_stream_splice_finish:
819 * @result: a #GAsyncResult.
820 * @error: a #GError location to store the error occurring, or %NULL to
823 * Finishes an asynchronous io stream splice operation.
825 * Returns: %TRUE on success, %FALSE otherwise.
830 g_io_stream_splice_finish (GAsyncResult
*result
,
833 GSimpleAsyncResult
*simple
;
835 g_return_val_if_fail (G_IS_SIMPLE_ASYNC_RESULT (result
), FALSE
);
837 simple
= G_SIMPLE_ASYNC_RESULT (result
);
839 if (g_simple_async_result_propagate_error (simple
, error
))
842 g_return_val_if_fail (g_simple_async_result_is_valid (result
, NULL
,
843 g_io_stream_splice_finish
), FALSE
);