Document clearly async functions not copying its args

Usually async methods copy/ref its arguments so caller can
forget about them. g_file_replace_contents_async() and
g_output_stream_write_async() are exceptions.

https://bugzilla.gnome.org/show_bug.cgi?id=690525

diff --git a/gio/gfile.c b/gio/gfile.c
index 568ed35..5b9226c 100644 (file)
--- a/gio/gfile.c
+++ b/gio/gfile.c
@@ -7311,6 +7311,11 @@ replace_contents_open_callback (GObject      *obj,
  *
  * If @make_backup is %TRUE, this function will attempt to
  * make a backup of @file.
+ *
+ * <warning><para>No copy of @content will be made, so it must stay valid until
+ * @callback is called. See g_file_replace_contents_bytes_async() for a #GBytes
+ * version that will automatically hold a reference to the contents (without
+ * copying) for the duration of the call.</para></warning>
  */
 void
 g_file_replace_contents_async  (GFile               *file,

diff --git a/gio/goutputstream.c b/gio/goutputstream.c
index d54418f..c2e651e 100644 (file)
--- a/gio/goutputstream.c
+++ b/gio/goutputstream.c
@@ -787,6 +787,11 @@ async_ready_write_callback_wrapper (GObject      *source_object,
  *
  * For the synchronous, blocking version of this function, see 
  * g_output_stream_write().
+ *
+ * <warning><para>No copy of @buffer will be made, so it must stay valid until
+ * @callback is called. See g_output_stream_write_bytes_async() for a #GBytes
+ * version that will automatically hold a reference to the contents (without
+ * copying) for the duration of the call.</para></warning>
  **/
 void
 g_output_stream_write_async (GOutputStream       *stream,