[gobject-introspection] Update annotations from GLib git

[Rico Tzschichholz <ricotz src gnome org>]

commit 0a5c522a23057a96f5097815d2341c2befa8ab0f
Author: Rico Tzschichholz <ricotz t-online de>
Date:   Sun Jan 8 15:10:04 2012 +0100

    Update annotations from GLib git

 gir/gio-2.0.c     |  218 ++++++++++++++++++++++++++++++++++++++++++++++++++---
 gir/glib-2.0.c    |  131 ++++++++++++++++++++++++-------
 gir/gobject-2.0.c |  108 ++++++++++++++++++++++++++
 3 files changed, 416 insertions(+), 41 deletions(-)
---
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index 6776829..b750f90 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -5004,6 +5004,9 @@
  *
  * On UNIX, processes are identified by a process id (an integer),
  * while Windows uses process handles (which are pointers).
+ *
+ * GPid is used in GLib only for descendant processes spawned with
+ * the g_spawn functions.
  */
 
 
@@ -5916,6 +5919,127 @@
 
 
 /**
+ * GSocketClient::event:
+ * @client: the #GSocketClient
+ * @event: the event that is occurring
+ * @connectable: the #GSocketConnectable that @event is occurring on
+ * @connection: the current representation of the connection
+ *
+ * Emitted when @client's activity on @connectable changes state.
+ * Among other things, this can be used to provide progress
+ * information about a network connection in the UI. The meanings of
+ * the different @event values are as follows:
+ *
+ * <variablelist>
+ * <varlistentry>
+ * <term>%G_SOCKET_CLIENT_RESOLVING:</term>
+ * <listitem><para>
+ * @client is about to look up @connectable in DNS.
+ * @connection will be %NULL.
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>%G_SOCKET_CLIENT_RESOLVED:</term>
+ * <listitem><para>
+ * @client has successfully resolved @connectable in DNS.
+ * @connection will be %NULL.
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>%G_SOCKET_CLIENT_CONNECTING:</term>
+ * <listitem><para>
+ * @client is about to make a connection to a remote host;
+ * either a proxy server or the destination server itself.
+ * @connection is the #GSocketConnection, which is not yet
+ * connected.
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>%G_SOCKET_CLIENT_CONNECTED:</term>
+ * <listitem><para>
+ * @client has successfully connected to a remote host.
+ * @connection is the connected #GSocketConnection.
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>%G_SOCKET_CLIENT_PROXY_NEGOTIATING:</term>
+ * <listitem><para>
+ * @client is about to negotiate with a proxy to get it to
+ * connect to @connectable. @connection is the
+ * #GSocketConnection to the proxy server.
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>%G_SOCKET_CLIENT_PROXY_NEGOTIATED:</term>
+ * <listitem><para>
+ * @client has negotiated a connection to @connectable through
+ * a proxy server. @connection is the stream returned from
+ * g_proxy_connect(), which may or may not be a
+ * #GSocketConnection.
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>%G_SOCKET_CLIENT_TLS_HANDSHAKING:</term>
+ * <listitem><para>
+ * @client is about to begin a TLS handshake. @connection is a
+ * #GTlsClientConnection.
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>%G_SOCKET_CLIENT_TLS_HANDSHAKED:</term>
+ * <listitem><para>
+ * @client has successfully completed the TLS handshake.
+ * @connection is a #GTlsClientConnection.
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>%G_SOCKET_CLIENT_COMPLETE:</term>
+ * <listitem><para>
+ * @client has either successfully connected to @connectable
+ * (in which case @connection is the #GSocketConnection that
+ * it will be returning to the caller) or has failed (in which
+ * case @connection is %NULL and the client is about to return
+ * an error).
+ * </para></listitem>
+ * </varlistentry>
+ * </variablelist>
+ *
+ * Each event except %G_SOCKET_CLIENT_COMPLETE may be emitted
+ * multiple times (or not at all) for a given connectable (in
+ * particular, if @client ends up attempting to connect to more than
+ * one address). However, if @client emits the #GSocketClient:event
+ * signal at all for a given connectable, that it will always emit
+ * it with %G_SOCKET_CLIENT_COMPLETE when it is done.
+ *
+ * Note that there may be additional #GSocketClientEvent values in
+ * the future; unrecognized @event values should be ignored.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * GSocketClientEvent:
+ * @G_SOCKET_CLIENT_RESOLVING: The client is doing a DNS lookup.
+ * @G_SOCKET_CLIENT_RESOLVED: The client has completed a DNS lookup.
+ * @G_SOCKET_CLIENT_CONNECTING: The client is connecting to a remote host (either a proxy or the destination server).
+ * @G_SOCKET_CLIENT_CONNECTED: The client has connected to a remote host.
+ * @G_SOCKET_CLIENT_PROXY_NEGOTIATING: The client is negotiating with a proxy to connect to the destination server.
+ * @G_SOCKET_CLIENT_PROXY_NEGOTIATED: The client has negotiated with the proxy server.
+ * @G_SOCKET_CLIENT_TLS_HANDSHAKING: The client is performing a TLS handshake.
+ * @G_SOCKET_CLIENT_TLS_HANDSHAKED: The client has performed a TLS handshake.
+ * @G_SOCKET_CLIENT_COMPLETE: The client is done with a particular #GSocketConnectable.
+ *
+ * Describes an event occurring on a #GSocketClient. See the
+ * #GSocketClient::event signal for more details.
+ *
+ * Additional values may be added to this type in the future.
+ *
+ * Since: 2.32
+ */
+
+
+/**
  * GSocketConnectable:
  *
  * Interface for objects that contain or generate #GSocketAddress<!-- -->es.
@@ -18741,8 +18865,7 @@
  * Gets a list of strings containing all the registered content types
  * known to the system. The list and its data should be freed using
  * <programlisting>
- * g_list_foreach (list, g_free, NULL);
- * g_list_free (list);
+ * g_list_free_full (list, g_free);
  * </programlisting>
  *
  * Returns: (element-type utf8) (transfer full): #GList of the registered content types
@@ -23793,7 +23916,7 @@
  *
  * Gets the keywords from the desktop file.
  *
- * Returns: (transfer none): The value of the X-GNOME-Keywords key
+ * Returns: (transfer none): The value of the Keywords key
  * Since: 2.32
  */
 
