From dd4c3695b4e4559179c2a10b7e1a6a13f8f8293e Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Wed, 2 Oct 2013 10:32:03 -0400 Subject: [PATCH] goutputstream: Add clear warning about short writes to _write_bytes() and async version Matthew Barnes noted this on IRC a few days ago. I just had this file open for other reasons and decided to tweak the docs to make this trap more clear. https://bugzilla.gnome.org/show_bug.cgi?id=709301 --- gio/goutputstream.c | 62 ++++++++++++++++++----------------------------------- 1 file changed, 21 insertions(+), 41 deletions(-) diff --git a/gio/goutputstream.c b/gio/goutputstream.c index 7e03df4..492a212 100644 --- a/gio/goutputstream.c +++ b/gio/goutputstream.c @@ -297,26 +297,18 @@ g_output_stream_write_all (GOutputStream *stream, * @cancellable: (allow-none): optional cancellable object * @error: location to store the error occurring, or %NULL to ignore * - * Tries to write the data from @bytes into the stream. Will block - * during the operation. - * - * If @bytes is 0-length, returns 0 and does nothing. A #GBytes larger - * than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. + * A wrapper function for g_output_stream_write() which takes a + * #GBytes as input. This can be more convenient for use by language + * bindings or in other cases where the refcounted nature of #GBytes + * is helpful over a bare pointer interface. * - * On success, the number of bytes written to the stream is returned. - * It is not an error if this is not the same as the requested size, as it - * can happen e.g. on a partial I/O error, or if there is not enough - * storage in the stream. All writes block until at least one byte - * is written or an error occurs; 0 is never returned (unless - * the size of @bytes is 0). - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. - * - * On error -1 is returned and @error is set accordingly. + * However, note that this function may still + * perform partial writes, just like g_output_stream_write(). If that + * occurs, to continue writing, you will need to create a new #GBytes + * containing just the remaining bytes, using + * g_bytes_new_from_bytes(). Passing the same #GBytes instance + * multiple times potentially can result in duplicated data in the + * output stream. * * Return value: Number of bytes written, or -1 on error **/ @@ -799,29 +791,17 @@ write_bytes_callback (GObject *stream, * @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 the data in @bytes to the stream. - * When the operation is finished @callback will be called. You can - * then call g_output_stream_write_bytes_finish() to get the result of - * the operation. - * - * During an async request no other sync and async calls are allowed, - * and will result in %G_IO_ERROR_PENDING errors. - * - * A #GBytes larger than %G_MAXSSIZE will cause a - * %G_IO_ERROR_INVALID_ARGUMENT error. - * - * On success, the number of bytes written will be passed to the - * @callback. It is not an error if this is not the same as the - * requested size, as it can happen e.g. on a partial I/O error, - * but generally we try to write as many bytes as requested. - * - * You are guaranteed that this method will never fail with - * %G_IO_ERROR_WOULD_BLOCK - if @stream can't accept more data, the - * method will just wait until this changes. + * This function is similar to g_output_stream_write_async(), but + * takes a #GBytes as input. Due to the refcounted nature of #GBytes, + * this allows the stream to avoid taking a copy of the data. * - * 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. + * However, note that this function may still + * perform partial writes, just like g_output_stream_write_async(). + * If that occurs, to continue writing, you will need to create a new + * #GBytes containing just the remaining bytes, using + * g_bytes_new_from_bytes(). Passing the same #GBytes instance + * multiple times potentially can result in duplicated data in the + * output stream. * * For the synchronous, blocking version of this function, see * g_output_stream_write_bytes(). -- 2.7.4