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 | |
23 | #include <string.h> |
24 | |
25 | #include "gsimpleasyncresult.h" |
26 | #include "gasyncresult.h" |
27 | #include "gcancellable.h" |
28 | #include "gioscheduler.h" |
29 | #include <gio/gioerror.h> |
30 | #include "glibintl.h" |
31 | |
32 | |
33 | /** |
34 | * SECTION:gsimpleasyncresult |
35 | * @short_description: Simple asynchronous results implementation |
36 | * @include: gio/gio.h |
37 | * @see_also: #GAsyncResult, #GTask |
38 | * |
39 | * As of GLib 2.46, #GSimpleAsyncResult is deprecated in favor of |
40 | * #GTask, which provides a simpler API. |
41 | * |
42 | * #GSimpleAsyncResult implements #GAsyncResult. |
43 | * |
44 | * GSimpleAsyncResult handles #GAsyncReadyCallbacks, error |
45 | * reporting, operation cancellation and the final state of an operation, |
46 | * completely transparent to the application. Results can be returned |
47 | * as a pointer e.g. for functions that return data that is collected |
48 | * asynchronously, a boolean value for checking the success or failure |
49 | * of an operation, or a #gssize for operations which return the number |
50 | * of bytes modified by the operation; all of the simple return cases |
51 | * are covered. |
52 | * |
53 | * Most of the time, an application will not need to know of the details |
54 | * of this API; it is handled transparently, and any necessary operations |
55 | * are handled by #GAsyncResult's interface. However, if implementing a |
56 | * new GIO module, for writing language bindings, or for complex |
57 | * applications that need better control of how asynchronous operations |
58 | * are completed, it is important to understand this functionality. |
59 | * |
60 | * GSimpleAsyncResults are tagged with the calling function to ensure |
61 | * that asynchronous functions and their finishing functions are used |
62 | * together correctly. |
63 | * |
64 | * To create a new #GSimpleAsyncResult, call g_simple_async_result_new(). |
65 | * If the result needs to be created for a #GError, use |
66 | * g_simple_async_result_new_from_error() or |
67 | * g_simple_async_result_new_take_error(). If a #GError is not available |
68 | * (e.g. the asynchronous operation's doesn't take a #GError argument), |
69 | * but the result still needs to be created for an error condition, use |
70 | * g_simple_async_result_new_error() (or g_simple_async_result_set_error_va() |
71 | * if your application or binding requires passing a variable argument list |
72 | * directly), and the error can then be propagated through the use of |
73 | * g_simple_async_result_propagate_error(). |
74 | * |
75 | * An asynchronous operation can be made to ignore a cancellation event by |
76 | * calling g_simple_async_result_set_handle_cancellation() with a |
77 | * #GSimpleAsyncResult for the operation and %FALSE. This is useful for |
78 | * operations that are dangerous to cancel, such as close (which would |
79 | * cause a leak if cancelled before being run). |
80 | * |
81 | * GSimpleAsyncResult can integrate into GLib's event loop, #GMainLoop, |
82 | * or it can use #GThreads. |
83 | * g_simple_async_result_complete() will finish an I/O task directly |
84 | * from the point where it is called. g_simple_async_result_complete_in_idle() |
85 | * will finish it from an idle handler in the |
86 | * [thread-default main context][g-main-context-push-thread-default] |
87 | * where the #GSimpleAsyncResult was created. |
88 | * g_simple_async_result_run_in_thread() will run the job in a |
89 | * separate thread and then use |
90 | * g_simple_async_result_complete_in_idle() to deliver the result. |
91 | * |
92 | * To set the results of an asynchronous function, |
93 | * g_simple_async_result_set_op_res_gpointer(), |
94 | * g_simple_async_result_set_op_res_gboolean(), and |
95 | * g_simple_async_result_set_op_res_gssize() |
96 | * are provided, setting the operation's result to a gpointer, gboolean, or |
97 | * gssize, respectively. |
98 | * |
99 | * Likewise, to get the result of an asynchronous function, |
100 | * g_simple_async_result_get_op_res_gpointer(), |
101 | * g_simple_async_result_get_op_res_gboolean(), and |
102 | * g_simple_async_result_get_op_res_gssize() are |
103 | * provided, getting the operation's result as a gpointer, gboolean, and |
104 | * gssize, respectively. |
105 | * |
106 | * For the details of the requirements implementations must respect, see |
107 | * #GAsyncResult. A typical implementation of an asynchronous operation |
108 | * using GSimpleAsyncResult looks something like this: |
109 | * |
110 | * |[<!-- language="C" --> |
111 | * static void |
112 | * baked_cb (Cake *cake, |
113 | * gpointer user_data) |
114 | * { |
115 | * // In this example, this callback is not given a reference to the cake, |
116 | * // so the GSimpleAsyncResult has to take a reference to it. |
117 | * GSimpleAsyncResult *result = user_data; |
118 | * |
119 | * if (cake == NULL) |
120 | * g_simple_async_result_set_error (result, |
121 | * BAKER_ERRORS, |
122 | * BAKER_ERROR_NO_FLOUR, |
123 | * "Go to the supermarket"); |
124 | * else |
125 | * g_simple_async_result_set_op_res_gpointer (result, |
126 | * g_object_ref (cake), |
127 | * g_object_unref); |
128 | * |
129 | * |
130 | * // In this example, we assume that baked_cb is called as a callback from |
131 | * // the mainloop, so it's safe to complete the operation synchronously here. |
132 | * // If, however, _baker_prepare_cake () might call its callback without |
133 | * // first returning to the mainloop — inadvisable, but some APIs do so — |
134 | * // we would need to use g_simple_async_result_complete_in_idle(). |
135 | * g_simple_async_result_complete (result); |
136 | * g_object_unref (result); |
137 | * } |
138 | * |
139 | * void |
140 | * baker_bake_cake_async (Baker *self, |
141 | * guint radius, |
142 | * GAsyncReadyCallback callback, |
143 | * gpointer user_data) |
144 | * { |
145 | * GSimpleAsyncResult *simple; |
146 | * Cake *cake; |
147 | * |
148 | * if (radius < 3) |
149 | * { |
150 | * g_simple_async_report_error_in_idle (G_OBJECT (self), |
151 | * callback, |
152 | * user_data, |
153 | * BAKER_ERRORS, |
154 | * BAKER_ERROR_TOO_SMALL, |
155 | * "%ucm radius cakes are silly", |
156 | * radius); |
157 | * return; |
158 | * } |
159 | * |
160 | * simple = g_simple_async_result_new (G_OBJECT (self), |
161 | * callback, |
162 | * user_data, |
163 | * baker_bake_cake_async); |
164 | * cake = _baker_get_cached_cake (self, radius); |
165 | * |
166 | * if (cake != NULL) |
167 | * { |
168 | * g_simple_async_result_set_op_res_gpointer (simple, |
169 | * g_object_ref (cake), |
170 | * g_object_unref); |
171 | * g_simple_async_result_complete_in_idle (simple); |
172 | * g_object_unref (simple); |
173 | * // Drop the reference returned by _baker_get_cached_cake(); |
174 | * // the GSimpleAsyncResult has taken its own reference. |
175 | * g_object_unref (cake); |
176 | * return; |
177 | * } |
178 | * |
179 | * _baker_prepare_cake (self, radius, baked_cb, simple); |
180 | * } |
181 | * |
182 | * Cake * |
183 | * baker_bake_cake_finish (Baker *self, |
184 | * GAsyncResult *result, |
185 | * GError **error) |
186 | * { |
187 | * GSimpleAsyncResult *simple; |
188 | * Cake *cake; |
189 | * |
190 | * g_return_val_if_fail (g_simple_async_result_is_valid (result, |
191 | * G_OBJECT (self), |
192 | * baker_bake_cake_async), |
193 | * NULL); |
194 | * |
195 | * simple = (GSimpleAsyncResult *) result; |
196 | * |
197 | * if (g_simple_async_result_propagate_error (simple, error)) |
198 | * return NULL; |
199 | * |
200 | * cake = CAKE (g_simple_async_result_get_op_res_gpointer (simple)); |
201 | * return g_object_ref (cake); |
202 | * } |
203 | * ]| |
204 | */ |
205 | |
206 | G_GNUC_BEGIN_IGNORE_DEPRECATIONS |
207 | |
208 | static void g_simple_async_result_async_result_iface_init (GAsyncResultIface *iface); |
209 | |
210 | struct _GSimpleAsyncResult |
211 | { |
212 | GObject parent_instance; |
213 | |
214 | GObject *source_object; |
215 | GAsyncReadyCallback callback; |
216 | gpointer user_data; |
217 | GMainContext *context; |
218 | GError *error; |
219 | gboolean failed; |
220 | gboolean handle_cancellation; |
221 | GCancellable *check_cancellable; |
222 | |
223 | gpointer source_tag; |
224 | |
225 | union { |
226 | gpointer v_pointer; |
227 | gboolean v_boolean; |
228 | gssize v_ssize; |
229 | } op_res; |
230 | |
231 | GDestroyNotify destroy_op_res; |
232 | }; |
233 | |
234 | struct _GSimpleAsyncResultClass |
235 | { |
236 | GObjectClass parent_class; |
237 | }; |
238 | |
239 | |
240 | G_DEFINE_TYPE_WITH_CODE (GSimpleAsyncResult, g_simple_async_result, G_TYPE_OBJECT, |
241 | G_IMPLEMENT_INTERFACE (G_TYPE_ASYNC_RESULT, |
242 | g_simple_async_result_async_result_iface_init)) |
243 | |
244 | static void |
245 | clear_op_res (GSimpleAsyncResult *simple) |
246 | { |
247 | if (simple->destroy_op_res) |
248 | simple->destroy_op_res (simple->op_res.v_pointer); |
249 | simple->destroy_op_res = NULL; |
250 | simple->op_res.v_ssize = 0; |
251 | } |
252 | |
253 | static void |
254 | g_simple_async_result_finalize (GObject *object) |
255 | { |
256 | GSimpleAsyncResult *simple; |
257 | |
258 | simple = G_SIMPLE_ASYNC_RESULT (object); |
259 | |
260 | if (simple->source_object) |
261 | g_object_unref (object: simple->source_object); |
262 | |
263 | if (simple->check_cancellable) |
264 | g_object_unref (object: simple->check_cancellable); |
265 | |
266 | g_main_context_unref (context: simple->context); |
267 | |
268 | clear_op_res (simple); |
269 | |
270 | if (simple->error) |
271 | g_error_free (error: simple->error); |
272 | |
273 | G_OBJECT_CLASS (g_simple_async_result_parent_class)->finalize (object); |
274 | } |
275 | |
276 | static void |
277 | g_simple_async_result_class_init (GSimpleAsyncResultClass *klass) |
278 | { |
279 | GObjectClass *gobject_class = G_OBJECT_CLASS (klass); |
280 | |
281 | gobject_class->finalize = g_simple_async_result_finalize; |
282 | } |
283 | |
284 | static void |
285 | g_simple_async_result_init (GSimpleAsyncResult *simple) |
286 | { |
287 | simple->handle_cancellation = TRUE; |
288 | |
289 | simple->context = g_main_context_ref_thread_default (); |
290 | } |
291 | |
292 | /** |
293 | * g_simple_async_result_new: |
294 | * @source_object: (nullable): a #GObject, or %NULL. |
295 | * @callback: (scope async): a #GAsyncReadyCallback. |
296 | * @user_data: (closure): user data passed to @callback. |
297 | * @source_tag: the asynchronous function. |
298 | * |
299 | * Creates a #GSimpleAsyncResult. |
300 | * |
301 | * The common convention is to create the #GSimpleAsyncResult in the |
302 | * function that starts the asynchronous operation and use that same |
303 | * function as the @source_tag. |
304 | * |
305 | * If your operation supports cancellation with #GCancellable (which it |
306 | * probably should) then you should provide the user's cancellable to |
307 | * g_simple_async_result_set_check_cancellable() immediately after |
308 | * this function returns. |
309 | * |
310 | * Returns: a #GSimpleAsyncResult. |
311 | * |
312 | * Deprecated: 2.46: Use g_task_new() instead. |
313 | **/ |
314 | GSimpleAsyncResult * |
315 | g_simple_async_result_new (GObject *source_object, |
316 | GAsyncReadyCallback callback, |
317 | gpointer user_data, |
318 | gpointer source_tag) |
319 | { |
320 | GSimpleAsyncResult *simple; |
321 | |
322 | g_return_val_if_fail (!source_object || G_IS_OBJECT (source_object), NULL); |
323 | |
324 | simple = g_object_new (G_TYPE_SIMPLE_ASYNC_RESULT, NULL); |
325 | simple->callback = callback; |
326 | if (source_object) |
327 | simple->source_object = g_object_ref (source_object); |
328 | else |
329 | simple->source_object = NULL; |
330 | simple->user_data = user_data; |
331 | simple->source_tag = source_tag; |
332 | |
333 | return simple; |
334 | } |
335 | |
336 | /** |
337 | * g_simple_async_result_new_from_error: |
338 | * @source_object: (nullable): a #GObject, or %NULL. |
339 | * @callback: (scope async): a #GAsyncReadyCallback. |
340 | * @user_data: (closure): user data passed to @callback. |
341 | * @error: a #GError |
342 | * |
343 | * Creates a #GSimpleAsyncResult from an error condition. |
344 | * |
345 | * Returns: a #GSimpleAsyncResult. |
346 | * |
347 | * Deprecated: 2.46: Use g_task_new() and g_task_return_error() instead. |
348 | **/ |
349 | GSimpleAsyncResult * |
350 | g_simple_async_result_new_from_error (GObject *source_object, |
351 | GAsyncReadyCallback callback, |
352 | gpointer user_data, |
353 | const GError *error) |
354 | { |
355 | GSimpleAsyncResult *simple; |
356 | |
357 | g_return_val_if_fail (!source_object || G_IS_OBJECT (source_object), NULL); |
358 | |
359 | simple = g_simple_async_result_new (source_object, |
360 | callback, |
361 | user_data, NULL); |
362 | g_simple_async_result_set_from_error (simple, error); |
363 | |
364 | return simple; |
365 | } |
366 | |
367 | /** |
368 | * g_simple_async_result_new_take_error: (skip) |
369 | * @source_object: (nullable): a #GObject, or %NULL |
370 | * @callback: (scope async): a #GAsyncReadyCallback |
371 | * @user_data: (closure): user data passed to @callback |
372 | * @error: a #GError |
373 | * |
374 | * Creates a #GSimpleAsyncResult from an error condition, and takes over the |
375 | * caller's ownership of @error, so the caller does not need to free it anymore. |
376 | * |
377 | * Returns: a #GSimpleAsyncResult |
378 | * |
379 | * Since: 2.28 |
380 | * |
381 | * Deprecated: 2.46: Use g_task_new() and g_task_return_error() instead. |
382 | **/ |
383 | GSimpleAsyncResult * |
384 | g_simple_async_result_new_take_error (GObject *source_object, |
385 | GAsyncReadyCallback callback, |
386 | gpointer user_data, |
387 | GError *error) |
388 | { |
389 | GSimpleAsyncResult *simple; |
390 | |
391 | g_return_val_if_fail (!source_object || G_IS_OBJECT (source_object), NULL); |
392 | |
393 | simple = g_simple_async_result_new (source_object, |
394 | callback, |
395 | user_data, NULL); |
396 | g_simple_async_result_take_error (simple, error); |
397 | |
398 | return simple; |
399 | } |
400 | |
401 | /** |
402 | * g_simple_async_result_new_error: |
403 | * @source_object: (nullable): a #GObject, or %NULL. |
404 | * @callback: (scope async): a #GAsyncReadyCallback. |
405 | * @user_data: (closure): user data passed to @callback. |
406 | * @domain: a #GQuark. |
407 | * @code: an error code. |
408 | * @format: a string with format characters. |
409 | * @...: a list of values to insert into @format. |
410 | * |
411 | * Creates a new #GSimpleAsyncResult with a set error. |
412 | * |
413 | * Returns: a #GSimpleAsyncResult. |
414 | * |
415 | * Deprecated: 2.46: Use g_task_new() and g_task_return_new_error() instead. |
416 | **/ |
417 | GSimpleAsyncResult * |
418 | g_simple_async_result_new_error (GObject *source_object, |
419 | GAsyncReadyCallback callback, |
420 | gpointer user_data, |
421 | GQuark domain, |
422 | gint code, |
423 | const char *format, |
424 | ...) |
425 | { |
426 | GSimpleAsyncResult *simple; |
427 | va_list args; |
428 | |
429 | g_return_val_if_fail (!source_object || G_IS_OBJECT (source_object), NULL); |
430 | g_return_val_if_fail (domain != 0, NULL); |
431 | g_return_val_if_fail (format != NULL, NULL); |
432 | |
433 | simple = g_simple_async_result_new (source_object, |
434 | callback, |
435 | user_data, NULL); |
436 | |
437 | va_start (args, format); |
438 | g_simple_async_result_set_error_va (simple, domain, code, format, args); |
439 | va_end (args); |
440 | |
441 | return simple; |
442 | } |
443 | |
444 | |
445 | static gpointer |
446 | g_simple_async_result_get_user_data (GAsyncResult *res) |
447 | { |
448 | return G_SIMPLE_ASYNC_RESULT (res)->user_data; |
449 | } |
450 | |
451 | static GObject * |
452 | g_simple_async_result_get_source_object (GAsyncResult *res) |
453 | { |
454 | if (G_SIMPLE_ASYNC_RESULT (res)->source_object) |
455 | return g_object_ref (G_SIMPLE_ASYNC_RESULT (res)->source_object); |
456 | return NULL; |
457 | } |
458 | |
459 | static gboolean |
460 | g_simple_async_result_is_tagged (GAsyncResult *res, |
461 | gpointer source_tag) |
462 | { |
463 | return G_SIMPLE_ASYNC_RESULT (res)->source_tag == source_tag; |
464 | } |
465 | |
466 | static void |
467 | g_simple_async_result_async_result_iface_init (GAsyncResultIface *iface) |
468 | { |
469 | iface->get_user_data = g_simple_async_result_get_user_data; |
470 | iface->get_source_object = g_simple_async_result_get_source_object; |
471 | iface->is_tagged = g_simple_async_result_is_tagged; |
472 | } |
473 | |
474 | /** |
475 | * g_simple_async_result_set_handle_cancellation: |
476 | * @simple: a #GSimpleAsyncResult. |
477 | * @handle_cancellation: a #gboolean. |
478 | * |
479 | * Sets whether to handle cancellation within the asynchronous operation. |
480 | * |
481 | * This function has nothing to do with |
482 | * g_simple_async_result_set_check_cancellable(). It only refers to the |
483 | * #GCancellable passed to g_simple_async_result_run_in_thread(). |
484 | * |
485 | * Deprecated: 2.46 |
486 | **/ |
487 | void |
488 | g_simple_async_result_set_handle_cancellation (GSimpleAsyncResult *simple, |
489 | gboolean handle_cancellation) |
490 | { |
491 | g_return_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple)); |
492 | simple->handle_cancellation = handle_cancellation; |
493 | } |
494 | |
495 | /** |
496 | * g_simple_async_result_get_source_tag: (skip) |
497 | * @simple: a #GSimpleAsyncResult. |
498 | * |
499 | * Gets the source tag for the #GSimpleAsyncResult. |
500 | * |
501 | * Returns: a #gpointer to the source object for the #GSimpleAsyncResult. |
502 | * |
503 | * Deprecated: 2.46. Use #GTask and g_task_get_source_tag() instead. |
504 | **/ |
505 | gpointer |
506 | g_simple_async_result_get_source_tag (GSimpleAsyncResult *simple) |
507 | { |
508 | g_return_val_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple), NULL); |
509 | return simple->source_tag; |
510 | } |
511 | |
512 | /** |
513 | * g_simple_async_result_propagate_error: |
514 | * @simple: a #GSimpleAsyncResult. |
515 | * @dest: (out): a location to propagate the error to. |
516 | * |
517 | * Propagates an error from within the simple asynchronous result to |
518 | * a given destination. |
519 | * |
520 | * If the #GCancellable given to a prior call to |
521 | * g_simple_async_result_set_check_cancellable() is cancelled then this |
522 | * function will return %TRUE with @dest set appropriately. |
523 | * |
524 | * Returns: %TRUE if the error was propagated to @dest. %FALSE otherwise. |
525 | * |
526 | * Deprecated: 2.46: Use #GTask instead. |
527 | **/ |
528 | gboolean |
529 | g_simple_async_result_propagate_error (GSimpleAsyncResult *simple, |
530 | GError **dest) |
531 | { |
532 | g_return_val_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple), FALSE); |
533 | |
534 | if (g_cancellable_set_error_if_cancelled (cancellable: simple->check_cancellable, error: dest)) |
535 | return TRUE; |
536 | |
537 | if (simple->failed) |
538 | { |
539 | g_propagate_error (dest, src: simple->error); |
540 | simple->error = NULL; |
541 | return TRUE; |
542 | } |
543 | |
544 | return FALSE; |
545 | } |
546 | |
547 | /** |
548 | * g_simple_async_result_set_op_res_gpointer: (skip) |
549 | * @simple: a #GSimpleAsyncResult. |
550 | * @op_res: a pointer result from an asynchronous function. |
551 | * @destroy_op_res: a #GDestroyNotify function. |
552 | * |
553 | * Sets the operation result within the asynchronous result to a pointer. |
554 | * |
555 | * Deprecated: 2.46: Use #GTask and g_task_return_pointer() instead. |
556 | **/ |
557 | void |
558 | g_simple_async_result_set_op_res_gpointer (GSimpleAsyncResult *simple, |
559 | gpointer op_res, |
560 | GDestroyNotify destroy_op_res) |
561 | { |
562 | g_return_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple)); |
563 | |
564 | clear_op_res (simple); |
565 | simple->op_res.v_pointer = op_res; |
566 | simple->destroy_op_res = destroy_op_res; |
567 | } |
568 | |
569 | /** |
570 | * g_simple_async_result_get_op_res_gpointer: (skip) |
571 | * @simple: a #GSimpleAsyncResult. |
572 | * |
573 | * Gets a pointer result as returned by the asynchronous function. |
574 | * |
575 | * Returns: a pointer from the result. |
576 | * |
577 | * Deprecated: 2.46: Use #GTask and g_task_propagate_pointer() instead. |
578 | **/ |
579 | gpointer |
580 | g_simple_async_result_get_op_res_gpointer (GSimpleAsyncResult *simple) |
581 | { |
582 | g_return_val_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple), NULL); |
583 | return simple->op_res.v_pointer; |
584 | } |
585 | |
586 | /** |
587 | * g_simple_async_result_set_op_res_gssize: |
588 | * @simple: a #GSimpleAsyncResult. |
589 | * @op_res: a #gssize. |
590 | * |
591 | * Sets the operation result within the asynchronous result to |
592 | * the given @op_res. |
593 | * |
594 | * Deprecated: 2.46: Use #GTask and g_task_return_int() instead. |
595 | **/ |
596 | void |
597 | g_simple_async_result_set_op_res_gssize (GSimpleAsyncResult *simple, |
598 | gssize op_res) |
599 | { |
600 | g_return_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple)); |
601 | clear_op_res (simple); |
602 | simple->op_res.v_ssize = op_res; |
603 | } |
604 | |
605 | /** |
606 | * g_simple_async_result_get_op_res_gssize: |
607 | * @simple: a #GSimpleAsyncResult. |
608 | * |
609 | * Gets a gssize from the asynchronous result. |
610 | * |
611 | * Returns: a gssize returned from the asynchronous function. |
612 | * |
613 | * Deprecated: 2.46: Use #GTask and g_task_propagate_int() instead. |
614 | **/ |
615 | gssize |
616 | g_simple_async_result_get_op_res_gssize (GSimpleAsyncResult *simple) |
617 | { |
618 | g_return_val_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple), 0); |
619 | return simple->op_res.v_ssize; |
620 | } |
621 | |
622 | /** |
623 | * g_simple_async_result_set_op_res_gboolean: |
624 | * @simple: a #GSimpleAsyncResult. |
625 | * @op_res: a #gboolean. |
626 | * |
627 | * Sets the operation result to a boolean within the asynchronous result. |
628 | * |
629 | * Deprecated: 2.46: Use #GTask and g_task_return_boolean() instead. |
630 | **/ |
631 | void |
632 | g_simple_async_result_set_op_res_gboolean (GSimpleAsyncResult *simple, |
633 | gboolean op_res) |
634 | { |
635 | g_return_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple)); |
636 | clear_op_res (simple); |
637 | simple->op_res.v_boolean = !!op_res; |
638 | } |
639 | |
640 | /** |
641 | * g_simple_async_result_get_op_res_gboolean: |
642 | * @simple: a #GSimpleAsyncResult. |
643 | * |
644 | * Gets the operation result boolean from within the asynchronous result. |
645 | * |
646 | * Returns: %TRUE if the operation's result was %TRUE, %FALSE |
647 | * if the operation's result was %FALSE. |
648 | * |
649 | * Deprecated: 2.46: Use #GTask and g_task_propagate_boolean() instead. |
650 | **/ |
651 | gboolean |
652 | g_simple_async_result_get_op_res_gboolean (GSimpleAsyncResult *simple) |
653 | { |
654 | g_return_val_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple), FALSE); |
655 | return simple->op_res.v_boolean; |
656 | } |
657 | |
658 | /** |
659 | * g_simple_async_result_set_from_error: |
660 | * @simple: a #GSimpleAsyncResult. |
661 | * @error: #GError. |
662 | * |
663 | * Sets the result from a #GError. |
664 | * |
665 | * Deprecated: 2.46: Use #GTask and g_task_return_error() instead. |
666 | **/ |
667 | void |
668 | g_simple_async_result_set_from_error (GSimpleAsyncResult *simple, |
669 | const GError *error) |
670 | { |
671 | g_return_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple)); |
672 | g_return_if_fail (error != NULL); |
673 | |
674 | if (simple->error) |
675 | g_error_free (error: simple->error); |
676 | simple->error = g_error_copy (error); |
677 | simple->failed = TRUE; |
678 | } |
679 | |
680 | /** |
681 | * g_simple_async_result_take_error: (skip) |
682 | * @simple: a #GSimpleAsyncResult |
683 | * @error: a #GError |
684 | * |
685 | * Sets the result from @error, and takes over the caller's ownership |
686 | * of @error, so the caller does not need to free it any more. |
687 | * |
688 | * Since: 2.28 |
689 | * |
690 | * Deprecated: 2.46: Use #GTask and g_task_return_error() instead. |
691 | **/ |
692 | void |
693 | g_simple_async_result_take_error (GSimpleAsyncResult *simple, |
694 | GError *error) |
695 | { |
696 | g_return_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple)); |
697 | g_return_if_fail (error != NULL); |
698 | |
699 | if (simple->error) |
700 | g_error_free (error: simple->error); |
701 | simple->error = error; |
702 | simple->failed = TRUE; |
703 | } |
704 | |
705 | /** |
706 | * g_simple_async_result_set_error_va: (skip) |
707 | * @simple: a #GSimpleAsyncResult. |
708 | * @domain: a #GQuark (usually #G_IO_ERROR). |
709 | * @code: an error code. |
710 | * @format: a formatted error reporting string. |
711 | * @args: va_list of arguments. |
712 | * |
713 | * Sets an error within the asynchronous result without a #GError. |
714 | * Unless writing a binding, see g_simple_async_result_set_error(). |
715 | * |
716 | * Deprecated: 2.46: Use #GTask and g_task_return_error() instead. |
717 | **/ |
718 | void |
719 | g_simple_async_result_set_error_va (GSimpleAsyncResult *simple, |
720 | GQuark domain, |
721 | gint code, |
722 | const char *format, |
723 | va_list args) |
724 | { |
725 | g_return_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple)); |
726 | g_return_if_fail (domain != 0); |
727 | g_return_if_fail (format != NULL); |
728 | |
729 | if (simple->error) |
730 | g_error_free (error: simple->error); |
731 | simple->error = g_error_new_valist (domain, code, format, args); |
732 | simple->failed = TRUE; |
733 | } |
734 | |
735 | /** |
736 | * g_simple_async_result_set_error: (skip) |
737 | * @simple: a #GSimpleAsyncResult. |
738 | * @domain: a #GQuark (usually #G_IO_ERROR). |
739 | * @code: an error code. |
740 | * @format: a formatted error reporting string. |
741 | * @...: a list of variables to fill in @format. |
742 | * |
743 | * Sets an error within the asynchronous result without a #GError. |
744 | * |
745 | * Deprecated: 2.46: Use #GTask and g_task_return_new_error() instead. |
746 | **/ |
747 | void |
748 | g_simple_async_result_set_error (GSimpleAsyncResult *simple, |
749 | GQuark domain, |
750 | gint code, |
751 | const char *format, |
752 | ...) |
753 | { |
754 | va_list args; |
755 | |
756 | g_return_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple)); |
757 | g_return_if_fail (domain != 0); |
758 | g_return_if_fail (format != NULL); |
759 | |
760 | va_start (args, format); |
761 | g_simple_async_result_set_error_va (simple, domain, code, format, args); |
762 | va_end (args); |
763 | } |
764 | |
765 | /** |
766 | * g_simple_async_result_complete: |
767 | * @simple: a #GSimpleAsyncResult. |
768 | * |
769 | * Completes an asynchronous I/O job immediately. Must be called in |
770 | * the thread where the asynchronous result was to be delivered, as it |
771 | * invokes the callback directly. If you are in a different thread use |
772 | * g_simple_async_result_complete_in_idle(). |
773 | * |
774 | * Calling this function takes a reference to @simple for as long as |
775 | * is needed to complete the call. |
776 | * |
777 | * Deprecated: 2.46: Use #GTask instead. |
778 | **/ |
779 | void |
780 | g_simple_async_result_complete (GSimpleAsyncResult *simple) |
781 | { |
782 | #ifndef G_DISABLE_CHECKS |
783 | GSource *current_source; |
784 | GMainContext *current_context; |
785 | #endif |
786 | |
787 | g_return_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple)); |
788 | |
789 | #ifndef G_DISABLE_CHECKS |
790 | current_source = g_main_current_source (); |
791 | if (current_source && !g_source_is_destroyed (source: current_source)) |
792 | { |
793 | current_context = g_source_get_context (source: current_source); |
794 | if (simple->context != current_context) |
795 | g_warning ("g_simple_async_result_complete() called from wrong context!" ); |
796 | } |
797 | #endif |
798 | |
799 | if (simple->callback) |
800 | { |
801 | g_main_context_push_thread_default (context: simple->context); |
802 | simple->callback (simple->source_object, |
803 | G_ASYNC_RESULT (simple), |
804 | simple->user_data); |
805 | g_main_context_pop_thread_default (context: simple->context); |
806 | } |
807 | } |
808 | |
809 | static gboolean |
810 | complete_in_idle_cb (gpointer data) |
811 | { |
812 | GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (data); |
813 | |
814 | g_simple_async_result_complete (simple); |
815 | |
816 | return FALSE; |
817 | } |
818 | |
819 | /** |
820 | * g_simple_async_result_complete_in_idle: |
821 | * @simple: a #GSimpleAsyncResult. |
822 | * |
823 | * Completes an asynchronous function in an idle handler in the |
824 | * [thread-default main context][g-main-context-push-thread-default] |
825 | * of the thread that @simple was initially created in |
826 | * (and re-pushes that context around the invocation of the callback). |
827 | * |
828 | * Calling this function takes a reference to @simple for as long as |
829 | * is needed to complete the call. |
830 | * |
831 | * Deprecated: 2.46: Use #GTask instead. |
832 | */ |
833 | void |
834 | g_simple_async_result_complete_in_idle (GSimpleAsyncResult *simple) |
835 | { |
836 | GSource *source; |
837 | |
838 | g_return_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple)); |
839 | |
840 | g_object_ref (simple); |
841 | |
842 | source = g_idle_source_new (); |
843 | g_source_set_priority (source, G_PRIORITY_DEFAULT); |
844 | g_source_set_callback (source, func: complete_in_idle_cb, data: simple, notify: g_object_unref); |
845 | g_source_set_name (source, name: "[gio] complete_in_idle_cb" ); |
846 | |
847 | g_source_attach (source, context: simple->context); |
848 | g_source_unref (source); |
849 | } |
850 | |
851 | typedef struct { |
852 | GSimpleAsyncResult *simple; |
853 | GCancellable *cancellable; |
854 | GSimpleAsyncThreadFunc func; |
855 | } RunInThreadData; |
856 | |
857 | |
858 | static gboolean |
859 | complete_in_idle_cb_for_thread (gpointer _data) |
860 | { |
861 | RunInThreadData *data = _data; |
862 | GSimpleAsyncResult *simple; |
863 | |
864 | simple = data->simple; |
865 | |
866 | if (simple->handle_cancellation && |
867 | g_cancellable_is_cancelled (cancellable: data->cancellable)) |
868 | g_simple_async_result_set_error (simple, |
869 | G_IO_ERROR, |
870 | code: G_IO_ERROR_CANCELLED, |
871 | format: "%s" , _("Operation was cancelled" )); |
872 | |
873 | g_simple_async_result_complete (simple); |
874 | |
875 | if (data->cancellable) |
876 | g_object_unref (object: data->cancellable); |
877 | g_object_unref (object: data->simple); |
878 | g_free (mem: data); |
879 | |
880 | return FALSE; |
881 | } |
882 | |
883 | static gboolean |
884 | run_in_thread (GIOSchedulerJob *job, |
885 | GCancellable *c, |
886 | gpointer _data) |
887 | { |
888 | RunInThreadData *data = _data; |
889 | GSimpleAsyncResult *simple = data->simple; |
890 | GSource *source; |
891 | |
892 | if (simple->handle_cancellation && |
893 | g_cancellable_is_cancelled (cancellable: c)) |
894 | g_simple_async_result_set_error (simple, |
895 | G_IO_ERROR, |
896 | code: G_IO_ERROR_CANCELLED, |
897 | format: "%s" , _("Operation was cancelled" )); |
898 | else |
899 | data->func (simple, |
900 | simple->source_object, |
901 | c); |
902 | |
903 | source = g_idle_source_new (); |
904 | g_source_set_priority (source, G_PRIORITY_DEFAULT); |
905 | g_source_set_callback (source, func: complete_in_idle_cb_for_thread, data, NULL); |
906 | g_source_set_name (source, name: "[gio] complete_in_idle_cb_for_thread" ); |
907 | |
908 | g_source_attach (source, context: simple->context); |
909 | g_source_unref (source); |
910 | |
911 | return FALSE; |
912 | } |
913 | |
914 | /** |
915 | * g_simple_async_result_run_in_thread: (skip) |
916 | * @simple: a #GSimpleAsyncResult. |
917 | * @func: a #GSimpleAsyncThreadFunc. |
918 | * @io_priority: the io priority of the request. |
919 | * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. |
920 | * |
921 | * Runs the asynchronous job in a separate thread and then calls |
922 | * g_simple_async_result_complete_in_idle() on @simple to return |
923 | * the result to the appropriate main loop. |
924 | * |
925 | * Calling this function takes a reference to @simple for as long as |
926 | * is needed to run the job and report its completion. |
927 | * |
928 | * Deprecated: 2.46: Use #GTask and g_task_run_in_thread() instead. |
929 | */ |
930 | void |
931 | g_simple_async_result_run_in_thread (GSimpleAsyncResult *simple, |
932 | GSimpleAsyncThreadFunc func, |
933 | int io_priority, |
934 | GCancellable *cancellable) |
935 | { |
936 | RunInThreadData *data; |
937 | |
938 | g_return_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple)); |
939 | g_return_if_fail (func != NULL); |
940 | |
941 | data = g_new (RunInThreadData, 1); |
942 | data->func = func; |
943 | data->simple = g_object_ref (simple); |
944 | data->cancellable = cancellable; |
945 | if (cancellable) |
946 | g_object_ref (cancellable); |
947 | G_GNUC_BEGIN_IGNORE_DEPRECATIONS; |
948 | g_io_scheduler_push_job (job_func: run_in_thread, user_data: data, NULL, io_priority, cancellable); |
949 | G_GNUC_END_IGNORE_DEPRECATIONS; |
950 | } |
951 | |
952 | /** |
953 | * g_simple_async_result_is_valid: |
954 | * @result: the #GAsyncResult passed to the _finish function. |
955 | * @source: (nullable): the #GObject passed to the _finish function. |
956 | * @source_tag: (nullable): the asynchronous function. |
957 | * |
958 | * Ensures that the data passed to the _finish function of an async |
959 | * operation is consistent. Three checks are performed. |
960 | * |
961 | * First, @result is checked to ensure that it is really a |
962 | * #GSimpleAsyncResult. Second, @source is checked to ensure that it |
963 | * matches the source object of @result. Third, @source_tag is |
964 | * checked to ensure that it is equal to the @source_tag argument given |
965 | * to g_simple_async_result_new() (which, by convention, is a pointer |
966 | * to the _async function corresponding to the _finish function from |
967 | * which this function is called). (Alternatively, if either |
968 | * @source_tag or @result's source tag is %NULL, then the source tag |
969 | * check is skipped.) |
970 | * |
971 | * Returns: #TRUE if all checks passed or #FALSE if any failed. |
972 | * |
973 | * Since: 2.20 |
974 | * |
975 | * Deprecated: 2.46: Use #GTask and g_task_is_valid() instead. |
976 | **/ |
977 | gboolean |
978 | g_simple_async_result_is_valid (GAsyncResult *result, |
979 | GObject *source, |
980 | gpointer source_tag) |
981 | { |
982 | GSimpleAsyncResult *simple; |
983 | GObject *cmp_source; |
984 | gpointer result_source_tag; |
985 | |
986 | if (!G_IS_SIMPLE_ASYNC_RESULT (result)) |
987 | return FALSE; |
988 | simple = (GSimpleAsyncResult *)result; |
989 | |
990 | cmp_source = g_async_result_get_source_object (res: result); |
991 | if (cmp_source != source) |
992 | { |
993 | if (cmp_source != NULL) |
994 | g_object_unref (object: cmp_source); |
995 | return FALSE; |
996 | } |
997 | if (cmp_source != NULL) |
998 | g_object_unref (object: cmp_source); |
999 | |
1000 | result_source_tag = g_simple_async_result_get_source_tag (simple); |
1001 | return source_tag == NULL || result_source_tag == NULL || |
1002 | source_tag == result_source_tag; |
1003 | } |
1004 | |
1005 | /** |
1006 | * g_simple_async_report_error_in_idle: (skip) |
1007 | * @object: (nullable): a #GObject, or %NULL. |
1008 | * @callback: a #GAsyncReadyCallback. |
1009 | * @user_data: user data passed to @callback. |
1010 | * @domain: a #GQuark containing the error domain (usually #G_IO_ERROR). |
1011 | * @code: a specific error code. |
1012 | * @format: a formatted error reporting string. |
1013 | * @...: a list of variables to fill in @format. |
1014 | * |
1015 | * Reports an error in an asynchronous function in an idle function by |
1016 | * directly setting the contents of the #GAsyncResult with the given error |
1017 | * information. |
1018 | * |
1019 | * Deprecated: 2.46: Use g_task_report_error(). |
1020 | **/ |
1021 | void |
1022 | g_simple_async_report_error_in_idle (GObject *object, |
1023 | GAsyncReadyCallback callback, |
1024 | gpointer user_data, |
1025 | GQuark domain, |
1026 | gint code, |
1027 | const char *format, |
1028 | ...) |
1029 | { |
1030 | GSimpleAsyncResult *simple; |
1031 | va_list args; |
1032 | |
1033 | g_return_if_fail (!object || G_IS_OBJECT (object)); |
1034 | g_return_if_fail (domain != 0); |
1035 | g_return_if_fail (format != NULL); |
1036 | |
1037 | simple = g_simple_async_result_new (source_object: object, |
1038 | callback, |
1039 | user_data, NULL); |
1040 | |
1041 | va_start (args, format); |
1042 | g_simple_async_result_set_error_va (simple, domain, code, format, args); |
1043 | va_end (args); |
1044 | g_simple_async_result_complete_in_idle (simple); |
1045 | g_object_unref (object: simple); |
1046 | } |
1047 | |
1048 | /** |
1049 | * g_simple_async_report_gerror_in_idle: |
1050 | * @object: (nullable): a #GObject, or %NULL |
1051 | * @callback: (scope async): a #GAsyncReadyCallback. |
1052 | * @user_data: (closure): user data passed to @callback. |
1053 | * @error: the #GError to report |
1054 | * |
1055 | * Reports an error in an idle function. Similar to |
1056 | * g_simple_async_report_error_in_idle(), but takes a #GError rather |
1057 | * than building a new one. |
1058 | * |
1059 | * Deprecated: 2.46: Use g_task_report_error(). |
1060 | **/ |
1061 | void |
1062 | g_simple_async_report_gerror_in_idle (GObject *object, |
1063 | GAsyncReadyCallback callback, |
1064 | gpointer user_data, |
1065 | const GError *error) |
1066 | { |
1067 | GSimpleAsyncResult *simple; |
1068 | |
1069 | g_return_if_fail (!object || G_IS_OBJECT (object)); |
1070 | g_return_if_fail (error != NULL); |
1071 | |
1072 | simple = g_simple_async_result_new_from_error (source_object: object, |
1073 | callback, |
1074 | user_data, |
1075 | error); |
1076 | g_simple_async_result_complete_in_idle (simple); |
1077 | g_object_unref (object: simple); |
1078 | } |
1079 | |
1080 | /** |
1081 | * g_simple_async_report_take_gerror_in_idle: (skip) |
1082 | * @object: (nullable): a #GObject, or %NULL |
1083 | * @callback: a #GAsyncReadyCallback. |
1084 | * @user_data: user data passed to @callback. |
1085 | * @error: the #GError to report |
1086 | * |
1087 | * Reports an error in an idle function. Similar to |
1088 | * g_simple_async_report_gerror_in_idle(), but takes over the caller's |
1089 | * ownership of @error, so the caller does not have to free it any more. |
1090 | * |
1091 | * Since: 2.28 |
1092 | * |
1093 | * Deprecated: 2.46: Use g_task_report_error(). |
1094 | **/ |
1095 | void |
1096 | g_simple_async_report_take_gerror_in_idle (GObject *object, |
1097 | GAsyncReadyCallback callback, |
1098 | gpointer user_data, |
1099 | GError *error) |
1100 | { |
1101 | GSimpleAsyncResult *simple; |
1102 | |
1103 | g_return_if_fail (!object || G_IS_OBJECT (object)); |
1104 | g_return_if_fail (error != NULL); |
1105 | |
1106 | simple = g_simple_async_result_new_take_error (source_object: object, |
1107 | callback, |
1108 | user_data, |
1109 | error); |
1110 | g_simple_async_result_complete_in_idle (simple); |
1111 | g_object_unref (object: simple); |
1112 | } |
1113 | |
1114 | /** |
1115 | * g_simple_async_result_set_check_cancellable: |
1116 | * @simple: a #GSimpleAsyncResult |
1117 | * @check_cancellable: (nullable): a #GCancellable to check, or %NULL to unset |
1118 | * |
1119 | * Sets a #GCancellable to check before dispatching results. |
1120 | * |
1121 | * This function has one very specific purpose: the provided cancellable |
1122 | * is checked at the time of g_simple_async_result_propagate_error() If |
1123 | * it is cancelled, these functions will return an "Operation was |
1124 | * cancelled" error (%G_IO_ERROR_CANCELLED). |
1125 | * |
1126 | * Implementors of cancellable asynchronous functions should use this in |
1127 | * order to provide a guarantee to their callers that cancelling an |
1128 | * async operation will reliably result in an error being returned for |
1129 | * that operation (even if a positive result for the operation has |
1130 | * already been sent as an idle to the main context to be dispatched). |
1131 | * |
1132 | * The checking described above is done regardless of any call to the |
1133 | * unrelated g_simple_async_result_set_handle_cancellation() function. |
1134 | * |
1135 | * Since: 2.32 |
1136 | * |
1137 | * Deprecated: 2.46: Use #GTask instead. |
1138 | **/ |
1139 | void |
1140 | g_simple_async_result_set_check_cancellable (GSimpleAsyncResult *simple, |
1141 | GCancellable *check_cancellable) |
1142 | { |
1143 | g_return_if_fail (G_IS_SIMPLE_ASYNC_RESULT (simple)); |
1144 | g_return_if_fail (check_cancellable == NULL || G_IS_CANCELLABLE (check_cancellable)); |
1145 | |
1146 | g_clear_object (&simple->check_cancellable); |
1147 | if (check_cancellable) |
1148 | simple->check_cancellable = g_object_ref (check_cancellable); |
1149 | } |
1150 | |
1151 | G_GNUC_END_IGNORE_DEPRECATIONS |
1152 | |