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>
35 G_DEFINE_TYPE (GIOStream, g_io_stream, G_TYPE_OBJECT);
39 * @short_description: Base class for implementing read/write streams
41 * @see_also: #GInputStream, #GOutputStream
43 * GIOStream represents an object that has both read and write streams.
44 * Generally the two streams acts as separate input and output streams,
45 * but they share some common resources and state. For instance, for
46 * seekable streams they may use the same position in both streams.
48 * Examples of #GIOStream objects are #GSocketConnection which represents
49 * a two-way network connection, and #GFileIOStream which represent a
50 * file handle opened in read-write mode.
52 * To do the actual reading and writing you need to get the substreams
53 * with g_io_stream_get_input_stream() and g_io_stream_get_output_stream().
55 * The #GIOStream object owns the input and the output streams, not the other
56 * way around, so keeping the substreams alive will not keep the #GIOStream
57 * object alive. If the #GIOStream object is freed it will be closed, thus
58 * closing the substream, so even if the substreams stay alive they will
59 * always just return a %G_IO_ERROR_CLOSED for all operations.
61 * To close a stream use g_io_stream_close() which will close the common
62 * stream object and also the individual substreams. You can also close
63 * the substreams themselves. In most cases this only marks the
64 * substream as closed, so further I/O on it fails. However, some streams
65 * may support "half-closed" states where one direction of the stream
66 * is actually shut down.
79 struct _GIOStreamPrivate {
82 GAsyncReadyCallback outstanding_callback;
85 static gboolean g_io_stream_real_close (GIOStream *stream,
86 GCancellable *cancellable,
88 static void g_io_stream_real_close_async (GIOStream *stream,
90 GCancellable *cancellable,
91 GAsyncReadyCallback callback,
93 static gboolean g_io_stream_real_close_finish (GIOStream *stream,
98 g_io_stream_finalize (GObject *object)
102 stream = G_IO_STREAM (object);
104 G_OBJECT_CLASS (g_io_stream_parent_class)->finalize (object);
108 g_io_stream_dispose (GObject *object)
112 stream = G_IO_STREAM (object);
114 if (!stream->priv->closed)
115 g_io_stream_close (stream, NULL, NULL);
117 G_OBJECT_CLASS (g_io_stream_parent_class)->dispose (object);
121 g_io_stream_init (GIOStream *stream)
123 stream->priv = G_TYPE_INSTANCE_GET_PRIVATE (stream,
129 g_io_stream_get_property (GObject *object,
134 GIOStream *stream = G_IO_STREAM (object);
139 g_value_set_boolean (value, stream->priv->closed);
142 case PROP_INPUT_STREAM:
143 g_value_set_object (value, g_io_stream_get_input_stream (stream));
146 case PROP_OUTPUT_STREAM:
147 g_value_set_object (value, g_io_stream_get_output_stream (stream));
151 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
156 g_io_stream_set_property (GObject *object,
164 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
169 g_io_stream_class_init (GIOStreamClass *klass)
171 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
173 g_type_class_add_private (klass, sizeof (GIOStreamPrivate));
175 gobject_class->finalize = g_io_stream_finalize;
176 gobject_class->dispose = g_io_stream_dispose;
177 gobject_class->set_property = g_io_stream_set_property;
178 gobject_class->get_property = g_io_stream_get_property;
180 klass->close_fn = g_io_stream_real_close;
181 klass->close_async = g_io_stream_real_close_async;
182 klass->close_finish = g_io_stream_real_close_finish;
184 g_object_class_install_property (gobject_class, PROP_CLOSED,
185 g_param_spec_boolean ("closed",
187 P_("Is the stream closed"),
189 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
191 g_object_class_install_property (gobject_class, PROP_INPUT_STREAM,
192 g_param_spec_object ("input-stream",
194 P_("The GInputStream to read from"),
196 G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
197 g_object_class_install_property (gobject_class, PROP_OUTPUT_STREAM,
198 g_param_spec_object ("output-stream",
200 P_("The GOutputStream to write to"),
201 G_TYPE_OUTPUT_STREAM,
202 G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
206 * g_io_stream_is_closed:
207 * @stream: a #GIOStream.
209 * Checks if a stream is closed.
211 * Returns: %TRUE if the stream is closed.
216 g_io_stream_is_closed (GIOStream *stream)
218 g_return_val_if_fail (G_IS_IO_STREAM (stream), TRUE);
220 return stream->priv->closed;
224 * g_io_stream_get_input_stream:
225 * @stream: input #GIOStream.
227 * Gets the input stream for this object. This is used
230 * Returns: a #GInputStream, owned by the #GIOStream do not free.
235 g_io_stream_get_input_stream (GIOStream *io_stream)
237 GIOStreamClass *klass;
239 klass = G_IO_STREAM_GET_CLASS (io_stream);
241 g_assert (klass->get_input_stream != NULL);
243 return klass->get_input_stream (io_stream);
247 * g_io_stream_get_output_stream:
248 * @stream: input #GIOStream.
250 * Gets the output stream for this object. This is used for
253 * Returns: a #GOutputStream, owned by the #GIOStream do not free.
258 g_io_stream_get_output_stream (GIOStream *io_stream)
260 GIOStreamClass *klass;
262 klass = G_IO_STREAM_GET_CLASS (io_stream);
264 g_assert (klass->get_output_stream != NULL);
265 return klass->get_output_stream (io_stream);
269 * g_io_stream_has_pending:
270 * @stream: a #GIOStream.
272 * Checks if a stream has pending actions.
274 * Returns: %TRUE if @stream has pending actions.
279 g_io_stream_has_pending (GIOStream *stream)
281 g_return_val_if_fail (G_IS_IO_STREAM (stream), FALSE);
283 return stream->priv->pending;
287 * g_io_stream_set_pending:
288 * @stream: a #GIOStream.
289 * @error: a #GError location to store the error occuring, or %NULL to
292 * Sets @stream to have actions pending. If the pending flag is
293 * already set or @stream is closed, it will return %FALSE and set
296 * Return value: %TRUE if pending was previously unset and is now set.
301 g_io_stream_set_pending (GIOStream *stream,
304 g_return_val_if_fail (G_IS_IO_STREAM (stream), FALSE);
306 if (stream->priv->closed)
308 g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_CLOSED,
309 _("Stream is already closed"));
313 if (stream->priv->pending)
315 g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_PENDING,
316 /* Translators: This is an error you get if there is
317 * already an operation running against this stream when
318 * you try to start one */
319 _("Stream has outstanding operation"));
323 stream->priv->pending = TRUE;
328 * g_io_stream_clear_pending:
329 * @stream: output stream
331 * Clears the pending flag on @stream.
336 g_io_stream_clear_pending (GIOStream *stream)
338 g_return_if_fail (G_IS_IO_STREAM (stream));
340 stream->priv->pending = FALSE;
344 g_io_stream_real_close (GIOStream *stream,
345 GCancellable *cancellable,
350 res = g_output_stream_close (g_io_stream_get_output_stream (stream),
353 /* If this errored out, unset error so that we don't report
354 further errors, but still do the following ops */
355 if (error != NULL && *error != NULL)
358 res &= g_input_stream_close (g_io_stream_get_input_stream (stream),
366 * @stream: A #GIOStream.
367 * @cancellable: optional #GCancellable object, %NULL to ignore.
368 * @error: location to store the error occuring, or %NULL to ignore
370 * Closes the stream, releasing resources related to it. This will also
371 * closes the individual input and output streams, if they are not already
374 * Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED.
375 * Closing a stream multiple times will not return an error.
377 * Closing a stream will automatically flush any outstanding buffers in the
380 * Streams will be automatically closed when the last reference
381 * is dropped, but you might want to call this function to make sure
382 * resources are released as early as possible.
384 * Some streams might keep the backing store of the stream (e.g. a file descriptor)
385 * open after the stream is closed. See the documentation for the individual
386 * stream for details.
388 * On failure the first error that happened will be reported, but the close
389 * operation will finish as much as possible. A stream that failed to
390 * close will still return %G_IO_ERROR_CLOSED for all operations. Still, it
391 * is important to check and report the error to the user, otherwise
392 * there might be a loss of data as all data might not be written.
394 * If @cancellable is not NULL, then the operation can be cancelled by
395 * triggering the cancellable object from another thread. If the operation
396 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
397 * Cancelling a close will still leave the stream closed, but some streams
398 * can use a faster close that doesn't block to e.g. check errors.
400 * The default implementation of this method just calls close on the
401 * individual input/output streams.
403 * Return value: %TRUE on success, %FALSE on failure
408 g_io_stream_close (GIOStream *stream,
409 GCancellable *cancellable,
412 GIOStreamClass *class;
415 g_return_val_if_fail (G_IS_IO_STREAM (stream), FALSE);
417 class = G_IO_STREAM_GET_CLASS (stream);
419 if (stream->priv->closed)
422 if (!g_io_stream_set_pending (stream, error))
426 g_cancellable_push_current (cancellable);
430 res = class->close_fn (stream, cancellable, error);
433 g_cancellable_pop_current (cancellable);
435 stream->priv->closed = TRUE;
436 g_io_stream_clear_pending (stream);
442 async_ready_close_callback_wrapper (GObject *source_object,
446 GIOStream *stream = G_IO_STREAM (source_object);
448 stream->priv->closed = TRUE;
449 g_io_stream_clear_pending (stream);
450 if (stream->priv->outstanding_callback)
451 (*stream->priv->outstanding_callback) (source_object, res, user_data);
452 g_object_unref (stream);
456 * g_io_stream_close_async:
457 * @stream: A #GIOStream.
458 * @io_priority: the io priority of the request.
459 * @callback: callback to call when the request is satisfied
460 * @user_data: the data to pass to callback function
461 * @cancellable: optional cancellable object
463 * Requests an asynchronous close of the stream, releasing resources
464 * related to it. When the operation is finished @callback will be
465 * called. You can then call g_io_stream_close_finish() to get
466 * the result of the operation.
468 * For behaviour details see g_io_stream_close().
470 * The asyncronous methods have a default fallback that uses threads
471 * to implement asynchronicity, so they are optional for inheriting
472 * classes. However, if you override one you must override all.
477 g_io_stream_close_async (GIOStream *stream,
479 GCancellable *cancellable,
480 GAsyncReadyCallback callback,
483 GIOStreamClass *class;
484 GSimpleAsyncResult *simple;
485 GError *error = NULL;
487 g_return_if_fail (G_IS_IO_STREAM (stream));
489 if (stream->priv->closed)
491 simple = g_simple_async_result_new (G_OBJECT (stream),
494 g_io_stream_close_async);
495 g_simple_async_result_complete_in_idle (simple);
496 g_object_unref (simple);
500 if (!g_io_stream_set_pending (stream, &error))
502 g_simple_async_report_gerror_in_idle (G_OBJECT (stream),
506 g_error_free (error);
510 class = G_IO_STREAM_GET_CLASS (stream);
511 stream->priv->outstanding_callback = callback;
512 g_object_ref (stream);
513 class->close_async (stream, io_priority, cancellable,
514 async_ready_close_callback_wrapper, user_data);
518 * g_io_stream_close_finish:
519 * @stream: a #GIOStream.
520 * @result: a #GAsyncResult.
521 * @error: a #GError location to store the error occuring, or %NULL to
526 * Returns: %TRUE if stream was successfully closed, %FALSE otherwise.
531 g_io_stream_close_finish (GIOStream *stream,
532 GAsyncResult *result,
535 GSimpleAsyncResult *simple;
536 GIOStreamClass *class;
538 g_return_val_if_fail (G_IS_IO_STREAM (stream), FALSE);
539 g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
541 if (G_IS_SIMPLE_ASYNC_RESULT (result))
543 simple = G_SIMPLE_ASYNC_RESULT (result);
544 if (g_simple_async_result_propagate_error (simple, error))
547 /* Special case already closed */
548 if (g_simple_async_result_get_source_tag (simple) == g_io_stream_close_async)
552 class = G_IO_STREAM_GET_CLASS (stream);
553 return class->close_finish (stream, result, error);
558 close_async_thread (GSimpleAsyncResult *res,
560 GCancellable *cancellable)
562 GIOStreamClass *class;
563 GError *error = NULL;
566 /* Auto handling of cancelation disabled, and ignore
567 cancellation, since we want to close things anyway, although
568 possibly in a quick-n-dirty way. At least we never want to leak
571 class = G_IO_STREAM_GET_CLASS (object);
572 result = class->close_fn (G_IO_STREAM (object), cancellable, &error);
575 g_simple_async_result_set_from_error (res, error);
576 g_error_free (error);
581 g_io_stream_real_close_async (GIOStream *stream,
583 GCancellable *cancellable,
584 GAsyncReadyCallback callback,
587 GSimpleAsyncResult *res;
589 res = g_simple_async_result_new (G_OBJECT (stream),
592 g_io_stream_real_close_async);
594 g_simple_async_result_set_handle_cancellation (res, FALSE);
596 g_simple_async_result_run_in_thread (res,
600 g_object_unref (res);
604 g_io_stream_real_close_finish (GIOStream *stream,
605 GAsyncResult *result,
608 GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
609 g_warn_if_fail (g_simple_async_result_get_source_tag (simple) ==
610 g_io_stream_real_close_async);
614 #define __G_IO_STREAM_C__
615 #include "gioaliasdef.c"