mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-01-12 07:26:15 +01:00
Migrating docs.
* docs/reference/gobject/tmpl/gtypeplugin.sgml: * gobject/gtypeplugin.c: * gobject/gtypeplugin.h: Migrating docs. svn path=/trunk/; revision=7079
This commit is contained in:
Stefan Kost
parent
f22d19fc34
commit
3f5419f6f1
@ -1,3 +1,10 @@
|
||||
2008-06-21 Stefan Kost <ensonic@users.sf.net>
|
||||
|
||||
* docs/reference/gobject/tmpl/gtypeplugin.sgml:
|
||||
* gobject/gtypeplugin.c:
|
||||
* gobject/gtypeplugin.h:
|
||||
Migrating docs.
|
||||
|
||||
2008-06-21 Stefan Kost <ensonic@users.sf.net>
|
||||
|
||||
* docs/reference/gobject/Makefile.am:
|
||||
@ -9,7 +16,7 @@
|
||||
* gobject/gparam.c:
|
||||
* gobject/gparam.h:
|
||||
* gobject/gtype.h:
|
||||
Convert character entities back. FIx some broken sgml.
|
||||
Convert character entities back. Fix some broken sgml.
|
||||
|
||||
2008-06-21 Stefan Kost <ensonic@users.sf.net>
|
||||
|
||||
|
||||
@ -1,187 +0,0 @@
|
||||
<!-- ##### SECTION Title ##### -->
|
||||
GTypePlugin
|
||||
|
||||
<!-- ##### SECTION Short_Description ##### -->
|
||||
An interface for dynamically loadable types
|
||||
|
||||
<!-- ##### SECTION Long_Description ##### -->
|
||||
<para>
|
||||
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:
|
||||
</para>
|
||||
<para>
|
||||
<orderedlist>
|
||||
<listitem><para>
|
||||
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:
|
||||
<literal>new_type_id = g_type_register_dynamic (parent_type_id,
|
||||
"TypeName",
|
||||
new_type_plugin,
|
||||
type_flags);
|
||||
</literal>
|
||||
where <literal>new_type_plugin</literal> is an implementation of the
|
||||
#GTypePlugin interface.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
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 <literal>new_type_id</literal>.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
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
|
||||
<literal>new_type_plugin</literal>.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
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).
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
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 <literal>new_type_plugin</literal>.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
Things may repeat from the second step.
|
||||
</para></listitem>
|
||||
</orderedlist>
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
#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.
|
||||
</para>
|
||||
|
||||
<!-- ##### SECTION See_Also ##### -->
|
||||
<para>
|
||||
#GTypeModule and g_type_register_dynamic().
|
||||
</para>
|
||||
|
||||
<!-- ##### SECTION Stability_Level ##### -->
|
||||
|
||||
|
||||
<!-- ##### STRUCT GTypePlugin ##### -->
|
||||
<para>
|
||||
The <structname>GTypePlugin</structname> typedef is used as a placeholder
|
||||
for objects that implement the <structname>GTypePlugin</structname>
|
||||
interface.
|
||||
</para>
|
||||
|
||||
|
||||
<!-- ##### STRUCT GTypePluginClass ##### -->
|
||||
<para>
|
||||
The #GTypePlugin interface is used by the type system in order to handle
|
||||
the lifecycle of dynamically loaded types.
|
||||
</para>
|
||||
|
||||
@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 <literal>memset(s, 0, sizeof (s))</literal> before calling
|
||||
this function.
|
||||
@complete_interface_info: Fills in missing parts of the #GInterfaceInfo
|
||||
for the interface. The structs is initialized with
|
||||
<literal>memset(s, 0, sizeof (s))</literal> before calling
|
||||
this function.
|
||||
|
||||
<!-- ##### USER_FUNCTION GTypePluginUse ##### -->
|
||||
<para>
|
||||
The type of the @use_plugin function of #GTypePluginClass, which gets called
|
||||
to increase the use count of @plugin.
|
||||
</para>
|
||||
|
||||
@plugin: the #GTypePlugin whose use count should be increased
|
||||
|
||||
|
||||
<!-- ##### USER_FUNCTION GTypePluginUnuse ##### -->
|
||||
<para>
|
||||
The type of the @unuse_plugin function of #GTypePluginClass.
|
||||
</para>
|
||||
|
||||
@plugin: the #GTypePlugin whose use count should be decreased
|
||||
|
||||
|
||||
<!-- ##### USER_FUNCTION GTypePluginCompleteTypeInfo ##### -->
|
||||
<para>
|
||||
The type of the @complete_type_info function of #GTypePluginClass.
|
||||
</para>
|
||||
|
||||
@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
|
||||
|
||||
|
||||
<!-- ##### USER_FUNCTION GTypePluginCompleteInterfaceInfo ##### -->
|
||||
<para>
|
||||
The type of the @complete_interface_info function of #GTypePluginClass.
|
||||
</para>
|
||||
|
||||
@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
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_type_plugin_use ##### -->
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
@plugin: a #GTypePlugin
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_type_plugin_unuse ##### -->
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
@plugin: a #GTypePlugin
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_type_plugin_complete_type_info ##### -->
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
@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
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_type_plugin_complete_interface_info ##### -->
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
@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
|
||||
|
||||
|
||||
@ -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:
|
||||
*
|
||||
* <orderedlist>
|
||||
* <listitem><para>
|
||||
* 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 <literal>new_type_plugin</literal> is an implementation of the
|
||||
* #GTypePlugin interface.
|
||||
* </para></listitem>
|
||||
* <listitem><para>
|
||||
* 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 <literal>new_type_id</literal>.
|
||||
* </para></listitem>
|
||||
* <listitem><para>
|
||||
* 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
|
||||
* <literal>new_type_plugin</literal>.
|
||||
* </para></listitem>
|
||||
* <listitem><para>
|
||||
* 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).
|
||||
* </para></listitem>
|
||||
* <listitem><para>
|
||||
* 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 <literal>new_type_plugin</literal>.
|
||||
* </para></listitem>
|
||||
* <listitem><para>
|
||||
* Things may repeat from the second step.
|
||||
* </para></listitem>
|
||||
* </orderedlist>
|
||||
*
|
||||
* 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,
|
||||
|
||||
@ -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 <structname>GTypePlugin</structname> typedef is used as a placeholder
|
||||
* for objects that implement the <structname>GTypePlugin</structname>
|
||||
* 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 <literal>memset(s, 0, sizeof (s))</literal> before calling
|
||||
* this function.
|
||||
* @complete_interface_info: Fills in missing parts of the #GInterfaceInfo
|
||||
* for the interface. The structs is initialized with
|
||||
* <literal>memset(s, 0, sizeof (s))</literal> 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 >*/
|
||||
|
||||
Loading…
Reference in New Issue
Block a user