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/ChangeLog

@@ -1,3 +1,10 @@
+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.
+
 2005-05-02  Matthias Clasen  <mclasen@redhat.com>
 
 	* glib/tmpl/hash_tables.sgml: Move some docs inline.

docs/reference/glib/Makefile.am

@@ -22,6 +22,7 @@ IGNORE_HFILES=			\
 	build			\
 	gobject 		\
 	config.h 		\
+	gdatasetprivate.h	\
 	glibintl.h		\
 	gbsearcharray.h		\
 	gmoduleconf.h		\

docs/reference/glib/glib-sections.txt

@@ -980,7 +980,7 @@ G_FILE_ERROR
 GFileTest
 g_file_error_from_errno
 g_file_get_contents
-g_file_replace
+g_file_set_contents
 g_file_test
 g_mkstemp
 g_file_open_tmp
@@ -1345,6 +1345,7 @@ g_nullify_pointer
 <SUBSECTION Private>
 G_NATIVE_ATEXIT
 g_ATEXIT
+g_win32_get_system_data_dirs_for_module
 ATEXIT
 
 </SECTION>
@@ -1970,6 +1971,10 @@ g_datalist_remove_no_notify
 <SUBSECTION>
 g_datalist_foreach
 g_datalist_clear
+g_datalist_set_flags
+g_datalist_unset_flags
+g_datalist_get_flags
+G_DATALIST_FLAGS_MASK
 </SECTION>
 
 

docs/reference/glib/tmpl/allocators.sgml

@@ -34,6 +34,9 @@ elements. Each must use separate allocators.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GAllocator ##### -->
 <para>
 The <structname>GAllocator</structname> struct contains private data. and should only be accessed

docs/reference/glib/tmpl/arrays.sgml

@@ -55,6 +55,9 @@ To free an array, use g_array_free().
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GArray ##### -->
 <para>
 Contains the public fields of an <link linkend="glib-arrays">Array</link>.

docs/reference/glib/tmpl/arrays_pointer.sgml

@@ -60,6 +60,9 @@ To free a pointer array, use g_ptr_array_free().
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GPtrArray ##### -->
 <para>
 Contains the public fields of a pointer array.

docs/reference/glib/tmpl/async_queues.sgml

@@ -63,6 +63,9 @@ locking function variants (those without the suffix _unlocked)
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GAsyncQueue ##### -->
 <para>
 The #GAsyncQueue struct is an opaque data structure, which represents

docs/reference/glib/tmpl/atomic_operations.sgml

@@ -60,6 +60,9 @@ g_atomic_pointer_compare_and_exchange() respectively.
 </variablelist>
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### FUNCTION g_atomic_int_get ##### -->
 <para>
 Reads the value of the integer pointed to by @atomic. Also acts as

docs/reference/glib/tmpl/byte_order.sgml

@@ -44,6 +44,9 @@ as the standard byte order (which is in fact the big-endian byte order).
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### MACRO G_BYTE_ORDER ##### -->
 <para>
 The host byte order.

docs/reference/glib/tmpl/caches.sgml

@@ -26,6 +26,9 @@ A #GCache value is the actual resource.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GCache ##### -->
 <para>
 The #GCache struct is an opaque data structure containing information about

docs/reference/glib/tmpl/conversions.sgml

@@ -161,6 +161,9 @@ export G_FILENAME_ENCODING=ISO-8859-1
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### FUNCTION g_convert ##### -->
 <para>
 

docs/reference/glib/tmpl/datalist.sgml

@@ -47,6 +47,9 @@ To remove all data elements from a datalist, use g_datalist_clear().
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GData ##### -->
 <para>
 The #GData struct is an opaque data structure to represent a
@@ -202,3 +205,37 @@ The data elements' destroy functions are called if they have been set.
 @datalist: a datalist.
 
 
+<!-- ##### FUNCTION g_datalist_set_flags ##### -->
+<para>
+
+</para>
+
+@datalist: 
+@flags: 
+
+
+<!-- ##### FUNCTION g_datalist_unset_flags ##### -->
+<para>
+
+</para>
+
+@datalist: 
+@flags: 
+
+
+<!-- ##### FUNCTION g_datalist_get_flags ##### -->
+<para>
+
+</para>
+
+@datalist: 
+@Returns: 
+
+
+<!-- ##### MACRO G_DATALIST_FLAGS_MASK ##### -->
+<para>
+
+</para>
+
+
+