@@ -30047,7 +30170,7 @@
  * @section: a #GMenuModel with the items of the section
  *
  * Convenience function for appending a section menu item to the end of
- * @menu.  Combine g_menu_new_section() and g_menu_insert_item() for a
+ * @menu.  Combine g_menu_item_new_section() and g_menu_insert_item() for a
  * more flexible alternative.
  *
  * Since: 2.32
@@ -30211,7 +30334,7 @@
  * @section: a #GMenuModel with the items of the section
  *
  * Convenience function for inserting a section menu item into @menu.
- * Combine g_menu_new_section() and g_menu_insert_item() for a more
+ * Combine g_menu_item_new_section() and g_menu_insert_item() for a more
  * flexible alternative.
  *
  * Since: 2.32
@@ -30689,9 +30812,12 @@
  *
  * If @objects is specified then it must be a #GHashTable that was
  * created using g_hash_table_new_full() with g_str_hash(),
- * g_str_equal(), g_free() and g_object_unref().  Any named menus (ie:
- * those with an id='' attribute) that are encountered while parsing
- * will be added to this table.  Each toplevel menu must be named.
+ * g_str_equal(), g_free() and g_object_unref().
+ * Any named menus (ie: <tag class="starttag">menu</tag>,
+ * <tag class="starttag">submenu</tag>,
+ * <tag class="starttag">section</tag> or <tag class="starttag">link</tag>
+ * elements with an id='' attribute) that are encountered while parsing
+ * will be added to this table. Each toplevel menu must be named.
  *
  * If @objects is %NULL then an empty hash table will be created.
  *
