* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General
- * Public License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
- * Boston, MA 02111-1307, USA.
+ * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
*/
#include "config.h"
/**
* SECTION:gtask
- * @short_description: Cancellable synchronous or asynchronous task and result
+ * @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 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>
+ * A #GTask represents and manages a cancellable "task".
+ *
+ * ## Asynchronous operations
+ *
+ * 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 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.
+ *
+ * Here is an example for using GTask as a GAsyncResult:
+ * |[<!-- language="C" -->
* typedef struct {
* CakeFrostingType frosting;
* char *message;
* 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() takes ownership of error
* g_task_return_error (task, error);
* 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 */
+ * // _baker_get_cached_cake() returns a reffed cake
* g_task_return_pointer (task, cake, g_object_unref);
* g_object_unref (task);
* return;
*
* 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>
+ * ]|
+ *
+ * ## Chained asynchronous operations
+ *
+ * #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 [I/O priority][io-priority]
+ * 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).
+ *
+ * Here is an example for chained asynchronous operations:
+ * |[<!-- language="C" -->
* typedef struct {
* Cake *cake;
* CakeFrostingType frosting;
* return;
* }
*
- * /* baking_data_free() will drop its ref on the cake, so
- * * we have to take another here to give to the caller.
- * */
+ * // 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);
* }
*
* bd->cake = cake;
*
- * /* Bail out now if the user has already cancelled */
+ * // Bail out now if the user has already cancelled
* if (g_task_return_error_if_cancelled (task))
* {
* g_object_unref (task);
* 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.
- * */
+ * // 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);
*
* 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>
+ * ]|
+ *
+ * ## Asynchronous operations from synchronous ones
+ *
+ * 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.
+ *
+ * Running a task in a thread:
+ * |[<!-- language="C" -->
* typedef struct {
* guint radius;
* CakeFlavor flavor;
* 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);
+ * g_object_unref (task);
* }
*
* Cake *
*
* 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>
+ * ]|
+ *
+ * ## Adding cancellability to uncancellable tasks
+ *
+ * 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.
+ *
+ * Cancelling a task:
+ * |[<!-- language="C" -->
* static void
* bake_cake_thread (GTask *task,
* gpointer source_object,
* 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 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.
- * */
+ * // 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);
* }
* 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);
* 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_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>
+ * ]|
+ *
+ * ## Porting from GSimpleAsyncResult
+ *
+ * #GTask's API attempts to be simpler than #GSimpleAsyncResult's
+ * in several ways:
+ * - 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.
+ * - In addition to the task data, #GTask also keeps track of the
+ * [priority][io-priority], #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.
+ * - 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
+ * `task_func`, even if the task's #GCancellable
+ * is already cancelled before the task gets a chance to run;
+ * you can start your `task_func` with a
+ * g_task_return_error_if_cancelled() check if you need the
+ * old behavior.
+ * - 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.)
+ * - 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.
+ * - With #GSimpleAsyncResult, it was common to call
+ * g_simple_async_result_propagate_error() from the
+ * `_finish()` 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 `g_task_propagate_` 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 `_async()` wrapper
+ * function (for "short-circuit" results, such as when passing
+ * 0 to g_input_stream_read_async()).
*/
/**
GDestroyNotify task_data_destroy;
GMainContext *context;
- guint64 creation_time;
+ gint64 creation_time;
gint priority;
GCancellable *cancellable;
gboolean check_cancellable;
* @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>.
+ * used to invoke @callback in the current
+ * [thread-default main context][g-main-context-push-thread-default].
*
* Call this in the "start" method of your asynchronous method, and
* pass the #GTask around throughout the asynchronous operation. You
/**
* g_task_set_priority:
* @task: the #GTask
- * @priority: the <link linkend="io-priority">priority</link>
- * of the request.
+ * @priority: the [priority][io-priority] of the request
*
* Sets @task's priority. If you do not call this, it will default to
* %G_PRIORITY_DEFAULT.
* g_task_get_task_data:
* @task: a #GTask
*
- * Gets @task's <literal>task_data</literal>.
+ * Gets @task's `task_data`.
*
- * Returns: (transfer none): @task's <literal>task_data</literal>.
+ * Returns: (transfer none): @task's `task_data`.
*
* Since: 2.36
*/
* @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).
+ * is, the context that was the
+ * [thread-default main context][g-main-context-push-thread-default]
+ * 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.
*
* Gets @task's source tag. See g_task_set_source_tag().
*
- * Return value: (transfer none): @task's source tag
+ * Returns: (transfer none): @task's source tag
*
* Since: 2.36
*/
/* Otherwise, complete in the next iteration */
source = g_idle_source_new ();
g_task_attach_source (task, source, complete_in_idle_cb);
+ g_source_set_name (source, "[gio] complete_in_idle_cb");
g_source_unref (source);
}
* 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.
+ * #GTaskThreadFunc returns, not when it calls a
+ * `g_task_return_` function.
*
* Since: 2.36
*/
return;
}
+ /* This introduces a reference count loop between the GTask and
+ * GCancellable, but is necessary to avoid a race on finalising the GTask
+ * between task_thread_cancelled() (in one thread) and
+ * g_task_thread_complete() (in another).
+ *
+ * Accordingly, the signal handler *must* be removed once the task has
+ * completed.
+ */
g_signal_connect_data (task->cancellable, "cancelled",
G_CALLBACK (task_thread_cancelled),
g_object_ref (task),
task_thread_cancelled_disconnect_notify, 0);
}
- g_thread_pool_push (task_pool, g_object_ref (task), &task->error);
- if (task->error)
- task->thread_complete = TRUE;
- else if (g_private_get (&task_private))
+ g_thread_pool_push (task_pool, g_object_ref (task), NULL);
+ if (g_private_get (&task_private))
{
/* This thread is being spawned from another GTask thread, so
* bump up max-threads so we don't starve.
* 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
+ * `callback`, but note that even if the task does
* have a callback, it will not be invoked when @task_func returns.
*
* Since: 2.36
*
* 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>.
+ * #GMainContext with @task's [priority][io-priority], and sets @source's
+ * callback to @callback, with @task as the callback's `user_data`.
*
* This takes a reference on @task until @source is destroyed.
*
* g_task_return_pointer() for more discussion of exactly what this
* means).
*
- * Return value: %TRUE if @task has been cancelled, %FALSE if not
+ * Returns: %TRUE if @task has been cancelled, %FALSE if not
*
* Since: 2.36
*/
* source object (or that @source_object is %NULL and @result has no
* source object). This can be used in g_return_if_fail() checks.
*
- * Return value: %TRUE if @result and @source_object are valid, %FALSE
+ * Returns: %TRUE if @result and @source_object are valid, %FALSE
* if not
*
* Since: 2.36