docs/reference/gobject/tmpl/gtypemodule.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GTypeModule
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Type loading modules
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 #GTypeModule provides a simple implementation of the #GTypePlugin
  10 interface. The model of #GTypeModule is a dynamically loaded module
  11 which implements some number of types and interface
  12 implementations. When the module is loaded, it registers its types
  13 and interfaces using g_type_module_register_type() and
  14 g_type_module_add_interface().  As long as any instances of these
  15 types and interface implementations are in use, the module is kept
  16 loaded. When the types and interfaces are gone, the module may be
  17 unloaded. If the types and interfaces become used again, the module
  18 will be reloaded.
  19 </para>
  20 <para>
  21 Keeping track of whether the module should be loaded or not is done by
  22 using a use count - it starts at zero, and whenever it is greater than
  23 zero, the module is loaded. The use count is maintained internally by
  24 the type system, but also can be explicitly controlled by
  25 g_type_module_use() and g_type_module_unuse(). Typically, when loading
  26 a module for the first type, g_type_module_use() will be used to load
  27 it so that it can initialize its types. At some later point, when the
  28 module no longer needs to be loaded except for the type
  29 implementations it contains, g_type_module_unuse() is called.
  30 </para>
  31 <para>
  32 #GTypeModule does not actually provide any implementation of module
  33 loading and unloading. To create a particular module type you must
  34 derive from #GTypeModule and implement the load and unload functions
  35 in #GTypeModuleClass.
  36 </para>
  37
  38 <!-- ##### SECTION See_Also ##### -->
  39 <para>
  40 <variablelist>
  41
  42 <varlistentry>
  43 <term>#GTypePlugin</term>
  44 <listitem><para>The abstract type loader interface.</para></listitem>
  45 </varlistentry>
  46
  47 <varlistentry>
  48 <term>#GModule</term>
  49 <listitem><para>Portable mechanism for dynamically loaded modules.</para></listitem>
  50 </varlistentry>
  51
  52 </variablelist>
  53 </para>
  54
  55 <!-- ##### STRUCT GTypeModule ##### -->
  56 <para>
  57 The members of the <structname>GTypeModule</structname> structure should not
  58 be accessed directly, except for the @name field.
  59 </para>
  60
  61
  62 <!-- ##### STRUCT GTypeModuleClass ##### -->
  63 <para>
  64 In order to implement dynamic loading of types based on #GTypeModule,
  65 the @load and @unload functions in #GTypeModuleClass must be implemented.
  66 </para>
  67
  68 @parent_class:
  69 @load: loads the module and registers one or more types using
  70   g_type_module_register_type().
  71 @unload: unloads the module
  72 @reserved1:
  73 @reserved2:
  74 @reserved3:
  75 @reserved4:
  76
  77 <!-- ##### FUNCTION g_type_module_use ##### -->
  78 <para>
  79 Increases the use count of a #GTypeModule by one. If the
  80 use count was zero before, the plugin will be loaded.
  81 </para>
  82
  83 @module: a #GTypeModule
  84 @Returns: %FALSE if the plugin needed to be loaded and
  85           loading the plugin failed.
  86
  87
  88 <!-- ##### FUNCTION g_type_module_unuse ##### -->
  89 <para>
  90 Decreases the use count of a #GTypeModule by one. If the
  91 result is zero, the module will be unloaded. (However, the
  92 #GTypeModule will not be freed, and types associated with the
  93 #GTypeModule are not unregistered. Once a #GTypeModule is
  94 initialized, it must exist forever.)
  95 </para>
  96
  97 @module: a #GTypeModule
  98
  99
 100 <!-- ##### FUNCTION g_type_module_set_name ##### -->
 101 <para>
 102 Sets the name for a #GTypeModule
 103 </para>
 104
 105 @module: a #GTypeModule.
 106 @name: a human-readable name to use in error messages.
 107
 108
 109 <!-- ##### FUNCTION g_type_module_register_type ##### -->
 110 <para>
 111 Looks up or registers a type that is implemented with a particular
 112 type plugin. If a type with name @type_name was previously registered,
 113 the #GType identifier for the type is returned, otherwise the type
 114 is newly registered, and the resulting #GType identifier returned.
 115 </para>
 116 <para>
 117 When reregistering a type (typically because a module is unloaded
 118 then reloaded, and reinitialized), @module and @parent_type must
 119 be the same as they were previously.
 120 </para>
 121 <para>
 122 As long as any instances of the type exist, the type plugin will
 123 not be unloaded.
 124 </para>
 125
 126 @module:  a #GTypeModule
 127 @parent_type:    the type for the parent class
 128 @type_name:      name for the type
 129 @type_info:      type information structure
 130 @flags:          flags field providing details about the type
 131 @Returns: the new or existing type ID
 132
 133
 134 <!-- ##### FUNCTION g_type_module_add_interface ##### -->
 135 <para>
 136 Registers an additional interface for a type, whose interface
 137 lives in the given type plugin. If the interface was already registered
 138 for the type in this plugin, nothing will be done.
 139 </para>
 140 <para>
 141 As long as any instances of the type exist, the type plugin will
 142 not be unloaded.
 143 </para>
 144
 145 @module: a #GTypeModule
 146 @instance_type: type to which to add the interface.
 147 @interface_type: interface type to add
 148 @interface_info: type information structure
 149
 150