docs/reference/glib/tmpl/datasets.sgml

@@ -49,6 +49,9 @@ To destroy a dataset, use g_dataset_destroy().
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### MACRO g_dataset_id_set_data ##### -->
 <para>
 Sets the data element associated with the given #GQuark id.

docs/reference/glib/tmpl/date.sgml

@@ -63,6 +63,9 @@ can request the current time as a #GTimeVal with g_get_current_time().
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### MACRO G_USEC_PER_SEC ##### -->
 <para>
 Number of microseconds in one second (1 million). This macro is provided for

docs/reference/glib/tmpl/error_reporting.sgml

@@ -370,6 +370,9 @@ Summary of rules for use of #GError:
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GError ##### -->
 <para>
 The <structname>GError</structname> structure contains 

docs/reference/glib/tmpl/fileutils.sgml

@@ -38,6 +38,9 @@ g_dir_read_name(), g_dir_rewind(), g_dir_close().
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### ENUM GFileError ##### -->
 <para>
 Values corresponding to <literal>errno</literal> codes returned from file operations
@@ -165,6 +168,18 @@ A test to perform on a file using g_file_test().
 @Returns: 
 
 
+<!-- ##### FUNCTION g_file_set_contents ##### -->
+<para>
+
+</para>
+
+@filename: 
+@contents: 
+@length: 
+@error: 
+@Returns: 
+
+
 <!-- ##### FUNCTION g_file_test ##### -->
 <para>
 
@@ -346,3 +361,33 @@ An opaque structure representing an opened directory.
 @Returns: 
 
 
+<!-- ##### FUNCTION g_chmod ##### -->
+<para>
+
+</para>
+
+@filename: 
+@mode: 
+@Returns: 
+
+
+<!-- ##### FUNCTION g_access ##### -->
+<para>
+
+</para>
+
+@filename: 
+@mode: 
+@Returns: 
+
+
+<!-- ##### FUNCTION g_creat ##### -->
+<para>
+
+</para>
+
+@filename: 
+@mode: 
+@Returns: 
+
+

docs/reference/glib/tmpl/glib-unused.sgml

@@ -44,6 +44,10 @@ serializes and deserializes a desktop entry.
 Desktop Entry Parser
 
 
+<!-- ##### SECTION ./tmpl/glib-unused.sgml:Stability_Level ##### -->
+
+
+
 <!-- ##### ENUM GChannelError ##### -->
 <para>
 
@@ -629,6 +633,17 @@ in any UNIX manual.
 @error: 
 @Returns: 
 
+<!-- ##### FUNCTION g_file_replace ##### -->
+<para>
+
+</para>
+
+@filename: 
+@contents: 
+@length: 
+@error: 
+@Returns: 
+
 <!-- ##### FUNCTION g_io_channel_error_quark ##### -->
 <para>
 

docs/reference/glib/tmpl/hash_tables.sgml

@@ -331,14 +331,14 @@ This function is deprecated and will be removed in the next major
 
 @v1: 
 @v2: 
-@Returns:
+@Returns: 
 
 
 <!-- ##### FUNCTION g_str_hash ##### -->
 <para>
 </para>
 
-@v:
-@Returns:
+@v: 
+@Returns: 
 
 

docs/reference/glib/tmpl/hooks.sgml

@@ -17,6 +17,9 @@ and the list of hook functions can be invoked.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GHookList ##### -->
 <para>
 The <structname>GHookList</structname> struct represents a 

docs/reference/glib/tmpl/i18n.sgml

@@ -27,6 +27,9 @@ the GETTEXT_PACKAGE macro suitably for your library:
 The gettext manual.
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### MACRO _ ##### -->
 <para>
 Marks a string for translation, gets replaced with the translated string

docs/reference/glib/tmpl/iochannels.sgml

