/src/glib/gio/gpollableinputstream.c

Source (jump to first uncovered line)
/* GIO - GLib Input, Output and Streaming Library
 *
 * Copyright (C) 2010 Red Hat, Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General
 * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
 */

#include "config.h"

#include <errno.h>

#include "gpollableinputstream.h"
#include "gasynchelper.h"
#include "glibintl.h"

/**
 * SECTION:gpollableinputstream
 * @short_description: Interface for pollable input streams
 * @include: gio/gio.h
 * @see_also: #GInputStream, #GPollableOutputStream, #GFileDescriptorBased
 *
 * #GPollableInputStream is implemented by #GInputStreams that
 * can be polled for readiness to read. This can be used when
 * interfacing with a non-GIO API that expects
 * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
 *
 * Since: 2.28
 */

G_DEFINE_INTERFACE (GPollableInputStream, g_pollable_input_stream, G_TYPE_INPUT_STREAM)

static gboolean g_pollable_input_stream_default_can_poll         (GPollableInputStream *stream);
static gssize   g_pollable_input_stream_default_read_nonblocking (GPollableInputStream  *stream,
                  void                  *buffer,
                  gsize                  count,
                  GError               **error);

static void
g_pollable_input_stream_default_init (GPollableInputStreamInterface *iface)
{
  iface->can_poll         = g_pollable_input_stream_default_can_poll;
  iface->read_nonblocking = g_pollable_input_stream_default_read_nonblocking;
}

static gboolean
g_pollable_input_stream_default_can_poll (GPollableInputStream *stream)
{
  return TRUE;
}

/**
 * g_pollable_input_stream_can_poll:
 * @stream: a #GPollableInputStream.
 *
 * Checks if @stream is actually pollable. Some classes may implement
 * #GPollableInputStream but have only certain instances of that class
 * be pollable. If this method returns %FALSE, then the behavior of
 * other #GPollableInputStream methods is undefined.
 *
 * For any given stream, the value returned by this method is constant;
 * a stream cannot switch from pollable to non-pollable or vice versa.
 *
 * Returns: %TRUE if @stream is pollable, %FALSE if not.
 *
 * Since: 2.28
 */
gboolean
g_pollable_input_stream_can_poll (GPollableInputStream *stream)
{
  g_return_val_if_fail (G_IS_POLLABLE_INPUT_STREAM (stream), FALSE);

  return G_POLLABLE_INPUT_STREAM_GET_INTERFACE (stream)->can_poll (stream);
}

/**
 * g_pollable_input_stream_is_readable:
 * @stream: a #GPollableInputStream.
 *
 * Checks if @stream can be read.
 *
 * Note that some stream types may not be able to implement this 100%
 * reliably, and it is possible that a call to g_input_stream_read()
 * after this returns %TRUE would still block. To guarantee
 * non-blocking behavior, you should always use
 * g_pollable_input_stream_read_nonblocking(), which will return a
 * %G_IO_ERROR_WOULD_BLOCK error rather than blocking.
 *
 * Returns: %TRUE if @stream is readable, %FALSE if not. If an error
 *   has occurred on @stream, this will result in
 *   g_pollable_input_stream_is_readable() returning %TRUE, and the
 *   next attempt to read will return the error.
 *
 * Since: 2.28
 */
gboolean
g_pollable_input_stream_is_readable (GPollableInputStream *stream)
{
  g_return_val_if_fail (G_IS_POLLABLE_INPUT_STREAM (stream), FALSE);

  return G_POLLABLE_INPUT_STREAM_GET_INTERFACE (stream)->is_readable (stream);
}

