<refentry id="GTypePlugin">
<refmeta>
<refentrytitle role="top_of_page" id="GTypePlugin.top_of_page">GTypePlugin</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GOBJECT Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>GTypePlugin</refname>
<refpurpose>An interface for dynamically loadable types</refpurpose>
</refnamediv>

<refsynopsisdiv id="GTypePlugin.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;glib-object.h&gt;

                    <link linkend="GTypePlugin-struct">GTypePlugin</link>;
                    <link linkend="GTypePluginClass">GTypePluginClass</link>;
<link linkend="void">void</link>                (<link linkend="GTypePluginUse">*GTypePluginUse</link>)                   (<link linkend="GTypePlugin">GTypePlugin</link> *plugin);
<link linkend="void">void</link>                (<link linkend="GTypePluginUnuse">*GTypePluginUnuse</link>)                 (<link linkend="GTypePlugin">GTypePlugin</link> *plugin);
<link linkend="void">void</link>                (<link linkend="GTypePluginCompleteTypeInfo">*GTypePluginCompleteTypeInfo</link>)      (<link linkend="GTypePlugin">GTypePlugin</link> *plugin,
                                                         <link linkend="GType">GType</link> g_type,
                                                         <link linkend="GTypeInfo">GTypeInfo</link> *info,
                                                         <link linkend="GTypeValueTable">GTypeValueTable</link> *value_table);
<link linkend="void">void</link>                (<link linkend="GTypePluginCompleteInterfaceInfo">*GTypePluginCompleteInterfaceInfo</link>) (<link linkend="GTypePlugin">GTypePlugin</link> *plugin,
                                                         <link linkend="GType">GType</link> instance_type,
                                                         <link linkend="GType">GType</link> interface_type,
                                                         <link linkend="GInterfaceInfo">GInterfaceInfo</link> *info);
<link linkend="void">void</link>                <link linkend="g-type-plugin-use">g_type_plugin_use</link>                   (<link linkend="GTypePlugin">GTypePlugin</link> *plugin);
<link linkend="void">void</link>                <link linkend="g-type-plugin-unuse">g_type_plugin_unuse</link>                 (<link linkend="GTypePlugin">GTypePlugin</link> *plugin);
<link linkend="void">void</link>                <link linkend="g-type-plugin-complete-type-info">g_type_plugin_complete_type_info</link>    (<link linkend="GTypePlugin">GTypePlugin</link> *plugin,
                                                         <link linkend="GType">GType</link> g_type,
                                                         <link linkend="GTypeInfo">GTypeInfo</link> *info,
                                                         <link linkend="GTypeValueTable">GTypeValueTable</link> *value_table);
<link linkend="void">void</link>                <link linkend="g-type-plugin-complete-interface-info">g_type_plugin_complete_interface_info</link>
                                                        (<link linkend="GTypePlugin">GTypePlugin</link> *plugin,
                                                         <link linkend="GType">GType</link> instance_type,
                                                         <link linkend="GType">GType</link> interface_type,
                                                         <link linkend="GInterfaceInfo">GInterfaceInfo</link> *info);
</synopsis>
</refsynopsisdiv>

<refsect1 id="GTypePlugin.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<synopsis>
  <link linkend="GInterface">GInterface</link>
   +----GTypePlugin
</synopsis>
</refsect1>




<refsect1 id="GTypePlugin.implementations" role="implementations">
<title role="implementations.title">Known Implementations</title>
<para>
GTypePlugin is implemented by
 <link linkend="GTypeModule">GTypeModule</link>.</para>
</refsect1>




<refsect1 id="GTypePlugin.description" role="desc">
<title role="desc.title">Description</title>
<para>
The GObject type system supports dynamic loading of types. The
<link linkend="GTypePlugin"><type>GTypePlugin</type></link> 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:
  <informalexample><programlisting>
  new_type_id = g_type_register_dynamic (parent_type_id,
                                                "TypeName",
                                                new_type_plugin,
                                                type_flags);
  </programlisting></informalexample>
  where <literal>new_type_plugin</literal> is an implementation of the
  <link linkend="GTypePlugin"><type>GTypePlugin</type></link> interface.
