Struct Task 

pub struct Task<V: ValueType + Send> { /* private fields */ }

Task provides idiomatic access to gio’s GTask API, for instance by being generic over their value type, while not completely departing from the underlying C API. Task is Send and Sync and requires its value to also be Send and Sync, thus is useful to to implement gio style asynchronous tasks that run in threads. If you need to only run tasks in glib main loop see the LocalTask type.

The constructors of LocalTask and Task is marked as unsafe because this API does not allow to automatically enforce all the invariants required to be a completely safe abstraction. The caller is responsible to ensure the following requirements are satisfied

• You should not create a LocalTask, upcast it to a glib::Object and then downcast it to a Task, as this will bypass the thread safety requirements

• You should ensure that the return_result, return_error_if_cancelled and propagate() methods are only called once. error); if (error) { g_task_return_error (task, error); return; }

  // If the task has already been cancelled, then we don’t want to add // the cake to the cake cache. Likewise, we don’t want to have the // task get cancelled in the middle of updating the cache. // g_task_set_return_on_cancel() will return true here if it managed // to disable return-on-cancel, or false if the task was cancelled // before it could. if (g_task_set_return_on_cancel (task, FALSE)) { // If the caller cancels at this point, their // GAsyncReadyCallback won’t be invoked until we return, // so we don’t have to worry that this code will run at // the same time as that code does. But if there were // other functions that might look at the cake cache, // then we’d probably need a GMutex here as well. baker_add_cake_to_cache (baker, cake); g_task_return_pointer (task, cake, g_object_unref); } }

void baker_bake_cake_async (Baker *self, guint radius, CakeFlavor flavor, CakeFrostingType frosting, const char *message, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data) { CakeData *cake_data; GTask *task;

cake_data = g_slice_new (CakeData);

…

task = g_task_new (self, cancellable, callback, user_data); g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); g_task_set_return_on_cancel (task, TRUE); g_task_run_in_thread (task, bake_cake_thread); }

Cake * baker_bake_cake_sync (Baker *self, guint radius, CakeFlavor flavor, CakeFrostingType frosting, const char *message, GCancellable *cancellable, GError **error) { CakeData *cake_data; GTask *task; Cake *cake;

cake_data = g_slice_new (CakeData);

…

task = g_task_new (self, cancellable, NULL, NULL); g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); g_task_set_return_on_cancel (task, TRUE); g_task_run_in_thread_sync (task, bake_cake_thread);

cake = g_task_propagate_pointer (task, error); g_object_unref (task); return cake; }

## Porting from `Gio::SimpleAsyncResult`

`GTask`’s API attempts to be simpler than `Gio::SimpleAsyncResult`’s
in several ways:

- You can save task-specific data with [`set_task_data()`][Self::set_task_data()], and
  retrieve it later with [`task_data()`][Self::task_data()]. This replaces the
  abuse of `Gio::SimpleAsyncResult::set_op_res_gpointer()` for the same
  purpose with `Gio::SimpleAsyncResult`.
