// Take a look at the license at the top of the repository in the LICENSE file.

use std::{boxed::Box as Box_, future::Future, mem::transmute, panic, ptr};

use glib::{
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
    value::ValueType,
};

use futures_channel::oneshot;

use crate::{AsyncResult, Cancellable};

glib::wrapper! {
    // rustdoc-stripper-ignore-next
    /// `LocalTask` 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. `LocalTask` does not require its value to be `Send`
    /// and `Sync` and thus is useful to to implement gio style asynchronous
    /// tasks that run in the glib main loop. If you need to run tasks in threads
    /// see the `Task` 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. See the `Task` type for more details.
    #[doc(alias = "GTask")]
    pub struct LocalTask<V: ValueType>(Object<ffi::GTask, ffi::GTaskClass>) @implements AsyncResult;

    match fn {
        type_ => || ffi::g_task_get_type(),
    }
}

glib::wrapper! {
    // rustdoc-stripper-ignore-next
    /// `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.
    // rustdoc-stripper-ignore-next-stop
    /// A [`Task`][crate::Task] represents and manages a cancellable "task".
    ///
    /// ## Asynchronous operations
    ///
    /// The most common usage of [`Task`][crate::Task] is as a [`AsyncResult`][crate::AsyncResult], to
    /// manage data during an asynchronous operation. You call
    /// [`new()`][Self::new()] in the "start" method, followed by
    /// [`set_task_data()`][Self::set_task_data()] and the like if you need to keep some
    /// additional data associated with the task, and then pass the
    /// task object around through your asynchronous operation.
    /// Eventually, you will call a method such as
    /// [`return_pointer()`][Self::return_pointer()] or [`return_error()`][Self::return_error()], which will
    /// save the value you give it and then invoke the task's callback
    /// function in the
    /// [thread-default main context][g-main-context-push-thread-default]
    /// where it was created (waiting until the next iteration of the main
    /// loop first, if necessary). The caller will pass the [`Task`][crate::Task] back to
    /// the operation's finish function (as a [`AsyncResult`][crate::AsyncResult]), and you can
    /// use [`propagate_pointer()`][Self::propagate_pointer()] or the like to extract the
    /// return value.
    ///
    /// Using [`Task`][crate::Task] requires the thread-default [`glib::MainContext`][crate::glib::MainContext] from when the
    /// [`Task`][crate::Task] was constructed to be running at least until the task has completed
    /// and its data has been freed.
    ///
    /// If a [`Task`][crate::Task] has been constructed and its callback set, it is an error to
    /// not call `g_task_return_*()` on it. GLib will warn at runtime if this happens
    /// (since 2.76).
    ///
    /// Here is an example for using GTask as a GAsyncResult:
    ///
    ///
    /// **⚠️ The following code is in C ⚠️**
    ///
    /// ```C
    ///     typedef struct {
    ///       CakeFrostingType frosting;
    ///       char *message;
    ///     } DecorationData;
    ///
    ///     static void
    ///     decoration_data_free (DecorationData *decoration)
    ///     {
    ///       g_free (decoration->message);
    ///       g_slice_free (DecorationData, decoration);
    ///     }
    ///
    ///     static void
    ///     baked_cb (Cake     *cake,
    ///               gpointer  user_data)
    ///     {
    ///       GTask *task = user_data;
    ///       DecorationData *decoration = g_task_get_task_data (task);
    ///       GError *error = NULL;
    ///
    ///       if (cake == NULL)
    ///         {
    ///           g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR,
    ///                                    "Go to the supermarket");
    ///           g_object_unref (task);
    ///           return;
    ///         }
    ///
    ///       if (!cake_decorate (cake, decoration->frosting, decoration->message, &error))
    ///         {
    ///           g_object_unref (cake);
    ///           // g_task_return_error() takes ownership of error
    ///           g_task_return_error (task, error);
    ///           g_object_unref (task);
    ///           return;
    ///         }
    ///
    ///       g_task_return_pointer (task, cake, g_object_unref);
    ///       g_object_unref (task);
    ///     }
    ///
    ///     void
    ///     baker_bake_cake_async (Baker               *self,
    ///                            guint                radius,
    ///                            CakeFlavor           flavor,
    ///                            CakeFrostingType     frosting,
    ///                            const char          *message,
    ///                            GCancellable        *cancellable,
    ///                            GAsyncReadyCallback  callback,
    ///                            gpointer             user_data)
    ///     {
    ///       GTask *task;
    ///       DecorationData *decoration;
    ///       Cake  *cake;
    ///
    ///       task = g_task_new (self, cancellable, callback, user_data);
    ///       if (radius < 3)
    ///         {
    ///           g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_TOO_SMALL,
    ///                                    "%ucm radius cakes are silly",
    ///                                    radius);
    ///           g_object_unref (task);
    ///           return;
    ///         }
    ///
    ///       cake = _baker_get_cached_cake (self, radius, flavor, frosting, message);
    ///       if (cake != NULL)
    ///         {
    ///           // _baker_get_cached_cake() returns a reffed cake
    ///           g_task_return_pointer (task, cake, g_object_unref);
    ///           g_object_unref (task);
    ///           return;
    ///         }
    ///
    ///       decoration = g_slice_new (DecorationData);
    ///       decoration->frosting = frosting;
    ///       decoration->message = g_strdup (message);
    ///       g_task_set_task_data (task, decoration, (GDestroyNotify) decoration_data_free);
    ///
    ///       _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task);
    ///     }
    ///
    ///     Cake *
    ///     baker_bake_cake_finish (Baker         *self,
    ///                             GAsyncResult  *result,
    ///                             GError       **error)
    ///     {
    ///       g_return_val_if_fail (g_task_is_valid (result, self), NULL);
    ///
    ///       return g_task_propagate_pointer (G_TASK (result), error);
    ///     }
    /// ```
    ///
    /// ## Chained asynchronous operations
    ///
    /// [`Task`][crate::Task] also tries to simplify asynchronous operations that
    /// internally chain together several smaller asynchronous
    /// operations. [`cancellable()`][Self::cancellable()], [`context()`][Self::context()],
    /// and [`priority()`][Self::priority()] allow you to get back the task's
    /// [`Cancellable`][crate::Cancellable], [`glib::MainContext`][crate::glib::MainContext], and [I/O priority][io-priority]
    /// when starting a new subtask, so you don't have to keep track
    /// of them yourself. [`attach_source()`][Self::attach_source()] simplifies the case
    /// of waiting for a source to fire (automatically using the correct
    /// [`glib::MainContext`][crate::glib::MainContext] and priority).
    ///
    /// Here is an example for chained asynchronous operations:
    ///
    ///
    /// **⚠️ The following code is in C ⚠️**
    ///
    /// ```C
    ///     typedef struct {
    ///       Cake *cake;
    ///       CakeFrostingType frosting;
    ///       char *message;
    ///     } BakingData;
    ///
    ///     static void
    ///     decoration_data_free (BakingData *bd)
    ///     {
    ///       if (bd->cake)
    ///         g_object_unref (bd->cake);
    ///       g_free (bd->message);
    ///       g_slice_free (BakingData, bd);
    ///     }
    ///
    ///     static void
    ///     decorated_cb (Cake         *cake,
    ///                   GAsyncResult *result,
    ///                   gpointer      user_data)
    ///     {
    ///       GTask *task = user_data;
    ///       GError *error = NULL;
    ///
    ///       if (!cake_decorate_finish (cake, result, &error))
    ///         {
    ///           g_object_unref (cake);
    ///           g_task_return_error (task, error);
    ///           g_object_unref (task);
    ///           return;
    ///         }
    ///
    ///       // baking_data_free() will drop its ref on the cake, so we have to
    ///       // take another here to give to the caller.
    ///       g_task_return_pointer (task, g_object_ref (cake), g_object_unref);
    ///       g_object_unref (task);
    ///     }
    ///
    ///     static gboolean
    ///     decorator_ready (gpointer user_data)
    ///     {
    ///       GTask *task = user_data;
    ///       BakingData *bd = g_task_get_task_data (task);
    ///
    ///       cake_decorate_async (bd->cake, bd->frosting, bd->message,
    ///                            g_task_get_cancellable (task),
    ///                            decorated_cb, task);
    ///
    ///       return G_SOURCE_REMOVE;
    ///     }
    ///
    ///     static void
    ///     baked_cb (Cake     *cake,
    ///               gpointer  user_data)
    ///     {
    ///       GTask *task = user_data;
    ///       BakingData *bd = g_task_get_task_data (task);
    ///       GError *error = NULL;
    ///
    ///       if (cake == NULL)
    ///         {
    ///           g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR,
    ///                                    "Go to the supermarket");
    ///           g_object_unref (task);
    ///           return;
    ///         }
    ///
    ///       bd->cake = cake;
    ///
    ///       // Bail out now if the user has already cancelled
    ///       if (g_task_return_error_if_cancelled (task))
    ///         {
    ///           g_object_unref (task);
    ///           return;
    ///         }
    ///
    ///       if (cake_decorator_available (cake))
    ///         decorator_ready (task);
    ///       else
    ///         {
    ///           GSource *source;
    ///
    ///           source = cake_decorator_wait_source_new (cake);
    ///           // Attach @source to @task's GMainContext and have it call
    ///           // decorator_ready() when it is ready.
    ///           g_task_attach_source (task, source, decorator_ready);
    ///           g_source_unref (source);
    ///         }
    ///     }
    ///
    ///     void
    ///     baker_bake_cake_async (Baker               *self,
    ///                            guint                radius,
    ///                            CakeFlavor           flavor,
    ///                            CakeFrostingType     frosting,
    ///                            const char          *message,
    ///                            gint                 priority,
    ///                            GCancellable        *cancellable,
    ///                            GAsyncReadyCallback  callback,
    ///                            gpointer             user_data)
    ///     {
    ///       GTask *task;
    ///       BakingData *bd;
    ///
    ///       task = g_task_new (self, cancellable, callback, user_data);
    ///       g_task_set_priority (task, priority);
    ///
    ///       bd = g_slice_new0 (BakingData);
    ///       bd->frosting = frosting;
    ///       bd->message = g_strdup (message);
    ///       g_task_set_task_data (task, bd, (GDestroyNotify) baking_data_free);
    ///
    ///       _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task);
    ///     }
    ///
    ///     Cake *
    ///     baker_bake_cake_finish (Baker         *self,
    ///                             GAsyncResult  *result,
    ///                             GError       **error)
    ///     {
    ///       g_return_val_if_fail (g_task_is_valid (result, self), NULL);
    ///
    ///       return g_task_propagate_pointer (G_TASK (result), error);
    ///     }
    /// ```
    ///
    /// ## Asynchronous operations from synchronous ones
    ///
    /// You can use [`run_in_thread()`][Self::run_in_thread()] to turn a synchronous
    /// operation into an asynchronous one, by running it in a thread.
    /// When it completes, the result will be dispatched to the
    /// [thread-default main context][g-main-context-push-thread-default]
    /// where the [`Task`][crate::Task] was created.
    ///
    /// Running a task in a thread:
    ///
    ///
    /// **⚠️ The following code is in C ⚠️**
    ///
    /// ```C
    ///     typedef struct {
    ///       guint radius;
    ///       CakeFlavor flavor;
    ///       CakeFrostingType frosting;
    ///       char *message;
    ///     } CakeData;
    ///
    ///     static void
    ///     cake_data_free (CakeData *cake_data)
    ///     {
    ///       g_free (cake_data->message);
    ///       g_slice_free (CakeData, cake_data);
    ///     }
    ///
    ///     static void
    ///     bake_cake_thread (GTask         *task,
    ///                       gpointer       source_object,
    ///                       gpointer       task_data,
    ///                       GCancellable  *cancellable)
    ///     {
    ///       Baker *self = source_object;
    ///       CakeData *cake_data = task_data;
    ///       Cake *cake;
    ///       GError *error = NULL;
    ///
    ///       cake = bake_cake (baker, cake_data->radius, cake_data->flavor,
    ///                         cake_data->frosting, cake_data->message,
    ///                         cancellable, &error);
    ///       if (cake)
    ///         g_task_return_pointer (task, cake, g_object_unref);
    ///       else
    ///         g_task_return_error (task, error);
    ///     }
    ///
    ///     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);
    ///       cake_data->radius = radius;
    ///       cake_data->flavor = flavor;
    ///       cake_data->frosting = frosting;
    ///       cake_data->message = g_strdup (message);
    ///       task = g_task_new (self, cancellable, callback, user_data);
    ///       g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
    ///       g_task_run_in_thread (task, bake_cake_thread);
    ///       g_object_unref (task);
    ///     }
    ///
    ///     Cake *
    ///     baker_bake_cake_finish (Baker         *self,
    ///                             GAsyncResult  *result,
    ///                             GError       **error)
    ///     {
    ///       g_return_val_if_fail (g_task_is_valid (result, self), NULL);
    ///
    ///       return g_task_propagate_pointer (G_TASK (result), error);
    ///     }
    /// ```
    ///
    /// ## Adding cancellability to uncancellable tasks
    ///
    /// Finally, [`run_in_thread()`][Self::run_in_thread()] and [`run_in_thread_sync()`][Self::run_in_thread_sync()]
    /// can be used to turn an uncancellable operation into a
    /// cancellable one. If you call [`set_return_on_cancel()`][Self::set_return_on_cancel()],
    /// passing [`true`], then if the task's [`Cancellable`][crate::Cancellable] is cancelled,
    /// it will return control back to the caller immediately, while
    /// allowing the task thread to continue running in the background
    /// (and simply discarding its result when it finally does finish).
    /// Provided that the task thread is careful about how it uses
    /// locks and other externally-visible resources, this allows you
    /// to make "GLib-friendly" asynchronous and cancellable
    /// synchronous variants of blocking APIs.
    ///
    /// Cancelling a task:
    ///
    ///
    /// **⚠️ The following code is in C ⚠️**
    ///
    /// ```C
    ///     static void
    ///     bake_cake_thread (GTask         *task,
    ///                       gpointer       source_object,
    ///                       gpointer       task_data,
    ///                       GCancellable  *cancellable)
    ///     {
    ///       Baker *self = source_object;
    ///       CakeData *cake_data = task_data;
    ///       Cake *cake;
    ///       GError *error = NULL;
    ///
    ///       cake = bake_cake (baker, cake_data->radius, cake_data->flavor,
    ///                         cake_data->frosting, cake_data->message,
    ///                         &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 GSimpleAsyncResult
    ///
    /// [`Task`][crate::Task]'s API attempts to be simpler than `GSimpleAsyncResult`'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 `g_simple_async_result_set_op_res_gpointer()` for the same
    ///  purpose with `GSimpleAsyncResult`.
    /// - In addition to the task data, [`Task`][crate::Task] also keeps track of the
    ///  [priority][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 [`Task`][crate::Task] return value by default, like
    ///  `GSimpleAsyncResult` does when
    ///  `g_simple_async_result_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. ([`Task`][crate::Task] 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 [`Task`][crate::Task] based operations are generally
    ///  much simpler than `GSimpleAsyncResult` 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 [`Task`][crate::Task], it is not necessary to juggle pointers around to
    ///  prevent it from being freed twice.
    /// - With `GSimpleAsyncResult`, it was common to call
    ///  `g_simple_async_result_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
    ///  `GSimpleAsyncResult` error-returning behavior, and
    ///  `g_async_result_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 [`Task::return_pointer()`][crate::Task::return_pointer()],
    /// [`Task::return_error()`][crate::Task::return_error()] or one of the other return functions have been called
    /// on the task.
    ///
    /// This property is guaranteed to change from [`false`] to [`true`] exactly once.
    ///
    /// The [`notify`][struct@crate::glib::Object#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]
    #[doc(alias = "GTask")]
    pub struct Task<V: ValueType + Send>(Object<ffi::GTask, ffi::GTaskClass>) @implements AsyncResult;

    match fn {
        type_ => || ffi::g_task_get_type(),
    }
}

