diff options
author | Rico Tzschichholz <ricotz@t-online.de> | 2012-10-17 07:58:03 +0200 |
---|---|---|
committer | Rico Tzschichholz <ricotz@t-online.de> | 2012-10-17 07:58:03 +0200 |
commit | 72472408669305a2056d0a83c73a3dc186056067 (patch) | |
tree | a33bd4da41d4df8655e70989fcbe359018b07498 /gir/gio-2.0.c | |
parent | 448230b381a6ba0394962ca73f35af563b5de4c9 (diff) | |
download | gobject-introspection-72472408669305a2056d0a83c73a3dc186056067.tar.gz |
Update annotations from glib git
Diffstat (limited to 'gir/gio-2.0.c')
-rw-r--r-- | gir/gio-2.0.c | 1181 |
1 files changed, 1136 insertions, 45 deletions
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index 3f3b2222..a3eb8b10 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. |