1 | /* GIO - GLib Input, Output and Streaming Library |
2 | * |
3 | * Copyright (C) 2006-2007 Red Hat, Inc. |
4 | * |
5 | * This library is free software; you can redistribute it and/or |
6 | * modify it under the terms of the GNU Lesser General Public |
7 | * License as published by the Free Software Foundation; either |
8 | * version 2.1 of the License, or (at your option) any later version. |
9 | * |
10 | * This library is distributed in the hope that it will be useful, |
11 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
12 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
13 | * Lesser General Public License for more details. |
14 | * |
15 | * You should have received a copy of the GNU Lesser General |
16 | * Public License along with this library; if not, see <http://www.gnu.org/licenses/>. |
17 | * |
18 | * Author: Alexander Larsson <alexl@redhat.com> |
19 | */ |
20 | |
21 | #include "config.h" |
22 | #include "gasyncresult.h" |
23 | #include "gsimpleasyncresult.h" |
24 | #include "glibintl.h" |
25 | |
26 | |
27 | /** |
28 | * SECTION:gasyncresult |
29 | * @short_description: Asynchronous Function Results |
30 | * @include: gio/gio.h |
31 | * @see_also: #GTask |
32 | * |
33 | * Provides a base class for implementing asynchronous function results. |
34 | * |
35 | * Asynchronous operations are broken up into two separate operations |
36 | * which are chained together by a #GAsyncReadyCallback. To begin |
37 | * an asynchronous operation, provide a #GAsyncReadyCallback to the |
38 | * asynchronous function. This callback will be triggered when the |
39 | * operation has completed, and must be run in a later iteration of |
40 | * the [thread-default main context][g-main-context-push-thread-default] |
41 | * from where the operation was initiated. It will be passed a |
42 | * #GAsyncResult instance filled with the details of the operation's |
43 | * success or failure, the object the asynchronous function was |
44 | * started for and any error codes returned. The asynchronous callback |
45 | * function is then expected to call the corresponding "_finish()" |
46 | * function, passing the object the function was called for, the |
47 | * #GAsyncResult instance, and (optionally) an @error to grab any |
48 | * error conditions that may have occurred. |
49 | * |
50 | * The "_finish()" function for an operation takes the generic result |
51 | * (of type #GAsyncResult) and returns the specific result that the |
52 | * operation in question yields (e.g. a #GFileEnumerator for a |
53 | * "enumerate children" operation). If the result or error status of the |
54 | * operation is not needed, there is no need to call the "_finish()" |
55 | * function; GIO will take care of cleaning up the result and error |
56 | * information after the #GAsyncReadyCallback returns. You can pass |
57 | * %NULL for the #GAsyncReadyCallback if you don't need to take any |
58 | * action at all after the operation completes. Applications may also |
59 | * take a reference to the #GAsyncResult and call "_finish()" later; |
60 | * however, the "_finish()" function may be called at most once. |
61 | * |
62 | * Example of a typical asynchronous operation flow: |
63 | * |[<!-- language="C" --> |
64 | * void _theoretical_frobnitz_async (Theoretical *t, |
65 | * GCancellable *c, |
66 | * GAsyncReadyCallback cb, |
67 | * gpointer u); |
68 | * |
69 | * gboolean _theoretical_frobnitz_finish (Theoretical *t, |
70 | * GAsyncResult *res, |
71 | * GError **e); |
72 | * |
73 | * static void |
74 | * frobnitz_result_func (GObject *source_object, |
75 | * GAsyncResult *res, |
76 | * gpointer user_data) |
77 | * { |
78 | * gboolean success = FALSE; |
79 | * |
80 | * success = _theoretical_frobnitz_finish (source_object, res, NULL); |
81 | * |
82 | * if (success) |
83 | * g_printf ("Hurray!\n"); |
84 | * else |
85 | * g_printf ("Uh oh!\n"); |
86 | * |
87 | * ... |
88 | * |
89 | * } |
90 | * |
91 | * int main (int argc, void *argv[]) |
92 | * { |
93 | * ... |
94 | * |
95 | * _theoretical_frobnitz_async (theoretical_data, |
96 | * NULL, |
97 | * frobnitz_result_func, |
98 | * NULL); |
99 | * |
100 | * ... |
101 | * } |
102 | * ]| |
103 | * |
104 | * The callback for an asynchronous operation is called only once, and is |
105 | * always called, even in the case of a cancelled operation. On cancellation |
106 | * the result is a %G_IO_ERROR_CANCELLED error. |
107 | * |
108 | * ## I/O Priority # {#io-priority} |
109 | * |
110 | * Many I/O-related asynchronous operations have a priority parameter, |
111 | * which is used in certain cases to determine the order in which |
112 | * operations are executed. They are not used to determine system-wide |
113 | * I/O scheduling. Priorities are integers, with lower numbers indicating |
114 | * higher priority. It is recommended to choose priorities between |
115 | * %G_PRIORITY_LOW and %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT |
116 | * as a default. |
117 | */ |
118 | |
119 | typedef GAsyncResultIface GAsyncResultInterface; |
120 | G_DEFINE_INTERFACE (GAsyncResult, g_async_result, G_TYPE_OBJECT) |
121 | |
122 | static void |
123 | g_async_result_default_init (GAsyncResultInterface *iface) |
124 | { |
125 | } |
126 | |
127 | /** |
128 | * g_async_result_get_user_data: |
129 | * @res: a #GAsyncResult. |
130 | * |
131 | * Gets the user data from a #GAsyncResult. |
132 | * |
133 | * Returns: (transfer full): the user data for @res. |
134 | **/ |
135 | gpointer |
136 | g_async_result_get_user_data (GAsyncResult *res) |
137 | { |
138 | GAsyncResultIface *iface; |
139 | |
140 | g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL); |
141 | |
142 | iface = G_ASYNC_RESULT_GET_IFACE (res); |
143 | |
144 | return (* iface->get_user_data) (res); |
145 | } |
146 | |
147 | /** |
148 | * g_async_result_get_source_object: |
149 | * @res: a #GAsyncResult |
150 | * |
151 | * Gets the source object from a #GAsyncResult. |
152 | * |
153 | * Returns: (transfer full) (nullable): a new reference to the source |
154 | * object for the @res, or %NULL if there is none. |
155 | */ |
156 | GObject * |
157 | g_async_result_get_source_object (GAsyncResult *res) |
158 | { |
159 | GAsyncResultIface *iface; |
160 | |
161 | g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL); |
162 | |
163 | iface = G_ASYNC_RESULT_GET_IFACE (res); |
164 | |
165 | return (* iface->get_source_object) (res); |
166 | } |
167 | |
168 | /** |
169 | * g_async_result_legacy_propagate_error: |
170 | * @res: a #GAsyncResult |
171 | * @error: (out): a location to propagate the error to. |
172 | * |
173 | * If @res is a #GSimpleAsyncResult, this is equivalent to |
174 | * g_simple_async_result_propagate_error(). Otherwise it returns |
175 | * %FALSE. |
176 | * |
177 | * This can be used for legacy error handling in async *_finish() |
178 | * wrapper functions that traditionally handled #GSimpleAsyncResult |
179 | * error returns themselves rather than calling into the virtual method. |
180 | * This should not be used in new code; #GAsyncResult errors that are |
181 | * set by virtual methods should also be extracted by virtual methods, |
182 | * to enable subclasses to chain up correctly. |
183 | * |
184 | * Returns: %TRUE if @error is has been filled in with an error from |
185 | * @res, %FALSE if not. |
186 | * |
187 | * Since: 2.34 |
188 | **/ |
189 | gboolean |
190 | g_async_result_legacy_propagate_error (GAsyncResult *res, |
191 | GError **error) |
192 | { |
193 | /* This doesn't use a vmethod, because it's only for code that used |
194 | * to use GSimpleAsyncResult. (But it's a GAsyncResult method so |
195 | * that callers don't need to worry about GSimpleAsyncResult |
196 | * deprecation warnings in the future.) |
197 | */ |
198 | |
199 | G_GNUC_BEGIN_IGNORE_DEPRECATIONS |
200 | if (G_IS_SIMPLE_ASYNC_RESULT (res)) |
201 | { |
202 | return g_simple_async_result_propagate_error (G_SIMPLE_ASYNC_RESULT (res), |
203 | dest: error); |
204 | } |
205 | else |
206 | return FALSE; |
207 | G_GNUC_END_IGNORE_DEPRECATIONS |
208 | } |
209 | |
210 | /** |
211 | * g_async_result_is_tagged: |
212 | * @res: a #GAsyncResult |
213 | * @source_tag: an application-defined tag |
214 | * |
215 | * Checks if @res has the given @source_tag (generally a function |
216 | * pointer indicating the function @res was created by). |
217 | * |
218 | * Returns: %TRUE if @res has the indicated @source_tag, %FALSE if |
219 | * not. |
220 | * |
221 | * Since: 2.34 |
222 | **/ |
223 | gboolean |
224 | g_async_result_is_tagged (GAsyncResult *res, |
225 | gpointer source_tag) |
226 | { |
227 | GAsyncResultIface *iface; |
228 | |
229 | g_return_val_if_fail (G_IS_ASYNC_RESULT (res), FALSE); |
230 | |
231 | iface = G_ASYNC_RESULT_GET_IFACE (res); |
232 | |
233 | if (!iface->is_tagged) |
234 | return FALSE; |
235 | |
236 | return (* iface->is_tagged) (res, source_tag); |
237 | } |
238 | |