macro_rules! task_impl {
    ($name:ident $(, @bound: $bound:tt)? $(, @safety: $safety:tt)?) => {
        impl <V: Into<glib::Value> + ValueType $(+ $bound)?> $name<V> {
            #[doc(alias = "g_task_new")]
            #[allow(unused_unsafe)]
            pub unsafe fn new<S, P, Q>(
                source_object: Option<&S>,
                cancellable: Option<&P>,
                callback: Q,
            ) -> Self
            where
                S: IsA<glib::Object> $(+ $bound)?,
                P: IsA<Cancellable>,
                Q: FnOnce($name<V>, Option<&S>) $(+ $bound)? + 'static,
            {
                let callback_data = Box_::new(callback);
                unsafe extern "C" fn trampoline<
                    S: IsA<glib::Object> $(+ $bound)?,
                    V: ValueType $(+ $bound)?,
                    Q: FnOnce($name<V>, Option<&S>) $(+ $bound)? + 'static,
                >(
                    source_object: *mut glib::gobject_ffi::GObject,
                    res: *mut ffi::GAsyncResult,
                    user_data: glib::ffi::gpointer,
                ) {
                    let callback: Box_<Q> = Box::from_raw(user_data as *mut _);
                    let task = AsyncResult::from_glib_none(res)
                        .downcast::<$name<V>>()
                        .unwrap();
                    let source_object = Option::<glib::Object>::from_glib_borrow(source_object);
                    callback(
                        task,
                        source_object.as_ref().as_ref().map(|s| s.unsafe_cast_ref()),
                    );
                }
                let callback = trampoline::<S, V, Q>;
                unsafe {
                    from_glib_full(ffi::g_task_new(
                        source_object.map(|p| p.as_ref()).to_glib_none().0,
                        cancellable.map(|p| p.as_ref()).to_glib_none().0,
                        Some(callback),
                        Box_::into_raw(callback_data) as *mut _,
                    ))
                }
            }

            #[doc(alias = "g_task_get_cancellable")]
            #[doc(alias = "get_cancellable")]
            pub fn cancellable(&self) -> Option<Cancellable> {
                unsafe { from_glib_none(ffi::g_task_get_cancellable(self.to_glib_none().0)) }
            }

            #[doc(alias = "g_task_get_check_cancellable")]
            #[doc(alias = "get_check_cancellable")]
            pub fn is_check_cancellable(&self) -> bool {
                unsafe { from_glib(ffi::g_task_get_check_cancellable(self.to_glib_none().0)) }
            }

            #[doc(alias = "g_task_set_check_cancellable")]
            pub fn set_check_cancellable(&self, check_cancellable: bool) {
                unsafe {
                    ffi::g_task_set_check_cancellable(self.to_glib_none().0, check_cancellable.into_glib());
                }
            }

            #[cfg(any(feature = "v2_60", feature = "dox"))]
            #[cfg_attr(feature = "dox", doc(cfg(feature = "v2_60")))]
            #[doc(alias = "g_task_set_name")]
            pub fn set_name(&self, name: Option<&str>) {
                unsafe {
                    ffi::g_task_set_name(self.to_glib_none().0, name.to_glib_none().0);
                }
            }

            #[doc(alias = "g_task_set_return_on_cancel")]
            pub fn set_return_on_cancel(&self, return_on_cancel: bool) -> bool {
                unsafe {
                    from_glib(ffi::g_task_set_return_on_cancel(
                        self.to_glib_none().0,
                        return_on_cancel.into_glib(),
                    ))
                }
            }

            #[doc(alias = "g_task_is_valid")]
            pub fn is_valid(
                result: &impl IsA<AsyncResult>,
                source_object: Option<&impl IsA<glib::Object>>,
            ) -> bool {
                unsafe {
                    from_glib(ffi::g_task_is_valid(
                        result.as_ref().to_glib_none().0,
                        source_object.map(|p| p.as_ref()).to_glib_none().0,
                    ))
                }
            }

            #[doc(alias = "get_priority")]
            #[doc(alias = "g_task_get_priority")]
            pub fn priority(&self) -> glib::source::Priority {
                unsafe { FromGlib::from_glib(ffi::g_task_get_priority(self.to_glib_none().0)) }
            }

            #[doc(alias = "g_task_set_priority")]
            pub fn set_priority(&self, priority: glib::source::Priority) {
                unsafe {
                    ffi::g_task_set_priority(self.to_glib_none().0, priority.into_glib());
                }
            }

            #[doc(alias = "g_task_get_completed")]
            #[doc(alias = "get_completed")]
            pub fn is_completed(&self) -> bool {
                unsafe { from_glib(ffi::g_task_get_completed(self.to_glib_none().0)) }
            }

            #[doc(alias = "g_task_get_context")]
            #[doc(alias = "get_context")]
            pub fn context(&self) -> glib::MainContext {
                unsafe { from_glib_none(ffi::g_task_get_context(self.to_glib_none().0)) }
            }

            #[cfg(any(feature = "v2_60", feature = "dox"))]
            #[cfg_attr(feature = "dox", doc(cfg(feature = "v2_60")))]
            #[doc(alias = "g_task_get_name")]
            #[doc(alias = "get_name")]
            pub fn name(&self) -> Option<glib::GString> {
                unsafe { from_glib_none(ffi::g_task_get_name(self.to_glib_none().0)) }
            }

            #[doc(alias = "g_task_get_return_on_cancel")]
            #[doc(alias = "get_return_on_cancel")]
            pub fn is_return_on_cancel(&self) -> bool {
                unsafe { from_glib(ffi::g_task_get_return_on_cancel(self.to_glib_none().0)) }
            }

            #[doc(alias = "g_task_had_error")]
            pub fn had_error(&self) -> bool {
                unsafe { from_glib(ffi::g_task_had_error(self.to_glib_none().0)) }
            }

            #[doc(alias = "completed")]
            pub fn connect_completed_notify<F>(&self, f: F) -> SignalHandlerId
            where
                F: Fn(&$name<V>) $(+ $bound)? + 'static,
            {
                unsafe extern "C" fn notify_completed_trampoline<V, F>(
                    this: *mut ffi::GTask,
                    _param_spec: glib::ffi::gpointer,
                    f: glib::ffi::gpointer,
                ) where
                    V: ValueType $(+ $bound)?,
                    F: Fn(&$name<V>) + 'static,
                {
                    let f: &F = &*(f as *const F);
                    f(&from_glib_borrow(this))
                }
                unsafe {
                    let f: Box_<F> = Box_::new(f);
                    connect_raw(
                        self.as_ptr() as *mut _,
                        b"notify::completed\0".as_ptr() as *const _,
                        Some(transmute::<_, unsafe extern "C" fn()>(
                            notify_completed_trampoline::<V, F> as *const (),
                        )),
                        Box_::into_raw(f),
                    )
                }
            }

            // the following functions are marked unsafe since they cannot be called
            // more than once, but we have no way to enforce that since the task can be cloned

            #[doc(alias = "g_task_return_error_if_cancelled")]
            #[allow(unused_unsafe)]
            pub $($safety)? fn return_error_if_cancelled(&self) -> bool {
                unsafe { from_glib(ffi::g_task_return_error_if_cancelled(self.to_glib_none().0)) }
            }

            #[doc(alias = "g_task_return_value")]
            #[doc(alias = "g_task_return_boolean")]
            #[doc(alias = "g_task_return_int")]
            #[doc(alias = "g_task_return_pointer")]
            #[doc(alias = "g_task_return_error")]
            #[allow(unused_unsafe)]
            pub $($safety)? fn return_result(self, result: Result<V, glib::Error>) {
                #[cfg(not(feature = "v2_64"))]
                unsafe extern "C" fn value_free(value: *mut libc::c_void) {
                    let _: glib::Value = from_glib_full(value as *mut glib::gobject_ffi::GValue);
                }

                match result {
                    #[cfg(feature = "v2_64")]
                    Ok(v) => unsafe {
                        ffi::g_task_return_value(
                            self.to_glib_none().0,
                            v.to_value().to_glib_none().0 as *mut _,
                        )
                    },
                    #[cfg(not(feature = "v2_64"))]
                    Ok(v) => unsafe {
                        let v: glib::Value = v.into();
                        ffi::g_task_return_pointer(
                            self.to_glib_none().0,
                            <glib::Value as glib::translate::IntoGlibPtr::<*mut glib::gobject_ffi::GValue>>::into_glib_ptr(v) as glib::ffi::gpointer,
                            Some(value_free),
                        )
                    },
                    Err(e) => unsafe {
                        ffi::g_task_return_error(self.to_glib_none().0, e.into_glib_ptr());
                    },
                }
            }

            #[doc(alias = "g_task_propagate_value")]
            #[doc(alias = "g_task_propagate_boolean")]
            #[doc(alias = "g_task_propagate_int")]
            #[doc(alias = "g_task_propagate_pointer")]
            #[allow(unused_unsafe)]
            pub $($safety)? fn propagate(self) -> Result<V, glib::Error> {
                let mut error = ptr::null_mut();

                unsafe {
                    #[cfg(feature = "v2_64")]
                    {
                        let mut value = glib::Value::uninitialized();
                        ffi::g_task_propagate_value(
                            self.to_glib_none().0,
                            value.to_glib_none_mut().0,
                            &mut error,
                        );

                        if error.is_null() {
                            Ok(V::from_value(&value))
                        } else {
                            Err(from_glib_full(error))
                        }
                    }

                    #[cfg(not(feature = "v2_64"))]
                    {
                        let value = ffi::g_task_propagate_pointer(self.to_glib_none().0, &mut error);

                        if error.is_null() {
                            let value = Option::<glib::Value>::from_glib_full(
                                value as *mut glib::gobject_ffi::GValue,
                            )
                            .expect("Task::propagate() called before Task::return_result()");
                            Ok(V::from_value(&value))
                        } else {
                            Err(from_glib_full(error))
                        }
                    }
                }
            }
        }

        impl <V: ValueType $(+ $bound)?> std::fmt::Display for $name<V> {
            fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
                f.write_str(stringify!($name))
            }
        }
    }
}

