source: appstream-generator/build/girepo/gio/Task.d @ 4841

Last change on this file since 4841 was 4841, checked in by Juanma, 2 years ago

Initial release

File size: 34.8 KB
Line 
1/*
2 * Licensed under the GNU Lesser General Public License Version 3
3 *
4 * This library is free software: you can redistribute it and/or modify
5 * it under the terms of the GNU Lesser General Public License as published by
6 * the Free Software Foundation, either version 3 of the license, or
7 * (at your option) any later version.
8 *
9 * This software is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 * GNU Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public License
15 * along with this library.  If not, see <http://www.gnu.org/licenses/>.
16 */
17
18// generated automatically - do not change
19
20
21module gio.Task;
22
23private import gi.gio;
24public  import gi.giotypes;
25private import gio.AsyncResultIF;
26private import gio.AsyncResultT;
27private import gio.Cancellable;
28private import glib.ConstructionException;
29private import glib.ErrorG;
30private import glib.GException;
31private import glib.MainContext;
32private import glib.Source;
33private import glib.Str;
34private import gobject.ObjectG;
35
36
37/**
38 * A #GTask represents and manages a cancellable "task".
39 *
40 * ## Asynchronous operations
41 *
42 * The most common usage of #GTask is as a #GAsyncResult, to
43 * manage data during an asynchronous operation. You call
44 * g_task_new() in the "start" method, followed by
45 * g_task_set_task_data() and the like if you need to keep some
46 * additional data associated with the task, and then pass the
47 * task object around through your asynchronous operation.
48 * Eventually, you will call a method such as
49 * g_task_return_pointer() or g_task_return_error(), which will
50 * save the value you give it and then invoke the task's callback
51 * function (waiting until the next iteration of the main
52 * loop first, if necessary). The caller will pass the #GTask back
53 * to the operation's finish function (as a #GAsyncResult), and
54 * you can use g_task_propagate_pointer() or the like to extract
55 * the return value.
56 *
57 * Here is an example for using GTask as a GAsyncResult:
58 * |[<!-- language="C" -->
59 * typedef struct {
60 * CakeFrostingType frosting;
61 * char *message;
62 * } DecorationData;
63 *
64 * static void
65 * decoration_data_free (DecorationData *decoration)
66 * {
67 * g_free (decoration->message);
68 * g_slice_free (DecorationData, decoration);
69 * }
70 *
71 * static void
72 * baked_cb (Cake     *cake,
73 * gpointer  user_data)
74 * {
75 * GTask *task = user_data;
76 * DecorationData *decoration = g_task_get_task_data (task);
77 * GError *error = NULL;
78 *
79 * if (cake == NULL)
80 * {
81 * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR,
82 * "Go to the supermarket");
83 * g_object_unref (task);
84 * return;
85 * }
86 *
87 * if (!cake_decorate (cake, decoration->frosting, decoration->message, &error))
88 * {
89 * g_object_unref (cake);
90 * // g_task_return_error() takes ownership of error
91 * g_task_return_error (task, error);
92 * g_object_unref (task);
93 * return;
94 * }
95 *
96 * g_task_return_pointer (task, cake, g_object_unref);
97 * g_object_unref (task);
98 * }
99 *
100 * void
101 * baker_bake_cake_async (Baker               *self,
102 * guint                radius,
103 * CakeFlavor           flavor,
104 * CakeFrostingType     frosting,
105 * const char          *message,
106 * GCancellable        *cancellable,
107 * GAsyncReadyCallback  callback,
108 * gpointer             user_data)
109 * {
110 * GTask *task;
111 * DecorationData *decoration;
112 * Cake  *cake;
113 *
114 * task = g_task_new (self, cancellable, callback, user_data);
115 * if (radius < 3)
116 * {
117 * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_TOO_SMALL,
118 * "%ucm radius cakes are silly",
119 * radius);
120 * g_object_unref (task);
121 * return;
122 * }
123 *
124 * cake = _baker_get_cached_cake (self, radius, flavor, frosting, message);
125 * if (cake != NULL)
126 * {
127 * // _baker_get_cached_cake() returns a reffed cake
128 * g_task_return_pointer (task, cake, g_object_unref);
129 * g_object_unref (task);
130 * return;
131 * }
132 *
133 * decoration = g_slice_new (DecorationData);
134 * decoration->frosting = frosting;
135 * decoration->message = g_strdup (message);
136 * g_task_set_task_data (task, decoration, (GDestroyNotify) decoration_data_free);
137 *
138 * _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task);
139 * }
140 *
141 * Cake *
142 * baker_bake_cake_finish (Baker         *self,
143 * GAsyncResult  *result,
144 * GError       **error)
145 * {
146 * g_return_val_if_fail (g_task_is_valid (result, self), NULL);
147 *
148 * return g_task_propagate_pointer (G_TASK (result), error);
149 * }
150 * ]|
151 *
152 * ## Chained asynchronous operations
153 *
154 * #GTask also tries to simplify asynchronous operations that
155 * internally chain together several smaller asynchronous
156 * operations. g_task_get_cancellable(), g_task_get_context(),
157 * and g_task_get_priority() allow you to get back the task's
158 * #GCancellable, #GMainContext, and [I/O priority][io-priority]
159 * when starting a new subtask, so you don't have to keep track
160 * of them yourself. g_task_attach_source() simplifies the case
161 * of waiting for a source to fire (automatically using the correct
162 * #GMainContext and priority).
163 *
164 * Here is an example for chained asynchronous operations:
165 * |[<!-- language="C" -->
166 * typedef struct {
167 * Cake *cake;
168 * CakeFrostingType frosting;
169 * char *message;
170 * } BakingData;
171 *
172 * static void
173 * decoration_data_free (BakingData *bd)
174 * {
175 * if (bd->cake)
176 * g_object_unref (bd->cake);
177 * g_free (bd->message);
178 * g_slice_free (BakingData, bd);
179 * }
180 *
181 * static void
182 * decorated_cb (Cake         *cake,
183 * GAsyncResult *result,
184 * gpointer      user_data)
185 * {
186 * GTask *task = user_data;
187 * GError *error = NULL;
188 *
189 * if (!cake_decorate_finish (cake, result, &error))
190 * {
191 * g_object_unref (cake);
192 * g_task_return_error (task, error);
193 * g_object_unref (task);
194 * return;
195 * }
196 *
197 * // baking_data_free() will drop its ref on the cake, so we have to
198 * // take another here to give to the caller.
199 * g_task_return_pointer (result, g_object_ref (cake), g_object_unref);
200 * g_object_unref (task);
201 * }
202 *
203 * static void
204 * decorator_ready (gpointer user_data)
205 * {
206 * GTask *task = user_data;
207 * BakingData *bd = g_task_get_task_data (task);
208 *
209 * cake_decorate_async (bd->cake, bd->frosting, bd->message,
210 * g_task_get_cancellable (task),
211 * decorated_cb, task);
212 * }
213 *
214 * static void
215 * baked_cb (Cake     *cake,
216 * gpointer  user_data)
217 * {
218 * GTask *task = user_data;
219 * BakingData *bd = g_task_get_task_data (task);
220 * GError *error = NULL;
221 *
222 * if (cake == NULL)
223 * {
224 * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR,
225 * "Go to the supermarket");
226 * g_object_unref (task);
227 * return;
228 * }
229 *
230 * bd->cake = cake;
231 *
232 * // Bail out now if the user has already cancelled
233 * if (g_task_return_error_if_cancelled (task))
234 * {
235 * g_object_unref (task);
236 * return;
237 * }
238 *
239 * if (cake_decorator_available (cake))
240 * decorator_ready (task);
241 * else
242 * {
243 * GSource *source;
244 *
245 * source = cake_decorator_wait_source_new (cake);
246 * // Attach @source to @task's GMainContext and have it call
247 * // decorator_ready() when it is ready.
248 * g_task_attach_source (task, source,
249 * G_CALLBACK (decorator_ready));
250 * g_source_unref (source);
251 * }
252 * }
253 *
254 * void
255 * baker_bake_cake_async (Baker               *self,
256 * guint                radius,
257 * CakeFlavor           flavor,
258 * CakeFrostingType     frosting,
259 * const char          *message,
260 * gint                 priority,
261 * GCancellable        *cancellable,
262 * GAsyncReadyCallback  callback,
263 * gpointer             user_data)
264 * {
265 * GTask *task;
266 * BakingData *bd;
267 *
268 * task = g_task_new (self, cancellable, callback, user_data);
269 * g_task_set_priority (task, priority);
270 *
271 * bd = g_slice_new0 (BakingData);
272 * bd->frosting = frosting;
273 * bd->message = g_strdup (message);
274 * g_task_set_task_data (task, bd, (GDestroyNotify) baking_data_free);
275 *
276 * _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task);
277 * }
278 *
279 * Cake *
280 * baker_bake_cake_finish (Baker         *self,
281 * GAsyncResult  *result,
282 * GError       **error)
283 * {
284 * g_return_val_if_fail (g_task_is_valid (result, self), NULL);
285 *
286 * return g_task_propagate_pointer (G_TASK (result), error);
287 * }
288 * ]|
289 *
290 * ## Asynchronous operations from synchronous ones
291 *
292 * You can use g_task_run_in_thread() to turn a synchronous
293 * operation into an asynchronous one, by running it in a thread
294 * which will then dispatch the result back to the caller's
295 * #GMainContext when it completes.
296 *
297 * Running a task in a thread:
298 * |[<!-- language="C" -->
299 * typedef struct {
300 * guint radius;
301 * CakeFlavor flavor;
302 * CakeFrostingType frosting;
303 * char *message;
304 * } CakeData;
305 *
306 * static void
307 * cake_data_free (CakeData *cake_data)
308 * {
309 * g_free (cake_data->message);
310 * g_slice_free (CakeData, cake_data);
311 * }
312 *
313 * static void
314 * bake_cake_thread (GTask         *task,
315 * gpointer       source_object,
316 * gpointer       task_data,
317 * GCancellable  *cancellable)
318 * {
319 * Baker *self = source_object;
320 * CakeData *cake_data = task_data;
321 * Cake *cake;
322 * GError *error = NULL;
323 *
324 * cake = bake_cake (baker, cake_data->radius, cake_data->flavor,
325 * cake_data->frosting, cake_data->message,
326 * cancellable, &error);
327 * if (cake)
328 * g_task_return_pointer (task, cake, g_object_unref);
329 * else
330 * g_task_return_error (task, error);
331 * }
332 *
333 * void
334 * baker_bake_cake_async (Baker               *self,
335 * guint                radius,
336 * CakeFlavor           flavor,
337 * CakeFrostingType     frosting,
338 * const char          *message,
339 * GCancellable        *cancellable,
340 * GAsyncReadyCallback  callback,
341 * gpointer             user_data)
342 * {
343 * CakeData *cake_data;
344 * GTask *task;
345 *
346 * cake_data = g_slice_new (CakeData);
347 * cake_data->radius = radius;
348 * cake_data->flavor = flavor;
349 * cake_data->frosting = frosting;
350 * cake_data->message = g_strdup (message);
351 * task = g_task_new (self, cancellable, callback, user_data);
352 * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
353 * g_task_run_in_thread (task, bake_cake_thread);
354 * g_object_unref (task);
355 * }
356 *
357 * Cake *
358 * baker_bake_cake_finish (Baker         *self,
359 * GAsyncResult  *result,
360 * GError       **error)
361 * {
362 * g_return_val_if_fail (g_task_is_valid (result, self), NULL);
363 *
364 * return g_task_propagate_pointer (G_TASK (result), error);
365 * }
366 * ]|
367 *
368 * ## Adding cancellability to uncancellable tasks
369 *
370 * Finally, g_task_run_in_thread() and g_task_run_in_thread_sync()
371 * can be used to turn an uncancellable operation into a
372 * cancellable one. If you call g_task_set_return_on_cancel(),
373 * passing %TRUE, then if the task's #GCancellable is cancelled,
374 * it will return control back to the caller immediately, while
375 * allowing the task thread to continue running in the background
376 * (and simply discarding its result when it finally does finish).
377 * Provided that the task thread is careful about how it uses
378 * locks and other externally-visible resources, this allows you
379 * to make "GLib-friendly" asynchronous and cancellable
380 * synchronous variants of blocking APIs.
381 *
382 * Cancelling a task:
383 * |[<!-- language="C" -->
384 * static void
385 * bake_cake_thread (GTask         *task,
386 * gpointer       source_object,
387 * gpointer       task_data,
388 * GCancellable  *cancellable)
389 * {
390 * Baker *self = source_object;
391 * CakeData *cake_data = task_data;
392 * Cake *cake;
393 * GError *error = NULL;
394 *
395 * cake = bake_cake (baker, cake_data->radius, cake_data->flavor,
396 * cake_data->frosting, cake_data->message,
397 * &error);
398 * if (error)
399 * {
400 * g_task_return_error (task, error);
401 * return;
402 * }
403 *
404 * // If the task has already been cancelled, then we don't want to add
405 * // the cake to the cake cache. Likewise, we don't  want to have the
406 * // task get cancelled in the middle of updating the cache.
407 * // g_task_set_return_on_cancel() will return %TRUE here if it managed
408 * // to disable return-on-cancel, or %FALSE if the task was cancelled
409 * // before it could.
410 * if (g_task_set_return_on_cancel (task, FALSE))
411 * {
412 * // If the caller cancels at this point, their
413 * // GAsyncReadyCallback won't be invoked until we return,
414 * // so we don't have to worry that this code will run at
415 * // the same time as that code does. But if there were
416 * // other functions that might look at the cake cache,
417 * // then we'd probably need a GMutex here as well.
418 * baker_add_cake_to_cache (baker, cake);
419 * g_task_return_pointer (task, cake, g_object_unref);
420 * }
421 * }
422 *
423 * void
424 * baker_bake_cake_async (Baker               *self,
425 * guint                radius,
426 * CakeFlavor           flavor,
427 * CakeFrostingType     frosting,
428 * const char          *message,
429 * GCancellable        *cancellable,
430 * GAsyncReadyCallback  callback,
431 * gpointer             user_data)
432 * {
433 * CakeData *cake_data;
434 * GTask *task;
435 *
436 * cake_data = g_slice_new (CakeData);
437 *
438 * ...
439 *
440 * task = g_task_new (self, cancellable, callback, user_data);
441 * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
442 * g_task_set_return_on_cancel (task, TRUE);
443 * g_task_run_in_thread (task, bake_cake_thread);
444 * }
445 *
446 * Cake *
447 * baker_bake_cake_sync (Baker               *self,
448 * guint                radius,
449 * CakeFlavor           flavor,
450 * CakeFrostingType     frosting,
451 * const char          *message,
452 * GCancellable        *cancellable,
453 * GError             **error)
454 * {
455 * CakeData *cake_data;
456 * GTask *task;
457 * Cake *cake;
458 *
459 * cake_data = g_slice_new (CakeData);
460 *
461 * ...
462 *
463 * task = g_task_new (self, cancellable, NULL, NULL);
464 * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
465 * g_task_set_return_on_cancel (task, TRUE);
466 * g_task_run_in_thread_sync (task, bake_cake_thread);
467 *
468 * cake = g_task_propagate_pointer (task, error);
469 * g_object_unref (task);
470 * return cake;
471 * }
472 * ]|
473 *
474 * ## Porting from GSimpleAsyncResult
475 *
476 * #GTask's API attempts to be simpler than #GSimpleAsyncResult's
477 * in several ways:
478 * - You can save task-specific data with g_task_set_task_data(), and
479 * retrieve it later with g_task_get_task_data(). This replaces the
480 * abuse of g_simple_async_result_set_op_res_gpointer() for the same
481 * purpose with #GSimpleAsyncResult.
482 * - In addition to the task data, #GTask also keeps track of the
483 * [priority][io-priority], #GCancellable, and
484 * #GMainContext associated with the task, so tasks that consist of
485 * a chain of simpler asynchronous operations will have easy access
486 * to those values when starting each sub-task.
487 * - g_task_return_error_if_cancelled() provides simplified
488 * handling for cancellation. In addition, cancellation
489 * overrides any other #GTask return value by default, like
490 * #GSimpleAsyncResult does when
491 * g_simple_async_result_set_check_cancellable() is called.
492 * (You can use g_task_set_check_cancellable() to turn off that
493 * behavior.) On the other hand, g_task_run_in_thread()
494 * guarantees that it will always run your
495 * `task_func`, even if the task's #GCancellable
496 * is already cancelled before the task gets a chance to run;
497 * you can start your `task_func` with a
498 * g_task_return_error_if_cancelled() check if you need the
499 * old behavior.
500 * - The "return" methods (eg, g_task_return_pointer())
501 * automatically cause the task to be "completed" as well, and
502 * there is no need to worry about the "complete" vs "complete
503 * in idle" distinction. (#GTask automatically figures out
504 * whether the task's callback can be invoked directly, or
505 * if it needs to be sent to another #GMainContext, or delayed
506 * until the next iteration of the current #GMainContext.)
507 * - The "finish" functions for #GTask-based operations are generally
508 * much simpler than #GSimpleAsyncResult ones, normally consisting
509 * of only a single call to g_task_propagate_pointer() or the like.
510 * Since g_task_propagate_pointer() "steals" the return value from
511 * the #GTask, it is not necessary to juggle pointers around to
512 * prevent it from being freed twice.
513 * - With #GSimpleAsyncResult, it was common to call
514 * g_simple_async_result_propagate_error() from the
515 * `_finish()` wrapper function, and have
516 * virtual method implementations only deal with successful
517 * returns. This behavior is deprecated, because it makes it
518 * difficult for a subclass to chain to a parent class's async
519 * methods. Instead, the wrapper function should just be a
520 * simple wrapper, and the virtual method should call an
521 * appropriate `g_task_propagate_` function.
522 * Note that wrapper methods can now use
523 * g_async_result_legacy_propagate_error() to do old-style
524 * #GSimpleAsyncResult error-returning behavior, and
525 * g_async_result_is_tagged() to check if a result is tagged as
526 * having come from the `_async()` wrapper
527 * function (for "short-circuit" results, such as when passing
528 * 0 to g_input_stream_read_async()).
529 */
530public class Task : ObjectG, AsyncResultIF
531{
532        /** the main Gtk struct */
533        protected GTask* gTask;
534
535        /** Get the main Gtk struct */
536        public GTask* getTaskStruct()
537        {
538                return gTask;
539        }
540
541        /** the main Gtk struct as a void* */
542        protected override void* getStruct()
543        {
544                return cast(void*)gTask;
545        }
546
547        protected override void setStruct(GObject* obj)
548        {
549                gTask = cast(GTask*)obj;
550                super.setStruct(obj);
551        }
552
553        /**
554         * Sets our main struct and passes it to the parent class.
555         */
556        public this (GTask* gTask, bool ownedRef = false)
557        {
558                this.gTask = gTask;
559                super(cast(GObject*)gTask, ownedRef);
560        }
561
562        // add the AsyncResult capabilities
563        mixin AsyncResultT!(GTask);
564
565
566        /** */
567        public static GType getType()
568        {
569                return g_task_get_type();
570        }
571
572        /**
573         * Creates a #GTask acting on @source_object, which will eventually be
574         * used to invoke @callback in the current
575         * [thread-default main context][g-main-context-push-thread-default].
576         *
577         * Call this in the "start" method of your asynchronous method, and
578         * pass the #GTask around throughout the asynchronous operation. You
579         * can use g_task_set_task_data() to attach task-specific data to the
580         * object, which you can retrieve later via g_task_get_task_data().
581         *
582         * By default, if @cancellable is cancelled, then the return value of
583         * the task will always be %G_IO_ERROR_CANCELLED, even if the task had
584         * already completed before the cancellation. This allows for
585         * simplified handling in cases where cancellation may imply that
586         * other objects that the task depends on have been destroyed. If you
587         * do not want this behavior, you can use
588         * g_task_set_check_cancellable() to change it.
589         *
590         * Params:
591         *     sourceObject = the #GObject that owns
592         *         this task, or %NULL.
593         *     cancellable = optional #GCancellable object, %NULL to ignore.
594         *     callback = a #GAsyncReadyCallback.
595         *     callbackData = user data passed to @callback.
596         *
597         * Returns: a #GTask.
598         *
599         * Since: 2.36
600         *
601         * Throws: ConstructionException GTK+ fails to create the object.
602         */
603        public this(ObjectG sourceObject, Cancellable cancellable, GAsyncReadyCallback callback, void* callbackData)
604        {
605                auto p = g_task_new((sourceObject is null) ? null : sourceObject.getObjectGStruct(), (cancellable is null) ? null : cancellable.getCancellableStruct(), callback, callbackData);
606               
607                if(p is null)
608                {
609                        throw new ConstructionException("null returned by new");
610                }
611               
612                this(cast(GTask*) p, true);
613        }
614
615        /**
616         * Checks that @result is a #GTask, and that @source_object is its
617         * source object (or that @source_object is %NULL and @result has no
618         * source object). This can be used in g_return_if_fail() checks.
619         *
620         * Params:
621         *     result = A #GAsyncResult
622         *     sourceObject = the source object
623         *         expected to be associated with the task
624         *
625         * Returns: %TRUE if @result and @source_object are valid, %FALSE
626         *     if not
627         *
628         * Since: 2.36
629         */
630        public static bool isValid(AsyncResultIF result, ObjectG sourceObject)
631        {
632                return g_task_is_valid((result is null) ? null : result.getAsyncResultStruct(), (sourceObject is null) ? null : sourceObject.getObjectGStruct()) != 0;
633        }
634
635        /**
636         * Creates a #GTask and then immediately calls g_task_return_error()
637         * on it. Use this in the wrapper function of an asynchronous method
638         * when you want to avoid even calling the virtual method. You can
639         * then use g_async_result_is_tagged() in the finish method wrapper to
640         * check if the result there is tagged as having been created by the
641         * wrapper method, and deal with it appropriately if so.
642         *
643         * See also g_task_report_new_error().
644         *
645         * Params:
646         *     sourceObject = the #GObject that owns
647         *         this task, or %NULL.
648         *     callback = a #GAsyncReadyCallback.
649         *     callbackData = user data passed to @callback.
650         *     sourceTag = an opaque pointer indicating the source of this task
651         *     error = error to report
652         *
653         * Since: 2.36
654         */
655        public static void reportError(ObjectG sourceObject, GAsyncReadyCallback callback, void* callbackData, void* sourceTag, ErrorG error)
656        {
657                g_task_report_error((sourceObject is null) ? null : sourceObject.getObjectGStruct(), callback, callbackData, sourceTag, (error is null) ? null : error.getErrorGStruct());
658        }
659
660        /**
661         * A utility function for dealing with async operations where you need
662         * to wait for a #GSource to trigger. Attaches @source to @task's
663         * #GMainContext with @task's [priority][io-priority], and sets @source's
664         * callback to @callback, with @task as the callback's `user_data`.
665         *
666         * This takes a reference on @task until @source is destroyed.
667         *
668         * Params:
669         *     source = the source to attach
670         *     callback = the callback to invoke when @source triggers
671         *
672         * Since: 2.36
673         */
674        public void attachSource(Source source, GSourceFunc callback)
675        {
676                g_task_attach_source(gTask, (source is null) ? null : source.getSourceStruct(), callback);
677        }
678
679        /**
680         * Gets @task's #GCancellable
681         *
682         * Returns: @task's #GCancellable
683         *
684         * Since: 2.36
685         */
686        public Cancellable getCancellable()
687        {
688                auto p = g_task_get_cancellable(gTask);
689               
690                if(p is null)
691                {
692                        return null;
693                }
694               
695                return ObjectG.getDObject!(Cancellable)(cast(GCancellable*) p);
696        }
697
698        /**
699         * Gets @task's check-cancellable flag. See
700         * g_task_set_check_cancellable() for more details.
701         *
702         * Since: 2.36
703         */
704        public bool getCheckCancellable()
705        {
706                return g_task_get_check_cancellable(gTask) != 0;
707        }
708
709        /**
710         * Gets the value of #GTask:completed. This changes from %FALSE to %TRUE after
711         * the task’s callback is invoked, and will return %FALSE if called from inside
712         * the callback.
713         *
714         * Returns: %TRUE if the task has completed, %FALSE otherwise.
715         *
716         * Since: 2.44
717         */
718        public bool getCompleted()
719        {
720                return g_task_get_completed(gTask) != 0;
721        }
722
723        /**
724         * Gets the #GMainContext that @task will return its result in (that
725         * is, the context that was the
726         * [thread-default main context][g-main-context-push-thread-default]
727         * at the point when @task was created).
728         *
729         * This will always return a non-%NULL value, even if the task's
730         * context is the default #GMainContext.
731         *
732         * Returns: @task's #GMainContext
733         *
734         * Since: 2.36
735         */
736        public MainContext getContext()
737        {
738                auto p = g_task_get_context(gTask);
739               
740                if(p is null)
741                {
742                        return null;
743                }
744               
745                return new MainContext(cast(GMainContext*) p);
746        }
747
748        /**
749         * Gets @task's priority
750         *
751         * Returns: @task's priority
752         *
753         * Since: 2.36
754         */
755        public int getPriority()
756        {
757                return g_task_get_priority(gTask);
758        }
759
760        /**
761         * Gets @task's return-on-cancel flag. See
762         * g_task_set_return_on_cancel() for more details.
763         *
764         * Since: 2.36
765         */
766        public bool getReturnOnCancel()
767        {
768                return g_task_get_return_on_cancel(gTask) != 0;
769        }
770
771        /**
772         * Gets the source object from @task. Like
773         * g_async_result_get_source_object(), but does not ref the object.
774         *
775         * Returns: @task's source object, or %NULL
776         *
777         * Since: 2.36
778         */
779        public ObjectG getSourceObject()
780        {
781                auto p = g_task_get_source_object(gTask);
782               
783                if(p is null)
784                {
785                        return null;
786                }
787               
788                return ObjectG.getDObject!(ObjectG)(cast(GObject*) p);
789        }
790
791        /**
792         * Gets @task's source tag. See g_task_set_source_tag().
793         *
794         * Returns: @task's source tag
795         *
796         * Since: 2.36
797         */
798        public void* getSourceTag()
799        {
800                return g_task_get_source_tag(gTask);
801        }
802
803        /**
804         * Gets @task's `task_data`.
805         *
806         * Returns: @task's `task_data`.
807         *
808         * Since: 2.36
809         */
810        public void* getTaskData()
811        {
812                return g_task_get_task_data(gTask);
813        }
814
815        /**
816         * Tests if @task resulted in an error.
817         *
818         * Returns: %TRUE if the task resulted in an error, %FALSE otherwise.
819         *
820         * Since: 2.36
821         */
822        public bool hadError()
823        {
824                return g_task_had_error(gTask) != 0;
825        }
826
827        /**
828         * Gets the result of @task as a #gboolean.
829         *
830         * If the task resulted in an error, or was cancelled, then this will
831         * instead return %FALSE and set @error.
832         *
833         * Since this method transfers ownership of the return value (or
834         * error) to the caller, you may only call it once.
835         *
836         * Returns: the task result, or %FALSE on error
837         *
838         * Since: 2.36
839         *
840         * Throws: GException on failure.
841         */
842        public bool propagateBoolean()
843        {
844                GError* err = null;
845               
846                auto p = g_task_propagate_boolean(gTask, &err) != 0;
847               
848                if (err !is null)
849                {
850                        throw new GException( new ErrorG(err) );
851                }
852               
853                return p;
854        }
855
856        /**
857         * Gets the result of @task as an integer (#gssize).
858         *
859         * If the task resulted in an error, or was cancelled, then this will
860         * instead return -1 and set @error.
861         *
862         * Since this method transfers ownership of the return value (or
863         * error) to the caller, you may only call it once.
864         *
865         * Returns: the task result, or -1 on error
866         *
867         * Since: 2.36
868         *
869         * Throws: GException on failure.
870         */
871        public ptrdiff_t propagateInt()
872        {
873                GError* err = null;
874               
875                auto p = g_task_propagate_int(gTask, &err);
876               
877                if (err !is null)
878                {
879                        throw new GException( new ErrorG(err) );
880                }
881               
882                return p;
883        }
884
885        /**
886         * Gets the result of @task as a pointer, and transfers ownership
887         * of that value to the caller.
888         *
889         * If the task resulted in an error, or was cancelled, then this will
890         * instead return %NULL and set @error.
891         *
892         * Since this method transfers ownership of the return value (or
893         * error) to the caller, you may only call it once.
894         *
895         * Returns: the task result, or %NULL on error
896         *
897         * Since: 2.36
898         *
899         * Throws: GException on failure.
900         */
901        public void* propagatePointer()
902        {
903                GError* err = null;
904               
905                auto p = g_task_propagate_pointer(gTask, &err);
906               
907                if (err !is null)
908                {
909                        throw new GException( new ErrorG(err) );
910                }
911               
912                return p;
913        }
914
915        /**
916         * Sets @task's result to @result and completes the task (see
917         * g_task_return_pointer() for more discussion of exactly what this
918         * means).
919         *
920         * Params:
921         *     result = the #gboolean result of a task function.
922         *
923         * Since: 2.36
924         */
925        public void returnBoolean(bool result)
926        {
927                g_task_return_boolean(gTask, result);
928        }
929
930        /**
931         * Sets @task's result to @error (which @task assumes ownership of)
932         * and completes the task (see g_task_return_pointer() for more
933         * discussion of exactly what this means).
934         *
935         * Note that since the task takes ownership of @error, and since the
936         * task may be completed before returning from g_task_return_error(),
937         * you cannot assume that @error is still valid after calling this.
938         * Call g_error_copy() on the error if you need to keep a local copy
939         * as well.
940         *
941         * See also g_task_return_new_error().
942         *
943         * Params:
944         *     error = the #GError result of a task function.
945         *
946         * Since: 2.36
947         */
948        public void returnError(ErrorG error)
949        {
950                g_task_return_error(gTask, (error is null) ? null : error.getErrorGStruct());
951        }
952
953        /**
954         * Checks if @task's #GCancellable has been cancelled, and if so, sets
955         * @task's error accordingly and completes the task (see
956         * g_task_return_pointer() for more discussion of exactly what this
957         * means).
958         *
959         * Returns: %TRUE if @task has been cancelled, %FALSE if not
960         *
961         * Since: 2.36
962         */
963        public bool returnErrorIfCancelled()
964        {
965                return g_task_return_error_if_cancelled(gTask) != 0;
966        }
967
968        /**
969         * Sets @task's result to @result and completes the task (see
970         * g_task_return_pointer() for more discussion of exactly what this
971         * means).
972         *
973         * Params:
974         *     result = the integer (#gssize) result of a task function.
975         *
976         * Since: 2.36
977         */
978        public void returnInt(ptrdiff_t result)
979        {
980                g_task_return_int(gTask, result);
981        }
982
983        /**
984         * Sets @task's result to @result and completes the task. If @result
985         * is not %NULL, then @result_destroy will be used to free @result if
986         * the caller does not take ownership of it with
987         * g_task_propagate_pointer().
988         *
989         * "Completes the task" means that for an ordinary asynchronous task
990         * it will either invoke the task's callback, or else queue that
991         * callback to be invoked in the proper #GMainContext, or in the next
992         * iteration of the current #GMainContext. For a task run via
993         * g_task_run_in_thread() or g_task_run_in_thread_sync(), calling this
994         * method will save @result to be returned to the caller later, but
995         * the task will not actually be completed until the #GTaskThreadFunc
996         * exits.
997         *
998         * Note that since the task may be completed before returning from
999         * g_task_return_pointer(), you cannot assume that @result is still
1000         * valid after calling this, unless you are still holding another
1001         * reference on it.
1002         *
1003         * Params:
1004         *     result = the pointer result of a task
1005         *         function
1006         *     resultDestroy = a #GDestroyNotify function.
1007         *
1008         * Since: 2.36
1009         */
1010        public void returnPointer(void* result, GDestroyNotify resultDestroy)
1011        {
1012                g_task_return_pointer(gTask, result, resultDestroy);
1013        }
1014
1015        /**
1016         * Runs @task_func in another thread. When @task_func returns, @task's
1017         * #GAsyncReadyCallback will be invoked in @task's #GMainContext.
1018         *
1019         * This takes a ref on @task until the task completes.
1020         *
1021         * See #GTaskThreadFunc for more details about how @task_func is handled.
1022         *
1023         * Although GLib currently rate-limits the tasks queued via
1024         * g_task_run_in_thread(), you should not assume that it will always
1025         * do this. If you have a very large number of tasks to run, but don't
1026         * want them to all run at once, you should only queue a limited
1027         * number of them at a time.
1028         *
1029         * Params:
1030         *     taskFunc = a #GTaskThreadFunc
1031         *
1032         * Since: 2.36
1033         */
1034        public void runInThread(GTaskThreadFunc taskFunc)
1035        {
1036                g_task_run_in_thread(gTask, taskFunc);
1037        }
1038
1039        /**
1040         * Runs @task_func in another thread, and waits for it to return or be
1041         * cancelled. You can use g_task_propagate_pointer(), etc, afterward
1042         * to get the result of @task_func.
1043         *
1044         * See #GTaskThreadFunc for more details about how @task_func is handled.
1045         *
1046         * Normally this is used with tasks created with a %NULL
1047         * `callback`, but note that even if the task does
1048         * have a callback, it will not be invoked when @task_func returns.
1049         * #GTask:completed will be set to %TRUE just before this function returns.
1050         *
1051         * Although GLib currently rate-limits the tasks queued via
1052         * g_task_run_in_thread_sync(), you should not assume that it will
1053         * always do this. If you have a very large number of tasks to run,
1054         * but don't want them to all run at once, you should only queue a
1055         * limited number of them at a time.
1056         *
1057         * Params:
1058         *     taskFunc = a #GTaskThreadFunc
1059         *
1060         * Since: 2.36
1061         */
1062        public void runInThreadSync(GTaskThreadFunc taskFunc)
1063        {
1064                g_task_run_in_thread_sync(gTask, taskFunc);
1065        }
1066
1067        /**
1068         * Sets or clears @task's check-cancellable flag. If this is %TRUE
1069         * (the default), then g_task_propagate_pointer(), etc, and
1070         * g_task_had_error() will check the task's #GCancellable first, and
1071         * if it has been cancelled, then they will consider the task to have
1072         * returned an "Operation was cancelled" error
1073         * (%G_IO_ERROR_CANCELLED), regardless of any other error or return
1074         * value the task may have had.
1075         *
1076         * If @check_cancellable is %FALSE, then the #GTask will not check the
1077         * cancellable itself, and it is up to @task's owner to do this (eg,
1078         * via g_task_return_error_if_cancelled()).
1079         *
1080         * If you are using g_task_set_return_on_cancel() as well, then
1081         * you must leave check-cancellable set %TRUE.
1082         *
1083         * Params:
1084         *     checkCancellable = whether #GTask will check the state of
1085         *         its #GCancellable for you.
1086         *
1087         * Since: 2.36
1088         */
1089        public void setCheckCancellable(bool checkCancellable)
1090        {
1091                g_task_set_check_cancellable(gTask, checkCancellable);
1092        }
1093
1094        /**
1095         * Sets @task's priority. If you do not call this, it will default to
1096         * %G_PRIORITY_DEFAULT.
1097         *
1098         * This will affect the priority of #GSources created with
1099         * g_task_attach_source() and the scheduling of tasks run in threads,
1100         * and can also be explicitly retrieved later via
1101         * g_task_get_priority().
1102         *
1103         * Params:
1104         *     priority = the [priority][io-priority] of the request
1105         *
1106         * Since: 2.36
1107         */
1108        public void setPriority(int priority)
1109        {
1110                g_task_set_priority(gTask, priority);
1111        }
1112
1113        /**
1114         * Sets or clears @task's return-on-cancel flag. This is only
1115         * meaningful for tasks run via g_task_run_in_thread() or
1116         * g_task_run_in_thread_sync().
1117         *
1118         * If @return_on_cancel is %TRUE, then cancelling @task's
1119         * #GCancellable will immediately cause it to return, as though the
1120         * task's #GTaskThreadFunc had called
1121         * g_task_return_error_if_cancelled() and then returned.
1122         *
1123         * This allows you to create a cancellable wrapper around an
1124         * uninterruptable function. The #GTaskThreadFunc just needs to be
1125         * careful that it does not modify any externally-visible state after
1126         * it has been cancelled. To do that, the thread should call
1127         * g_task_set_return_on_cancel() again to (atomically) set
1128         * return-on-cancel %FALSE before making externally-visible changes;
1129         * if the task gets cancelled before the return-on-cancel flag could
1130         * be changed, g_task_set_return_on_cancel() will indicate this by
1131         * returning %FALSE.
1132         *
1133         * You can disable and re-enable this flag multiple times if you wish.
1134         * If the task's #GCancellable is cancelled while return-on-cancel is
1135         * %FALSE, then calling g_task_set_return_on_cancel() to set it %TRUE
1136         * again will cause the task to be cancelled at that point.
1137         *
1138         * If the task's #GCancellable is already cancelled before you call
1139         * g_task_run_in_thread()/g_task_run_in_thread_sync(), then the
1140         * #GTaskThreadFunc will still be run (for consistency), but the task
1141         * will also be completed right away.
1142         *
1143         * Params:
1144         *     returnOnCancel = whether the task returns automatically when
1145         *         it is cancelled.
1146         *
1147         * Returns: %TRUE if @task's return-on-cancel flag was changed to
1148         *     match @return_on_cancel. %FALSE if @task has already been
1149         *     cancelled.
1150         *
1151         * Since: 2.36
1152         */
1153        public bool setReturnOnCancel(bool returnOnCancel)
1154        {
1155                return g_task_set_return_on_cancel(gTask, returnOnCancel) != 0;
1156        }
1157
1158        /**
1159         * Sets @task's source tag. You can use this to tag a task return
1160         * value with a particular pointer (usually a pointer to the function
1161         * doing the tagging) and then later check it using
1162         * g_task_get_source_tag() (or g_async_result_is_tagged()) in the
1163         * task's "finish" function, to figure out if the response came from a
1164         * particular place.
1165         *
1166         * Params:
1167         *     sourceTag = an opaque pointer indicating the source of this task
1168         *
1169         * Since: 2.36
1170         */
1171        public void setSourceTag(void* sourceTag)
1172        {
1173                g_task_set_source_tag(gTask, sourceTag);
1174        }
1175
1176        /**
1177         * Sets @task's task data (freeing the existing task data, if any).
1178         *
1179         * Params:
1180         *     taskData = task-specific data
1181         *     taskDataDestroy = #GDestroyNotify for @task_data
1182         *
1183         * Since: 2.36
1184         */
1185        public void setTaskData(void* taskData, GDestroyNotify taskDataDestroy)
1186        {
1187                g_task_set_task_data(gTask, taskData, taskDataDestroy);
1188        }
1189}
Note: See TracBrowser for help on using the repository browser.