@@ -30721,9 +30847,13 @@
  *
  * If @objects is specified then it must be a #GHashTable that was
  * created using g_hash_table_new_full() with g_str_hash(),
- * g_str_equal(), g_free() and g_object_unref().  Any named menus (ie:
- * those with an * id='' attribute) that are encountered while parsing
+ * g_str_equal(), g_free() and g_object_unref().
+ * Any named menus (ie: <tag class="starttag">submenu</tag>,
+ * <tag class="starttag">section</tag> or <tag class="starttag">link</tag>
+ * elements with an id='' attribute) that are encountered while parsing
  * will be added to this table.
+ * Note that toplevel <tag class="starttag">menu</tag> is not added to
+ * the hash table, even if it has an id attribute.
  *
  * If @objects is %NULL then named menus will not be supported.
  *
@@ -30958,7 +31088,7 @@
  * @section: a #GMenuModel with the items of the section
  *
  * Convenience function for prepending a section menu item to the start
- * of @menu.  Combine g_menu_new_section() and g_menu_insert_item() for
+ * of @menu.  Combine g_menu_item_new_section() and g_menu_insert_item() for
  * a more flexible alternative.
  *
  * Since: 2.32
@@ -35787,6 +35917,14 @@
  * g_tcp_wrapper_connection_get_base_io_stream() on the return value
  * to extract the #GTlsClientConnection.
  *
+ * If you need to modify the behavior of the TLS handshake (eg, by
+ * setting a client-side certificate to use, or connecting to the
+ * #GTlsConnection::accept-certificate signal), you can connect to
+ * @client's #GSocketClient::event signal and wait for it to be
+ * emitted with %G_SOCKET_CLIENT_TLS_HANDSHAKING, which will give you
+ * a chance to see the #GTlsClientConnection before the handshake
+ * starts.
+ *
  * Since: 2.28
  */
 
@@ -35950,6 +36088,52 @@
 
 
 /**
+ * g_socket_connection_connect:
+ * @connection: a #GSocketConnection
+ * @address: a #GSocketAddress specifying the remote address.
+ * @cancellable: (allow-none): a %GCancellable or %NULL
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Connect @connection to the specified remote address.
+ *
+ * Returns: %TRUE if the connection succeeded, %FALSE on error
+ * Since: 2.32
+ */
+
+
+/**
+ * g_socket_connection_connect_async:
+ * @connection: a #GSocketConnection
+ * @address: a #GSocketAddress specifying the remote address.
+ * @cancellable: (allow-none): a %GCancellable or %NULL
+ * @callback: (scope async): a #GAsyncReadyCallback
+ * @user_data: (closure): user data for the callback
+ *
+ * Asynchronously connect @connection to the specified remote address.
+ *
+ * This clears the #GSocket:blocking flag on @connection's underlying
+ * socket if it is currently set.
+ *
+ * Use g_socket_connection_connect_finish() to retrieve the result.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_socket_connection_connect_finish:
+ * @connection: a #GSocketConnection
+ * @result: the #GAsyncResult
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Gets the result of a g_socket_connection_connect_async() call.
+ *
+ * Returns: %TRUE if the connection succeeded, %FALSE on error
+ * Since: 2.32
+ */
+
+
+/**
  * g_socket_connection_factory_create_connection:
  * @socket: a #GSocket
  *
@@ -36035,6 +36219,18 @@
 
 
 /**
+ * g_socket_connection_is_connected:
+ * @connection: a #GSocketConnection
+ *
+ * Checks if @connection is connected. This is equivalent to calling
+ * g_socket_is_connected() on @connection's underlying #GSocket.
+ *
+ * Returns: whether @connection is connected
+ * Since: 2.32
+ */
+
+
+/**
  * g_socket_control_message_deserialize:
  * @level: a socket level
  * @type: a socket control message type for the given @level
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index ef4d007..5580715 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -2491,6 +2491,9 @@
  *
  * On UNIX, processes are identified by a process id (an integer),
  * while Windows uses process handles (which are pointers).
+ *
+ * GPid is used in GLib only for descendant processes spawned with
+ * the g_spawn functions.
  */
 
 
@@ -11492,6 +11495,9 @@
  * }
  * </programlisting>
  * </example>
