From 68a7351a35f5fa1c039ee3504e654b0f6a2a5d8b Mon Sep 17 00:00:00 2001 From: Rico Tzschichholz Date: Tue, 20 Mar 2012 19:54:18 +0100 Subject: Update glib annotations to 2.31.22 --- gir/gio-2.0.c | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ gir/glib-2.0.c | 24 +++++++++++++----------- gir/gobject-2.0.c | 4 ++++ 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. */ @@ -35735,6 +35754,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. @@ -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. - * * 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. + * + * This is guaranteed to be a stable sort since version 2.32. */ @@ -27194,6 +27192,8 @@ * 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. + * + * 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. */ -- cgit v1.2.1