gi-gobject-2.0.31: GObject bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.GObject.Interfaces.TypePlugin

Contents

- Exported types
- Methods
  - completeInterfaceInfo
  - completeTypeInfo
  - unuse
  - use

Description

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:

### c code

    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.

1. The type's implementation is referenced, e.g. through `typeClassRef` or through `GObject.type_create_instance` (this is being called by `Object`.`new`()) or through one of the above done on a type derived from `new_type_id`.
2. This causes the type system to load the type's implementation by calling `typePluginUse` and `typePluginCompleteTypeInfo` on `new_type_plugin`.
3. At some point the type's implementation isn't required anymore, e.g. after `typeClassUnref` or `typeFreeInstance` (called when the reference count of an instance drops to zero).
4. This causes the type system to throw away the information retrieved from `typePluginCompleteTypeInfo` and then it calls `typePluginUnuse` on `new_type_plugin`.
5. 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 `typePluginCompleteTypeInfo` 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 `typePluginUse` and `typePluginCompleteTypeInfo` again when the type is needed again.

`TypeModule` 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.

Synopsis

- newtype TypePlugin = TypePlugin (ManagedPtr TypePlugin)
- class (ManagedPtrNewtype o, IsDescendantOf TypePlugin o) => IsTypePlugin o
- typePluginCompleteInterfaceInfo :: (HasCallStack, MonadIO m, IsTypePlugin a) => a -> GType -> GType -> InterfaceInfo -> m ()
- typePluginCompleteTypeInfo :: (HasCallStack, MonadIO m, IsTypePlugin a) => a -> GType -> TypeInfo -> TypeValueTable -> m ()
- typePluginUnuse :: (HasCallStack, MonadIO m, IsTypePlugin a) => a -> m ()
- typePluginUse :: (HasCallStack, MonadIO m, IsTypePlugin a) => a -> m ()

# Exported types

newtype TypePlugin Source #

Memory-managed wrapper type.

Constructors

TypePlugin (ManagedPtr TypePlugin) |

#### Instances

Instances details

Eq TypePlugin Source # |
Instance details Defined in GI.GObject.Interfaces.TypePlugin Methods (==) :: TypePlugin -> TypePlugin -> Bool Source # (/=) :: TypePlugin -> TypePlugin -> Bool Source #
BoxedPtr TypePlugin Source # |
Instance details Defined in GI.GObject.Interfaces.TypePlugin Methods boxedPtrCopy :: TypePlugin -> IO TypePlugin Source # boxedPtrFree :: TypePlugin -> IO () Source #
ManagedPtrNewtype TypePlugin Source # |
Instance details Defined in GI.GObject.Interfaces.TypePlugin Methods toManagedPtr :: TypePlugin -> ManagedPtr TypePlugin Source #

class (ManagedPtrNewtype o, IsDescendantOf TypePlugin o) => IsTypePlugin o Source #

Type class for types which implement `TypePlugin`.

#### Instances

Instances details

(ManagedPtrNewtype o, IsDescendantOf TypePlugin o) => IsTypePlugin o Source # |
Instance details Defined in GI.GObject.Interfaces.TypePlugin

# Methods

### Click to display all available methods, including inherited ones

Expand

#### Methods

completeInterfaceInfo, completeTypeInfo, unuse, use.

#### Getters

None.

#### Setters

None.

## completeInterfaceInfo

typePluginCompleteInterfaceInfo Source #

Arguments

:: (HasCallStack, MonadIO m, IsTypePlugin a) |
=> a | `plugin`: the `TypePlugin`
-> GType | `instanceType`: the `GType` of an instantiatable type to which the interface is added
-> GType | `interfaceType`: the `GType` of the interface whose info is completed
-> InterfaceInfo | `info`: the `InterfaceInfo` to fill in
-> m () |

Calls the `completeInterfaceInfo` function from the `GTypePluginClass` of `plugin`. There should be no need to use this function outside of the GObject type system itself.

## completeTypeInfo

typePluginCompleteTypeInfo Source #

Arguments

:: (HasCallStack, MonadIO m, IsTypePlugin a) |
=> a | `plugin`: a `TypePlugin`
-> GType | `gType`: the `GType` whose info is completed
-> TypeInfo | `info`: the `TypeInfo` struct to fill in
-> TypeValueTable | `valueTable`: the `TypeValueTable` to fill in
-> m () |

Calls the `completeTypeInfo` function from the `GTypePluginClass` of `plugin`. There should be no need to use this function outside of the GObject type system itself.

## unuse

typePluginUnuse Source #

Arguments

:: (HasCallStack, MonadIO m, IsTypePlugin a) |
=> a | `plugin`: a `TypePlugin`
-> m () |

Calls the `unusePlugin` function from the `GTypePluginClass` of `plugin`. There should be no need to use this function outside of the GObject type system itself.

## use

typePluginUse Source #

Arguments

:: (HasCallStack, MonadIO m, IsTypePlugin a) |
=> a | `plugin`: a `TypePlugin`
-> m () |

Calls the `usePlugin` function from the `GTypePluginClass` of `plugin`. There should be no need to use this function outside of the GObject type system itself.