← Back to branch summary

~ubuntu-branches/ubuntu/trusty/glib2.0/trusty-proposed

« back to all changes in this revision

Viewing changes to docs/reference/gio/xml/gasyncresult.xml

  • Committer: Bazaar Package Importer
  • Author(s): Sebastien Bacher
  • Date: 2010-03-09 11:28:22 UTC
  • mfrom: (3.4.8 experimental)
  • Revision ID: james.westby@ubuntu.com-20100309112822-j4n0v3xbtsup8s97
Tags: 2.23.5-1ubuntu1
* Resync on Debian
* debian/patches/01_gettext-desktopfiles.patch:
  - updated to use gettext for X-GNOME-Fullname too
* debian/patches/71_gio_launch_handler.patch:
  - new gio default launch handle feature required for wncksync
* debian/control.in, 
  debian/patches/80-gtester-subunit.patch:
  - gtester-report subunit support
* debian/libglib2.0-0.symbols:
  - updated the symbols list for the gio launcher handler
* debian/rules:
  - don't break build on test suite errors, debian recently activated this but
    the build breaks even when there is no error in the testsuite

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/reference/gio/xml/gasyncresult.xml
 
1
<?xml version="1.0"?>
 
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
 
3
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
 
4
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
 
5
<!ENTITY version SYSTEM "version.xml">
 
6
]>
 
7
<refentry id="GAsyncResult">
 
8
<refmeta>
 
9
<refentrytitle role="top_of_page" id="GAsyncResult.top_of_page">GAsyncResult</refentrytitle>
 
10
<manvolnum>3</manvolnum>
 
11
<refmiscinfo>GIO Library</refmiscinfo>
 
12
</refmeta>
 
13
 
 
14
<refnamediv>
 
15
<refname>GAsyncResult</refname>
 
16
<refpurpose>Asynchronous Function Results</refpurpose>
 
17
</refnamediv>
 
18
 
 
19
<refsynopsisdiv id="GAsyncResult.synopsis" role="synopsis">
 
20
<title role="synopsis.title">Synopsis</title>
 
21
 
 
22
<synopsis>
 
23
 
 
24
#include &lt;gio/gio.h&gt;
 
25
 
 
26
                    <link linkend="GAsyncResult-struct">GAsyncResult</link>;
 
27
                    <link linkend="GAsyncResultIface">GAsyncResultIface</link>;
 
28
<link linkend="void">void</link>                (<link linkend="GAsyncReadyCallback">*GAsyncReadyCallback</link>)              (<link linkend="GObject">GObject</link> *source_object,
 
29
                                                         <link linkend="GAsyncResult">GAsyncResult</link> *res,
 
30
                                                         <link linkend="gpointer">gpointer</link> user_data);
 
31
<link linkend="gpointer">gpointer</link>            <link linkend="g-async-result-get-user-data">g_async_result_get_user_data</link>        (<link linkend="GAsyncResult">GAsyncResult</link> *res);
 
32
<link linkend="GObject">GObject</link> *           <link linkend="g-async-result-get-source-object">g_async_result_get_source_object</link>    (<link linkend="GAsyncResult">GAsyncResult</link> *res);
 
33
</synopsis>
 
34
</refsynopsisdiv>
 
35
 
 
36
<refsect1 id="GAsyncResult.object-hierarchy" role="object_hierarchy">
 
37
<title role="object_hierarchy.title">Object Hierarchy</title>
 
38
<synopsis>
 
39
  <link linkend="GInterface">GInterface</link>
 
40
   +----GAsyncResult
 
41
</synopsis>
 
42
</refsect1>
 
43
 
 
44
<refsect1 id="GAsyncResult.prerequisites" role="prerequisites">
 
45
<title role="prerequisites.title">Prerequisites</title>
 
46
<para>
 
47
GAsyncResult requires
 
48
 <link linkend="GObject">GObject</link>.</para>
 
49
</refsect1>
 
50
 
 
51
 
 
52
 
 
53
<refsect1 id="GAsyncResult.implementations" role="implementations">
 
54
<title role="implementations.title">Known Implementations</title>
 
55
<para>
 
56
GAsyncResult is implemented by
 
57
 <link linkend="GSimpleAsyncResult">GSimpleAsyncResult</link>.</para>
 
58
</refsect1>
 
59
 
 
60
 
 
61
 
 
62
 
 
63
<refsect1 id="GAsyncResult.description" role="desc">
 
64
<title role="desc.title">Description</title>
 
65
<para>
 
66
Provides a base class for implementing asynchronous function results.
 
67
</para>
 
68
<para>
 
69
Asynchronous operations are broken up into two separate operations
 
70
which are chained together by a <link linkend="GAsyncReadyCallback"><type>GAsyncReadyCallback</type></link>. To begin
 
71
an asynchronous operation, provide a <link linkend="GAsyncReadyCallback"><type>GAsyncReadyCallback</type></link> to the
 
72
asynchronous function. This callback will be triggered when the
 
