luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-11-10 11:26:16 +01:00
Code Issues Packages Projects Releases Wiki Activity

corrected floating reference documentation.

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

        * gobject/tmpl/objects.sgml: corrected floating reference documentation.
This commit is contained in:
Tim Janik 2005-12-12 14:32:27 +00:00 committed by Tim Janik
parent 0d19d25fe4
commit 2e6faeec59
2 changed files with 55 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/reference/ChangeLog
View File

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

64
docs/reference/gobject/tmpl/objects.sgml
View File

@ -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
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.
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>
To create #GObject<!-- -->s with a floating reference, call
g_object_force_floating() from the object's init function.
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>
#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
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