gio/gpollableinputstream.c

   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 {
  59   iface->can_poll         = g_pollable_input_stream_default_can_poll;
  60   iface->read_nonblocking = g_pollable_input_stream_default_read_nonblocking;
  61 }
  62
  63 static gboolean
  64 g_pollable_input_stream_default_can_poll (GPollableInputStream *stream)
  65 {
  66   return TRUE;
  67 }
  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 {
  88   g_return_val_if_fail (G_IS_POLLABLE_INPUT_STREAM (stream), FALSE);
  89
  90   return G_POLLABLE_INPUT_STREAM_GET_INTERFACE (stream)->can_poll (stream);
  91 }
  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 {
 119   g_return_val_if_fail (G_IS_POLLABLE_INPUT_STREAM (stream), FALSE);
 120
 121   return G_POLLABLE_INPUT_STREAM_GET_INTERFACE (stream)->is_readable (stream);
 122 }
 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 {
 149   g_return_val_if_fail (G_IS_POLLABLE_INPUT_STREAM (stream), NULL);
 150
 151   return G_POLLABLE_INPUT_STREAM_GET_INTERFACE (stream)->
 152           create_source (stream, cancellable);
 153 }
 154
 155 static gssize
 156 g_pollable_input_stream_default_read_nonblocking (GPollableInputStream  *stream,
 157                                                   void                  *buffer,
 158                                                   gsize                  count,
 159                                                   GError               **error)
 160 {
 161   if (!g_pollable_input_stream_is_readable (stream))
 162     {
 163       g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_WOULD_BLOCK,
 164                            g_strerror (EAGAIN));
 165       return -1;
 166     }
 167
 168   return G_INPUT_STREAM_GET_CLASS (stream)->
 169     read_fn (G_INPUT_STREAM (stream), buffer, count, NULL, error);
 170 }
 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 {
 207   gssize res;
 208
 209   g_return_val_if_fail (G_IS_POLLABLE_INPUT_STREAM (stream), -1);
 210   g_return_val_if_fail (buffer != NULL, 0);
 211
 212   if (g_cancellable_set_error_if_cancelled (cancellable, error))
 213     return -1;
 214
 215   if (count == 0)
 216     return 0;
 217
 218   if (((gssize) count) < 0)
 219     {
 220       g_set_error (error, G_IO_ERROR, G_IO_ERROR_INVALID_ARGUMENT,
 221                    _("Too large count value passed to %s"), G_STRFUNC);
 222       return -1;
 223     }
 224
 225   if (cancellable)
 226     g_cancellable_push_current (cancellable);
 227
 228   res = G_POLLABLE_INPUT_STREAM_GET_INTERFACE (stream)->
 229     read_nonblocking (stream, buffer, count, error);
 230
 231   if (cancellable)
 232     g_cancellable_pop_current (cancellable);
 233
 234   return res;
 235 }