73
operation has completed, and will be passed a <link linkend="GAsyncResult"><type>GAsyncResult</type></link> instance
 
74
filled with the details of the operation's success or failure, the
 
75
object the asynchronous function was started for and any error codes
 
76
returned. The asynchronous callback function is then expected to call
 
77
the corresponding "<link linkend="finish"><function>_finish()</function></link>" function, passing the object the
 
78
function was called for, the <link linkend="GAsyncResult"><type>GAsyncResult</type></link> instance, and (optionally)
 
79
an <parameter>error</parameter> to grab any error conditions that may have occurred.
 
80
</para>
 
81
<para>
 
82
The "<link linkend="finish"><function>_finish()</function></link>" function for an operation takes the generic result
 
83
(of type <link linkend="GAsyncResult"><type>GAsyncResult</type></link>) and returns the specific result that the
 
84
operation in question yields (e.g. a <link linkend="GFileEnumerator"><type>GFileEnumerator</type></link> for a
 
85
"enumerate children" operation). If the result or error status of the
 
86
operation is not needed, there is no need to call the "<link linkend="finish"><function>_finish()</function></link>"
 
87
function; GIO will take care of cleaning up the result and error
 
88
information after the <link linkend="GAsyncReadyCallback"><type>GAsyncReadyCallback</type></link> returns. Applications may
 
89
also take a reference to the <link linkend="GAsyncResult"><type>GAsyncResult</type></link> and call "<link linkend="finish"><function>_finish()</function></link>"
 
90
later; however, the "<link linkend="finish"><function>_finish()</function></link>" function may be called at most once.
 
91
</para>
 
92
<para>
 
93
Example of a typical asynchronous operation flow:
 
94
<informalexample><programlisting>
 
95
void _theoretical_frobnitz_async (Theoretical         *t,
 
96
                                  GCancellable        *c,
 
97
                                  GAsyncReadyCallback *cb,
 
98
                                  gpointer             u);
 
99
 
 
100
gboolean _theoretical_frobnitz_finish (Theoretical   *t,
 
101
                                       GAsyncResult  *res,
 
102
                                       GError       **e);
 
103
 
 
104
static void
 
105
frobnitz_result_func (GObject      *source_object,
 
106
                 GAsyncResult *res,
 
107
                 gpointer      user_data)
 
108
{
 
109
  gboolean success = FALSE;
 
110
 
 
111
  success = _theoretical_frobnitz_finish (source_object, res, NULL);
 
112
 
 
113
  if (success)
 
114
    g_printf ("Hurray!\n");
 
115
  else
 
116
    g_printf ("Uh oh!\n");
 
117
 
 
118
  /<!-- -->* ... *<!-- -->/
 
119
 
 
120
}
 
121
 
 
122
int main (int argc, void *argv[])
 
123
{
 
124
   /<!-- -->* ... *<!-- -->/
 
125
 
 
126
   _theoretical_frobnitz_async (theoretical_data,
 
127
                                NULL,
 
128
                                frobnitz_result_func,
 
129
                                NULL);
 
130
 
 
131
   /<!-- -->* ... *<!-- -->/
 
132
}
 
133
</programlisting></informalexample>
 
134
</para>
 
135
<para>
 
136
The callback for an asynchronous operation is called only once, and is
 
137
always called, even in the case of a cancelled operation. On cancellation
 
138
the result is a <link linkend="G-IO-ERROR-CANCELLED--CAPS"><literal>G_IO_ERROR_CANCELLED</literal></link> error.
 
139
</para>
 
140
<para>
 
141
Some asynchronous operations are implemented using synchronous calls.
 
142
These are run in a separate thread, if <link linkend="GThread"><type>GThread</type></link> has been initialized, but
 
143
otherwise they are sent to the Main Event Loop and processed in an idle
 
144
function. So, if you truly need asynchronous operations, make sure to
 
145
initialize <link linkend="GThread"><type>GThread</type></link>.</para>
 
146
<para>
 
147
</para>
 
148
</refsect1>
 
149
 
 
150
<refsect1 id="GAsyncResult.details" role="details">
 
151
<title role="details.title">Details</title>
 
152
<refsect2 id="GAsyncResult-struct" role="struct">
 
153
<title>GAsyncResult</title>
 
154
<indexterm zone="GAsyncResult-struct"><primary sortas="AsyncResult">GAsyncResult</primary></indexterm><programlisting>typedef struct _GAsyncResult GAsyncResult;</programlisting>
 
155
<para>
 
156
Holds results information for an asynchronous operation,
 
157
usually passed directly to a asynchronous <link linkend="finish"><function>_finish()</function></link> operation.</para>
 
158
<para>
 
159
</para></refsect2>
 
160
<refsect2 id="GAsyncResultIface" role="struct">
 
161
<title>GAsyncResultIface</title>
 
162
<indexterm zone="GAsyncResultIface"><primary sortas="AsyncResultIface">GAsyncResultIface</primary></indexterm><programlisting>typedef struct {
 
163
  GTypeInterface g_iface;
 
164
 
 
165
  /* Virtual Table */
 
166
 
 
167
  gpointer  (* get_user_data)     (GAsyncResult *async_result);
 
168
  GObject * (* get_source_object) (GAsyncResult *async_result);
 
169
} GAsyncResultIface;
 