- In addition to the task data, `GTask` also keeps track of the
  [priority](iface.AsyncResult.html#io-priority), [`Cancellable`][crate::Cancellable],
  and [`glib::MainContext`][crate::glib::MainContext] associated with the task, so tasks that
  consist of a chain of simpler asynchronous operations will have easy access
  to those values when starting each sub-task.
- [`return_error_if_cancelled()`][Self::return_error_if_cancelled()] provides simplified
  handling for cancellation. In addition, cancellation
  overrides any other `GTask` return value by default, like
  `Gio::SimpleAsyncResult` does when
  `Gio::SimpleAsyncResult::set_check_cancellable()` is called.
  (You can use [`set_check_cancellable()`][Self::set_check_cancellable()] to turn off that
  behavior.) On the other hand, [`run_in_thread()`][Self::run_in_thread()]
  guarantees that it will always run your
  `task_func`, even if the task’s [`Cancellable`][crate::Cancellable]
  is already cancelled before the task gets a chance to run;
  you can start your `task_func` with a
  [`return_error_if_cancelled()`][Self::return_error_if_cancelled()] check if you need the
  old behavior.
- The ‘return’ methods (eg, [`return_pointer()`][Self::return_pointer()])
  automatically cause the task to be ‘completed’ as well, and
  there is no need to worry about the ‘complete’ vs ‘complete in idle’
  distinction. (`GTask` automatically figures out
  whether the task’s callback can be invoked directly, or
  if it needs to be sent to another [`glib::MainContext`][crate::glib::MainContext], or delayed
  until the next iteration of the current [`glib::MainContext`][crate::glib::MainContext].)
- The ‘finish’ functions for `GTask` based operations are generally
  much simpler than `Gio::SimpleAsyncResult` ones, normally consisting
  of only a single call to [`propagate_pointer()`][Self::propagate_pointer()] or the like.
  Since [`propagate_pointer()`][Self::propagate_pointer()] ‘steals’ the return value from
  the `GTask`, it is not necessary to juggle pointers around to
  prevent it from being freed twice.
- With `Gio::SimpleAsyncResult`, it was common to call
  `Gio::SimpleAsyncResult::propagate_error()` from the
  `_finish()` wrapper function, and have
  virtual method implementations only deal with successful
  returns. This behavior is deprecated, because it makes it
  difficult for a subclass to chain to a parent class’s async
  methods. Instead, the wrapper function should just be a
  simple wrapper, and the virtual method should call an
  appropriate `g_task_propagate_` function.
  Note that wrapper methods can now use
  [`AsyncResultExt::legacy_propagate_error()`][crate::prelude::AsyncResultExt::legacy_propagate_error()] to do old-style
  `Gio::SimpleAsyncResult` error-returning behavior, and
  `Gio::AsyncResult::is_tagged()` to check if a result is tagged as
  having come from the `_async()` wrapper
  function (for ‘short-circuit’ results, such as when passing
  `0` to [`InputStreamExtManual::read_async()`][crate::prelude::InputStreamExtManual::read_async()]).

## Thread-safety considerations

Due to some infelicities in the API design, there is a
thread-safety concern that users of `GTask` have to be aware of:

If the `main` thread drops its last reference to the source object
or the task data before the task is finalized, then the finalizers
of these objects may be called on the worker thread.

This is a problem if the finalizers use non-threadsafe API, and
can lead to hard-to-debug crashes. Possible workarounds include:

- Clear task data in a signal handler for `notify::completed`
- Keep iterating a main context in the main thread and defer
  dropping the reference to the source object to that main
  context when the task is finalized

## Properties


#### `completed`
 Whether the task has completed, meaning its callback (if set) has been
invoked.

This can only happen after g_task_return_pointer(),
g_task_return_error() or one of the other return functions have been called
on the task. However, it is not guaranteed to happen immediately after
those functions are called, as the task’s callback may need to be scheduled
to run in a different thread.

That means it is **not safe** to use this property to track whether a
return function has been called on the #GTask. Callers must do that
tracking themselves, typically by linking the lifetime of the #GTask to the
control flow of their code.

This property is guaranteed to change from [`false`] to [`true`] exactly once.

The #GObject::notify signal for this change is emitted in the same main
context as the task’s callback, immediately after that callback is invoked.

Readable

# Implements

[`trait@glib::ObjectExt`], [`AsyncResultExt`][trait@crate::prelude::AsyncResultExt]

GLib type: GObject with reference counted clone semantics.

Implementations

impl<V: Into<Value> + ValueType + Send> Task<V>

pub unsafe fn new<S, P, Q>( source_object: Option<&S>, cancellable: Option<&P>, callback: Q, ) -> Self

where S: IsA<Object> + Send, P: IsA<Cancellable>, Q: FnOnce(Task<V>, Option<&S>) + Send + 'static,

pub fn cancellable(&self) -> Option<Cancellable>

pub fn is_check_cancellable(&self) -> bool

pub fn set_check_cancellable(&self, check_cancellable: bool)

pub fn set_name(&self, name: Option<&str>)

Available on crate feature v2_60 only.

pub fn set_return_on_cancel(&self, return_on_cancel: bool) -> bool

pub fn is_valid( result: &impl IsA<AsyncResult>, source_object: Option<&impl IsA<Object>>, ) -> bool

pub fn priority(&self) -> Priority

pub fn set_priority(&self, priority: Priority)

pub fn is_completed(&self) -> bool

pub fn context(&self) -> MainContext

pub fn name(&self) -> Option<GString>

Available on crate feature v2_60 only.

pub fn is_return_on_cancel(&self) -> bool

pub fn had_error(&self) -> bool

pub fn connect_completed_notify<F>(&self, f: F) -> SignalHandlerId

where F: Fn(&Task<V>) + Send + 'static,

pub unsafe fn return_error_if_cancelled(&self) -> bool

pub unsafe fn return_result(self, result: Result<V, Error>)

Set the result of the task

Safety

The value must be read with Task::propagate, g_task_propagate_value or g_task_propagate_pointer.

pub unsafe fn return_boolean_result(self, result: Result<bool, Error>)

Set the result of the task as a boolean

Safety

The value must be read with Task::propagate_boolean, or g_task_propagate_boolean.

pub unsafe fn return_int_result(self, result: Result<isize, Error>)

Set the result of the task as an int

Safety

The value must be read with Task::propagate_int, or g_task_propagate_int.

pub unsafe fn propagate(self) -> Result<V, Error>

Gets the result of the task and transfers ownership of it

Safety

This must only be called once, and only if the result was set via Task::return_result, g_task_return_value or g_task_return_pointer.

pub unsafe fn propagate_boolean(self) -> Result<bool, Error>

Gets the result of the task as a boolean, or the error

Safety

This must only be called once, and only if the result was set via Task::return_boolean_result, or g_task_return_boolean.

pub unsafe fn propagate_int(self) -> Result<isize, Error>

Gets the result of the task as an int, or the error

Safety

This must only be called once, and only if the result was set via Task::return_int_result, or g_task_return_int.

impl<V: ValueType + Send> Task<V>

pub fn run_in_thread<S, Q>(&self, task_func: Q)

where S: IsA<Object> + Send, Q: FnOnce(Self, Option<&S>, Option<&Cancellable>) + Send + 'static,

Trait Implementations

impl<V: ValueType + Send> Clone for Task<V>

fn clone(&self) -> Self

Makes a clone of this shared reference.

This increments the strong reference count of the object. Dropping the object will decrement it again.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<V: ValueType + Send> Debug for Task<V>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<V: ValueType + Send> Eq for Task<V>

impl<V: ValueType + Send> HasParamSpec for Task<V>

type ParamSpec = ParamSpecObject

type SetValue = Task<V>

Preferred value to be used as setter for the associated ParamSpec.

type BuilderFn = fn(&str) -> ParamSpecObjectBuilder<'_, Task<V>>

fn param_spec_builder() -> Self::BuilderFn

impl<V: ValueType + Send> Hash for Task<V>

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Hashes the memory address of this object.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<V: ValueType + Send> IsA<AsyncResult> for Task<V>

impl<V: ValueType + Send> Ord for Task<V>

fn cmp(&self, other: &Self) -> Ordering

Comparison for two GObjects.

Compares the memory addresses of the provided objects.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<V: ValueType + Send> ParentClassIs for Task<V>

type Parent = Object

impl<OT: ObjectType, V: ValueType + Send> PartialEq<OT> for Task<V>

fn eq(&self, other: &OT) -> bool

Equality for two GObjects.

Two GObjects are equal if their memory addresses are equal.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<OT: ObjectType, V: ValueType + Send> PartialOrd<OT> for Task<V>

fn partial_cmp(&self, other: &OT) -> Option<Ordering>

Partial comparison for two GObjects.

Compares the memory addresses of the provided objects.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<V: ValueType + Send> Send for Task<V>

impl<V: ValueType + Send> StaticType for Task<V>

fn static_type() -> Type

Returns the type identifier of Self.

impl<V: ValueType + Send> Sync for Task<V>