mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-07-07 02:59:39 +02:00
GTask: convert long desc to markdown
Use markdown sections and lists here.
This commit is contained in:
Matthias Clasen
parent
ed2bb95330
commit
ba307a0c52
80
gio/gtask.c
80
gio/gtask.c
@ -30,12 +30,10 @@
|
||||
* @include: gio/gio.h
|
||||
* @see_also: #GAsyncResult
|
||||
*
|
||||
* <para>
|
||||
* A #GTask represents and manages a cancellable "task".
|
||||
* </para>
|
||||
* <refsect2>
|
||||
* <title>Asynchronous operations</title>
|
||||
* <para>
|
||||
*
|
||||
* ## 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
|
||||
@ -50,7 +48,7 @@
|
||||
* 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>
|
||||
*
|
||||
* Here is an example for using GTask as a GAsyncResult:
|
||||
* |[
|
||||
* typedef struct {
|
||||
@ -145,10 +143,9 @@
|
||||
* return g_task_propagate_pointer (G_TASK (result), error);
|
||||
* }
|
||||
* ]|
|
||||
* </refsect2>
|
||||
* <refsect2>
|
||||
* <title>Chained asynchronous operations</title>
|
||||
* <para>
|
||||
*
|
||||
* ## 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
|
||||
@ -159,8 +156,7 @@
|
||||
* g_task_attach_source() simplifies the case of waiting for a
|
||||
* source to fire (automatically using the correct #GMainContext
|
||||
* and priority).
|
||||
* </para>
|
||||
* <para>
|
||||
*
|
||||
* Here is an example for chained asynchronous operations:
|
||||
* |[
|
||||
* typedef struct {
|
||||
@ -288,17 +284,14 @@
|
||||
* return g_task_propagate_pointer (G_TASK (result), error);
|
||||
* }
|
||||
* ]|
|
||||
* </para>
|
||||
* </refsect2>
|
||||
* <refsect2>
|
||||
* <title>Asynchronous operations from synchronous ones</title>
|
||||
* <para>
|
||||
*
|
||||
* ## 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.
|
||||
* </para>
|
||||
* <para>
|
||||
*
|
||||
* Running a task in a thread:
|
||||
* |[
|
||||
* typedef struct {
|
||||
@ -368,11 +361,9 @@
|
||||
* return g_task_propagate_pointer (G_TASK (result), error);
|
||||
* }
|
||||
* ]|
|
||||
* </para>
|
||||
* </refsect2>
|
||||
* <refsect2>
|
||||
* <title>Adding cancellability to uncancellable tasks</title>
|
||||
* <para>
|
||||
*
|
||||
* ## 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(),
|
||||
@ -384,8 +375,7 @@
|
||||
* locks and other externally-visible resources, this allows you
|
||||
* to make "GLib-friendly" asynchronous and cancellable
|
||||
* synchronous variants of blocking APIs.
|
||||
* </para>
|
||||
* <para>
|
||||
*
|
||||
* Cancelling a task:
|
||||
* |[
|
||||
* static void
|
||||
@ -439,7 +429,7 @@
|
||||
* GAsyncReadyCallback callback,
|
||||
* gpointer user_data)
|
||||
* {
|
||||
* CakeData *cake_data;
|
||||
J* CakeData *cake_data;
|
||||
* GTask *task;
|
||||
*
|
||||
* cake_data = g_slice_new (CakeData);
|
||||
@ -477,30 +467,21 @@
|
||||
* return cake;
|
||||
* }
|
||||
* ]|
|
||||
* </para>
|
||||
* </refsect2>
|
||||
* <refsect2>
|
||||
* <title>Porting from <literal>GSimpleAsyncResult</literal></title>
|
||||
* <para>
|
||||
*
|
||||
* ## Porting from GSimpleAsyncResult
|
||||
*
|
||||
* #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
|
||||
* - 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
|
||||
* - 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
|
||||
* - 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
|
||||
@ -513,26 +494,20 @@
|
||||
* 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())
|
||||
* - 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
|
||||
* - 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
|
||||
* - 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
|
||||
@ -548,9 +523,6 @@
|
||||
* 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>
|
||||
*/
|
||||
|
||||
/**
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user