task_impl!(LocalTask);
task_impl!(Task, @bound: Send, @safety: unsafe);

impl<V: ValueType + Send> Task<V> {
    #[doc(alias = "g_task_run_in_thread")]
    pub fn run_in_thread<S, Q>(&self, task_func: Q)
    where
        S: IsA<glib::Object> + Send,
        Q: FnOnce(Self, Option<&S>, Option<&Cancellable>) + Send + 'static,
    {
        let task_func_data = Box_::new(task_func);

        // We store the func pointer into the task data.
        // We intentionally do not expose a way to set the task data in the bindings.
        // If we detect that the task data is set, there is not much we can do, so we panic.
        unsafe {
            assert!(
                ffi::g_task_get_task_data(self.to_glib_none().0).is_null(),
                "Task data was manually set or the task was run thread multiple times"
            );

            ffi::g_task_set_task_data(
                self.to_glib_none().0,
                Box_::into_raw(task_func_data) as *mut _,
                None,
            );
        }

        unsafe extern "C" fn trampoline<V, S, Q>(
            task: *mut ffi::GTask,
            source_object: *mut glib::gobject_ffi::GObject,
            user_data: glib::ffi::gpointer,
            cancellable: *mut ffi::GCancellable,
        ) where
            V: ValueType + Send,
            S: IsA<glib::Object> + Send,
            Q: FnOnce(Task<V>, Option<&S>, Option<&Cancellable>) + Send + 'static,
        {
            let task = Task::from_glib_none(task);
            let source_object = Option::<glib::Object>::from_glib_borrow(source_object);
            let cancellable = Option::<Cancellable>::from_glib_borrow(cancellable);
            let task_func: Box_<Q> = Box::from_raw(user_data as *mut _);
            task_func(
                task,
                source_object.as_ref().as_ref().map(|s| s.unsafe_cast_ref()),
                cancellable.as_ref().as_ref(),
            );
        }

        let task_func = trampoline::<V, S, Q>;
        unsafe {
            ffi::g_task_run_in_thread(self.to_glib_none().0, Some(task_func));
        }
    }
}

