From: Stefan Kost Date: Sat, 21 Jun 2008 16:35:50 +0000 (+0000) Subject: Migrating docs. X-Git-Tag: GLIB_2_17_3~53 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=f2da2e8e92bb7b03a227fcc2a387b07a60db1b2b;p=platform%2Fupstream%2Fglib.git Migrating docs. * docs/reference/gobject/tmpl/gtypemodule.sgml: * gobject/gtypemodule.c: * gobject/gtypemodule.h: Migrating docs. svn path=/trunk/; revision=7077 --- diff --git a/ChangeLog b/ChangeLog index 8fda23f..690fcdb 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,12 @@ 2008-06-21 Stefan Kost + * docs/reference/gobject/tmpl/gtypemodule.sgml: + * gobject/gtypemodule.c: + * gobject/gtypemodule.h: + Migrating docs. + +2008-06-21 Stefan Kost + * gobject/gboxed.c: * gobject/gclosure.c: * gobject/genums.c: diff --git a/docs/reference/gobject/tmpl/gtypemodule.sgml b/docs/reference/gobject/tmpl/gtypemodule.sgml deleted file mode 100644 index 8c46f67..0000000 --- a/docs/reference/gobject/tmpl/gtypemodule.sgml +++ /dev/null @@ -1,286 +0,0 @@ - -GTypeModule - - -Type loading modules - - - -#GTypeModule provides a simple implementation of the #GTypePlugin -interface. The model of #GTypeModule is a dynamically loaded module -which implements some number of types and interface -implementations. When the module is loaded, it registers its types -and interfaces using g_type_module_register_type() and -g_type_module_add_interface(). As long as any instances of these -types and interface implementations are in use, the module is kept -loaded. When the types and interfaces are gone, the module may be -unloaded. If the types and interfaces become used again, the module -will be reloaded. Note that the last unref can not happen in module -code, since that would lead to the caller's code being unloaded before -g_object_unref() returns to it. - - -Keeping track of whether the module should be loaded or not is done by -using a use count - it starts at zero, and whenever it is greater than -zero, the module is loaded. The use count is maintained internally by -the type system, but also can be explicitly controlled by -g_type_module_use() and g_type_module_unuse(). Typically, when loading -a module for the first type, g_type_module_use() will be used to load -it so that it can initialize its types. At some later point, when the -module no longer needs to be loaded except for the type -implementations it contains, g_type_module_unuse() is called. - - -#GTypeModule does not actually provide any implementation of module -loading and unloading. To create a particular module type you must -derive from #GTypeModule and implement the load and unload functions -in #GTypeModuleClass. - - - - - - - -#GTypePlugin -The abstract type loader interface. - - - -#GModule -Portable mechanism for dynamically loaded modules. - - - - - - - - - - -The members of the GTypeModule structure should not -be accessed directly, except for the @name field. - - -@name: the name of the module - - - -In order to implement dynamic loading of types based on #GTypeModule, -the @load and @unload functions in #GTypeModuleClass must be implemented. - - -@parent_class: the parent class -@load: loads the module and registers one or more types using - g_type_module_register_type(). -@unload: unloads the module - - - -Increases the use count of a #GTypeModule by one. If the -use count was zero before, the plugin will be loaded. - - -@module: a #GTypeModule -@Returns: %FALSE if the plugin needed to be loaded and - loading the plugin failed. - - - - -Decreases the use count of a #GTypeModule by one. If the -result is zero, the module will be unloaded. (However, the -#GTypeModule will not be freed, and types associated with the -#GTypeModule are not unregistered. Once a #GTypeModule is -initialized, it must exist forever.) - - -@module: a #GTypeModule - - - - -Sets the name for a #GTypeModule - - -@module: a #GTypeModule. -@name: a human-readable name to use in error messages. - - - - -Looks up or registers a type that is implemented with a particular -type plugin. If a type with name @type_name was previously registered, -the #GType identifier for the type is returned, otherwise the type -is newly registered, and the resulting #GType identifier returned. - - -When reregistering a type (typically because a module is unloaded -then reloaded, and reinitialized), @module and @parent_type must -be the same as they were previously. - - -As long as any instances of the type exist, the type plugin will -not be unloaded. - - -@module: a #GTypeModule -@parent_type: the type for the parent class -@type_name: name for the type -@type_info: type information structure -@flags: flags field providing details about the type -@Returns: the new or existing type ID - - - - -Registers an additional interface for a type, whose interface -lives in the given type plugin. If the interface was already registered -for the type in this plugin, nothing will be done. - - -As long as any instances of the type exist, the type plugin will -not be unloaded. - - -@module: a #GTypeModule -@instance_type: type to which to add the interface. -@interface_type: interface type to add -@interface_info: type information structure - - - - -Looks up or registers an enumeration that is implemented with a particular -type plugin. If a type with name @type_name was previously registered, -the #GType identifier for the type is returned, otherwise the type -is newly registered, and the resulting #GType identifier returned. - - -As long as any instances of the type exist, the type plugin will -not be unloaded. - - -@module: a #GTypeModule -@name: name for the type -@const_static_values: an array of #GEnumValue structs for the possible - enumeration values. The array is terminated by a struct with all - members being 0. -@Returns: the new or existing type ID -@Since: 2.6 - - - - -Looks up or registers a flags type that is implemented with a particular -type plugin. If a type with name @type_name was previously registered, -the #GType identifier for the type is returned, otherwise the type -is newly registered, and the resulting #GType identifier returned. - - -As long as any instances of the type exist, the type plugin will -not be unloaded. - - -@module: a #GTypeModule -@name: name for the type -@const_static_values: an array of #GFlagsValue structs for the possible - flags values. The array is terminated by a struct with all - members being 0. -@Returns: the new or existing type ID -@Since: 2.6 - - - - -A convenience macro for dynamic type implementations, which declares a -class initialization function, an instance initialization function (see -#GTypeInfo for information about these) and a static variable named -@t_n_parent_class pointing to the parent class. Furthermore, -it defines a *_get_type() and a static -*_register_type() function for use in your -module_init(). -See G_DEFINE_DYNAMIC_TYPE_EXTENDED() for an example. - - -@TN: The name of the new type, in Camel case. -@t_n: The name of the new type, in lowercase, with words - separated by '_'. -@T_P: The #GType of the parent type. -@Since: 2.14 - - - - -A more general version of G_DEFINE_DYNAMIC_TYPE() which -allows to specify #GTypeFlags and custom code. - - -G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget, - gtk_gadget, - GTK_TYPE_THING, - 0, - G_IMPLEMENT_INTERFACE (TYPE_GIZMO, - gtk_gadget_gizmo_init)); - -expands to - -static void gtk_gadget_init (GtkGadget *self); -static void gtk_gadget_class_init (GtkGadgetClass *klass); -static void gtk_gadget_class_finalize (GtkGadgetClass *klass); - -static gpointer gtk_gadget_parent_class = NULL; -static GType gtk_gadget_type_id = 0; - -static void gtk_gadget_class_intern_init (gpointer klass) -{ - gtk_gadget_parent_class = g_type_class_peek_parent (klass); - gtk_gadget_class_init ((GtkGadgetClass*) klass); -} - -GType -gtk_gadget_get_type (void) -{ - return gtk_gadget_type_id; -} - -static void -gtk_gadget_register_type (GTypeModule *type_module) -{ - const GTypeInfo g_define_type_info = { - sizeof (GtkGadgetClass), - (GBaseInitFunc) NULL, - (GBaseFinalizeFunc) NULL, - (GClassInitFunc) gtk_gadget_class_intern_init, - (GClassFinalizeFunc) gtk_gadget_class_finalize, - NULL, /* class_data */ - sizeof (GtkGadget), - 0, /* n_preallocs */ - (GInstanceInitFunc) gtk_gadget_init, - NULL /* value_table */ - }; - gtk_gadget_type_id = g_type_module_register_type (type_module, - GTK_TYPE_THING, - GtkGadget, - &g_define_type_info, - (GTypeFlags) flags); - { - const GInterfaceInfo g_implement_interface_info = { - (GInterfaceInitFunc) gtk_gadget_gizmo_init - }; - g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info); - } -} - - - -@TypeName: The name of the new type, in Camel case. -@type_name: The name of the new type, in lowercase, with words - separated by '_'. -@TYPE_PARENT: The #GType of the parent type. -@flags: #GTypeFlags to pass to g_type_module_register_type() -@CODE: Custom code that gets inserted in the *_get_type() function. -@Since: 2.14 - - diff --git a/gobject/gtypemodule.c b/gobject/gtypemodule.c index 47e5247..94b8e09 100644 --- a/gobject/gtypemodule.c +++ b/gobject/gtypemodule.c @@ -16,6 +16,49 @@ * Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. */ +/** + * SECTION:gtypemodule + * @Short_description: Type loading modules + * @See_also: + * + * #GTypePlugin + * The abstract type loader interface. + * + * + * #GModule + * Portable mechanism for dynamically loaded modules. + * + * + * @Title: GTypeModule + * + * #GTypeModule provides a simple implementation of the #GTypePlugin + * interface. The model of #GTypeModule is a dynamically loaded module + * which implements some number of types and interface + * implementations. When the module is loaded, it registers its types + * and interfaces using g_type_module_register_type() and + * g_type_module_add_interface(). As long as any instances of these + * types and interface implementations are in use, the module is kept + * loaded. When the types and interfaces are gone, the module may be + * unloaded. If the types and interfaces become used again, the module + * will be reloaded. Note that the last unref can not happen in module + * code, since that would lead to the caller's code being unloaded before + * g_object_unref() returns to it. + * + * Keeping track of whether the module should be loaded or not is done by + * using a use count - it starts at zero, and whenever it is greater than + * zero, the module is loaded. The use count is maintained internally by + * the type system, but also can be explicitly controlled by + * g_type_module_use() and g_type_module_unuse(). Typically, when loading + * a module for the first type, g_type_module_use() will be used to load + * it so that it can initialize its types. At some later point, when the + * module no longer needs to be loaded except for the type + * implementations it contains, g_type_module_unuse() is called. + * + * #GTypeModule does not actually provide any implementation of module + * loading and unloading. To create a particular module type you must + * derive from #GTypeModule and implement the load and unload functions + * in #GTypeModuleClass. + */ #include @@ -131,6 +174,13 @@ g_type_module_get_type (void) return type_module_type; } +/** + * g_type_module_set_name: + * @module: a #GTypeModule. + * @name: a human-readable name to use in error messages. + * + * Sets the name for a #GTypeModule + */ void g_type_module_set_name (GTypeModule *module, const gchar *name) @@ -177,6 +227,16 @@ g_type_module_find_interface_info (GTypeModule *module, return NULL; } +/** + * g_type_module_use: + * @module: a #GTypeModule + * + * Increases the use count of a #GTypeModule by one. If the + * use count was zero before, the plugin will be loaded. + * + * Returns: %FALSE if the plugin needed to be loaded and + * loading the plugin failed. + */ gboolean g_type_module_use (GTypeModule *module) { @@ -212,6 +272,16 @@ g_type_module_use (GTypeModule *module) return TRUE; } +/** + * g_type_module_unuse: + * @module: a #GTypeModule + * + * Decreases the use count of a #GTypeModule by one. If the + * result is zero, the module will be unloaded. (However, the + * #GTypeModule will not be freed, and types associated with the + * #GTypeModule are not unregistered. Once a #GTypeModule is + * initialized, it must exist forever.) + */ void g_type_module_unuse (GTypeModule *module) { @@ -277,6 +347,28 @@ g_type_module_complete_interface_info (GTypePlugin *plugin, *info = module_interface_info->info; } +/** + * g_type_module_register_type: + * @module: a #GTypeModule + * @parent_type: the type for the parent class + * @type_name: name for the type + * @type_info: type information structure + * @flags: flags field providing details about the type + * + * Looks up or registers a type that is implemented with a particular + * type plugin. If a type with name @type_name was previously registered, + * the #GType identifier for the type is returned, otherwise the type + * is newly registered, and the resulting #GType identifier returned. + * + * When reregistering a type (typically because a module is unloaded + * then reloaded, and reinitialized), @module and @parent_type must + * be the same as they were previously. + * + * As long as any instances of the type exist, the type plugin will + * not be unloaded. + * + * Returns: the new or existing type ID + */ GType g_type_module_register_type (GTypeModule *module, GType parent_type, @@ -340,6 +432,20 @@ g_type_module_register_type (GTypeModule *module, return module_type_info->type; } +/** + * g_type_module_add_interface: + * @module: a #GTypeModule + * @instance_type: type to which to add the interface. + * @interface_type: interface type to add + * @interface_info: type information structure + * + * Registers an additional interface for a type, whose interface + * lives in the given type plugin. If the interface was already registered + * for the type in this plugin, nothing will be done. + * + * As long as any instances of the type exist, the type plugin will + * not be unloaded. + */ void g_type_module_add_interface (GTypeModule *module, GType instance_type, @@ -389,6 +495,25 @@ g_type_module_add_interface (GTypeModule *module, module_interface_info->info = *interface_info; } +/** + * g_type_module_register_enum: + * @module: a #GTypeModule + * @name: name for the type + * @const_static_values: an array of #GEnumValue structs for the possible + * enumeration values. The array is terminated by a struct with all + * members being 0. + * + * Looks up or registers an enumeration that is implemented with a particular + * type plugin. If a type with name @type_name was previously registered, + * the #GType identifier for the type is returned, otherwise the type + * is newly registered, and the resulting #GType identifier returned. + * + * As long as any instances of the type exist, the type plugin will + * not be unloaded. + * + * Since: 2.6 + * Returns: the new or existing type ID + */ GType g_type_module_register_enum (GTypeModule *module, const gchar *name, @@ -407,6 +532,25 @@ g_type_module_register_enum (GTypeModule *module, G_TYPE_ENUM, name, &enum_type_info, 0); } +/** + * g_type_module_register_flags: + * @module: a #GTypeModule + * @name: name for the type + * @const_static_values: an array of #GFlagsValue structs for the possible + * flags values. The array is terminated by a struct with all + * members being 0. + * + * Looks up or registers a flags type that is implemented with a particular + * type plugin. If a type with name @type_name was previously registered, + * the #GType identifier for the type is returned, otherwise the type + * is newly registered, and the resulting #GType identifier returned. + * + * As long as any instances of the type exist, the type plugin will + * not be unloaded. + * + * Since: 2.6 + * Returns: the new or existing type ID + */ GType g_type_module_register_flags (GTypeModule *module, const gchar *name, diff --git a/gobject/gtypemodule.h b/gobject/gtypemodule.h index 46858f5..a7c3cf9 100644 --- a/gobject/gtypemodule.h +++ b/gobject/gtypemodule.h @@ -38,6 +38,13 @@ typedef struct _GTypeModuleClass GTypeModuleClass; #define G_IS_TYPE_MODULE_CLASS(class) (G_TYPE_CHECK_CLASS_TYPE ((class), G_TYPE_TYPE_MODULE)) #define G_TYPE_MODULE_GET_CLASS(module) (G_TYPE_INSTANCE_GET_CLASS ((module), G_TYPE_TYPE_MODULE, GTypeModuleClass)) +/** + * GTypeModule: + * @name: the name of the module + * + * The members of the GTypeModule structure should not + * be accessed directly, except for the @name field. + */ struct _GTypeModule { GObject parent_instance; @@ -50,6 +57,16 @@ struct _GTypeModule gchar *name; }; +/** + * GTypeModuleClass: + * @parent_class: the parent class + * @load: loads the module and registers one or more types using + * g_type_module_register_type(). + * @unload: unloads the module + * + * In order to implement dynamic loading of types based on #GTypeModule, + * the @load and @unload functions in #GTypeModuleClass must be implemented. + */ struct _GTypeModuleClass { GObjectClass parent_class; @@ -66,7 +83,97 @@ struct _GTypeModuleClass void (*reserved4) (void); }; +/** + * G_DEFINE_DYNAMIC_TYPE: + * @TN: The name of the new type, in Camel case. + * @t_n: The name of the new type, in lowercase, with words + * separated by '_'. + * @T_P: The #GType of the parent type. + * + * A convenience macro for dynamic type implementations, which declares a + * class initialization function, an instance initialization function (see + * #GTypeInfo for information about these) and a static variable named + * @t_n_parent_class pointing to the parent class. Furthermore, + * it defines a *_get_type() and a static + * *_register_type() function for use in your + * module_init(). + * See G_DEFINE_DYNAMIC_TYPE_EXTENDED() for an example. + * + * Since: 2.14 + */ #define G_DEFINE_DYNAMIC_TYPE(TN, t_n, T_P) G_DEFINE_DYNAMIC_TYPE_EXTENDED (TN, t_n, T_P, 0, {}) +/** + * G_DEFINE_DYNAMIC_TYPE_EXTENDED: + * @TypeName: The name of the new type, in Camel case. + * @type_name: The name of the new type, in lowercase, with words + * separated by '_'. + * @TYPE_PARENT: The #GType of the parent type. + * @flags: #GTypeFlags to pass to g_type_module_register_type() + * @CODE: Custom code that gets inserted in the *_get_type() function. + * + * A more general version of G_DEFINE_DYNAMIC_TYPE() which + * allows to specify #GTypeFlags and custom code. + * + * |[ + * G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget, + * gtk_gadget, + * GTK_TYPE_THING, + * 0, + * G_IMPLEMENT_INTERFACE (TYPE_GIZMO, + * gtk_gadget_gizmo_init)); + * ]| + * expands to + * |[ + * static void gtk_gadget_init (GtkGadget *self); + * static void gtk_gadget_class_init (GtkGadgetClass *klass); + * static void gtk_gadget_class_finalize (GtkGadgetClass *klass); + * + * static gpointer gtk_gadget_parent_class = NULL; + * static GType gtk_gadget_type_id = 0; + * + * static void gtk_gadget_class_intern_init (gpointer klass) + * { + * gtk_gadget_parent_class = g_type_class_peek_parent (klass); + * gtk_gadget_class_init ((GtkGadgetClass*) klass); + * } + * + * GType + * gtk_gadget_get_type (void) + * { + * return gtk_gadget_type_id; + * } + * + * static void + * gtk_gadget_register_type (GTypeModule *type_module) + * { + * const GTypeInfo g_define_type_info = { + * sizeof (GtkGadgetClass), + * (GBaseInitFunc) NULL, + * (GBaseFinalizeFunc) NULL, + * (GClassInitFunc) gtk_gadget_class_intern_init, + * (GClassFinalizeFunc) gtk_gadget_class_finalize, + * NULL, // class_data + * sizeof (GtkGadget), + * 0, // n_preallocs + * (GInstanceInitFunc) gtk_gadget_init, + * NULL // value_table + * }; + * gtk_gadget_type_id = g_type_module_register_type (type_module, + * GTK_TYPE_THING, + * GtkGadget, + * &g_define_type_info, + * (GTypeFlags) flags); + * { + * const GInterfaceInfo g_implement_interface_info = { + * (GInterfaceInitFunc) gtk_gadget_gizmo_init + * }; + * g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info); + * } + * } + * ]| + * + * Since: 2.14 + */ #define G_DEFINE_DYNAMIC_TYPE_EXTENDED(TypeName, type_name, TYPE_PARENT, flags, CODE) \ static void type_name##_init (TypeName *self); \ static void type_name##_class_init (TypeName##Class *klass); \