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

@@ -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 ===

docs/reference/gobject/tmpl/objects.sgml

@@ -13,18 +13,55 @@ 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
+The initial reference a #GObject is created with is flagged as a
-optionally be "floating", which means that it is not specifically owned
+<firstterm>floating</firstterm> reference.
-by the creator of the object. The floating reference can be converted into 
+This means that it is not specifically claimed to be "owned" by
-an ordinary reference by anyone at any time, by calling g_object_ref_sink(). 
+any code portion. The main motivation for providing floating references is
-If the object is already sunk (has no floating reference), g_object_ref_sink() 
+C convenience. In particular, it allowes code to be written as:
-returns a new reference.
+<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>
-To create #GObject<!-- -->s with a floating reference, call 
+Some object implementations may need to save an objects floating state
-g_object_force_floating() from the object's init function.
+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>
 #GParamSpecObject, g_param_spec_object()
@@ -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
+This function is intended for #GObject implementations to re-enforce a
-initial reference to the object as 
+<link linkend="floating-ref">floating</link> object reference.
-<link linkend="floating-ref">floating</link>. It must only be called  
+Doing this is seldomly required, all
-from an object's init function.
+#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