unsafe impl<V: ValueType + Send> Send for Task<V> {}
unsafe impl<V: ValueType + Send> Sync for Task<V> {}

// rustdoc-stripper-ignore-next
/// A handle to a task running on the I/O thread pool.
///
/// Like [`std::thread::JoinHandle`] for a blocking I/O task rather than a thread. The return value
/// from the task can be retrieved by awaiting on this handle. Dropping the handle "detaches" the
/// task, allowing it to complete but discarding the return value.
#[derive(Debug)]
pub struct JoinHandle<T> {
    rx: oneshot::Receiver<std::thread::Result<T>>,
}

impl<T> JoinHandle<T> {
    #[inline]
    fn new() -> (Self, oneshot::Sender<std::thread::Result<T>>) {
        let (tx, rx) = oneshot::channel();
        (Self { rx }, tx)
    }
}

impl<T> Future for JoinHandle<T> {
    type Output = std::thread::Result<T>;
    #[inline]
    fn poll(
        mut self: std::pin::Pin<&mut Self>,
        cx: &mut std::task::Context<'_>,
    ) -> std::task::Poll<Self::Output> {
        std::pin::Pin::new(&mut self.rx)
            .poll(cx)
            .map(|r| r.unwrap())
    }
}

impl<T> futures_core::FusedFuture for JoinHandle<T> {
    #[inline]
    fn is_terminated(&self) -> bool {
        self.rx.is_terminated()
    }
}

