glib/gobject/

type_plugin.rs

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

use crate::{gobject_ffi, prelude::*, translate::*, InterfaceInfo, TypeInfo, TypeValueTable};

crate::wrapper! {
    /// An interface that handles the lifecycle of dynamically loaded types.
    ///
    /// The GObject type system supports dynamic loading of types.
    /// It goes as follows:
    ///
    /// 1. The type is initially introduced (usually upon loading the module
    ///  the first time, or by your main application that knows what modules
    ///  introduces what types), like this:
    ///  **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    ///    new_type_id = g_type_register_dynamic (parent_type_id,
    ///                                           "TypeName",
    ///                                           new_type_plugin,
    ///                                           type_flags);
    ///    ```
    ///  where `new_type_plugin` is an implementation of the
    ///  `GTypePlugin` interface.
    ///
    /// 2. The type's implementation is referenced, e.g. through
    ///  [func[`Object`][crate::Object].ref] or through [func[`Object`][crate::Object]]
    ///  (this is being called by [ctor[`Object`][crate::Object].new]) or through one of the above
    ///  done on a type derived from `new_type_id`.
    ///
    /// 3. This causes the type system to load the type's implementation by calling
    ///  [method[`Object`][crate::Object].use] and [method[`Object`][crate::Object].complete_type_info]
    ///  on `new_type_plugin`.
    ///
    /// 4. At some point the type's implementation isn't required anymore, e.g. after
    ///  [method[`Object`][crate::Object].unref] or [func[`Object`][crate::Object]]
    ///  (called when the reference count of an instance drops to zero).
    ///
    /// 5. This causes the type system to throw away the information retrieved
    ///  from [method[`Object`][crate::Object].complete_type_info] and then it calls
    ///  [method[`Object`][crate::Object].unuse] on `new_type_plugin`.
    ///
    /// 6. Things may repeat from the second step.
    ///
    /// So basically, you need to implement a `GTypePlugin` type that
    /// carries a use_count, once use_count goes from zero to one, you need
    /// to load the implementation to successfully handle the upcoming
    /// [method[`Object`][crate::Object].complete_type_info] call. Later, maybe after
    /// succeeding use/unuse calls, once use_count drops to zero, you can
    /// unload the implementation again. The type system makes sure to call
    /// [method[`Object`][crate::Object].use] and [method[`Object`][crate::Object].complete_type_info]
    /// again when the type is needed again.
    ///
    /// [class[`Object`][crate::Object]] is an implementation of `GTypePlugin` that
    /// already implements most of this except for the actual module loading and
    /// unloading. It even handles multiple registered types per module.
    ///
    /// # Implements
    ///
    /// [`TypePluginExt`][trait@crate::prelude::TypePluginExt]
    #[doc(alias = "GTypePlugin")]
    pub struct TypePlugin(Interface<gobject_ffi::GTypePlugin, gobject_ffi::GTypePluginClass>);

    match fn {
        type_ => || gobject_ffi::g_type_plugin_get_type(),
    }
}

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

mod sealed {
    pub trait Sealed {}
    impl<T: super::IsA<super::TypePlugin>> Sealed for T {}
}

/// Trait containing all [`struct@TypePlugin`] methods.
///
/// # Implementors
///
/// [`TypeModule`][struct@crate::TypeModule], [`TypePlugin`][struct@crate::TypePlugin]
pub trait TypePluginExt: IsA<TypePlugin> + sealed::Sealed + 'static {
    /// Calls the `complete_interface_info` function from the
    /// `GTypePluginClass` of `self`. There should be no need to use this
    /// function outside of the GObject type system itself.
    /// ## `instance_type`
    /// the `GType` of an instantiatable type to which the interface
    ///  is added
    /// ## `interface_type`
    /// the `GType` of the interface whose info is completed
    /// ## `info`
    /// the [`InterfaceInfo`][crate::InterfaceInfo] to fill in
    #[doc(alias = "g_type_plugin_complete_interface_info")]
    fn complete_interface_info(
        &self,
        instance_type: crate::types::Type,
        interface_type: crate::types::Type,
    ) -> InterfaceInfo {
        let info = InterfaceInfo::default();
        unsafe {
            gobject_ffi::g_type_plugin_complete_interface_info(
                self.as_ref().to_glib_none().0,
                instance_type.into_glib(),
                interface_type.into_glib(),
                info.as_ptr(),
            );
        }
        info
    }

    /// Calls the `complete_type_info` function from the `GTypePluginClass` of `self`.
    /// There should be no need to use this function outside of the GObject
    /// type system itself.
    /// ## `g_type`
    /// the `GType` whose info is completed
    /// ## `info`
    /// the [`TypeInfo`][crate::TypeInfo] struct to fill in
    /// ## `value_table`
    /// the [`TypeValueTable`][crate::TypeValueTable] to fill in
    #[doc(alias = "g_type_plugin_complete_type_info")]
    fn complete_type_info(&self, g_type: crate::types::Type) -> (TypeInfo, TypeValueTable) {
        let info = TypeInfo::default();
        let value_table = TypeValueTable::default();
        unsafe {
            gobject_ffi::g_type_plugin_complete_type_info(
                self.as_ref().to_glib_none().0,
                g_type.into_glib(),
                info.as_ptr(),
                value_table.as_ptr(),
            );
        }
        (info, value_table)
    }

    /// Calls the `unuse_plugin` function from the `GTypePluginClass` of
    /// `self`. There should be no need to use this function outside of
    /// the GObject type system itself.
    #[doc(alias = "g_type_plugin_unuse")]
    fn unuse(&self) {
        unsafe {
            gobject_ffi::g_type_plugin_unuse(self.as_ref().to_glib_none().0);
        }
    }

    /// Calls the `use_plugin` function from the `GTypePluginClass` of
    /// `self`. There should be no need to use this function outside of
    /// the GObject type system itself.
    #[doc(alias = "g_type_plugin_use")]
    #[doc(alias = "use")]
    fn use_(&self) {
        unsafe {
            gobject_ffi::g_type_plugin_use(self.as_ref().to_glib_none().0);
        }
    }
}

impl<O: IsA<TypePlugin>> TypePluginExt for O {}