| <!-- ##### SECTION Title ##### --> |
| GTypePlugin |
| |
| <!-- ##### SECTION Short_Description ##### --> |
| An interface for dynamically loadable types |
| |
| <!-- ##### SECTION Long_Description ##### --> |
| <para> |
| 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: |
| </para> |
| <para> |
| <orderedlist> |
| <listitem><para> |
| 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: |
| <literal>new_type_id = g_type_register_dynamic (parent_type_id, |
| "TypeName", |
| new_type_plugin, |
| type_flags); |
| </literal> |
| where <literal>new_type_plugin</literal> is an implementation of the |
| #GTypePlugin interface. |
| </para></listitem> |
| <listitem><para> |
| 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 <literal>new_type_id</literal>. |
| </para></listitem> |
| <listitem><para> |
| 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 |
| <literal>new_type_plugin</literal>. |
| </para></listitem> |
| <listitem><para> |
| 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). |
| </para></listitem> |
| <listitem><para> |
| 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 <literal>new_type_plugin</literal>. |
| </para></listitem> |
| <listitem><para> |
| Things may repeat from the second step. |
| </para></listitem> |
| </orderedlist> |
| </para> |
| <para> |
| 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. |
| </para> |
| <para> |
| #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. |
| </para> |
| |
| <!-- ##### SECTION See_Also ##### --> |
| <para> |
| #GTypeModule and g_type_register_dynamic(). |
| </para> |
| |
| <!-- ##### SECTION Stability_Level ##### --> |
| |
| |
| <!-- ##### STRUCT GTypePlugin ##### --> |
| <para> |
| The <structname>GTypePlugin</structname> typedef is used as a placeholder |
| for objects that implement the <structname>GTypePlugin</structname> |
| interface. |
| </para> |
| |
| |
| <!-- ##### STRUCT GTypePluginClass ##### --> |
| <para> |
| The #GTypePlugin interface is used by the type system in order to handle |
| the lifecycle of dynamically loaded types. |
| </para> |
| |
| @use_plugin: Increases the use count of the plugin. |
| @unuse_plugin: Decreases the use count of the plugin. |
| @complete_type_info: Fills in the #GTypeInfo and |
| #GTypeValueTable structs for the type. The structs are initialized |
| with <literal>memset(s, 0, sizeof (s))</literal> before calling |
| this function. |
| @complete_interface_info: Fills in missing parts of the #GInterfaceInfo |
| for the interface. The structs is initialized with |
| <literal>memset(s, 0, sizeof (s))</literal> before calling |
| this function. |
| |
| <!-- ##### USER_FUNCTION GTypePluginUse ##### --> |
| <para> |
| The type of the @use_plugin function of #GTypePluginClass, which gets called |
| to increase the use count of @plugin. |
| </para> |
| |
| @plugin: the #GTypePlugin whose use count should be increased |
| |
| |
| <!-- ##### USER_FUNCTION GTypePluginUnuse ##### --> |
| <para> |
| The type of the @unuse_plugin function of #GTypePluginClass. |
| </para> |
| |
| @plugin: the #GTypePlugin whose use count should be decreased |
| |
| |
| <!-- ##### USER_FUNCTION GTypePluginCompleteTypeInfo ##### --> |
| <para> |
| The type of the @complete_type_info function of #GTypePluginClass. |
| </para> |
| |
| @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 |
| |
| |
| <!-- ##### USER_FUNCTION GTypePluginCompleteInterfaceInfo ##### --> |
| <para> |
| The type of the @complete_interface_info function of #GTypePluginClass. |
| </para> |
| |
| @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 |
| |
| |
| <!-- ##### FUNCTION g_type_plugin_use ##### --> |
| <para> |
| 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. |
| </para> |
| |
| @plugin: a #GTypePlugin |
| |
| |
| <!-- ##### FUNCTION g_type_plugin_unuse ##### --> |
| <para> |
| 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. |
| </para> |
| |
| @plugin: a #GTypePlugin |
| |
| |
| <!-- ##### FUNCTION g_type_plugin_complete_type_info ##### --> |
| <para> |
| 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. |
| </para> |
| |
| @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 |
| |
| |
| <!-- ##### FUNCTION g_type_plugin_complete_interface_info ##### --> |
| <para> |
| 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. |
| </para> |
| |
| @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 |
| |
| |