1 /* GObject - GLib Type, Object, Parameter and Signal Library
2 * Copyright (C) 2000 Red Hat, Inc.
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
24 #include "gtypeplugin.h"
25 #include "gtypemodule.h"
30 * @short_description: Type loading modules
31 * @see_also:<variablelist>
33 * <term>#GTypePlugin</term>
34 * <listitem><para>The abstract type loader interface.</para></listitem>
37 * <term>#GModule</term>
38 * <listitem><para>Portable mechanism for dynamically loaded modules.</para></listitem>
43 * #GTypeModule provides a simple implementation of the #GTypePlugin
44 * interface. The model of #GTypeModule is a dynamically loaded module
45 * which implements some number of types and interface
46 * implementations. When the module is loaded, it registers its types
47 * and interfaces using g_type_module_register_type() and
48 * g_type_module_add_interface(). As long as any instances of these
49 * types and interface implementations are in use, the module is kept
50 * loaded. When the types and interfaces are gone, the module may be
51 * unloaded. If the types and interfaces become used again, the module
52 * will be reloaded. Note that the last unref can not happen in module
53 * code, since that would lead to the caller's code being unloaded before
54 * g_object_unref() returns to it.
56 * Keeping track of whether the module should be loaded or not is done by
57 * using a use count - it starts at zero, and whenever it is greater than
58 * zero, the module is loaded. The use count is maintained internally by
59 * the type system, but also can be explicitly controlled by
60 * g_type_module_use() and g_type_module_unuse(). Typically, when loading
61 * a module for the first type, g_type_module_use() will be used to load
62 * it so that it can initialize its types. At some later point, when the
63 * module no longer needs to be loaded except for the type
64 * implementations it contains, g_type_module_unuse() is called.
66 * #GTypeModule does not actually provide any implementation of module
67 * loading and unloading. To create a particular module type you must
68 * derive from #GTypeModule and implement the load and unload functions
69 * in #GTypeModuleClass.
73 typedef struct _ModuleTypeInfo ModuleTypeInfo
;
74 typedef struct _ModuleInterfaceInfo ModuleInterfaceInfo
;
76 struct _ModuleTypeInfo
84 struct _ModuleInterfaceInfo
92 static void g_type_module_use_plugin (GTypePlugin
*plugin
);
93 static void g_type_module_complete_type_info (GTypePlugin
*plugin
,
96 GTypeValueTable
*value_table
);
97 static void g_type_module_complete_interface_info (GTypePlugin
*plugin
,
100 GInterfaceInfo
*info
);
102 static gpointer parent_class
= NULL
;
105 g_type_module_dispose (GObject
*object
)
107 GTypeModule
*module
= G_TYPE_MODULE (object
);
109 if (module
->type_infos
|| module
->interface_infos
)
111 g_warning (G_STRLOC
": unsolicitated invocation of g_object_dispose() on GTypeModule");
113 g_object_ref (object
);
116 G_OBJECT_CLASS (parent_class
)->dispose (object
);
120 g_type_module_finalize (GObject
*object
)
122 GTypeModule
*module
= G_TYPE_MODULE (object
);
124 g_free (module
->name
);
126 G_OBJECT_CLASS (parent_class
)->finalize (object
);
130 g_type_module_class_init (GTypeModuleClass
*class)
132 GObjectClass
*gobject_class
= G_OBJECT_CLASS (class);
134 parent_class
= G_OBJECT_CLASS (g_type_class_peek_parent (class));
136 gobject_class
->dispose
= g_type_module_dispose
;
137 gobject_class
->finalize
= g_type_module_finalize
;
141 g_type_module_iface_init (GTypePluginClass
*iface
)
143 iface
->use_plugin
= g_type_module_use_plugin
;
144 iface
->unuse_plugin
= (void (*) (GTypePlugin
*))g_type_module_unuse
;
145 iface
->complete_type_info
= g_type_module_complete_type_info
;
146 iface
->complete_interface_info
= g_type_module_complete_interface_info
;
150 g_type_module_get_type (void)
152 static GType type_module_type
= 0;
154 if (!type_module_type
)
156 static const GTypeInfo type_module_info
= {
157 sizeof (GTypeModuleClass
),
158 NULL
, /* base_init */
159 NULL
, /* base_finalize */
160 (GClassInitFunc
) g_type_module_class_init
,
161 NULL
, /* class_finalize */
162 NULL
, /* class_data */
163 sizeof (GTypeModule
),
165 NULL
, /* instance_init */
167 static const GInterfaceInfo iface_info
= {
168 (GInterfaceInitFunc
) g_type_module_iface_init
,
169 NULL
, /* interface_finalize */
170 NULL
, /* interface_data */
173 type_module_type
= g_type_register_static (G_TYPE_OBJECT
, g_intern_static_string ("GTypeModule"), &type_module_info
, G_TYPE_FLAG_ABSTRACT
);
175 g_type_add_interface_static (type_module_type
, G_TYPE_TYPE_PLUGIN
, &iface_info
);
178 return type_module_type
;
182 * g_type_module_set_name:
183 * @module: a #GTypeModule.
184 * @name: a human-readable name to use in error messages.
186 * Sets the name for a #GTypeModule
189 g_type_module_set_name (GTypeModule
*module
,
192 g_return_if_fail (G_IS_TYPE_MODULE (module
));
194 g_free (module
->name
);
195 module
->name
= g_strdup (name
);
198 static ModuleTypeInfo
*
199 g_type_module_find_type_info (GTypeModule
*module
,
202 GSList
*tmp_list
= module
->type_infos
;
205 ModuleTypeInfo
*type_info
= tmp_list
->data
;
206 if (type_info
->type
== type
)
209 tmp_list
= tmp_list
->next
;
215 static ModuleInterfaceInfo
*
216 g_type_module_find_interface_info (GTypeModule
*module
,
218 GType interface_type
)
220 GSList
*tmp_list
= module
->interface_infos
;
223 ModuleInterfaceInfo
*interface_info
= tmp_list
->data
;
224 if (interface_info
->instance_type
== instance_type
&&
225 interface_info
->interface_type
== interface_type
)
226 return interface_info
;
228 tmp_list
= tmp_list
->next
;
236 * @module: a #GTypeModule
238 * Increases the use count of a #GTypeModule by one. If the
239 * use count was zero before, the plugin will be loaded.
240 * If loading the plugin fails, the use count is reset to
243 * Returns: %FALSE if the plugin needed to be loaded and
244 * loading the plugin failed.
247 g_type_module_use (GTypeModule
*module
)
249 g_return_val_if_fail (G_IS_TYPE_MODULE (module
), FALSE
);
252 if (module
->use_count
== 1)
256 if (!G_TYPE_MODULE_GET_CLASS (module
)->load (module
))
262 tmp_list
= module
->type_infos
;
265 ModuleTypeInfo
*type_info
= tmp_list
->data
;
266 if (!type_info
->loaded
)
268 g_warning ("plugin '%s' failed to register type '%s'\n",
269 module
->name
? module
->name
: "(unknown)",
270 g_type_name (type_info
->type
));
275 tmp_list
= tmp_list
->next
;
283 * g_type_module_unuse:
284 * @module: a #GTypeModule
286 * Decreases the use count of a #GTypeModule by one. If the
287 * result is zero, the module will be unloaded. (However, the
288 * #GTypeModule will not be freed, and types associated with the
289 * #GTypeModule are not unregistered. Once a #GTypeModule is
290 * initialized, it must exist forever.)
293 g_type_module_unuse (GTypeModule
*module
)
295 g_return_if_fail (G_IS_TYPE_MODULE (module
));
296 g_return_if_fail (module
->use_count
> 0);
300 if (module
->use_count
== 0)
304 G_TYPE_MODULE_GET_CLASS (module
)->unload (module
);
306 tmp_list
= module
->type_infos
;
309 ModuleTypeInfo
*type_info
= tmp_list
->data
;
310 type_info
->loaded
= FALSE
;
312 tmp_list
= tmp_list
->next
;
318 g_type_module_use_plugin (GTypePlugin
*plugin
)
320 GTypeModule
*module
= G_TYPE_MODULE (plugin
);
322 if (!g_type_module_use (module
))
324 g_warning ("Fatal error - Could not reload previously loaded plugin '%s'\n",
325 module
->name
? module
->name
: "(unknown)");
331 g_type_module_complete_type_info (GTypePlugin
*plugin
,
334 GTypeValueTable
*value_table
)
336 GTypeModule
*module
= G_TYPE_MODULE (plugin
);
337 ModuleTypeInfo
*module_type_info
= g_type_module_find_type_info (module
, g_type
);
339 *info
= module_type_info
->info
;
341 if (module_type_info
->info
.value_table
)
342 *value_table
= *module_type_info
->info
.value_table
;
346 g_type_module_complete_interface_info (GTypePlugin
*plugin
,
348 GType interface_type
,
349 GInterfaceInfo
*info
)
351 GTypeModule
*module
= G_TYPE_MODULE (plugin
);
352 ModuleInterfaceInfo
*module_interface_info
= g_type_module_find_interface_info (module
, instance_type
, interface_type
);
354 *info
= module_interface_info
->info
;
358 * g_type_module_register_type:
359 * @module: a #GTypeModule
360 * @parent_type: the type for the parent class
361 * @type_name: name for the type
362 * @type_info: type information structure
363 * @flags: flags field providing details about the type
365 * Looks up or registers a type that is implemented with a particular
366 * type plugin. If a type with name @type_name was previously registered,
367 * the #GType identifier for the type is returned, otherwise the type
368 * is newly registered, and the resulting #GType identifier returned.
370 * When reregistering a type (typically because a module is unloaded
371 * then reloaded, and reinitialized), @module and @parent_type must
372 * be the same as they were previously.
374 * As long as any instances of the type exist, the type plugin will
377 * Returns: the new or existing type ID
380 g_type_module_register_type (GTypeModule
*module
,
382 const gchar
*type_name
,
383 const GTypeInfo
*type_info
,
386 ModuleTypeInfo
*module_type_info
= NULL
;
389 g_return_val_if_fail (module
!= NULL
, 0);
390 g_return_val_if_fail (type_name
!= NULL
, 0);
391 g_return_val_if_fail (type_info
!= NULL
, 0);
393 type
= g_type_from_name (type_name
);
396 GTypePlugin
*old_plugin
= g_type_get_plugin (type
);
398 if (old_plugin
!= G_TYPE_PLUGIN (module
))
400 g_warning ("Two different plugins tried to register '%s'.", type_name
);
407 module_type_info
= g_type_module_find_type_info (module
, type
);
409 if (module_type_info
->parent_type
!= parent_type
)
411 const gchar
*parent_type_name
= g_type_name (parent_type
);
413 g_warning ("Type '%s' recreated with different parent type.\n"
414 "(was '%s', now '%s')", type_name
,
415 g_type_name (module_type_info
->parent_type
),
416 parent_type_name
? parent_type_name
: "(unknown)");
420 if (module_type_info
->info
.value_table
)
421 g_free ((GTypeValueTable
*) module_type_info
->info
.value_table
);
425 module_type_info
= g_new (ModuleTypeInfo
, 1);
427 module_type_info
->parent_type
= parent_type
;
428 module_type_info
->type
= g_type_register_dynamic (parent_type
, type_name
, G_TYPE_PLUGIN (module
), flags
);
430 module
->type_infos
= g_slist_prepend (module
->type_infos
, module_type_info
);
433 module_type_info
->loaded
= TRUE
;
434 module_type_info
->info
= *type_info
;
435 if (type_info
->value_table
)
436 module_type_info
->info
.value_table
= g_memdup (type_info
->value_table
,
437 sizeof (GTypeValueTable
));
439 return module_type_info
->type
;
443 * g_type_module_add_interface:
444 * @module: a #GTypeModule
445 * @instance_type: type to which to add the interface.
446 * @interface_type: interface type to add
447 * @interface_info: type information structure
449 * Registers an additional interface for a type, whose interface lives
450 * in the given type plugin. If the interface was already registered
451 * for the type in this plugin, nothing will be done.
453 * As long as any instances of the type exist, the type plugin will
457 g_type_module_add_interface (GTypeModule
*module
,
459 GType interface_type
,
460 const GInterfaceInfo
*interface_info
)
462 ModuleInterfaceInfo
*module_interface_info
= NULL
;
464 g_return_if_fail (module
!= NULL
);
465 g_return_if_fail (interface_info
!= NULL
);
467 if (g_type_is_a (instance_type
, interface_type
))
469 GTypePlugin
*old_plugin
= g_type_interface_get_plugin (instance_type
,
474 g_warning ("Interface '%s' for '%s' was previously registered statically or for a parent type.",
475 g_type_name (interface_type
), g_type_name (instance_type
));
478 else if (old_plugin
!= G_TYPE_PLUGIN (module
))
480 g_warning ("Two different plugins tried to register interface '%s' for '%s'.",
481 g_type_name (interface_type
), g_type_name (instance_type
));
485 module_interface_info
= g_type_module_find_interface_info (module
, instance_type
, interface_type
);
487 g_assert (module_interface_info
);
491 module_interface_info
= g_new (ModuleInterfaceInfo
, 1);
493 module_interface_info
->instance_type
= instance_type
;
494 module_interface_info
->interface_type
= interface_type
;
496 g_type_add_interface_dynamic (instance_type
, interface_type
, G_TYPE_PLUGIN (module
));
498 module
->interface_infos
= g_slist_prepend (module
->interface_infos
, module_interface_info
);
501 module_interface_info
->loaded
= TRUE
;
502 module_interface_info
->info
= *interface_info
;
506 * g_type_module_register_enum:
507 * @module: a #GTypeModule
508 * @name: name for the type
509 * @const_static_values: an array of #GEnumValue structs for the
510 * possible enumeration values. The array is
511 * terminated by a struct with all members being
514 * Looks up or registers an enumeration that is implemented with a particular
515 * type plugin. If a type with name @type_name was previously registered,
516 * the #GType identifier for the type is returned, otherwise the type
517 * is newly registered, and the resulting #GType identifier returned.
519 * As long as any instances of the type exist, the type plugin will
524 * Returns: the new or existing type ID
527 g_type_module_register_enum (GTypeModule
*module
,
529 const GEnumValue
*const_static_values
)
531 GTypeInfo enum_type_info
= { 0, };
533 g_return_val_if_fail (G_IS_TYPE_MODULE (module
), 0);
534 g_return_val_if_fail (name
!= NULL
, 0);
535 g_return_val_if_fail (const_static_values
!= NULL
, 0);
537 g_enum_complete_type_info (G_TYPE_ENUM
,
538 &enum_type_info
, const_static_values
);
540 return g_type_module_register_type (G_TYPE_MODULE (module
),
541 G_TYPE_ENUM
, name
, &enum_type_info
, 0);
545 * g_type_module_register_flags:
546 * @module: a #GTypeModule
547 * @name: name for the type
548 * @const_static_values: an array of #GFlagsValue structs for the
549 * possible flags values. The array is
550 * terminated by a struct with all members being
553 * Looks up or registers a flags type that is implemented with a particular
554 * type plugin. If a type with name @type_name was previously registered,
555 * the #GType identifier for the type is returned, otherwise the type
556 * is newly registered, and the resulting #GType identifier returned.
558 * As long as any instances of the type exist, the type plugin will
563 * Returns: the new or existing type ID
566 g_type_module_register_flags (GTypeModule
*module
,
568 const GFlagsValue
*const_static_values
)
570 GTypeInfo flags_type_info
= { 0, };
572 g_return_val_if_fail (G_IS_TYPE_MODULE (module
), 0);
573 g_return_val_if_fail (name
!= NULL
, 0);
574 g_return_val_if_fail (const_static_values
!= NULL
, 0);
576 g_flags_complete_type_info (G_TYPE_FLAGS
,
577 &flags_type_info
, const_static_values
);
579 return g_type_module_register_type (G_TYPE_MODULE (module
),
580 G_TYPE_FLAGS
, name
, &flags_type_info
, 0);