+ *
+ * As of version 2.32, there is also a g_hash_table_add() function to
+ * add a key to a #GHashTable that is being used as a set.
  */
 
 
@@ -14267,8 +14273,7 @@
  * calling g_atexit() (or atexit()) except in the main executable of a
  * program.
  *
- * Deprecated:2.32: It is best to avoid g_atexit(), for the reasons
- * outlined above.
+ * Deprecated:2.32: It is best to avoid g_atexit().
  */
 
 
@@ -16352,9 +16357,6 @@
  * If no threads are waiting for @cond, this function has no effect.
  * It is good practice to lock the same mutex as the waiting threads
  * while calling this function, though not required.
- *
- * This function can be used even if g_thread_init() has not yet been
- * called, and, in that case, will do nothing.
  */
 
 
@@ -16402,9 +16404,6 @@
  * If no threads are waiting for @cond, this function has no effect.
  * It is good practice to hold the same lock as the waiting thread
  * while calling this function, though not required.
- *
- * This function can be used even if g_thread_init() has not yet been
- * called, and, in that case, will do nothing.
  */
 
 
@@ -19988,6 +19987,34 @@
 
 
 /**
+ * g_hash_table_add:
+ * @hash_table: a #GHashTable
+ * @key: a key to insert
+ *
+ * This is a convenience function for using a #GHashTable as a set.  It
+ * is equivalent to calling g_hash_table_replace() with @key as both the
+ * key and the value.
+ *
+ * When a hash table only ever contains keys that have themselves as the
+ * corresponding value it is able to be stored more efficiently.  See
+ * the discussion in the section description.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_hash_table_contains:
+ * @hash_table: a #GHashTable
+ * @key: a key to check
+ *
+ * Checks if @key is in @hash_table.
+ *
+ * Since: 2.32
+ */
+
+
+/**
  * g_hash_table_destroy:
  * @hash_table: a #GHashTable
  *
@@ -24998,7 +25025,7 @@
  * returned and %errno will be set.
  *
  * Returns: A pointer to @tmpl, which has been modified
- * Since: 2.26
+ * Since: 2.30
  */
 
 
@@ -25023,7 +25050,7 @@
  * returned, and %errno will be set.
  *
  * Returns: A pointer to @tmpl, which has been modified
- * Since: 2.26
+ * Since: 2.30
  */
 
 
@@ -25135,9 +25162,6 @@
  * current thread will block until @mutex is unlocked by the other
  * thread.
  *
- * This function can be used even if g_thread_init() has not yet been
- * called, and, in that case, will do nothing.
- *
  * <note>#GMutex is neither guaranteed to be recursive nor to be
  * non-recursive.  As such, calling g_mutex_lock() on a #GMutex that has
  * already been locked by the same thread results in undefined behaviour
@@ -25153,9 +25177,6 @@
  * it immediately returns %FALSE. Otherwise it locks @mutex and returns
  * %TRUE.
  *
- * This function can be used even if g_thread_init() has not yet been
- * called, and, in that case, will immediately return %TRUE.
- *
  * <note>#GMutex is neither guaranteed to be recursive nor to be
  * non-recursive.  As such, calling g_mutex_lock() on a #GMutex that has
  * already been locked by the same thread results in undefined behaviour
@@ -25175,9 +25196,6 @@
  *
  * Calling g_mutex_unlock() on a mutex that is not locked by the
  * current thread leads to undefined behaviour.
- *
- * This function can be used even if g_thread_init() has not yet been
- * called, and, in that case, will do nothing.
  */
 
 