// rustdoc-stripper-ignore-next
/// Runs a blocking I/O task on the I/O thread pool.
///
/// Calls `func` on the internal Gio thread pool for blocking I/O operations. The thread pool is
/// shared with other Gio async I/O operations, and may rate-limit the tasks it receives. Callers
/// may want to avoid blocking indefinitely by making sure blocking calls eventually time out.
///
/// This function should not be used to spawn async tasks. Instead, use
/// [`glib::MainContext::spawn`] or [`glib::MainContext::spawn_local`] to run a future.
pub fn spawn_blocking<T, F>(func: F) -> JoinHandle<T>
where
    T: Send + 'static,
    F: FnOnce() -> T + Send + 'static,
{
    // use Cancellable::NONE as source obj to fulfill `Send` requirement
    let task = unsafe { Task::<bool>::new(Cancellable::NONE, Cancellable::NONE, |_, _| {}) };
    let (join, tx) = JoinHandle::new();
    task.run_in_thread(move |_, _: Option<&Cancellable>, _| {
        let res = panic::catch_unwind(panic::AssertUnwindSafe(func));
        let _ = tx.send(res);
    });

    join
}

#[cfg(test)]
mod test {
    use super::*;
    use crate::{prelude::*, test_util::run_async_local};

    #[test]
    fn test_int_async_result() {
        match run_async_local(|tx, l| {
            let cancellable = crate::Cancellable::new();
            let task = unsafe {
                crate::LocalTask::new(
                    None,
                    Some(&cancellable),
                    move |t: LocalTask<i32>, _b: Option<&glib::Object>| {
                        tx.send(t.propagate()).unwrap();
                        l.quit();
                    },
                )
            };
            task.return_result(Ok(100_i32));
        }) {
            Err(_) => panic!(),
            Ok(i) => assert_eq!(i, 100),
        }
    }