@@ -64,6 +64,9 @@ Convenience functions for creating #GIOChannel instances and adding them to the
 </variablelist>
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GIOChannel ##### -->
 <para>
 A data structure representing an IO Channel. The fields should be considered

docs/reference/glib/tmpl/keyfile.sgml

@@ -97,6 +97,9 @@ Key and Group names are case-sensitive, for example a group called
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GKeyFile ##### -->
 <para>
 The <structname>GKeyFile</structname> struct contains only private fields

docs/reference/glib/tmpl/limits.sgml

@@ -15,6 +15,9 @@ the standard integer and floating point types.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### MACRO G_MININT ##### -->
 <para>
 The minimum value which can be held in a #gint.

docs/reference/glib/tmpl/linked_lists_double.sgml

@@ -64,6 +64,9 @@ To free the entire list, use g_list_free().
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GList ##### -->
 <para>
 The #GList struct is used for each element in a doubly-linked list.

docs/reference/glib/tmpl/linked_lists_single.sgml

@@ -64,6 +64,9 @@ To free the entire list, use g_slist_free().
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GSList ##### -->
 <para>
 The #GSList struct is used for each element in the singly-linked list.
@@ -74,7 +77,6 @@ The #GSList struct is used for each element in the singly-linked list.
   <link linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>.
 @next: contains the link to the next element in the list.
 
-
 <!-- ##### FUNCTION g_slist_alloc ##### -->
 <para>
 Allocates space for one #GSList element.

docs/reference/glib/tmpl/macros.sgml

@@ -14,6 +14,9 @@ These macros provide a few commonly-used features.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### MACRO G_OS_WIN32 ##### -->
 <para>
 This macro is defined only on Windows. So you can bracket

docs/reference/glib/tmpl/macros_misc.sgml

@@ -15,6 +15,9 @@ by application programmers.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### MACRO G_INLINE_FUNC ##### -->
 <para>
 Used to declare inline functions. If inline functions are not supported on
@@ -238,6 +241,8 @@ See the GNU C documentation for details.
 
 Since: 2.8
 
+
+
 <!-- ##### MACRO G_GNUC_FUNCTION ##### -->
 <para>
 Expands to the GNU C <literal>__FUNCTION__</literal> variable if the 

docs/reference/glib/tmpl/main.sgml

@@ -101,6 +101,9 @@ manages all available sources of events.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GMainLoop ##### -->
 <para>
 The <structname>GMainLoop</structname> struct is an opaque data type 

docs/reference/glib/tmpl/markup.sgml

@@ -85,6 +85,9 @@ Sections marked as CDATA
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### ENUM GMarkupError ##### -->
 <para>
 Error codes returned by markup parsing.

docs/reference/glib/tmpl/memory.sgml

@@ -20,6 +20,9 @@ This also means that there is no need to check if the call succeeded.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### MACRO g_new ##### -->
 <para>
 Allocates @n_structs elements of type @struct_type.
@@ -228,18 +231,12 @@ Wraps g_alloca() in a more typesafe manner.
 
 <!-- ##### MACRO g_memmove ##### -->
 <para>
-Copies a block of memory @n bytes long, from @s to @d.
-The source and destination areas may overlap.
-</para>
-<para>
-In order to use this function, you must include <filename>string.h</filename>
-yourself, because this macro will typically simply resolve
-to <function>memmove()</function> and GLib does not include <filename>string.h</filename> for you.
+
 </para>
 
-@d: the destination address to copy the bytes to.
-@s: the source address to copy the bytes from.
-@n: the number of bytes to copy.
+@dest: 
+@src: 
+@len: 
 
 
 <!-- ##### FUNCTION g_memdup ##### -->

docs/reference/glib/tmpl/memory_chunks.sgml

@@ -122,6 +122,9 @@ To help debug memory chunks, use g_mem_chunk_info() and g_mem_chunk_print().
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GMemChunk ##### -->
 <para>
 The #GMemChunk struct is an opaque data structure representing a memory

docs/reference/glib/tmpl/messages.sgml

@@ -20,6 +20,9 @@ These can be extended with user-defined levels.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### MACRO G_LOG_DOMAIN ##### -->
 <para>
 Defines the log domain.

