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.1 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, see <http://www.gnu.org/licenses/>.
  17  */
  18
  19 #include "config.h"
  20
  21 #include <errno.h>
  22
  23 #include "gpollableoutputstream.h"
  24 #include "gasynchelper.h"
  25 #include "gfiledescriptorbased.h"
  26 #include "glibintl.h"
  27
  28 /**
  29  * SECTION:gpollableoutputstream
  30  * @short_description: Interface for pollable output streams
  31  * @include: gio/gio.h
  32  * @see_also: #GOutputStream, #GFileDescriptorBased, #GPollableInputStream
  33  *
  34  * #GPollableOutputStream is implemented by #GOutputStreams that
  35  * can be polled for readiness to write. This can be used when
  36  * interfacing with a non-GIO API that expects
  37  * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
  38  *
  39  * Since: 2.28
  40  */
  41
  42 G_DEFINE_INTERFACE (GPollableOutputStream, g_pollable_output_stream, G_TYPE_OUTPUT_STREAM)
  43
  44 static gboolean g_pollable_output_stream_default_can_poll          (GPollableOutputStream *stream);
  45 static gssize   g_pollable_output_stream_default_write_nonblocking (GPollableOutputStream  *stream,
  46                                                                     const void             *buffer,
  47                                                                     gsize                   count,
  48                                                                     GError                **error);
  49
  50 static void
  51 g_pollable_output_stream_default_init (GPollableOutputStreamInterface *iface)
  52 {
  53   iface->can_poll          = g_pollable_output_stream_default_can_poll;
  54   iface->write_nonblocking = g_pollable_output_stream_default_write_nonblocking;
  55 }
  56
  57 static gboolean
  58 g_pollable_output_stream_default_can_poll (GPollableOutputStream *stream)
  59 {
  60   return TRUE;
  61 }
  62
  63 /**
  64  * g_pollable_output_stream_can_poll:
  65  * @stream: a #GPollableOutputStream.
  66  *
  67  * Checks if @stream is actually pollable. Some classes may implement
  68  * #GPollableOutputStream but have only certain instances of that
  69  * class be pollable. If this method returns %FALSE, then the behavior
  70  * of other #GPollableOutputStream methods is undefined.
  71  *
  72  * For any given stream, the value returned by this method is constant;
  73  * a stream cannot switch from pollable to non-pollable or vice versa.
  74  *
  75  * Returns: %TRUE if @stream is pollable, %FALSE if not.
  76  *
  77  * Since: 2.28
  78  */
  79 gboolean
  80 g_pollable_output_stream_can_poll (GPollableOutputStream *stream)
  81 {
  82   g_return_val_if_fail (G_IS_POLLABLE_OUTPUT_STREAM (stream), FALSE);
  83
  84   return G_POLLABLE_OUTPUT_STREAM_GET_INTERFACE (stream)->can_poll (stream);
  85 }
  86
  87 /**
  88  * g_pollable_output_stream_is_writable:
  89  * @stream: a #GPollableOutputStream.
  90  *
  91  * Checks if @stream can be written.
  92  *
  93  * Note that some stream types may not be able to implement this 100%
  94  * reliably, and it is possible that a call to g_output_stream_write()
  95  * after this returns %TRUE would still block. To guarantee
  96  * non-blocking behavior, you should always use
  97  * g_pollable_output_stream_write_nonblocking(), which will return a
  98  * %G_IO_ERROR_WOULD_BLOCK error rather than blocking.
  99  *
 100  * Returns: %TRUE if @stream is writable, %FALSE if not. If an error
 101  *   has occurred on @stream, this will result in
 102  *   g_pollable_output_stream_is_writable() returning %TRUE, and the
 103  *   next attempt to write will return the error.
 104  *
 105  * Since: 2.28
 106  */
 107 gboolean
 108 g_pollable_output_stream_is_writable (GPollableOutputStream *stream)
 109 {
 110   g_return_val_if_fail (G_IS_POLLABLE_OUTPUT_STREAM (stream), FALSE);
 111
 112   return G_POLLABLE_OUTPUT_STREAM_GET_INTERFACE (stream)->is_writable (stream);
 113 }
 114
 115 /**
 116  * g_pollable_output_stream_create_source:
 117  * @stream: a #GPollableOutputStream.
 118  * @cancellable: (nullable): a #GCancellable, or %NULL
 119  *
 120  * Creates a #GSource that triggers when @stream can be written, or
 121  * @cancellable is triggered or an error occurs. The callback on the
 122  * source is of the #GPollableSourceFunc type.
 123  *
 124  * As with g_pollable_output_stream_is_writable(), it is possible that
 125  * the stream may not actually be writable even after the source
 126  * triggers, so you should use g_pollable_output_stream_write_nonblocking()
 127  * rather than g_output_stream_write() from the callback.
 128  *
 129  * Returns: (transfer full): a new #GSource
 130  *
 131  * Since: 2.28
 132  */
 133 GSource *
 134 g_pollable_output_stream_create_source (GPollableOutputStream *stream,
 135                                         GCancellable          *cancellable)
 136 {
 137   g_return_val_if_fail (G_IS_POLLABLE_OUTPUT_STREAM (stream), NULL);
 138
 139   return G_POLLABLE_OUTPUT_STREAM_GET_INTERFACE (stream)->
 140           create_source (stream, cancellable);
 141 }
 142
 143 static gssize
 144 g_pollable_output_stream_default_write_nonblocking (GPollableOutputStream  *stream,
 145                                                     const void             *buffer,
 146                                                     gsize                   count,
 147                                                     GError                **error)
 148 {
 149   if (!g_pollable_output_stream_is_writable (stream))
 150     {
 151       g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_WOULD_BLOCK,
 152                            g_strerror (EAGAIN));
 153       return -1;
 154     }
 155
 156   return G_OUTPUT_STREAM_GET_CLASS (stream)->
 157     write_fn (G_OUTPUT_STREAM (stream), buffer, count, NULL, error);
 158 }
 159
 160 /**
 161  * g_pollable_output_stream_write_nonblocking:
 162  * @stream: a #GPollableOutputStream
 163  * @buffer: (array length=count) (element-type guint8): a buffer to write
 164  *     data from
 165  * @count: the number of bytes you want to write
 166  * @cancellable: (nullable): a #GCancellable, or %NULL
 167  * @error: #GError for error reporting, or %NULL to ignore.
 168  *
 169  * Attempts to write up to @count bytes from @buffer to @stream, as
 170  * with g_output_stream_write(). If @stream is not currently writable,
 171  * this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can
 172  * use g_pollable_output_stream_create_source() to create a #GSource
 173  * that will be triggered when @stream is writable.
 174  *
 175  * Note that since this method never blocks, you cannot actually
 176  * use @cancellable to cancel it. However, it will return an error
 177  * if @cancellable has already been cancelled when you call, which
 178  * may happen if you call this method after a source triggers due
 179  * to having been cancelled.
 180  *
 181  * Also note that if %G_IO_ERROR_WOULD_BLOCK is returned some underlying
 182  * transports like D/TLS require that you send the same @buffer and @count.
 183  *
 184  * Virtual: write_nonblocking
 185  * Returns: 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                   count,
 192                                             GCancellable           *cancellable,
 193                                             GError                **error)
 194 {
 195   gssize res;
 196
 197   g_return_val_if_fail (G_IS_POLLABLE_OUTPUT_STREAM (stream), -1);
 198   g_return_val_if_fail (buffer != NULL, 0);
 199
 200   if (g_cancellable_set_error_if_cancelled (cancellable, error))
 201     return -1;
 202
 203   if (count == 0)
 204     return 0;
 205
 206   if (((gssize) count) < 0)
 207     {
 208       g_set_error (error, G_IO_ERROR, G_IO_ERROR_INVALID_ARGUMENT,
 209                    _("Too large count value passed to %s"), G_STRFUNC);
 210       return -1;
 211     }
 212
 213   if (cancellable)
 214     g_cancellable_push_current (cancellable);
 215
 216   res = G_POLLABLE_OUTPUT_STREAM_GET_INTERFACE (stream)->
 217     write_nonblocking (stream, buffer, count, error);
 218
 219   if (cancellable)
 220     g_cancellable_pop_current (cancellable);
 221
 222   return res;
 223 }