Update glib annotations to 2.31.22

3 files changed, 65 insertions, 11 deletions

diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index 356e136d..2277c730 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -20329,6 +20329,9 @@
  * See g_dbus_connection_call_sync() for the synchronous version of this
  * function.
  *
+ * If @callback is %NULL then the D-Bus method call message will be sent with
+ * the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set.
+ *
  * Since: 2.26
  */
 
@@ -23613,6 +23616,9 @@
  * the operation. See g_dbus_proxy_call_sync() for the synchronous
  * version of this method.
  *
+ * If @callback is %NULL then the D-Bus method call message will be sent with
+ * the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set.
+ *
  * Since: 2.26
  */
 
@@ -35659,6 +35665,15 @@
  *
  * Creates a #GSimpleAsyncResult.
  *
+ * The common convention is to create the #GSimpleAsyncResult in the
+ * function that starts the asynchronous operation and use that same
+ * function as the @source_tag.
+ *
+ * If your operation supports cancellation with #GCancellable (which it
+ * probably should) then you should provide the user's cancellable to
+ * g_simple_async_result_set_check_cancellable() immediately after
+ * this function returns.
+ *
  * Returns: a #GSimpleAsyncResult.
  */
 
@@ -35715,6 +35730,10 @@
  * Propagates an error from within the simple asynchronous result to
  * a given destination.
  *
+ * If the #GCancellable given to a prior call to
+ * g_simple_async_result_set_check_cancellable() is cancelled then this
+ * function will return %TRUE with @dest set appropriately.
+ *
  * Returns: %TRUE if the error was propagated to @dest. %FALSE otherwise.
  */
 
@@ -35736,6 +35755,31 @@
 
 
 /**
+ * g_simple_async_result_set_check_cancellable:
+ * @simple: a #GSimpleAsyncResult
+ * @check_cancellable: a #GCancellable to check, or %NULL to unset
+ *
+ * Sets a #GCancellable to check before dispatching results.
+ *
+ * This function has one very specific purpose: the provided cancellable
+ * is checked at the time of g_simple_async_result_propagate_error() If
+ * it is cancelled, these functions will return an "Operation was
+ * cancelled" error (%G_IO_ERROR_CANCELLED).
+ *
+ * Implementors of cancellable asynchronous functions should use this in
+ * order to provide a guarantee to their callers that cancelling an
+ * async operation will reliably result in an error being returned for
+ * that operation (even if a positive result for the operation has
+ * already been sent as an idle to the main context to be dispatched).
+ *
+ * The checking described above is done regardless of any call to the
+ * unrelated g_simple_async_result_set_handle_cancellation() function.
+ *
+ * Since: 2.32
+ */
+
+
+/**
  * g_simple_async_result_set_error: (skip)
  * @simple: a #GSimpleAsyncResult.
  * @domain: a #GQuark (usually #G_IO_ERROR).
@@ -35775,6 +35819,10 @@
  * @handle_cancellation: a #gboolean.
  *
  * Sets whether to handle cancellation within the asynchronous operation.
+ *
+ * This function has nothing to do with
+ * g_simple_async_result_set_check_cancellable().  It only refers to the
+ * #GCancellable passed to g_simple_async_result_run_in_thread().
  */
 
 
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index fb17fa37..74d991a8 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -13467,11 +13467,7 @@
  * than second arg, zero for equal, greater zero if first arg is
  * greater than second arg).
  *
- * If two array elements compare equal, their order in the sorted array
- * is undefined. If you want equal elements to keep their order (i.e.
- * you want a stable sort) you can write a comparison function that,
- * if two elements would otherwise compare equal, compares them by
- * their addresses.
+ * This is guaranteed to be a stable sort since version 2.32.
  */
 
 
@@ -13483,6 +13479,12 @@
  *
  * Like g_array_sort(), but the comparison function receives an extra
  * user data argument.
+ *
+ * This is guaranteed to be a stable sort since version 2.32.
+ *
+ * There used to be a comment here about making the sort stable by
+ * using the addresses of the elements in the comparison function.
+ * This did not actually work, so any such code should be removed.
  */
 
 
@@ -27170,15 +27172,11 @@
  * than second arg, zero for equal, greater than zero if irst arg is
  * greater than second arg).
  *
- * If two array elements compare equal, their order in the sorted array
- * is undefined. If you want equal elements to keep their order (i.e.
- * you want a stable sort) you can write a comparison function that,
- * if two elements would otherwise compare equal, compares them by
- * their addresses.
- *
  * <note><para>The comparison function for g_ptr_array_sort() doesn't
  * take the pointers from the array as arguments, it takes pointers to
  * the pointers in the array.</para></note>
+ *
+ * This is guaranteed to be a stable sort since version 2.32.
  */
 
 
@@ -27194,6 +27192,8 @@
  * <note><para>The comparison function for g_ptr_array_sort_with_data()
  * doesn't take the pointers from the array as arguments, it takes
  * pointers to the pointers in the array.</para></note>
+ *
+ * This is guaranteed to be a stable sort since version 2.32.
  */
 
 
@@ -27220,6 +27220,8 @@
  *
  * This is just like the standard C qsort() function, but
  * the comparison routine accepts a user data argument.
+ *
+ * This is guaranteed to be a stable sort since version 2.32.
  */
 
 
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index 518936ca..af3cdcbe 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -10383,6 +10383,8 @@
  * (such as the various fundamental type implementations or the signal
  * system).
  *
+ * This function is idempotent.
+ *
  * Since version 2.24 this also initializes the thread system
  */
 
@@ -10392,6 +10394,8 @@
  * @debug_flags: Bitwise combination of #GTypeDebugFlags values for debugging purposes.
  *
  * Similar to g_type_init(), but additionally sets debug flags.
+ *
+ * This function is idempotent.
  */