1 /* GIO - GLib Input, Output and Streaming Library
3 * Copyright (C) 2006-2007 Red Hat, Inc.
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
15 * You should have received a copy of the GNU Lesser General
16 * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
18 * Author: Alexander Larsson <alexl@redhat.com>
25 #include "ginputstream.h"
26 #include "gioprivate.h"
27 #include "gseekable.h"
28 #include "gcancellable.h"
29 #include "gasyncresult.h"
31 #include "gpollableinputstream.h"
34 * SECTION:ginputstream
35 * @short_description: Base class for implementing streaming input
38 * #GInputStream has functions to read from a stream (g_input_stream_read()),
39 * to close a stream (g_input_stream_close()) and to skip some content
40 * (g_input_stream_skip()).
42 * To copy the content of an input stream to an output stream without
43 * manually handling the reads and writes, use g_output_stream_splice().
45 * See the documentation for #GIOStream for details of thread safety of
48 * All of these functions have async variants too.
51 struct _GInputStreamPrivate
{
54 GAsyncReadyCallback outstanding_callback
;
57 G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GInputStream
, g_input_stream
, G_TYPE_OBJECT
)
59 static gssize
g_input_stream_real_skip (GInputStream
*stream
,
61 GCancellable
*cancellable
,
63 static void g_input_stream_real_read_async (GInputStream
*stream
,
67 GCancellable
*cancellable
,
68 GAsyncReadyCallback callback
,
70 static gssize
g_input_stream_real_read_finish (GInputStream
*stream
,
73 static void g_input_stream_real_skip_async (GInputStream
*stream
,
76 GCancellable
*cancellable
,
77 GAsyncReadyCallback callback
,
79 static gssize
g_input_stream_real_skip_finish (GInputStream
*stream
,
82 static void g_input_stream_real_close_async (GInputStream
*stream
,
84 GCancellable
*cancellable
,
85 GAsyncReadyCallback callback
,
87 static gboolean
g_input_stream_real_close_finish (GInputStream
*stream
,
92 g_input_stream_dispose (GObject
*object
)
96 stream
= G_INPUT_STREAM (object
);
98 if (!stream
->priv
->closed
)
99 g_input_stream_close (stream
, NULL
, NULL
);
101 G_OBJECT_CLASS (g_input_stream_parent_class
)->dispose (object
);
106 g_input_stream_class_init (GInputStreamClass
*klass
)
108 GObjectClass
*gobject_class
= G_OBJECT_CLASS (klass
);
110 gobject_class
->dispose
= g_input_stream_dispose
;
112 klass
->skip
= g_input_stream_real_skip
;
113 klass
->read_async
= g_input_stream_real_read_async
;
114 klass
->read_finish
= g_input_stream_real_read_finish
;
115 klass
->skip_async
= g_input_stream_real_skip_async
;
116 klass
->skip_finish
= g_input_stream_real_skip_finish
;
117 klass
->close_async
= g_input_stream_real_close_async
;
118 klass
->close_finish
= g_input_stream_real_close_finish
;
122 g_input_stream_init (GInputStream
*stream
)
124 stream
->priv
= g_input_stream_get_instance_private (stream
);
128 * g_input_stream_read:
129 * @stream: a #GInputStream.
130 * @buffer: (array length=count) (element-type guint8): a buffer to
131 * read data into (which should be at least count bytes long).
132 * @count: the number of bytes that will be read from the stream
133 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
134 * @error: location to store the error occurring, or %NULL to ignore
136 * Tries to read @count bytes from the stream into the buffer starting at
137 * @buffer. Will block during this read.
139 * If count is zero returns zero and does nothing. A value of @count
140 * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
142 * On success, the number of bytes read into the buffer is returned.
143 * It is not an error if this is not the same as the requested size, as it
144 * can happen e.g. near the end of a file. Zero is returned on end of file
145 * (or if @count is zero), but never otherwise.
147 * The returned @buffer is not a nul-terminated string, it can contain nul bytes
148 * at any position, and this function doesn't nul-terminate the @buffer.
150 * If @cancellable is not %NULL, then the operation can be cancelled by
151 * triggering the cancellable object from another thread. If the operation
152 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
153 * operation was partially finished when the operation was cancelled the
154 * partial result will be returned, without an error.
156 * On error -1 is returned and @error is set accordingly.
158 * Returns: Number of bytes read, or -1 on error, or 0 on end of file.
161 g_input_stream_read (GInputStream
*stream
,
164 GCancellable
*cancellable
,
167 GInputStreamClass
*class;
170 g_return_val_if_fail (G_IS_INPUT_STREAM (stream
), -1);
171 g_return_val_if_fail (buffer
!= NULL
, 0);
176 if (((gssize
) count
) < 0)
178 g_set_error (error
, G_IO_ERROR
, G_IO_ERROR_INVALID_ARGUMENT
,
179 _("Too large count value passed to %s"), G_STRFUNC
);
183 class = G_INPUT_STREAM_GET_CLASS (stream
);
185 if (class->read_fn
== NULL
)
187 g_set_error_literal (error
, G_IO_ERROR
, G_IO_ERROR_NOT_SUPPORTED
,
188 _("Input stream doesn't implement read"));
192 if (!g_input_stream_set_pending (stream
, error
))
196 g_cancellable_push_current (cancellable
);
198 res
= class->read_fn (stream
, buffer
, count
, cancellable
, error
);
201 g_cancellable_pop_current (cancellable
);
203 g_input_stream_clear_pending (stream
);
209 * g_input_stream_read_all:
210 * @stream: a #GInputStream.
211 * @buffer: (array length=count) (element-type guint8): a buffer to
212 * read data into (which should be at least count bytes long).
213 * @count: the number of bytes that will be read from the stream
214 * @bytes_read: (out): location to store the number of bytes that was read from the stream
215 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
216 * @error: location to store the error occurring, or %NULL to ignore
218 * Tries to read @count bytes from the stream into the buffer starting at
219 * @buffer. Will block during this read.
221 * This function is similar to g_input_stream_read(), except it tries to
222 * read as many bytes as requested, only stopping on an error or end of stream.
224 * On a successful read of @count bytes, or if we reached the end of the
225 * stream, %TRUE is returned, and @bytes_read is set to the number of bytes
228 * If there is an error during the operation %FALSE is returned and @error
229 * is set to indicate the error status.
231 * As a special exception to the normal conventions for functions that
232 * use #GError, if this function returns %FALSE (and sets @error) then
233 * @bytes_read will be set to the number of bytes that were successfully
234 * read before the error was encountered. This functionality is only
235 * available from C. If you need it from another language then you must
236 * write your own loop around g_input_stream_read().
238 * Returns: %TRUE on success, %FALSE if there was an error
241 g_input_stream_read_all (GInputStream
*stream
,
245 GCancellable
*cancellable
,
251 g_return_val_if_fail (G_IS_INPUT_STREAM (stream
), FALSE
);
252 g_return_val_if_fail (buffer
!= NULL
, FALSE
);
255 while (_bytes_read
< count
)
257 res
= g_input_stream_read (stream
, (char *)buffer
+ _bytes_read
, count
- _bytes_read
,
262 *bytes_read
= _bytes_read
;
273 *bytes_read
= _bytes_read
;
278 * g_input_stream_read_bytes:
279 * @stream: a #GInputStream.
280 * @count: maximum number of bytes that will be read from the stream. Common
281 * values include 4096 and 8192.
282 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
283 * @error: location to store the error occurring, or %NULL to ignore
285 * Like g_input_stream_read(), this tries to read @count bytes from
286 * the stream in a blocking fashion. However, rather than reading into
287 * a user-supplied buffer, this will create a new #GBytes containing
288 * the data that was read. This may be easier to use from language
291 * If count is zero, returns a zero-length #GBytes and does nothing. A
292 * value of @count larger than %G_MAXSSIZE will cause a
293 * %G_IO_ERROR_INVALID_ARGUMENT error.
295 * On success, a new #GBytes is returned. It is not an error if the
296 * size of this object is not the same as the requested size, as it
297 * can happen e.g. near the end of a file. A zero-length #GBytes is
298 * returned on end of file (or if @count is zero), but never
301 * If @cancellable is not %NULL, then the operation can be cancelled by
302 * triggering the cancellable object from another thread. If the operation
303 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
304 * operation was partially finished when the operation was cancelled the
305 * partial result will be returned, without an error.
307 * On error %NULL is returned and @error is set accordingly.
309 * Returns: a new #GBytes, or %NULL on error
314 g_input_stream_read_bytes (GInputStream
*stream
,
316 GCancellable
*cancellable
,
322 buf
= g_malloc (count
);
323 nread
= g_input_stream_read (stream
, buf
, count
, cancellable
, error
);
332 return g_bytes_new_static ("", 0);
335 return g_bytes_new_take (buf
, nread
);
339 * g_input_stream_skip:
340 * @stream: a #GInputStream.
341 * @count: the number of bytes that will be skipped from the stream
342 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
343 * @error: location to store the error occurring, or %NULL to ignore
345 * Tries to skip @count bytes from the stream. Will block during the operation.
347 * This is identical to g_input_stream_read(), from a behaviour standpoint,
348 * but the bytes that are skipped are not returned to the user. Some
349 * streams have an implementation that is more efficient than reading the data.
351 * This function is optional for inherited classes, as the default implementation
352 * emulates it using read.
354 * If @cancellable is not %NULL, then the operation can be cancelled by
355 * triggering the cancellable object from another thread. If the operation
356 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
357 * operation was partially finished when the operation was cancelled the
358 * partial result will be returned, without an error.
360 * Returns: Number of bytes skipped, or -1 on error
363 g_input_stream_skip (GInputStream
*stream
,
365 GCancellable
*cancellable
,
368 GInputStreamClass
*class;
371 g_return_val_if_fail (G_IS_INPUT_STREAM (stream
), -1);
376 if (((gssize
) count
) < 0)
378 g_set_error (error
, G_IO_ERROR
, G_IO_ERROR_INVALID_ARGUMENT
,
379 _("Too large count value passed to %s"), G_STRFUNC
);
383 class = G_INPUT_STREAM_GET_CLASS (stream
);
385 if (!g_input_stream_set_pending (stream
, error
))
389 g_cancellable_push_current (cancellable
);
391 res
= class->skip (stream
, count
, cancellable
, error
);
394 g_cancellable_pop_current (cancellable
);
396 g_input_stream_clear_pending (stream
);
402 g_input_stream_real_skip (GInputStream
*stream
,
404 GCancellable
*cancellable
,
407 GInputStreamClass
*class;
408 gssize ret
, read_bytes
;
412 if (G_IS_SEEKABLE (stream
) && g_seekable_can_seek (G_SEEKABLE (stream
)))
414 if (g_seekable_seek (G_SEEKABLE (stream
),
422 /* If not seekable, or seek failed, fall back to reading data: */
424 class = G_INPUT_STREAM_GET_CLASS (stream
);
431 ret
= class->read_fn (stream
, buffer
, MIN (sizeof (buffer
), count
),
432 cancellable
, &my_error
);
435 if (read_bytes
> 0 &&
436 my_error
->domain
== G_IO_ERROR
&&
437 my_error
->code
== G_IO_ERROR_CANCELLED
)
439 g_error_free (my_error
);
443 g_propagate_error (error
, my_error
);
450 if (ret
== 0 || count
== 0)
456 * g_input_stream_close:
457 * @stream: A #GInputStream.
458 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
459 * @error: location to store the error occurring, or %NULL to ignore
461 * Closes the stream, releasing resources related to it.
463 * Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED.
464 * Closing a stream multiple times will not return an error.
466 * Streams will be automatically closed when the last reference
467 * is dropped, but you might want to call this function to make sure
468 * resources are released as early as possible.
470 * Some streams might keep the backing store of the stream (e.g. a file descriptor)
471 * open after the stream is closed. See the documentation for the individual
472 * stream for details.
474 * On failure the first error that happened will be reported, but the close
475 * operation will finish as much as possible. A stream that failed to
476 * close will still return %G_IO_ERROR_CLOSED for all operations. Still, it
477 * is important to check and report the error to the user.
479 * If @cancellable is not %NULL, then the operation can be cancelled by
480 * triggering the cancellable object from another thread. If the operation
481 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
482 * Cancelling a close will still leave the stream closed, but some streams
483 * can use a faster close that doesn't block to e.g. check errors.
485 * Returns: %TRUE on success, %FALSE on failure
488 g_input_stream_close (GInputStream
*stream
,
489 GCancellable
*cancellable
,
492 GInputStreamClass
*class;
495 g_return_val_if_fail (G_IS_INPUT_STREAM (stream
), FALSE
);
497 class = G_INPUT_STREAM_GET_CLASS (stream
);
499 if (stream
->priv
->closed
)
504 if (!g_input_stream_set_pending (stream
, error
))
508 g_cancellable_push_current (cancellable
);
511 res
= class->close_fn (stream
, cancellable
, error
);
514 g_cancellable_pop_current (cancellable
);
516 g_input_stream_clear_pending (stream
);
518 stream
->priv
->closed
= TRUE
;
524 async_ready_callback_wrapper (GObject
*source_object
,
528 GInputStream
*stream
= G_INPUT_STREAM (source_object
);
530 g_input_stream_clear_pending (stream
);
531 if (stream
->priv
->outstanding_callback
)
532 (*stream
->priv
->outstanding_callback
) (source_object
, res
, user_data
);
533 g_object_unref (stream
);
537 async_ready_close_callback_wrapper (GObject
*source_object
,
541 GInputStream
*stream
= G_INPUT_STREAM (source_object
);
543 g_input_stream_clear_pending (stream
);
544 stream
->priv
->closed
= TRUE
;
545 if (stream
->priv
->outstanding_callback
)
546 (*stream
->priv
->outstanding_callback
) (source_object
, res
, user_data
);
547 g_object_unref (stream
);
551 * g_input_stream_read_async:
552 * @stream: A #GInputStream.
553 * @buffer: (array length=count) (element-type guint8): a buffer to
554 * read data into (which should be at least count bytes long).
555 * @count: the number of bytes that will be read from the stream
556 * @io_priority: the [I/O priority][io-priority]
558 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
559 * @callback: (scope async): callback to call when the request is satisfied
560 * @user_data: (closure): the data to pass to callback function
562 * Request an asynchronous read of @count bytes from the stream into the buffer
563 * starting at @buffer. When the operation is finished @callback will be called.
564 * You can then call g_input_stream_read_finish() to get the result of the
567 * During an async request no other sync and async calls are allowed on @stream, and will
568 * result in %G_IO_ERROR_PENDING errors.
570 * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
572 * On success, the number of bytes read into the buffer will be passed to the
573 * callback. It is not an error if this is not the same as the requested size, as it
574 * can happen e.g. near the end of a file, but generally we try to read
575 * as many bytes as requested. Zero is returned on end of file
576 * (or if @count is zero), but never otherwise.
578 * Any outstanding i/o request with higher priority (lower numerical value) will
579 * be executed before an outstanding request with lower priority. Default
580 * priority is %G_PRIORITY_DEFAULT.
582 * The asyncronous methods have a default fallback that uses threads to implement
583 * asynchronicity, so they are optional for inheriting classes. However, if you
584 * override one you must override all.
587 g_input_stream_read_async (GInputStream
*stream
,
591 GCancellable
*cancellable
,
592 GAsyncReadyCallback callback
,
595 GInputStreamClass
*class;
596 GError
*error
= NULL
;
598 g_return_if_fail (G_IS_INPUT_STREAM (stream
));
599 g_return_if_fail (buffer
!= NULL
);
605 task
= g_task_new (stream
, cancellable
, callback
, user_data
);
606 g_task_set_source_tag (task
, g_input_stream_read_async
);
607 g_task_return_int (task
, 0);
608 g_object_unref (task
);
612 if (((gssize
) count
) < 0)
614 g_task_report_new_error (stream
, callback
, user_data
,
615 g_input_stream_read_async
,
616 G_IO_ERROR
, G_IO_ERROR_INVALID_ARGUMENT
,
617 _("Too large count value passed to %s"),
622 if (!g_input_stream_set_pending (stream
, &error
))
624 g_task_report_error (stream
, callback
, user_data
,
625 g_input_stream_read_async
,
630 class = G_INPUT_STREAM_GET_CLASS (stream
);
631 stream
->priv
->outstanding_callback
= callback
;
632 g_object_ref (stream
);
633 class->read_async (stream
, buffer
, count
, io_priority
, cancellable
,
634 async_ready_callback_wrapper
, user_data
);
638 * g_input_stream_read_finish:
639 * @stream: a #GInputStream.
640 * @result: a #GAsyncResult.
641 * @error: a #GError location to store the error occurring, or %NULL to
644 * Finishes an asynchronous stream read operation.
646 * Returns: number of bytes read in, or -1 on error, or 0 on end of file.
649 g_input_stream_read_finish (GInputStream
*stream
,
650 GAsyncResult
*result
,
653 GInputStreamClass
*class;
655 g_return_val_if_fail (G_IS_INPUT_STREAM (stream
), -1);
656 g_return_val_if_fail (G_IS_ASYNC_RESULT (result
), -1);
658 if (g_async_result_legacy_propagate_error (result
, error
))
660 else if (g_async_result_is_tagged (result
, g_input_stream_read_async
))
661 return g_task_propagate_int (G_TASK (result
), error
);
663 class = G_INPUT_STREAM_GET_CLASS (stream
);
664 return class->read_finish (stream
, result
, error
);
675 free_async_read_all (gpointer data
)
677 g_slice_free (AsyncReadAll
, data
);
681 read_all_callback (GObject
*stream
,
682 GAsyncResult
*result
,
685 GTask
*task
= user_data
;
686 AsyncReadAll
*data
= g_task_get_task_data (task
);
687 gboolean got_eof
= FALSE
;
691 GError
*error
= NULL
;
694 nread
= g_input_stream_read_finish (G_INPUT_STREAM (stream
), result
, &error
);
698 g_task_return_error (task
, error
);
699 g_object_unref (task
);
703 g_assert_cmpint (nread
, <=, data
->to_read
);
704 data
->to_read
-= nread
;
705 data
->bytes_read
+= nread
;
706 got_eof
= (nread
== 0);
709 if (got_eof
|| data
->to_read
== 0)
711 g_task_return_boolean (task
, TRUE
);
712 g_object_unref (task
);
716 g_input_stream_read_async (G_INPUT_STREAM (stream
),
717 data
->buffer
+ data
->bytes_read
,
719 g_task_get_priority (task
),
720 g_task_get_cancellable (task
),
721 read_all_callback
, task
);
726 read_all_async_thread (GTask
*task
,
727 gpointer source_object
,
729 GCancellable
*cancellable
)
731 GInputStream
*stream
= source_object
;
732 AsyncReadAll
*data
= task_data
;
733 GError
*error
= NULL
;
735 if (g_input_stream_read_all (stream
, data
->buffer
, data
->to_read
, &data
->bytes_read
,
736 g_task_get_cancellable (task
), &error
))
737 g_task_return_boolean (task
, TRUE
);
739 g_task_return_error (task
, error
);
743 * g_input_stream_read_all_async:
744 * @stream: A #GInputStream
745 * @buffer: (array length=count) (element-type guint8): a buffer to
746 * read data into (which should be at least count bytes long)
747 * @count: the number of bytes that will be read from the stream
748 * @io_priority: the [I/O priority][io-priority] of the request
749 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
750 * @callback: (scope async): callback to call when the request is satisfied
751 * @user_data: (closure): the data to pass to callback function
753 * Request an asynchronous read of @count bytes from the stream into the
754 * buffer starting at @buffer.
756 * This is the asynchronous equivalent of g_input_stream_read_all().
758 * Call g_input_stream_read_all_finish() to collect the result.
760 * Any outstanding I/O request with higher priority (lower numerical
761 * value) will be executed before an outstanding request with lower
762 * priority. Default priority is %G_PRIORITY_DEFAULT.
767 g_input_stream_read_all_async (GInputStream
*stream
,
771 GCancellable
*cancellable
,
772 GAsyncReadyCallback callback
,
778 g_return_if_fail (G_IS_INPUT_STREAM (stream
));
779 g_return_if_fail (buffer
!= NULL
|| count
== 0);
781 task
= g_task_new (stream
, cancellable
, callback
, user_data
);
782 data
= g_slice_new0 (AsyncReadAll
);
783 data
->buffer
= buffer
;
784 data
->to_read
= count
;
786 g_task_set_task_data (task
, data
, free_async_read_all
);
787 g_task_set_priority (task
, io_priority
);
789 /* If async reads are going to be handled via the threadpool anyway
790 * then we may as well do it with a single dispatch instead of
791 * bouncing in and out.
793 if (g_input_stream_async_read_is_via_threads (stream
))
795 g_task_run_in_thread (task
, read_all_async_thread
);
796 g_object_unref (task
);
799 read_all_callback (G_OBJECT (stream
), NULL
, task
);
803 * g_input_stream_read_all_finish:
804 * @stream: a #GInputStream
805 * @result: a #GAsyncResult
806 * @bytes_read: (out): location to store the number of bytes that was read from the stream
807 * @error: a #GError location to store the error occurring, or %NULL to ignore
809 * Finishes an asynchronous stream read operation started with
810 * g_input_stream_read_all_async().
812 * As a special exception to the normal conventions for functions that
813 * use #GError, if this function returns %FALSE (and sets @error) then
814 * @bytes_read will be set to the number of bytes that were successfully
815 * read before the error was encountered. This functionality is only
816 * available from C. If you need it from another language then you must
817 * write your own loop around g_input_stream_read_async().
819 * Returns: %TRUE on success, %FALSE if there was an error
824 g_input_stream_read_all_finish (GInputStream
*stream
,
825 GAsyncResult
*result
,
831 g_return_val_if_fail (G_IS_INPUT_STREAM (stream
), FALSE
);
832 g_return_val_if_fail (g_task_is_valid (result
, stream
), FALSE
);
834 task
= G_TASK (result
);
838 AsyncReadAll
*data
= g_task_get_task_data (task
);
840 *bytes_read
= data
->bytes_read
;
843 return g_task_propagate_boolean (task
, error
);
847 read_bytes_callback (GObject
*stream
,
848 GAsyncResult
*result
,
851 GTask
*task
= user_data
;
852 guchar
*buf
= g_task_get_task_data (task
);
853 GError
*error
= NULL
;
855 GBytes
*bytes
= NULL
;
857 nread
= g_input_stream_read_finish (G_INPUT_STREAM (stream
),
862 g_task_return_error (task
, error
);
867 bytes
= g_bytes_new_static ("", 0);
870 bytes
= g_bytes_new_take (buf
, nread
);
873 g_task_return_pointer (task
, bytes
, (GDestroyNotify
)g_bytes_unref
);
875 g_object_unref (task
);
879 * g_input_stream_read_bytes_async:
880 * @stream: A #GInputStream.
881 * @count: the number of bytes that will be read from the stream
882 * @io_priority: the [I/O priority][io-priority] of the request
883 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
884 * @callback: (scope async): callback to call when the request is satisfied
885 * @user_data: (closure): the data to pass to callback function
887 * Request an asynchronous read of @count bytes from the stream into a
888 * new #GBytes. When the operation is finished @callback will be
889 * called. You can then call g_input_stream_read_bytes_finish() to get the
890 * result of the operation.
892 * During an async request no other sync and async calls are allowed
893 * on @stream, and will result in %G_IO_ERROR_PENDING errors.
895 * A value of @count larger than %G_MAXSSIZE will cause a
896 * %G_IO_ERROR_INVALID_ARGUMENT error.
898 * On success, the new #GBytes will be passed to the callback. It is
899 * not an error if this is smaller than the requested size, as it can
900 * happen e.g. near the end of a file, but generally we try to read as
901 * many bytes as requested. Zero is returned on end of file (or if
902 * @count is zero), but never otherwise.
904 * Any outstanding I/O request with higher priority (lower numerical
905 * value) will be executed before an outstanding request with lower
906 * priority. Default priority is %G_PRIORITY_DEFAULT.
911 g_input_stream_read_bytes_async (GInputStream
*stream
,
914 GCancellable
*cancellable
,
915 GAsyncReadyCallback callback
,
921 task
= g_task_new (stream
, cancellable
, callback
, user_data
);
922 buf
= g_malloc (count
);
923 g_task_set_task_data (task
, buf
, NULL
);
925 g_input_stream_read_async (stream
, buf
, count
,
926 io_priority
, cancellable
,
927 read_bytes_callback
, task
);
931 * g_input_stream_read_bytes_finish:
932 * @stream: a #GInputStream.
933 * @result: a #GAsyncResult.
934 * @error: a #GError location to store the error occurring, or %NULL to
937 * Finishes an asynchronous stream read-into-#GBytes operation.
939 * Returns: the newly-allocated #GBytes, or %NULL on error
944 g_input_stream_read_bytes_finish (GInputStream
*stream
,
945 GAsyncResult
*result
,
948 g_return_val_if_fail (G_IS_INPUT_STREAM (stream
), NULL
);
949 g_return_val_if_fail (g_task_is_valid (result
, stream
), NULL
);
951 return g_task_propagate_pointer (G_TASK (result
), error
);
955 * g_input_stream_skip_async:
956 * @stream: A #GInputStream.
957 * @count: the number of bytes that will be skipped from the stream
958 * @io_priority: the [I/O priority][io-priority] of the request
959 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
960 * @callback: (scope async): callback to call when the request is satisfied
961 * @user_data: (closure): the data to pass to callback function
963 * Request an asynchronous skip of @count bytes from the stream.
964 * When the operation is finished @callback will be called.
965 * You can then call g_input_stream_skip_finish() to get the result
968 * During an async request no other sync and async calls are allowed,
969 * and will result in %G_IO_ERROR_PENDING errors.
971 * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
973 * On success, the number of bytes skipped will be passed to the callback.
974 * It is not an error if this is not the same as the requested size, as it
975 * can happen e.g. near the end of a file, but generally we try to skip
976 * as many bytes as requested. Zero is returned on end of file
977 * (or if @count is zero), but never otherwise.
979 * Any outstanding i/o request with higher priority (lower numerical value)
980 * will be executed before an outstanding request with lower priority.
981 * Default priority is %G_PRIORITY_DEFAULT.
983 * The asynchronous methods have a default fallback that uses threads to
984 * implement asynchronicity, so they are optional for inheriting classes.
985 * However, if you override one, you must override all.
988 g_input_stream_skip_async (GInputStream
*stream
,
991 GCancellable
*cancellable
,
992 GAsyncReadyCallback callback
,
995 GInputStreamClass
*class;
996 GError
*error
= NULL
;
998 g_return_if_fail (G_IS_INPUT_STREAM (stream
));
1004 task
= g_task_new (stream
, cancellable
, callback
, user_data
);
1005 g_task_set_source_tag (task
, g_input_stream_skip_async
);
1006 g_task_return_int (task
, 0);
1007 g_object_unref (task
);
1011 if (((gssize
) count
) < 0)
1013 g_task_report_new_error (stream
, callback
, user_data
,
1014 g_input_stream_skip_async
,
1015 G_IO_ERROR
, G_IO_ERROR_INVALID_ARGUMENT
,
1016 _("Too large count value passed to %s"),
1021 if (!g_input_stream_set_pending (stream
, &error
))
1023 g_task_report_error (stream
, callback
, user_data
,
1024 g_input_stream_skip_async
,
1029 class = G_INPUT_STREAM_GET_CLASS (stream
);
1030 stream
->priv
->outstanding_callback
= callback
;
1031 g_object_ref (stream
);
1032 class->skip_async (stream
, count
, io_priority
, cancellable
,
1033 async_ready_callback_wrapper
, user_data
);
1037 * g_input_stream_skip_finish:
1038 * @stream: a #GInputStream.
1039 * @result: a #GAsyncResult.
1040 * @error: a #GError location to store the error occurring, or %NULL to
1043 * Finishes a stream skip operation.
1045 * Returns: the size of the bytes skipped, or %-1 on error.
1048 g_input_stream_skip_finish (GInputStream
*stream
,
1049 GAsyncResult
*result
,
1052 GInputStreamClass
*class;
1054 g_return_val_if_fail (G_IS_INPUT_STREAM (stream
), -1);
1055 g_return_val_if_fail (G_IS_ASYNC_RESULT (result
), -1);
1057 if (g_async_result_legacy_propagate_error (result
, error
))
1059 else if (g_async_result_is_tagged (result
, g_input_stream_skip_async
))
1060 return g_task_propagate_int (G_TASK (result
), error
);
1062 class = G_INPUT_STREAM_GET_CLASS (stream
);
1063 return class->skip_finish (stream
, result
, error
);
1067 * g_input_stream_close_async:
1068 * @stream: A #GInputStream.
1069 * @io_priority: the [I/O priority][io-priority] of the request
1070 * @cancellable: (allow-none): optional cancellable object
1071 * @callback: (scope async): callback to call when the request is satisfied
1072 * @user_data: (closure): the data to pass to callback function
1074 * Requests an asynchronous closes of the stream, releasing resources related to it.
1075 * When the operation is finished @callback will be called.
1076 * You can then call g_input_stream_close_finish() to get the result of the
1079 * For behaviour details see g_input_stream_close().
1081 * The asyncronous methods have a default fallback that uses threads to implement
1082 * asynchronicity, so they are optional for inheriting classes. However, if you
1083 * override one you must override all.
1086 g_input_stream_close_async (GInputStream
*stream
,
1088 GCancellable
*cancellable
,
1089 GAsyncReadyCallback callback
,
1092 GInputStreamClass
*class;
1093 GError
*error
= NULL
;
1095 g_return_if_fail (G_IS_INPUT_STREAM (stream
));
1097 if (stream
->priv
->closed
)
1101 task
= g_task_new (stream
, cancellable
, callback
, user_data
);
1102 g_task_set_source_tag (task
, g_input_stream_close_async
);
1103 g_task_return_boolean (task
, TRUE
);
1104 g_object_unref (task
);
1108 if (!g_input_stream_set_pending (stream
, &error
))
1110 g_task_report_error (stream
, callback
, user_data
,
1111 g_input_stream_close_async
,
1116 class = G_INPUT_STREAM_GET_CLASS (stream
);
1117 stream
->priv
->outstanding_callback
= callback
;
1118 g_object_ref (stream
);
1119 class->close_async (stream
, io_priority
, cancellable
,
1120 async_ready_close_callback_wrapper
, user_data
);
1124 * g_input_stream_close_finish:
1125 * @stream: a #GInputStream.
1126 * @result: a #GAsyncResult.
1127 * @error: a #GError location to store the error occurring, or %NULL to
1130 * Finishes closing a stream asynchronously, started from g_input_stream_close_async().
1132 * Returns: %TRUE if the stream was closed successfully.
1135 g_input_stream_close_finish (GInputStream
*stream
,
1136 GAsyncResult
*result
,
1139 GInputStreamClass
*class;
1141 g_return_val_if_fail (G_IS_INPUT_STREAM (stream
), FALSE
);
1142 g_return_val_if_fail (G_IS_ASYNC_RESULT (result
), FALSE
);
1144 if (g_async_result_legacy_propagate_error (result
, error
))
1146 else if (g_async_result_is_tagged (result
, g_input_stream_close_async
))
1147 return g_task_propagate_boolean (G_TASK (result
), error
);
1149 class = G_INPUT_STREAM_GET_CLASS (stream
);
1150 return class->close_finish (stream
, result
, error
);
1154 * g_input_stream_is_closed:
1155 * @stream: input stream.
1157 * Checks if an input stream is closed.
1159 * Returns: %TRUE if the stream is closed.
1162 g_input_stream_is_closed (GInputStream
*stream
)
1164 g_return_val_if_fail (G_IS_INPUT_STREAM (stream
), TRUE
);
1166 return stream
->priv
->closed
;
1170 * g_input_stream_has_pending:
1171 * @stream: input stream.
1173 * Checks if an input stream has pending actions.
1175 * Returns: %TRUE if @stream has pending actions.
1178 g_input_stream_has_pending (GInputStream
*stream
)
1180 g_return_val_if_fail (G_IS_INPUT_STREAM (stream
), TRUE
);
1182 return stream
->priv
->pending
;
1186 * g_input_stream_set_pending:
1187 * @stream: input stream
1188 * @error: a #GError location to store the error occurring, or %NULL to
1191 * Sets @stream to have actions pending. If the pending flag is
1192 * already set or @stream is closed, it will return %FALSE and set
1195 * Returns: %TRUE if pending was previously unset and is now set.
1198 g_input_stream_set_pending (GInputStream
*stream
, GError
**error
)
1200 g_return_val_if_fail (G_IS_INPUT_STREAM (stream
), FALSE
);
1202 if (stream
->priv
->closed
)
1204 g_set_error_literal (error
, G_IO_ERROR
, G_IO_ERROR_CLOSED
,
1205 _("Stream is already closed"));
1209 if (stream
->priv
->pending
)
1211 g_set_error_literal (error
, G_IO_ERROR
, G_IO_ERROR_PENDING
,
1212 /* Translators: This is an error you get if there is already an
1213 * operation running against this stream when you try to start
1215 _("Stream has outstanding operation"));
1219 stream
->priv
->pending
= TRUE
;
1224 * g_input_stream_clear_pending:
1225 * @stream: input stream
1227 * Clears the pending flag on @stream.
1230 g_input_stream_clear_pending (GInputStream
*stream
)
1232 g_return_if_fail (G_IS_INPUT_STREAM (stream
));
1234 stream
->priv
->pending
= FALSE
;
1238 * g_input_stream_async_read_is_via_threads:
1239 * @stream: input stream
1241 * Checks if an input stream's read_async function uses threads.
1243 * Returns: %TRUE if @stream's read_async function uses threads.
1246 g_input_stream_async_read_is_via_threads (GInputStream
*stream
)
1248 GInputStreamClass
*class;
1250 g_return_val_if_fail (G_IS_INPUT_STREAM (stream
), FALSE
);
1252 class = G_INPUT_STREAM_GET_CLASS (stream
);
1254 return (class->read_async
== g_input_stream_real_read_async
&&
1255 !(G_IS_POLLABLE_INPUT_STREAM (stream
) &&
1256 g_pollable_input_stream_can_poll (G_POLLABLE_INPUT_STREAM (stream
))));
1260 * g_input_stream_async_close_is_via_threads:
1261 * @stream: input stream
1263 * Checks if an input stream's close_async function uses threads.
1265 * Returns: %TRUE if @stream's close_async function uses threads.
1268 g_input_stream_async_close_is_via_threads (GInputStream
*stream
)
1270 GInputStreamClass
*class;
1272 g_return_val_if_fail (G_IS_INPUT_STREAM (stream
), FALSE
);
1274 class = G_INPUT_STREAM_GET_CLASS (stream
);
1276 return class->close_async
== g_input_stream_real_close_async
;
1279 /********************************************
1280 * Default implementation of async ops *
1281 ********************************************/
1289 free_read_data (ReadData
*op
)
1291 g_slice_free (ReadData
, op
);
1295 read_async_thread (GTask
*task
,
1296 gpointer source_object
,
1298 GCancellable
*cancellable
)
1300 GInputStream
*stream
= source_object
;
1301 ReadData
*op
= task_data
;
1302 GInputStreamClass
*class;
1303 GError
*error
= NULL
;
1306 class = G_INPUT_STREAM_GET_CLASS (stream
);
1308 nread
= class->read_fn (stream
,
1309 op
->buffer
, op
->count
,
1310 g_task_get_cancellable (task
),
1313 g_task_return_error (task
, error
);
1315 g_task_return_int (task
, nread
);
1318 static void read_async_pollable (GPollableInputStream
*stream
,
1322 read_async_pollable_ready (GPollableInputStream
*stream
,
1325 GTask
*task
= user_data
;
1327 read_async_pollable (stream
, task
);
1332 read_async_pollable (GPollableInputStream
*stream
,
1335 ReadData
*op
= g_task_get_task_data (task
);
1336 GError
*error
= NULL
;
1339 if (g_task_return_error_if_cancelled (task
))
1342 nread
= G_POLLABLE_INPUT_STREAM_GET_INTERFACE (stream
)->
1343 read_nonblocking (stream
, op
->buffer
, op
->count
, &error
);
1345 if (g_error_matches (error
, G_IO_ERROR
, G_IO_ERROR_WOULD_BLOCK
))
1349 g_error_free (error
);
1351 source
= g_pollable_input_stream_create_source (stream
,
1352 g_task_get_cancellable (task
));
1353 g_task_attach_source (task
, source
,
1354 (GSourceFunc
) read_async_pollable_ready
);
1355 g_source_unref (source
);
1360 g_task_return_error (task
, error
);
1362 g_task_return_int (task
, nread
);
1363 /* g_input_stream_real_read_async() unrefs task */
1368 g_input_stream_real_read_async (GInputStream
*stream
,
1372 GCancellable
*cancellable
,
1373 GAsyncReadyCallback callback
,
1379 op
= g_slice_new0 (ReadData
);
1380 task
= g_task_new (stream
, cancellable
, callback
, user_data
);
1381 g_task_set_task_data (task
, op
, (GDestroyNotify
) free_read_data
);
1382 g_task_set_priority (task
, io_priority
);
1383 op
->buffer
= buffer
;
1386 if (!g_input_stream_async_read_is_via_threads (stream
))
1387 read_async_pollable (G_POLLABLE_INPUT_STREAM (stream
), task
);
1389 g_task_run_in_thread (task
, read_async_thread
);
1390 g_object_unref (task
);
1394 g_input_stream_real_read_finish (GInputStream
*stream
,
1395 GAsyncResult
*result
,
1398 g_return_val_if_fail (g_task_is_valid (result
, stream
), -1);
1400 return g_task_propagate_int (G_TASK (result
), error
);
1405 skip_async_thread (GTask
*task
,
1406 gpointer source_object
,
1408 GCancellable
*cancellable
)
1410 GInputStream
*stream
= source_object
;
1411 gsize count
= GPOINTER_TO_SIZE (task_data
);
1412 GInputStreamClass
*class;
1413 GError
*error
= NULL
;
1416 class = G_INPUT_STREAM_GET_CLASS (stream
);
1417 ret
= class->skip (stream
, count
,
1418 g_task_get_cancellable (task
),
1421 g_task_return_error (task
, error
);
1423 g_task_return_int (task
, ret
);
1429 gsize count_skipped
;
1430 } SkipFallbackAsyncData
;
1433 skip_callback_wrapper (GObject
*source_object
,
1437 GInputStreamClass
*class;
1438 GTask
*task
= user_data
;
1439 SkipFallbackAsyncData
*data
= g_task_get_task_data (task
);
1440 GError
*error
= NULL
;
1443 ret
= g_input_stream_read_finish (G_INPUT_STREAM (source_object
), res
, &error
);
1448 data
->count_skipped
+= ret
;
1450 if (data
->count
> 0)
1452 class = G_INPUT_STREAM_GET_CLASS (source_object
);
1453 class->read_async (G_INPUT_STREAM (source_object
),
1454 data
->buffer
, MIN (8192, data
->count
),
1455 g_task_get_priority (task
),
1456 g_task_get_cancellable (task
),
1457 skip_callback_wrapper
, task
);
1463 g_error_matches (error
, G_IO_ERROR
, G_IO_ERROR_CANCELLED
) &&
1464 data
->count_skipped
)
1466 /* No error, return partial read */
1467 g_clear_error (&error
);
1471 g_task_return_error (task
, error
);
1473 g_task_return_int (task
, data
->count_skipped
);
1474 g_object_unref (task
);
1478 g_input_stream_real_skip_async (GInputStream
*stream
,
1481 GCancellable
*cancellable
,
1482 GAsyncReadyCallback callback
,
1485 GInputStreamClass
*class;
1486 SkipFallbackAsyncData
*data
;
1489 class = G_INPUT_STREAM_GET_CLASS (stream
);
1491 task
= g_task_new (stream
, cancellable
, callback
, user_data
);
1492 g_task_set_priority (task
, io_priority
);
1494 if (g_input_stream_async_read_is_via_threads (stream
))
1496 /* Read is thread-using async fallback.
1497 * Make skip use threads too, so that we can use a possible sync skip
1498 * implementation. */
1499 g_task_set_task_data (task
, GSIZE_TO_POINTER (count
), NULL
);
1501 g_task_run_in_thread (task
, skip_async_thread
);
1502 g_object_unref (task
);
1506 /* TODO: Skip fallback uses too much memory, should do multiple read calls */
1508 /* There is a custom async read function, lets use that. */
1509 data
= g_new (SkipFallbackAsyncData
, 1);
1510 data
->count
= count
;
1511 data
->count_skipped
= 0;
1512 g_task_set_task_data (task
, data
, g_free
);
1513 g_task_set_check_cancellable (task
, FALSE
);
1514 class->read_async (stream
, data
->buffer
, MIN (8192, count
), io_priority
, cancellable
,
1515 skip_callback_wrapper
, task
);
1521 g_input_stream_real_skip_finish (GInputStream
*stream
,
1522 GAsyncResult
*result
,
1525 g_return_val_if_fail (g_task_is_valid (result
, stream
), -1);
1527 return g_task_propagate_int (G_TASK (result
), error
);
1531 close_async_thread (GTask
*task
,
1532 gpointer source_object
,
1534 GCancellable
*cancellable
)
1536 GInputStream
*stream
= source_object
;
1537 GInputStreamClass
*class;
1538 GError
*error
= NULL
;
1541 class = G_INPUT_STREAM_GET_CLASS (stream
);
1542 if (class->close_fn
)
1544 result
= class->close_fn (stream
,
1545 g_task_get_cancellable (task
),
1549 g_task_return_error (task
, error
);
1554 g_task_return_boolean (task
, TRUE
);
1558 g_input_stream_real_close_async (GInputStream
*stream
,
1560 GCancellable
*cancellable
,
1561 GAsyncReadyCallback callback
,
1566 task
= g_task_new (stream
, cancellable
, callback
, user_data
);
1567 g_task_set_check_cancellable (task
, FALSE
);
1568 g_task_set_priority (task
, io_priority
);
1570 g_task_run_in_thread (task
, close_async_thread
);
1571 g_object_unref (task
);
1575 g_input_stream_real_close_finish (GInputStream
*stream
,
1576 GAsyncResult
*result
,
1579 g_return_val_if_fail (g_task_is_valid (result
, stream
), FALSE
);
1581 return g_task_propagate_boolean (G_TASK (result
), error
);