gobject/gtypemodule.c

   1 /* GObject - GLib Type, Object, Parameter and Signal Library
   2  * Copyright (C) 2000 Red Hat, Inc.
   3  *
   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.
   8  *
   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.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
  16  */
  17
  18 #include "config.h"
  19
  20 #include <stdlib.h>
  21
  22 #include "gtypeplugin.h"
  23 #include "gtypemodule.h"
  24
  25
  26 /**
  27  * SECTION:gtypemodule
  28  * @short_description: Type loading modules
  29  * @see_also:<variablelist>
  30  * <varlistentry>
  31  * <term>#GTypePlugin</term>
  32  * <listitem><para>The abstract type loader interface.</para></listitem>
  33  * </varlistentry>
  34  * <varlistentry>
  35  * <term>#GModule</term>
  36  * <listitem><para>Portable mechanism for dynamically loaded modules.</para></listitem>
  37  * </varlistentry>
  38  * </variablelist>
  39  * @title: GTypeModule
  40  *
  41  * #GTypeModule provides a simple implementation of the #GTypePlugin
  42  * interface. The model of #GTypeModule is a dynamically loaded module
  43  * which implements some number of types and interface
  44  * implementations. When the module is loaded, it registers its types
  45  * and interfaces using g_type_module_register_type() and
  46  * g_type_module_add_interface().  As long as any instances of these
  47  * types and interface implementations are in use, the module is kept
  48  * loaded. When the types and interfaces are gone, the module may be
  49  * unloaded. If the types and interfaces become used again, the module
  50  * will be reloaded. Note that the last unref cannot happen in module
  51  * code, since that would lead to the caller's code being unloaded before
  52  * g_object_unref() returns to it.
  53  *
  54  * Keeping track of whether the module should be loaded or not is done by
  55  * using a use count - it starts at zero, and whenever it is greater than
  56  * zero, the module is loaded. The use count is maintained internally by
  57  * the type system, but also can be explicitly controlled by
  58  * g_type_module_use() and g_type_module_unuse(). Typically, when loading
  59  * a module for the first type, g_type_module_use() will be used to load
  60  * it so that it can initialize its types. At some later point, when the
  61  * module no longer needs to be loaded except for the type
  62  * implementations it contains, g_type_module_unuse() is called.
  63  *
  64  * #GTypeModule does not actually provide any implementation of module
  65  * loading and unloading. To create a particular module type you must
  66  * derive from #GTypeModule and implement the load and unload functions
  67  * in #GTypeModuleClass.
  68  */
  69
  70
  71 typedef struct _ModuleTypeInfo ModuleTypeInfo;
  72 typedef struct _ModuleInterfaceInfo ModuleInterfaceInfo;
  73
  74 struct _ModuleTypeInfo
  75 {
  76   gboolean  loaded;
  77   GType     type;
  78   GType     parent_type;
  79   GTypeInfo info;
  80 };
  81
  82 struct _ModuleInterfaceInfo
  83 {
  84   gboolean       loaded;
  85   GType          instance_type;
  86   GType          interface_type;
  87   GInterfaceInfo info;
  88 };
  89
  90 static void g_type_module_use_plugin              (GTypePlugin     *plugin);
  91 static void g_type_module_complete_type_info      (GTypePlugin     *plugin,
  92                                                    GType            g_type,
  93                                                    GTypeInfo       *info,
  94                                                    GTypeValueTable *value_table);
  95 static void g_type_module_complete_interface_info (GTypePlugin     *plugin,
  96                                                    GType            instance_type,
  97                                                    GType            interface_type,
  98                                                    GInterfaceInfo  *info);
  99
 100 static gpointer parent_class = NULL;
 101
 102 static void
 103 g_type_module_dispose (GObject *object)
 104 {
 105   GTypeModule *module = G_TYPE_MODULE (object);
 106
 107   if (module->type_infos || module->interface_infos)
 108     {
 109       g_warning (G_STRLOC ": unsolicitated invocation of g_object_run_dispose() on GTypeModule");
 110
 111       g_object_ref (object);
 112     }
 113
 114   G_OBJECT_CLASS (parent_class)->dispose (object);
 115 }
 116
 117 static void
 118 g_type_module_finalize (GObject *object)
 119 {
 120   GTypeModule *module = G_TYPE_MODULE (object);
 121
 122   g_free (module->name);
 123
 124   G_OBJECT_CLASS (parent_class)->finalize (object);
 125 }
 126
 127 static void
 128 g_type_module_class_init (GTypeModuleClass *class)
 129 {
 130   GObjectClass *gobject_class = G_OBJECT_CLASS (class);
 131
 132   parent_class = G_OBJECT_CLASS (g_type_class_peek_parent (class));
 133
 134   gobject_class->dispose = g_type_module_dispose;
 135   gobject_class->finalize = g_type_module_finalize;
 136 }
 137
 138 static void
 139 g_type_module_iface_init (GTypePluginClass *iface)
 140 {
 141   iface->use_plugin = g_type_module_use_plugin;
 142   iface->unuse_plugin = (void (*) (GTypePlugin *))g_type_module_unuse;
 143   iface->complete_type_info = g_type_module_complete_type_info;
 144   iface->complete_interface_info = g_type_module_complete_interface_info;
 145 }
 146
 147 GType
 148 g_type_module_get_type (void)
 149 {
 150   static GType type_module_type = 0;
 151
 152   if (!type_module_type)
 153     {
 154       const GTypeInfo type_module_info = {
 155         sizeof (GTypeModuleClass),
 156         NULL,           /* base_init */
 157         NULL,           /* base_finalize */
 158         (GClassInitFunc) g_type_module_class_init,
 159         NULL,           /* class_finalize */
 160         NULL,           /* class_data */
 161         sizeof (GTypeModule),
 162         0,              /* n_preallocs */
 163         NULL,           /* instance_init */
 164       };
 165       const GInterfaceInfo iface_info = {
 166         (GInterfaceInitFunc) g_type_module_iface_init,
 167         NULL,               /* interface_finalize */
 168         NULL,               /* interface_data */
 169       };
 170
 171       type_module_type = g_type_register_static (G_TYPE_OBJECT, g_intern_static_string ("GTypeModule"), &type_module_info, G_TYPE_FLAG_ABSTRACT);
 172
 173       g_type_add_interface_static (type_module_type, G_TYPE_TYPE_PLUGIN, &iface_info);
 174     }
 175
 176   return type_module_type;
 177 }
 178
 179 /**
 180  * g_type_module_set_name:
 181  * @module: a #GTypeModule.
 182  * @name: a human-readable name to use in error messages.
 183  *
 184  * Sets the name for a #GTypeModule
 185  */
 186 void
 187 g_type_module_set_name (GTypeModule  *module,
 188                         const gchar  *name)
 189 {
 190   g_return_if_fail (G_IS_TYPE_MODULE (module));
 191
 192   g_free (module->name);
 193   module->name = g_strdup (name);
 194 }
 195
 196 static ModuleTypeInfo *
 197 g_type_module_find_type_info (GTypeModule *module,
 198                               GType        type)
 199 {
 200   GSList *tmp_list = module->type_infos;
 201   while (tmp_list)
 202     {
 203       ModuleTypeInfo *type_info = tmp_list->data;
 204       if (type_info->type == type)
 205         return type_info;
 206
 207       tmp_list = tmp_list->next;
 208     }
 209
 210   return NULL;
 211 }
 212
 213 static ModuleInterfaceInfo *
 214 g_type_module_find_interface_info (GTypeModule *module,
 215                                    GType        instance_type,
 216                                    GType        interface_type)
 217 {
 218   GSList *tmp_list = module->interface_infos;
 219   while (tmp_list)
 220     {
 221       ModuleInterfaceInfo *interface_info = tmp_list->data;
 222       if (interface_info->instance_type == instance_type &&
 223           interface_info->interface_type == interface_type)
 224         return interface_info;
 225
 226       tmp_list = tmp_list->next;
 227     }
 228
 229   return NULL;
 230 }
 231
 232 /**
 233  * g_type_module_use:
 234  * @module: a #GTypeModule
 235  *
 236  * Increases the use count of a #GTypeModule by one. If the
 237  * use count was zero before, the plugin will be loaded.
 238  * If loading the plugin fails, the use count is reset to
 239  * its prior value.
 240  *
 241  * Returns: %FALSE if the plugin needed to be loaded and
 242  *  loading the plugin failed.
 243  */
 244 gboolean
 245 g_type_module_use (GTypeModule *module)
 246 {
 247   g_return_val_if_fail (G_IS_TYPE_MODULE (module), FALSE);
 248
 249   module->use_count++;
 250   if (module->use_count == 1)
 251     {
 252       GSList *tmp_list;
 253
 254       if (!G_TYPE_MODULE_GET_CLASS (module)->load (module))
 255         {
 256           module->use_count--;
 257           return FALSE;
 258         }
 259
 260       tmp_list = module->type_infos;
 261       while (tmp_list)
 262         {
 263           ModuleTypeInfo *type_info = tmp_list->data;
 264           if (!type_info->loaded)
 265             {
 266               g_warning ("plugin '%s' failed to register type '%s'\n",
 267                          module->name ? module->name : "(unknown)",
 268                          g_type_name (type_info->type));
 269               module->use_count--;
 270               return FALSE;
 271             }
 272
 273           tmp_list = tmp_list->next;
 274         }
 275     }
 276
 277   return TRUE;
 278 }
 279
 280 /**
 281  * g_type_module_unuse:
 282  * @module: a #GTypeModule
 283  *
 284  * Decreases the use count of a #GTypeModule by one. If the
 285  * result is zero, the module will be unloaded. (However, the
 286  * #GTypeModule will not be freed, and types associated with the
 287  * #GTypeModule are not unregistered. Once a #GTypeModule is
 288  * initialized, it must exist forever.)
 289  */
 290 void
 291 g_type_module_unuse (GTypeModule *module)
 292 {
 293   g_return_if_fail (G_IS_TYPE_MODULE (module));
 294   g_return_if_fail (module->use_count > 0);
 295
 296   module->use_count--;
 297
 298   if (module->use_count == 0)
 299     {
 300       GSList *tmp_list;
 301
 302       G_TYPE_MODULE_GET_CLASS (module)->unload (module);
 303
 304       tmp_list = module->type_infos;
 305       while (tmp_list)
 306         {
 307           ModuleTypeInfo *type_info = tmp_list->data;
 308           type_info->loaded = FALSE;
 309
 310           tmp_list = tmp_list->next;
 311         }
 312     }
 313 }
 314
 315 static void
 316 g_type_module_use_plugin (GTypePlugin *plugin)
 317 {
 318   GTypeModule *module = G_TYPE_MODULE (plugin);
 319
 320   if (!g_type_module_use (module))
 321     {
 322       g_warning ("Fatal error - Could not reload previously loaded plugin '%s'\n",
 323                  module->name ? module->name : "(unknown)");
 324       exit (1);
 325     }
 326 }
 327
 328 static void
 329 g_type_module_complete_type_info (GTypePlugin     *plugin,
 330                                   GType            g_type,
 331                                   GTypeInfo       *info,
 332                                   GTypeValueTable *value_table)
 333 {
 334   GTypeModule *module = G_TYPE_MODULE (plugin);
 335   ModuleTypeInfo *module_type_info = g_type_module_find_type_info (module, g_type);
 336
 337   *info = module_type_info->info;
 338
 339   if (module_type_info->info.value_table)
 340     *value_table = *module_type_info->info.value_table;
 341 }
 342
 343 static void
 344 g_type_module_complete_interface_info (GTypePlugin    *plugin,
 345                                        GType           instance_type,
 346                                        GType           interface_type,
 347                                        GInterfaceInfo *info)
 348 {
 349   GTypeModule *module = G_TYPE_MODULE (plugin);
 350   ModuleInterfaceInfo *module_interface_info = g_type_module_find_interface_info (module, instance_type, interface_type);
 351
 352   *info = module_interface_info->info;
 353 }
 354
 355 /**
 356  * g_type_module_register_type:
 357  * @module: a #GTypeModule
 358  * @parent_type: the type for the parent class
 359  * @type_name: name for the type
 360  * @type_info: type information structure
 361  * @flags: flags field providing details about the type
 362  *
 363  * Looks up or registers a type that is implemented with a particular
 364  * type plugin. If a type with name @type_name was previously registered,
 365  * the #GType identifier for the type is returned, otherwise the type
 366  * is newly registered, and the resulting #GType identifier returned.
 367  *
 368  * When reregistering a type (typically because a module is unloaded
 369  * then reloaded, and reinitialized), @module and @parent_type must
 370  * be the same as they were previously.
 371  *
 372  * As long as any instances of the type exist, the type plugin will
 373  * not be unloaded.
 374  *
 375  * Returns: the new or existing type ID
 376  */
 377 GType
 378 g_type_module_register_type (GTypeModule     *module,
 379                              GType            parent_type,
 380                              const gchar     *type_name,
 381                              const GTypeInfo *type_info,
 382                              GTypeFlags       flags)
 383 {
 384   ModuleTypeInfo *module_type_info = NULL;
 385   GType type;
 386
 387   g_return_val_if_fail (module != NULL, 0);
 388   g_return_val_if_fail (type_name != NULL, 0);
 389   g_return_val_if_fail (type_info != NULL, 0);
 390
 391   type = g_type_from_name (type_name);
 392   if (type)
 393     {
 394       GTypePlugin *old_plugin = g_type_get_plugin (type);
 395
 396       if (old_plugin != G_TYPE_PLUGIN (module))
 397         {
 398           g_warning ("Two different plugins tried to register '%s'.", type_name);
 399           return 0;
 400         }
 401     }
 402
 403   if (type)
 404     {
 405       module_type_info = g_type_module_find_type_info (module, type);
 406
 407       if (module_type_info->parent_type != parent_type)
 408         {
 409           const gchar *parent_type_name = g_type_name (parent_type);
 410
 411           g_warning ("Type '%s' recreated with different parent type.\n"
 412                      "(was '%s', now '%s')", type_name,
 413                      g_type_name (module_type_info->parent_type),
 414                      parent_type_name ? parent_type_name : "(unknown)");
 415           return 0;
 416         }
 417
 418       if (module_type_info->info.value_table)
 419         g_free ((GTypeValueTable *) module_type_info->info.value_table);
 420     }
 421   else
 422     {
 423       module_type_info = g_new (ModuleTypeInfo, 1);
 424
 425       module_type_info->parent_type = parent_type;
 426       module_type_info->type = g_type_register_dynamic (parent_type, type_name, G_TYPE_PLUGIN (module), flags);
 427
 428       module->type_infos = g_slist_prepend (module->type_infos, module_type_info);
 429     }
 430
 431   module_type_info->loaded = TRUE;
 432   module_type_info->info = *type_info;
 433   if (type_info->value_table)
 434     module_type_info->info.value_table = g_memdup (type_info->value_table,
 435                                                    sizeof (GTypeValueTable));
 436
 437   return module_type_info->type;
 438 }
 439
 440 /**
 441  * g_type_module_add_interface:
 442  * @module: a #GTypeModule
 443  * @instance_type: type to which to add the interface.
 444  * @interface_type: interface type to add
 445  * @interface_info: type information structure
 446  *
 447  * Registers an additional interface for a type, whose interface lives
 448  * in the given type plugin. If the interface was already registered
 449  * for the type in this plugin, nothing will be done.
 450  *
 451  * As long as any instances of the type exist, the type plugin will
 452  * not be unloaded.
 453  */
 454 void
 455 g_type_module_add_interface (GTypeModule          *module,
 456                              GType                 instance_type,
 457                              GType                 interface_type,
 458                              const GInterfaceInfo *interface_info)
 459 {
 460   ModuleInterfaceInfo *module_interface_info = NULL;
 461
 462   g_return_if_fail (module != NULL);
 463   g_return_if_fail (interface_info != NULL);
 464
 465   if (g_type_is_a (instance_type, interface_type))
 466     {
 467       GTypePlugin *old_plugin = g_type_interface_get_plugin (instance_type,
 468                                                              interface_type);
 469
 470       if (!old_plugin)
 471         {
 472           g_warning ("Interface '%s' for '%s' was previously registered statically or for a parent type.",
 473                      g_type_name (interface_type), g_type_name (instance_type));
 474           return;
 475         }
 476       else if (old_plugin != G_TYPE_PLUGIN (module))
 477         {
 478           g_warning ("Two different plugins tried to register interface '%s' for '%s'.",
 479                      g_type_name (interface_type), g_type_name (instance_type));
 480           return;
 481         }
 482
 483       module_interface_info = g_type_module_find_interface_info (module, instance_type, interface_type);
 484
 485       g_assert (module_interface_info);
 486     }
 487   else
 488     {
 489       module_interface_info = g_new (ModuleInterfaceInfo, 1);
 490
 491       module_interface_info->instance_type = instance_type;
 492       module_interface_info->interface_type = interface_type;
 493
 494       g_type_add_interface_dynamic (instance_type, interface_type, G_TYPE_PLUGIN (module));
 495
 496       module->interface_infos = g_slist_prepend (module->interface_infos, module_interface_info);
 497     }
 498
 499   module_interface_info->loaded = TRUE;
 500   module_interface_info->info = *interface_info;
 501 }
 502
 503 /**
 504  * g_type_module_register_enum:
 505  * @module: a #GTypeModule
 506  * @name: name for the type
 507  * @const_static_values: an array of #GEnumValue structs for the
 508  *                       possible enumeration values. The array is
 509  *                       terminated by a struct with all members being
 510  *                       0.
 511  *
 512  * Looks up or registers an enumeration that is implemented with a particular
 513  * type plugin. If a type with name @type_name was previously registered,
 514  * the #GType identifier for the type is returned, otherwise the type
 515  * is newly registered, and the resulting #GType identifier returned.
 516  *
 517  * As long as any instances of the type exist, the type plugin will
 518  * not be unloaded.
 519  *
 520  * Since: 2.6
 521  *
 522  * Returns: the new or existing type ID
 523  */
 524 GType
 525 g_type_module_register_enum (GTypeModule      *module,
 526                              const gchar      *name,
 527                              const GEnumValue *const_static_values)
 528 {
 529   GTypeInfo enum_type_info = { 0, };
 530
 531   g_return_val_if_fail (G_IS_TYPE_MODULE (module), 0);
 532   g_return_val_if_fail (name != NULL, 0);
 533   g_return_val_if_fail (const_static_values != NULL, 0);
 534
 535   g_enum_complete_type_info (G_TYPE_ENUM,
 536                              &enum_type_info, const_static_values);
 537
 538   return g_type_module_register_type (G_TYPE_MODULE (module),
 539                                       G_TYPE_ENUM, name, &enum_type_info, 0);
 540 }
 541
 542 /**
 543  * g_type_module_register_flags:
 544  * @module: a #GTypeModule
 545  * @name: name for the type
 546  * @const_static_values: an array of #GFlagsValue structs for the
 547  *                       possible flags values. The array is
 548  *                       terminated by a struct with all members being
 549  *                       0.
 550  *
 551  * Looks up or registers a flags type that is implemented with a particular
 552  * type plugin. If a type with name @type_name was previously registered,
 553  * the #GType identifier for the type is returned, otherwise the type
 554  * is newly registered, and the resulting #GType identifier returned.
 555  *
 556  * As long as any instances of the type exist, the type plugin will
 557  * not be unloaded.
 558  *
 559  * Since: 2.6
 560  *
 561  * Returns: the new or existing type ID
 562  */
 563 GType
 564 g_type_module_register_flags (GTypeModule      *module,
 565                              const gchar       *name,
 566                              const GFlagsValue *const_static_values)
 567 {
 568   GTypeInfo flags_type_info = { 0, };
 569
 570   g_return_val_if_fail (G_IS_TYPE_MODULE (module), 0);
 571   g_return_val_if_fail (name != NULL, 0);
 572   g_return_val_if_fail (const_static_values != NULL, 0);
 573
 574   g_flags_complete_type_info (G_TYPE_FLAGS,
 575                              &flags_type_info, const_static_values);
 576
 577   return g_type_module_register_type (G_TYPE_MODULE (module),
 578                                       G_TYPE_FLAGS, name, &flags_type_info, 0);
 579 }