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"
26 #include "gobjectalias.h"
31 * @short_description: Type loading modules
32 * @see_also:<variablelist>
34 * <term>#GTypePlugin</term>
35 * <listitem><para>The abstract type loader interface.</para></listitem>
38 * <term>#GModule</term>
39 * <listitem><para>Portable mechanism for dynamically loaded modules.</para></listitem>
44 * #GTypeModule provides a simple implementation of the #GTypePlugin
45 * interface. The model of #GTypeModule is a dynamically loaded module
46 * which implements some number of types and interface
47 * implementations. When the module is loaded, it registers its types
48 * and interfaces using g_type_module_register_type() and
49 * g_type_module_add_interface(). As long as any instances of these
50 * types and interface implementations are in use, the module is kept
51 * loaded. When the types and interfaces are gone, the module may be
52 * unloaded. If the types and interfaces become used again, the module
53 * will be reloaded. Note that the last unref can not happen in module
54 * code, since that would lead to the caller's code being unloaded before
55 * g_object_unref() returns to it.
57 * Keeping track of whether the module should be loaded or not is done by
58 * using a use count - it starts at zero, and whenever it is greater than
59 * zero, the module is loaded. The use count is maintained internally by
60 * the type system, but also can be explicitly controlled by
61 * g_type_module_use() and g_type_module_unuse(). Typically, when loading
62 * a module for the first type, g_type_module_use() will be used to load
63 * it so that it can initialize its types. At some later point, when the
64 * module no longer needs to be loaded except for the type
65 * implementations it contains, g_type_module_unuse() is called.
67 * #GTypeModule does not actually provide any implementation of module
68 * loading and unloading. To create a particular module type you must
69 * derive from #GTypeModule and implement the load and unload functions
70 * in #GTypeModuleClass.
74 typedef struct _ModuleTypeInfo ModuleTypeInfo;
75 typedef struct _ModuleInterfaceInfo ModuleInterfaceInfo;
77 struct _ModuleTypeInfo
85 struct _ModuleInterfaceInfo
93 static void g_type_module_use_plugin (GTypePlugin *plugin);
94 static void g_type_module_complete_type_info (GTypePlugin *plugin,
97 GTypeValueTable *value_table);
98 static void g_type_module_complete_interface_info (GTypePlugin *plugin,
100 GType interface_type,
101 GInterfaceInfo *info);
103 static gpointer parent_class = NULL;
106 g_type_module_dispose (GObject *object)
108 GTypeModule *module = G_TYPE_MODULE (object);
110 if (module->type_infos || module->interface_infos)
112 g_warning (G_STRLOC ": unsolicitated invocation of g_object_dispose() on GTypeModule");
114 g_object_ref (object);
117 G_OBJECT_CLASS (parent_class)->dispose (object);
121 g_type_module_finalize (GObject *object)
123 GTypeModule *module = G_TYPE_MODULE (object);
125 g_free (module->name);
127 G_OBJECT_CLASS (parent_class)->finalize (object);
131 g_type_module_class_init (GTypeModuleClass *class)
133 GObjectClass *gobject_class = G_OBJECT_CLASS (class);
135 parent_class = G_OBJECT_CLASS (g_type_class_peek_parent (class));
137 gobject_class->dispose = g_type_module_dispose;
138 gobject_class->finalize = g_type_module_finalize;
142 g_type_module_iface_init (GTypePluginClass *iface)
144 iface->use_plugin = g_type_module_use_plugin;
145 iface->unuse_plugin = (void (*) (GTypePlugin *))g_type_module_unuse;
146 iface->complete_type_info = g_type_module_complete_type_info;
147 iface->complete_interface_info = g_type_module_complete_interface_info;
151 g_type_module_get_type (void)
153 static GType type_module_type = 0;
155 if (!type_module_type)
157 static const GTypeInfo type_module_info = {
158 sizeof (GTypeModuleClass),
159 NULL, /* base_init */
160 NULL, /* base_finalize */
161 (GClassInitFunc) g_type_module_class_init,
162 NULL, /* class_finalize */
163 NULL, /* class_data */
164 sizeof (GTypeModule),
166 NULL, /* instance_init */
168 static const GInterfaceInfo iface_info = {
169 (GInterfaceInitFunc) g_type_module_iface_init,
170 NULL, /* interface_finalize */
171 NULL, /* interface_data */
174 type_module_type = g_type_register_static (G_TYPE_OBJECT, g_intern_static_string ("GTypeModule"), &type_module_info, G_TYPE_FLAG_ABSTRACT);
176 g_type_add_interface_static (type_module_type, G_TYPE_TYPE_PLUGIN, &iface_info);
179 return type_module_type;
183 * g_type_module_set_name:
184 * @module: a #GTypeModule.
185 * @name: a human-readable name to use in error messages.
187 * Sets the name for a #GTypeModule
190 g_type_module_set_name (GTypeModule *module,
193 g_return_if_fail (G_IS_TYPE_MODULE (module));
195 g_free (module->name);
196 module->name = g_strdup (name);
199 static ModuleTypeInfo *
200 g_type_module_find_type_info (GTypeModule *module,
203 GSList *tmp_list = module->type_infos;
206 ModuleTypeInfo *type_info = tmp_list->data;
207 if (type_info->type == type)
210 tmp_list = tmp_list->next;
216 static ModuleInterfaceInfo *
217 g_type_module_find_interface_info (GTypeModule *module,
219 GType interface_type)
221 GSList *tmp_list = module->interface_infos;
224 ModuleInterfaceInfo *interface_info = tmp_list->data;
225 if (interface_info->instance_type == instance_type &&
226 interface_info->interface_type == interface_type)
227 return interface_info;
229 tmp_list = tmp_list->next;
237 * @module: a #GTypeModule
239 * Increases the use count of a #GTypeModule by one. If the
240 * use count was zero before, the plugin will be loaded.
241 * If loading the plugin fails, the use count is reset to
244 * Returns: %FALSE if the plugin needed to be loaded and
245 * loading the plugin failed.
248 g_type_module_use (GTypeModule *module)
250 g_return_val_if_fail (G_IS_TYPE_MODULE (module), FALSE);
253 if (module->use_count == 1)
257 if (!G_TYPE_MODULE_GET_CLASS (module)->load (module))
263 tmp_list = module->type_infos;
266 ModuleTypeInfo *type_info = tmp_list->data;
267 if (!type_info->loaded)
269 g_warning ("plugin '%s' failed to register type '%s'\n",
270 module->name ? module->name : "(unknown)",
271 g_type_name (type_info->type));
276 tmp_list = tmp_list->next;
284 * g_type_module_unuse:
285 * @module: a #GTypeModule
287 * Decreases the use count of a #GTypeModule by one. If the
288 * result is zero, the module will be unloaded. (However, the
289 * #GTypeModule will not be freed, and types associated with the
290 * #GTypeModule are not unregistered. Once a #GTypeModule is
291 * initialized, it must exist forever.)
294 g_type_module_unuse (GTypeModule *module)
296 g_return_if_fail (G_IS_TYPE_MODULE (module));
297 g_return_if_fail (module->use_count > 0);
301 if (module->use_count == 0)
305 G_TYPE_MODULE_GET_CLASS (module)->unload (module);
307 tmp_list = module->type_infos;
310 ModuleTypeInfo *type_info = tmp_list->data;
311 type_info->loaded = FALSE;
313 tmp_list = tmp_list->next;
319 g_type_module_use_plugin (GTypePlugin *plugin)
321 GTypeModule *module = G_TYPE_MODULE (plugin);
323 if (!g_type_module_use (module))
325 g_warning ("Fatal error - Could not reload previously loaded plugin '%s'\n",
326 module->name ? module->name : "(unknown)");
332 g_type_module_complete_type_info (GTypePlugin *plugin,
335 GTypeValueTable *value_table)
337 GTypeModule *module = G_TYPE_MODULE (plugin);
338 ModuleTypeInfo *module_type_info = g_type_module_find_type_info (module, g_type);
340 *info = module_type_info->info;
342 if (module_type_info->info.value_table)
343 *value_table = *module_type_info->info.value_table;
347 g_type_module_complete_interface_info (GTypePlugin *plugin,
349 GType interface_type,
350 GInterfaceInfo *info)
352 GTypeModule *module = G_TYPE_MODULE (plugin);
353 ModuleInterfaceInfo *module_interface_info = g_type_module_find_interface_info (module, instance_type, interface_type);
355 *info = module_interface_info->info;
359 * g_type_module_register_type:
360 * @module: a #GTypeModule
361 * @parent_type: the type for the parent class
362 * @type_name: name for the type
363 * @type_info: type information structure
364 * @flags: flags field providing details about the type
366 * Looks up or registers a type that is implemented with a particular
367 * type plugin. If a type with name @type_name was previously registered,
368 * the #GType identifier for the type is returned, otherwise the type
369 * is newly registered, and the resulting #GType identifier returned.
371 * When reregistering a type (typically because a module is unloaded
372 * then reloaded, and reinitialized), @module and @parent_type must
373 * be the same as they were previously.
375 * As long as any instances of the type exist, the type plugin will
378 * Returns: the new or existing type ID
381 g_type_module_register_type (GTypeModule *module,
383 const gchar *type_name,
384 const GTypeInfo *type_info,
387 ModuleTypeInfo *module_type_info = NULL;
390 g_return_val_if_fail (module != NULL, 0);
391 g_return_val_if_fail (type_name != NULL, 0);
392 g_return_val_if_fail (type_info != NULL, 0);
394 type = g_type_from_name (type_name);
397 GTypePlugin *old_plugin = g_type_get_plugin (type);
399 if (old_plugin != G_TYPE_PLUGIN (module))
401 g_warning ("Two different plugins tried to register '%s'.", type_name);
408 module_type_info = g_type_module_find_type_info (module, type);
410 if (module_type_info->parent_type != parent_type)
412 const gchar *parent_type_name = g_type_name (parent_type);
414 g_warning ("Type '%s' recreated with different parent type.\n"
415 "(was '%s', now '%s')", type_name,
416 g_type_name (module_type_info->parent_type),
417 parent_type_name ? parent_type_name : "(unknown)");
421 if (module_type_info->info.value_table)
422 g_free ((GTypeValueTable *) module_type_info->info.value_table);
426 module_type_info = g_new (ModuleTypeInfo, 1);
428 module_type_info->parent_type = parent_type;
429 module_type_info->type = g_type_register_dynamic (parent_type, type_name, G_TYPE_PLUGIN (module), flags);
431 module->type_infos = g_slist_prepend (module->type_infos, module_type_info);
434 module_type_info->loaded = TRUE;
435 module_type_info->info = *type_info;
436 if (type_info->value_table)
437 module_type_info->info.value_table = g_memdup (type_info->value_table,
438 sizeof (GTypeValueTable));
440 return module_type_info->type;
444 * g_type_module_add_interface:
445 * @module: a #GTypeModule
446 * @instance_type: type to which to add the interface.
447 * @interface_type: interface type to add
448 * @interface_info: type information structure
450 * Registers an additional interface for a type, whose interface lives
451 * in the given type plugin. If the interface was already registered
452 * for the type in this plugin, nothing will be done.
454 * As long as any instances of the type exist, the type plugin will
458 g_type_module_add_interface (GTypeModule *module,
460 GType interface_type,
461 const GInterfaceInfo *interface_info)
463 ModuleInterfaceInfo *module_interface_info = NULL;
465 g_return_if_fail (module != NULL);
466 g_return_if_fail (interface_info != NULL);
468 if (g_type_is_a (instance_type, interface_type))
470 GTypePlugin *old_plugin = g_type_interface_get_plugin (instance_type,
475 g_warning ("Interface '%s' for '%s' was previously registered statically or for a parent type.",
476 g_type_name (interface_type), g_type_name (instance_type));
479 else if (old_plugin != G_TYPE_PLUGIN (module))
481 g_warning ("Two different plugins tried to register interface '%s' for '%s'.",
482 g_type_name (interface_type), g_type_name (instance_type));
486 module_interface_info = g_type_module_find_interface_info (module, instance_type, interface_type);
488 g_assert (module_interface_info);
492 module_interface_info = g_new (ModuleInterfaceInfo, 1);
494 module_interface_info->instance_type = instance_type;
495 module_interface_info->interface_type = interface_type;
497 g_type_add_interface_dynamic (instance_type, interface_type, G_TYPE_PLUGIN (module));
499 module->interface_infos = g_slist_prepend (module->interface_infos, module_interface_info);
502 module_interface_info->loaded = TRUE;
503 module_interface_info->info = *interface_info;
507 * g_type_module_register_enum:
508 * @module: a #GTypeModule
509 * @name: name for the type
510 * @const_static_values: an array of #GEnumValue structs for the
511 * possible enumeration values. The array is
512 * terminated by a struct with all members being
515 * Looks up or registers an enumeration that is implemented with a particular
516 * type plugin. If a type with name @type_name was previously registered,
517 * the #GType identifier for the type is returned, otherwise the type
518 * is newly registered, and the resulting #GType identifier returned.
520 * As long as any instances of the type exist, the type plugin will
525 * Returns: the new or existing type ID
528 g_type_module_register_enum (GTypeModule *module,
530 const GEnumValue *const_static_values)
532 GTypeInfo enum_type_info = { 0, };
534 g_return_val_if_fail (G_IS_TYPE_MODULE (module), 0);
535 g_return_val_if_fail (name != NULL, 0);
536 g_return_val_if_fail (const_static_values != NULL, 0);
538 g_enum_complete_type_info (G_TYPE_ENUM,
539 &enum_type_info, const_static_values);
541 return g_type_module_register_type (G_TYPE_MODULE (module),
542 G_TYPE_ENUM, name, &enum_type_info, 0);
546 * g_type_module_register_flags:
547 * @module: a #GTypeModule
548 * @name: name for the type
549 * @const_static_values: an array of #GFlagsValue structs for the
550 * possible flags values. The array is
551 * terminated by a struct with all members being
554 * Looks up or registers a flags type that is implemented with a particular
555 * type plugin. If a type with name @type_name was previously registered,
556 * the #GType identifier for the type is returned, otherwise the type
557 * is newly registered, and the resulting #GType identifier returned.
559 * As long as any instances of the type exist, the type plugin will
564 * Returns: the new or existing type ID
567 g_type_module_register_flags (GTypeModule *module,
569 const GFlagsValue *const_static_values)
571 GTypeInfo flags_type_info = { 0, };
573 g_return_val_if_fail (G_IS_TYPE_MODULE (module), 0);
574 g_return_val_if_fail (name != NULL, 0);
575 g_return_val_if_fail (const_static_values != NULL, 0);
577 g_flags_complete_type_info (G_TYPE_FLAGS,
578 &flags_type_info, const_static_values);
580 return g_type_module_register_type (G_TYPE_MODULE (module),
581 G_TYPE_FLAGS, name, &flags_type_info, 0);
585 #define __G_TYPE_MODULE_C__
586 #include "gobjectaliasdef.c"