gio/gpollableoutputstream.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 "gpollableoutputstream.h"
  26 #include "gasynchelper.h"
  27 #include "gfiledescriptorbased.h"
  28 #include "gio-marshal.h"
  29 #include "glibintl.h"
  30
  31 /**
  32  * SECTION:gpollableoutputstream
  33  * @short_description: Interface for pollable output streams
  34  * @include: gio/gio.h
  35  * @see_also: #GOutputStream, #GFileDescriptorBased, #GPollableInputStream
  36  *
  37  * #GPollableOutputStream is implemented by #GOutputStream<!-- -->s that
  38  * can be polled for readiness to write. This can be used when
  39  * interfacing with a non-GIO API that expects
  40  * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
  41  *
  42  * Since: 2.28
  43  */
  44
  45 G_DEFINE_INTERFACE (GPollableOutputStream, g_pollable_output_stream, G_TYPE_OUTPUT_STREAM)
  46
  47 static gboolean g_pollable_output_stream_default_can_poll          (GPollableOutputStream *stream);
  48 static gssize   g_pollable_output_stream_default_write_nonblocking (GPollableOutputStream  *stream,
  49                                                                     const void             *buffer,
  50                                                                     gsize                   size,
  51                                                                     GError                **error);
  52
  53 static void
  54 g_pollable_output_stream_default_init (GPollableOutputStreamInterface *iface)
  55 {
  56   iface->can_poll          = g_pollable_output_stream_default_can_poll;
  57   iface->write_nonblocking = g_pollable_output_stream_default_write_nonblocking;
  58 }
  59
  60 static gboolean
  61 g_pollable_output_stream_default_can_poll (GPollableOutputStream *stream)
  62 {
  63   return TRUE;
  64 }
  65
  66 /**
  67  * g_pollable_output_stream_can_poll:
  68  * @stream: a #GPollableOutputStream.
  69  *
  70  * Checks if @stream is actually pollable. Some classes may implement
  71  * #GPollableOutputStream but have only certain instances of that
  72  * class be pollable. If this method returns %FALSE, then the behavior
  73  * of other #GPollableOutputStream 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_output_stream_can_poll (GPollableOutputStream *stream)
  84 {
  85   g_return_val_if_fail (G_IS_POLLABLE_OUTPUT_STREAM (stream), FALSE);
  86
  87   return G_POLLABLE_OUTPUT_STREAM_GET_INTERFACE (stream)->can_poll (stream);
  88 }
  89
  90 /**
  91  * g_pollable_output_stream_is_writable:
  92  * @stream: a #GPollableOutputStream.
  93  *
  94  * Checks if @stream can be written.
  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_output_stream_write()
  98  * after this returns %TRUE would still block. To guarantee
  99  * non-blocking behavior, you should always use
 100  * g_pollable_output_stream_write_nonblocking(), which will return a
 101  * %G_IO_ERROR_WOULD_BLOCK error rather than blocking.
 102  *
 103  * Returns: %TRUE if @stream is writable, %FALSE if not. If an error
 104  *   has occurred on @stream, this will result in
 105  *   g_pollable_output_stream_is_writable() returning %TRUE, and the
 106  *   next attempt to write will return the error.
 107  *
 108  * Since: 2.28
 109  */
 110 gboolean
 111 g_pollable_output_stream_is_writable (GPollableOutputStream *stream)
 112 {
 113   g_return_val_if_fail (G_IS_POLLABLE_OUTPUT_STREAM (stream), FALSE);
 114
 115   return G_POLLABLE_OUTPUT_STREAM_GET_INTERFACE (stream)->is_writable (stream);
 116 }
 117
 118 /**
 119  * g_pollable_output_stream_create_source: (skip)
 120  * @stream: a #GPollableOutputStream.
 121  * @cancellable: (allow-none): a #GCancellable, or %NULL
 122  *
 123  * Creates a #GSource that triggers when @stream can be written, or
 124  * @cancellable is triggered or an error occurs. The callback on the
 125  * source is of the #GPollableSourceFunc type.
 126  *
 127  * As with g_pollable_output_stream_is_writable(), it is possible that
 128  * the stream may not actually be writable even after the source
 129  * triggers, so you should use g_pollable_output_stream_write_nonblocking()
 130  * rather than g_output_stream_write() from the callback.
 131  *
 132  * Returns: (transfer full): a new #GSource
 133  *
 134  * Since: 2.28
 135  */
 136 GSource *
 137 g_pollable_output_stream_create_source (GPollableOutputStream *stream,
 138                                         GCancellable          *cancellable)
 139 {
 140   g_return_val_if_fail (G_IS_POLLABLE_OUTPUT_STREAM (stream), NULL);
 141
 142   return G_POLLABLE_OUTPUT_STREAM_GET_INTERFACE (stream)->
 143           create_source (stream, cancellable);
 144 }
 145
 146 static gssize
 147 g_pollable_output_stream_default_write_nonblocking (GPollableOutputStream  *stream,
 148                                                     const void             *buffer,
 149                                                     gsize                   size,
 150                                                     GError                **error)
 151 {
 152   if (!g_pollable_output_stream_is_writable (stream))
 153     {
 154       g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_WOULD_BLOCK,
 155                            g_strerror (EAGAIN));
 156       return -1;
 157     }
 158
 159   return g_output_stream_write (G_OUTPUT_STREAM (stream), buffer, size,
 160                                 NULL, error);
 161 }
 162
 163 /**
 164  * g_pollable_output_stream_write_nonblocking:
 165  * @stream: a #GPollableOutputStream
 166  * @buffer: (array length=size) (element-type guint8): a buffer to write
 167  *     data from
 168  * @size: the number of bytes you want to write
 169  * @cancellable: (allow-none): a #GCancellable, or %NULL
 170  * @error: #GError for error reporting, or %NULL to ignore.
 171  *
 172  * Attempts to write up to @size bytes from @buffer to @stream, as
 173  * with g_output_stream_write(). If @stream is not currently writable,
 174  * this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can
 175  * use g_pollable_output_stream_create_source() to create a #GSource
 176  * that will be triggered when @stream is writable.
 177  *
 178  * Note that since this method never blocks, you cannot actually
 179  * use @cancellable to cancel it. However, it will return an error
 180  * if @cancellable has already been cancelled when you call, which
 181  * may happen if you call this method after a source triggers due
 182  * to having been cancelled.
 183  *
 184  * Virtual: write_nonblocking
 185  * Return value: the number of bytes written, or -1 on error (including
 186  *   %G_IO_ERROR_WOULD_BLOCK).
 187  */
 188 gssize
 189 g_pollable_output_stream_write_nonblocking (GPollableOutputStream  *stream,
 190                                             const void             *buffer,
 191                                             gsize                   size,
 192                                             GCancellable           *cancellable,
 193                                             GError                **error)
 194 {
 195   g_return_val_if_fail (G_IS_POLLABLE_OUTPUT_STREAM (stream), -1);
 196
 197   if (g_cancellable_set_error_if_cancelled (cancellable, error))
 198     return -1;
 199
 200   return G_POLLABLE_OUTPUT_STREAM_GET_INTERFACE (stream)->
 201     write_nonblocking (stream, buffer, size, error);
 202 }