From 5ef6ed6fbc96bd583350599f123438e7d6834ef7 Mon Sep 17 00:00:00 2001 From: Rico Tzschichholz Date: Tue, 17 Mar 2015 17:43:07 +0100 Subject: Update glib annotations from git master --- gir/gio-2.0.c | 88 ++++++++++++++++++++++++++++++++++++++++++++----------- gir/glib-2.0.c | 85 ++++++++++++++++++++++++++++++++++++++--------------- gir/gobject-2.0.c | 12 +++++++- 3 files changed, 143 insertions(+), 42 deletions(-) diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index c1651046..93e376bb 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -2967,6 +2967,23 @@ */ +/** + * GTask:completed: + * + * Whether the task has completed, meaning its callback (if set) has been + * invoked. This can only happen after g_task_return_pointer(), + * g_task_return_error() or one of the other return functions have been called + * on the task. + * + * This property is guaranteed to change from %FALSE to %TRUE exactly once. + * + * The #GObject::notify signal for this change is emitted in the same main + * context as the task’s callback, immediately after that callback is invoked. + * + * Since: 2.44 + */ + + /** * GTaskThreadFunc: * @task: the #GTask @@ -5489,9 +5506,15 @@ * the operation, producing a GAsyncResult which is then passed to the * function's matching _finish() operation. * - * Some #GFile operations do not have synchronous analogs, as they may - * take a very long time to finish, and blocking may leave an application - * unusable. Notable cases include: + * It is highly recommended to use asynchronous calls when running within a + * shared main loop, such as in the main thread of an application. This avoids + * I/O operations blocking other sources on the main loop from being dispatched. + * Synchronous I/O operations should be performed from worker threads. See the + * [introduction to asynchronous programming section][async-programming] for + * more. + * + * Some #GFile operations almost always take a noticeable amount of time, and + * so do not have synchronous analogs. Notable cases include: * - g_file_mount_mountable() to mount a mountable file. * - g_file_unmount_mountable_with_operation() to unmount a mountable file. * - g_file_eject_mountable_with_operation() to eject a mountable file. @@ -30233,14 +30256,6 @@ */ -/** - * g_resource_new_from_table: - * @table: (transfer full): a GvdbTable - * - * Returns: (transfer full): a new #GResource for @table - */ - - /** * g_resource_open_stream: * @resource: A #GResource @@ -35988,6 +36003,19 @@ */ +/** + * g_task_get_completed: + * @task: a #GTask. + * + * Gets the value of #GTask:completed. This changes from %FALSE to %TRUE after + * the task’s callback is invoked, and will return %FALSE if called from inside + * the callback. + * + * Returns: %TRUE if the task has completed, %FALSE otherwise. + * Since: 2.44 + */ + + /** * g_task_get_context: * @task: a #GTask @@ -36361,6 +36389,7 @@ * Normally this is used with tasks created with a %NULL * `callback`, but note that even if the task does * have a callback, it will not be invoked when @task_func returns. + * #GTask:completed will be set to %TRUE just before this function returns. * * Since: 2.36 */ @@ -38695,15 +38724,34 @@ */ +/** + * g_unix_mount_monitor_get: + * + * Gets the #GUnixMountMonitor for the current thread-default main + * context. + * + * The mount monitor can be used to monitor for changes to the list of + * mounted filesystems as well as the list of mount points (ie: fstab + * entries). + * + * You must only call g_object_unref() on the return value from under + * the same main context as you called this function. + * + * Returns: (transfer full): the #GUnixMountMonitor. + * Since: 2.44 + */ + + /** * g_unix_mount_monitor_new: * - * Gets a new #GUnixMountMonitor. The default rate limit for which the - * monitor will report consecutive changes for the mount and mount - * point entry files is the default for a #GFileMonitor. Use - * g_unix_mount_monitor_set_rate_limit() to change this. + * Deprecated alias for g_unix_mount_monitor_get(). + * + * This function was never a true constructor, which is why it was + * renamed. * * Returns: a #GUnixMountMonitor. + * Deprecated: 2.44: Use g_unix_mount_monitor_get() instead. */ @@ -38713,10 +38761,16 @@ * @limit_msec: a integer with the limit in milliseconds to * poll for changes. * - * Sets the rate limit to which the @mount_monitor will report - * consecutive change events to the mount and mount point entry files. + * This function does nothing. + * + * Before 2.44, this was a partially-effective way of controlling the + * rate at which events would be reported under some uncommon + * circumstances. Since @mount_monitor is a singleton, it also meant + * that calling this function would have side effects for other users of + * the monitor. * * Since: 2.18 + * Deprecated: 2.44: This function does nothing. Don't call it. */ diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index 08625f2b..ef98e45c 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -5636,7 +5636,8 @@ * functions in GLib and GTK+ do not use the #GError facility. * * Functions that can fail take a return location for a #GError as their - * last argument. For example: + * last argument. On error, a new #GError instance will be allocated and + * returned to the caller via this argument. For example: * |[ * gboolean g_file_get_contents (const gchar *filename, * gchar **contents, @@ -5745,7 +5746,8 @@ * ]| * * If the sub-function does not indicate errors other than by - * reporting a #GError, you need to create a temporary #GError + * reporting a #GError (or if its return value does not reliably indicate + * errors) you need to create a temporary #GError * since the passed-in one may be %NULL. g_propagate_error() is * intended for use in this case. * |[ @@ -14937,7 +14939,9 @@ * @mem: (allow-none): the memory to free * * Frees the memory pointed to by @mem. - * If @mem is %NULL it simply returns. + * + * If @mem is %NULL it simply returns, so there is no need to check @mem + * against %NULL before calling this function. */ @@ -15632,6 +15636,10 @@ * Retrieves every key inside @hash_table. The returned data is valid * until changes to the hash release those keys. * + * This iterates over every entry in the hash table to build its return value. + * To iterate over the entries in a #GHashTable more efficiently, use a + * #GHashTableIter. + * * Returns: a #GList containing all the keys inside the hash * table. The content of the list is owned by the hash table and * should not be modified or freed. Use g_list_free() when done @@ -15654,6 +15662,10 @@ * Note: in the common case of a string-keyed #GHashTable, the return * value of this function can be conveniently cast to (const gchar **). * + * This iterates over every entry in the hash table to build its return value. + * To iterate over the entries in a #GHashTable more efficiently, use a + * #GHashTableIter. + * * You should always free the return result with g_free(). In the * above-mentioned case of a string-keyed hash table, it may be * appropriate to use g_strfreev() if you call g_hash_table_steal_all() @@ -15672,6 +15684,10 @@ * Retrieves every value inside @hash_table. The returned data * is valid until @hash_table is modified. * + * This iterates over every entry in the hash table to build its return value. + * To iterate over the entries in a #GHashTable more efficiently, use a + * #GHashTableIter. + * * Returns: a #GList containing all the values inside the hash * table. The content of the list is owned by the hash table and * should not be modified or freed. Use g_list_free() when done @@ -16576,8 +16592,10 @@ * sources and will not be called again. * * This internally creates a main loop source using g_idle_source_new() - * and attaches it to the main loop context using g_source_attach(). - * You can do these steps manually if you need greater control. + * and attaches it to the global #GMainContext using g_source_attach(), so + * the callback will be invoked in whichever thread is running that main + * context. You can do these steps manually if you need greater control or to + * use a custom main context. * * Returns: the ID (greater than 0) of the event source. */ @@ -16596,8 +16614,10 @@ * removed from the list of event sources and will not be called again. * * This internally creates a main loop source using g_idle_source_new() - * and attaches it to the main loop context using g_source_attach(). - * You can do these steps manually if you need greater control. + * and attaches it to the global #GMainContext using g_source_attach(), so + * the callback will be invoked in whichever thread is running that main + * context. You can do these steps manually if you need greater control or to + * use a custom main context. * * Returns: the ID (greater than 0) of the event source. */ @@ -18408,7 +18428,10 @@ * g_list_free_1: * @list: a #GList element * - * Frees one #GList element. + * Frees one #GList element, but does not update links from the next and + * previous elements in the list, so you should not call this function on an + * element that is currently part of a list. + * * It is usually used after g_list_remove_link(). */ @@ -18554,6 +18577,10 @@ * * Gets the element at the given position in a #GList. * + * This iterates over the list until it reaches the @n-th position. If you + * intend to iterate over every element, it is better to use a for-loop as + * described in the #GList introduction. + * * Returns: the element, or %NULL if the position is off * the end of the #GList */ @@ -18566,6 +18593,10 @@ * * Gets the data of the element at the given position. * + * This iterates over the list until it reaches the @n-th position. If you + * intend to iterate over every element, it is better to use a for-loop as + * described in the #GList introduction. + * * Returns: the element's data, or %NULL if the position * is off the end of the #GList */ @@ -22009,7 +22040,7 @@ * i.e. after the "/" in UNIX or "C:\" under Windows. If @file_name * is not an absolute path it returns %NULL. * - * Returns: a pointer into @file_name after the root component + * Returns: (nullable): a pointer into @file_name after the root component */ @@ -27894,7 +27925,7 @@ * it's %FALSE, the caller gains ownership of the buffer and must * free it after use with g_free(). * - * Returns: the character data of @string + * Returns: (nullable): the character data of @string * (i.e. %NULL if @free_segment is %TRUE) */ @@ -30346,8 +30377,10 @@ * optimizations and more efficient system power usage. * * This internally creates a main loop source using g_timeout_source_new() - * and attaches it to the main loop context using g_source_attach(). You can - * do these steps manually if you need greater control. + * and attaches it to the global #GMainContext using g_source_attach(), so + * the callback will be invoked in whichever thread is running that main + * context. You can do these steps manually if you need greater control or to + * use a custom main context. * * The interval given is in terms of monotonic time, not wall clock * time. See g_get_monotonic_time(). @@ -30380,8 +30413,10 @@ * (it does not try to 'catch up' time lost in delays). * * This internally creates a main loop source using g_timeout_source_new() - * and attaches it to the main loop context using g_source_attach(). You can - * do these steps manually if you need greater control. + * and attaches it to the global #GMainContext using g_source_attach(), so + * the callback will be invoked in whichever thread is running that main + * context. You can do these steps manually if you need greater control or to + * use a custom main context. * * The interval given in terms of monotonic time, not wall clock time. * See g_get_monotonic_time(). @@ -30948,7 +30983,9 @@ * * Attempts to realloc @mem to a new size, @n_bytes, and returns %NULL * on failure. Contrast with g_realloc(), which aborts the program - * on failure. If @mem is %NULL, behaves the same as g_try_malloc(). + * on failure. + * + * If @mem is %NULL, behaves the same as g_try_malloc(). * * Returns: the allocated memory, or %NULL. */ @@ -33069,11 +33106,11 @@ * Similar to g_variant_get_string() except that instead of returning * a constant string, the string is duplicated. * - * The string will always be utf8 encoded. + * The string will always be UTF-8 encoded. * * The return value must be freed using g_free(). * - * Returns: (transfer full): a newly allocated string, utf8 encoded + * Returns: (transfer full): a newly allocated string, UTF-8 encoded * Since: 2.24 */ @@ -33512,7 +33549,7 @@ * type. This includes the types %G_VARIANT_TYPE_STRING, * %G_VARIANT_TYPE_OBJECT_PATH and %G_VARIANT_TYPE_SIGNATURE. * - * The string will always be utf8 encoded. + * The string will always be UTF-8 encoded. * * If @length is non-%NULL then the length of the string (in bytes) is * returned there. For trusted values, this information is already @@ -33523,7 +33560,7 @@ * * The return value remains valid as long as @value exists. * - * Returns: (transfer none): the constant string, utf8 encoded + * Returns: (transfer none): the constant string, UTF-8 encoded * Since: 2.24 */ @@ -34206,7 +34243,7 @@ * * Creates an array-of-bytes #GVariant with the contents of @string. * This function is just like g_variant_new_string() except that the - * string need not be valid utf8. + * string need not be valid UTF-8. * * The nul terminator character at the end of the string is stored in * the array. @@ -34546,11 +34583,11 @@ /** * g_variant_new_string: - * @string: a normal utf8 nul-terminated string + * @string: a normal UTF-8 nul-terminated string * * Creates a string #GVariant with the contents of @string. * - * @string must be valid utf8. + * @string must be valid UTF-8. * * Returns: (transfer none): a floating reference to a new string #GVariant instance * Since: 2.24 @@ -34574,11 +34611,11 @@ /** * g_variant_new_take_string: (skip) - * @string: a normal utf8 nul-terminated string + * @string: a normal UTF-8 nul-terminated string * * Creates a string #GVariant with the contents of @string. * - * @string must be valid utf8. + * @string must be valid UTF-8. * * This function consumes @string. g_free() will be called on @string * when it is no longer required. diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c index efe8981a..440d0c2d 100644 --- a/gir/gobject-2.0.c +++ b/gir/gobject-2.0.c @@ -3310,6 +3310,11 @@ * * Decreases the reference count of @object. When its reference count * drops to 0, the object is finalized (i.e. its memory is freed). + * + * If the pointer to the #GObject may be reused in future (for example, if it is + * an instance variable of another object), it is recommended to clear the + * pointer to %NULL rather than retain a dangling pointer to a potentially + * invalid #GObject instance. Use g_clear_object() for this. */ @@ -3368,7 +3373,10 @@ * @flags: flags for the property specified * * Creates a new #GParamSpecBoolean instance specifying a %G_TYPE_BOOLEAN - * property. + * property. In many cases, it may be more appropriate to use an enum with + * g_param_spec_enum(), both to improve code clarity by using explicitly named + * values, and to allow for more values to be added in future without breaking + * API. * * See g_param_spec_internal() for details on property names. * @@ -3716,6 +3724,8 @@ * @flags: flags for the property specified * * Creates a new #GParamSpecPointer instance specifying a pointer property. + * Where possible, it is better to use g_param_spec_object() or + * g_param_spec_boxed() to expose memory management information. * * See g_param_spec_internal() for details on property names. * -- cgit v1.2.1