    #[test]
    fn test_object_async_result() {
        use glib::subclass::prelude::*;
        pub struct MySimpleObjectPrivate {
            pub size: std::cell::RefCell<Option<i64>>,
        }

        #[glib::object_subclass]
        impl ObjectSubclass for MySimpleObjectPrivate {
            const NAME: &'static str = "MySimpleObjectPrivate";
            type Type = MySimpleObject;

            fn new() -> Self {
                Self {
                    size: std::cell::RefCell::new(Some(100)),
                }
            }
        }

        impl ObjectImpl for MySimpleObjectPrivate {}

        glib::wrapper! {
            pub struct MySimpleObject(ObjectSubclass<MySimpleObjectPrivate>);
        }

        impl MySimpleObject {
            pub fn new() -> Self {
                glib::Object::new()
            }

            #[doc(alias = "get_size")]
            pub fn size(&self) -> Option<i64> {
                *self.imp().size.borrow()
            }

            pub fn set_size(&self, size: i64) {
                self.imp().size.borrow_mut().replace(size);
            }
        }

        impl Default for MySimpleObject {
            fn default() -> Self {
                Self::new()
            }
        }

        match run_async_local(|tx, l| {
            let cancellable = crate::Cancellable::new();
            let task = unsafe {
                crate::LocalTask::new(
                    None,
                    Some(&cancellable),
                    move |t: LocalTask<glib::Object>, _b: Option<&glib::Object>| {
                        tx.send(t.propagate()).unwrap();
                        l.quit();
                    },
                )
            };
            let my_object = MySimpleObject::new();
            my_object.set_size(100);
            task.return_result(Ok(my_object.upcast::<glib::Object>()));
        }) {
            Err(_) => panic!(),
            Ok(o) => {
                let o = o.downcast::<MySimpleObject>().unwrap();
                assert_eq!(o.size(), Some(100));
            }
        }
    }

