/src/glib/gio/gpollableinputstream.c

Source (jump to first uncovered line)
/* GIO - GLib Input, Output and Streaming Library
 *
 * Copyright (C) 2010 Red Hat, Inc.
 *
 * SPDX-License-Identifier: LGPL-2.1-or-later
 *
 * 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.
 *
 * Some classes may implement #GPollableInputStream but have only certain
 * instances of that class be pollable. If g_pollable_input_stream_can_poll()
 * returns %FALSE, then the behavior of other #GPollableInputStream methods is
 * undefined.
 *
 * 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.
 *
 * The behaviour of this method is undefined if
 * g_pollable_input_stream_can_poll() returns %FALSE for @stream.
 *
 * 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.
 *
 * The behaviour of this method is undefined if
 * g_pollable_input_stream_can_poll() returns %FALSE for @stream.
 *
 * 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) (out caller-allocates): a
 *     buffer to read data into (which should be at least @count bytes long).
 * @count: (in): 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.
 *
 * The behaviour of this method is undefined if
 * g_pollable_input_stream_can_poll() returns %FALSE for @stream.
 *
 * 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-06-13 06:55

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