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_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_set_property (GObject *object,
159 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
164 g_io_stream_class_init (GIOStreamClass *klass)
166 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
168 g_type_class_add_private (klass, sizeof (GIOStreamPrivate));
170 gobject_class->finalize = g_io_stream_finalize;
171 gobject_class->dispose = g_io_stream_dispose;
172 gobject_class->set_property = g_io_stream_set_property;
173 gobject_class->get_property = g_io_stream_get_property;
175 klass->close_fn = g_io_stream_real_close;
176 klass->close_async = g_io_stream_real_close_async;
177 klass->close_finish = g_io_stream_real_close_finish;
179 g_object_class_install_property (gobject_class, PROP_CLOSED,
180 g_param_spec_boolean ("closed",
182 P_("Is the stream closed"),
184 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
186 g_object_class_install_property (gobject_class, PROP_INPUT_STREAM,
187 g_param_spec_object ("input-stream",
189 P_("The GInputStream to read from"),
191 G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
192 g_object_class_install_property (gobject_class, PROP_OUTPUT_STREAM,
193 g_param_spec_object ("output-stream",
195 P_("The GOutputStream to write to"),
196 G_TYPE_OUTPUT_STREAM,
197 G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
201 * g_io_stream_is_closed:
202 * @stream: a #GIOStream
204 * Checks if a stream is closed.
206 * Returns: %TRUE if the stream is closed.
211 g_io_stream_is_closed (GIOStream *stream)
213 g_return_val_if_fail (G_IS_IO_STREAM (stream), TRUE);
215 return stream->priv->closed;
219 * g_io_stream_get_input_stream:
220 * @stream: a #GIOStream
222 * Gets the input stream for this object. This is used
225 * Returns: a #GInputStream, owned by the #GIOStream. Do not free.
230 g_io_stream_get_input_stream (GIOStream *stream)
232 GIOStreamClass *klass;
234 klass = G_IO_STREAM_GET_CLASS (stream);
236 g_assert (klass->get_input_stream != NULL);
238 return klass->get_input_stream (stream);
242 * g_io_stream_get_output_stream:
243 * @stream: a #GIOStream
245 * Gets the output stream for this object. This is used for
248 * Returns: a #GOutputStream, owned by the #GIOStream. Do not free.
253 g_io_stream_get_output_stream (GIOStream *stream)
255 GIOStreamClass *klass;
257 klass = G_IO_STREAM_GET_CLASS (stream);
259 g_assert (klass->get_output_stream != NULL);
260 return klass->get_output_stream (stream);
264 * g_io_stream_has_pending:
265 * @stream: a #GIOStream
267 * Checks if a stream has pending actions.
269 * Returns: %TRUE if @stream has pending actions.
274 g_io_stream_has_pending (GIOStream *stream)
276 g_return_val_if_fail (G_IS_IO_STREAM (stream), FALSE);
278 return stream->priv->pending;
282 * g_io_stream_set_pending:
283 * @stream: a #GIOStream
284 * @error: a #GError location to store the error occuring, or %NULL to
287 * Sets @stream to have actions pending. If the pending flag is
288 * already set or @stream is closed, it will return %FALSE and set
291 * Return value: %TRUE if pending was previously unset and is now set.
296 g_io_stream_set_pending (GIOStream *stream,
299 g_return_val_if_fail (G_IS_IO_STREAM (stream), FALSE);
301 if (stream->priv->closed)
303 g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_CLOSED,
304 _("Stream is already closed"));
308 if (stream->priv->pending)
310 g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_PENDING,
311 /* Translators: This is an error you get if there is
312 * already an operation running against this stream when
313 * you try to start one */
314 _("Stream has outstanding operation"));
318 stream->priv->pending = TRUE;
323 * g_io_stream_clear_pending:
324 * @stream: a #GIOStream
326 * Clears the pending flag on @stream.
331 g_io_stream_clear_pending (GIOStream *stream)
333 g_return_if_fail (G_IS_IO_STREAM (stream));
335 stream->priv->pending = FALSE;
339 g_io_stream_real_close (GIOStream *stream,
340 GCancellable *cancellable,
345 res = g_output_stream_close (g_io_stream_get_output_stream (stream),
348 /* If this errored out, unset error so that we don't report
349 further errors, but still do the following ops */
350 if (error != NULL && *error != NULL)
353 res &= g_input_stream_close (g_io_stream_get_input_stream (stream),
361 * @stream: a #GIOStream
362 * @cancellable: optional #GCancellable object, %NULL to ignore
363 * @error: location to store the error occuring, or %NULL to ignore
365 * Closes the stream, releasing resources related to it. This will also
366 * closes the individual input and output streams, if they are not already
369 * Once the stream is closed, all other operations will return
370 * %G_IO_ERROR_CLOSED. Closing a stream multiple times will not
373 * Closing a stream will automatically flush any outstanding buffers
376 * Streams will be automatically closed when the last reference
377 * is dropped, but you might want to call this function to make sure
378 * resources are released as early as possible.
380 * Some streams might keep the backing store of the stream (e.g. a file
381 * descriptor) open after the stream is closed. See the documentation for
382 * the individual stream for details.
384 * On failure the first error that happened will be reported, but the
385 * close operation will finish as much as possible. A stream that failed
386 * to close will still return %G_IO_ERROR_CLOSED for all operations.
387 * Still, it is important to check and report the error to the user,
388 * otherwise there might be a loss of data as all data might not be written.
390 * If @cancellable is not NULL, then the operation can be cancelled by
391 * triggering the cancellable object from another thread. If the operation
392 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
393 * Cancelling a close will still leave the stream closed, but some streams
394 * can use a faster close that doesn't block to e.g. check errors.
396 * The default implementation of this method just calls close on the
397 * individual input/output streams.
399 * Return value: %TRUE on success, %FALSE on failure
404 g_io_stream_close (GIOStream *stream,
405 GCancellable *cancellable,
408 GIOStreamClass *class;
411 g_return_val_if_fail (G_IS_IO_STREAM (stream), FALSE);
413 class = G_IO_STREAM_GET_CLASS (stream);
415 if (stream->priv->closed)
418 if (!g_io_stream_set_pending (stream, error))
422 g_cancellable_push_current (cancellable);
426 res = class->close_fn (stream, cancellable, error);
429 g_cancellable_pop_current (cancellable);
431 stream->priv->closed = TRUE;
432 g_io_stream_clear_pending (stream);
438 async_ready_close_callback_wrapper (GObject *source_object,
442 GIOStream *stream = G_IO_STREAM (source_object);
444 stream->priv->closed = TRUE;
445 g_io_stream_clear_pending (stream);
446 if (stream->priv->outstanding_callback)
447 (*stream->priv->outstanding_callback) (source_object, res, user_data);
448 g_object_unref (stream);
452 * g_io_stream_close_async:
453 * @stream: a #GIOStream
454 * @io_priority: the io priority of the request
455 * @callback: callback to call when the request is satisfied
456 * @user_data: the data to pass to callback function
457 * @cancellable: optional cancellable object
459 * Requests an asynchronous close of the stream, releasing resources
460 * related to it. When the operation is finished @callback will be
461 * called. You can then call g_io_stream_close_finish() to get
462 * the result of the operation.
464 * For behaviour details see g_io_stream_close().
466 * The asynchronous methods have a default fallback that uses threads
467 * to implement asynchronicity, so they are optional for inheriting
468 * classes. However, if you override one you must override all.
473 g_io_stream_close_async (GIOStream *stream,
475 GCancellable *cancellable,
476 GAsyncReadyCallback callback,
479 GIOStreamClass *class;
480 GSimpleAsyncResult *simple;
481 GError *error = NULL;
483 g_return_if_fail (G_IS_IO_STREAM (stream));
485 if (stream->priv->closed)
487 simple = g_simple_async_result_new (G_OBJECT (stream),
490 g_io_stream_close_async);
491 g_simple_async_result_complete_in_idle (simple);
492 g_object_unref (simple);
496 if (!g_io_stream_set_pending (stream, &error))
498 g_simple_async_report_gerror_in_idle (G_OBJECT (stream),
502 g_error_free (error);
506 class = G_IO_STREAM_GET_CLASS (stream);
507 stream->priv->outstanding_callback = callback;
508 g_object_ref (stream);
509 class->close_async (stream, io_priority, cancellable,
510 async_ready_close_callback_wrapper, user_data);
514 * g_io_stream_close_finish:
515 * @stream: a #GIOStream
516 * @result: a #GAsyncResult
517 * @error: a #GError location to store the error occuring, or %NULL to
522 * Returns: %TRUE if stream was successfully closed, %FALSE otherwise.
527 g_io_stream_close_finish (GIOStream *stream,
528 GAsyncResult *result,
531 GSimpleAsyncResult *simple;
532 GIOStreamClass *class;
534 g_return_val_if_fail (G_IS_IO_STREAM (stream), FALSE);
535 g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
537 if (G_IS_SIMPLE_ASYNC_RESULT (result))
539 simple = G_SIMPLE_ASYNC_RESULT (result);
540 if (g_simple_async_result_propagate_error (simple, error))
543 /* Special case already closed */
544 if (g_simple_async_result_get_source_tag (simple) == g_io_stream_close_async)
548 class = G_IO_STREAM_GET_CLASS (stream);
549 return class->close_finish (stream, result, error);
554 close_async_thread (GSimpleAsyncResult *res,
556 GCancellable *cancellable)
558 GIOStreamClass *class;
559 GError *error = NULL;
562 /* Auto handling of cancelation disabled, and ignore cancellation,
563 * since we want to close things anyway, although possibly in a
564 * quick-n-dirty way. At least we never want to leak open handles
566 class = G_IO_STREAM_GET_CLASS (object);
569 result = class->close_fn (G_IO_STREAM (object), cancellable, &error);
572 g_simple_async_result_set_from_error (res, error);
573 g_error_free (error);
579 g_io_stream_real_close_async (GIOStream *stream,
581 GCancellable *cancellable,
582 GAsyncReadyCallback callback,
585 GSimpleAsyncResult *res;
587 res = g_simple_async_result_new (G_OBJECT (stream),
590 g_io_stream_real_close_async);
592 g_simple_async_result_set_handle_cancellation (res, FALSE);
594 g_simple_async_result_run_in_thread (res,
598 g_object_unref (res);
602 g_io_stream_real_close_finish (GIOStream *stream,
603 GAsyncResult *result,
606 GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
607 g_warn_if_fail (g_simple_async_result_get_source_tag (simple) ==
608 g_io_stream_real_close_async);