/**
 * g_pollable_input_stream_create_source:
 * @stream: a #GPollableInputStream.
 * @cancellable: (nullable): a #GCancellable, or %NULL
 *
 * Creates a #GSource that triggers when @stream can be read, or
 * @cancellable is triggered or an error occurs. The callback on the
 * source is of the #GPollableSourceFunc type.
 *
 * As with g_pollable_input_stream_is_readable(), it is possible that
 * the stream may not actually be readable even after the source
 * triggers, so you should use g_pollable_input_stream_read_nonblocking()
 * rather than g_input_stream_read() from the callback.
 *
 * Returns: (transfer full): a new #GSource
 *
 * Since: 2.28
 */
GSource *
g_pollable_input_stream_create_source (GPollableInputStream *stream,
               GCancellable         *cancellable)
{
  g_return_val_if_fail (G_IS_POLLABLE_INPUT_STREAM (stream), NULL);

  return G_POLLABLE_INPUT_STREAM_GET_INTERFACE (stream)->
    create_source (stream, cancellable);
}

static gssize
g_pollable_input_stream_default_read_nonblocking (GPollableInputStream  *stream,
              void                  *buffer,
              gsize                  count,
              GError               **error)
{
  if (!g_pollable_input_stream_is_readable (stream))
    {
      g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_WOULD_BLOCK,
                           g_strerror (EAGAIN));
      return -1;
    }

  return G_INPUT_STREAM_GET_CLASS (stream)->
    read_fn (G_INPUT_STREAM (stream), buffer, count, NULL, error);
}

/**
 * g_pollable_input_stream_read_nonblocking:
 * @stream: a #GPollableInputStream
 * @buffer: (array length=count) (element-type guint8): a buffer to
 *     read data into (which should be at least @count bytes long).
 * @count: the number of bytes you want to read
 * @cancellable: (nullable): a #GCancellable, or %NULL
 * @error: #GError for error reporting, or %NULL to ignore.
 *
 * Attempts to read up to @count bytes from @stream into @buffer, as
 * with g_input_stream_read(). If @stream is not currently readable,
 * this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can
 * use g_pollable_input_stream_create_source() to create a #GSource
 * that will be triggered when @stream is readable.
 *
 * Note that since this method never blocks, you cannot actually
 * use @cancellable to cancel it. However, it will return an error
 * if @cancellable has already been cancelled when you call, which
 * may happen if you call this method after a source triggers due
 * to having been cancelled.
 *
 * Virtual: read_nonblocking
 * Returns: the number of bytes read, or -1 on error (including
 *   %G_IO_ERROR_WOULD_BLOCK).
 */
gssize
g_pollable_input_stream_read_nonblocking (GPollableInputStream  *stream,
            void                  *buffer,
            gsize                  count,
            GCancellable          *cancellable,
            GError               **error)
{
  gssize res;

  g_return_val_if_fail (G_IS_POLLABLE_INPUT_STREAM (stream), -1);
  g_return_val_if_fail (buffer != NULL, 0);

  if (g_cancellable_set_error_if_cancelled (cancellable, error))
    return -1;

  if (count == 0)
    return 0;

  if (((gssize) count) < 0)
    {
      g_set_error (error, G_IO_ERROR, G_IO_ERROR_INVALID_ARGUMENT,
       _("Too large count value passed to %s"), G_STRFUNC);
      return -1;
    }

  if (cancellable)
    g_cancellable_push_current (cancellable);

  res = G_POLLABLE_INPUT_STREAM_GET_INTERFACE (stream)->
    read_nonblocking (stream, buffer, count, error);

  if (cancellable)
    g_cancellable_pop_current (cancellable);

  return res;
}

Coverage Report

Created: 2025-07-01 07:09

