Merge branch '976-disable-assert-checks' into 'master'
[glib.git] / gio / gpollableoutputstream.c
blob40c649f0d50d01b3f18a6b7ce7d7600d6ba36311
1 /* GIO - GLib Input, Output and Streaming Library
3 * Copyright (C) 2010 Red Hat, Inc.
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.
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.
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/>.
19 #include "config.h"
21 #include <errno.h>
23 #include "gpollableoutputstream.h"
24 #include "gasynchelper.h"
25 #include "gfiledescriptorbased.h"
26 #include "glibintl.h"
28 /**
29 * SECTION:gpollableoutputstream
30 * @short_description: Interface for pollable output streams
31 * @include: gio/gio.h
32 * @see_also: #GOutputStream, #GFileDescriptorBased, #GPollableInputStream
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.
39 * Since: 2.28
42 G_DEFINE_INTERFACE (GPollableOutputStream, g_pollable_output_stream, G_TYPE_OUTPUT_STREAM)
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);
50 static void
51 g_pollable_output_stream_default_init (GPollableOutputStreamInterface *iface)
53 iface->can_poll = g_pollable_output_stream_default_can_poll;
54 iface->write_nonblocking = g_pollable_output_stream_default_write_nonblocking;
57 static gboolean
58 g_pollable_output_stream_default_can_poll (GPollableOutputStream *stream)
60 return TRUE;
63 /**
64 * g_pollable_output_stream_can_poll:
65 * @stream: a #GPollableOutputStream.
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.
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.
75 * Returns: %TRUE if @stream is pollable, %FALSE if not.
77 * Since: 2.28
79 gboolean
80 g_pollable_output_stream_can_poll (GPollableOutputStream *stream)
82 g_return_val_if_fail (G_IS_POLLABLE_OUTPUT_STREAM (stream), FALSE);
84 return G_POLLABLE_OUTPUT_STREAM_GET_INTERFACE (stream)->can_poll (stream);
87 /**
88 * g_pollable_output_stream_is_writable:
89 * @stream: a #GPollableOutputStream.
91 * Checks if @stream can be written.
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.
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.
105 * Since: 2.28
107 gboolean
108 g_pollable_output_stream_is_writable (GPollableOutputStream *stream)
110 g_return_val_if_fail (G_IS_POLLABLE_OUTPUT_STREAM (stream), FALSE);
112 return G_POLLABLE_OUTPUT_STREAM_GET_INTERFACE (stream)->is_writable (stream);
116 * g_pollable_output_stream_create_source:
117 * @stream: a #GPollableOutputStream.
118 * @cancellable: (nullable): a #GCancellable, or %NULL
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.
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.
129 * Returns: (transfer full): a new #GSource
131 * Since: 2.28
133 GSource *
134 g_pollable_output_stream_create_source (GPollableOutputStream *stream,
135 GCancellable *cancellable)
137 g_return_val_if_fail (G_IS_POLLABLE_OUTPUT_STREAM (stream), NULL);
139 return G_POLLABLE_OUTPUT_STREAM_GET_INTERFACE (stream)->
140 create_source (stream, cancellable);
143 static gssize
144 g_pollable_output_stream_default_write_nonblocking (GPollableOutputStream *stream,
145 const void *buffer,
146 gsize count,
147 GError **error)
149 if (!g_pollable_output_stream_is_writable (stream))
151 g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_WOULD_BLOCK,
152 g_strerror (EAGAIN));
153 return -1;
156 return G_OUTPUT_STREAM_GET_CLASS (stream)->
157 write_fn (G_OUTPUT_STREAM (stream), buffer, count, NULL, error);
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.
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.
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.
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.
184 * Virtual: write_nonblocking
185 * Returns: the number of bytes written, or -1 on error (including
186 * %G_IO_ERROR_WOULD_BLOCK).
188 gssize
189 g_pollable_output_stream_write_nonblocking (GPollableOutputStream *stream,
190 const void *buffer,
191 gsize count,
192 GCancellable *cancellable,
193 GError **error)
195 gssize res;
197 g_return_val_if_fail (G_IS_POLLABLE_OUTPUT_STREAM (stream), -1);
198 g_return_val_if_fail (buffer != NULL, 0);
200 if (g_cancellable_set_error_if_cancelled (cancellable, error))
201 return -1;
203 if (count == 0)
204 return 0;
206 if (((gssize) count) < 0)
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;
213 if (cancellable)
214 g_cancellable_push_current (cancellable);
216 res = G_POLLABLE_OUTPUT_STREAM_GET_INTERFACE (stream)->
217 write_nonblocking (stream, buffer, count, error);
219 if (cancellable)
220 g_cancellable_pop_current (cancellable);
222 return res;