/src/pango/subprojects/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"

/**
 * GPollableInputStream:
 *
 * `GPollableInputStream` is implemented by [class@Gio.InputStream]s 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 [method@Gio.PollableInputStream.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: (virtual 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.
 *
 * 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-23 08:13

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