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, see <http://www.gnu.org/licenses/>.
19 * Authors: Ryan Lortie <desrt@desrt.ca>
20 * Alexander Larsson <alexl@redhat.com>
27 #include "giostream.h"
28 #include "gasyncresult.h"
29 #include "gioprivate.h"
34 * @short_description: Base class for implementing read/write streams
36 * @see_also: #GInputStream, #GOutputStream
38 * GIOStream represents an object that has both read and write streams.
39 * Generally the two streams act as separate input and output streams,
40 * but they share some common resources and state. For instance, for
41 * seekable streams, both streams may use the same position.
43 * Examples of #GIOStream objects are #GSocketConnection, which represents
44 * a two-way network connection; and #GFileIOStream, which represents a
45 * file handle opened in read-write mode.
47 * To do the actual reading and writing you need to get the substreams
48 * with g_io_stream_get_input_stream() and g_io_stream_get_output_stream().
50 * The #GIOStream object owns the input and the output streams, not the other
51 * way around, so keeping the substreams alive will not keep the #GIOStream
52 * object alive. If the #GIOStream object is freed it will be closed, thus
53 * closing the substreams, so even if the substreams stay alive they will
54 * always return %G_IO_ERROR_CLOSED for all operations.
56 * To close a stream use g_io_stream_close() which will close the common
57 * stream object and also the individual substreams. You can also close
58 * the substreams themselves. In most cases this only marks the
59 * substream as closed, so further I/O on it fails but common state in the
60 * #GIOStream may still be open. However, some streams may support
61 * "half-closed" states where one direction of the stream is actually shut down.
63 * Operations on #GIOStreams cannot be started while another operation on the
64 * #GIOStream or its substreams is in progress. Specifically, an application can
65 * read from the #GInputStream and write to the #GOutputStream simultaneously
66 * (either in separate threads, or as asynchronous operations in the same
67 * thread), but an application cannot start any #GIOStream operation while there
68 * is a #GIOStream, #GInputStream or #GOutputStream operation in progress, and
69 * an application can’t start any #GInputStream or #GOutputStream operation
70 * while there is a #GIOStream operation in progress.
72 * This is a product of individual stream operations being associated with a
73 * given #GMainContext (the thread-default context at the time the operation was
74 * started), rather than entire streams being associated with a single
77 * GIO may run operations on #GIOStreams from other (worker) threads, and this
78 * may be exposed to application code in the behaviour of wrapper streams, such
79 * as #GBufferedInputStream or #GTlsConnection. With such wrapper APIs,
80 * application code may only run operations on the base (wrapped) stream when
81 * the wrapper stream is idle. Note that the semantics of such operations may
82 * not be well-defined due to the state the wrapper stream leaves the base
83 * stream in (though they are guaranteed not to crash).
96 struct _GIOStreamPrivate {
101 static gboolean g_io_stream_real_close (GIOStream *stream,
102 GCancellable *cancellable,
104 static void g_io_stream_real_close_async (GIOStream *stream,
106 GCancellable *cancellable,
107 GAsyncReadyCallback callback,
109 static gboolean g_io_stream_real_close_finish (GIOStream *stream,
110 GAsyncResult *result,
113 G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GIOStream, g_io_stream, G_TYPE_OBJECT)
116 g_io_stream_dispose (GObject *object)
120 stream = G_IO_STREAM (object);
122 if (!stream->priv->closed)
123 g_io_stream_close (stream, NULL, NULL);
125 G_OBJECT_CLASS (g_io_stream_parent_class)->dispose (object);
129 g_io_stream_init (GIOStream *stream)
131 stream->priv = g_io_stream_get_instance_private (stream);
135 g_io_stream_get_property (GObject *object,
140 GIOStream *stream = G_IO_STREAM (object);
145 g_value_set_boolean (value, stream->priv->closed);
148 case PROP_INPUT_STREAM:
149 g_value_set_object (value, g_io_stream_get_input_stream (stream));
152 case PROP_OUTPUT_STREAM:
153 g_value_set_object (value, g_io_stream_get_output_stream (stream));
157 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
162 g_io_stream_class_init (GIOStreamClass *klass)
164 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
166 gobject_class->dispose = g_io_stream_dispose;
167 gobject_class->get_property = g_io_stream_get_property;
169 klass->close_fn = g_io_stream_real_close;
170 klass->close_async = g_io_stream_real_close_async;
171 klass->close_finish = g_io_stream_real_close_finish;
173 g_object_class_install_property (gobject_class, PROP_CLOSED,
174 g_param_spec_boolean ("closed",
176 P_("Is the stream closed"),
178 G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
180 g_object_class_install_property (gobject_class, PROP_INPUT_STREAM,
181 g_param_spec_object ("input-stream",
183 P_("The GInputStream to read from"),
185 G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
186 g_object_class_install_property (gobject_class, PROP_OUTPUT_STREAM,
187 g_param_spec_object ("output-stream",
189 P_("The GOutputStream to write to"),
190 G_TYPE_OUTPUT_STREAM,
191 G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
195 * g_io_stream_is_closed:
196 * @stream: a #GIOStream
198 * Checks if a stream is closed.
200 * Returns: %TRUE if the stream is closed.
205 g_io_stream_is_closed (GIOStream *stream)
207 g_return_val_if_fail (G_IS_IO_STREAM (stream), TRUE);
209 return stream->priv->closed;
213 * g_io_stream_get_input_stream:
214 * @stream: a #GIOStream
216 * Gets the input stream for this object. This is used
219 * Returns: (transfer none): a #GInputStream, owned by the #GIOStream.
225 g_io_stream_get_input_stream (GIOStream *stream)
227 GIOStreamClass *klass;
229 klass = G_IO_STREAM_GET_CLASS (stream);
231 g_assert (klass->get_input_stream != NULL);
233 return klass->get_input_stream (stream);
237 * g_io_stream_get_output_stream:
238 * @stream: a #GIOStream
240 * Gets the output stream for this object. This is used for
243 * Returns: (transfer none): a #GOutputStream, owned by the #GIOStream.
249 g_io_stream_get_output_stream (GIOStream *stream)
251 GIOStreamClass *klass;
253 klass = G_IO_STREAM_GET_CLASS (stream);
255 g_assert (klass->get_output_stream != NULL);
256 return klass->get_output_stream (stream);
260 * g_io_stream_has_pending:
261 * @stream: a #GIOStream
263 * Checks if a stream has pending actions.
265 * Returns: %TRUE if @stream has pending actions.
270 g_io_stream_has_pending (GIOStream *stream)
272 g_return_val_if_fail (G_IS_IO_STREAM (stream), FALSE);
274 return stream->priv->pending;
278 * g_io_stream_set_pending:
279 * @stream: a #GIOStream
280 * @error: a #GError location to store the error occurring, or %NULL to
283 * Sets @stream to have actions pending. If the pending flag is
284 * already set or @stream is closed, it will return %FALSE and set
287 * Returns: %TRUE if pending was previously unset and is now set.
292 g_io_stream_set_pending (GIOStream *stream,
295 g_return_val_if_fail (G_IS_IO_STREAM (stream), FALSE);
297 if (stream->priv->closed)
299 g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_CLOSED,
300 _("Stream is already closed"));
304 if (stream->priv->pending)
306 g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_PENDING,
307 /* Translators: This is an error you get if there is
308 * already an operation running against this stream when
309 * you try to start one */
310 _("Stream has outstanding operation"));
314 stream->priv->pending = TRUE;
319 * g_io_stream_clear_pending:
320 * @stream: a #GIOStream
322 * Clears the pending flag on @stream.
327 g_io_stream_clear_pending (GIOStream *stream)
329 g_return_if_fail (G_IS_IO_STREAM (stream));
331 stream->priv->pending = FALSE;
335 g_io_stream_real_close (GIOStream *stream,
336 GCancellable *cancellable,
341 res = g_output_stream_close (g_io_stream_get_output_stream (stream),
344 /* If this errored out, unset error so that we don't report
345 further errors, but still do the following ops */
346 if (error != NULL && *error != NULL)
349 res &= g_input_stream_close (g_io_stream_get_input_stream (stream),
357 * @stream: a #GIOStream
358 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
359 * @error: location to store the error occurring, or %NULL to ignore
361 * Closes the stream, releasing resources related to it. This will also
362 * close the individual input and output streams, if they are not already
365 * Once the stream is closed, all other operations will return
366 * %G_IO_ERROR_CLOSED. Closing a stream multiple times will not
369 * Closing a stream will automatically flush any outstanding buffers
372 * Streams will be automatically closed when the last reference
373 * is dropped, but you might want to call this function to make sure
374 * resources are released as early as possible.
376 * Some streams might keep the backing store of the stream (e.g. a file
377 * descriptor) open after the stream is closed. See the documentation for
378 * the individual stream for details.
380 * On failure the first error that happened will be reported, but the
381 * close operation will finish as much as possible. A stream that failed
382 * to close will still return %G_IO_ERROR_CLOSED for all operations.
383 * Still, it is important to check and report the error to the user,
384 * otherwise there might be a loss of data as all data might not be written.
386 * If @cancellable is not NULL, then the operation can be cancelled by
387 * triggering the cancellable object from another thread. If the operation
388 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
389 * Cancelling a close will still leave the stream closed, but some streams
390 * can use a faster close that doesn't block to e.g. check errors.
392 * The default implementation of this method just calls close on the
393 * individual input/output streams.
395 * Returns: %TRUE on success, %FALSE on failure
400 g_io_stream_close (GIOStream *stream,
401 GCancellable *cancellable,
404 GIOStreamClass *class;
407 g_return_val_if_fail (G_IS_IO_STREAM (stream), FALSE);
409 class = G_IO_STREAM_GET_CLASS (stream);
411 if (stream->priv->closed)
414 if (!g_io_stream_set_pending (stream, error))
418 g_cancellable_push_current (cancellable);
422 res = class->close_fn (stream, cancellable, error);
425 g_cancellable_pop_current (cancellable);
427 stream->priv->closed = TRUE;
428 g_io_stream_clear_pending (stream);
434 async_ready_close_callback_wrapper (GObject *source_object,
438 GIOStream *stream = G_IO_STREAM (source_object);
439 GIOStreamClass *klass = G_IO_STREAM_GET_CLASS (stream);
440 GTask *task = user_data;
441 GError *error = NULL;
444 stream->priv->closed = TRUE;
445 g_io_stream_clear_pending (stream);
447 if (g_async_result_legacy_propagate_error (res, &error))
450 success = klass->close_finish (stream, res, &error);
453 g_task_return_error (task, error);
455 g_task_return_boolean (task, success);
457 g_object_unref (task);
461 * g_io_stream_close_async:
462 * @stream: a #GIOStream
463 * @io_priority: the io priority of the request
464 * @cancellable: (allow-none): optional cancellable object
465 * @callback: (scope async): callback to call when the request is satisfied
466 * @user_data: (closure): the data to pass to callback function
468 * Requests an asynchronous close of the stream, releasing resources
469 * related to it. When the operation is finished @callback will be
470 * called. You can then call g_io_stream_close_finish() to get
471 * the result of the operation.
473 * For behaviour details see g_io_stream_close().
475 * The asynchronous methods have a default fallback that uses threads
476 * to implement asynchronicity, so they are optional for inheriting
477 * classes. However, if you override one you must override all.
482 g_io_stream_close_async (GIOStream *stream,
484 GCancellable *cancellable,
485 GAsyncReadyCallback callback,
488 GIOStreamClass *class;
489 GError *error = NULL;
492 g_return_if_fail (G_IS_IO_STREAM (stream));
494 task = g_task_new (stream, cancellable, callback, user_data);
496 if (stream->priv->closed)
498 g_task_return_boolean (task, TRUE);
499 g_object_unref (task);
503 if (!g_io_stream_set_pending (stream, &error))
505 g_task_return_error (task, error);
506 g_object_unref (task);
510 class = G_IO_STREAM_GET_CLASS (stream);
512 class->close_async (stream, io_priority, cancellable,
513 async_ready_close_callback_wrapper, task);
517 * g_io_stream_close_finish:
518 * @stream: a #GIOStream
519 * @result: a #GAsyncResult
520 * @error: a #GError location to store the error occurring, or %NULL to
525 * Returns: %TRUE if stream was successfully closed, %FALSE otherwise.
530 g_io_stream_close_finish (GIOStream *stream,
531 GAsyncResult *result,
534 g_return_val_if_fail (G_IS_IO_STREAM (stream), FALSE);
535 g_return_val_if_fail (g_task_is_valid (result, stream), FALSE);
537 return g_task_propagate_boolean (G_TASK (result), error);
542 close_async_thread (GTask *task,
543 gpointer source_object,
545 GCancellable *cancellable)
547 GIOStream *stream = source_object;
548 GIOStreamClass *class;
549 GError *error = NULL;
552 class = G_IO_STREAM_GET_CLASS (stream);
555 result = class->close_fn (stream,
556 g_task_get_cancellable (task),
560 g_task_return_error (task, error);
565 g_task_return_boolean (task, TRUE);
575 stream_close_complete (GObject *source,
576 GAsyncResult *result,
579 GTask *task = user_data;
580 CloseAsyncData *data;
582 data = g_task_get_task_data (task);
585 if (G_IS_OUTPUT_STREAM (source))
587 GError *error = NULL;
589 /* Match behaviour with the sync route and give precedent to the
590 * error returned from closing the output stream.
592 g_output_stream_close_finish (G_OUTPUT_STREAM (source), result, &error);
596 g_error_free (data->error);
601 g_input_stream_close_finish (G_INPUT_STREAM (source), result, data->error ? NULL : &data->error);
603 if (data->pending == 0)
606 g_task_return_error (task, data->error);
608 g_task_return_boolean (task, TRUE);
610 g_slice_free (CloseAsyncData, data);
611 g_object_unref (task);
616 g_io_stream_real_close_async (GIOStream *stream,
618 GCancellable *cancellable,
619 GAsyncReadyCallback callback,
623 GOutputStream *output;
626 task = g_task_new (stream, cancellable, callback, user_data);
627 g_task_set_check_cancellable (task, FALSE);
628 g_task_set_priority (task, io_priority);
630 input = g_io_stream_get_input_stream (stream);
631 output = g_io_stream_get_output_stream (stream);
633 if (g_input_stream_async_close_is_via_threads (input) && g_output_stream_async_close_is_via_threads (output))
635 /* No sense in dispatching to the thread twice -- just do it all
638 g_task_run_in_thread (task, close_async_thread);
639 g_object_unref (task);
643 CloseAsyncData *data;
645 /* We should avoid dispatching to another thread in case either
646 * object that would not do it for itself because it may not be
649 data = g_slice_new (CloseAsyncData);
653 g_task_set_task_data (task, data, NULL);
654 g_input_stream_close_async (input, io_priority, cancellable, stream_close_complete, task);
655 g_output_stream_close_async (output, io_priority, cancellable, stream_close_complete, task);
660 g_io_stream_real_close_finish (GIOStream *stream,
661 GAsyncResult *result,
664 g_return_val_if_fail (g_task_is_valid (result, stream), FALSE);
666 return g_task_propagate_boolean (G_TASK (result), error);
673 GIOStreamSpliceFlags flags;
675 GCancellable *cancellable;
677 GCancellable *op1_cancellable;
678 GCancellable *op2_cancellable;
684 splice_context_free (SpliceContext *ctx)
686 g_object_unref (ctx->stream1);
687 g_object_unref (ctx->stream2);
688 if (ctx->cancellable != NULL)
689 g_object_unref (ctx->cancellable);
690 g_object_unref (ctx->op1_cancellable);
691 g_object_unref (ctx->op2_cancellable);
692 g_clear_error (&ctx->error);
693 g_slice_free (SpliceContext, ctx);
697 splice_complete (GTask *task,
700 if (ctx->cancelled_id != 0)
701 g_cancellable_disconnect (ctx->cancellable, ctx->cancelled_id);
702 ctx->cancelled_id = 0;
704 if (ctx->error != NULL)
706 g_task_return_error (task, ctx->error);
710 g_task_return_boolean (task, TRUE);
714 splice_close_cb (GObject *iostream,
718 GTask *task = user_data;
719 SpliceContext *ctx = g_task_get_task_data (task);
720 GError *error = NULL;
722 g_io_stream_close_finish (G_IO_STREAM (iostream), res, &error);
726 /* Keep the first error that occurred */
727 if (error != NULL && ctx->error == NULL)
730 g_clear_error (&error);
732 /* If all operations are done, complete now */
733 if (ctx->completed == 4)
734 splice_complete (task, ctx);
736 g_object_unref (task);
740 splice_cb (GObject *ostream,
744 GTask *task = user_data;
745 SpliceContext *ctx = g_task_get_task_data (task);
746 GError *error = NULL;
748 g_output_stream_splice_finish (G_OUTPUT_STREAM (ostream), res, &error);
752 /* ignore cancellation error if it was not requested by the user */
754 g_error_matches (error, G_IO_ERROR, G_IO_ERROR_CANCELLED) &&
755 (ctx->cancellable == NULL ||
756 !g_cancellable_is_cancelled (ctx->cancellable)))
757 g_clear_error (&error);
759 /* Keep the first error that occurred */
760 if (error != NULL && ctx->error == NULL)
763 g_clear_error (&error);
765 if (ctx->completed == 1 &&
766 (ctx->flags & G_IO_STREAM_SPLICE_WAIT_FOR_BOTH) == 0)
768 /* We don't want to wait for the 2nd operation to finish, cancel it */
769 g_cancellable_cancel (ctx->op1_cancellable);
770 g_cancellable_cancel (ctx->op2_cancellable);
772 else if (ctx->completed == 2)
774 if (ctx->cancellable == NULL ||
775 !g_cancellable_is_cancelled (ctx->cancellable))
777 g_cancellable_reset (ctx->op1_cancellable);
778 g_cancellable_reset (ctx->op2_cancellable);
781 /* Close the IO streams if needed */
782 if ((ctx->flags & G_IO_STREAM_SPLICE_CLOSE_STREAM1) != 0)
784 g_io_stream_close_async (ctx->stream1,
785 g_task_get_priority (task),
786 ctx->op1_cancellable,
787 splice_close_cb, g_object_ref (task));
792 if ((ctx->flags & G_IO_STREAM_SPLICE_CLOSE_STREAM2) != 0)
794 g_io_stream_close_async (ctx->stream2,
795 g_task_get_priority (task),
796 ctx->op2_cancellable,
797 splice_close_cb, g_object_ref (task));
802 /* If all operations are done, complete now */
803 if (ctx->completed == 4)
804 splice_complete (task, ctx);
807 g_object_unref (task);
811 splice_cancelled_cb (GCancellable *cancellable,
816 ctx = g_task_get_task_data (task);
817 g_cancellable_cancel (ctx->op1_cancellable);
818 g_cancellable_cancel (ctx->op2_cancellable);
822 * g_io_stream_splice_async:
823 * @stream1: a #GIOStream.
824 * @stream2: a #GIOStream.
825 * @flags: a set of #GIOStreamSpliceFlags.
826 * @io_priority: the io priority of the request.
827 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
828 * @callback: (scope async): a #GAsyncReadyCallback.
829 * @user_data: (closure): user data passed to @callback.
831 * Asyncronously splice the output stream of @stream1 to the input stream of
832 * @stream2, and splice the output stream of @stream2 to the input stream of
835 * When the operation is finished @callback will be called.
836 * You can then call g_io_stream_splice_finish() to get the
837 * result of the operation.
842 g_io_stream_splice_async (GIOStream *stream1,
844 GIOStreamSpliceFlags flags,
846 GCancellable *cancellable,
847 GAsyncReadyCallback callback,
852 GInputStream *istream;
853 GOutputStream *ostream;
855 if (cancellable != NULL && g_cancellable_is_cancelled (cancellable))
857 g_task_report_new_error (NULL, callback, user_data,
858 g_io_stream_splice_async,
859 G_IO_ERROR, G_IO_ERROR_CANCELLED,
860 "Operation has been cancelled");
864 ctx = g_slice_new0 (SpliceContext);
865 ctx->stream1 = g_object_ref (stream1);
866 ctx->stream2 = g_object_ref (stream2);
868 ctx->op1_cancellable = g_cancellable_new ();
869 ctx->op2_cancellable = g_cancellable_new ();
872 task = g_task_new (NULL, cancellable, callback, user_data);
873 g_task_set_task_data (task, ctx, (GDestroyNotify) splice_context_free);
875 if (cancellable != NULL)
877 ctx->cancellable = g_object_ref (cancellable);
878 ctx->cancelled_id = g_cancellable_connect (cancellable,
879 G_CALLBACK (splice_cancelled_cb), g_object_ref (task),
883 istream = g_io_stream_get_input_stream (stream1);
884 ostream = g_io_stream_get_output_stream (stream2);
885 g_output_stream_splice_async (ostream, istream, G_OUTPUT_STREAM_SPLICE_NONE,
886 io_priority, ctx->op1_cancellable, splice_cb,
887 g_object_ref (task));
889 istream = g_io_stream_get_input_stream (stream2);
890 ostream = g_io_stream_get_output_stream (stream1);
891 g_output_stream_splice_async (ostream, istream, G_OUTPUT_STREAM_SPLICE_NONE,
892 io_priority, ctx->op2_cancellable, splice_cb,
893 g_object_ref (task));
895 g_object_unref (task);
899 * g_io_stream_splice_finish:
900 * @result: a #GAsyncResult.
901 * @error: a #GError location to store the error occurring, or %NULL to
904 * Finishes an asynchronous io stream splice operation.
906 * Returns: %TRUE on success, %FALSE otherwise.
911 g_io_stream_splice_finish (GAsyncResult *result,
914 g_return_val_if_fail (g_task_is_valid (result, NULL), FALSE);
916 return g_task_propagate_boolean (G_TASK (result), error);