170
</programlisting>
 
171
<para>
 
172
Interface definition for <link linkend="GAsyncResult"><type>GAsyncResult</type></link>.</para>
 
173
<para>
 
174
</para><variablelist role="struct">
 
175
<varlistentry>
 
176
<term><link linkend="GTypeInterface">GTypeInterface</link>&#160;<structfield>g_iface</structfield>;</term>
 
177
<listitem><simpara> The parent interface.
 
178
</simpara></listitem>
 
179
</varlistentry>
 
180
<varlistentry>
 
181
<term><structfield>get_user_data</structfield>&#160;()</term>
 
182
<listitem><simpara> Gets the user data passed to the callback.
 
183
</simpara></listitem>
 
184
</varlistentry>
 
185
<varlistentry>
 
186
<term><structfield>get_source_object</structfield>&#160;()</term>
 
187
<listitem><simpara> Gets the source object that issued the asynchronous operation.
 
188
</simpara></listitem>
 
189
</varlistentry>
 
190
</variablelist></refsect2>
 
191
<refsect2 id="GAsyncReadyCallback" role="function">
 
192
<title>GAsyncReadyCallback ()</title>
 
193
<indexterm zone="GAsyncReadyCallback"><primary sortas="AsyncReadyCallback">GAsyncReadyCallback</primary></indexterm><programlisting><link linkend="void">void</link>                (*GAsyncReadyCallback)              (<link linkend="GObject">GObject</link> *source_object,
 
194
                                                         <link linkend="GAsyncResult">GAsyncResult</link> *res,
 
195
                                                         <link linkend="gpointer">gpointer</link> user_data);</programlisting>
 
196
<para>
 
197
Type definition for a function that will be called back when an asynchronous
 
198
operation within GIO has been completed.</para>
 
199
<para>
 
200
</para><variablelist role="params">
 
201
<varlistentry><term><parameter>source_object</parameter>&#160;:</term>
 
202
<listitem><simpara> the object the asynchronous operation was started with.
 
203
</simpara></listitem></varlistentry>
 
204
<varlistentry><term><parameter>res</parameter>&#160;:</term>
 
205
<listitem><simpara> a <link linkend="GAsyncResult"><type>GAsyncResult</type></link>.
 
206
</simpara></listitem></varlistentry>
 
207
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
 
208
<listitem><simpara> user data passed to the callback.
 
209
</simpara></listitem></varlistentry>
 
210
</variablelist></refsect2>
 
211
<refsect2 id="g-async-result-get-user-data" role="function">
 
212
<title>g_async_result_get_user_data ()</title>
 
213
<indexterm zone="g-async-result-get-user-data"><primary sortas="async_result_get_user_data">g_async_result_get_user_data</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            g_async_result_get_user_data        (<link linkend="GAsyncResult">GAsyncResult</link> *res);</programlisting>
 
214
<para>
 
215
Gets the user data from a <link linkend="GAsyncResult"><type>GAsyncResult</type></link>.</para>
 
216
<para>
 
217
</para><variablelist role="params">
 
218
<varlistentry><term><parameter>res</parameter>&#160;:</term>
 
219
<listitem><simpara> a <link linkend="GAsyncResult"><type>GAsyncResult</type></link>.
 
220
</simpara></listitem></varlistentry>
 
221
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the user data for <parameter>res</parameter>.
 
222
</simpara></listitem></varlistentry>
 
223
</variablelist></refsect2>
 
224
<refsect2 id="g-async-result-get-source-object" role="function">
 
225
<title>g_async_result_get_source_object ()</title>
 
226
<indexterm zone="g-async-result-get-source-object"><primary sortas="async_result_get_source_object">g_async_result_get_source_object</primary></indexterm><programlisting><link linkend="GObject">GObject</link> *           g_async_result_get_source_object    (<link linkend="GAsyncResult">GAsyncResult</link> *res);</programlisting>
 
227
<para>
 
228
Gets the source object from a <link linkend="GAsyncResult"><type>GAsyncResult</type></link>.</para>
 
229
<para>
 
230
</para><variablelist role="params">
 
231
<varlistentry><term><parameter>res</parameter>&#160;:</term>
 
232
<listitem><simpara> a <link linkend="GAsyncResult"><type>GAsyncResult</type></link>
 
233
</simpara></listitem></varlistentry>
 
234
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a new reference to the source object for the <parameter>res</parameter>,
 
235
   or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if there is none.
 
236
</simpara></listitem></varlistentry>
 
237
</variablelist></refsect2>
 
238
 
 
239
</refsect1>
 
240
 
 
241
 
 
242
 
 
243
<refsect1 id="GAsyncResult.see-also">
 
244
<title>See Also</title>
 
245
#GSimpleAsyncResult
 
246
</refsect1>
 
247
 
 
248
</refentry>