From 3f5419f6f166e20d42ce6222f58110e93347c3f5 Mon Sep 17 00:00:00 2001 From: Stefan Kost Date: Sat, 21 Jun 2008 18:20:43 +0000 Subject: Migrating docs. * docs/reference/gobject/tmpl/gtypeplugin.sgml: * gobject/gtypeplugin.c: * gobject/gtypeplugin.h: Migrating docs. svn path=/trunk/; revision=7079 --- gobject/gtypeplugin.c | 101 ++++++++++++++++++++++++++++++++++++++++++++++++++ gobject/gtypeplugin.h | 55 +++++++++++++++++++++++++++ 2 files changed, 156 insertions(+) (limited to 'gobject') diff --git a/gobject/gtypeplugin.c b/gobject/gtypeplugin.c index 2d681bdc5..8aaa7e4d6 100644 --- a/gobject/gtypeplugin.c +++ b/gobject/gtypeplugin.c @@ -16,6 +16,68 @@ * Free Software Foundation, Inc., 59 Temple Place, Suite 330, * Boston, MA 02111-1307, USA. */ +/** + * SECTION:gtypeplugin + * @Short_description: An interface for dynamically loadable types + * @See_also:#GTypeModule and g_type_register_dynamic(). + * @Titile: GTypePlugin + * + * The GObject type system supports dynamic loading of types. The #GTypePlugin + * interface is used to handle the lifecycle of dynamically loaded types. + * It goes as follows: + * + * + * + * 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: + * |[ + * new_type_id = g_type_register_dynamic (parent_type_id, + * "TypeName", + * new_type_plugin, + * type_flags); + * ]| + * where new_type_plugin is an implementation of the + * #GTypePlugin interface. + * + * + * The type's implementation is referenced, e.g. through + * g_type_class_ref() or through g_type_create_instance() (this is + * being called by g_object_new()) or through one of the above done on + * a type derived from new_type_id. + * + * + * This causes the type system to load the type's implementation by calling + * g_type_plugin_use() and g_type_plugin_complete_type_info() on + * new_type_plugin. + * + * + * At some point the type's implementation isn't required anymore, e.g. after + * g_type_class_unref() or g_type_free_instance() (called when the reference + * count of an instance drops to zero). + * + * + * This causes the type system to throw away the information retrieved from + * g_type_plugin_complete_type_info() and then it calls + * g_type_plugin_unuse() on new_type_plugin. + * + * + * Things may repeat from the second step. + * + * + * + * So basically, you need to implement a #GTypePlugin 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 + * g_type_plugin_complete_type_info() 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 g_type_plugin_use() + * and g_type_plugin_complete_type_info() again when the type is needed again. + * + * #GTypeModule is an implementation of #GTypePlugin that already implements + * most of this except for the actual module loading and unloading. It even + * handles multiple registered types per module. + */ #include "gtypeplugin.h" #include "gobjectalias.h" @@ -41,6 +103,14 @@ g_type_plugin_get_type (void) return type_plugin_type; } +/** + * g_type_plugin_use: + * @plugin: a #GTypePlugin + * + * Calls the @use_plugin function from the #GTypePluginClass of @plugin. + * There should be no need to use this function outside of the GObject + * type system itself. + */ void g_type_plugin_use (GTypePlugin *plugin) { @@ -52,6 +122,14 @@ g_type_plugin_use (GTypePlugin *plugin) iface->use_plugin (plugin); } +/** + * g_type_plugin_unuse: + * @plugin: a #GTypePlugin + * + * Calls the @unuse_plugin function from the #GTypePluginClass of @plugin. + * There should be no need to use this function outside of the GObject + * type system itself. + */ void g_type_plugin_unuse (GTypePlugin *plugin) { @@ -63,6 +141,17 @@ g_type_plugin_unuse (GTypePlugin *plugin) iface->unuse_plugin (plugin); } +/** + * g_type_plugin_complete_type_info: + * @plugin: a #GTypePlugin + * @g_type: the #GType whose info is completed + * @info: the #GTypeInfo struct to fill in + * @value_table: the #GTypeValueTable to fill in + * + * Calls the @complete_type_info function from the #GTypePluginClass of @plugin. + * There should be no need to use this function outside of the GObject + * type system itself. + */ void g_type_plugin_complete_type_info (GTypePlugin *plugin, GType g_type, @@ -82,6 +171,18 @@ g_type_plugin_complete_type_info (GTypePlugin *plugin, value_table); } +/** + * g_type_plugin_complete_interface_info: + * @plugin: the #GTypePlugin + * @instance_type: the #GType of an instantiable type to which the interface + * is added + * @interface_type: the #GType of the interface whose info is completed + * @info: the #GInterfaceInfo to fill in + * + * Calls the @complete_interface_info function from the #GTypePluginClass + * of @plugin. There should be no need to use this function outside of the + * GObject type system itself. + */ void g_type_plugin_complete_interface_info (GTypePlugin *plugin, GType instance_type, diff --git a/gobject/gtypeplugin.h b/gobject/gtypeplugin.h index a8e9803d6..ff87a7018 100644 --- a/gobject/gtypeplugin.h +++ b/gobject/gtypeplugin.h @@ -38,16 +38,71 @@ G_BEGIN_DECLS /* --- typedefs & structures --- */ typedef struct _GTypePluginClass GTypePluginClass; +/** + * GTypePluginUse: + * @plugin: the #GTypePlugin whose use count should be increased + * + * The type of the @use_plugin function of #GTypePluginClass, which gets called + * to increase the use count of @plugin. + */ typedef void (*GTypePluginUse) (GTypePlugin *plugin); +/** + * GTypePluginUnuse: + * @plugin: the #GTypePlugin whose use count should be decreased + * + * The type of the @unuse_plugin function of #GTypePluginClass. + */ typedef void (*GTypePluginUnuse) (GTypePlugin *plugin); +/** + * GTypePluginCompleteTypeInfo: + * @plugin: the #GTypePlugin + * @g_type: the #GType whose info is completed + * @info: the #GTypeInfo struct to fill in + * @value_table: the #GTypeValueTable to fill in + * + * The type of the @complete_type_info function of #GTypePluginClass. + */ typedef void (*GTypePluginCompleteTypeInfo) (GTypePlugin *plugin, GType g_type, GTypeInfo *info, GTypeValueTable *value_table); +/** + * GTypePluginCompleteInterfaceInfo: + * @plugin: the #GTypePlugin + * @instance_type: the #GType of an instantiable type to which the interface + * is added + * @interface_type: the #GType of the interface whose info is completed + * @info: the #GInterfaceInfo to fill in + * + * The type of the @complete_interface_info function of #GTypePluginClass. + */ typedef void (*GTypePluginCompleteInterfaceInfo) (GTypePlugin *plugin, GType instance_type, GType interface_type, GInterfaceInfo *info); +/** + * GTypePlugin: + * + * The GTypePlugin typedef is used as a placeholder + * for objects that implement the GTypePlugin + * interface. + */ +/** + * GTypePluginClass: + * @use_plugin: Increases the use count of the plugin. + * @unuse_plugin: Decreases the use count of the plugin. + * @complete_type_info: Fills in the #GTypeInfo and + * #GTypeValueTable structs for the type. The structs are initialized + * with memset(s, 0, sizeof (s)) before calling + * this function. + * @complete_interface_info: Fills in missing parts of the #GInterfaceInfo + * for the interface. The structs is initialized with + * memset(s, 0, sizeof (s)) before calling + * this function. + * + * The #GTypePlugin interface is used by the type system in order to handle + * the lifecycle of dynamically loaded types. + */ struct _GTypePluginClass { /*< private >*/ -- cgit v1.2.3-70-g09d2