    #[test]
    fn test_error() {
        match run_async_local(|tx, l| {
            let cancellable = crate::Cancellable::new();
            let task = unsafe {
                crate::LocalTask::new(
                    None,
                    Some(&cancellable),
                    move |t: LocalTask<i32>, _b: Option<&glib::Object>| {
                        tx.send(t.propagate()).unwrap();
                        l.quit();
                    },
                )
            };
            task.return_result(Err(glib::Error::new(
                crate::IOErrorEnum::WouldBlock,
                "WouldBlock",
            )));
        }) {
            Err(e) => match e.kind().unwrap() {
                crate::IOErrorEnum::WouldBlock => {}
                _ => panic!(),
            },
            Ok(_) => panic!(),
        }
    }

    #[test]
    fn test_cancelled() {
        match run_async_local(|tx, l| {
            let cancellable = crate::Cancellable::new();
            let task = unsafe {
                crate::LocalTask::new(
                    None,
                    Some(&cancellable),
                    move |t: LocalTask<i32>, _b: Option<&glib::Object>| {
                        tx.send(t.propagate()).unwrap();
                        l.quit();
                    },
                )
            };
            cancellable.cancel();
            task.return_error_if_cancelled();
        }) {
            Err(e) => match e.kind().unwrap() {
                crate::IOErrorEnum::Cancelled => {}
                _ => panic!(),
            },
            Ok(_) => panic!(),
        }
    }
}