gio/auto/

async_initable.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

use crate::{ffi, AsyncResult, Cancellable};
use glib::{prelude::*, translate::*};
use std::{boxed::Box as Box_, pin::Pin};

glib::wrapper! {
    /// `GAsyncInitable` is an interface for asynchronously initializable objects.
    ///
    /// This is the asynchronous version of [`Initable`][crate::Initable]; it behaves the same
    /// in all ways except that initialization is asynchronous. For more details
    /// see the descriptions on `GInitable`.
    ///
    /// A class may implement both the `GInitable` and `GAsyncInitable` interfaces.
    ///
    /// Users of objects implementing this are not intended to use the interface
    /// method directly; instead it will be used automatically in various ways.
    /// For C applications you generally just call [`new_async()`][Self::new_async()]
    /// directly, or indirectly via a foo_thing_new_async() wrapper. This will call
    /// [`AsyncInitableExt::init_async()`][crate::prelude::AsyncInitableExt::init_async()] under the covers, calling back with `NULL`
    /// and a set `GError` on failure.
    ///
    /// A typical implementation might look something like this:
    ///
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    /// enum {
    ///    NOT_INITIALIZED,
    ///    INITIALIZING,
    ///    INITIALIZED
    /// };
    ///
    /// static void
    /// _foo_ready_cb (Foo *self)
    /// {
    ///   GList *l;
    ///
    ///   self->priv->state = INITIALIZED;
    ///
    ///   for (l = self->priv->init_results; l != NULL; l = l->next)
    ///     {
    ///       GTask *task = l->data;
    ///
    ///       if (self->priv->success)
    ///         g_task_return_boolean (task, TRUE);
    ///       else
    ///         g_task_return_new_error (task, ...);
    ///       g_object_unref (task);
    ///     }
    ///
    ///   g_list_free (self->priv->init_results);
    ///   self->priv->init_results = NULL;
    /// }
    ///
    /// static void
    /// foo_init_async (GAsyncInitable       *initable,
    ///                 int                   io_priority,
    ///                 GCancellable         *cancellable,
    ///                 GAsyncReadyCallback   callback,
    ///                 gpointer              user_data)
    /// {
    ///   Foo *self = FOO (initable);
    ///   GTask *task;
    ///
    ///   task = g_task_new (initable, cancellable, callback, user_data);
    ///   g_task_set_name (task, G_STRFUNC);
    ///
    ///   switch (self->priv->state)
    ///     {
    ///       case NOT_INITIALIZED:
    ///         _foo_get_ready (self);
    ///         self->priv->init_results = g_list_append (self->priv->init_results,
    ///                                                   task);
    ///         self->priv->state = INITIALIZING;
    ///         break;
    ///       case INITIALIZING:
    ///         self->priv->init_results = g_list_append (self->priv->init_results,
    ///                                                   task);
    ///         break;
    ///       case INITIALIZED:
    ///         if (!self->priv->success)
    ///           g_task_return_new_error (task, ...);
    ///         else
    ///           g_task_return_boolean (task, TRUE);
    ///         g_object_unref (task);
    ///         break;
    ///     }
    /// }
    ///
    /// static gboolean
    /// foo_init_finish (GAsyncInitable       *initable,
    ///                  GAsyncResult         *result,
    ///                  GError              **error)
    /// {
    ///   g_return_val_if_fail (g_task_is_valid (result, initable), FALSE);
    ///
    ///   return g_task_propagate_boolean (G_TASK (result), error);
    /// }
    ///
    /// static void
    /// foo_async_initable_iface_init (gpointer g_iface,
    ///                                gpointer data)
    /// {
    ///   GAsyncInitableIface *iface = g_iface;
    ///
    ///   iface->init_async = foo_init_async;
    ///   iface->init_finish = foo_init_finish;
    /// }
    /// ```
    ///
    /// # Implements
    ///
    /// [`AsyncInitableExt`][trait@crate::prelude::AsyncInitableExt]
    #[doc(alias = "GAsyncInitable")]
    pub struct AsyncInitable(Interface<ffi::GAsyncInitable, ffi::GAsyncInitableIface>);

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

impl AsyncInitable {
    pub const NONE: Option<&'static AsyncInitable> = None;
}

/// Trait containing all [`struct@AsyncInitable`] methods.
///
/// # Implementors
///
/// [`AsyncInitable`][struct@crate::AsyncInitable], [`DBusConnection`][struct@crate::DBusConnection], [`DBusProxy`][struct@crate::DBusProxy]
pub trait AsyncInitableExt: IsA<AsyncInitable> + 'static {
    /// Starts asynchronous initialization of the object implementing the
    /// interface. This must be done before any real use of the object after
    /// initial construction. If the object also implements #GInitable you can
    /// optionally call g_initable_init() instead.
    ///
    /// This method is intended for language bindings. If writing in C,
    /// g_async_initable_new_async() should typically be used instead.
    ///
    /// When the initialization is finished, @callback will be called. You can
    /// then call g_async_initable_init_finish() to get the result of the
    /// initialization.
    ///
    /// Implementations may also support cancellation. If @cancellable is not
    /// [`None`], then initialization can be cancelled by triggering the cancellable
    /// object from another thread. If the operation was cancelled, the error
    /// [`IOErrorEnum::Cancelled`][crate::IOErrorEnum::Cancelled] will be returned. If @cancellable is not [`None`], and
    /// the object doesn't support cancellable initialization, the error
    /// [`IOErrorEnum::NotSupported`][crate::IOErrorEnum::NotSupported] will be returned.
    ///
    /// As with #GInitable, if the object is not initialized, or initialization
    /// returns with an error, then all operations on the object except
    /// g_object_ref() and g_object_unref() are considered to be invalid, and
    /// have undefined behaviour. They will often fail with g_critical() or
    /// g_warning(), but this must not be relied on.
    ///
    /// Callers should not assume that a class which implements #GAsyncInitable can
    /// be initialized multiple times; for more information, see g_initable_init().
    /// If a class explicitly supports being initialized multiple times,
    /// implementation requires yielding all subsequent calls to init_async() on the
    /// results of the first call.
    ///
    /// For classes that also support the #GInitable interface, the default
    /// implementation of this method will run the g_initable_init() function
    /// in a thread, so if you want to support asynchronous initialization via
    /// threads, just implement the #GAsyncInitable interface without overriding
    /// any interface methods.
    /// ## `io_priority`
    /// the [I/O priority](iface.AsyncResult.html#io-priority) of the operation
    /// ## `cancellable`
    /// optional #GCancellable object, [`None`] to ignore.
    /// ## `callback`
    /// a #GAsyncReadyCallback to call when the request is satisfied
    #[doc(alias = "g_async_initable_init_async")]
    unsafe fn init_async<P: FnOnce(Result<(), glib::Error>) + 'static>(
        &self,
        io_priority: glib::Priority,
        cancellable: Option<&impl IsA<Cancellable>>,
        callback: P,
    ) {
        let main_context = glib::MainContext::ref_thread_default();
        let is_main_context_owner = main_context.is_owner();
        let has_acquired_main_context = (!is_main_context_owner)
            .then(|| main_context.acquire().ok())
            .flatten();
        assert!(
            is_main_context_owner || has_acquired_main_context.is_some(),
            "Async operations only allowed if the thread is owning the MainContext"
        );

        let user_data: Box_<glib::thread_guard::ThreadGuard<P>> =
            Box_::new(glib::thread_guard::ThreadGuard::new(callback));
        unsafe extern "C" fn init_async_trampoline<P: FnOnce(Result<(), glib::Error>) + 'static>(
            _source_object: *mut glib::gobject_ffi::GObject,
            res: *mut crate::ffi::GAsyncResult,
            user_data: glib::ffi::gpointer,
        ) {
            let mut error = std::ptr::null_mut();
            let _ = ffi::g_async_initable_init_finish(_source_object as *mut _, res, &mut error);
            let result = if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            };
            let callback: Box_<glib::thread_guard::ThreadGuard<P>> =
                Box_::from_raw(user_data as *mut _);
            let callback: P = callback.into_inner();
            callback(result);
        }
        let callback = init_async_trampoline::<P>;
        ffi::g_async_initable_init_async(
            self.as_ref().to_glib_none().0,
            io_priority.into_glib(),
            cancellable.map(|p| p.as_ref()).to_glib_none().0,
            Some(callback),
            Box_::into_raw(user_data) as *mut _,
        );
    }

    unsafe fn init_future(
        &self,
        io_priority: glib::Priority,
    ) -> Pin<Box_<dyn std::future::Future<Output = Result<(), glib::Error>> + 'static>> {
        Box_::pin(crate::GioFuture::new(
            self,
            move |obj, cancellable, send| {
                obj.init_async(io_priority, Some(cancellable), move |res| {
                    send.resolve(res);
                });
            },
        ))
    }
}

impl<O: IsA<AsyncInitable>> AsyncInitableExt for O {}