@@ -25703,11 +25721,13 @@
 
 /**
  * g_on_error_stack_trace:
- * @prg_name: the program name, needed by <command>gdb</command> for the [S]tack trace option. If @prg_name is %NULL, g_get_prgname() is called to get the program name (which will work correctly if gdk_init() or gtk_init() has been called)
+ * @prg_name: the program name, needed by <command>gdb</command> for the [S]tack trace option.
  *
  * Invokes <command>gdb</command>, which attaches to the current
  * process and shows a stack trace. Called by g_on_error_query()
- * when the [S]tack trace option is selected.
+ * when the [S]tack trace option is selected. You can get the current
+ * process's "program name" with g_get_prgname(), assuming that you
+ * have called gtk_init() or gdk_init().
  *
  * This function may cause different actions on non-UNIX platforms.
  */
@@ -31523,7 +31543,7 @@
  * @source: a string to escape
  * @exceptions: a string of characters not to escape in @source
  *
- * Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\'
+ * Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\v', '\'
  * and '&quot;' in the string @source by inserting a '\' before
  * them. Additionally all characters in the range 0x01-0x1F (everything
  * below SPACE) and in the range 0x7F-0xFF (all non-ASCII chars) are
@@ -32678,7 +32698,7 @@
  * </para></listitem>
  * </varlistentry>
  * <varlistentry>
- * <term><option>-m {perf|slow|thorough|quick}</option></term>
+ * <term><option>-m {perf|slow|thorough|quick|undefined|no-undefined}</option></term>
  * <listitem><para>
  * execute tests according to these test modes:
  * <variablelist>
@@ -32701,6 +32721,20 @@
  * quick tests, should run really quickly and give good coverage.
  * </para></listitem>
  * </varlistentry>
+ * <varlistentry>
+ * <term>undefined</term>
+ * <listitem><para>
+ * tests for undefined behaviour, may provoke programming errors
+ * under g_test_trap_fork() to check that appropriate assertions
+ * or warnings are given
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>no-undefined</term>
+ * <listitem><para>
+ * avoid tests for undefined behaviour
+ * </para></listitem>
+ * </varlistentry>
  * </variablelist>
  * </para></listitem>
  * </varlistentry>
@@ -32882,6 +32916,8 @@
  * g_test_quick:
  *
  * Returns %TRUE if tests are run in quick mode.
+ * Exactly one of g_test_quick() and g_test_slow() is active in any run;
+ * there is no "medium speed".
  *
  * Returns: %TRUE if in quick mode
  */
@@ -32891,8 +32927,9 @@
  * g_test_quiet:
  *
  * Returns %TRUE if tests are run in quiet mode.
+ * The default is neither g_test_verbose() nor g_test_quiet().
  *
- * Returns: %TRUE if in quied mode
+ * Returns: %TRUE if in quiet mode
  */
 
 
@@ -32997,8 +33034,10 @@
  * g_test_slow:
  *
  * Returns %TRUE if tests are run in slow mode.
+ * Exactly one of g_test_quick() and g_test_slow() is active in any run;
+ * there is no "medium speed".
  *
- * Returns: %TRUE if in slow mode
+ * Returns: the opposite of g_test_quick()
  */
 
 
@@ -33027,9 +33066,10 @@
 /**
  * g_test_thorough:
  *
- * Returns %TRUE if tests are run in thorough mode.
+ * Returns %TRUE if tests are run in thorough mode, equivalent to
+ * g_test_slow().
  *
- * Returns: %TRUE if in thorough mode
+ * Returns: the same thing as g_test_slow()
  */
 
 
@@ -33069,6 +33109,12 @@
  * Assert that the last forked test failed.
  * See g_test_trap_fork().
  *
+ * This is sometimes used to test situations that are formally considered to
+ * be undefined behaviour, like inputs that fail a g_return_if_fail()
+ * check. In these situations you should skip the entire test, including the
+ * call to g_test_trap_fork(), unless g_test_undefined() returns %TRUE
+ * to indicate that undefined behaviour may be tested.
+ *
  * Since: 2.16
  */
 