docs/reference/glib/tmpl/misc_utils.sgml

@@ -14,6 +14,9 @@ These are portable utility functions.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### FUNCTION g_get_application_name ##### -->
 <para>
 
@@ -74,12 +77,20 @@ These are portable utility functions.
 @variable: 
 
 
+<!-- ##### FUNCTION g_listenv ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+
 <!-- ##### FUNCTION g_get_user_name ##### -->
 <para>
 
 </para>
 
-@Returns:
+@Returns: 
 
 
 <!-- ##### FUNCTION g_get_real_name ##### -->
@@ -87,7 +98,7 @@ These are portable utility functions.
 
 </para>
 
-@Returns:
+@Returns: 
 
 
 <!-- ##### FUNCTION g_get_user_cache_dir ##### -->
@@ -151,7 +162,7 @@ These are portable utility functions.
 
 </para>
 
-@Returns:
+@Returns: 
 
 
 <!-- ##### FUNCTION g_basename ##### -->
@@ -181,8 +192,8 @@ The returned string should be freed when no longer needed.
 
 </para>
 
-@file_name:
-@Returns:
+@file_name: 
+@Returns: 
 
 
 <!-- ##### FUNCTION g_path_skip_root ##### -->
@@ -309,8 +320,8 @@ larger than @num.
 
 @string: 
 @keys: 
-@nkeys:
-@Returns:
+@nkeys: 
+@Returns: 
 
 
 <!-- ##### STRUCT GDebugKey ##### -->

docs/reference/glib/tmpl/modules.sgml

@@ -88,6 +88,9 @@ just_say_hello (const char *filename, GError **error)
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GModule ##### -->
 <para>
 The #GModule struct is an opaque data structure to represent a

docs/reference/glib/tmpl/numerical.sgml

@@ -24,6 +24,9 @@ The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the
 <ulink url="http://cch.loria.fr/documentation/IEEE754/numerical_comp_guide/ncg_math.doc.html">http://cch.loria.fr/documentation/IEEE754/numerical_comp_guide/ncg_math.doc.html</ulink>
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### MACRO G_IEEE754_FLOAT_BIAS ##### -->
 <para>
 See <ulink url="http://cch.loria.fr/documentation/IEEE754/numerical_comp_guide/ncg_math.doc.html">http://cch.loria.fr/documentation/IEEE754/numerical_comp_guide/ncg_math.doc.html</ulink>

docs/reference/glib/tmpl/option.sgml

@@ -124,6 +124,9 @@ main (int argc, char *argv[])
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### ENUM GOptionError ##### -->
 <para>
 Error codes returned by option parsing.

docs/reference/glib/tmpl/patterns.sgml

@@ -30,6 +30,9 @@ pattern compilation.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GPatternSpec ##### -->
 <para>
 A <structname>GPatternSpec</structname> is the 'compiled' form of a pattern.

docs/reference/glib/tmpl/quarks.sgml

@@ -31,6 +31,9 @@ To find the #GQuark corresponding to a given string, use g_quark_try_string().
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### TYPEDEF GQuark ##### -->
 <para>
 A GQuark is an integer which uniquely identifies a particular string.

docs/reference/glib/tmpl/queue.sgml

@@ -35,6 +35,9 @@ To free the entire queue, use g_queue_free().
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GQueue ##### -->
 <para>
 Contains the public fields of a <link linkend="glib-queues">Queue</link>.

docs/reference/glib/tmpl/random_numbers.sgml

@@ -55,6 +55,9 @@ with Glib-2.0 that you need to reproduce exactly.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GRand ##### -->
 <para>
 The #GRand struct is an opaque data structure. It should only be

docs/reference/glib/tmpl/relations.sgml

@@ -56,6 +56,9 @@ To help debug #GRelation objects, use g_relation_print().
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GRelation ##### -->
 <para>
 The #GRelation struct is an opaque data structure to represent a

docs/reference/glib/tmpl/scanner.sgml

@@ -19,6 +19,9 @@ understand it myself. Look at gtkrc.c for some code using the scanner.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GScanner ##### -->
 <para>
 The data structure representing a lexical scanner.