</para></listitem>
<listitem><para>
   The type's implementation is referenced, e.g. through
   <link linkend="g-type-class-ref"><function>g_type_class_ref()</function></link> or through <link linkend="g-type-create-instance"><function>g_type_create_instance()</function></link> (this is
   being called by <link linkend="g-object-new"><function>g_object_new()</function></link>) 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
   <link linkend="g-type-plugin-use"><function>g_type_plugin_use()</function></link> and <link linkend="g-type-plugin-complete-type-info"><function>g_type_plugin_complete_type_info()</function></link> on
   <literal>new_type_plugin</literal>.
</para></listitem>
<listitem><para>
   At some point the type's implementation isn't required anymore, e.g. after
   <link linkend="g-type-class-unref"><function>g_type_class_unref()</function></link> or <link linkend="g-type-free-instance"><function>g_type_free_instance()</function></link> (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
   <link linkend="g-type-plugin-complete-type-info"><function>g_type_plugin_complete_type_info()</function></link> and then it calls
   <link linkend="g-type-plugin-unuse"><function>g_type_plugin_unuse()</function></link> 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 <link linkend="GTypePlugin"><type>GTypePlugin</type></link> 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
<link linkend="g-type-plugin-complete-type-info"><function>g_type_plugin_complete_type_info()</function></link> 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
<link linkend="g-type-plugin-use"><function>g_type_plugin_use()</function></link> and <link linkend="g-type-plugin-complete-type-info"><function>g_type_plugin_complete_type_info()</function></link> again
when the type is needed again.
</para>
<para>
<link linkend="GTypeModule"><type>GTypeModule</type></link> is an implementation of <link linkend="GTypePlugin"><type>GTypePlugin</type></link> that already
implements most of this except for the actual module loading and
unloading. It even handles multiple registered types per module.</para>
<para>
</para>
</refsect1>

<refsect1 id="GTypePlugin.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="GTypePlugin-struct" role="struct">
<title>GTypePlugin</title>
<indexterm zone="GTypePlugin-struct"><primary sortas="TypePlugin">GTypePlugin</primary></indexterm><programlisting>typedef struct _GTypePlugin GTypePlugin;</programlisting>
<para>
The <structname>GTypePlugin</structname> typedef is used as a placeholder 
for objects that implement the <structname>GTypePlugin</structname> 
interface.</para>
<para>
</para></refsect2>
<refsect2 id="GTypePluginClass" role="struct">
<title>GTypePluginClass</title>
<indexterm zone="GTypePluginClass"><primary sortas="TypePluginClass">GTypePluginClass</primary></indexterm><programlisting>typedef struct {
  GTypePluginUse		   use_plugin;
  GTypePluginUnuse		   unuse_plugin;
  GTypePluginCompleteTypeInfo	   complete_type_info;
  GTypePluginCompleteInterfaceInfo complete_interface_info;
} GTypePluginClass;
</programlisting>
<para>
The <link linkend="GTypePlugin"><type>GTypePlugin</type></link> interface is used by the type system in order to handle
the lifecycle of dynamically loaded types.</para>
<para>
</para><variablelist role="struct">
<varlistentry>
<term><link linkend="GTypePluginUse">GTypePluginUse</link>&#160;<structfield>use_plugin</structfield>;</term>
<listitem><simpara> Increases the use count of the plugin.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="GTypePluginUnuse">GTypePluginUnuse</link>&#160;<structfield>unuse_plugin</structfield>;</term>
<listitem><simpara> Decreases the use count of the plugin.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="GTypePluginCompleteTypeInfo">GTypePluginCompleteTypeInfo</link>&#160;<structfield>complete_type_info</structfield>;</term>
<listitem><simpara> Fills in the <link linkend="GTypeInfo"><type>GTypeInfo</type></link> and 
 <link linkend="GTypeValueTable"><type>GTypeValueTable</type></link> structs for the type. The structs are initialized
 with <literal>memset(s, 0, sizeof (s))</literal> before calling 
 this function.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="GTypePluginCompleteInterfaceInfo">GTypePluginCompleteInterfaceInfo</link>&#160;<structfield>complete_interface_info</structfield>;</term>
<listitem><simpara> Fills in missing parts of the <link linkend="GInterfaceInfo"><type>GInterfaceInfo</type></link> 
 for the interface. The structs is initialized with 
 <literal>memset(s, 0, sizeof (s))</literal> before calling
 this function.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="GTypePluginUse" role="function">
<title>GTypePluginUse ()</title>
<indexterm zone="GTypePluginUse"><primary sortas="TypePluginUse">GTypePluginUse</primary></indexterm><programlisting><link linkend="void">void</link>                (*GTypePluginUse)                   (<link linkend="GTypePlugin">GTypePlugin</link> *plugin);</programlisting>
<para>
The type of the <parameter>use_plugin</parameter> function of <link linkend="GTypePluginClass"><type>GTypePluginClass</type></link>, which gets called
to increase the use count of <parameter>plugin</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>plugin</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GTypePlugin"><type>GTypePlugin</type></link> whose use count should be increased
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GTypePluginUnuse" role="function">
<title>GTypePluginUnuse ()</title>
<indexterm zone="GTypePluginUnuse"><primary sortas="TypePluginUnuse">GTypePluginUnuse</primary></indexterm><programlisting><link linkend="void">void</link>                (*GTypePluginUnuse)                 (<link linkend="GTypePlugin">GTypePlugin</link> *plugin);</programlisting>
<para>
The type of the <parameter>unuse_plugin</parameter> function of <link linkend="GTypePluginClass"><type>GTypePluginClass</type></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>plugin</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GTypePlugin"><type>GTypePlugin</type></link> whose use count should be decreased
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GTypePluginCompleteTypeInfo" role="function">
<title>GTypePluginCompleteTypeInfo ()</title>
<indexterm zone="GTypePluginCompleteTypeInfo"><primary sortas="TypePluginCompleteTypeInfo">GTypePluginCompleteTypeInfo</primary></indexterm><programlisting><link linkend="void">void</link>                (*GTypePluginCompleteTypeInfo)      (<link linkend="GTypePlugin">GTypePlugin</link> *plugin,
                                                         <link linkend="GType">GType</link> g_type,
                                                         <link linkend="GTypeInfo">GTypeInfo</link> *info,
                                                         <link linkend="GTypeValueTable">GTypeValueTable</link> *value_table);</programlisting>
<para>
The type of the <parameter>complete_type_info</parameter> function of <link linkend="GTypePluginClass"><type>GTypePluginClass</type></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>plugin</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GTypePlugin"><type>GTypePlugin</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>g_type</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GType"><type>GType</type></link> whose info is completed
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>info</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GTypeInfo"><type>GTypeInfo</type></link> struct to fill in
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>value_table</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GTypeValueTable"><type>GTypeValueTable</type></link> to fill in
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GTypePluginCompleteInterfaceInfo" role="function">
<title>GTypePluginCompleteInterfaceInfo ()</title>
<indexterm zone="GTypePluginCompleteInterfaceInfo"><primary sortas="TypePluginCompleteInterfaceInfo">GTypePluginCompleteInterfaceInfo</primary></indexterm><programlisting><link linkend="void">void</link>                (*GTypePluginCompleteInterfaceInfo) (<link linkend="GTypePlugin">GTypePlugin</link> *plugin,
                                                         <link linkend="GType">GType</link> instance_type,
                                                         <link linkend="GType">GType</link> interface_type,
                                                         <link linkend="GInterfaceInfo">GInterfaceInfo</link> *info);</programlisting>
<para>
The type of the <parameter>complete_interface_info</parameter> function of <link linkend="GTypePluginClass"><type>GTypePluginClass</type></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>plugin</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GTypePlugin"><type>GTypePlugin</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>instance_type</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GType"><type>GType</type></link> of an instantiable type to which the interface
 is added
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>interface_type</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GType"><type>GType</type></link> of the interface whose info is completed
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>info</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GInterfaceInfo"><type>GInterfaceInfo</type></link> to fill in
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-type-plugin-use" role="function">
<title>g_type_plugin_use ()</title>
<indexterm zone="g-type-plugin-use"><primary sortas="type_plugin_use">g_type_plugin_use</primary></indexterm><programlisting><link linkend="void">void</link>                g_type_plugin_use                   (<link linkend="GTypePlugin">GTypePlugin</link> *plugin);</programlisting>
<para>
Calls the <parameter>use_plugin</parameter> function from the <link linkend="GTypePluginClass"><type>GTypePluginClass</type></link> of
<parameter>plugin</parameter>.  There should be no need to use this function outside of
the GObject type system itself.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>plugin</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GTypePlugin"><type>GTypePlugin</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-type-plugin-unuse" role="function">
<title>g_type_plugin_unuse ()</title>
<indexterm zone="g-type-plugin-unuse"><primary sortas="type_plugin_unuse">g_type_plugin_unuse</primary></indexterm><programlisting><link linkend="void">void</link>                g_type_plugin_unuse                 (<link linkend="GTypePlugin">GTypePlugin</link> *plugin);</programlisting>
<para>
Calls the <parameter>unuse_plugin</parameter> function from the <link linkend="GTypePluginClass"><type>GTypePluginClass</type></link> of
<parameter>plugin</parameter>.  There should be no need to use this function outside of
the GObject type system itself.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>plugin</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GTypePlugin"><type>GTypePlugin</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-type-plugin-complete-type-info" role="function">
<title>g_type_plugin_complete_type_info ()</title>
<indexterm zone="g-type-plugin-complete-type-info"><primary sortas="type_plugin_complete_type_info">g_type_plugin_complete_type_info</primary></indexterm><programlisting><link linkend="void">void</link>                g_type_plugin_complete_type_info    (<link linkend="GTypePlugin">GTypePlugin</link> *plugin,
                                                         <link linkend="GType">GType</link> g_type,
                                                         <link linkend="GTypeInfo">GTypeInfo</link> *info,
                                                         <link linkend="GTypeValueTable">GTypeValueTable</link> *value_table);</programlisting>
<para>
Calls the <parameter>complete_type_info</parameter> function from the <link linkend="GTypePluginClass"><type>GTypePluginClass</type></link> of <parameter>plugin</parameter>.
There should be no need to use this function outside of the GObject 
type system itself.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>plugin</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GTypePlugin"><type>GTypePlugin</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>g_type</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GType"><type>GType</type></link> whose info is completed
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>info</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GTypeInfo"><type>GTypeInfo</type></link> struct to fill in
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>value_table</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GTypeValueTable"><type>GTypeValueTable</type></link> to fill in
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-type-plugin-complete-interface-info" role="function">
<title>g_type_plugin_complete_interface_info ()</title>
<indexterm zone="g-type-plugin-complete-interface-info"><primary sortas="type_plugin_complete_interface_info">g_type_plugin_complete_interface_info</primary></indexterm><programlisting><link linkend="void">void</link>                g_type_plugin_complete_interface_info
                                                        (<link linkend="GTypePlugin">GTypePlugin</link> *plugin,
                                                         <link linkend="GType">GType</link> instance_type,
                                                         <link linkend="GType">GType</link> interface_type,
                                                         <link linkend="GInterfaceInfo">GInterfaceInfo</link> *info);</programlisting>
<para>
Calls the <parameter>complete_interface_info</parameter> function from the
<link linkend="GTypePluginClass"><type>GTypePluginClass</type></link> of <parameter>plugin</parameter>. There should be no need to use this
function outside of the GObject type system itself.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>plugin</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GTypePlugin"><type>GTypePlugin</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>instance_type</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GType"><type>GType</type></link> of an instantiable type to which the interface
 is added
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>interface_type</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GType"><type>GType</type></link> of the interface whose info is completed
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>info</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GInterfaceInfo"><type>GInterfaceInfo</type></link> to fill in
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>



<refsect1 id="GTypePlugin.see-also">
<title>See Also</title>
#GTypeModule and <link linkend="g-type-register-dynamic"><function>g_type_register_dynamic()</function></link>.
</refsect1>

</refentry>