@@ -33090,6 +33136,12 @@
  * Assert that the stderr output of the last forked test
  * matches @serrpattern. See  g_test_trap_fork().
  *
+ * This is sometimes used to test situations that are formally considered to
+ * be undefined behaviour, like inputs that fail a g_return_if_fail()
+ * check. In these situations you should skip the entire test, including the
+ * call to g_test_trap_fork(), unless g_test_undefined() returns %TRUE
+ * to indicate that undefined behaviour may be tested.
+ *
  * Since: 2.16
  */
 
@@ -33187,9 +33239,22 @@
 
 
 /**
+ * g_test_undefined:
+ *
+ * Returns %TRUE if tests may provoke assertions and other formally-undefined
+ * behaviour under g_test_trap_fork(), to verify that appropriate warnings
+ * are given. It can be useful to turn this off if running tests under
+ * valgrind.
+ *
+ * Returns: %TRUE if tests may provoke programming errors
+ */
+
+
+/**
  * g_test_verbose:
  *
  * Returns %TRUE if tests are run in verbose mode.
+ * The default is neither g_test_verbose() nor g_test_quiet().
  *
  * Returns: %TRUE if in verbose mode
  */
@@ -35727,10 +35792,11 @@
 /**
  * g_utf8_strlen:
  * @p: pointer to the start of a UTF-8 encoded string
- * @max: the maximum number of bytes to examine. If @max is less than 0, then the string is assumed to be nul-terminated. If @max is 0, @p will not be examined and may be %NULL.
+ * @max: the maximum number of bytes to examine. If @max is less than 0, then the string is assumed to be nul-terminated. If @max is 0, @p will not be examined and may be %NULL. If @max is greater than 0, up to @max bytes are examined
  *
  * Computes the length of the string in characters, not including
- * the terminating nul character.
+ * the terminating nul character. If the @max'th byte falls in the
+ * middle of a character, the last (partial) character is not counted.
  *
  * Returns: the length of the string in characters
  */
@@ -35899,7 +35965,7 @@
  * being validated otherwise).
  *
  * Note that g_utf8_validate() returns %FALSE if @max_len is
- * positive and NUL is met before @max_len bytes have been read.
+ * positive and any of the @max_len bytes are NUL.
  *
  * Returns %TRUE if all of @str was valid. Many GLib and GTK+
  * routines <emphasis>require</emphasis> valid UTF-8 as input;
@@ -37086,6 +37152,10 @@
  * function and g_variant_iter_next() or g_variant_iter_next_value() on
  * the same iterator causes undefined behavior.
  *
+ * If you break out of a such a while loop using g_variant_iter_loop() then
+ * you must free or unreference all the unpacked values as you would with
+ * g_variant_get(). Failure to do so will cause a memory leak.
+ *
  * See the section on <link linkend='gvariant-format-strings'>GVariant
  * Format Strings</link>.
  *
@@ -37107,6 +37177,7 @@
  * g_variant_get_type_string (value));
  *
  * /<!-- -->* no need to free 'key' and 'value' here *<!-- -->/
+ * /<!-- -->* unless breaking out of this loop *<!-- -->/
  * }
  * }
  * </programlisting>
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index 16d8491..07a4d54 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -1292,6 +1292,9 @@
  *
  * On UNIX, processes are identified by a process id (an integer),
  * while Windows uses process handles (which are pointers).
+ *
+ * GPid is used in GLib only for descendant processes spawned with
+ * the g_spawn functions.
  */
 
 
