GTypePlugin

## GTypePlugin GTypePlugin — An interface for dynamically loadable types |

## Synopsis

    #include <glib-object.h>

    struct      GTypePlugin;
    struct      GTypePluginClass;
    void        (*GTypePluginUse)               (GTypePlugin *plugin);
    void        (*GTypePluginUnuse)             (GTypePlugin *plugin);
    void        (*GTypePluginCompleteTypeInfo)  (GTypePlugin *plugin,
                                                 GType g_type,
                                                 GTypeInfo *info,
                                                 GTypeValueTable *value_table);
    void        (*GTypePluginCompleteInterfaceInfo)
                                                (GTypePlugin *plugin,
                                                 GType instance_type,
                                                 GType interface_type,
                                                 GInterfaceInfo *info);
    void        g_type_plugin_use               (GTypePlugin *plugin);
    void        g_type_plugin_unuse             (GTypePlugin *plugin);
    void        g_type_plugin_complete_type_info
                                                (GTypePlugin *plugin,
                                                 GType g_type,
                                                 GTypeInfo *info,
                                                 GTypeValueTable *value_table);
    void        g_type_plugin_complete_interface_info
                                                (GTypePlugin *plugin,
                                                 GType instance_type,
                                                 GType interface_type,
                                                 GInterfaceInfo *info);

## Object Hierarchy

      GInterface
       +----GTypePlugin

## Known Implementations

GTypePlugin is implemented by GTypeModule.

## Description

The GObject type system supports dynamic loading of types. The GTypePlugin interface is used to handle the lifecycle of dynamically loaded 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: `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 `g_type_class_ref()` or through `g_type_create_instance()` (this is being called by `g_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 `g_type_plugin_use()` and `g_type_plugin_complete_type_info()` on `new_type_plugin`.

4. At some point the type's implementation isn't required anymore, e.g. after `g_type_class_unref()` or `g_type_free_instance()` (called when the reference count of an instance drops to zero).

5. This causes the type system to throw away the information retrieved from `g_type_plugin_complete_type_info()` and then it calls `g_type_plugin_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 `g_type_plugin_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 `g_type_plugin_use()` and `g_type_plugin_complete_type_info()` again when the type is needed again.

GTypeModule 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.

## Details

### struct GTypePlugin

    struct GTypePlugin;

The GTypePlugin typedef is used as a placeholder for objects that implement the GTypePlugin interface.

### struct GTypePluginClass

    struct GTypePluginClass {

      GTypePluginUse		   use_plugin;
      GTypePluginUnuse		   unuse_plugin;
      GTypePluginCompleteTypeInfo	   complete_type_info;
      GTypePluginCompleteInterfaceInfo complete_interface_info;
    };

The GTypePlugin interface is used by the type system in order to handle the lifecycle of dynamically loaded types.

GTypePluginUse `use_plugin` | Increases the use count of the plugin.
GTypePluginUnuse `unuse_plugin` | Decreases the use count of the plugin.
GTypePluginCompleteTypeInfo `complete_type_info` | Fills in the GTypeInfo and GTypeValueTable structs for the type. The structs are initialized with `memset(s, 0, sizeof (s))` before calling this function.
GTypePluginCompleteInterfaceInfo `complete_interface_info` | Fills in missing parts of the GInterfaceInfo for the interface. The structs is initialized with `memset(s, 0, sizeof (s))` before calling this function.

### GTypePluginUse ()

    void        (*GTypePluginUse)               (GTypePlugin *plugin);

The type of the `use_plugin` function of GTypePluginClass, which gets called to increase the use count of `plugin`.

`plugin` : | the GTypePlugin whose use count should be increased

### GTypePluginUnuse ()

    void        (*GTypePluginUnuse)             (GTypePlugin *plugin);

The type of the `unuse_plugin` function of GTypePluginClass.

`plugin` : | the GTypePlugin whose use count should be decreased

### GTypePluginCompleteTypeInfo ()

    void        (*GTypePluginCompleteTypeInfo)  (GTypePlugin *plugin,
                                                 GType g_type,
                                                 GTypeInfo *info,
                                                 GTypeValueTable *value_table);

The type of the `complete_type_info` function of GTypePluginClass.

`plugin` : | the GTypePlugin
`g_type` : | the GType whose info is completed
`info` : | the GTypeInfo struct to fill in
`value_table` : | the GTypeValueTable to fill in

### GTypePluginCompleteInterfaceInfo ()

    void        (*GTypePluginCompleteInterfaceInfo)
                                                (GTypePlugin *plugin,
                                                 GType instance_type,
                                                 GType interface_type,
                                                 GInterfaceInfo *info);

The type of the `complete_interface_info` function of GTypePluginClass.

`plugin` : | the GTypePlugin
`instance_type` : | the GType of an instantiable type to which the interface is added
`interface_type` : | the GType of the interface whose info is completed
`info` : | the GInterfaceInfo to fill in

### g_type_plugin_use ()

    void        g_type_plugin_use               (GTypePlugin *plugin);

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

`plugin` : | a GTypePlugin

### g_type_plugin_unuse ()

    void        g_type_plugin_unuse             (GTypePlugin *plugin);

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

`plugin` : | a GTypePlugin

### g_type_plugin_complete_type_info ()

    void        g_type_plugin_complete_type_info
                                                (GTypePlugin *plugin,
                                                 GType g_type,
                                                 GTypeInfo *info,
                                                 GTypeValueTable *value_table);

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

`plugin` : | a GTypePlugin
`g_type` : | the GType whose info is completed
`info` : | the GTypeInfo struct to fill in
`value_table` : | the GTypeValueTable to fill in

### g_type_plugin_complete_interface_info ()

    void        g_type_plugin_complete_interface_info
                                                (GTypePlugin *plugin,
                                                 GType instance_type,
                                                 GType interface_type,
                                                 GInterfaceInfo *info);

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

`plugin` : | the GTypePlugin
`instance_type` : | the GType of an instantiable type to which the interface is added
`interface_type` : | the GType of the interface whose info is completed
`info` : | the GInterfaceInfo to fill in

## See Also

GTypeModule and `g_type_register_dynamic()`.