Package: gobject

Class g-initially-unowned

Superclasses

g-object, common-lisp:standard-object, common-lisp:t

Documented Subclasses

Direct Slots

None

Details

g-initially-unowned is derived from g-object. The only difference between the two is that the initial reference of a g-initially-unowned is flagged as a floating 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 allows code to be written as:
 container = create_container ();
 container_add_child (container, create_child());  
If container_add_child() will g-object-ref-sink the passed in child, no reference of the newly created child is leaked. Without floating references, container_add_child() can only g-object-ref the new child, so to implement this code without reference leaks, it would have to be written as:
 Child *child;
 container = create_container ();
 child = create_child ();
 container_add_child (container, child);
 g_object_unref (child);  
The floating reference can be converted into an ordinary reference by calling the g-object-ref-sink function. For already sunken objects (objects that do not have a floating reference anymore), the g-object-ref-sink function is equivalent to the g-object-ref function and returns a new reference. Since floating references are useful almost exclusively for C convenience, language bindings that provide automated reference and memory ownership maintenance (such as smart pointers or garbage collection) should not expose floating references in their API.

Some object implementations may need to save an objects floating state across certain code portions (an example is gtk-menu), to achieve this, the following sequence can be used:
 /* 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_object_unref (object); /* release previously acquired reference */  
All the fields in the g-initially-unowned structure are private to the g-initially-unowned implementation and should never be accessed directly.
 

Inherited Slot Access Functions

2013-6-9