@@ -2319,6 +2322,32 @@
 
 
 /**
+ * GWeakRef:
+ *
+ * A structure containing a weak reference to a #GObject.  It can either
+ * be empty (i.e. point to %NULL), or point to an object for as long as
+ * at least one "strong" reference to that object exists. Before the
+ * object's #GObjectClass.dispose method is called, every #GWeakRef
+ * associated with becomes empty (i.e. points to %NULL).
+ *
+ * Like #GValue, #GWeakRef can be statically allocated, stack- or
+ * heap-allocated, or embedded in larger structures.
+ *
+ * Unlike g_object_weak_ref() and g_object_add_weak_pointer(), this weak
+ * reference is thread-safe: converting a weak pointer to a reference is
+ * atomic with respect to invalidation of weak pointers to destroyed
+ * objects.
+ *
+ * If the object's #GObjectClass.dispose method results in additional
+ * references to the object being held, any #GWeakRef<!-- -->s taken
+ * before it was disposed will continue to point to %NULL.  If
+ * #GWeakRef<!-- -->s are taken after the object is disposed and
+ * re-referenced, they will continue to point to it until its refcount
+ * goes back to zero, at which point they too will be invalidated.
+ */
+
+
+/**
  * G_BOOKMARK_FILE_ERROR:
  *
  * Error domain for bookmark file parsing.
@@ -7207,6 +7236,11 @@
  * the pointer located at @weak_pointer_location is only valid during
  * the lifetime of @object. When the @object is finalized,
  * @weak_pointer will be set to %NULL.
+ *
+ * Note that as with g_object_weak_ref(), the weak references created by
+ * this method are not thread-safe: they cannot safely be used in one
+ * thread if the object's last g_object_unref() might happen in another
+ * thread. Use #GWeakRef if thread-safety is required.
  */
 
 
@@ -8125,6 +8159,11 @@
  * "weak references" because they allow you to safely hold a pointer
  * to an object without calling g_object_ref() (g_object_ref() adds a
  * strong reference, that is, forces the object to stay alive).
+ *
+ * Note that the weak references created by this method are not
+ * thread-safe: they cannot safely be used in one thread if the
+ * object's last g_object_unref() might happen in another thread.
+ * Use #GWeakRef if thread-safety is required.
  */
 
 
@@ -11582,6 +11621,75 @@
 
 
 /**
+ * g_weak_ref_clear: (skip)
+ * @weak_ref: (inout): location of a weak reference, which may be empty
+ *
+ * Frees resources associated with a non-statically-allocated #GWeakRef.
+ * After this call, the #GWeakRef is left in an undefined state.
+ *
+ * You should only call this on a #GWeakRef that previously had
+ * g_weak_ref_init() called on it.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_weak_ref_get: (skip)
+ * @weak_ref: (inout): location of a weak reference to a #GObject
+ *
+ * If @weak_ref is not empty, atomically acquire a strong
+ * reference to the object it points to, and return that reference.
+ *
+ * This function is needed because of the potential race between taking
+ * the pointer value and g_object_ref() on it, if the object was losing
+ * its last reference at the same time in a different thread.
+ *
+ * The caller should release the resulting reference in the usual way,
+ * by using g_object_unref().
+ *
+ * by @weak_ref, or %NULL if it was empty
+ *
+ * Returns: (transfer full) (type GObject.Object): the object pointed to
+ * Since: 2.32
+ */
+
+
+/**
+ * g_weak_ref_init: (skip)
+ * @weak_ref: (inout): uninitialized or empty location for a weak reference
+ * @object: (allow-none): a #GObject or %NULL
+ *
+ * Initialise a non-statically-allocated #GWeakRef.
+ *
+ * This function also calls g_weak_ref_set() with @object on the
+ * freshly-initialised weak reference.
+ *
+ * This function should always be matched with a call to
+ * g_weak_ref_clear().  It is not necessary to use this function for a
+ * #GWeakRef in static storage because it will already be
+ * properly initialised.  Just use g_weak_ref_set() directly.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_weak_ref_set: (skip)
+ * @weak_ref: location for a weak reference
+ * @object: (allow-none): a #GObject or %NULL
+ *
+ * Change the object to which @weak_ref points, or set it to
+ * %NULL.
+ *
+ * You must own a strong reference on @object while calling this
+ * function.
+ *
+ * Since: 2.32
+ */
+
+
+/**
  * gchararray:
  *
  * A C representable type name for #G_TYPE_STRING.