* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
- * version 2 of the License, or (at your option) any later version.
+ * version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* (g_output_stream_flush()).
*
* To copy the content of an input stream to an output stream without
- * manually handling the reads and writes, use g_output_stream_splice().
+ * manually handling the reads and writes, use g_output_stream_splice().
+ *
+ * See the documentation for #GIOStream for details of thread safety of
+ * streaming APIs.
*
* All of these functions have async variants too.
**/
* @stream: a #GOutputStream.
* @buffer: (array length=count) (element-type guint8): the buffer containing the data to write.
* @count: the number of bytes to write
- * @cancellable: (allow-none): optional cancellable object
+ * @cancellable: (nullable): optional cancellable object
* @error: location to store the error occurring, or %NULL to ignore
*
* Tries to write @count bytes from @buffer into the stream. Will block
*
* Virtual: write_fn
*
- * Return value: Number of bytes written, or -1 on error
+ * Returns: Number of bytes written, or -1 on error
**/
gssize
g_output_stream_write (GOutputStream *stream,
if (class->write_fn == NULL)
{
g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
- _("Output stream doesn't implement write"));
+ _("Output stream doesn’t implement write"));
return -1;
}
* @stream: a #GOutputStream.
* @buffer: (array length=count) (element-type guint8): the buffer containing the data to write.
* @count: the number of bytes to write
- * @bytes_written: (out): location to store the number of bytes that was
+ * @bytes_written: (out) (optional): location to store the number of bytes that was
* written to the stream
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
* @error: location to store the error occurring, or %NULL to ignore
*
* Tries to write @count bytes from @buffer into the stream. Will block
* is set to @count.
*
* If there is an error during the operation %FALSE is returned and @error
- * is set to indicate the error status, @bytes_written is updated to contain
- * the number of bytes written into the stream before the error occurred.
+ * is set to indicate the error status.
+ *
+ * As a special exception to the normal conventions for functions that
+ * use #GError, if this function returns %FALSE (and sets @error) then
+ * @bytes_written will be set to the number of bytes that were
+ * successfully written before the error was encountered. This
+ * functionality is only available from C. If you need it from another
+ * language then you must write your own loop around
+ * g_output_stream_write().
*
- * Return value: %TRUE on success, %FALSE if there was an error
+ * Returns: %TRUE on success, %FALSE if there was an error
**/
gboolean
g_output_stream_write_all (GOutputStream *stream,
/**
* g_output_stream_printf:
* @stream: a #GOutputStream.
- * @bytes_written: (out): location to store the number of bytes that was
+ * @bytes_written: (out) (optional): location to store the number of bytes that was
* written to the stream
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
* @error: location to store the error occurring, or %NULL to ignore
* @format: the format string. See the printf() documentation
* @...: the parameters to insert into the format string
*
* Since: 2.40
*
- * Return value: %TRUE on success, %FALSE if there was an error
+ * Returns: %TRUE on success, %FALSE if there was an error
**/
gboolean
g_output_stream_printf (GOutputStream *stream,
/**
* g_output_stream_vprintf:
* @stream: a #GOutputStream.
- * @bytes_written: (out): location to store the number of bytes that was
+ * @bytes_written: (out) (optional): location to store the number of bytes that was
* written to the stream
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
* @error: location to store the error occurring, or %NULL to ignore
* @format: the format string. See the printf() documentation
* @args: the parameters to insert into the format string
*
* Since: 2.40
*
- * Return value: %TRUE on success, %FALSE if there was an error
+ * Returns: %TRUE on success, %FALSE if there was an error
**/
gboolean
g_output_stream_vprintf (GOutputStream *stream,
* g_output_stream_write_bytes:
* @stream: a #GOutputStream.
* @bytes: the #GBytes to write
- * @cancellable: (allow-none): optional cancellable object
+ * @cancellable: (nullable): optional cancellable object
* @error: location to store the error occurring, or %NULL to ignore
*
* A wrapper function for g_output_stream_write() which takes a
* #GBytes instance multiple times potentially can result in duplicated
* data in the output stream.
*
- * Return value: Number of bytes written, or -1 on error
+ * Returns: Number of bytes written, or -1 on error
**/
gssize
g_output_stream_write_bytes (GOutputStream *stream,
/**
* g_output_stream_flush:
* @stream: a #GOutputStream.
- * @cancellable: (allow-none): optional cancellable object
+ * @cancellable: (nullable): optional cancellable object
* @error: location to store the error occurring, or %NULL to ignore
*
* Forces a write of all user-space buffered data for the given
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
- * Return value: %TRUE on success, %FALSE on error
+ * Returns: %TRUE on success, %FALSE on error
**/
gboolean
g_output_stream_flush (GOutputStream *stream,
* @stream: a #GOutputStream.
* @source: a #GInputStream.
* @flags: a set of #GOutputStreamSpliceFlags.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
* @error: a #GError location to store the error occurring, or %NULL to
* ignore.
*
if (class->write_fn == NULL)
{
g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
- _("Output stream doesn't implement write"));
+ _("Output stream doesn’t implement write"));
res = FALSE;
goto notsupported;
}
if (flags & G_OUTPUT_STREAM_SPLICE_CLOSE_TARGET)
{
/* But write errors on close are bad! */
- res = g_output_stream_internal_close (stream, cancellable, error);
+ if (!g_output_stream_internal_close (stream, cancellable, error))
+ res = FALSE;
}
if (res)
/**
* g_output_stream_close:
* @stream: A #GOutputStream.
- * @cancellable: (allow-none): optional cancellable object
+ * @cancellable: (nullable): optional cancellable object
* @error: location to store the error occurring, or %NULL to ignore
*
* Closes the stream, releasing resources related to it.
* cancellation (as with any error) there is no guarantee that all written
* data will reach the target.
*
- * Return value: %TRUE on success, %FALSE on failure
+ * Returns: %TRUE on success, %FALSE on failure
**/
gboolean
g_output_stream_close (GOutputStream *stream,
* @buffer: (array length=count) (element-type guint8): the buffer containing the data to write.
* @count: the number of bytes to write
* @io_priority: the io priority of the request.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
* @callback: (scope async): callback to call when the request is satisfied
* @user_data: (closure): the data to pass to callback function
*
* value) will be executed before an outstanding request with lower
* priority. Default priority is %G_PRIORITY_DEFAULT.
*
- * The asyncronous methods have a default fallback that uses threads
+ * The asynchronous methods have a default fallback that uses threads
* to implement asynchronicity, so they are optional for inheriting
* classes. However, if you override one you must override all.
*
return g_task_propagate_int (G_TASK (result), error);
}
+typedef struct
+{
+ const guint8 *buffer;
+ gsize to_write;
+ gsize bytes_written;
+} AsyncWriteAll;
+
+static void
+free_async_write_all (gpointer data)
+{
+ g_slice_free (AsyncWriteAll, data);
+}
+
+static void
+write_all_callback (GObject *stream,
+ GAsyncResult *result,
+ gpointer user_data)
+{
+ GTask *task = user_data;
+ AsyncWriteAll *data = g_task_get_task_data (task);
+
+ if (result)
+ {
+ GError *error = NULL;
+ gssize nwritten;
+
+ nwritten = g_output_stream_write_finish (G_OUTPUT_STREAM (stream), result, &error);
+
+ if (nwritten == -1)
+ {
+ g_task_return_error (task, error);
+ g_object_unref (task);
+ return;
+ }
+
+ g_assert_cmpint (nwritten, <=, data->to_write);
+ g_warn_if_fail (nwritten > 0);
+
+ data->to_write -= nwritten;
+ data->bytes_written += nwritten;
+ }
+
+ if (data->to_write == 0)
+ {
+ g_task_return_boolean (task, TRUE);
+ g_object_unref (task);
+ }
+
+ else
+ g_output_stream_write_async (G_OUTPUT_STREAM (stream),
+ data->buffer + data->bytes_written,
+ data->to_write,
+ g_task_get_priority (task),
+ g_task_get_cancellable (task),
+ write_all_callback, task);
+}
+
+static void
+write_all_async_thread (GTask *task,
+ gpointer source_object,
+ gpointer task_data,
+ GCancellable *cancellable)
+{
+ GOutputStream *stream = source_object;
+ AsyncWriteAll *data = task_data;
+ GError *error = NULL;
+
+ if (g_output_stream_write_all (stream, data->buffer, data->to_write, &data->bytes_written,
+ g_task_get_cancellable (task), &error))
+ g_task_return_boolean (task, TRUE);
+ else
+ g_task_return_error (task, error);
+}
+
+/**
+ * g_output_stream_write_all_async:
+ * @stream: A #GOutputStream
+ * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write
+ * @count: the number of bytes to write
+ * @io_priority: the io priority of the request
+ * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore
+ * @callback: (scope async): callback to call when the request is satisfied
+ * @user_data: (closure): the data to pass to callback function
+ *
+ * Request an asynchronous write of @count bytes from @buffer into
+ * the stream. When the operation is finished @callback will be called.
+ * You can then call g_output_stream_write_all_finish() to get the result of the
+ * operation.
+ *
+ * This is the asynchronous version of g_output_stream_write_all().
+ *
+ * Call g_output_stream_write_all_finish() to collect the result.
+ *
+ * Any outstanding I/O request with higher priority (lower numerical
+ * value) will be executed before an outstanding request with lower
+ * priority. Default priority is %G_PRIORITY_DEFAULT.
+ *
+ * Note that no copy of @buffer will be made, so it must stay valid
+ * until @callback is called.
+ *
+ * Since: 2.44
+ */
+void
+g_output_stream_write_all_async (GOutputStream *stream,
+ const void *buffer,
+ gsize count,
+ int io_priority,
+ GCancellable *cancellable,
+ GAsyncReadyCallback callback,
+ gpointer user_data)
+{
+ AsyncWriteAll *data;
+ GTask *task;
+
+ g_return_if_fail (G_IS_OUTPUT_STREAM (stream));
+ g_return_if_fail (buffer != NULL || count == 0);
+
+ task = g_task_new (stream, cancellable, callback, user_data);
+ data = g_slice_new0 (AsyncWriteAll);
+ data->buffer = buffer;
+ data->to_write = count;
+
+ g_task_set_source_tag (task, g_output_stream_write_all_async);
+ g_task_set_task_data (task, data, free_async_write_all);
+ g_task_set_priority (task, io_priority);
+
+ /* If async writes are going to be handled via the threadpool anyway
+ * then we may as well do it with a single dispatch instead of
+ * bouncing in and out.
+ */
+ if (g_output_stream_async_write_is_via_threads (stream))
+ {
+ g_task_run_in_thread (task, write_all_async_thread);
+ g_object_unref (task);
+ }
+ else
+ write_all_callback (G_OBJECT (stream), NULL, task);
+}
+
+/**
+ * g_output_stream_write_all_finish:
+ * @stream: a #GOutputStream
+ * @result: a #GAsyncResult
+ * @bytes_written: (out) (optional): location to store the number of bytes that was written to the stream
+ * @error: a #GError location to store the error occurring, or %NULL to ignore.
+ *
+ * Finishes an asynchronous stream write operation started with
+ * g_output_stream_write_all_async().
+ *
+ * As a special exception to the normal conventions for functions that
+ * use #GError, if this function returns %FALSE (and sets @error) then
+ * @bytes_written will be set to the number of bytes that were
+ * successfully written before the error was encountered. This
+ * functionality is only available from C. If you need it from another
+ * language then you must write your own loop around
+ * g_output_stream_write_async().
+ *
+ * Returns: %TRUE on success, %FALSE if there was an error
+ *
+ * Since: 2.44
+ **/
+gboolean
+g_output_stream_write_all_finish (GOutputStream *stream,
+ GAsyncResult *result,
+ gsize *bytes_written,
+ GError **error)
+{
+ GTask *task;
+
+ g_return_val_if_fail (G_IS_OUTPUT_STREAM (stream), FALSE);
+ g_return_val_if_fail (g_task_is_valid (result, stream), FALSE);
+
+ task = G_TASK (result);
+
+ if (bytes_written)
+ {
+ AsyncWriteAll *data = (AsyncWriteAll *)g_task_get_task_data (task);
+
+ *bytes_written = data->bytes_written;
+ }
+
+ return g_task_propagate_boolean (task, error);
+}
+
static void
write_bytes_callback (GObject *stream,
GAsyncResult *result,
* @stream: A #GOutputStream.
* @bytes: The bytes to write
* @io_priority: the io priority of the request.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
* @callback: (scope async): callback to call when the request is satisfied
* @user_data: (closure): the data to pass to callback function
*
data = g_bytes_get_data (bytes, &size);
task = g_task_new (stream, cancellable, callback, user_data);
+ g_task_set_source_tag (task, g_output_stream_write_bytes_async);
g_task_set_task_data (task, g_bytes_ref (bytes),
(GDestroyNotify) g_bytes_unref);
* @source: a #GInputStream.
* @flags: a set of #GOutputStreamSpliceFlags.
* @io_priority: the io priority of the request.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
* @callback: (scope async): a #GAsyncReadyCallback.
* @user_data: (closure): user data passed to @callback.
*
* g_output_stream_flush_async:
* @stream: a #GOutputStream.
* @io_priority: the io priority of the request.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
* @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
* @user_data: (closure): the data to pass to callback function
*
* g_output_stream_close_async:
* @stream: A #GOutputStream.
* @io_priority: the io priority of the request.
- * @cancellable: (allow-none): optional cancellable object
+ * @cancellable: (nullable): optional cancellable object
* @callback: (scope async): callback to call when the request is satisfied
* @user_data: (closure): the data to pass to callback function
*
*
* For behaviour details see g_output_stream_close().
*
- * The asyncronous methods have a default fallback that uses threads
+ * The asynchronous methods have a default fallback that uses threads
* to implement asynchronicity, so they are optional for inheriting
* classes. However, if you override one you must override all.
**/
* g_output_stream_has_pending:
* @stream: a #GOutputStream.
*
- * Checks if an ouput stream has pending actions.
+ * Checks if an output stream has pending actions.
*
* Returns: %TRUE if @stream has pending actions.
**/
* already set or @stream is closed, it will return %FALSE and set
* @error.
*
- * Return value: %TRUE if pending was previously unset and is now set.
+ * Returns: %TRUE if pending was previously unset and is now set.
**/
gboolean
g_output_stream_set_pending (GOutputStream *stream,
stream->priv->pending = FALSE;
}
-/**
+/*< internal >
* g_output_stream_async_write_is_via_threads:
* @stream: a #GOutputStream.
*
- * Checks if an ouput stream's write_async function uses threads.
+ * Checks if an output stream's write_async function uses threads.
*
* Returns: %TRUE if @stream's write_async function uses threads.
**/
g_pollable_output_stream_can_poll (G_POLLABLE_OUTPUT_STREAM (stream))));
}
+/*< internal >
+ * g_output_stream_async_close_is_via_threads:
+ * @stream: output stream
+ *
+ * Checks if an output stream's close_async function uses threads.
+ *
+ * Returns: %TRUE if @stream's close_async function uses threads.
+ **/
+gboolean
+g_output_stream_async_close_is_via_threads (GOutputStream *stream)
+{
+ GOutputStreamClass *class;
+
+ g_return_val_if_fail (G_IS_OUTPUT_STREAM (stream), FALSE);
+
+ class = G_OUTPUT_STREAM_GET_CLASS (stream);
+
+ return class->close_async == g_output_stream_real_close_async;
+}
/********************************************
* Default implementation of async ops *
projects / platform / upstream / glib.git / blobdiff