gio/gpollableinputstream.c

   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 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, write to the
  17  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  18  * Boston, MA 02111-1307, USA.
  19  */
  20
  21 #include "config.h"
  22
  23 #include <errno.h>
  24
  25 #include "gpollableinputstream.h"
  26 #include "gasynchelper.h"
  27 #include "gio-marshal.h"
  28 #include "glibintl.h"
  29
  30 /**
  31  * SECTION:gpollableinputstream
  32  * @short_description: Interface for pollable input streams
  33  * @include: gio/gio.h
  34  * @see_also: #GInputStream, #GPollableOutputStream, #GFileDescriptorBased
  35  *
  36  * #GPollableInputStream is implemented by #GInputStream<!-- -->s that
  37  * can be polled for readiness to read. This can be used when
  38  * interfacing with a non-GIO API that expects
  39  * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
  40  *
  41  * Since: 2.28
  42  */
  43
  44 G_DEFINE_INTERFACE (GPollableInputStream, g_pollable_input_stream, G_TYPE_INPUT_STREAM)
  45
  46 static gboolean g_pollable_input_stream_default_can_poll         (GPollableInputStream *stream);
  47 static gssize   g_pollable_input_stream_default_read_nonblocking (GPollableInputStream  *stream,
  48                                                                   void                  *buffer,
  49                                                                   gsize                  size,
  50                                                                   GError               **error);
  51
  52 static void
  53 g_pollable_input_stream_default_init (GPollableInputStreamInterface *iface)
  54 {
  55   iface->can_poll         = g_pollable_input_stream_default_can_poll;
  56   iface->read_nonblocking = g_pollable_input_stream_default_read_nonblocking;
  57 }
  58
  59 static gboolean
  60 g_pollable_input_stream_default_can_poll (GPollableInputStream *stream)
  61 {
  62   return TRUE;
  63 }
  64
  65 /**
  66  * g_pollable_input_stream_can_poll:
  67  * @stream: a #GPollableInputStream.
  68  *
  69  * Checks if @stream is actually pollable. Some classes may implement
  70  * #GPollableInputStream but have only certain instances of that class
  71  * be pollable. If this method returns %FALSE, then the behavior of
  72  * other #GPollableInputStream methods is undefined.
  73  *
  74  * For any given stream, the value returned by this method is constant;
  75  * a stream cannot switch from pollable to non-pollable or vice versa.
  76  *
  77  * Returns: %TRUE if @stream is pollable, %FALSE if not.
  78  *
  79  * Since: 2.28
  80  */
  81 gboolean
  82 g_pollable_input_stream_can_poll (GPollableInputStream *stream)
  83 {
  84   g_return_val_if_fail (G_IS_POLLABLE_INPUT_STREAM (stream), FALSE);
  85
  86   return G_POLLABLE_INPUT_STREAM_GET_INTERFACE (stream)->can_poll (stream);
  87 }
  88
  89 /**
  90  * g_pollable_input_stream_is_readable:
  91  * @stream: a #GPollableInputStream.
  92  *
  93  * Checks if @stream can be read.
  94  *
  95  * Note that some stream types may not be able to implement this 100%
  96  * reliably, and it is possible that a call to g_input_stream_read()
  97  * after this returns %TRUE would still block. To guarantee
  98  * non-blocking behavior, you should always use
  99  * g_pollable_input_stream_read_nonblocking(), which will return a
 100  * %G_IO_ERROR_WOULD_BLOCK error rather than blocking.
 101  *
 102  * Returns: %TRUE if @stream is readable, %FALSE if not. If an error
 103  *   has occurred on @stream, this will result in
 104  *   g_pollable_input_stream_is_readable() returning %TRUE, and the
 105  *   next attempt to read will return the error.
 106  *
 107  * Since: 2.28
 108  */
 109 gboolean
 110 g_pollable_input_stream_is_readable (GPollableInputStream *stream)
 111 {
 112   g_return_val_if_fail (G_IS_POLLABLE_INPUT_STREAM (stream), FALSE);
 113
 114   return G_POLLABLE_INPUT_STREAM_GET_INTERFACE (stream)->is_readable (stream);
 115 }
 116
 117 /**
 118  * g_pollable_input_stream_create_source: (skip)
 119  * @stream: a #GPollableInputStream.
 120  * @cancellable: (allow-none): a #GCancellable, or %NULL
 121  *
 122  * Creates a #GSource that triggers when @stream can be read, or
 123  * @cancellable is triggered or an error occurs. The callback on the
 124  * source is of the #GPollableSourceFunc type.
 125  *
 126  * As with g_pollable_input_stream_is_readable(), it is possible that
 127  * the stream may not actually be readable even after the source
 128  * triggers, so you should use g_pollable_input_stream_read_nonblocking()
 129  * rather than g_input_stream_read() from the callback.
 130  *
 131  * Returns: (transfer full): a new #GSource
 132  *
 133  * Since: 2.28
 134  */
 135 GSource *
 136 g_pollable_input_stream_create_source (GPollableInputStream *stream,
 137                                        GCancellable         *cancellable)
 138 {
 139   g_return_val_if_fail (G_IS_POLLABLE_INPUT_STREAM (stream), NULL);
 140
 141   return G_POLLABLE_INPUT_STREAM_GET_INTERFACE (stream)->
 142           create_source (stream, cancellable);
 143 }
 144
 145 static gssize
 146 g_pollable_input_stream_default_read_nonblocking (GPollableInputStream  *stream,
 147                                                   void                  *buffer,
 148                                                   gsize                  size,
 149                                                   GError               **error)
 150 {
 151   if (!g_pollable_input_stream_is_readable (stream))
 152     {
 153       g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_WOULD_BLOCK,
 154                            g_strerror (EAGAIN));
 155       return -1;
 156     }
 157
 158   return g_input_stream_read (G_INPUT_STREAM (stream), buffer, size,
 159                               NULL, error);
 160 }
 161
 162 /**
 163  * g_pollable_input_stream_read_nonblocking:
 164  * @stream: a #GPollableInputStream
 165  * @buffer: a buffer to read data into (which should be at least @size
 166  *     bytes long).
 167  * @size: the number of bytes you want to read
 168  * @cancellable: (allow-none): a #GCancellable, or %NULL
 169  * @error: #GError for error reporting, or %NULL to ignore.
 170  *
 171  * Attempts to read up to @size bytes from @stream into @buffer, as
 172  * with g_input_stream_read(). If @stream is not currently readable,
 173  * this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can
 174  * use g_pollable_input_stream_create_source() to create a #GSource
 175  * that will be triggered when @stream is readable.
 176  *
 177  * Note that since this method never blocks, you cannot actually
 178  * use @cancellable to cancel it. However, it will return an error
 179  * if @cancellable has already been cancelled when you call, which
 180  * may happen if you call this method after a source triggers due
 181  * to having been cancelled.
 182  *
 183  * Virtual: read_nonblocking
 184  * Return value: the number of bytes read, or -1 on error (including
 185  *   %G_IO_ERROR_WOULD_BLOCK).
 186  */
 187 gssize
 188 g_pollable_input_stream_read_nonblocking (GPollableInputStream  *stream,
 189                                           void                  *buffer,
 190                                           gsize                  size,
 191                                           GCancellable          *cancellable,
 192                                           GError               **error)
 193 {
 194   g_return_val_if_fail (G_IS_POLLABLE_INPUT_STREAM (stream), -1);
 195
 196   if (g_cancellable_set_error_if_cancelled (cancellable, error))
 197     return -1;
 198
 199   return G_POLLABLE_INPUT_STREAM_GET_INTERFACE (stream)->
 200     read_nonblocking (stream, buffer, size, error);
 201 }
 202
 203 /* GPollableSource */
 204
 205 typedef struct {
 206   GSource       source;
 207
 208   GObject      *stream;
 209 } GPollableSource;
 210
 211 static gboolean
 212 pollable_source_prepare (GSource *source,
 213                          gint    *timeout)
 214 {
 215   *timeout = -1;
 216   return FALSE;
 217 }
 218
 219 static gboolean
 220 pollable_source_check (GSource *source)
 221 {
 222   return FALSE;
 223 }
 224
 225 static gboolean
 226 pollable_source_dispatch (GSource     *source,
 227                           GSourceFunc  callback,
 228                           gpointer     user_data)
 229 {
 230   GPollableSourceFunc func = (GPollableSourceFunc)callback;
 231   GPollableSource *pollable_source = (GPollableSource *)source;
 232
 233   return (*func) (pollable_source->stream, user_data);
 234 }
 235
 236 static void
 237 pollable_source_finalize (GSource *source)
 238 {
 239   GPollableSource *pollable_source = (GPollableSource *)source;
 240
 241   g_object_unref (pollable_source->stream);
 242 }
 243
 244 static gboolean
 245 pollable_source_closure_callback (GObject  *stream,
 246                                   gpointer  data)
 247 {
 248   GClosure *closure = data;
 249
 250   GValue param = { 0, };
 251   GValue result_value = { 0, };
 252   gboolean result;
 253
 254   g_value_init (&result_value, G_TYPE_BOOLEAN);
 255
 256   g_value_init (&param, G_TYPE_OBJECT);
 257   g_value_set_object (&param, stream);
 258
 259   g_closure_invoke (closure, &result_value, 1, &param, NULL);
 260
 261   result = g_value_get_boolean (&result_value);
 262   g_value_unset (&result_value);
 263   g_value_unset (&param);
 264
 265   return result;
 266 }
 267
 268 static GSourceFuncs pollable_source_funcs =
 269 {
 270   pollable_source_prepare,
 271   pollable_source_check,
 272   pollable_source_dispatch,
 273   pollable_source_finalize,
 274   (GSourceFunc)pollable_source_closure_callback,
 275   (GSourceDummyMarshal)_gio_marshal_BOOLEAN__VOID,
 276 };
 277
 278 /**
 279  * g_pollable_source_new: (skip)
 280  * @pollable_stream: the stream associated with the new source
 281  *
 282  * Utility method for #GPollableInputStream and #GPollableOutputStream
 283  * implementations. Creates a new #GSource that expects a callback of
 284  * type #GPollableSourceFunc. The new source does not actually do
 285  * anything on its own; use g_source_add_child_source() to add other
 286  * sources to it to cause it to trigger.
 287  *
 288  * Return value: (transfer full): the new #GSource.
 289  *
 290  * Since: 2.28
 291  */
 292 GSource *
 293 g_pollable_source_new (GObject *pollable_stream)
 294 {
 295   GSource *source;
 296   GPollableSource *pollable_source;
 297
 298   source = g_source_new (&pollable_source_funcs, sizeof (GPollableSource));
 299   g_source_set_name (source, "GPollableSource");
 300   pollable_source = (GPollableSource *)source;
 301   pollable_source->stream = g_object_ref (pollable_stream);
 302
 303   return source;
 304 }