From 2e6faeec59055e4f852b6cda0f4243dcf581a684 Mon Sep 17 00:00:00 2001
From: Tim Janik <timj@imendio.com>
Date: Mon, 12 Dec 2005 14:32:27 +0000
Subject: [PATCH] corrected floating reference documentation.

Mon Dec 12 15:31:41 2005  Tim Janik  <timj@imendio.com>

        * gobject/tmpl/objects.sgml: corrected floating reference documentation.
---
 docs/reference/ChangeLog                 |  4 ++
 docs/reference/gobject/tmpl/objects.sgml | 70 ++++++++++++++++++------
 2 files changed, 58 insertions(+), 16 deletions(-)

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index cb5c6d7d..1318d7bb 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,7 @@
+Mon Dec 12 15:31:41 2005  Tim Janik  <timj@imendio.com>
+
+	* gobject/tmpl/objects.sgml: corrected floating reference documentation.
+
 2005-12-09  Matthias Clasen  <mclasen@redhat.com>
 
 	* === Released 2.9.1 ===
diff --git a/docs/reference/gobject/tmpl/objects.sgml b/docs/reference/gobject/tmpl/objects.sgml
index 8a22b591..38c4c4e7 100644
--- a/docs/reference/gobject/tmpl/objects.sgml
+++ b/docs/reference/gobject/tmpl/objects.sgml
@@ -13,17 +13,54 @@ property access methods, and signal support.
 Signals are described in detail in <xref linkend="gobject-Signals"/>.
 </para>
 <para id="floating-ref">
-The initial reference to a #GObject which is returned by g_object_new() can
-optionally be "floating", which means that it is not specifically owned
-by the creator of the object. The floating reference can be converted into 
-an ordinary reference by anyone at any time, by calling g_object_ref_sink(). 
-If the object is already sunk (has no floating reference), g_object_ref_sink() 
-returns a new reference.
-</para>
-<para>
-To create #GObject<!-- -->s with a floating reference, call 
-g_object_force_floating() from the object's init function.
-</para>
+The initial reference a #GObject is created with is flagged as a
+<firstterm>floating</firstterm> reference.
+This means that it is not specifically claimed to be "owned" by
+any code portion. The main motivation for providing floating references is
+C convenience. In particular, it allowes code to be written as:
+<example><programlisting>
+  container = create_container();
+  container_add_child (container, create_child());
+</programlisting></example>
+If <function>container_add_child()</function> will g_object_ref_sink() the
+passed in child, no reference of the newly created child is leaked.
+Without floating references, <function>container_add_child()</function>
+can only g_object_ref() the new child, so to implement this code without
+reference leaks, it would have to be written as:
+<example><programlisting>
+  Child *child;
+  container = create_container();
+  child = create_child();
+  container_add_child (container, child);
+  g_object_unref (child);
+</programlisting></example>
+The floating reference can be converted into 
+an ordinary reference by calling g_object_ref_sink().
+For already sunken objects (objects that don't have a floating reference
+anymore), g_object_ref_sink() is equivalent to g_object_ref() and returns
+a new reference.
+Since floating references are useful allmost exclusively for C convenience,
+language bindings that provide automated reference and memory ownership
+maintenance (such as smart pointers or garbage collection) therefore don't
+need to expose floating references in their API.
+</para>
+<para>
+Some object implementations may need to save an objects floating state
+across certain code portions (an example is #GtkMenu), to achive this, the
+following sequence can be used:
+</para>
+
+<example><programlisting>
+  /* save floating state */
+  gboolean was_floating = g_object_is_floating (object);
+  g_object_ref_sink (object);
+  /* protected code portion */
+  ...;
+  /* restore floating state */
+  if (was_floating)
+    g_object_force_floating (object);
+  g_obejct_unref (object); /* release previously acquired reference */
+</programlisting></example>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
@@ -419,7 +456,7 @@ When its reference count drops to 0, the object is finalized (i.e. its memory is
 
 <!-- ##### FUNCTION g_object_ref_sink ##### -->
 <para>
-Increase the reference count of @object, and remove the 
+Increase the reference count of @object, and possibly remove the 
 <link linkend="floating-ref">floating</link> reference, if @object
 has a floating reference.
 </para>
@@ -442,10 +479,11 @@ reference.
 
 <!-- ##### FUNCTION g_object_force_floating ##### -->
 <para>
-This function is intended for #GObject implementations to mark the
-initial reference to the object as 
-<link linkend="floating-ref">floating</link>. It must only be called  
-from an object's init function.
+This function is intended for #GObject implementations to re-enforce a
+<link linkend="floating-ref">floating</link> object reference.
+Doing this is seldomly required, all
+#GObject<!-- -->s are created with a floating reference which usually
+just needs to be sunken by calling g_object_ref_sink().
 </para>
 
 @object: a #GObject
-- 
2.34.1