docs/reference/glib/tmpl/shell.sgml

@@ -14,6 +14,9 @@ shell-like commandline handling.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### ENUM GShellError ##### -->
 <para>
 Error codes returned by shell functions.

docs/reference/glib/tmpl/spawn.sgml

@@ -14,6 +14,9 @@ process launching with <function>fork()</function>/<function>exec()</function>.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### ENUM GSpawnError ##### -->
 <para>
 Error codes returned by spawning processes.

docs/reference/glib/tmpl/string_chunks.sgml

@@ -40,6 +40,9 @@ It is not possible to free individual strings.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GStringChunk ##### -->
 <para>
 An opaque data structure representing String Chunks.

docs/reference/glib/tmpl/string_utils.sgml

@@ -37,6 +37,9 @@ wide characters (see g_unichar_iswide()) into account.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### FUNCTION g_strdup ##### -->
 <para>
 Duplicates a string.

docs/reference/glib/tmpl/strings.sgml

@@ -76,7 +76,7 @@ you do not have to worry about having enough space to copy the string.
 </para>
 
 @string: the destination #GString. Its current contents are destroyed.
-@rval: the string to copy into @string 
+@rval: the string to copy into @string
 @Returns: the destination #GString.
 <!-- # Unused Parameters # -->
 @val: the string to copy into @string.

docs/reference/glib/tmpl/thread_pools.sgml

@@ -59,6 +59,9 @@ can be stopped by calling g_thread_pool_stop_unused_threads().
 </variablelist>
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GThreadPool ##### -->
 <para>
 The #GThreadPool struct represents a thread pool. It has six public

docs/reference/glib/tmpl/threads.sgml

@@ -49,6 +49,9 @@ primitives to portably create and manage threads (#GThread).
 </variablelist>
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### MACRO G_THREADS_ENABLED ##### -->
 
 <para>

docs/reference/glib/tmpl/timers.sgml

@@ -17,6 +17,9 @@ get exactly right, so #GTimer provides a portable/convenient interface.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GTimer ##### -->
 <para>
 Opaque datatype that records a start time. 

docs/reference/glib/tmpl/trash_stack.sgml

@@ -21,6 +21,9 @@ is a perfectly valid empty stack.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GTrashStack ##### -->
 <para>
 Each piece of memory that is pushed onto the stack

docs/reference/glib/tmpl/trees-binary.sgml

@@ -40,6 +40,9 @@ To destroy a #GTree, use g_tree_destroy().
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GTree ##### -->
 <para>
 The <structname>GTree</structname> struct is an opaque data structure representing a

docs/reference/glib/tmpl/trees-nary.sgml

@@ -49,6 +49,9 @@ g_node_destroy().
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GNode ##### -->
 <para>
 The <structname>GNode</structname> struct represents one node in a

docs/reference/glib/tmpl/type_conversion.sgml

@@ -55,6 +55,9 @@ integer; values outside the range of a 32-bit integer will be mangled.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### MACRO GINT_TO_POINTER ##### -->
 <para>
 Stuffs an integer into a pointer type.

docs/reference/glib/tmpl/types.sgml

@@ -37,6 +37,9 @@ for completeness - #gchar, #gint, #gshort, #glong, #gfloat, #gdouble.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### TYPEDEF gboolean ##### -->
 <para>
 A standard <type>boolean</type> type.

docs/reference/glib/tmpl/unicode.sgml

@@ -29,6 +29,9 @@ Convenience functions for converting between UTF-8 and the locale encoding.
 </variablelist>
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### TYPEDEF gunichar ##### -->
 <para>
 A type which can hold any UCS-4 character code. 

docs/reference/glib/tmpl/version.sgml

@@ -16,6 +16,9 @@ typically use the features described here.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### VARIABLE glib_major_version ##### -->
 <para>
 The major version number of the GLib library. 

docs/reference/glib/tmpl/warnings.sgml

@@ -14,6 +14,9 @@ These functions provide support for outputting messages.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### FUNCTION g_print ##### -->
 <para>
 Outputs a formatted message via the print handler.

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.