[gobject-introspection] Update annotations from glib git
- From: Rico Tzschichholz <ricotz src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gobject-introspection] Update annotations from glib git
- Date: Wed, 17 Oct 2012 05:59:05 +0000 (UTC)
commit 72472408669305a2056d0a83c73a3dc186056067
Author: Rico Tzschichholz <ricotz t-online de>
Date: Wed Oct 17 07:58:03 2012 +0200
Update annotations from glib git
gir/gio-2.0.c | 1181 +++++++++++++++++++++++++++++++++++++++++++++++++++--
gir/glib-2.0.c | 48 +--
gir/gobject-2.0.c | 51 +--
3 files changed, 1158 insertions(+), 122 deletions(-)
---
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index 3f3b222..a3eb8b1 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -2392,6 +2392,41 @@
/**
+ * GTask:
+ *
+ * The opaque object representing a synchronous or asynchronous task
+ * and its result.
+ */
+
+
+/**
+ * GTaskThreadFunc:
+ * @task: the #GTask
+ * @source_object: @task's source object
+ * @task_data: @task's task data
+ * @cancellable: @task's #GCancellable, or %NULL
+ *
+ * The prototype for a task function to be run in a thread via
+ * g_task_run_in_thread() or g_task_run_in_thread_sync().
+ *
+ * If the return-on-cancel flag is set on @task, and @cancellable gets
+ * cancelled, then the #GTask will be completed immediately (as though
+ * g_task_return_error_if_cancelled() had been called), without
+ * waiting for the task function to complete. However, the task
+ * function will continue running in its thread in the background. The
+ * function therefore needs to be careful about how it uses
+ * externally-visible state in this case. See
+ * g_task_set_return_on_cancel() for more details.
+ *
+ * Other than in that case, @task will be completed when the
+ * #GTaskThreadFunc returns, <emphasis>not</emphasis> when it calls
+ * a <literal>g_task_return_</literal> function.
+ *
+ * Since: 2.36
+ */
+
+
+/**
* GTestDBus:
*
* The #GTestDBus structure contains only private data and
@@ -3698,13 +3733,13 @@
*
* for (l = self->priv->init_results; l != NULL; l = l->next)
* {
- * GSimpleAsyncResult *simple = l->data;
+ * GTask *task = l->data;
*
- * if (!self->priv->success)
- * g_simple_async_result_set_error (simple, ...);
- *
- * g_simple_async_result_complete (simple);
- * g_object_unref (simple);
+ * if (self->priv->success)
+ * g_task_return_boolean (task, TRUE);
+ * else
+ * g_task_return_new_error (task, ...);
+ * g_object_unref (task);
* }
*
* g_list_free (self->priv->init_results);
@@ -3719,31 +3754,28 @@
* gpointer user_data)
* {
* Foo *self = FOO (initable);
- * GSimpleAsyncResult *simple;
+ * GTask *task;
*
- * simple = g_simple_async_result_new (G_OBJECT (initable)
- * callback,
- * user_data,
- * foo_init_async);
+ * task = g_task_new (initable, cancellable, callback, user_data);
*
* switch (self->priv->state)
* {
* case NOT_INITIALIZED:
* _foo_get_ready (self);
* self->priv->init_results = g_list_append (self->priv->init_results,
- * simple);
+ * task);
* self->priv->state = INITIALIZING;
* break;
* case INITIALIZING:
* self->priv->init_results = g_list_append (self->priv->init_results,
- * simple);
+ * task);
* break;
* case INITIALIZED:
* if (!self->priv->success)
- * g_simple_async_result_set_error (simple, ...);
- *
- * g_simple_async_result_complete_in_idle (simple);
- * g_object_unref (simple);
+ * g_task_return_new_error (task, ...);
+ * else
+ * g_task_return_boolean (task, TRUE);
+ * g_object_unref (task);
* break;
* }
* }
@@ -3753,14 +3785,9 @@
* GAsyncResult *result,
* GError **error)
* {
- * g_return_val_if_fail (g_simple_async_result_is_valid (result,
- * G_OBJECT (initable), foo_init_async), FALSE);
- *
- * if (g_simple_async_result_propagate_error (G_SIMPLE_ASYNC_RESULT (result),
- * error))
- * return FALSE;
+ * g_return_val_if_fail (g_task_is_valid (result, initable), FALSE);
*
- * return TRUE;
+ * return g_task_propagate_boolean (G_TASK (result), error);
* }
*
* static void
@@ -3780,7 +3807,7 @@
* SECTION:gasyncresult
* @short_description: Asynchronous Function Results
* @include: gio/gio.h
- * @see_also: #GSimpleAsyncResult
+ * @see_also: #GTask
*
* Provides a base class for implementing asynchronous function results.
*
@@ -3853,6 +3880,16 @@
* The callback for an asynchronous operation is called only once, and is
* always called, even in the case of a cancelled operation. On cancellation
* the result is a %G_IO_ERROR_CANCELLED error.
+ *
+ * <para id="io-priority"><indexterm><primary>I/O
+ * priority</primary></indexterm> Many I/O-related asynchronous
+ * operations have a priority parameter, which is used in certain
+ * cases to determine the order in which operations are executed. They
+ * are <emphasis>not</emphasis> used to determine system-wide I/O
+ * scheduling. Priorities are integers, with lower numbers indicating
+ * higher priority. It is recommended to choose priorities between
+ * %G_PRIORITY_LOW and %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT as a
+ * default. </para>
*/
@@ -5249,17 +5286,13 @@
* @short_description: I/O Scheduler
* @include: gio/gio.h
*
+ * <note><para>
+ * As of GLib 2.36, the <literal>g_io_scheduler</literal> methods
+ * are deprecated in favor of #GThreadPool and #GTask.
+ * </para></note>
+ *
* Schedules asynchronous I/O operations. #GIOScheduler integrates
* into the main event loop (#GMainLoop) and uses threads.
- *
- * <para id="io-priority"><indexterm><primary>I/O priority</primary></indexterm>
- * Each I/O operation has a priority, and the scheduler uses the priorities
- * to determine the order in which operations are executed. They are
- * <emphasis>not</emphasis> used to determine system-wide I/O scheduling.
- * Priorities are integers, with lower numbers indicating higher priority.
- * It is recommended to choose priorities between %G_PRIORITY_LOW and
- * %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT as a default.
- * </para>
*/
@@ -6221,10 +6254,12 @@
* @include: gio/gio.h
* @see_also: #GAsyncResult
*
- * Implements #GAsyncResult for simple cases. Most of the time, this
- * will be all an application needs, and will be used transparently.
- * Because of this, #GSimpleAsyncResult is used throughout GIO for
- * handling asynchronous functions.
+ * <note><para>
+ * As of GLib 2.36, #GSimpleAsyncResult is deprecated in favor of
+ * #GTask, which provides a simpler API.
+ * </para></note>
+ *
+ * #GSimpleAsyncResult implements #GAsyncResult.
*
* GSimpleAsyncResult handles #GAsyncReadyCallback<!-- -->s, error
* reporting, operation cancellation and the final state of an operation,
@@ -6696,6 +6731,534 @@
/**
+ * SECTION:gtask
+ * @short_description: Cancellable synchronous or asynchronous task and result
+ * @include: gio/gio.h
+ * @see_also: #GAsyncResult
+ *
+ * <para>
+ * A #GTask represents and manages a cancellable "task".
+ * </para>
+ * <refsect2>
+ * <title>Asynchronous operations</title>
+ * <para>
+ * The most common usage of #GTask is as a #GAsyncResult, to
+ * manage data during an asynchronous operation. You call
+ * g_task_new() in the "start" method, followed by
+ * g_task_set_task_data() and the like if you need to keep some
+ * additional data associated with the task, and then pass the
+ * task object around through your asynchronous operation.
+ * Eventually, you will call a method such as
+ * g_task_return_pointer() or g_task_return_error(), which will
+ * save the value you give it and then invoke the task's callback
+ * function (waiting until the next next iteration of the main
+ * loop first, if necessary). The caller will pass the #GTask back
+ * to the operation's finish function (as a #GAsyncResult), and
+ * you can use g_task_propagate_pointer() or the like to extract
+ * the return value.
+ * </para>
+ * <example id="gtask-async"><title>GTask as a GAsyncResult</title>
+ * <programlisting>
+ * typedef struct {
+ * CakeFrostingType frosting;
+ * char *message;
+ * } DecorationData;
+ *
+ * static void
+ * decoration_data_free (DecorationData *decoration)
+ * {
+ * g_free (decoration->message);
+ * g_slice_free (DecorationData, decoration);
+ * }
+ *
+ * static void
+ * baked_cb (Cake *cake,
+ * gpointer user_data)
+ * {
+ * GTask *task = user_data;
+ * DecorationData *decoration = g_task_get_task_data (task);
+ * GError *error = NULL;
+ *
+ * if (cake == NULL)
+ * {
+ * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR,
+ * "Go to the supermarket");
+ * g_object_unref (task);
+ * return;
+ * }
+ *
+ * if (!cake_decorate (cake, decoration->frosting, decoration->message, &error))
+ * {
+ * g_object_unref (cake);
+ * /* g_task_return_error() takes ownership of error */
+ * g_task_return_error (task, error);
+ * g_object_unref (task);
+ * return;
+ * }
+ *
+ * g_task_return_pointer (result, cake, g_object_unref);
+ * g_object_unref (task);
+ * }
+ *
+ * void
+ * baker_bake_cake_async (Baker *self,
+ * guint radius,
+ * CakeFlavor flavor,
+ * CakeFrostingType frosting,
+ * const char *message,
+ * GCancellable *cancellable,
+ * GAsyncReadyCallback callback,
+ * gpointer user_data)
+ * {
+ * GTask *task;
+ * DecorationData *decoration;
+ * Cake *cake;
+ *
+ * task = g_task_new (self, cancellable, callback, user_data);
+ * if (radius < 3)
+ * {
+ * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_TOO_SMALL,
+ * "%ucm radius cakes are silly",
+ * radius);
+ * g_object_unref (task);
+ * return;
+ * }
+ *
+ * cake = _baker_get_cached_cake (self, radius, flavor, frosting, message);
+ * if (cake != NULL)
+ * {
+ * /* _baker_get_cached_cake() returns a reffed cake */
+ * g_task_return_pointer (task, cake, g_object_unref);
+ * g_object_unref (task);
+ * return;
+ * }
+ *
+ * decoration = g_slice_new (DecorationData);
+ * decoration->frosting = frosting;
+ * decoration->message = g_strdup (message);
+ * g_task_set_task_data (task, decoration, (GDestroyNotify) decoration_data_free);
+ *
+ * _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task);
+ * }
+ *
+ * Cake *
+ * baker_bake_cake_finish (Baker *self,
+ * GAsyncResult *result,
+ * GError **error)
+ * {
+ * g_return_val_if_fail (g_task_is_valid (result, self), NULL);
+ *
+ * return g_task_propagate_pointer (G_TASK (result), error);
+ * }
+ * </programlisting>
+ * </example>
+ * </refsect2>
+ * <refsect2>
+ * <title>Chained asynchronous operations</title>
+ * <para>
+ * #GTask also tries to simplify asynchronous operations that
+ * internally chain together several smaller asynchronous
+ * operations. g_task_get_cancellable(), g_task_get_context(), and
+ * g_task_get_priority() allow you to get back the task's
+ * #GCancellable, #GMainContext, and <link
+ * linkend="io-priority">I/O priority</link> when starting a new
+ * subtask, so you don't have to keep track of them yourself.
+ * g_task_attach_source() simplifies the case of waiting for a
+ * source to fire (automatically using the correct #GMainContext
+ * and priority).
+ * </para>
+ * <example id="gtask-chained"><title>Chained asynchronous operations</title>
+ * <programlisting>
+ * typedef struct {
+ * Cake *cake;
+ * CakeFrostingType frosting;
+ * char *message;
+ * } BakingData;
+ *
+ * static void
+ * decoration_data_free (BakingData *bd)
+ * {
+ * if (bd->cake)
+ * g_object_unref (bd->cake);
+ * g_free (bd->message);
+ * g_slice_free (BakingData, bd);
+ * }
+ *
+ * static void
+ * decorated_cb (Cake *cake,
+ * GAsyncResult *result,
+ * gpointer user_data)
+ * {
+ * GTask *task = user_data;
+ * GError *error = NULL;
+ *
+ * if (!cake_decorate_finish (cake, result, &error))
+ * {
+ * g_object_unref (cake);
+ * g_task_return_error (task, error);
+ * g_object_unref (task);
+ * return;
+ * }
+ *
+ * /* baking_data_free() will drop its ref on the cake, so
+ * * we have to take another here to give to the caller.
+ * */
+ * g_task_return_pointer (result, g_object_ref (cake), g_object_unref);
+ * g_object_unref (task);
+ * }
+ *
+ * static void
+ * decorator_ready (gpointer user_data)
+ * {
+ * GTask *task = user_data;
+ * BakingData *bd = g_task_get_task_data (task);
+ *
+ * cake_decorate_async (bd->cake, bd->frosting, bd->message,
+ * g_task_get_cancellable (task),
+ * decorated_cb, task);
+ * }
+ *
+ * static void
+ * baked_cb (Cake *cake,
+ * gpointer user_data)
+ * {
+ * GTask *task = user_data;
+ * BakingData *bd = g_task_get_task_data (task);
+ * GError *error = NULL;
+ *
+ * if (cake == NULL)
+ * {
+ * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR,
+ * "Go to the supermarket");
+ * g_object_unref (task);
+ * return;
+ * }
+ *
+ * bd->cake = cake;
+ *
+ * /* Bail out now if the user has already cancelled */
+ * if (g_task_return_error_if_cancelled (g_task_get_cancellable (task)))
+ * {
+ * g_object_unref (task);
+ * return;
+ * }
+ *
+ * if (cake_decorator_available (cake))
+ * decorator_ready (task);
+ * else
+ * {
+ * GSource *source;
+ *
+ * source = cake_decorator_wait_source_new (cake);
+ * /* Attach @source to @task's GMainContext and have it call
+ * * decorator_ready() when it is ready.
+ * */
+ * g_task_attach_source (task, source,
+ * G_CALLBACK (decorator_ready));
+ * g_source_unref (source);
+ * }
+ * }
+ *
+ * void
+ * baker_bake_cake_async (Baker *self,
+ * guint radius,
+ * CakeFlavor flavor,
+ * CakeFrostingType frosting,
+ * const char *message,
+ * gint priority,
+ * GCancellable *cancellable,
+ * GAsyncReadyCallback callback,
+ * gpointer user_data)
+ * {
+ * GTask *task;
+ * BakingData *bd;
+ *
+ * task = g_task_new (self, cancellable, callback, user_data);
+ * g_task_set_priority (task, priority);
+ *
+ * bd = g_slice_new0 (BakingData);
+ * bd->frosting = frosting;
+ * bd->message = g_strdup (message);
+ * g_task_set_task_data (task, bd, (GDestroyNotify) baking_data_free);
+ *
+ * _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task);
+ * }
+ *
+ * Cake *
+ * baker_bake_cake_finish (Baker *self,
+ * GAsyncResult *result,
+ * GError **error)
+ * {
+ * g_return_val_if_fail (g_task_is_valid (result, self), NULL);
+ *
+ * return g_task_propagate_pointer (G_TASK (result), error);
+ * }
+ * </programlisting>
+ * </example>
+ * </refsect2>
+ * <refsect2>
+ * <title>Asynchronous operations from synchronous ones</title>
+ * <para>
+ * You can use g_task_run_in_thread() to turn a synchronous
+ * operation into an asynchronous one, by running it in a thread
+ * which will then dispatch the result back to the caller's
+ * #GMainContext when it completes.
+ * </para>
+ * <example id="gtask-run-in-thread"><title>g_task_run_in_thread()</title>
+ * <programlisting>
+ * typedef struct {
+ * guint radius;
+ * CakeFlavor flavor;
+ * CakeFrostingType frosting;
+ * char *message;
+ * } CakeData;
+ *
+ * static void
+ * cake_data_free (CakeData *cake_data)
+ * {
+ * g_free (cake_data->message);
+ * g_slice_free (CakeData, cake_data);
+ * }
+ *
+ * static void
+ * bake_cake_thread (GTask *task,
+ * gpointer source_object,
+ * gpointer task_data,
+ * GCancellable *cancellable)
+ * {
+ * Baker *self = source_object;
+ * CakeData *cake_data = task_data;
+ * Cake *cake;
+ * GError *error = NULL;
+ *
+ * cake = bake_cake (baker, cake_data->radius, cake_data->flavor,
+ * cake_data->frosting, cake_data->message,
+ * cancellable, &error);
+ * if (cake)
+ * g_task_return_pointer (task, cake, g_object_unref);
+ * else
+ * g_task_return_error (task, error);
+ * }
+ *
+ * void
+ * baker_bake_cake_async (Baker *self,
+ * guint radius,
+ * CakeFlavor flavor,
+ * CakeFrostingType frosting,
+ * const char *message,
+ * GCancellable *cancellable,
+ * GAsyncReadyCallback callback,
+ * gpointer user_data)
+ * {
+ * CakeData *cake_data;
+ * GTask *task;
+ *
+ * cake_data = g_slice_new (CakeData);
+ * cake_data->radius = radius;
+ * cake_data->flavor = flavor;
+ * cake_data->frosting = frosting;
+ * cake_data->message = g_strdup (message);
+ * task = g_task_new (self, cancellable, callback, user_data);
+ * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
+ * g_task_run_in_thread (task, bake_cake_thread);
+ * }
+ *
+ * Cake *
+ * baker_bake_cake_finish (Baker *self,
+ * GAsyncResult *result,
+ * GError **error)
+ * {
+ * g_return_val_if_fail (g_task_is_valid (result, self), NULL);
+ *
+ * return g_task_propagate_pointer (G_TASK (result), error);
+ * }
+ * </programlisting>
+ * </example>
+ * </refsect2>
+ * <refsect2>
+ * <title>Adding cancellability to uncancellable tasks</title>
+ * <para>
+ * Finally, g_task_run_in_thread() and g_task_run_in_thread_sync()
+ * can be used to turn an uncancellable operation into a
+ * cancellable one. If you call g_task_set_return_on_cancel(),
+ * passing %TRUE, then if the task's #GCancellable is cancelled,
+ * it will return control back to the caller immediately, while
+ * allowing the task thread to continue running in the background
+ * (and simply discarding its result when it finally does finish).
+ * Provided that the task thread is careful about how it uses
+ * locks and other externally-visible resources, this allows you
+ * to make "GLib-friendly" asynchronous and cancellable
+ * synchronous variants of blocking APIs.
+ * </para>
+ * <example id="gtask-cancellable"><title>g_task_set_return_on_cancel()</title>
+ * <programlisting>
+ * static void
+ * bake_cake_thread (GTask *task,
+ * gpointer source_object,
+ * gpointer task_data,
+ * GCancellable *cancellable)
+ * {
+ * Baker *self = source_object;
+ * CakeData *cake_data = task_data;
+ * Cake *cake;
+ * GError *error = NULL;
+ *
+ * cake = bake_cake (baker, cake_data->radius, cake_data->flavor,
+ * cake_data->frosting, cake_data->message,
+ * &error);
+ * if (error)
+ * {
+ * g_task_return_error (task, error);
+ * return;
+ * }
+ *
+ * /* If the task has already been cancelled, then we don't
+ * * want to add the cake to the cake cache. Likewise, we don't
+ * * want to have the task get cancelled in the middle of
+ * * updating the cache. g_task_set_return_on_cancel() will
+ * * return %TRUE here if it managed to disable return-on-cancel,
+ * * or %FALSE if the task was cancelled before it could.
+ * */
+ * if (g_task_set_return_on_cancel (task, FALSE))
+ * {
+ * /* If the caller cancels at this point, their
+ * * GAsyncReadyCallback won't be invoked until we return,
+ * * so we don't have to worry that this code will run at
+ * * the same time as that code does. But if there were
+ * * other functions that might look at the cake cache,
+ * * then we'd probably need a GMutex here as well.
+ * */
+ * baker_add_cake_to_cache (baker, cake);
+ * g_task_return_pointer (task, cake, g_object_unref);
+ * }
+ * }
+ *
+ * void
+ * baker_bake_cake_async (Baker *self,
+ * guint radius,
+ * CakeFlavor flavor,
+ * CakeFrostingType frosting,
+ * const char *message,
+ * GCancellable *cancellable,
+ * GAsyncReadyCallback callback,
+ * gpointer user_data)
+ * {
+ * CakeData *cake_data;
+ * GTask *task;
+ *
+ * cake_data = g_slice_new (CakeData);
+ * /* ... */
+ *
+ * task = g_task_new (self, cancellable, callback, user_data);
+ * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
+ * g_task_set_return_on_cancel (task, TRUE);
+ * g_task_run_in_thread (task, bake_cake_thread);
+ * }
+ *
+ * Cake *
+ * baker_bake_cake_sync (Baker *self,
+ * guint radius,
+ * CakeFlavor flavor,
+ * CakeFrostingType frosting,
+ * const char *message,
+ * GCancellable *cancellable,
+ * GError **error)
+ * {
+ * CakeData *cake_data;
+ * GTask *task;
+ * Cake *cake;
+ *
+ * cake_data = g_slice_new (CakeData);
+ * /* ... */
+ *
+ * task = g_task_new (self, cancellable, NULL, NULL);
+ * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
+ * g_task_set_return_on_cancel (task, TRUE);
+ * g_task_run_in_thread_sync (task, bake_cake_thread);
+ *
+ * cake = g_task_propagate_pointer (task, error);
+ * g_object_unref (task);
+ * return cake;
+ * }
+ * </programlisting>
+ * </example>
+ * </refsect2>
+ * <refsect2>
+ * <title>Porting from <literal>GSimpleAsyncResult</literal></title>
+ * <para>
+ * #GTask's API attempts to be simpler than #GSimpleAsyncResult's
+ * in several ways:
+ * </para>
+ * <itemizedlist>
+ * <listitem><para>
+ * You can save task-specific data with g_task_set_task_data(), and
+ * retrieve it later with g_task_get_task_data(). This replaces the
+ * abuse of g_simple_async_result_set_op_res_gpointer() for the same
+ * purpose with #GSimpleAsyncResult.
+ * </para></listitem>
+ * <listitem><para>
+ * In addition to the task data, #GTask also keeps track of the
+ * <link linkend="io-priority">priority</link>, #GCancellable, and
+ * #GMainContext associated with the task, so tasks that consist of
+ * a chain of simpler asynchronous operations will have easy access
+ * to those values when starting each sub-task.
+ * </para></listitem>
+ * <listitem><para>
+ * g_task_return_error_if_cancelled() provides simplified
+ * handling for cancellation. In addition, cancellation
+ * overrides any other #GTask return value by default, like
+ * #GSimpleAsyncResult does when
+ * g_simple_async_result_set_check_cancellable() is called.
+ * (You can use g_task_set_check_cancellable() to turn off that
+ * behavior.) On the other hand, g_task_run_in_thread()
+ * guarantees that it will always run your
+ * <literal>task_func</literal>, even if the task's #GCancellable
+ * is already cancelled before the task gets a chance to run;
+ * you can start your <literal>task_func</literal> with a
+ * g_task_return_error_if_cancelled() check if you need the
+ * old behavior.
+ * </para></listitem>
+ * <listitem><para>
+ * The "return" methods (eg, g_task_return_pointer())
+ * automatically cause the task to be "completed" as well, and
+ * there is no need to worry about the "complete" vs "complete
+ * in idle" distinction. (#GTask automatically figures out
+ * whether the task's callback can be invoked directly, or
+ * if it needs to be sent to another #GMainContext, or delayed
+ * until the next iteration of the current #GMainContext.)
+ * </para></listitem>
+ * <listitem><para>
+ * The "finish" functions for #GTask-based operations are generally
+ * much simpler than #GSimpleAsyncResult ones, normally consisting
+ * of only a single call to g_task_propagate_pointer() or the like.
+ * Since g_task_propagate_pointer() "steals" the return value from
+ * the #GTask, it is not necessary to juggle pointers around to
+ * prevent it from being freed twice.
+ * </para></listitem>
+ * <listitem><para>
+ * With #GSimpleAsyncResult, it was common to call
+ * g_simple_async_result_propagate_error() from the
+ * <literal>_finish()</literal> wrapper function, and have
+ * virtual method implementations only deal with successful
+ * returns. This behavior is deprecated, because it makes it
+ * difficult for a subclass to chain to a parent class's async
+ * methods. Instead, the wrapper function should just be a
+ * simple wrapper, and the virtual method should call an
+ * appropriate <literal>g_task_propagate_</literal> function.
+ * Note that wrapper methods can now use
+ * g_async_result_legacy_propagate_error() to do old-style
+ * #GSimpleAsyncResult error-returning behavior, and
+ * g_async_result_is_tagged() to check if a result is tagged as
+ * having come from the <literal>_async()</literal> wrapper
+ * function (for "short-circuit" results, such as when passing
+ * 0 to g_input_stream_read_async()).
+ * </para></listitem>
+ * </itemizedlist>
+ * </refsect2>
+ */
+
+
+/**
* SECTION:gtcpconnection
* @title: GTcpConnection
* @short_description: A TCP GSocketConnection
@@ -6729,7 +7292,8 @@
* @short_description: D-Bus testing helper
* @include: gio/gio.h
*
- * Helper to test D-Bus code wihtout messing up with user' session bus.
+ * A helper class for testing code which uses D-Bus without touching the user's
+ * session bus.
*/
@@ -10117,8 +10681,6 @@
*
* Creates a new #GApplication instance.
*
- * This function calls g_type_init() for you.
- *
* If non-%NULL, the application id must be valid. See
* g_application_id_is_valid().
*
@@ -14209,7 +14771,7 @@
* @interface_: A #GDBusInterfaceSkeleton.
* @connection: A #GDBusConnection.
*
- * Checks if @interface_ is export on @connection.
+ * Checks if @interface_ is exported on @connection.
*
* Returns: %TRUE if @interface_ is exported on @connection, %FALSE otherwise.
* Since: 2.32
@@ -17918,7 +18480,7 @@
* g_file_enumerator_next_files_async:
* @enumerator: a #GFileEnumerator.
* @num_files: the number of file info objects to request
- * @io_priority: the <link linkend="gioscheduler">io priority</link> of the request.
+ * @io_priority: the <link linkend="io-priority">io priority</link> of the request.
* @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
* @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
* @user_data: (closure): the data to pass to callback function
@@ -22030,6 +22592,8 @@
*
* A job is cancellable if a #GCancellable was passed into
* g_io_scheduler_push_job().
+ *
+ * Deprecated: You should never call this function, since you don't know how other libraries in your program might be making use of gioscheduler.
*/
@@ -22045,6 +22609,7 @@
* blocking the I/O job).
*
* Returns: The return value of @func
+ * Deprecated: Use g_main_context_invoke().
*/
@@ -22064,6 +22629,8 @@
* on to this function you have to ensure that it is not freed before
* @func is called, either by passing %NULL as @notify to
* g_io_scheduler_push_job() or by using refcounting for @user_data.
+ *
+ * Deprecated: Use g_main_context_invoke().
*/
@@ -22072,7 +22639,7 @@
* @job_func: a #GIOSchedulerJobFunc.
* @user_data: data to pass to @job_func
* @notify: (allow-none): a #GDestroyNotify for @user_data, or %NULL
- * @io_priority: the <link linkend="gioscheduler">I/O priority</link> of the request.
+ * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
* @cancellable: optional #GCancellable object, %NULL to ignore.
*
* Schedules the I/O job to run in another thread.
@@ -22083,6 +22650,8 @@
* If @cancellable is not %NULL, it can be used to cancel the I/O job
* by calling g_cancellable_cancel() or by calling
* g_io_scheduler_cancel_all_jobs().
+ *
+ * Deprecated: use #GThreadPool or g_task_run_in_thread()
*/
@@ -30256,6 +30825,528 @@
/**
+ * g_task_attach_source:
+ * @task: a #GTask
+ * @source: the source to attach
+ * @callback: the callback to invoke when @source triggers
+ *
+ * A utility function for dealing with async operations where you need
+ * to wait for a #GSource to trigger. Attaches @source to @task's
+ * #GMainContext with @task's <link
+ * linkend="io-priority">priority</link>, and sets @source's callback
+ * to @callback, with @task as the callback's
+ * <literal>user_data</literal>.
+ *
+ * This takes a reference on @task until @source is destroyed.
+ *
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_get_cancellable:
+ * @task: a #GTask
+ *
+ * Gets @task's #GCancellable
+ *
+ * Returns: (transfer none): @task's #GCancellable
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_get_check_cancellable:
+ * @task: the #GTask
+ *
+ * Gets @task's check-cancellable flag. See
+ * g_task_set_check_cancellable() for more details.
+ *
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_get_context:
+ * @task: a #GTask
+ *
+ * Gets the #GMainContext that @task will return its result in (that
+ * is, the context that was the <link
+ * linkend="g-main-context-push-thread-default">thread-default main
+ * context</link> at the point when @task was created).
+ *
+ * This will always return a non-%NULL value, even if the task's
+ * context is the default #GMainContext.
+ *
+ * Returns: (transfer none): @task's #GMainContext
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_get_priority:
+ * @task: a #GTask
+ *
+ * Gets @task's priority
+ *
+ * Returns: @task's priority
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_get_return_on_cancel:
+ * @task: the #GTask
+ *
+ * Gets @task's return-on-cancel flag. See
+ * g_task_set_return_on_cancel() for more details.
+ *
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_get_source_object:
+ * @task: a #GTask
+ *
+ * Gets the source object from @task. Like
+ * g_async_result_get_source_object(), but does not ref the object.
+ *
+ * Returns: (transfer none): @task's source object, or %NULL
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_get_source_tag:
+ * @task: a #GTask
+ *
+ * Gets @task's source tag. See g_task_set_source_tag().
+ *
+ * Returns: (transfer none): @task's source tag
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_get_task_data:
+ * @task: a #GTask
+ *
+ * Gets @task's <literal>task_data</literal>.
+ *
+ * Returns: (transfer none): @task's <literal>task_data</literal>.
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_had_error:
+ * @task: a #GTask.
+ *
+ * Tests if @task resulted in an error.
+ *
+ * Returns: %TRUE if the task resulted in an error, %FALSE otherwise.
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_is_valid:
+ * @result: (type Gio.AsyncResult): A #GAsyncResult
+ * @source_object: (allow-none): the source object expected to be associated with the task
+ *
+ * Checks that @result is a #GTask, and that @source_object is its
+ * source object (or that @source_object is %NULL and @result has no
+ * source object). This can be used in g_return_if_fail() checks.
+ *
+ * Returns: %TRUE if @result and @source_object are valid, %FALSE if not
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_new:
+ * @source_object: (allow-none): the #GObject that owns this task, or %NULL.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @callback: (scope async): a #GAsyncReadyCallback.
+ * @callback_data: (closure): user data passed to @callback.
+ *
+ * Creates a #GTask acting on @source_object, which will eventually be
+ * used to invoke @callback in the current <link
+ * linkend="g-main-context-push-thread-default">thread-default main
+ * context</link>.
+ *
+ * Call this in the "start" method of your asynchronous method, and
+ * pass the #GTask around throughout the asynchronous operation. You
+ * can use g_task_set_task_data() to attach task-specific data to the
+ * object, which you can retrieve later via g_task_get_task_data().
+ *
+ * By default, if @cancellable is cancelled, then the return value of
+ * the task will always be %G_IO_ERROR_CANCELLED, even if the task had
+ * already completed before the cancellation. This allows for
+ * simplified handling in cases where cancellation may imply that
+ * other objects that the task depends on have been destroyed. If you
+ * do not want this behavior, you can use
+ * g_task_set_check_cancellable() to change it.
+ *
+ * Returns: a #GTask.
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_propagate_boolean:
+ * @task: a #GTask.
+ * @error: return location for a #GError
+ *
+ * Gets the result of @task as a #gboolean.
+ *
+ * If the task resulted in an error, or was cancelled, then this will
+ * instead return %FALSE and set @error.
+ *
+ * Since this method transfers ownership of the return value (or
+ * error) to the caller, you may only call it once.
+ *
+ * Returns: the task result, or %FALSE on error
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_propagate_int:
+ * @task: a #GTask.
+ * @error: return location for a #GError
+ *
+ * Gets the result of @task as an integer (#gssize).
+ *
+ * If the task resulted in an error, or was cancelled, then this will
+ * instead return -1 and set @error.
+ *
+ * Since this method transfers ownership of the return value (or
+ * error) to the caller, you may only call it once.
+ *
+ * Returns: the task result, or -1 on error
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_propagate_pointer:
+ * @task: a #GTask
+ * @error: return location for a #GError
+ *
+ * Gets the result of @task as a pointer, and transfers ownership
+ * of that value to the caller.
+ *
+ * If the task resulted in an error, or was cancelled, then this will
+ * instead return %NULL and set @error.
+ *
+ * Since this method transfers ownership of the return value (or
+ * error) to the caller, you may only call it once.
+ *
+ * Returns: (transfer full): the task result, or %NULL on error
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_report_error:
+ * @source_object: (allow-none): the #GObject that owns this task, or %NULL.
+ * @callback: (scope async): a #GAsyncReadyCallback.
+ * @callback_data: (closure): user data passed to @callback.
+ * @source_tag: an opaque pointer indicating the source of this task
+ * @error: (transfer full): error to report
+ *
+ * Creates a #GTask and then immediately calls g_task_return_error()
+ * on it. Use this in the wrapper function of an asynchronous method
+ * when you want to avoid even calling the virtual method. You can
+ * then use g_async_result_is_tagged() in the finish method wrapper to
+ * check if the result there is tagged as having been created by the
+ * wrapper method, and deal with it appropriately if so.
+ *
+ * See also g_task_report_new_error().
+ *
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_report_new_error:
+ * @source_object: (allow-none): the #GObject that owns this task, or %NULL.
+ * @callback: (scope async): a #GAsyncReadyCallback.
+ * @callback_data: (closure): user data passed to @callback.
+ * @source_tag: an opaque pointer indicating the source of this task
+ * @domain: a #GQuark.
+ * @code: an error code.
+ * @format: a string with format characters.
+ * @...: a list of values to insert into @format.
+ *
+ * Creates a #GTask and then immediately calls
+ * g_task_return_new_error() on it. Use this in the wrapper function
+ * of an asynchronous method when you want to avoid even calling the
+ * virtual method. You can then use g_async_result_is_tagged() in the
+ * finish method wrapper to check if the result there is tagged as
+ * having been created by the wrapper method, and deal with it
+ * appropriately if so.
+ *
+ * See also g_task_report_error().
+ *
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_return_boolean:
+ * @task: a #GTask.
+ * @result: the #gboolean result of a task function.
+ *
+ * Sets @task's result to @result and completes the task (see
+ * g_task_return_pointer() for more discussion of exactly what this
+ * means).
+ *
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_return_error:
+ * @task: a #GTask.
+ * @error: (transfer full): the #GError result of a task function.
+ *
+ * Sets @task's result to @error (which @task assumes ownership of)
+ * and completes the task (see g_task_return_pointer() for more
+ * discussion of exactly what this means).
+ *
+ * Note that since the task takes ownership of @error, and since the
+ * task may be completed before returning from g_task_return_error(),
+ * you cannot assume that @error is still valid after calling this.
+ * Call g_error_copy() on the error if you need to keep a local copy
+ * as well.
+ *
+ * See also g_task_return_new_error().
+ *
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_return_error_if_cancelled:
+ * @task: a #GTask
+ *
+ * Checks if @task's #GCancellable has been cancelled, and if so, sets
+ * @task's error accordingly and completes the task (see
+ * g_task_return_pointer() for more discussion of exactly what this
+ * means).
+ *
+ * Returns: %TRUE if @task has been cancelled, %FALSE if not
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_return_int:
+ * @task: a #GTask.
+ * @result: the integer (#gssize) result of a task function.
+ *
+ * Sets @task's result to @result and completes the task (see
+ * g_task_return_pointer() for more discussion of exactly what this
+ * means).
+ *
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_return_new_error:
+ * @task: a #GTask.
+ * @domain: a #GQuark.
+ * @code: an error code.
+ * @format: a string with format characters.
+ * @...: a list of values to insert into @format.
+ *
+ * Sets @task's result to a new #GError created from @domain, @code,
+ * @format, and the remaining arguments, and completes the task (see
+ * g_task_return_pointer() for more discussion of exactly what this
+ * means).
+ *
+ * See also g_task_return_error().
+ *
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_return_pointer:
+ * @task: a #GTask
+ * @result: (allow-none) (transfer full): the pointer result of a task function
+ * @result_destroy: (allow-none): a #GDestroyNotify function.
+ *
+ * Sets @task's result to @result and completes the task. If @result
+ * is not %NULL, then @result_destroy will be used to free @result if
+ * the caller does not take ownership of it with
+ * g_task_propagate_pointer().
+ *
+ * "Completes the task" means that for an ordinary asynchronous task
+ * it will either invoke the task's callback, or else queue that
+ * callback to be invoked in the proper #GMainContext, or in the next
+ * iteration of the current #GMainContext. For a task run via
+ * g_task_run_in_thread() or g_task_run_in_thread_sync(), calling this
+ * method will save @result to be returned to the caller later, but
+ * the task will not actually be completed until the #GTaskThreadFunc
+ * exits.
+ *
+ * Note that since the task may be completed before returning from
+ * g_task_return_pointer(), you cannot assume that @result is still
+ * valid after calling this, unless you are still holding another
+ * reference on it.
+ *
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_run_in_thread:
+ * @task: a #GTask
+ * @task_func: a #GTaskThreadFunc
+ *
+ * Runs @task_func in another thread. When @task_func returns, @task's
+ * #GAsyncReadyCallback will be invoked in @task's #GMainContext.
+ *
+ * This takes a ref on @task until the task completes.
+ *
+ * See #GTaskThreadFunc for more details about how @task_func is handled.
+ *
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_run_in_thread_sync:
+ * @task: a #GTask
+ * @task_func: a #GTaskThreadFunc
+ *
+ * Runs @task_func in another thread, and waits for it to return or be
+ * cancelled. You can use g_task_propagate_pointer(), etc, afterward
+ * to get the result of @task_func.
+ *
+ * See #GTaskThreadFunc for more details about how @task_func is handled.
+ *
+ * Normally this is used with tasks created with a %NULL
+ * <literal>callback</literal>, but note that even if the task does
+ * have a callback, it will not be invoked when @task_func returns.
+ *
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_set_check_cancellable:
+ * @task: the #GTask
+ * @check_cancellable: whether #GTask will check the state of its #GCancellable for you.
+ *
+ * Sets or clears @task's check-cancellable flag. If this is %TRUE
+ * (the default), then g_task_propagate_pointer(), etc, and
+ * g_task_had_error() will check the task's #GCancellable first, and
+ * if it has been cancelled, then they will consider the task to have
+ * returned an "Operation was cancelled" error
+ * (%G_IO_ERROR_CANCELLED), regardless of any other error or return
+ * value the task may have had.
+ *
+ * If @check_cancellable is %FALSE, then the #GTask will not check the
+ * cancellable itself, and it is up to @task's owner to do this (eg,
+ * via g_task_return_error_if_cancelled()).
+ *
+ * If you are using g_task_set_return_on_cancel() as well, then
+ * you must leave check-cancellable set %TRUE.
+ *
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_set_priority:
+ * @task: the #GTask
+ * @priority: the <link linkend="io-priority">priority</link> of the request.
+ *
+ * Sets @task's priority. If you do not call this, it will default to
+ * %G_PRIORITY_DEFAULT.
+ *
+ * This will affect the priority of #GSources created with
+ * g_task_attach_source() and the scheduling of tasks run in threads,
+ * and can also be explicitly retrieved later via
+ * g_task_get_priority().
+ *
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_set_return_on_cancel:
+ * @task: the #GTask
+ * @return_on_cancel: whether the task returns automatically when it is cancelled.
+ *
+ * Sets or clears @task's return-on-cancel flag. This is only
+ * meaningful for tasks run via g_task_run_in_thread() or
+ * g_task_run_in_thread_sync().
+ *
+ * If @return_on_cancel is %TRUE, then cancelling @task's
+ * #GCancellable will immediately cause it to return, as though the
+ * task's #GTaskThreadFunc had called
+ * g_task_return_error_if_cancelled() and then returned.
+ *
+ * This allows you to create a cancellable wrapper around an
+ * uninterruptable function. The #GTaskThreadFunc just needs to be
+ * careful that it does not modify any externally-visible state after
+ * it has been cancelled. To do that, the thread should call
+ * g_task_set_return_on_cancel() again to (atomically) set
+ * return-on-cancel %FALSE before making externally-visible changes;
+ * if the task gets cancelled before the return-on-cancel flag could
+ * be changed, g_task_set_return_on_cancel() will indicate this by
+ * returning %FALSE.
+ *
+ * You can disable and re-enable this flag multiple times if you wish.
+ * If the task's #GCancellable is cancelled while return-on-cancel is
+ * %FALSE, then calling g_task_set_return_on_cancel() to set it %TRUE
+ * again will cause the task to be cancelled at that point.
+ *
+ * If the task's #GCancellable is already cancelled before you call
+ * g_task_run_in_thread()/g_task_run_in_thread_sync(), then the
+ * #GTaskThreadFunc will still be run (for consistency), but the task
+ * will also be completed right away.
+ *
+ * Returns: %TRUE if @task's return-on-cancel flag was changed to match @return_on_cancel. %FALSE if @task has already been cancelled.
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_set_source_tag:
+ * @task: the #GTask
+ * @source_tag: an opaque pointer indicating the source of this task
+ *
+ * Sets @task's source tag. You can use this to tag a task return
+ * value with a particular pointer (usually a pointer to the function
+ * doing the tagging) and then later check it using
+ * g_task_get_source_tag() (or g_async_result_is_tagged()) in the
+ * task's "finish" function, to figure out if the response came from a
+ * particular place.
+ *
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_set_task_data:
+ * @task: the #GTask
+ * @task_data: (allow-none): task-specific data
+ * @task_data_destroy: (allow-none): #GDestroyNotify for @task_data
+ *
+ * Sets @task's task data (freeing the existing task data, if any).
+ *
+ * Since: 2.36
+ */
+
+
+/**
* g_tcp_connection_get_graceful_disconnect:
* @connection: a #GTcpConnection
*
@@ -30392,7 +31483,7 @@
* @self: a #GTestDBus
*
* Start a dbus-daemon instance and set DBUS_SESSION_BUS_ADDRESS. After this
- * call, it is safe for unit tests to start sending messages on the session bug.
+ * call, it is safe for unit tests to start sending messages on the session bus.
*
* If this function is called from setup callback of g_test_add(),
* g_test_dbus_down() must be called in its teardown callback.
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index 90ec000..85399ca 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -6434,50 +6434,14 @@
*
* To destroy a #GHashTable use g_hash_table_destroy().
*
- * <example>
- * <title>Using a GHashTable as a set</title>
- * <para>
- * A common use-case for hash tables is to store information about
- * a set of keys, without associating any particular value with each
+ * A common use-case for hash tables is to store information about a
+ * set of keys, without associating any particular value with each
* key. GHashTable optimizes one way of doing so: If you store only
* key-value pairs where key == value, then GHashTable does not
* allocate memory to store the values, which can be a considerable
- * space saving, if your set is large.
- * </para>
- * <programlisting>
- * GHashTable *
- * set_new (GHashFunc hash_func,
- * GEqualFunc equal_func,
- * GDestroyNotify destroy)
- * {
- * return g_hash_table_new_full (hash_func, equal_func, destroy, NULL);
- * }
- *
- * void
- * set_add (GHashTable *set,
- * gpointer element)
- * {
- * g_hash_table_replace (set, element, element);
- * }
- *
- * gboolean
- * set_contains (GHashTable *set,
- * gpointer element)
- * {
- * return g_hash_table_lookup_extended (set, element, NULL, NULL);
- * }
- *
- * gboolean
- * set_remove (GHashTable *set,
- * gpointer element)
- * {
- * return g_hash_table_remove (set, element);
- * }
- * </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.
+ * space saving, if your set is large. The functions
+ * g_hash_table_add() and g_hash_table_contains() are designed to be
+ * used when using #GHashTable this way.
*/
@@ -25975,7 +25939,7 @@
* gracefully by sorting it before non-%NULL strings.
* Comparing two %NULL pointers returns 0.
*
- * Returns: -1, 0 or 1, if @str1 is <, == or > than @str2.
+ * Returns: an integer less than, equal to, or greater than zero, if @str1 is <, == or > than @str2.
* Since: 2.16
*/
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index 81e65a3..755f4c2 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -328,8 +328,6 @@
* GValue b = G_VALUE_INIT;
* const gchar *message;
*
- * g_type_init ();
- *
* /* The GValue starts empty */
* g_assert (!G_VALUE_HOLDS_STRING (&a));
*
@@ -391,9 +389,7 @@
*
* The GType API is the foundation of the GObject system. It provides the
* facilities for registering and managing all fundamental data types,
- * user-defined object and interface types. Before using any GType
- * or GObject functions, g_type_init() must be called to initialize the
- * type system.
+ * user-defined object and interface types.
*
* For type creation and registration purposes, all types fall into one of
* two categories: static or dynamic. Static types are never loaded or
@@ -3591,24 +3587,10 @@
* ensures that the @gobject stays alive during the call to @c_handler
* by temporarily adding a reference count to @gobject.
*
- * Note that there is a bug in GObject that makes this function
- * much less useful than it might seem otherwise. Once @gobject is
- * disposed, the callback will no longer be called, but, the signal
- * handler is <emphasis>not</emphasis> currently disconnected. If the
- * @instance is itself being freed at the same time than this doesn't
- * matter, since the signal will automatically be removed, but
- * if @instance persists, then the signal handler will leak. You
- * should not remove the signal yourself because in a future versions of
- * GObject, the handler <emphasis>will</emphasis> automatically
- * be disconnected.
- *
- * It's possible to work around this problem in a way that will
- * continue to work with future versions of GObject by checking
- * that the signal handler is still connected before disconnected it:
- * <informalexample><programlisting>
- * if (g_signal_handler_is_connected (instance, id))
- * g_signal_handler_disconnect (instance, id);
- * </programlisting></informalexample>
+ * When the object is destroyed the signal handler will be automatically
+ * disconnected. Note that this is not currently threadsafe (ie:
+ * emitting a signal while @gobject is being destroyed in another thread
+ * is not safe).
*
* Returns: the handler id.
*/
@@ -4594,17 +4576,11 @@
/**
* g_type_init:
*
- * Prior to any use of the type system, g_type_init() has to be called
- * to initialize the type system and assorted other code portions
- * (such as the various fundamental type implementations or the signal
- * system).
- *
- * This function is idempotent: If you call it multiple times, all but
- * the first calls will be silently ignored.
+ * This function used to initialise the type system. Since GLib 2.36,
+ * the type system is initialised automatically and this function does
+ * nothing.
*
- * There is no way to undo the effect of g_type_init().
- *
- * Since version 2.24 this also initializes the thread system
+ * Deprecated: 2.36: the type system is now initialised automatically
*/
@@ -4612,9 +4588,14 @@
* g_type_init_with_debug_flags:
* @debug_flags: Bitwise combination of #GTypeDebugFlags values for debugging purposes.
*
- * Similar to g_type_init(), but additionally sets debug flags.
+ * This function used to initialise the type system with debugging
+ * flags. Since GLib 2.36, the type system is initialised automatically
+ * and this function does nothing.
+ *
+ * If you need to enable debugging features, use the GOBJECT_DEBUG
+ * environment variable.
*
- * This function is idempotent.
+ * Deprecated: 2.36: the type system is now initialised automatically
*/
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