Line	Count	Source (jump to first uncovered line)
1		/* GIO - GLib Input, Output and Streaming Library
2		*
3		* Copyright (C) 2010 Red Hat, Inc.
4		*
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.1 of the License, or (at your option) any later version.
9		*
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.
14		*
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/>.
17		*/
18
19		#include "config.h"
20
21		#include <errno.h>
22
23		#include "gpollableinputstream.h"
24		#include "gasynchelper.h"
25		#include "glibintl.h"
26
27		/**
28		* SECTION:gpollableinputstream
29		* @short_description: Interface for pollable input streams
30		* @include: gio/gio.h
31		* @see_also: #GInputStream, #GPollableOutputStream, #GFileDescriptorBased
32		*
33		* #GPollableInputStream is implemented by #GInputStreams that
34		* can be polled for readiness to read. This can be used when
35		* interfacing with a non-GIO API that expects
36		* UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
37		*
38		* Since: 2.28
39		*/
40
41		G_DEFINE_INTERFACE (GPollableInputStream, g_pollable_input_stream, G_TYPE_INPUT_STREAM)
42
43		static gboolean g_pollable_input_stream_default_can_poll (GPollableInputStream *stream);
44		static gssize g_pollable_input_stream_default_read_nonblocking (GPollableInputStream *stream,
45		void *buffer,
46		gsize count,
47		GError **error);
48
49		static void
50		g_pollable_input_stream_default_init (GPollableInputStreamInterface *iface)
51	36	{
52	36	iface->can_poll = g_pollable_input_stream_default_can_poll;
53	36	iface->read_nonblocking = g_pollable_input_stream_default_read_nonblocking;
54	36	}
55
56		static gboolean
57		g_pollable_input_stream_default_can_poll (GPollableInputStream *stream)
58	0	{
59	0	return TRUE;
60	0	}
61
62		/**
63		* g_pollable_input_stream_can_poll:
64		* @stream: a #GPollableInputStream.
65		*
66		* Checks if @stream is actually pollable. Some classes may implement
67		* #GPollableInputStream but have only certain instances of that class
68		* be pollable. If this method returns %FALSE, then the behavior of
69		* other #GPollableInputStream methods is undefined.
70		*
71		* For any given stream, the value returned by this method is constant;
72		* a stream cannot switch from pollable to non-pollable or vice versa.
73		*
74		* Returns: %TRUE if @stream is pollable, %FALSE if not.
75		*
76		* Since: 2.28
77		*/
78		gboolean
79		g_pollable_input_stream_can_poll (GPollableInputStream *stream)
80	0	{
81	0	g_return_val_if_fail (G_IS_POLLABLE_INPUT_STREAM (stream), FALSE);
82
83	0	return G_POLLABLE_INPUT_STREAM_GET_INTERFACE (stream)->can_poll (stream);
84	0	}
85
86		/**
87		* g_pollable_input_stream_is_readable:
88		* @stream: a #GPollableInputStream.
89		*
90		* Checks if @stream can be read.
91		*
92		* Note that some stream types may not be able to implement this 100%
93		* reliably, and it is possible that a call to g_input_stream_read()
94		* after this returns %TRUE would still block. To guarantee
95		* non-blocking behavior, you should always use
96		* g_pollable_input_stream_read_nonblocking(), which will return a
97		* %G_IO_ERROR_WOULD_BLOCK error rather than blocking.
98		*
99		* Returns: %TRUE if @stream is readable, %FALSE if not. If an error
100		* has occurred on @stream, this will result in
101		* g_pollable_input_stream_is_readable() returning %TRUE, and the
102		* next attempt to read will return the error.
103		*
104		* Since: 2.28
105		*/
106		gboolean
107		g_pollable_input_stream_is_readable (GPollableInputStream *stream)
108	0	{
109	0	g_return_val_if_fail (G_IS_POLLABLE_INPUT_STREAM (stream), FALSE);
110
111	0	return G_POLLABLE_INPUT_STREAM_GET_INTERFACE (stream)->is_readable (stream);
112	0	}
113
114		/**
115		* g_pollable_input_stream_create_source:
116		* @stream: a #GPollableInputStream.
117		* @cancellable: (nullable): a #GCancellable, or %NULL
118		*
119		* Creates a #GSource that triggers when @stream can be read, or
120		* @cancellable is triggered or an error occurs. The callback on the
121		* source is of the #GPollableSourceFunc type.
122		*
123		* As with g_pollable_input_stream_is_readable(), it is possible that
124		* the stream may not actually be readable even after the source
125		* triggers, so you should use g_pollable_input_stream_read_nonblocking()
126		* rather than g_input_stream_read() from the callback.
127		*
128		* Returns: (transfer full): a new #GSource
129		*
130		* Since: 2.28
131		*/
132		GSource *
133		g_pollable_input_stream_create_source (GPollableInputStream *stream,
134		GCancellable *cancellable)
135	0	{
136	0	g_return_val_if_fail (G_IS_POLLABLE_INPUT_STREAM (stream), NULL);
137
138	0	return G_POLLABLE_INPUT_STREAM_GET_INTERFACE (stream)->
139	0	create_source (stream, cancellable);
140	0	}
141
142		static gssize
143		g_pollable_input_stream_default_read_nonblocking (GPollableInputStream *stream,
144		void *buffer,
145		gsize count,
146		GError **error)
147	0	{
148	0	if (!g_pollable_input_stream_is_readable (stream))
149	0	{
150	0	g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_WOULD_BLOCK,
151	0	g_strerror (EAGAIN));
152	0	return -1;
153	0	}
154
155	0	return G_INPUT_STREAM_GET_CLASS (stream)->
156	0	read_fn (G_INPUT_STREAM (stream), buffer, count, NULL, error);
157	0	}
158
159		/**
160		* g_pollable_input_stream_read_nonblocking:
161		* @stream: a #GPollableInputStream
162		* @buffer: (array length=count) (element-type guint8): a buffer to
163		* read data into (which should be at least @count bytes long).
164		* @count: the number of bytes you want to read
165		* @cancellable: (nullable): a #GCancellable, or %NULL
166		* @error: #GError for error reporting, or %NULL to ignore.
167		*
168		* Attempts to read up to @count bytes from @stream into @buffer, as
169		* with g_input_stream_read(). If @stream is not currently readable,
170		* this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can
171		* use g_pollable_input_stream_create_source() to create a #GSource
172		* that will be triggered when @stream is readable.
173		*
174		* Note that since this method never blocks, you cannot actually
175		* use @cancellable to cancel it. However, it will return an error
176		* if @cancellable has already been cancelled when you call, which
177		* may happen if you call this method after a source triggers due
178		* to having been cancelled.
179		*
180		* Virtual: read_nonblocking
181		* Returns: the number of bytes read, or -1 on error (including
182		* %G_IO_ERROR_WOULD_BLOCK).
183		*/
184		gssize
185		g_pollable_input_stream_read_nonblocking (GPollableInputStream *stream,
186		void *buffer,
187		gsize count,
188		GCancellable *cancellable,
189		GError **error)
190	0	{
191	0	gssize res;
192
193	0	g_return_val_if_fail (G_IS_POLLABLE_INPUT_STREAM (stream), -1);
194	0	g_return_val_if_fail (buffer != NULL, 0);
195
196	0	if (g_cancellable_set_error_if_cancelled (cancellable, error))
197	0	return -1;
198
199	0	if (count == 0)
200	0	return 0;
201
202	0	if (((gssize) count) < 0)
203	0	{
204	0	g_set_error (error, G_IO_ERROR, G_IO_ERROR_INVALID_ARGUMENT,
205	0	_("Too large count value passed to %s"), G_STRFUNC);
206	0	return -1;
207	0	}
208
209	0	if (cancellable)
210	0	g_cancellable_push_current (cancellable);
211
212	0	res = G_POLLABLE_INPUT_STREAM_GET_INTERFACE (stream)->
213	0	read_nonblocking (stream, buffer, count, error);
214
215	0	if (cancellable)
216	0	g_cancellable_pop_current (cancellable);
217
218	0	return res;
219	0	}