[glib] Bug 627071 – g_output_stream_write() clarification

[David Zeuthen <davidz src gnome org>]

commit b8e7ef6e90512999be0340a6ef3f20e1783647c4
Author: David Zeuthen <davidz redhat com>
Date:   Mon Aug 16 15:37:01 2010 -0400

    Bug 627071 â?? g_output_stream_write() clarification
    
    This patch guarantees that g_output_stream_write() can never fail with
    G_IO_ERROR_WOULD_BLOCK. Without such a guarantee, we would need some
    kind of GIOPollable interface or some way to get an event when the
    stream is writable again. Which is mostly useless considering that
    this method is asynchronous anyway.
    
    Note: this patch just codifies existing behavior - GUnixOutputStream,
    GSocketOutputStream and other implementations already work this way.
    
    See also bug 626748 comment 5 for how the GDBus code relies on this
    guarantee.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=627071
    
    Signed-off-by: David Zeuthen <davidz redhat com>

 gio/goutputstream.c |    4 ++++
 1 files changed, 4 insertions(+), 0 deletions(-)
---
diff --git a/gio/goutputstream.c b/gio/goutputstream.c
index 1115599..60e8111 100644
--- a/gio/goutputstream.c
+++ b/gio/goutputstream.c
@@ -673,6 +673,10 @@ async_ready_close_flushed_callback_wrapper (GObject      *source_object,
  * 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.
+ *
  * 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.