| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> | |
| <html> | |
| <head> | |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> | |
| <title>GTask: GIO Reference Manual</title> | |
| <meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> | |
| <link rel="home" href="index.html" title="GIO Reference Manual"> | |
| <link rel="up" href="async.html" title="Asynchronous I/O"> | |
| <link rel="prev" href="GAsyncResult.html" title="GAsyncResult"> | |
| <link rel="next" href="gio-GIOScheduler.html" title="GIOScheduler"> | |
| <meta name="generator" content="GTK-Doc V1.25.1 (XML mode)"> | |
| <link rel="stylesheet" href="style.css" type="text/css"> | |
| </head> | |
| <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> | |
| <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle"> | |
| <td width="100%" align="left" class="shortcuts"> | |
| <a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> | |
| <a href="#GTask.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> | |
| <a href="#GTask.object-hierarchy" class="shortcut">Object Hierarchy</a></span><span id="nav_interfaces"> <span class="dim">|</span> | |
| <a href="#GTask.implemented-interfaces" class="shortcut">Implemented Interfaces</a></span><span id="nav_properties"> <span class="dim">|</span> | |
| <a href="#GTask.properties" class="shortcut">Properties</a></span> | |
| </td> | |
| <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> | |
| <td><a accesskey="u" href="async.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> | |
| <td><a accesskey="p" href="GAsyncResult.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> | |
| <td><a accesskey="n" href="gio-GIOScheduler.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> | |
| </tr></table> | |
| <div class="refentry"> | |
| <a name="GTask"></a><div class="titlepage"></div> | |
| <div class="refnamediv"><table width="100%"><tr> | |
| <td valign="top"> | |
| <h2><span class="refentrytitle"><a name="GTask.top_of_page"></a>GTask</span></h2> | |
| <p>GTask — Cancellable synchronous or asynchronous task | |
| and result</p> | |
| </td> | |
| <td class="gallery_image" valign="top" align="right"></td> | |
| </tr></table></div> | |
| <div class="refsect1"> | |
| <a name="GTask.functions"></a><h2>Functions</h2> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="functions_return"> | |
| <col class="functions_name"> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td class="function_type"> | |
| <a class="link" href="GTask.html" title="GTask"><span class="returnvalue">GTask</span></a> * | |
| </td> | |
| <td class="function_name"> | |
| <a class="link" href="GTask.html#g-task-new" title="g_task_new ()">g_task_new</a> <span class="c_punctuation">()</span> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td class="function_type"> | |
| <span class="returnvalue">void</span> | |
| </td> | |
| <td class="function_name"> | |
| <a class="link" href="GTask.html#g-task-set-task-data" title="g_task_set_task_data ()">g_task_set_task_data</a> <span class="c_punctuation">()</span> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td class="function_type"> | |
| <span class="returnvalue">void</span> | |
| </td> | |
| <td class="function_name"> | |
| <a class="link" href="GTask.html#g-task-set-priority" title="g_task_set_priority ()">g_task_set_priority</a> <span class="c_punctuation">()</span> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td class="function_type"> | |
| <span class="returnvalue">void</span> | |
| </td> | |
| <td class="function_name"> | |
| <a class="link" href="GTask.html#g-task-set-check-cancellable" title="g_task_set_check_cancellable ()">g_task_set_check_cancellable</a> <span class="c_punctuation">()</span> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td class="function_type"> | |
| <a href="../glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> | |
| </td> | |
| <td class="function_name"> | |
| <a class="link" href="GTask.html#g-task-set-return-on-cancel" title="g_task_set_return_on_cancel ()">g_task_set_return_on_cancel</a> <span class="c_punctuation">()</span> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td class="function_type"> | |
| <span class="returnvalue">void</span> | |
| </td> | |
| <td class="function_name"> | |
| <a class="link" href="GTask.html#g-task-set-source-tag" title="g_task_set_source_tag ()">g_task_set_source_tag</a> <span class="c_punctuation">()</span> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td class="function_type"> | |
| <span class="returnvalue">void</span> | |
| </td> | |
| <td class="function_name"> | |
| <a class="link" href="GTask.html#g-task-report-error" title="g_task_report_error ()">g_task_report_error</a> <span class="c_punctuation">()</span> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td class="function_type"> | |
| <span class="returnvalue">void</span> | |
| </td> | |
| <td class="function_name"> | |
| <a class="link" href="GTask.html#g-task-report-new-error" title="g_task_report_new_error ()">g_task_report_new_error</a> <span class="c_punctuation">()</span> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td class="function_type"> | |
| <a href="../glib-Basic-Types.html#gpointer"><span class="returnvalue">gpointer</span></a> | |
| </td> | |
| <td class="function_name"> | |
| <a class="link" href="GTask.html#g-task-get-task-data" title="g_task_get_task_data ()">g_task_get_task_data</a> <span class="c_punctuation">()</span> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td class="function_type"> | |
| <a href="../glib-Basic-Types.html#gint"><span class="returnvalue">gint</span></a> | |
| </td> | |
| <td class="function_name"> | |
| <a class="link" href="GTask.html#g-task-get-priority" title="g_task_get_priority ()">g_task_get_priority</a> <span class="c_punctuation">()</span> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td class="function_type"> | |
| <a class="link" href="GCancellable.html" title="GCancellable"><span class="returnvalue">GCancellable</span></a> * | |
| </td> | |
| <td class="function_name"> | |
| <a class="link" href="GTask.html#g-task-get-cancellable" title="g_task_get_cancellable ()">g_task_get_cancellable</a> <span class="c_punctuation">()</span> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td class="function_type"> | |
| <a href="../glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> | |
| </td> | |
| <td class="function_name"> | |
| <a class="link" href="GTask.html#g-task-get-check-cancellable" title="g_task_get_check_cancellable ()">g_task_get_check_cancellable</a> <span class="c_punctuation">()</span> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td class="function_type"> | |
| <a href="../glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> | |
| </td> | |
| <td class="function_name"> | |
| <a class="link" href="GTask.html#g-task-get-return-on-cancel" title="g_task_get_return_on_cancel ()">g_task_get_return_on_cancel</a> <span class="c_punctuation">()</span> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td class="function_type"> | |
| <a href="../glib-The-Main-Event-Loop.html#GMainContext"><span class="returnvalue">GMainContext</span></a> * | |
| </td> | |
| <td class="function_name"> | |
| <a class="link" href="GTask.html#g-task-get-context" title="g_task_get_context ()">g_task_get_context</a> <span class="c_punctuation">()</span> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td class="function_type"> | |
| <a href="../glib-Basic-Types.html#gpointer"><span class="returnvalue">gpointer</span></a> | |
| </td> | |
| <td class="function_name"> | |
| <a class="link" href="GTask.html#g-task-get-source-object" title="g_task_get_source_object ()">g_task_get_source_object</a> <span class="c_punctuation">()</span> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td class="function_type"> | |
| <a href="../glib-Basic-Types.html#gpointer"><span class="returnvalue">gpointer</span></a> | |
| </td> | |
| <td class="function_name"> | |
| <a class="link" href="GTask.html#g-task-get-source-tag" title="g_task_get_source_tag ()">g_task_get_source_tag</a> <span class="c_punctuation">()</span> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td class="function_type"> | |
| <span class="returnvalue">void</span> | |
| </td> | |
| <td class="function_name"> | |
| <a class="link" href="GTask.html#g-task-return-boolean" title="g_task_return_boolean ()">g_task_return_boolean</a> <span class="c_punctuation">()</span> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td class="function_type"> | |
| <span class="returnvalue">void</span> | |
| </td> | |
| <td class="function_name"> | |
| <a class="link" href="GTask.html#g-task-return-int" title="g_task_return_int ()">g_task_return_int</a> <span class="c_punctuation">()</span> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td class="function_type"> | |
| <span class="returnvalue">void</span> | |
| </td> | |
| <td class="function_name"> | |
| <a class="link" href="GTask.html#g-task-return-pointer" title="g_task_return_pointer ()">g_task_return_pointer</a> <span class="c_punctuation">()</span> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td class="function_type"> | |
| <span class="returnvalue">void</span> | |
| </td> | |
| <td class="function_name"> | |
| <a class="link" href="GTask.html#g-task-return-error" title="g_task_return_error ()">g_task_return_error</a> <span class="c_punctuation">()</span> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td class="function_type"> | |
| <span class="returnvalue">void</span> | |
| </td> | |
| <td class="function_name"> | |
| <a class="link" href="GTask.html#g-task-return-new-error" title="g_task_return_new_error ()">g_task_return_new_error</a> <span class="c_punctuation">()</span> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td class="function_type"> | |
| <a href="../glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> | |
| </td> | |
| <td class="function_name"> | |
| <a class="link" href="GTask.html#g-task-return-error-if-cancelled" title="g_task_return_error_if_cancelled ()">g_task_return_error_if_cancelled</a> <span class="c_punctuation">()</span> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td class="function_type"> | |
| <a href="../glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> | |
| </td> | |
| <td class="function_name"> | |
| <a class="link" href="GTask.html#g-task-propagate-boolean" title="g_task_propagate_boolean ()">g_task_propagate_boolean</a> <span class="c_punctuation">()</span> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td class="function_type"> | |
| <a href="../glib-Basic-Types.html#gssize"><span class="returnvalue">gssize</span></a> | |
| </td> | |
| <td class="function_name"> | |
| <a class="link" href="GTask.html#g-task-propagate-int" title="g_task_propagate_int ()">g_task_propagate_int</a> <span class="c_punctuation">()</span> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td class="function_type"> | |
| <a href="../glib-Basic-Types.html#gpointer"><span class="returnvalue">gpointer</span></a> | |
| </td> | |
| <td class="function_name"> | |
| <a class="link" href="GTask.html#g-task-propagate-pointer" title="g_task_propagate_pointer ()">g_task_propagate_pointer</a> <span class="c_punctuation">()</span> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td class="function_type"> | |
| <a href="../glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> | |
| </td> | |
| <td class="function_name"> | |
| <a class="link" href="GTask.html#g-task-had-error" title="g_task_had_error ()">g_task_had_error</a> <span class="c_punctuation">()</span> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td class="function_type"> | |
| <a href="../glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> | |
| </td> | |
| <td class="function_name"> | |
| <a class="link" href="GTask.html#g-task-get-completed" title="g_task_get_completed ()">g_task_get_completed</a> <span class="c_punctuation">()</span> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td class="function_type"> | |
| <span class="returnvalue">void</span> | |
| </td> | |
| <td class="function_name"> | |
| <a class="link" href="GTask.html#g-task-run-in-thread" title="g_task_run_in_thread ()">g_task_run_in_thread</a> <span class="c_punctuation">()</span> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td class="function_type"> | |
| <span class="returnvalue">void</span> | |
| </td> | |
| <td class="function_name"> | |
| <a class="link" href="GTask.html#g-task-run-in-thread-sync" title="g_task_run_in_thread_sync ()">g_task_run_in_thread_sync</a> <span class="c_punctuation">()</span> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td class="function_type"> | |
| <span class="returnvalue">void</span> | |
| </td> | |
| <td class="function_name"> | |
| <span class="c_punctuation">(</span><a class="link" href="GTask.html#GTaskThreadFunc" title="GTaskThreadFunc ()">*GTaskThreadFunc</a><span class="c_punctuation">)</span> <span class="c_punctuation">()</span> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td class="function_type"> | |
| <span class="returnvalue">void</span> | |
| </td> | |
| <td class="function_name"> | |
| <a class="link" href="GTask.html#g-task-attach-source" title="g_task_attach_source ()">g_task_attach_source</a> <span class="c_punctuation">()</span> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td class="function_type"> | |
| <a href="../glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> | |
| </td> | |
| <td class="function_name"> | |
| <a class="link" href="GTask.html#g-task-is-valid" title="g_task_is_valid ()">g_task_is_valid</a> <span class="c_punctuation">()</span> | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table></div> | |
| </div> | |
| <div class="refsect1"> | |
| <a name="GTask.properties"></a><h2>Properties</h2> | |
| <div class="informaltable"><table class="informaltable" border="0"> | |
| <colgroup> | |
| <col width="150px" class="properties_type"> | |
| <col width="300px" class="properties_name"> | |
| <col width="200px" class="properties_flags"> | |
| </colgroup> | |
| <tbody><tr> | |
| <td class="property_type"><a href="../glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></td> | |
| <td class="property_name"><a class="link" href="GTask.html#GTask--completed" title="The “completed” property">completed</a></td> | |
| <td class="property_flags">Read</td> | |
| </tr></tbody> | |
| </table></div> | |
| </div> | |
| <div class="refsect1"> | |
| <a name="GTask.other"></a><h2>Types and Values</h2> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="name"> | |
| <col class="description"> | |
| </colgroup> | |
| <tbody><tr> | |
| <td class="datatype_keyword"> </td> | |
| <td class="function_name"><a class="link" href="GTask.html#GTask-struct" title="GTask">GTask</a></td> | |
| </tr></tbody> | |
| </table></div> | |
| </div> | |
| <div class="refsect1"> | |
| <a name="GTask.object-hierarchy"></a><h2>Object Hierarchy</h2> | |
| <pre class="screen"> <a href="../gobject-The-Base-Object-Type.html#GObject-struct">GObject</a> | |
| <span class="lineart">╰──</span> GTask | |
| </pre> | |
| </div> | |
| <div class="refsect1"> | |
| <a name="GTask.implemented-interfaces"></a><h2>Implemented Interfaces</h2> | |
| <p> | |
| GTask implements | |
| <a class="link" href="GAsyncResult.html" title="GAsyncResult">GAsyncResult</a>.</p> | |
| </div> | |
| <div class="refsect1"> | |
| <a name="GTask.includes"></a><h2>Includes</h2> | |
| <pre class="synopsis">#include <gio/gio.h> | |
| </pre> | |
| </div> | |
| <div class="refsect1"> | |
| <a name="GTask.description"></a><h2>Description</h2> | |
| <p>A <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> represents and manages a cancellable "task".</p> | |
| <div class="refsect3"> | |
| <a name="id-1.4.5.4.9.3"></a><h4>Asynchronous operations</h4> | |
| <p>The most common usage of <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> is as a <a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a>, to | |
| manage data during an asynchronous operation. You call | |
| <a class="link" href="GTask.html#g-task-new" title="g_task_new ()"><code class="function">g_task_new()</code></a> in the "start" method, followed by | |
| <a class="link" href="GTask.html#g-task-set-task-data" title="g_task_set_task_data ()"><code class="function">g_task_set_task_data()</code></a> 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 | |
| <a class="link" href="GTask.html#g-task-return-pointer" title="g_task_return_pointer ()"><code class="function">g_task_return_pointer()</code></a> or <a class="link" href="GTask.html#g-task-return-error" title="g_task_return_error ()"><code class="function">g_task_return_error()</code></a>, 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 <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> back | |
| to the operation's finish function (as a <a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a>), and | |
| you can use <a class="link" href="GTask.html#g-task-propagate-pointer" title="g_task_propagate_pointer ()"><code class="function">g_task_propagate_pointer()</code></a> or the like to extract | |
| the return value.</p> | |
| <p>Here is an example for using GTask as a GAsyncResult:</p> | |
| <div class="informalexample"> | |
| <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> | |
| <tbody> | |
| <tr> | |
| <td class="listing_lines" align="right"><pre>1 | |
| 2 | |
| 3 | |
| 4 | |
| 5 | |
| 6 | |
| 7 | |
| 8 | |
| 9 | |
| 10 | |
| 11 | |
| 12 | |
| 13 | |
| 14 | |
| 15 | |
| 16 | |
| 17 | |
| 18 | |
| 19 | |
| 20 | |
| 21 | |
| 22 | |
| 23 | |
| 24 | |
| 25 | |
| 26 | |
| 27 | |
| 28 | |
| 29 | |
| 30 | |
| 31 | |
| 32 | |
| 33 | |
| 34 | |
| 35 | |
| 36 | |
| 37 | |
| 38 | |
| 39 | |
| 40 | |
| 41 | |
| 42 | |
| 43 | |
| 44 | |
| 45 | |
| 46 | |
| 47 | |
| 48 | |
| 49 | |
| 50 | |
| 51 | |
| 52 | |
| 53 | |
| 54 | |
| 55 | |
| 56 | |
| 57 | |
| 58 | |
| 59 | |
| 60 | |
| 61 | |
| 62 | |
| 63 | |
| 64 | |
| 65 | |
| 66 | |
| 67 | |
| 68 | |
| 69 | |
| 70 | |
| 71 | |
| 72 | |
| 73 | |
| 74 | |
| 75 | |
| 76 | |
| 77 | |
| 78 | |
| 79 | |
| 80 | |
| 81 | |
| 82 | |
| 83 | |
| 84 | |
| 85 | |
| 86 | |
| 87 | |
| 88 | |
| 89 | |
| 90 | |
| 91</pre></td> | |
| <td class="listing_code"><pre class="programlisting"><span class="keyword">typedef</span><span class="normal"> </span><span class="keyword">struct</span><span class="normal"> </span><span class="cbracket">{</span> | |
| <span class="normal"> </span><span class="usertype">CakeFrostingType</span><span class="normal"> frosting</span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="type">char</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">message</span><span class="symbol">;</span> | |
| <span class="cbracket">}</span><span class="normal"> DecorationData</span><span class="symbol">;</span> | |
| <span class="keyword">static</span><span class="normal"> </span><span class="type">void</span> | |
| <span class="function">decoration_data_free</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">DecorationData</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">decoration</span><span class="symbol">)</span> | |
| <span class="cbracket">{</span> | |
| <span class="normal"> </span><span class="function"><a href="../glib-Memory-Allocation.html#g-free">g_free</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">decoration</span><span class="symbol">-></span><span class="normal">message</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="function"><a href="../glib-Memory-Slices.html#g-slice-free">g_slice_free</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">DecorationData</span><span class="symbol">,</span><span class="normal"> decoration</span><span class="symbol">);</span> | |
| <span class="cbracket">}</span> | |
| <span class="keyword">static</span><span class="normal"> </span><span class="type">void</span> | |
| <span class="function">baked_cb</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">Cake</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">cake</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">gpointer</span><span class="normal"> user_data</span><span class="symbol">)</span> | |
| <span class="cbracket">{</span> | |
| <span class="normal"> </span><span class="usertype">GTask</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">task </span><span class="symbol">=</span><span class="normal"> user_data</span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="usertype">DecorationData</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">decoration </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="GTask.html#g-task-get-task-data">g_task_get_task_data</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="usertype">GError</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">error </span><span class="symbol">=</span><span class="normal"> <a href="../glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">cake </span><span class="symbol">==</span><span class="normal"> <a href="../glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">)</span> | |
| <span class="normal"> </span><span class="cbracket">{</span> | |
| <span class="normal"> </span><span class="function"><a href="GTask.html#g-task-return-new-error">g_task_return_new_error</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">,</span><span class="normal"> BAKER_ERROR</span><span class="symbol">,</span><span class="normal"> BAKER_ERROR_NO_FLOUR</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="string">"Go to the supermarket"</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="function"><a href="../gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="keyword">return</span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="cbracket">}</span> | |
| <span class="normal"> </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(!</span><span class="function">cake_decorate</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">cake</span><span class="symbol">,</span><span class="normal"> decoration</span><span class="symbol">-></span><span class="normal">frosting</span><span class="symbol">,</span><span class="normal"> decoration</span><span class="symbol">-></span><span class="normal">message</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&</span><span class="normal">error</span><span class="symbol">))</span> | |
| <span class="normal"> </span><span class="cbracket">{</span> | |
| <span class="normal"> </span><span class="function"><a href="../gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">cake</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="comment">// g_task_return_error() takes ownership of error</span> | |
| <span class="normal"> </span><span class="function"><a href="GTask.html#g-task-return-error">g_task_return_error</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">,</span><span class="normal"> error</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="function"><a href="../gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="keyword">return</span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="cbracket">}</span> | |
| <span class="normal"> </span><span class="function"><a href="GTask.html#g-task-return-pointer">g_task_return_pointer</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">,</span><span class="normal"> cake</span><span class="symbol">,</span><span class="normal"> <a href="../gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a></span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="function"><a href="../gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">);</span> | |
| <span class="cbracket">}</span> | |
| <span class="type">void</span> | |
| <span class="function">baker_bake_cake_async</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">Baker</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">self</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">guint</span><span class="normal"> radius</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">CakeFlavor</span><span class="normal"> flavor</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">CakeFrostingType</span><span class="normal"> frosting</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="keyword">const</span><span class="normal"> </span><span class="type">char</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">message</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">GCancellable</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">cancellable</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">GAsyncReadyCallback</span><span class="normal"> callback</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">gpointer</span><span class="normal"> user_data</span><span class="symbol">)</span> | |
| <span class="cbracket">{</span> | |
| <span class="normal"> </span><span class="usertype">GTask</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">task</span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="usertype">DecorationData</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">decoration</span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="usertype">Cake</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">cake</span><span class="symbol">;</span> | |
| <span class="normal"> task </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="GTask.html#g-task-new">g_task_new</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">self</span><span class="symbol">,</span><span class="normal"> cancellable</span><span class="symbol">,</span><span class="normal"> callback</span><span class="symbol">,</span><span class="normal"> user_data</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">radius </span><span class="symbol"><</span><span class="normal"> </span><span class="number">3</span><span class="symbol">)</span> | |
| <span class="normal"> </span><span class="cbracket">{</span> | |
| <span class="normal"> </span><span class="function"><a href="GTask.html#g-task-return-new-error">g_task_return_new_error</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">,</span><span class="normal"> BAKER_ERROR</span><span class="symbol">,</span><span class="normal"> BAKER_ERROR_TOO_SMALL</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="string">"%ucm radius cakes are silly"</span><span class="symbol">,</span> | |
| <span class="normal"> radius</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="function"><a href="../gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="keyword">return</span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="cbracket">}</span> | |
| <span class="normal"> cake </span><span class="symbol">=</span><span class="normal"> </span><span class="function">_baker_get_cached_cake</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">self</span><span class="symbol">,</span><span class="normal"> radius</span><span class="symbol">,</span><span class="normal"> flavor</span><span class="symbol">,</span><span class="normal"> frosting</span><span class="symbol">,</span><span class="normal"> message</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">cake </span><span class="symbol">!=</span><span class="normal"> <a href="../glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">)</span> | |
| <span class="normal"> </span><span class="cbracket">{</span> | |
| <span class="normal"> </span><span class="comment">// _baker_get_cached_cake() returns a reffed cake</span> | |
| <span class="normal"> </span><span class="function"><a href="GTask.html#g-task-return-pointer">g_task_return_pointer</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">,</span><span class="normal"> cake</span><span class="symbol">,</span><span class="normal"> <a href="../gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a></span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="function"><a href="../gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="keyword">return</span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="cbracket">}</span> | |
| <span class="normal"> decoration </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="../glib-Memory-Slices.html#g-slice-new">g_slice_new</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">DecorationData</span><span class="symbol">);</span> | |
| <span class="normal"> decoration</span><span class="symbol">-></span><span class="normal">frosting </span><span class="symbol">=</span><span class="normal"> frosting</span><span class="symbol">;</span> | |
| <span class="normal"> decoration</span><span class="symbol">-></span><span class="normal">message </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="../glib-String-Utility-Functions.html#g-strdup">g_strdup</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">message</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="function"><a href="GTask.html#g-task-set-task-data">g_task_set_task_data</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">,</span><span class="normal"> decoration</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">(</span><span class="normal"><a href="../glib-Datasets.html#GDestroyNotify">GDestroyNotify</a></span><span class="symbol">)</span><span class="normal"> decoration_data_free</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="function">_baker_begin_cake</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">self</span><span class="symbol">,</span><span class="normal"> radius</span><span class="symbol">,</span><span class="normal"> flavor</span><span class="symbol">,</span><span class="normal"> cancellable</span><span class="symbol">,</span><span class="normal"> baked_cb</span><span class="symbol">,</span><span class="normal"> task</span><span class="symbol">);</span> | |
| <span class="cbracket">}</span> | |
| <span class="normal">Cake </span><span class="symbol">*</span> | |
| <span class="function">baker_bake_cake_finish</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">Baker</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">self</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">GAsyncResult</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">result</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">GError</span><span class="normal"> </span><span class="symbol">**</span><span class="normal">error</span><span class="symbol">)</span> | |
| <span class="cbracket">{</span> | |
| <span class="normal"> </span><span class="function"><a href="../glib-Warnings-and-Assertions.html#g-return-val-if-fail">g_return_val_if_fail</a></span><span class="normal"> </span><span class="symbol">(</span><span class="function"><a href="GTask.html#g-task-is-valid">g_task_is_valid</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">result</span><span class="symbol">,</span><span class="normal"> self</span><span class="symbol">),</span><span class="normal"> <a href="../glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="keyword">return</span><span class="normal"> </span><span class="function"><a href="GTask.html#g-task-propagate-pointer">g_task_propagate_pointer</a></span><span class="normal"> </span><span class="symbol">(</span><span class="function">G_TASK</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">result</span><span class="symbol">),</span><span class="normal"> error</span><span class="symbol">);</span> | |
| <span class="cbracket">}</span></pre></td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| </div> | |
| <p></p> | |
| </div> | |
| <div class="refsect3"> | |
| <a name="id-1.4.5.4.9.4"></a><h4>Chained asynchronous operations</h4> | |
| <p><a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> also tries to simplify asynchronous operations that | |
| internally chain together several smaller asynchronous | |
| operations. <a class="link" href="GTask.html#g-task-get-cancellable" title="g_task_get_cancellable ()"><code class="function">g_task_get_cancellable()</code></a>, <a class="link" href="GTask.html#g-task-get-context" title="g_task_get_context ()"><code class="function">g_task_get_context()</code></a>, | |
| and <a class="link" href="GTask.html#g-task-get-priority" title="g_task_get_priority ()"><code class="function">g_task_get_priority()</code></a> allow you to get back the task's | |
| <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a>, <a href="../glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a>, and <a class="link" href="GAsyncResult.html#io-priority" title="I/O Priority">I/O priority</a> | |
| when starting a new subtask, so you don't have to keep track | |
| of them yourself. <a class="link" href="GTask.html#g-task-attach-source" title="g_task_attach_source ()"><code class="function">g_task_attach_source()</code></a> simplifies the case | |
| of waiting for a source to fire (automatically using the correct | |
| <a href="../glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a> and priority).</p> | |
| <p>Here is an example for chained asynchronous operations:</p> | |
| <div class="informalexample"> | |
| <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> | |
| <tbody> | |
| <tr> | |
| <td class="listing_lines" align="right"><pre>1 | |
| 2 | |
| 3 | |
| 4 | |
| 5 | |
| 6 | |
| 7 | |
| 8 | |
| 9 | |
| 10 | |
| 11 | |
| 12 | |
| 13 | |
| 14 | |
| 15 | |
| 16 | |
| 17 | |
| 18 | |
| 19 | |
| 20 | |
| 21 | |
| 22 | |
| 23 | |
| 24 | |
| 25 | |
| 26 | |
| 27 | |
| 28 | |
| 29 | |
| 30 | |
| 31 | |
| 32 | |
| 33 | |
| 34 | |
| 35 | |
| 36 | |
| 37 | |
| 38 | |
| 39 | |
| 40 | |
| 41 | |
| 42 | |
| 43 | |
| 44 | |
| 45 | |
| 46 | |
| 47 | |
| 48 | |
| 49 | |
| 50 | |
| 51 | |
| 52 | |
| 53 | |
| 54 | |
| 55 | |
| 56 | |
| 57 | |
| 58 | |
| 59 | |
| 60 | |
| 61 | |
| 62 | |
| 63 | |
| 64 | |
| 65 | |
| 66 | |
| 67 | |
| 68 | |
| 69 | |
| 70 | |
| 71 | |
| 72 | |
| 73 | |
| 74 | |
| 75 | |
| 76 | |
| 77 | |
| 78 | |
| 79 | |
| 80 | |
| 81 | |
| 82 | |
| 83 | |
| 84 | |
| 85 | |
| 86 | |
| 87 | |
| 88 | |
| 89 | |
| 90 | |
| 91 | |
| 92 | |
| 93 | |
| 94 | |
| 95 | |
| 96 | |
| 97 | |
| 98 | |
| 99 | |
| 100 | |
| 101 | |
| 102 | |
| 103 | |
| 104 | |
| 105 | |
| 106 | |
| 107 | |
| 108 | |
| 109 | |
| 110 | |
| 111 | |
| 112 | |
| 113 | |
| 114 | |
| 115 | |
| 116 | |
| 117 | |
| 118 | |
| 119 | |
| 120 | |
| 121 | |
| 122 | |
| 123</pre></td> | |
| <td class="listing_code"><pre class="programlisting"><span class="keyword">typedef</span><span class="normal"> </span><span class="keyword">struct</span><span class="normal"> </span><span class="cbracket">{</span> | |
| <span class="normal"> </span><span class="usertype">Cake</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">cake</span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="usertype">CakeFrostingType</span><span class="normal"> frosting</span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="type">char</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">message</span><span class="symbol">;</span> | |
| <span class="cbracket">}</span><span class="normal"> BakingData</span><span class="symbol">;</span> | |
| <span class="keyword">static</span><span class="normal"> </span><span class="type">void</span> | |
| <span class="function">decoration_data_free</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">BakingData</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">bd</span><span class="symbol">)</span> | |
| <span class="cbracket">{</span> | |
| <span class="normal"> </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">bd</span><span class="symbol">-></span><span class="normal">cake</span><span class="symbol">)</span> | |
| <span class="normal"> </span><span class="function"><a href="../gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">bd</span><span class="symbol">-></span><span class="normal">cake</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="function"><a href="../glib-Memory-Allocation.html#g-free">g_free</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">bd</span><span class="symbol">-></span><span class="normal">message</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="function"><a href="../glib-Memory-Slices.html#g-slice-free">g_slice_free</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">BakingData</span><span class="symbol">,</span><span class="normal"> bd</span><span class="symbol">);</span> | |
| <span class="cbracket">}</span> | |
| <span class="keyword">static</span><span class="normal"> </span><span class="type">void</span> | |
| <span class="function">decorated_cb</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">Cake</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">cake</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">GAsyncResult</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">result</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">gpointer</span><span class="normal"> user_data</span><span class="symbol">)</span> | |
| <span class="cbracket">{</span> | |
| <span class="normal"> </span><span class="usertype">GTask</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">task </span><span class="symbol">=</span><span class="normal"> user_data</span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="usertype">GError</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">error </span><span class="symbol">=</span><span class="normal"> <a href="../glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(!</span><span class="function">cake_decorate_finish</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">cake</span><span class="symbol">,</span><span class="normal"> result</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&</span><span class="normal">error</span><span class="symbol">))</span> | |
| <span class="normal"> </span><span class="cbracket">{</span> | |
| <span class="normal"> </span><span class="function"><a href="../gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">cake</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="function"><a href="GTask.html#g-task-return-error">g_task_return_error</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">,</span><span class="normal"> error</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="function"><a href="../gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="keyword">return</span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="cbracket">}</span> | |
| <span class="normal"> </span><span class="comment">// baking_data_free() will drop its ref on the cake, so we have to</span> | |
| <span class="normal"> </span><span class="comment">// take another here to give to the caller.</span> | |
| <span class="normal"> </span><span class="function"><a href="GTask.html#g-task-return-pointer">g_task_return_pointer</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">,</span><span class="normal"> </span><span class="function"><a href="../gobject-The-Base-Object-Type.html#g-object-ref">g_object_ref</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">cake</span><span class="symbol">),</span><span class="normal"> <a href="../gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a></span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="function"><a href="../gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">);</span> | |
| <span class="cbracket">}</span> | |
| <span class="keyword">static</span><span class="normal"> <a href="../glib-Basic-Types.html#gboolean">gboolean</a></span> | |
| <span class="function">decorator_ready</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">gpointer</span><span class="normal"> user_data</span><span class="symbol">)</span> | |
| <span class="cbracket">{</span> | |
| <span class="normal"> </span><span class="usertype">GTask</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">task </span><span class="symbol">=</span><span class="normal"> user_data</span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="usertype">BakingData</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">bd </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="GTask.html#g-task-get-task-data">g_task_get_task_data</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="function">cake_decorate_async</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">bd</span><span class="symbol">-></span><span class="normal">cake</span><span class="symbol">,</span><span class="normal"> bd</span><span class="symbol">-></span><span class="normal">frosting</span><span class="symbol">,</span><span class="normal"> bd</span><span class="symbol">-></span><span class="normal">message</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="function"><a href="GTask.html#g-task-get-cancellable">g_task_get_cancellable</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">),</span> | |
| <span class="normal"> decorated_cb</span><span class="symbol">,</span><span class="normal"> task</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="keyword">return</span><span class="normal"> <a href="../glib-The-Main-Event-Loop.html#G-SOURCE-REMOVE:CAPS">G_SOURCE_REMOVE</a></span><span class="symbol">;</span> | |
| <span class="cbracket">}</span> | |
| <span class="keyword">static</span><span class="normal"> </span><span class="type">void</span> | |
| <span class="function">baked_cb</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">Cake</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">cake</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">gpointer</span><span class="normal"> user_data</span><span class="symbol">)</span> | |
| <span class="cbracket">{</span> | |
| <span class="normal"> </span><span class="usertype">GTask</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">task </span><span class="symbol">=</span><span class="normal"> user_data</span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="usertype">BakingData</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">bd </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="GTask.html#g-task-get-task-data">g_task_get_task_data</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="usertype">GError</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">error </span><span class="symbol">=</span><span class="normal"> <a href="../glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">cake </span><span class="symbol">==</span><span class="normal"> <a href="../glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">)</span> | |
| <span class="normal"> </span><span class="cbracket">{</span> | |
| <span class="normal"> </span><span class="function"><a href="GTask.html#g-task-return-new-error">g_task_return_new_error</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">,</span><span class="normal"> BAKER_ERROR</span><span class="symbol">,</span><span class="normal"> BAKER_ERROR_NO_FLOUR</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="string">"Go to the supermarket"</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="function"><a href="../gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="keyword">return</span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="cbracket">}</span> | |
| <span class="normal"> bd</span><span class="symbol">-></span><span class="normal">cake </span><span class="symbol">=</span><span class="normal"> cake</span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="comment">// Bail out now if the user has already cancelled</span> | |
| <span class="normal"> </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="function"><a href="GTask.html#g-task-return-error-if-cancelled">g_task_return_error_if_cancelled</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">))</span> | |
| <span class="normal"> </span><span class="cbracket">{</span> | |
| <span class="normal"> </span><span class="function"><a href="../gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="keyword">return</span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="cbracket">}</span> | |
| <span class="normal"> </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="function">cake_decorator_available</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">cake</span><span class="symbol">))</span> | |
| <span class="normal"> </span><span class="function">decorator_ready</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="keyword">else</span> | |
| <span class="normal"> </span><span class="cbracket">{</span> | |
| <span class="normal"> </span><span class="usertype">GSource</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">source</span><span class="symbol">;</span> | |
| <span class="normal"> source </span><span class="symbol">=</span><span class="normal"> </span><span class="function">cake_decorator_wait_source_new</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">cake</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="comment">// Attach @source to @task's GMainContext and have it call</span> | |
| <span class="normal"> </span><span class="comment">// decorator_ready() when it is ready.</span> | |
| <span class="normal"> </span><span class="function"><a href="GTask.html#g-task-attach-source">g_task_attach_source</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">,</span><span class="normal"> source</span><span class="symbol">,</span><span class="normal"> decorator_ready</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="function"><a href="../glib-The-Main-Event-Loop.html#g-source-unref">g_source_unref</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">source</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="cbracket">}</span> | |
| <span class="cbracket">}</span> | |
| <span class="type">void</span> | |
| <span class="function">baker_bake_cake_async</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">Baker</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">self</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">guint</span><span class="normal"> radius</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">CakeFlavor</span><span class="normal"> flavor</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">CakeFrostingType</span><span class="normal"> frosting</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="keyword">const</span><span class="normal"> </span><span class="type">char</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">message</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">gint</span><span class="normal"> priority</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">GCancellable</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">cancellable</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">GAsyncReadyCallback</span><span class="normal"> callback</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">gpointer</span><span class="normal"> user_data</span><span class="symbol">)</span> | |
| <span class="cbracket">{</span> | |
| <span class="normal"> </span><span class="usertype">GTask</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">task</span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="usertype">BakingData</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">bd</span><span class="symbol">;</span> | |
| <span class="normal"> task </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="GTask.html#g-task-new">g_task_new</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">self</span><span class="symbol">,</span><span class="normal"> cancellable</span><span class="symbol">,</span><span class="normal"> callback</span><span class="symbol">,</span><span class="normal"> user_data</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="function"><a href="GTask.html#g-task-set-priority">g_task_set_priority</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">,</span><span class="normal"> priority</span><span class="symbol">);</span> | |
| <span class="normal"> bd </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="../glib-Memory-Slices.html#g-slice-new0">g_slice_new0</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">BakingData</span><span class="symbol">);</span> | |
| <span class="normal"> bd</span><span class="symbol">-></span><span class="normal">frosting </span><span class="symbol">=</span><span class="normal"> frosting</span><span class="symbol">;</span> | |
| <span class="normal"> bd</span><span class="symbol">-></span><span class="normal">message </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="../glib-String-Utility-Functions.html#g-strdup">g_strdup</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">message</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="function"><a href="GTask.html#g-task-set-task-data">g_task_set_task_data</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">,</span><span class="normal"> bd</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">(</span><span class="normal"><a href="../glib-Datasets.html#GDestroyNotify">GDestroyNotify</a></span><span class="symbol">)</span><span class="normal"> baking_data_free</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="function">_baker_begin_cake</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">self</span><span class="symbol">,</span><span class="normal"> radius</span><span class="symbol">,</span><span class="normal"> flavor</span><span class="symbol">,</span><span class="normal"> cancellable</span><span class="symbol">,</span><span class="normal"> baked_cb</span><span class="symbol">,</span><span class="normal"> task</span><span class="symbol">);</span> | |
| <span class="cbracket">}</span> | |
| <span class="normal">Cake </span><span class="symbol">*</span> | |
| <span class="function">baker_bake_cake_finish</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">Baker</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">self</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">GAsyncResult</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">result</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">GError</span><span class="normal"> </span><span class="symbol">**</span><span class="normal">error</span><span class="symbol">)</span> | |
| <span class="cbracket">{</span> | |
| <span class="normal"> </span><span class="function"><a href="../glib-Warnings-and-Assertions.html#g-return-val-if-fail">g_return_val_if_fail</a></span><span class="normal"> </span><span class="symbol">(</span><span class="function"><a href="GTask.html#g-task-is-valid">g_task_is_valid</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">result</span><span class="symbol">,</span><span class="normal"> self</span><span class="symbol">),</span><span class="normal"> <a href="../glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="keyword">return</span><span class="normal"> </span><span class="function"><a href="GTask.html#g-task-propagate-pointer">g_task_propagate_pointer</a></span><span class="normal"> </span><span class="symbol">(</span><span class="function">G_TASK</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">result</span><span class="symbol">),</span><span class="normal"> error</span><span class="symbol">);</span> | |
| <span class="cbracket">}</span></pre></td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| </div> | |
| <p></p> | |
| </div> | |
| <div class="refsect3"> | |
| <a name="id-1.4.5.4.9.5"></a><h4>Asynchronous operations from synchronous ones</h4> | |
| <p>You can use <a class="link" href="GTask.html#g-task-run-in-thread" title="g_task_run_in_thread ()"><code class="function">g_task_run_in_thread()</code></a> 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 | |
| <a href="../glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a> when it completes.</p> | |
| <p>Running a task in a thread:</p> | |
| <div class="informalexample"> | |
| <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> | |
| <tbody> | |
| <tr> | |
| <td class="listing_lines" align="right"><pre>1 | |
| 2 | |
| 3 | |
| 4 | |
| 5 | |
| 6 | |
| 7 | |
| 8 | |
| 9 | |
| 10 | |
| 11 | |
| 12 | |
| 13 | |
| 14 | |
| 15 | |
| 16 | |
| 17 | |
| 18 | |
| 19 | |
| 20 | |
| 21 | |
| 22 | |
| 23 | |
| 24 | |
| 25 | |
| 26 | |
| 27 | |
| 28 | |
| 29 | |
| 30 | |
| 31 | |
| 32 | |
| 33 | |
| 34 | |
| 35 | |
| 36 | |
| 37 | |
| 38 | |
| 39 | |
| 40 | |
| 41 | |
| 42 | |
| 43 | |
| 44 | |
| 45 | |
| 46 | |
| 47 | |
| 48 | |
| 49 | |
| 50 | |
| 51 | |
| 52 | |
| 53 | |
| 54 | |
| 55 | |
| 56 | |
| 57 | |
| 58 | |
| 59 | |
| 60 | |
| 61 | |
| 62 | |
| 63 | |
| 64 | |
| 65 | |
| 66 | |
| 67</pre></td> | |
| <td class="listing_code"><pre class="programlisting"><span class="keyword">typedef</span><span class="normal"> </span><span class="keyword">struct</span><span class="normal"> </span><span class="cbracket">{</span> | |
| <span class="normal"> </span><span class="usertype">guint</span><span class="normal"> radius</span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="usertype">CakeFlavor</span><span class="normal"> flavor</span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="usertype">CakeFrostingType</span><span class="normal"> frosting</span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="type">char</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">message</span><span class="symbol">;</span> | |
| <span class="cbracket">}</span><span class="normal"> CakeData</span><span class="symbol">;</span> | |
| <span class="keyword">static</span><span class="normal"> </span><span class="type">void</span> | |
| <span class="function">cake_data_free</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">CakeData</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">cake_data</span><span class="symbol">)</span> | |
| <span class="cbracket">{</span> | |
| <span class="normal"> </span><span class="function"><a href="../glib-Memory-Allocation.html#g-free">g_free</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">cake_data</span><span class="symbol">-></span><span class="normal">message</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="function"><a href="../glib-Memory-Slices.html#g-slice-free">g_slice_free</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">CakeData</span><span class="symbol">,</span><span class="normal"> cake_data</span><span class="symbol">);</span> | |
| <span class="cbracket">}</span> | |
| <span class="keyword">static</span><span class="normal"> </span><span class="type">void</span> | |
| <span class="function">bake_cake_thread</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">GTask</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">task</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">gpointer</span><span class="normal"> source_object</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">gpointer</span><span class="normal"> task_data</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">GCancellable</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">cancellable</span><span class="symbol">)</span> | |
| <span class="cbracket">{</span> | |
| <span class="normal"> </span><span class="usertype">Baker</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">self </span><span class="symbol">=</span><span class="normal"> source_object</span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="usertype">CakeData</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">cake_data </span><span class="symbol">=</span><span class="normal"> task_data</span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="usertype">Cake</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">cake</span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="usertype">GError</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">error </span><span class="symbol">=</span><span class="normal"> <a href="../glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">;</span> | |
| <span class="normal"> cake </span><span class="symbol">=</span><span class="normal"> </span><span class="function">bake_cake</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">baker</span><span class="symbol">,</span><span class="normal"> cake_data</span><span class="symbol">-></span><span class="normal">radius</span><span class="symbol">,</span><span class="normal"> cake_data</span><span class="symbol">-></span><span class="normal">flavor</span><span class="symbol">,</span> | |
| <span class="normal"> cake_data</span><span class="symbol">-></span><span class="normal">frosting</span><span class="symbol">,</span><span class="normal"> cake_data</span><span class="symbol">-></span><span class="normal">message</span><span class="symbol">,</span> | |
| <span class="normal"> cancellable</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&</span><span class="normal">error</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">cake</span><span class="symbol">)</span> | |
| <span class="normal"> </span><span class="function"><a href="GTask.html#g-task-return-pointer">g_task_return_pointer</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">,</span><span class="normal"> cake</span><span class="symbol">,</span><span class="normal"> <a href="../gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a></span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="keyword">else</span> | |
| <span class="normal"> </span><span class="function"><a href="GTask.html#g-task-return-error">g_task_return_error</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">,</span><span class="normal"> error</span><span class="symbol">);</span> | |
| <span class="cbracket">}</span> | |
| <span class="type">void</span> | |
| <span class="function">baker_bake_cake_async</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">Baker</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">self</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">guint</span><span class="normal"> radius</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">CakeFlavor</span><span class="normal"> flavor</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">CakeFrostingType</span><span class="normal"> frosting</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="keyword">const</span><span class="normal"> </span><span class="type">char</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">message</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">GCancellable</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">cancellable</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">GAsyncReadyCallback</span><span class="normal"> callback</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">gpointer</span><span class="normal"> user_data</span><span class="symbol">)</span> | |
| <span class="cbracket">{</span> | |
| <span class="normal"> </span><span class="usertype">CakeData</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">cake_data</span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="usertype">GTask</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">task</span><span class="symbol">;</span> | |
| <span class="normal"> cake_data </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="../glib-Memory-Slices.html#g-slice-new">g_slice_new</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">CakeData</span><span class="symbol">);</span> | |
| <span class="normal"> cake_data</span><span class="symbol">-></span><span class="normal">radius </span><span class="symbol">=</span><span class="normal"> radius</span><span class="symbol">;</span> | |
| <span class="normal"> cake_data</span><span class="symbol">-></span><span class="normal">flavor </span><span class="symbol">=</span><span class="normal"> flavor</span><span class="symbol">;</span> | |
| <span class="normal"> cake_data</span><span class="symbol">-></span><span class="normal">frosting </span><span class="symbol">=</span><span class="normal"> frosting</span><span class="symbol">;</span> | |
| <span class="normal"> cake_data</span><span class="symbol">-></span><span class="normal">message </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="../glib-String-Utility-Functions.html#g-strdup">g_strdup</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">message</span><span class="symbol">);</span> | |
| <span class="normal"> task </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="GTask.html#g-task-new">g_task_new</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">self</span><span class="symbol">,</span><span class="normal"> cancellable</span><span class="symbol">,</span><span class="normal"> callback</span><span class="symbol">,</span><span class="normal"> user_data</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="function"><a href="GTask.html#g-task-set-task-data">g_task_set_task_data</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">,</span><span class="normal"> cake_data</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">(</span><span class="normal"><a href="../glib-Datasets.html#GDestroyNotify">GDestroyNotify</a></span><span class="symbol">)</span><span class="normal"> cake_data_free</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="function"><a href="GTask.html#g-task-run-in-thread">g_task_run_in_thread</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">,</span><span class="normal"> bake_cake_thread</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="function"><a href="../gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">);</span> | |
| <span class="cbracket">}</span> | |
| <span class="normal">Cake </span><span class="symbol">*</span> | |
| <span class="function">baker_bake_cake_finish</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">Baker</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">self</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">GAsyncResult</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">result</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">GError</span><span class="normal"> </span><span class="symbol">**</span><span class="normal">error</span><span class="symbol">)</span> | |
| <span class="cbracket">{</span> | |
| <span class="normal"> </span><span class="function"><a href="../glib-Warnings-and-Assertions.html#g-return-val-if-fail">g_return_val_if_fail</a></span><span class="normal"> </span><span class="symbol">(</span><span class="function"><a href="GTask.html#g-task-is-valid">g_task_is_valid</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">result</span><span class="symbol">,</span><span class="normal"> self</span><span class="symbol">),</span><span class="normal"> <a href="../glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="keyword">return</span><span class="normal"> </span><span class="function"><a href="GTask.html#g-task-propagate-pointer">g_task_propagate_pointer</a></span><span class="normal"> </span><span class="symbol">(</span><span class="function">G_TASK</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">result</span><span class="symbol">),</span><span class="normal"> error</span><span class="symbol">);</span> | |
| <span class="cbracket">}</span></pre></td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| </div> | |
| <p></p> | |
| </div> | |
| <div class="refsect3"> | |
| <a name="id-1.4.5.4.9.6"></a><h4>Adding cancellability to uncancellable tasks</h4> | |
| <p>Finally, <a class="link" href="GTask.html#g-task-run-in-thread" title="g_task_run_in_thread ()"><code class="function">g_task_run_in_thread()</code></a> and <a class="link" href="GTask.html#g-task-run-in-thread-sync" title="g_task_run_in_thread_sync ()"><code class="function">g_task_run_in_thread_sync()</code></a> | |
| can be used to turn an uncancellable operation into a | |
| cancellable one. If you call <a class="link" href="GTask.html#g-task-set-return-on-cancel" title="g_task_set_return_on_cancel ()"><code class="function">g_task_set_return_on_cancel()</code></a>, | |
| passing <a href="../glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a>, then if the task's <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> 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.</p> | |
| <p>Cancelling a task:</p> | |
| <div class="informalexample"> | |
| <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> | |
| <tbody> | |
| <tr> | |
| <td class="listing_lines" align="right"><pre>1 | |
| 2 | |
| 3 | |
| 4 | |
| 5 | |
| 6 | |
| 7 | |
| 8 | |
| 9 | |
| 10 | |
| 11 | |
| 12 | |
| 13 | |
| 14 | |
| 15 | |
| 16 | |
| 17 | |
| 18 | |
| 19 | |
| 20 | |
| 21 | |
| 22 | |
| 23 | |
| 24 | |
| 25 | |
| 26 | |
| 27 | |
| 28 | |
| 29 | |
| 30 | |
| 31 | |
| 32 | |
| 33 | |
| 34 | |
| 35 | |
| 36 | |
| 37 | |
| 38 | |
| 39 | |
| 40 | |
| 41 | |
| 42 | |
| 43 | |
| 44 | |
| 45 | |
| 46 | |
| 47 | |
| 48 | |
| 49 | |
| 50 | |
| 51 | |
| 52 | |
| 53 | |
| 54 | |
| 55 | |
| 56 | |
| 57 | |
| 58 | |
| 59 | |
| 60 | |
| 61 | |
| 62 | |
| 63 | |
| 64 | |
| 65 | |
| 66 | |
| 67 | |
| 68 | |
| 69 | |
| 70 | |
| 71 | |
| 72 | |
| 73 | |
| 74 | |
| 75 | |
| 76 | |
| 77 | |
| 78 | |
| 79 | |
| 80 | |
| 81 | |
| 82 | |
| 83 | |
| 84 | |
| 85 | |
| 86 | |
| 87 | |
| 88</pre></td> | |
| <td class="listing_code"><pre class="programlisting"><span class="keyword">static</span><span class="normal"> </span><span class="type">void</span> | |
| <span class="function">bake_cake_thread</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">GTask</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">task</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">gpointer</span><span class="normal"> source_object</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">gpointer</span><span class="normal"> task_data</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">GCancellable</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">cancellable</span><span class="symbol">)</span> | |
| <span class="cbracket">{</span> | |
| <span class="normal"> </span><span class="usertype">Baker</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">self </span><span class="symbol">=</span><span class="normal"> source_object</span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="usertype">CakeData</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">cake_data </span><span class="symbol">=</span><span class="normal"> task_data</span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="usertype">Cake</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">cake</span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="usertype">GError</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">error </span><span class="symbol">=</span><span class="normal"> <a href="../glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">;</span> | |
| <span class="normal"> cake </span><span class="symbol">=</span><span class="normal"> </span><span class="function">bake_cake</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">baker</span><span class="symbol">,</span><span class="normal"> cake_data</span><span class="symbol">-></span><span class="normal">radius</span><span class="symbol">,</span><span class="normal"> cake_data</span><span class="symbol">-></span><span class="normal">flavor</span><span class="symbol">,</span> | |
| <span class="normal"> cake_data</span><span class="symbol">-></span><span class="normal">frosting</span><span class="symbol">,</span><span class="normal"> cake_data</span><span class="symbol">-></span><span class="normal">message</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="symbol">&</span><span class="normal">error</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">error</span><span class="symbol">)</span> | |
| <span class="normal"> </span><span class="cbracket">{</span> | |
| <span class="normal"> </span><span class="function"><a href="GTask.html#g-task-return-error">g_task_return_error</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">,</span><span class="normal"> error</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="keyword">return</span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="cbracket">}</span> | |
| <span class="normal"> </span><span class="comment">// If the task has already been cancelled, then we don't want to add</span> | |
| <span class="normal"> </span><span class="comment">// the cake to the cake cache. Likewise, we don't want to have the</span> | |
| <span class="normal"> </span><span class="comment">// task get cancelled in the middle of updating the cache.</span> | |
| <span class="normal"> </span><span class="comment">// g_task_set_return_on_cancel() will return %TRUE here if it managed</span> | |
| <span class="normal"> </span><span class="comment">// to disable return-on-cancel, or %FALSE if the task was cancelled</span> | |
| <span class="normal"> </span><span class="comment">// before it could.</span> | |
| <span class="normal"> </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="function"><a href="GTask.html#g-task-set-return-on-cancel">g_task_set_return_on_cancel</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">,</span><span class="normal"> <a href="../glib-Standard-Macros.html#FALSE:CAPS">FALSE</a></span><span class="symbol">))</span> | |
| <span class="normal"> </span><span class="cbracket">{</span> | |
| <span class="normal"> </span><span class="comment">// If the caller cancels at this point, their</span> | |
| <span class="normal"> </span><span class="comment">// GAsyncReadyCallback won't be invoked until we return,</span> | |
| <span class="normal"> </span><span class="comment">// so we don't have to worry that this code will run at</span> | |
| <span class="normal"> </span><span class="comment">// the same time as that code does. But if there were</span> | |
| <span class="normal"> </span><span class="comment">// other functions that might look at the cake cache,</span> | |
| <span class="normal"> </span><span class="comment">// then we'd probably need a GMutex here as well.</span> | |
| <span class="normal"> </span><span class="function">baker_add_cake_to_cache</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">baker</span><span class="symbol">,</span><span class="normal"> cake</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="function"><a href="GTask.html#g-task-return-pointer">g_task_return_pointer</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">,</span><span class="normal"> cake</span><span class="symbol">,</span><span class="normal"> <a href="../gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a></span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="cbracket">}</span> | |
| <span class="cbracket">}</span> | |
| <span class="type">void</span> | |
| <span class="function">baker_bake_cake_async</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">Baker</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">self</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">guint</span><span class="normal"> radius</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">CakeFlavor</span><span class="normal"> flavor</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">CakeFrostingType</span><span class="normal"> frosting</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="keyword">const</span><span class="normal"> </span><span class="type">char</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">message</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">GCancellable</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">cancellable</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">GAsyncReadyCallback</span><span class="normal"> callback</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">gpointer</span><span class="normal"> user_data</span><span class="symbol">)</span> | |
| <span class="cbracket">{</span> | |
| <span class="normal"> </span><span class="usertype">CakeData</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">cake_data</span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="usertype">GTask</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">task</span><span class="symbol">;</span> | |
| <span class="normal"> cake_data </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="../glib-Memory-Slices.html#g-slice-new">g_slice_new</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">CakeData</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="symbol">...</span> | |
| <span class="normal"> task </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="GTask.html#g-task-new">g_task_new</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">self</span><span class="symbol">,</span><span class="normal"> cancellable</span><span class="symbol">,</span><span class="normal"> callback</span><span class="symbol">,</span><span class="normal"> user_data</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="function"><a href="GTask.html#g-task-set-task-data">g_task_set_task_data</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">,</span><span class="normal"> cake_data</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">(</span><span class="normal"><a href="../glib-Datasets.html#GDestroyNotify">GDestroyNotify</a></span><span class="symbol">)</span><span class="normal"> cake_data_free</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="function"><a href="GTask.html#g-task-set-return-on-cancel">g_task_set_return_on_cancel</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">,</span><span class="normal"> <a href="../glib-Standard-Macros.html#TRUE:CAPS">TRUE</a></span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="function"><a href="GTask.html#g-task-run-in-thread">g_task_run_in_thread</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">,</span><span class="normal"> bake_cake_thread</span><span class="symbol">);</span> | |
| <span class="cbracket">}</span> | |
| <span class="normal">Cake </span><span class="symbol">*</span> | |
| <span class="function">baker_bake_cake_sync</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">Baker</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">self</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">guint</span><span class="normal"> radius</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">CakeFlavor</span><span class="normal"> flavor</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">CakeFrostingType</span><span class="normal"> frosting</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="keyword">const</span><span class="normal"> </span><span class="type">char</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">message</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">GCancellable</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">cancellable</span><span class="symbol">,</span> | |
| <span class="normal"> </span><span class="usertype">GError</span><span class="normal"> </span><span class="symbol">**</span><span class="normal">error</span><span class="symbol">)</span> | |
| <span class="cbracket">{</span> | |
| <span class="normal"> </span><span class="usertype">CakeData</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">cake_data</span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="usertype">GTask</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">task</span><span class="symbol">;</span> | |
| <span class="normal"> </span><span class="usertype">Cake</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">cake</span><span class="symbol">;</span> | |
| <span class="normal"> cake_data </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="../glib-Memory-Slices.html#g-slice-new">g_slice_new</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">CakeData</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="symbol">...</span> | |
| <span class="normal"> task </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="GTask.html#g-task-new">g_task_new</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">self</span><span class="symbol">,</span><span class="normal"> cancellable</span><span class="symbol">,</span><span class="normal"> <a href="../glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">,</span><span class="normal"> <a href="../glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="function"><a href="GTask.html#g-task-set-task-data">g_task_set_task_data</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">,</span><span class="normal"> cake_data</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">(</span><span class="normal"><a href="../glib-Datasets.html#GDestroyNotify">GDestroyNotify</a></span><span class="symbol">)</span><span class="normal"> cake_data_free</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="function"><a href="GTask.html#g-task-set-return-on-cancel">g_task_set_return_on_cancel</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">,</span><span class="normal"> <a href="../glib-Standard-Macros.html#TRUE:CAPS">TRUE</a></span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="function"><a href="GTask.html#g-task-run-in-thread-sync">g_task_run_in_thread_sync</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">,</span><span class="normal"> bake_cake_thread</span><span class="symbol">);</span> | |
| <span class="normal"> cake </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="GTask.html#g-task-propagate-pointer">g_task_propagate_pointer</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">,</span><span class="normal"> error</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="function"><a href="../gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">task</span><span class="symbol">);</span> | |
| <span class="normal"> </span><span class="keyword">return</span><span class="normal"> cake</span><span class="symbol">;</span> | |
| <span class="cbracket">}</span></pre></td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| </div> | |
| <p></p> | |
| </div> | |
| <div class="refsect3"> | |
| <a name="id-1.4.5.4.9.7"></a><h4>Porting from GSimpleAsyncResult</h4> | |
| <p><a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a>'s API attempts to be simpler than <a class="link" href="GSimpleAsyncResult.html" title="GSimpleAsyncResult"><span class="type">GSimpleAsyncResult</span></a>'s | |
| in several ways:</p> | |
| <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> | |
| <li class="listitem"><p>You can save task-specific data with <a class="link" href="GTask.html#g-task-set-task-data" title="g_task_set_task_data ()"><code class="function">g_task_set_task_data()</code></a>, and | |
| retrieve it later with <a class="link" href="GTask.html#g-task-get-task-data" title="g_task_get_task_data ()"><code class="function">g_task_get_task_data()</code></a>. This replaces the | |
| abuse of <a class="link" href="GSimpleAsyncResult.html#g-simple-async-result-set-op-res-gpointer" title="g_simple_async_result_set_op_res_gpointer ()"><code class="function">g_simple_async_result_set_op_res_gpointer()</code></a> for the same | |
| purpose with <a class="link" href="GSimpleAsyncResult.html" title="GSimpleAsyncResult"><span class="type">GSimpleAsyncResult</span></a>.</p></li> | |
| <li class="listitem"><p>In addition to the task data, <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> also keeps track of the | |
| <a class="link" href="GAsyncResult.html#io-priority" title="I/O Priority">priority</a>, <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a>, and | |
| <a href="../glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a> 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.</p></li> | |
| <li class="listitem"><p>g_task_return_error_if_cancelled() provides simplified | |
| handling for cancellation. In addition, cancellation | |
| overrides any other <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> return value by default, like | |
| <a class="link" href="GSimpleAsyncResult.html" title="GSimpleAsyncResult"><span class="type">GSimpleAsyncResult</span></a> does when | |
| <a class="link" href="GSimpleAsyncResult.html#g-simple-async-result-set-check-cancellable" title="g_simple_async_result_set_check_cancellable ()"><code class="function">g_simple_async_result_set_check_cancellable()</code></a> is called. | |
| (You can use <a class="link" href="GTask.html#g-task-set-check-cancellable" title="g_task_set_check_cancellable ()"><code class="function">g_task_set_check_cancellable()</code></a> to turn off that | |
| behavior.) On the other hand, <a class="link" href="GTask.html#g-task-run-in-thread" title="g_task_run_in_thread ()"><code class="function">g_task_run_in_thread()</code></a> | |
| guarantees that it will always run your | |
| <code class="literal">task_func</code>, even if the task's <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> | |
| is already cancelled before the task gets a chance to run; | |
| you can start your <code class="literal">task_func</code> with a | |
| <a class="link" href="GTask.html#g-task-return-error-if-cancelled" title="g_task_return_error_if_cancelled ()"><code class="function">g_task_return_error_if_cancelled()</code></a> check if you need the | |
| old behavior.</p></li> | |
| <li class="listitem"><p>The "return" methods (eg, <a class="link" href="GTask.html#g-task-return-pointer" title="g_task_return_pointer ()"><code class="function">g_task_return_pointer()</code></a>) | |
| automatically cause the task to be "completed" as well, and | |
| there is no need to worry about the "complete" vs "complete | |
| in idle" distinction. (<a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> automatically figures out | |
| whether the task's callback can be invoked directly, or | |
| if it needs to be sent to another <a href="../glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a>, or delayed | |
| until the next iteration of the current <a href="../glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a>.)</p></li> | |
| <li class="listitem"><p>The "finish" functions for <span class="type">GTask-based</span> operations are generally | |
| much simpler than <a class="link" href="GSimpleAsyncResult.html" title="GSimpleAsyncResult"><span class="type">GSimpleAsyncResult</span></a> ones, normally consisting | |
| of only a single call to <a class="link" href="GTask.html#g-task-propagate-pointer" title="g_task_propagate_pointer ()"><code class="function">g_task_propagate_pointer()</code></a> or the like. | |
| Since <a class="link" href="GTask.html#g-task-propagate-pointer" title="g_task_propagate_pointer ()"><code class="function">g_task_propagate_pointer()</code></a> "steals" the return value from | |
| the <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a>, it is not necessary to juggle pointers around to | |
| prevent it from being freed twice.</p></li> | |
| <li class="listitem"><p>With <a class="link" href="GSimpleAsyncResult.html" title="GSimpleAsyncResult"><span class="type">GSimpleAsyncResult</span></a>, it was common to call | |
| <a class="link" href="GSimpleAsyncResult.html#g-simple-async-result-propagate-error" title="g_simple_async_result_propagate_error ()"><code class="function">g_simple_async_result_propagate_error()</code></a> from the | |
| <code class="literal"><code class="function">_finish()</code></code> 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 <code class="literal">g_task_propagate_</code> function. | |
| Note that wrapper methods can now use | |
| <a class="link" href="GAsyncResult.html#g-async-result-legacy-propagate-error" title="g_async_result_legacy_propagate_error ()"><code class="function">g_async_result_legacy_propagate_error()</code></a> to do old-style | |
| <a class="link" href="GSimpleAsyncResult.html" title="GSimpleAsyncResult"><span class="type">GSimpleAsyncResult</span></a> error-returning behavior, and | |
| <a class="link" href="GAsyncResult.html#g-async-result-is-tagged" title="g_async_result_is_tagged ()"><code class="function">g_async_result_is_tagged()</code></a> to check if a result is tagged as | |
| having come from the <code class="literal"><a class="link" href="async.html" title="Asynchronous I/O"><code class="function">_async()</code></a></code> wrapper | |
| function (for "short-circuit" results, such as when passing | |
| 0 to <a class="link" href="GInputStream.html#g-input-stream-read-async" title="g_input_stream_read_async ()"><code class="function">g_input_stream_read_async()</code></a>).</p></li> | |
| </ul></div> | |
| </div> | |
| </div> | |
| <div class="refsect1"> | |
| <a name="GTask.functions_details"></a><h2>Functions</h2> | |
| <div class="refsect2"> | |
| <a name="g-task-new"></a><h3>g_task_new ()</h3> | |
| <pre class="programlisting"><a class="link" href="GTask.html" title="GTask"><span class="returnvalue">GTask</span></a> * | |
| g_task_new (<em class="parameter"><code><a href="../glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> source_object</code></em>, | |
| <em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>, | |
| <em class="parameter"><code><a class="link" href="GAsyncResult.html#GAsyncReadyCallback" title="GAsyncReadyCallback ()"><span class="type">GAsyncReadyCallback</span></a> callback</code></em>, | |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> callback_data</code></em>);</pre> | |
| <p>Creates a <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> acting on <em class="parameter"><code>source_object</code></em> | |
| , which will eventually be | |
| used to invoke <em class="parameter"><code>callback</code></em> | |
| in the current | |
| <a href="../glib-The-Main-Event-Loop.html#g-main-context-push-thread-default">thread-default main context</a>.</p> | |
| <p>Call this in the "start" method of your asynchronous method, and | |
| pass the <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> around throughout the asynchronous operation. You | |
| can use <a class="link" href="GTask.html#g-task-set-task-data" title="g_task_set_task_data ()"><code class="function">g_task_set_task_data()</code></a> to attach task-specific data to the | |
| object, which you can retrieve later via <a class="link" href="GTask.html#g-task-get-task-data" title="g_task_get_task_data ()"><code class="function">g_task_get_task_data()</code></a>.</p> | |
| <p>By default, if <em class="parameter"><code>cancellable</code></em> | |
| is cancelled, then the return value of | |
| the task will always be <a class="link" href="gio-GIOError.html#G-IO-ERROR-CANCELLED:CAPS"><code class="literal">G_IO_ERROR_CANCELLED</code></a>, 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 | |
| <a class="link" href="GTask.html#g-task-set-check-cancellable" title="g_task_set_check_cancellable ()"><code class="function">g_task_set_check_cancellable()</code></a> to change it.</p> | |
| <div class="refsect3"> | |
| <a name="g-task-new.parameters"></a><h4>Parameters</h4> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="parameters_name"> | |
| <col class="parameters_description"> | |
| <col width="200px" class="parameters_annotations"> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td class="parameter_name"><p>source_object</p></td> | |
| <td class="parameter_description"><p> the <a href="../gobject-The-Base-Object-Type.html#GObject-struct"><span class="type">GObject</span></a> that owns | |
| this task, or <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p></td> | |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>][<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> GObject]</span></td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>cancellable</p></td> | |
| <td class="parameter_description"><p> optional <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> object, <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore. </p></td> | |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>callback</p></td> | |
| <td class="parameter_description"><p> a <a class="link" href="GAsyncResult.html#GAsyncReadyCallback" title="GAsyncReadyCallback ()"><span class="type">GAsyncReadyCallback</span></a>. </p></td> | |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="The callback is valid until first called."><span class="acronym">scope async</span></acronym>]</span></td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>callback_data</p></td> | |
| <td class="parameter_description"><p> user data passed to <em class="parameter"><code>callback</code></em> | |
| . </p></td> | |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="This parameter is a 'user_data', for callbacks; many bindings can pass NULL here."><span class="acronym">closure</span></acronym>]</span></td> | |
| </tr> | |
| </tbody> | |
| </table></div> | |
| </div> | |
| <div class="refsect3"> | |
| <a name="g-task-new.returns"></a><h4>Returns</h4> | |
| <p> a <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a>.</p> | |
| </div> | |
| <p class="since">Since: <a class="link" href="api-index-2-36.html#api-index-2.36">2.36</a></p> | |
| </div> | |
| <hr> | |
| <div class="refsect2"> | |
| <a name="g-task-set-task-data"></a><h3>g_task_set_task_data ()</h3> | |
| <pre class="programlisting"><span class="returnvalue">void</span> | |
| g_task_set_task_data (<em class="parameter"><code><a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> *task</code></em>, | |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> task_data</code></em>, | |
| <em class="parameter"><code><a href="../glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> task_data_destroy</code></em>);</pre> | |
| <p>Sets <em class="parameter"><code>task</code></em> | |
| 's task data (freeing the existing task data, if any).</p> | |
| <div class="refsect3"> | |
| <a name="g-task-set-task-data.parameters"></a><h4>Parameters</h4> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="parameters_name"> | |
| <col class="parameters_description"> | |
| <col width="200px" class="parameters_annotations"> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td class="parameter_name"><p>task</p></td> | |
| <td class="parameter_description"><p>the <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a></p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>task_data</p></td> | |
| <td class="parameter_description"><p> task-specific data. </p></td> | |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>task_data_destroy</p></td> | |
| <td class="parameter_description"><p> <a href="../glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> for <em class="parameter"><code>task_data</code></em> | |
| . </p></td> | |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> | |
| </tr> | |
| </tbody> | |
| </table></div> | |
| </div> | |
| <p class="since">Since: <a class="link" href="api-index-2-36.html#api-index-2.36">2.36</a></p> | |
| </div> | |
| <hr> | |
| <div class="refsect2"> | |
| <a name="g-task-set-priority"></a><h3>g_task_set_priority ()</h3> | |
| <pre class="programlisting"><span class="returnvalue">void</span> | |
| g_task_set_priority (<em class="parameter"><code><a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> *task</code></em>, | |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gint"><span class="type">gint</span></a> priority</code></em>);</pre> | |
| <p>Sets <em class="parameter"><code>task</code></em> | |
| 's priority. If you do not call this, it will default to | |
| <a href="../glib-The-Main-Event-Loop.html#G-PRIORITY-DEFAULT:CAPS"><code class="literal">G_PRIORITY_DEFAULT</code></a>.</p> | |
| <p>This will affect the priority of <a href="../glib-The-Main-Event-Loop.html#GSource"><span class="type">GSources</span></a> created with | |
| <a class="link" href="GTask.html#g-task-attach-source" title="g_task_attach_source ()"><code class="function">g_task_attach_source()</code></a> and the scheduling of tasks run in threads, | |
| and can also be explicitly retrieved later via | |
| <a class="link" href="GTask.html#g-task-get-priority" title="g_task_get_priority ()"><code class="function">g_task_get_priority()</code></a>.</p> | |
| <div class="refsect3"> | |
| <a name="g-task-set-priority.parameters"></a><h4>Parameters</h4> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="parameters_name"> | |
| <col class="parameters_description"> | |
| <col width="200px" class="parameters_annotations"> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td class="parameter_name"><p>task</p></td> | |
| <td class="parameter_description"><p>the <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a></p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>priority</p></td> | |
| <td class="parameter_description"><p>the <a class="link" href="GAsyncResult.html#io-priority" title="I/O Priority">priority</a> of the request</p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| </tbody> | |
| </table></div> | |
| </div> | |
| <p class="since">Since: <a class="link" href="api-index-2-36.html#api-index-2.36">2.36</a></p> | |
| </div> | |
| <hr> | |
| <div class="refsect2"> | |
| <a name="g-task-set-check-cancellable"></a><h3>g_task_set_check_cancellable ()</h3> | |
| <pre class="programlisting"><span class="returnvalue">void</span> | |
| g_task_set_check_cancellable (<em class="parameter"><code><a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> *task</code></em>, | |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a> check_cancellable</code></em>);</pre> | |
| <p>Sets or clears <em class="parameter"><code>task</code></em> | |
| 's check-cancellable flag. If this is <a href="../glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> | |
| (the default), then <a class="link" href="GTask.html#g-task-propagate-pointer" title="g_task_propagate_pointer ()"><code class="function">g_task_propagate_pointer()</code></a>, etc, and | |
| <a class="link" href="GTask.html#g-task-had-error" title="g_task_had_error ()"><code class="function">g_task_had_error()</code></a> will check the task's <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> first, and | |
| if it has been cancelled, then they will consider the task to have | |
| returned an "Operation was cancelled" error | |
| (<a class="link" href="gio-GIOError.html#G-IO-ERROR-CANCELLED:CAPS"><code class="literal">G_IO_ERROR_CANCELLED</code></a>), regardless of any other error or return | |
| value the task may have had.</p> | |
| <p>If <em class="parameter"><code>check_cancellable</code></em> | |
| is <a href="../glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a>, then the <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> will not check the | |
| cancellable itself, and it is up to <em class="parameter"><code>task</code></em> | |
| 's owner to do this (eg, | |
| via <a class="link" href="GTask.html#g-task-return-error-if-cancelled" title="g_task_return_error_if_cancelled ()"><code class="function">g_task_return_error_if_cancelled()</code></a>).</p> | |
| <p>If you are using <a class="link" href="GTask.html#g-task-set-return-on-cancel" title="g_task_set_return_on_cancel ()"><code class="function">g_task_set_return_on_cancel()</code></a> as well, then | |
| you must leave check-cancellable set <a href="../glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a>.</p> | |
| <div class="refsect3"> | |
| <a name="g-task-set-check-cancellable.parameters"></a><h4>Parameters</h4> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="parameters_name"> | |
| <col class="parameters_description"> | |
| <col width="200px" class="parameters_annotations"> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td class="parameter_name"><p>task</p></td> | |
| <td class="parameter_description"><p>the <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a></p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>check_cancellable</p></td> | |
| <td class="parameter_description"><p>whether <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> will check the state of | |
| its <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> for you.</p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| </tbody> | |
| </table></div> | |
| </div> | |
| <p class="since">Since: <a class="link" href="api-index-2-36.html#api-index-2.36">2.36</a></p> | |
| </div> | |
| <hr> | |
| <div class="refsect2"> | |
| <a name="g-task-set-return-on-cancel"></a><h3>g_task_set_return_on_cancel ()</h3> | |
| <pre class="programlisting"><a href="../glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> | |
| g_task_set_return_on_cancel (<em class="parameter"><code><a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> *task</code></em>, | |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a> return_on_cancel</code></em>);</pre> | |
| <p>Sets or clears <em class="parameter"><code>task</code></em> | |
| 's return-on-cancel flag. This is only | |
| meaningful for tasks run via <a class="link" href="GTask.html#g-task-run-in-thread" title="g_task_run_in_thread ()"><code class="function">g_task_run_in_thread()</code></a> or | |
| <a class="link" href="GTask.html#g-task-run-in-thread-sync" title="g_task_run_in_thread_sync ()"><code class="function">g_task_run_in_thread_sync()</code></a>.</p> | |
| <p>If <em class="parameter"><code>return_on_cancel</code></em> | |
| is <a href="../glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a>, then cancelling <em class="parameter"><code>task</code></em> | |
| 's | |
| <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> will immediately cause it to return, as though the | |
| task's <a class="link" href="GTask.html#GTaskThreadFunc" title="GTaskThreadFunc ()"><span class="type">GTaskThreadFunc</span></a> had called | |
| <a class="link" href="GTask.html#g-task-return-error-if-cancelled" title="g_task_return_error_if_cancelled ()"><code class="function">g_task_return_error_if_cancelled()</code></a> and then returned.</p> | |
| <p>This allows you to create a cancellable wrapper around an | |
| uninterruptable function. The <a class="link" href="GTask.html#GTaskThreadFunc" title="GTaskThreadFunc ()"><span class="type">GTaskThreadFunc</span></a> 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 | |
| <a class="link" href="GTask.html#g-task-set-return-on-cancel" title="g_task_set_return_on_cancel ()"><code class="function">g_task_set_return_on_cancel()</code></a> again to (atomically) set | |
| return-on-cancel <a href="../glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> before making externally-visible changes; | |
| if the task gets cancelled before the return-on-cancel flag could | |
| be changed, <a class="link" href="GTask.html#g-task-set-return-on-cancel" title="g_task_set_return_on_cancel ()"><code class="function">g_task_set_return_on_cancel()</code></a> will indicate this by | |
| returning <a href="../glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a>.</p> | |
| <p>You can disable and re-enable this flag multiple times if you wish. | |
| If the task's <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> is cancelled while return-on-cancel is | |
| <a href="../glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a>, then calling <a class="link" href="GTask.html#g-task-set-return-on-cancel" title="g_task_set_return_on_cancel ()"><code class="function">g_task_set_return_on_cancel()</code></a> to set it <a href="../glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> | |
| again will cause the task to be cancelled at that point.</p> | |
| <p>If the task's <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> is already cancelled before you call | |
| <a class="link" href="GTask.html#g-task-run-in-thread" title="g_task_run_in_thread ()"><code class="function">g_task_run_in_thread()</code></a>/<a class="link" href="GTask.html#g-task-run-in-thread-sync" title="g_task_run_in_thread_sync ()"><code class="function">g_task_run_in_thread_sync()</code></a>, then the | |
| <a class="link" href="GTask.html#GTaskThreadFunc" title="GTaskThreadFunc ()"><span class="type">GTaskThreadFunc</span></a> will still be run (for consistency), but the task | |
| will also be completed right away.</p> | |
| <div class="refsect3"> | |
| <a name="g-task-set-return-on-cancel.parameters"></a><h4>Parameters</h4> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="parameters_name"> | |
| <col class="parameters_description"> | |
| <col width="200px" class="parameters_annotations"> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td class="parameter_name"><p>task</p></td> | |
| <td class="parameter_description"><p>the <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a></p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>return_on_cancel</p></td> | |
| <td class="parameter_description"><p>whether the task returns automatically when | |
| it is cancelled.</p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| </tbody> | |
| </table></div> | |
| </div> | |
| <div class="refsect3"> | |
| <a name="g-task-set-return-on-cancel.returns"></a><h4>Returns</h4> | |
| <p> <a href="../glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>task</code></em> | |
| 's return-on-cancel flag was changed to | |
| match <em class="parameter"><code>return_on_cancel</code></em> | |
| . <a href="../glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if <em class="parameter"><code>task</code></em> | |
| has already been | |
| cancelled.</p> | |
| </div> | |
| <p class="since">Since: <a class="link" href="api-index-2-36.html#api-index-2.36">2.36</a></p> | |
| </div> | |
| <hr> | |
| <div class="refsect2"> | |
| <a name="g-task-set-source-tag"></a><h3>g_task_set_source_tag ()</h3> | |
| <pre class="programlisting"><span class="returnvalue">void</span> | |
| g_task_set_source_tag (<em class="parameter"><code><a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> *task</code></em>, | |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> source_tag</code></em>);</pre> | |
| <p>Sets <em class="parameter"><code>task</code></em> | |
| '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 | |
| <a class="link" href="GTask.html#g-task-get-source-tag" title="g_task_get_source_tag ()"><code class="function">g_task_get_source_tag()</code></a> (or <a class="link" href="GAsyncResult.html#g-async-result-is-tagged" title="g_async_result_is_tagged ()"><code class="function">g_async_result_is_tagged()</code></a>) in the | |
| task's "finish" function, to figure out if the response came from a | |
| particular place.</p> | |
| <div class="refsect3"> | |
| <a name="g-task-set-source-tag.parameters"></a><h4>Parameters</h4> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="parameters_name"> | |
| <col class="parameters_description"> | |
| <col width="200px" class="parameters_annotations"> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td class="parameter_name"><p>task</p></td> | |
| <td class="parameter_description"><p>the <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a></p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>source_tag</p></td> | |
| <td class="parameter_description"><p>an opaque pointer indicating the source of this task</p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| </tbody> | |
| </table></div> | |
| </div> | |
| <p class="since">Since: <a class="link" href="api-index-2-36.html#api-index-2.36">2.36</a></p> | |
| </div> | |
| <hr> | |
| <div class="refsect2"> | |
| <a name="g-task-report-error"></a><h3>g_task_report_error ()</h3> | |
| <pre class="programlisting"><span class="returnvalue">void</span> | |
| g_task_report_error (<em class="parameter"><code><a href="../glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> source_object</code></em>, | |
| <em class="parameter"><code><a class="link" href="GAsyncResult.html#GAsyncReadyCallback" title="GAsyncReadyCallback ()"><span class="type">GAsyncReadyCallback</span></a> callback</code></em>, | |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> callback_data</code></em>, | |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> source_tag</code></em>, | |
| <em class="parameter"><code><a href="../glib-Error-Reporting.html#GError"><span class="type">GError</span></a> *error</code></em>);</pre> | |
| <p>Creates a <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> and then immediately calls <a class="link" href="GTask.html#g-task-return-error" title="g_task_return_error ()"><code class="function">g_task_return_error()</code></a> | |
| 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 <a class="link" href="GAsyncResult.html#g-async-result-is-tagged" title="g_async_result_is_tagged ()"><code class="function">g_async_result_is_tagged()</code></a> 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.</p> | |
| <p>See also <a class="link" href="GTask.html#g-task-report-new-error" title="g_task_report_new_error ()"><code class="function">g_task_report_new_error()</code></a>.</p> | |
| <div class="refsect3"> | |
| <a name="g-task-report-error.parameters"></a><h4>Parameters</h4> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="parameters_name"> | |
| <col class="parameters_description"> | |
| <col width="200px" class="parameters_annotations"> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td class="parameter_name"><p>source_object</p></td> | |
| <td class="parameter_description"><p> the <a href="../gobject-The-Base-Object-Type.html#GObject-struct"><span class="type">GObject</span></a> that owns | |
| this task, or <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p></td> | |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>][<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> GObject]</span></td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>callback</p></td> | |
| <td class="parameter_description"><p> a <a class="link" href="GAsyncResult.html#GAsyncReadyCallback" title="GAsyncReadyCallback ()"><span class="type">GAsyncReadyCallback</span></a>. </p></td> | |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="The callback is valid until first called."><span class="acronym">scope async</span></acronym>]</span></td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>callback_data</p></td> | |
| <td class="parameter_description"><p> user data passed to <em class="parameter"><code>callback</code></em> | |
| . </p></td> | |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="This parameter is a 'user_data', for callbacks; many bindings can pass NULL here."><span class="acronym">closure</span></acronym>]</span></td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>source_tag</p></td> | |
| <td class="parameter_description"><p>an opaque pointer indicating the source of this task</p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>error</p></td> | |
| <td class="parameter_description"><p> error to report. </p></td> | |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></td> | |
| </tr> | |
| </tbody> | |
| </table></div> | |
| </div> | |
| <p class="since">Since: <a class="link" href="api-index-2-36.html#api-index-2.36">2.36</a></p> | |
| </div> | |
| <hr> | |
| <div class="refsect2"> | |
| <a name="g-task-report-new-error"></a><h3>g_task_report_new_error ()</h3> | |
| <pre class="programlisting"><span class="returnvalue">void</span> | |
| g_task_report_new_error (<em class="parameter"><code><a href="../glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> source_object</code></em>, | |
| <em class="parameter"><code><a class="link" href="GAsyncResult.html#GAsyncReadyCallback" title="GAsyncReadyCallback ()"><span class="type">GAsyncReadyCallback</span></a> callback</code></em>, | |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> callback_data</code></em>, | |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> source_tag</code></em>, | |
| <em class="parameter"><code><a href="../glib-Quarks.html#GQuark"><span class="type">GQuark</span></a> domain</code></em>, | |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gint"><span class="type">gint</span></a> code</code></em>, | |
| <em class="parameter"><code>const <span class="type">char</span> *format</code></em>, | |
| <em class="parameter"><code>...</code></em>);</pre> | |
| <p>Creates a <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> and then immediately calls | |
| <a class="link" href="GTask.html#g-task-return-new-error" title="g_task_return_new_error ()"><code class="function">g_task_return_new_error()</code></a> 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 <a class="link" href="GAsyncResult.html#g-async-result-is-tagged" title="g_async_result_is_tagged ()"><code class="function">g_async_result_is_tagged()</code></a> 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.</p> | |
| <p>See also <a class="link" href="GTask.html#g-task-report-error" title="g_task_report_error ()"><code class="function">g_task_report_error()</code></a>.</p> | |
| <div class="refsect3"> | |
| <a name="g-task-report-new-error.parameters"></a><h4>Parameters</h4> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="parameters_name"> | |
| <col class="parameters_description"> | |
| <col width="200px" class="parameters_annotations"> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td class="parameter_name"><p>source_object</p></td> | |
| <td class="parameter_description"><p> the <a href="../gobject-The-Base-Object-Type.html#GObject-struct"><span class="type">GObject</span></a> that owns | |
| this task, or <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p></td> | |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>][<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> GObject]</span></td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>callback</p></td> | |
| <td class="parameter_description"><p> a <a class="link" href="GAsyncResult.html#GAsyncReadyCallback" title="GAsyncReadyCallback ()"><span class="type">GAsyncReadyCallback</span></a>. </p></td> | |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="The callback is valid until first called."><span class="acronym">scope async</span></acronym>]</span></td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>callback_data</p></td> | |
| <td class="parameter_description"><p> user data passed to <em class="parameter"><code>callback</code></em> | |
| . </p></td> | |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="This parameter is a 'user_data', for callbacks; many bindings can pass NULL here."><span class="acronym">closure</span></acronym>]</span></td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>source_tag</p></td> | |
| <td class="parameter_description"><p>an opaque pointer indicating the source of this task</p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>domain</p></td> | |
| <td class="parameter_description"><p>a <a href="../glib-Quarks.html#GQuark"><span class="type">GQuark</span></a>.</p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>code</p></td> | |
| <td class="parameter_description"><p>an error code.</p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>format</p></td> | |
| <td class="parameter_description"><p>a string with format characters.</p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>...</p></td> | |
| <td class="parameter_description"><p>a list of values to insert into <em class="parameter"><code>format</code></em> | |
| .</p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| </tbody> | |
| </table></div> | |
| </div> | |
| <p class="since">Since: <a class="link" href="api-index-2-36.html#api-index-2.36">2.36</a></p> | |
| </div> | |
| <hr> | |
| <div class="refsect2"> | |
| <a name="g-task-get-task-data"></a><h3>g_task_get_task_data ()</h3> | |
| <pre class="programlisting"><a href="../glib-Basic-Types.html#gpointer"><span class="returnvalue">gpointer</span></a> | |
| g_task_get_task_data (<em class="parameter"><code><a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> *task</code></em>);</pre> | |
| <p>Gets <em class="parameter"><code>task</code></em> | |
| 's <code class="literal">task_data</code>.</p> | |
| <div class="refsect3"> | |
| <a name="g-task-get-task-data.parameters"></a><h4>Parameters</h4> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="parameters_name"> | |
| <col class="parameters_description"> | |
| <col width="200px" class="parameters_annotations"> | |
| </colgroup> | |
| <tbody><tr> | |
| <td class="parameter_name"><p>task</p></td> | |
| <td class="parameter_description"><p>a <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a></p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr></tbody> | |
| </table></div> | |
| </div> | |
| <div class="refsect3"> | |
| <a name="g-task-get-task-data.returns"></a><h4>Returns</h4> | |
| <p> <em class="parameter"><code>task</code></em> | |
| 's <code class="literal">task_data</code>. </p> | |
| <p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p> | |
| </div> | |
| <p class="since">Since: <a class="link" href="api-index-2-36.html#api-index-2.36">2.36</a></p> | |
| </div> | |
| <hr> | |
| <div class="refsect2"> | |
| <a name="g-task-get-priority"></a><h3>g_task_get_priority ()</h3> | |
| <pre class="programlisting"><a href="../glib-Basic-Types.html#gint"><span class="returnvalue">gint</span></a> | |
| g_task_get_priority (<em class="parameter"><code><a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> *task</code></em>);</pre> | |
| <p>Gets <em class="parameter"><code>task</code></em> | |
| 's priority</p> | |
| <div class="refsect3"> | |
| <a name="g-task-get-priority.parameters"></a><h4>Parameters</h4> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="parameters_name"> | |
| <col class="parameters_description"> | |
| <col width="200px" class="parameters_annotations"> | |
| </colgroup> | |
| <tbody><tr> | |
| <td class="parameter_name"><p>task</p></td> | |
| <td class="parameter_description"><p>a <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a></p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr></tbody> | |
| </table></div> | |
| </div> | |
| <div class="refsect3"> | |
| <a name="g-task-get-priority.returns"></a><h4>Returns</h4> | |
| <p> <em class="parameter"><code>task</code></em> | |
| 's priority</p> | |
| </div> | |
| <p class="since">Since: <a class="link" href="api-index-2-36.html#api-index-2.36">2.36</a></p> | |
| </div> | |
| <hr> | |
| <div class="refsect2"> | |
| <a name="g-task-get-cancellable"></a><h3>g_task_get_cancellable ()</h3> | |
| <pre class="programlisting"><a class="link" href="GCancellable.html" title="GCancellable"><span class="returnvalue">GCancellable</span></a> * | |
| g_task_get_cancellable (<em class="parameter"><code><a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> *task</code></em>);</pre> | |
| <p>Gets <em class="parameter"><code>task</code></em> | |
| 's <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a></p> | |
| <div class="refsect3"> | |
| <a name="g-task-get-cancellable.parameters"></a><h4>Parameters</h4> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="parameters_name"> | |
| <col class="parameters_description"> | |
| <col width="200px" class="parameters_annotations"> | |
| </colgroup> | |
| <tbody><tr> | |
| <td class="parameter_name"><p>task</p></td> | |
| <td class="parameter_description"><p>a <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a></p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr></tbody> | |
| </table></div> | |
| </div> | |
| <div class="refsect3"> | |
| <a name="g-task-get-cancellable.returns"></a><h4>Returns</h4> | |
| <p> <em class="parameter"><code>task</code></em> | |
| 's <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a>. </p> | |
| <p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p> | |
| </div> | |
| <p class="since">Since: <a class="link" href="api-index-2-36.html#api-index-2.36">2.36</a></p> | |
| </div> | |
| <hr> | |
| <div class="refsect2"> | |
| <a name="g-task-get-check-cancellable"></a><h3>g_task_get_check_cancellable ()</h3> | |
| <pre class="programlisting"><a href="../glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> | |
| g_task_get_check_cancellable (<em class="parameter"><code><a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> *task</code></em>);</pre> | |
| <p>Gets <em class="parameter"><code>task</code></em> | |
| 's check-cancellable flag. See | |
| <a class="link" href="GTask.html#g-task-set-check-cancellable" title="g_task_set_check_cancellable ()"><code class="function">g_task_set_check_cancellable()</code></a> for more details.</p> | |
| <div class="refsect3"> | |
| <a name="g-task-get-check-cancellable.parameters"></a><h4>Parameters</h4> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="parameters_name"> | |
| <col class="parameters_description"> | |
| <col width="200px" class="parameters_annotations"> | |
| </colgroup> | |
| <tbody><tr> | |
| <td class="parameter_name"><p>task</p></td> | |
| <td class="parameter_description"><p>the <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a></p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr></tbody> | |
| </table></div> | |
| </div> | |
| <p class="since">Since: <a class="link" href="api-index-2-36.html#api-index-2.36">2.36</a></p> | |
| </div> | |
| <hr> | |
| <div class="refsect2"> | |
| <a name="g-task-get-return-on-cancel"></a><h3>g_task_get_return_on_cancel ()</h3> | |
| <pre class="programlisting"><a href="../glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> | |
| g_task_get_return_on_cancel (<em class="parameter"><code><a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> *task</code></em>);</pre> | |
| <p>Gets <em class="parameter"><code>task</code></em> | |
| 's return-on-cancel flag. See | |
| <a class="link" href="GTask.html#g-task-set-return-on-cancel" title="g_task_set_return_on_cancel ()"><code class="function">g_task_set_return_on_cancel()</code></a> for more details.</p> | |
| <div class="refsect3"> | |
| <a name="g-task-get-return-on-cancel.parameters"></a><h4>Parameters</h4> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="parameters_name"> | |
| <col class="parameters_description"> | |
| <col width="200px" class="parameters_annotations"> | |
| </colgroup> | |
| <tbody><tr> | |
| <td class="parameter_name"><p>task</p></td> | |
| <td class="parameter_description"><p>the <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a></p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr></tbody> | |
| </table></div> | |
| </div> | |
| <p class="since">Since: <a class="link" href="api-index-2-36.html#api-index-2.36">2.36</a></p> | |
| </div> | |
| <hr> | |
| <div class="refsect2"> | |
| <a name="g-task-get-context"></a><h3>g_task_get_context ()</h3> | |
| <pre class="programlisting"><a href="../glib-The-Main-Event-Loop.html#GMainContext"><span class="returnvalue">GMainContext</span></a> * | |
| g_task_get_context (<em class="parameter"><code><a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> *task</code></em>);</pre> | |
| <p>Gets the <a href="../glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a> that <em class="parameter"><code>task</code></em> | |
| will return its result in (that | |
| is, the context that was the | |
| <a href="../glib-The-Main-Event-Loop.html#g-main-context-push-thread-default">thread-default main context</a> | |
| at the point when <em class="parameter"><code>task</code></em> | |
| was created).</p> | |
| <p>This will always return a non-<a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> value, even if the task's | |
| context is the default <a href="../glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a>.</p> | |
| <div class="refsect3"> | |
| <a name="g-task-get-context.parameters"></a><h4>Parameters</h4> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="parameters_name"> | |
| <col class="parameters_description"> | |
| <col width="200px" class="parameters_annotations"> | |
| </colgroup> | |
| <tbody><tr> | |
| <td class="parameter_name"><p>task</p></td> | |
| <td class="parameter_description"><p>a <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a></p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr></tbody> | |
| </table></div> | |
| </div> | |
| <div class="refsect3"> | |
| <a name="g-task-get-context.returns"></a><h4>Returns</h4> | |
| <p> <em class="parameter"><code>task</code></em> | |
| 's <a href="../glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a>. </p> | |
| <p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p> | |
| </div> | |
| <p class="since">Since: <a class="link" href="api-index-2-36.html#api-index-2.36">2.36</a></p> | |
| </div> | |
| <hr> | |
| <div class="refsect2"> | |
| <a name="g-task-get-source-object"></a><h3>g_task_get_source_object ()</h3> | |
| <pre class="programlisting"><a href="../glib-Basic-Types.html#gpointer"><span class="returnvalue">gpointer</span></a> | |
| g_task_get_source_object (<em class="parameter"><code><a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> *task</code></em>);</pre> | |
| <p>Gets the source object from <em class="parameter"><code>task</code></em> | |
| . Like | |
| <a class="link" href="GAsyncResult.html#g-async-result-get-source-object" title="g_async_result_get_source_object ()"><code class="function">g_async_result_get_source_object()</code></a>, but does not ref the object.</p> | |
| <div class="refsect3"> | |
| <a name="g-task-get-source-object.parameters"></a><h4>Parameters</h4> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="parameters_name"> | |
| <col class="parameters_description"> | |
| <col width="200px" class="parameters_annotations"> | |
| </colgroup> | |
| <tbody><tr> | |
| <td class="parameter_name"><p>task</p></td> | |
| <td class="parameter_description"><p>a <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a></p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr></tbody> | |
| </table></div> | |
| </div> | |
| <div class="refsect3"> | |
| <a name="g-task-get-source-object.returns"></a><h4>Returns</h4> | |
| <p> <em class="parameter"><code>task</code></em> | |
| 's source object, or <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p> | |
| <p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>][<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> GObject]</span></p> | |
| </div> | |
| <p class="since">Since: <a class="link" href="api-index-2-36.html#api-index-2.36">2.36</a></p> | |
| </div> | |
| <hr> | |
| <div class="refsect2"> | |
| <a name="g-task-get-source-tag"></a><h3>g_task_get_source_tag ()</h3> | |
| <pre class="programlisting"><a href="../glib-Basic-Types.html#gpointer"><span class="returnvalue">gpointer</span></a> | |
| g_task_get_source_tag (<em class="parameter"><code><a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> *task</code></em>);</pre> | |
| <p>Gets <em class="parameter"><code>task</code></em> | |
| 's source tag. See <a class="link" href="GTask.html#g-task-set-source-tag" title="g_task_set_source_tag ()"><code class="function">g_task_set_source_tag()</code></a>.</p> | |
| <div class="refsect3"> | |
| <a name="g-task-get-source-tag.parameters"></a><h4>Parameters</h4> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="parameters_name"> | |
| <col class="parameters_description"> | |
| <col width="200px" class="parameters_annotations"> | |
| </colgroup> | |
| <tbody><tr> | |
| <td class="parameter_name"><p>task</p></td> | |
| <td class="parameter_description"><p>a <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a></p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr></tbody> | |
| </table></div> | |
| </div> | |
| <div class="refsect3"> | |
| <a name="g-task-get-source-tag.returns"></a><h4>Returns</h4> | |
| <p> <em class="parameter"><code>task</code></em> | |
| 's source tag. </p> | |
| <p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p> | |
| </div> | |
| <p class="since">Since: <a class="link" href="api-index-2-36.html#api-index-2.36">2.36</a></p> | |
| </div> | |
| <hr> | |
| <div class="refsect2"> | |
| <a name="g-task-return-boolean"></a><h3>g_task_return_boolean ()</h3> | |
| <pre class="programlisting"><span class="returnvalue">void</span> | |
| g_task_return_boolean (<em class="parameter"><code><a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> *task</code></em>, | |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a> result</code></em>);</pre> | |
| <p>Sets <em class="parameter"><code>task</code></em> | |
| 's result to <em class="parameter"><code>result</code></em> | |
| and completes the task (see | |
| <a class="link" href="GTask.html#g-task-return-pointer" title="g_task_return_pointer ()"><code class="function">g_task_return_pointer()</code></a> for more discussion of exactly what this | |
| means).</p> | |
| <div class="refsect3"> | |
| <a name="g-task-return-boolean.parameters"></a><h4>Parameters</h4> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="parameters_name"> | |
| <col class="parameters_description"> | |
| <col width="200px" class="parameters_annotations"> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td class="parameter_name"><p>task</p></td> | |
| <td class="parameter_description"><p>a <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a>.</p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>result</p></td> | |
| <td class="parameter_description"><p>the <a href="../glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a> result of a task function.</p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| </tbody> | |
| </table></div> | |
| </div> | |
| <p class="since">Since: <a class="link" href="api-index-2-36.html#api-index-2.36">2.36</a></p> | |
| </div> | |
| <hr> | |
| <div class="refsect2"> | |
| <a name="g-task-return-int"></a><h3>g_task_return_int ()</h3> | |
| <pre class="programlisting"><span class="returnvalue">void</span> | |
| g_task_return_int (<em class="parameter"><code><a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> *task</code></em>, | |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gssize"><span class="type">gssize</span></a> result</code></em>);</pre> | |
| <p>Sets <em class="parameter"><code>task</code></em> | |
| 's result to <em class="parameter"><code>result</code></em> | |
| and completes the task (see | |
| <a class="link" href="GTask.html#g-task-return-pointer" title="g_task_return_pointer ()"><code class="function">g_task_return_pointer()</code></a> for more discussion of exactly what this | |
| means).</p> | |
| <div class="refsect3"> | |
| <a name="g-task-return-int.parameters"></a><h4>Parameters</h4> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="parameters_name"> | |
| <col class="parameters_description"> | |
| <col width="200px" class="parameters_annotations"> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td class="parameter_name"><p>task</p></td> | |
| <td class="parameter_description"><p>a <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a>.</p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>result</p></td> | |
| <td class="parameter_description"><p>the integer (<a href="../glib-Basic-Types.html#gssize"><span class="type">gssize</span></a>) result of a task function.</p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| </tbody> | |
| </table></div> | |
| </div> | |
| <p class="since">Since: <a class="link" href="api-index-2-36.html#api-index-2.36">2.36</a></p> | |
| </div> | |
| <hr> | |
| <div class="refsect2"> | |
| <a name="g-task-return-pointer"></a><h3>g_task_return_pointer ()</h3> | |
| <pre class="programlisting"><span class="returnvalue">void</span> | |
| g_task_return_pointer (<em class="parameter"><code><a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> *task</code></em>, | |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> result</code></em>, | |
| <em class="parameter"><code><a href="../glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> result_destroy</code></em>);</pre> | |
| <p>Sets <em class="parameter"><code>task</code></em> | |
| 's result to <em class="parameter"><code>result</code></em> | |
| and completes the task. If <em class="parameter"><code>result</code></em> | |
| is not <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, then <em class="parameter"><code>result_destroy</code></em> | |
| will be used to free <em class="parameter"><code>result</code></em> | |
| if | |
| the caller does not take ownership of it with | |
| <a class="link" href="GTask.html#g-task-propagate-pointer" title="g_task_propagate_pointer ()"><code class="function">g_task_propagate_pointer()</code></a>.</p> | |
| <p>"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 <a href="../glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a>, or in the next | |
| iteration of the current <a href="../glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a>. For a task run via | |
| <a class="link" href="GTask.html#g-task-run-in-thread" title="g_task_run_in_thread ()"><code class="function">g_task_run_in_thread()</code></a> or <a class="link" href="GTask.html#g-task-run-in-thread-sync" title="g_task_run_in_thread_sync ()"><code class="function">g_task_run_in_thread_sync()</code></a>, calling this | |
| method will save <em class="parameter"><code>result</code></em> | |
| to be returned to the caller later, but | |
| the task will not actually be completed until the <a class="link" href="GTask.html#GTaskThreadFunc" title="GTaskThreadFunc ()"><span class="type">GTaskThreadFunc</span></a> | |
| exits.</p> | |
| <p>Note that since the task may be completed before returning from | |
| <a class="link" href="GTask.html#g-task-return-pointer" title="g_task_return_pointer ()"><code class="function">g_task_return_pointer()</code></a>, you cannot assume that <em class="parameter"><code>result</code></em> | |
| is still | |
| valid after calling this, unless you are still holding another | |
| reference on it.</p> | |
| <div class="refsect3"> | |
| <a name="g-task-return-pointer.parameters"></a><h4>Parameters</h4> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="parameters_name"> | |
| <col class="parameters_description"> | |
| <col width="200px" class="parameters_annotations"> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td class="parameter_name"><p>task</p></td> | |
| <td class="parameter_description"><p>a <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a></p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>result</p></td> | |
| <td class="parameter_description"><p> the pointer result of a task | |
| function. </p></td> | |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>][<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>result_destroy</p></td> | |
| <td class="parameter_description"><p> a <a href="../glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> function. </p></td> | |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> | |
| </tr> | |
| </tbody> | |
| </table></div> | |
| </div> | |
| <p class="since">Since: <a class="link" href="api-index-2-36.html#api-index-2.36">2.36</a></p> | |
| </div> | |
| <hr> | |
| <div class="refsect2"> | |
| <a name="g-task-return-error"></a><h3>g_task_return_error ()</h3> | |
| <pre class="programlisting"><span class="returnvalue">void</span> | |
| g_task_return_error (<em class="parameter"><code><a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> *task</code></em>, | |
| <em class="parameter"><code><a href="../glib-Error-Reporting.html#GError"><span class="type">GError</span></a> *error</code></em>);</pre> | |
| <p>Sets <em class="parameter"><code>task</code></em> | |
| 's result to <em class="parameter"><code>error</code></em> | |
| (which <em class="parameter"><code>task</code></em> | |
| assumes ownership of) | |
| and completes the task (see <a class="link" href="GTask.html#g-task-return-pointer" title="g_task_return_pointer ()"><code class="function">g_task_return_pointer()</code></a> for more | |
| discussion of exactly what this means).</p> | |
| <p>Note that since the task takes ownership of <em class="parameter"><code>error</code></em> | |
| , and since the | |
| task may be completed before returning from <a class="link" href="GTask.html#g-task-return-error" title="g_task_return_error ()"><code class="function">g_task_return_error()</code></a>, | |
| you cannot assume that <em class="parameter"><code>error</code></em> | |
| is still valid after calling this. | |
| Call <a href="../glib-Error-Reporting.html#g-error-copy"><code class="function">g_error_copy()</code></a> on the error if you need to keep a local copy | |
| as well.</p> | |
| <p>See also <a class="link" href="GTask.html#g-task-return-new-error" title="g_task_return_new_error ()"><code class="function">g_task_return_new_error()</code></a>.</p> | |
| <div class="refsect3"> | |
| <a name="g-task-return-error.parameters"></a><h4>Parameters</h4> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="parameters_name"> | |
| <col class="parameters_description"> | |
| <col width="200px" class="parameters_annotations"> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td class="parameter_name"><p>task</p></td> | |
| <td class="parameter_description"><p>a <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a>.</p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>error</p></td> | |
| <td class="parameter_description"><p> the <a href="../glib-Error-Reporting.html#GError"><span class="type">GError</span></a> result of a task function. </p></td> | |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></td> | |
| </tr> | |
| </tbody> | |
| </table></div> | |
| </div> | |
| <p class="since">Since: <a class="link" href="api-index-2-36.html#api-index-2.36">2.36</a></p> | |
| </div> | |
| <hr> | |
| <div class="refsect2"> | |
| <a name="g-task-return-new-error"></a><h3>g_task_return_new_error ()</h3> | |
| <pre class="programlisting"><span class="returnvalue">void</span> | |
| g_task_return_new_error (<em class="parameter"><code><a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> *task</code></em>, | |
| <em class="parameter"><code><a href="../glib-Quarks.html#GQuark"><span class="type">GQuark</span></a> domain</code></em>, | |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gint"><span class="type">gint</span></a> code</code></em>, | |
| <em class="parameter"><code>const <span class="type">char</span> *format</code></em>, | |
| <em class="parameter"><code>...</code></em>);</pre> | |
| <p>Sets <em class="parameter"><code>task</code></em> | |
| 's result to a new <a href="../glib-Error-Reporting.html#GError"><span class="type">GError</span></a> created from <em class="parameter"><code>domain</code></em> | |
| , <em class="parameter"><code>code</code></em> | |
| , | |
| <em class="parameter"><code>format</code></em> | |
| , and the remaining arguments, and completes the task (see | |
| <a class="link" href="GTask.html#g-task-return-pointer" title="g_task_return_pointer ()"><code class="function">g_task_return_pointer()</code></a> for more discussion of exactly what this | |
| means).</p> | |
| <p>See also <a class="link" href="GTask.html#g-task-return-error" title="g_task_return_error ()"><code class="function">g_task_return_error()</code></a>.</p> | |
| <div class="refsect3"> | |
| <a name="g-task-return-new-error.parameters"></a><h4>Parameters</h4> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="parameters_name"> | |
| <col class="parameters_description"> | |
| <col width="200px" class="parameters_annotations"> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td class="parameter_name"><p>task</p></td> | |
| <td class="parameter_description"><p>a <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a>.</p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>domain</p></td> | |
| <td class="parameter_description"><p>a <a href="../glib-Quarks.html#GQuark"><span class="type">GQuark</span></a>.</p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>code</p></td> | |
| <td class="parameter_description"><p>an error code.</p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>format</p></td> | |
| <td class="parameter_description"><p>a string with format characters.</p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>...</p></td> | |
| <td class="parameter_description"><p>a list of values to insert into <em class="parameter"><code>format</code></em> | |
| .</p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| </tbody> | |
| </table></div> | |
| </div> | |
| <p class="since">Since: <a class="link" href="api-index-2-36.html#api-index-2.36">2.36</a></p> | |
| </div> | |
| <hr> | |
| <div class="refsect2"> | |
| <a name="g-task-return-error-if-cancelled"></a><h3>g_task_return_error_if_cancelled ()</h3> | |
| <pre class="programlisting"><a href="../glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> | |
| g_task_return_error_if_cancelled (<em class="parameter"><code><a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> *task</code></em>);</pre> | |
| <p>Checks if <em class="parameter"><code>task</code></em> | |
| 's <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> has been cancelled, and if so, sets | |
| <em class="parameter"><code>task</code></em> | |
| 's error accordingly and completes the task (see | |
| <a class="link" href="GTask.html#g-task-return-pointer" title="g_task_return_pointer ()"><code class="function">g_task_return_pointer()</code></a> for more discussion of exactly what this | |
| means).</p> | |
| <div class="refsect3"> | |
| <a name="g-task-return-error-if-cancelled.parameters"></a><h4>Parameters</h4> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="parameters_name"> | |
| <col class="parameters_description"> | |
| <col width="200px" class="parameters_annotations"> | |
| </colgroup> | |
| <tbody><tr> | |
| <td class="parameter_name"><p>task</p></td> | |
| <td class="parameter_description"><p>a <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a></p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr></tbody> | |
| </table></div> | |
| </div> | |
| <div class="refsect3"> | |
| <a name="g-task-return-error-if-cancelled.returns"></a><h4>Returns</h4> | |
| <p> <a href="../glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>task</code></em> | |
| has been cancelled, <a href="../glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if not</p> | |
| </div> | |
| <p class="since">Since: <a class="link" href="api-index-2-36.html#api-index-2.36">2.36</a></p> | |
| </div> | |
| <hr> | |
| <div class="refsect2"> | |
| <a name="g-task-propagate-boolean"></a><h3>g_task_propagate_boolean ()</h3> | |
| <pre class="programlisting"><a href="../glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> | |
| g_task_propagate_boolean (<em class="parameter"><code><a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> *task</code></em>, | |
| <em class="parameter"><code><a href="../glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre> | |
| <p>Gets the result of <em class="parameter"><code>task</code></em> | |
| as a <a href="../glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a>.</p> | |
| <p>If the task resulted in an error, or was cancelled, then this will | |
| instead return <a href="../glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> and set <em class="parameter"><code>error</code></em> | |
| .</p> | |
| <p>Since this method transfers ownership of the return value (or | |
| error) to the caller, you may only call it once.</p> | |
| <div class="refsect3"> | |
| <a name="g-task-propagate-boolean.parameters"></a><h4>Parameters</h4> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="parameters_name"> | |
| <col class="parameters_description"> | |
| <col width="200px" class="parameters_annotations"> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td class="parameter_name"><p>task</p></td> | |
| <td class="parameter_description"><p>a <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a>.</p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>error</p></td> | |
| <td class="parameter_description"><p>return location for a <a href="../glib-Error-Reporting.html#GError"><span class="type">GError</span></a></p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| </tbody> | |
| </table></div> | |
| </div> | |
| <div class="refsect3"> | |
| <a name="g-task-propagate-boolean.returns"></a><h4>Returns</h4> | |
| <p> the task result, or <a href="../glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> on error</p> | |
| </div> | |
| <p class="since">Since: <a class="link" href="api-index-2-36.html#api-index-2.36">2.36</a></p> | |
| </div> | |
| <hr> | |
| <div class="refsect2"> | |
| <a name="g-task-propagate-int"></a><h3>g_task_propagate_int ()</h3> | |
| <pre class="programlisting"><a href="../glib-Basic-Types.html#gssize"><span class="returnvalue">gssize</span></a> | |
| g_task_propagate_int (<em class="parameter"><code><a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> *task</code></em>, | |
| <em class="parameter"><code><a href="../glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre> | |
| <p>Gets the result of <em class="parameter"><code>task</code></em> | |
| as an integer (<a href="../glib-Basic-Types.html#gssize"><span class="type">gssize</span></a>).</p> | |
| <p>If the task resulted in an error, or was cancelled, then this will | |
| instead return -1 and set <em class="parameter"><code>error</code></em> | |
| .</p> | |
| <p>Since this method transfers ownership of the return value (or | |
| error) to the caller, you may only call it once.</p> | |
| <div class="refsect3"> | |
| <a name="g-task-propagate-int.parameters"></a><h4>Parameters</h4> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="parameters_name"> | |
| <col class="parameters_description"> | |
| <col width="200px" class="parameters_annotations"> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td class="parameter_name"><p>task</p></td> | |
| <td class="parameter_description"><p>a <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a>.</p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>error</p></td> | |
| <td class="parameter_description"><p>return location for a <a href="../glib-Error-Reporting.html#GError"><span class="type">GError</span></a></p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| </tbody> | |
| </table></div> | |
| </div> | |
| <div class="refsect3"> | |
| <a name="g-task-propagate-int.returns"></a><h4>Returns</h4> | |
| <p> the task result, or -1 on error</p> | |
| </div> | |
| <p class="since">Since: <a class="link" href="api-index-2-36.html#api-index-2.36">2.36</a></p> | |
| </div> | |
| <hr> | |
| <div class="refsect2"> | |
| <a name="g-task-propagate-pointer"></a><h3>g_task_propagate_pointer ()</h3> | |
| <pre class="programlisting"><a href="../glib-Basic-Types.html#gpointer"><span class="returnvalue">gpointer</span></a> | |
| g_task_propagate_pointer (<em class="parameter"><code><a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> *task</code></em>, | |
| <em class="parameter"><code><a href="../glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre> | |
| <p>Gets the result of <em class="parameter"><code>task</code></em> | |
| as a pointer, and transfers ownership | |
| of that value to the caller.</p> | |
| <p>If the task resulted in an error, or was cancelled, then this will | |
| instead return <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> and set <em class="parameter"><code>error</code></em> | |
| .</p> | |
| <p>Since this method transfers ownership of the return value (or | |
| error) to the caller, you may only call it once.</p> | |
| <div class="refsect3"> | |
| <a name="g-task-propagate-pointer.parameters"></a><h4>Parameters</h4> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="parameters_name"> | |
| <col class="parameters_description"> | |
| <col width="200px" class="parameters_annotations"> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td class="parameter_name"><p>task</p></td> | |
| <td class="parameter_description"><p>a <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a></p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>error</p></td> | |
| <td class="parameter_description"><p>return location for a <a href="../glib-Error-Reporting.html#GError"><span class="type">GError</span></a></p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| </tbody> | |
| </table></div> | |
| </div> | |
| <div class="refsect3"> | |
| <a name="g-task-propagate-pointer.returns"></a><h4>Returns</h4> | |
| <p> the task result, or <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> on error. </p> | |
| <p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> | |
| </div> | |
| <p class="since">Since: <a class="link" href="api-index-2-36.html#api-index-2.36">2.36</a></p> | |
| </div> | |
| <hr> | |
| <div class="refsect2"> | |
| <a name="g-task-had-error"></a><h3>g_task_had_error ()</h3> | |
| <pre class="programlisting"><a href="../glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> | |
| g_task_had_error (<em class="parameter"><code><a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> *task</code></em>);</pre> | |
| <p>Tests if <em class="parameter"><code>task</code></em> | |
| resulted in an error.</p> | |
| <div class="refsect3"> | |
| <a name="g-task-had-error.parameters"></a><h4>Parameters</h4> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="parameters_name"> | |
| <col class="parameters_description"> | |
| <col width="200px" class="parameters_annotations"> | |
| </colgroup> | |
| <tbody><tr> | |
| <td class="parameter_name"><p>task</p></td> | |
| <td class="parameter_description"><p>a <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a>.</p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr></tbody> | |
| </table></div> | |
| </div> | |
| <div class="refsect3"> | |
| <a name="g-task-had-error.returns"></a><h4>Returns</h4> | |
| <p> <a href="../glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if the task resulted in an error, <a href="../glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> otherwise.</p> | |
| </div> | |
| <p class="since">Since: <a class="link" href="api-index-2-36.html#api-index-2.36">2.36</a></p> | |
| </div> | |
| <hr> | |
| <div class="refsect2"> | |
| <a name="g-task-get-completed"></a><h3>g_task_get_completed ()</h3> | |
| <pre class="programlisting"><a href="../glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> | |
| g_task_get_completed (<em class="parameter"><code><a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> *task</code></em>);</pre> | |
| <p>Gets the value of <a class="link" href="GTask.html#GTask--completed" title="The “completed” property"><span class="type">“completed”</span></a>. This changes from <a href="../glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> to <a href="../glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> after | |
| the task’s callback is invoked, and will return <a href="../glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if called from inside | |
| the callback.</p> | |
| <div class="refsect3"> | |
| <a name="g-task-get-completed.parameters"></a><h4>Parameters</h4> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="parameters_name"> | |
| <col class="parameters_description"> | |
| <col width="200px" class="parameters_annotations"> | |
| </colgroup> | |
| <tbody><tr> | |
| <td class="parameter_name"><p>task</p></td> | |
| <td class="parameter_description"><p>a <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a>.</p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr></tbody> | |
| </table></div> | |
| </div> | |
| <div class="refsect3"> | |
| <a name="g-task-get-completed.returns"></a><h4>Returns</h4> | |
| <p> <a href="../glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if the task has completed, <a href="../glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> otherwise.</p> | |
| </div> | |
| <p class="since">Since: <a class="link" href="api-index-2-44.html#api-index-2.44">2.44</a></p> | |
| </div> | |
| <hr> | |
| <div class="refsect2"> | |
| <a name="g-task-run-in-thread"></a><h3>g_task_run_in_thread ()</h3> | |
| <pre class="programlisting"><span class="returnvalue">void</span> | |
| g_task_run_in_thread (<em class="parameter"><code><a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> *task</code></em>, | |
| <em class="parameter"><code><a class="link" href="GTask.html#GTaskThreadFunc" title="GTaskThreadFunc ()"><span class="type">GTaskThreadFunc</span></a> task_func</code></em>);</pre> | |
| <p>Runs <em class="parameter"><code>task_func</code></em> | |
| in another thread. When <em class="parameter"><code>task_func</code></em> | |
| returns, <em class="parameter"><code>task</code></em> | |
| 's | |
| <a class="link" href="GAsyncResult.html#GAsyncReadyCallback" title="GAsyncReadyCallback ()"><span class="type">GAsyncReadyCallback</span></a> will be invoked in <em class="parameter"><code>task</code></em> | |
| 's <a href="../glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a>.</p> | |
| <p>This takes a ref on <em class="parameter"><code>task</code></em> | |
| until the task completes.</p> | |
| <p>See <a class="link" href="GTask.html#GTaskThreadFunc" title="GTaskThreadFunc ()"><span class="type">GTaskThreadFunc</span></a> for more details about how <em class="parameter"><code>task_func</code></em> | |
| is handled.</p> | |
| <p>Although GLib currently rate-limits the tasks queued via | |
| <a class="link" href="GTask.html#g-task-run-in-thread" title="g_task_run_in_thread ()"><code class="function">g_task_run_in_thread()</code></a>, you should not assume that it will always | |
| do this. If you have a very large number of tasks to run, but don't | |
| want them to all run at once, you should only queue a limited | |
| number of them at a time.</p> | |
| <div class="refsect3"> | |
| <a name="g-task-run-in-thread.parameters"></a><h4>Parameters</h4> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="parameters_name"> | |
| <col class="parameters_description"> | |
| <col width="200px" class="parameters_annotations"> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td class="parameter_name"><p>task</p></td> | |
| <td class="parameter_description"><p>a <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a></p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>task_func</p></td> | |
| <td class="parameter_description"><p>a <a class="link" href="GTask.html#GTaskThreadFunc" title="GTaskThreadFunc ()"><span class="type">GTaskThreadFunc</span></a></p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| </tbody> | |
| </table></div> | |
| </div> | |
| <p class="since">Since: <a class="link" href="api-index-2-36.html#api-index-2.36">2.36</a></p> | |
| </div> | |
| <hr> | |
| <div class="refsect2"> | |
| <a name="g-task-run-in-thread-sync"></a><h3>g_task_run_in_thread_sync ()</h3> | |
| <pre class="programlisting"><span class="returnvalue">void</span> | |
| g_task_run_in_thread_sync (<em class="parameter"><code><a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> *task</code></em>, | |
| <em class="parameter"><code><a class="link" href="GTask.html#GTaskThreadFunc" title="GTaskThreadFunc ()"><span class="type">GTaskThreadFunc</span></a> task_func</code></em>);</pre> | |
| <p>Runs <em class="parameter"><code>task_func</code></em> | |
| in another thread, and waits for it to return or be | |
| cancelled. You can use <a class="link" href="GTask.html#g-task-propagate-pointer" title="g_task_propagate_pointer ()"><code class="function">g_task_propagate_pointer()</code></a>, etc, afterward | |
| to get the result of <em class="parameter"><code>task_func</code></em> | |
| .</p> | |
| <p>See <a class="link" href="GTask.html#GTaskThreadFunc" title="GTaskThreadFunc ()"><span class="type">GTaskThreadFunc</span></a> for more details about how <em class="parameter"><code>task_func</code></em> | |
| is handled.</p> | |
| <p>Normally this is used with tasks created with a <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> | |
| <code class="literal">callback</code>, but note that even if the task does | |
| have a callback, it will not be invoked when <em class="parameter"><code>task_func</code></em> | |
| returns. | |
| <a class="link" href="GTask.html#GTask--completed" title="The “completed” property"><span class="type">“completed”</span></a> will be set to <a href="../glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> just before this function returns.</p> | |
| <p>Although GLib currently rate-limits the tasks queued via | |
| <a class="link" href="GTask.html#g-task-run-in-thread-sync" title="g_task_run_in_thread_sync ()"><code class="function">g_task_run_in_thread_sync()</code></a>, you should not assume that it will | |
| always do this. If you have a very large number of tasks to run, | |
| but don't want them to all run at once, you should only queue a | |
| limited number of them at a time.</p> | |
| <div class="refsect3"> | |
| <a name="g-task-run-in-thread-sync.parameters"></a><h4>Parameters</h4> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="parameters_name"> | |
| <col class="parameters_description"> | |
| <col width="200px" class="parameters_annotations"> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td class="parameter_name"><p>task</p></td> | |
| <td class="parameter_description"><p>a <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a></p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>task_func</p></td> | |
| <td class="parameter_description"><p>a <a class="link" href="GTask.html#GTaskThreadFunc" title="GTaskThreadFunc ()"><span class="type">GTaskThreadFunc</span></a></p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| </tbody> | |
| </table></div> | |
| </div> | |
| <p class="since">Since: <a class="link" href="api-index-2-36.html#api-index-2.36">2.36</a></p> | |
| </div> | |
| <hr> | |
| <div class="refsect2"> | |
| <a name="GTaskThreadFunc"></a><h3>GTaskThreadFunc ()</h3> | |
| <pre class="programlisting"><span class="returnvalue">void</span> | |
| <span class="c_punctuation">(</span>*GTaskThreadFunc<span class="c_punctuation">)</span> (<em class="parameter"><code><a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> *task</code></em>, | |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> source_object</code></em>, | |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> task_data</code></em>, | |
| <em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>);</pre> | |
| <p>The prototype for a task function to be run in a thread via | |
| <a class="link" href="GTask.html#g-task-run-in-thread" title="g_task_run_in_thread ()"><code class="function">g_task_run_in_thread()</code></a> or <a class="link" href="GTask.html#g-task-run-in-thread-sync" title="g_task_run_in_thread_sync ()"><code class="function">g_task_run_in_thread_sync()</code></a>.</p> | |
| <p>If the return-on-cancel flag is set on <em class="parameter"><code>task</code></em> | |
| , and <em class="parameter"><code>cancellable</code></em> | |
| gets | |
| cancelled, then the <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> will be completed immediately (as though | |
| <a class="link" href="GTask.html#g-task-return-error-if-cancelled" title="g_task_return_error_if_cancelled ()"><code class="function">g_task_return_error_if_cancelled()</code></a> 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 | |
| <a class="link" href="GTask.html#g-task-set-return-on-cancel" title="g_task_set_return_on_cancel ()"><code class="function">g_task_set_return_on_cancel()</code></a> for more details.</p> | |
| <p>Other than in that case, <em class="parameter"><code>task</code></em> | |
| will be completed when the | |
| <a class="link" href="GTask.html#GTaskThreadFunc" title="GTaskThreadFunc ()"><span class="type">GTaskThreadFunc</span></a> returns, not when it calls a | |
| <code class="literal">g_task_return_</code> function.</p> | |
| <div class="refsect3"> | |
| <a name="GTaskThreadFunc.parameters"></a><h4>Parameters</h4> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="parameters_name"> | |
| <col class="parameters_description"> | |
| <col width="200px" class="parameters_annotations"> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td class="parameter_name"><p>task</p></td> | |
| <td class="parameter_description"><p>the <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a></p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>source_object</p></td> | |
| <td class="parameter_description"><p> <em class="parameter"><code>task</code></em> | |
| 's source object. </p></td> | |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> GObject]</span></td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>task_data</p></td> | |
| <td class="parameter_description"><p><em class="parameter"><code>task</code></em> | |
| 's task data</p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>cancellable</p></td> | |
| <td class="parameter_description"><p><em class="parameter"><code>task</code></em> | |
| 's <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a>, or <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| </tbody> | |
| </table></div> | |
| </div> | |
| <p class="since">Since: <a class="link" href="api-index-2-36.html#api-index-2.36">2.36</a></p> | |
| </div> | |
| <hr> | |
| <div class="refsect2"> | |
| <a name="g-task-attach-source"></a><h3>g_task_attach_source ()</h3> | |
| <pre class="programlisting"><span class="returnvalue">void</span> | |
| g_task_attach_source (<em class="parameter"><code><a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a> *task</code></em>, | |
| <em class="parameter"><code><a href="../glib-The-Main-Event-Loop.html#GSource"><span class="type">GSource</span></a> *source</code></em>, | |
| <em class="parameter"><code><a href="../glib-The-Main-Event-Loop.html#GSourceFunc"><span class="type">GSourceFunc</span></a> callback</code></em>);</pre> | |
| <p>A utility function for dealing with async operations where you need | |
| to wait for a <a href="../glib-The-Main-Event-Loop.html#GSource"><span class="type">GSource</span></a> to trigger. Attaches <em class="parameter"><code>source</code></em> | |
| to <em class="parameter"><code>task</code></em> | |
| 's | |
| <a href="../glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a> with <em class="parameter"><code>task</code></em> | |
| 's <a class="link" href="GAsyncResult.html#io-priority" title="I/O Priority">priority</a>, and sets <em class="parameter"><code>source</code></em> | |
| 's | |
| callback to <em class="parameter"><code>callback</code></em> | |
| , with <em class="parameter"><code>task</code></em> | |
| as the callback's <code class="literal">user_data</code>.</p> | |
| <p>This takes a reference on <em class="parameter"><code>task</code></em> | |
| until <em class="parameter"><code>source</code></em> | |
| is destroyed.</p> | |
| <div class="refsect3"> | |
| <a name="g-task-attach-source.parameters"></a><h4>Parameters</h4> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="parameters_name"> | |
| <col class="parameters_description"> | |
| <col width="200px" class="parameters_annotations"> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td class="parameter_name"><p>task</p></td> | |
| <td class="parameter_description"><p>a <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a></p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>source</p></td> | |
| <td class="parameter_description"><p>the source to attach</p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>callback</p></td> | |
| <td class="parameter_description"><p>the callback to invoke when <em class="parameter"><code>source</code></em> | |
| triggers</p></td> | |
| <td class="parameter_annotations"> </td> | |
| </tr> | |
| </tbody> | |
| </table></div> | |
| </div> | |
| <p class="since">Since: <a class="link" href="api-index-2-36.html#api-index-2.36">2.36</a></p> | |
| </div> | |
| <hr> | |
| <div class="refsect2"> | |
| <a name="g-task-is-valid"></a><h3>g_task_is_valid ()</h3> | |
| <pre class="programlisting"><a href="../glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> | |
| g_task_is_valid (<em class="parameter"><code><a href="../glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> result</code></em>, | |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> source_object</code></em>);</pre> | |
| <p>Checks that <em class="parameter"><code>result</code></em> | |
| is a <a class="link" href="GTask.html" title="GTask"><span class="type">GTask</span></a>, and that <em class="parameter"><code>source_object</code></em> | |
| is its | |
| source object (or that <em class="parameter"><code>source_object</code></em> | |
| is <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> and <em class="parameter"><code>result</code></em> | |
| has no | |
| source object). This can be used in <a href="../glib-Warnings-and-Assertions.html#g-return-if-fail"><code class="function">g_return_if_fail()</code></a> checks.</p> | |
| <div class="refsect3"> | |
| <a name="g-task-is-valid.parameters"></a><h4>Parameters</h4> | |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> | |
| <colgroup> | |
| <col width="150px" class="parameters_name"> | |
| <col class="parameters_description"> | |
| <col width="200px" class="parameters_annotations"> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td class="parameter_name"><p>result</p></td> | |
| <td class="parameter_description"><p> A <a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a>. </p></td> | |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> Gio.AsyncResult]</span></td> | |
| </tr> | |
| <tr> | |
| <td class="parameter_name"><p>source_object</p></td> | |
| <td class="parameter_description"><p> the source object | |
| expected to be associated with the task. </p></td> | |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>][<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> GObject]</span></td> | |
| </tr> | |
| </tbody> | |
| </table></div> | |
| </div> | |
| <div class="refsect3"> | |
| <a name="g-task-is-valid.returns"></a><h4>Returns</h4> | |
| <p> <a href="../glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>result</code></em> | |
| and <em class="parameter"><code>source_object</code></em> | |
| are valid, <a href="../glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> | |
| if not</p> | |
| </div> | |
| <p class="since">Since: <a class="link" href="api-index-2-36.html#api-index-2.36">2.36</a></p> | |
| </div> | |
| </div> | |
| <div class="refsect1"> | |
| <a name="GTask.other_details"></a><h2>Types and Values</h2> | |
| <div class="refsect2"> | |
| <a name="GTask-struct"></a><h3>GTask</h3> | |
| <pre class="programlisting">typedef struct _GTask GTask;</pre> | |
| <p>The opaque object representing a synchronous or asynchronous task | |
| and its result.</p> | |
| </div> | |
| </div> | |
| <div class="refsect1"> | |
| <a name="GTask.property-details"></a><h2>Property Details</h2> | |
| <div class="refsect2"> | |
| <a name="GTask--completed"></a><h3>The <code class="literal">“completed”</code> property</h3> | |
| <pre class="programlisting"> “completed” <a href="../glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></pre> | |
| <p>Whether the task has completed, meaning its callback (if set) has been | |
| invoked. This can only happen after <a class="link" href="GTask.html#g-task-return-pointer" title="g_task_return_pointer ()"><code class="function">g_task_return_pointer()</code></a>, | |
| <a class="link" href="GTask.html#g-task-return-error" title="g_task_return_error ()"><code class="function">g_task_return_error()</code></a> or one of the other return functions have been called | |
| on the task.</p> | |
| <p>This property is guaranteed to change from <a href="../glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> to <a href="../glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> exactly once.</p> | |
| <p>The <a href="../gobject-The-Base-Object-Type.html#GObject-notify"><span class="type">“notify”</span></a> signal for this change is emitted in the same main | |
| context as the task’s callback, immediately after that callback is invoked.</p> | |
| <p>Flags: Read</p> | |
| <p>Default value: FALSE</p> | |
| <p class="since">Since: <a class="link" href="api-index-2-44.html#api-index-2.44">2.44</a></p> | |
| </div> | |
| </div> | |
| <div class="refsect1"> | |
| <a name="GTask.see-also"></a><h2>See Also</h2> | |
| <p><a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a></p> | |
| </div> | |
| </div> | |
| <div class="footer"> | |
| <hr>Generated by GTK-Doc V1.25.1</div> | |
| </body> | |
| </html> |