From 0a5c522a23057a96f5097815d2341c2befa8ab0f Mon Sep 17 00:00:00 2001 From: Rico Tzschichholz Date: Sun, 8 Jan 2012 15:10:04 +0100 Subject: 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 67768291..b750f90a 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. */ @@ -5915,6 +5918,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: + * + * + * + * %G_SOCKET_CLIENT_RESOLVING: + * + * @client is about to look up @connectable in DNS. + * @connection will be %NULL. + * + * + * + * %G_SOCKET_CLIENT_RESOLVED: + * + * @client has successfully resolved @connectable in DNS. + * @connection will be %NULL. + * + * + * + * %G_SOCKET_CLIENT_CONNECTING: + * + * @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. + * + * + * + * %G_SOCKET_CLIENT_CONNECTED: + * + * @client has successfully connected to a remote host. + * @connection is the connected #GSocketConnection. + * + * + * + * %G_SOCKET_CLIENT_PROXY_NEGOTIATING: + * + * @client is about to negotiate with a proxy to get it to + * connect to @connectable. @connection is the + * #GSocketConnection to the proxy server. + * + * + * + * %G_SOCKET_CLIENT_PROXY_NEGOTIATED: + * + * @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. + * + * + * + * %G_SOCKET_CLIENT_TLS_HANDSHAKING: + * + * @client is about to begin a TLS handshake. @connection is a + * #GTlsClientConnection. + * + * + * + * %G_SOCKET_CLIENT_TLS_HANDSHAKED: + * + * @client has successfully completed the TLS handshake. + * @connection is a #GTlsClientConnection. + * + * + * + * %G_SOCKET_CLIENT_COMPLETE: + * + * @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). + * + * + * + * + * 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: * @@ -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 * - * g_list_foreach (list, g_free, NULL); - * g_list_free (list); + * g_list_free_full (list, g_free); * * * 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: menu, + * submenu, + * section or link + * 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: submenu, + * section or link + * elements with an id='' attribute) that are encountered while parsing * will be added to this table. + * Note that toplevel menu 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 */ @@ -35949,6 +36087,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 @@ -36034,6 +36218,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 diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index ef4d007b..55807157 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 @@ * } * * + * + * 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. */ @@ -19987,6 +19986,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. - * * #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. - * * #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 gdb 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 gdb for the [S]tack trace option. * * Invokes gdb, 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 '"' 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 @@ * * * - * + * * * execute tests according to these test modes: * @@ -32701,6 +32721,20 @@ * quick tests, should run really quickly and give good coverage. * * + * + * undefined + * + * tests for undefined behaviour, may provoke programming errors + * under g_test_trap_fork() to check that appropriate assertions + * or warnings are given + * + * + * + * no-undefined + * + * avoid tests for undefined behaviour + * + * * * * @@ -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 */ @@ -33186,10 +33238,23 @@ */ +/** + * 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 require 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 GVariant * Format Strings. * @@ -37107,6 +37177,7 @@ * g_variant_get_type_string (value)); * * /* no need to free 'key' and 'value' here */ + * /* unless breaking out of this loop */ * } * } * diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c index 16d8491d..07a4d544 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. */ @@ -2318,6 +2321,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 #GWeakRefs taken + * before it was disposed will continue to point to %NULL. If + * #GWeakRefs 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: * @@ -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. */ @@ -11581,6 +11620,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: * -- cgit v1.2.1