Add g_object_add/remove_toggle_ref() functions to get notification when a

2005-05-05  Owen Taylor  <otaylor@redhat.com>

        * gobject.[ch] gobject.symbols: Add
        g_object_add/remove_toggle_ref() functions to get notification
        when a reference count is the last remaining reference; this
        enables better memory management for language bindings.
        (http://mail.gnome.org/archives/gtk-devel-list/2005-April/msg00095.html)

2005-05-05  Owen Taylor  <otaylor@redhat.com>

        * glib/gdataset.[ch] glib/gdatasetprivate.h: Add
        g_datalist_set/unset_flags(), g_datalist_get_flags() functions
        to squeeze some bits into a GDataSet... this is needed for
        efficient implementation of toggle references in GObject.

        * tests/gobject/references.c tests/gobject/Makefile.am:
        Add a test case for weak and toggle references.

        * glib/gfileutils.[ch]: Rename g_file_replace() back
        to g_file_set_contents().

        * glib/glib.symbols: Update.

2005-05-05  Owen Taylor  <otaylor@redhat.com>

        * glib/Makefile.am glib/glib-sections.txt gobject/gobject-sections.txt:
        Update

        * gobject/tmpl/objects.sgml: Document toggle-references.

docs/reference/gobject/gobject-sections.txt

@@ -242,6 +242,9 @@ g_object_weak_ref
 g_object_weak_unref
 g_object_add_weak_pointer
 g_object_remove_weak_pointer
+GToggleNotify
+g_object_add_toggle_ref
+g_object_remove_toggle_ref
 g_object_connect
 g_object_disconnect
 g_object_set

docs/reference/gobject/tmpl/gboxed.sgml

@@ -14,6 +14,9 @@ A mechanism to wrap opaque C structures registered by the type system
 #GParamSpecBoxed, g_param_spec_boxed()
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### USER_FUNCTION GBoxedCopyFunc ##### -->
 <para>
 This function is provided by the user and should produce a copy of the passed

docs/reference/gobject/tmpl/gclosure.sgml

@@ -60,6 +60,9 @@ automatically removed when the objects they point to go away.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### MACRO G_CLOSURE_NEEDS_MARSHAL ##### -->
 <para>
 Returns %TRUE if a #GClosureMarshal marshaller has not yet been set on 

docs/reference/gobject/tmpl/gparamspec.sgml

@@ -21,6 +21,9 @@ g_object_class_install_property(), g_object_set(), g_object_get(),
 g_object_set_property(), g_object_get_property(), g_value_register_transform_func()
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### MACRO G_TYPE_IS_PARAM ##### -->
 <para>
 Returns whether @type "is a" %G_TYPE_PARAM.

docs/reference/gobject/tmpl/gtypeplugin.sgml

@@ -70,6 +70,9 @@ handles multiple registered types per module.
 #GTypeModule and g_type_register_dynamic().
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GTypePlugin ##### -->
 <para>
 The <structname>GTypePlugin</structname> typedef is used as a placeholder 

docs/reference/gobject/tmpl/objects.sgml

@@ -14,6 +14,9 @@ The base object type
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GObject ##### -->
 <para>
 All the fields in the <structname>GObject</structname> structure are private 
@@ -432,6 +435,76 @@ to match the one used with g_object_add_weak_pointer().
 @weak_pointer_location: The memory address of a pointer.
 
 
+<!-- ##### USER_FUNCTION GToggleNotify ##### -->
+<para>
+A callback function used for notification when the state
+of a toggle reference changes. See g_object_add_toggle_ref().
+</para>
+
+@data: Callback data passed to g_object_add_toggle_ref()
+@object: The object on which g_object_add_toggle_ref() was called.
+@is_last_ref: %TRUE if the toggle reference is now the
+  last reference to the object. %FALSE if the toggle
+  reference was the last reference and there are now other
+  references.
+
+
+<!-- ##### FUNCTION g_object_add_toggle_ref ##### -->
+<para>
+Increases the reference count of the object by one and sets a
+callback to be called when all other references to the object are
+dropped, or when this is already the last reference to the object
+and another reference is established.
+</para>
+<para>
+This functionality is intended for binding @object to a proxy
+object managed by another memory manager. This is done with two
+paired references: the strong reference added by
+g_object_add_toggle_ref() and a reverse reference to the proxy
+object which is either a strong reference or weak reference.
+</para>
+<para>
+The setup is that when there are no other references to @object,
+only a weak reference is held in the reverse direction from @object
+to the proxy object, but when there are other references held to
+@object, a strong reference is held. The @notify callback is called
+when the reference from @object to the proxy object should be
+<firstterm>toggled</firstterm> from strong to weak (@is_last_ref
+true) or weak to strong (@is_last_ref false).
+</para>
+<para>
+Since a (normal) reference must be held to the object before
+calling g_object_toggle_ref(), the initial state of the reverse
+link is always strong.
+</para>
+<para>
+Multiple toggle references may be added to the same gobject,
+however if there are multiple toggle references to an object, none
+of them will ever be notified until all but one are removed.  For
+this reason, you should only ever use a toggle reference if there
+is important state in the proxy object.
+</para>
+
+@object: a #GObject
+@notify: a function to call when this reference is the
+  last reference to the object, or is no longer
+  the last reference.
+@data: data to pass to @notify
+
+
+<!-- ##### FUNCTION g_object_remove_toggle_ref ##### -->
+<para>
+Removes a reference added with g_object_add_toggle_ref(). The
+reference count of the object is decreased by one.
+</para>
+
+@object: a #GObject
+@notify: a function to call when this reference is the
+  last reference to the object, or is no longer
+  the last reference.
+@data: data to pass to @notify
+
+
 <!-- ##### FUNCTION g_object_connect ##### -->
 <para>
 A convenience function to connect multiple signals at once.

docs/reference/gobject/tmpl/param_value_types.sgml

@@ -833,7 +833,6 @@ A #GParamSpec derived structure that contains the meta data for double propertie
 @default_value:   default value for the property specified
 @epsilon:         values closer than @epsilon will be considered identical
                   by g_param_values_cmp(); the default value is 1e-90.
-                  
 
 <!-- ##### FUNCTION g_param_spec_double ##### -->
 <para>

docs/reference/gobject/tmpl/value_collection.sgml

@@ -14,6 +14,9 @@ Converting varargs to generic values
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### UNION GTypeCValue ##### -->
 <para>
 A union holding one collected value.