1 <?xml version='1.0' encoding="ISO-8859-1"?>
2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
5 <chapter id="chapter-gtype">
6 <title>The GLib Dynamic Type System</title>
9 A type, as manipulated by the GLib type system, is much more generic than what
10 is usually understood as an Object type. It is best explained by looking at the
11 structure and the functions used to register new types in the type system.
13 typedef struct _GTypeInfo GTypeInfo;
16 /* interface types, classed types, instantiated types */
19 GBaseInitFunc base_init;
20 GBaseFinalizeFunc base_finalize;
22 /* classed types, instantiated types */
23 GClassInitFunc class_init;
24 GClassFinalizeFunc class_finalize;
25 gconstpointer class_data;
27 /* instantiated types */
28 guint16 instance_size;
30 GInstanceInitFunc instance_init;
33 const GTypeValueTable *value_table;
35 GType g_type_register_static (GType parent_type,
36 const gchar *type_name,
37 const GTypeInfo *info,
39 GType g_type_register_fundamental (GType type_id,
40 const gchar *type_name,
41 const GTypeInfo *info,
42 const GTypeFundamentalInfo *finfo,
48 <function><link linkend="g-type-register-static">g_type_register_static</link></function> and
49 <function><link linkend="g-type-register-fundamental">g_type_register_fundamental</link></function>
50 are the C functions, defined in
51 <filename>gtype.h</filename> and implemented in <filename>gtype.c</filename>
52 which you should use to register a new <link linkend="GType"><type>GType</type></link> in the program's type system.
53 It is not likely you will ever need to use
54 <function><link linkend="g-type-register-fundamental">g_type_register_fundamental</link></function> (you have to be Tim Janik
55 to do that) but in case you want to, the last chapter explains how to create
56 new fundamental types.
59 Please note that there exists another registration function: the
60 <function><link linkend="g-type-register-dynamic">g_type_register_dynamic</link></function>. We will not discuss this
61 function here since its use is very similar to the <function>_static</function>
68 Fundamental types are top-level types which do not derive from any other type
69 while other non-fundamental types derive from other types.
70 Upon initialization, the type system not only initializes its
71 internal data structures but it also registers a number of core
72 types: some of these are fundamental types. Others are types derived from these
77 Fundamental and non-fundamental types are defined by:
80 class size: the class_size field in <link linkend="GTypeInfo"><type>GTypeInfo</type></link>.
83 class initialization functions (C++ constructor): the base_init and
84 class_init fields in <link linkend="GTypeInfo"><type>GTypeInfo</type></link>.
87 class destruction functions (C++ destructor): the base_finalize and
88 class_finalize fields in <link linkend="GTypeInfo"><type>GTypeInfo</type></link>.
91 instance size (C++ parameter to new): the instance_size field in
92 <link linkend="GTypeInfo"><type>GTypeInfo</type></link>.
95 instantiation policy (C++ type of new operator): the n_preallocs
96 field in <link linkend="GTypeInfo"><type>GTypeInfo</type></link>.
99 copy functions (C++ copy operators): the value_table field in
100 <link linkend="GTypeInfo"><type>GTypeInfo</type></link>.
103 type characteristic flags: <link linkend="GTypeFlags"><type>GTypeFlags</type></link>.
106 Fundamental types are also defined by a set of <link linkend="GTypeFundamentalFlags"><type>GTypeFundamentalFlags</type></link>
107 which are stored in a <link linkend="GTypeFundamentalInfo"><type>GTypeFundamentalInfo</type></link>.
108 Non-fundamental types are furthermore defined by the type of their parent which is
109 passed as the parent_type parameter to <function><link linkend="g-type-register-static">g_type_register_static</link></function>
110 and <function><link linkend="g-type-register-dynamic">g_type_register_dynamic</link></function>.
113 <sect1 id="gtype-copy">
114 <title>Copy functions</title>
117 The major common point between <emphasis>all</emphasis> GLib types (fundamental and
118 non-fundamental, classed and non-classed, instantiable and non-instantiable) is that
119 they can all be manipulated through a single API to copy/assign them.
123 The <link linkend="GValue"><type>GValue</type></link> structure is used as an abstract container for all of these
124 types. Its simplistic API (defined in <filename>gobject/gvalue.h</filename>) can be
125 used to invoke the value_table functions registered
126 during type registration: for example <function><link linkend="g-value-copy">g_value_copy</link></function> copies the
127 content of a <link linkend="GValue"><type>GValue</type></link> to another <link linkend="GValue"><type>GValue</type></link>. This is similar
128 to a C++ assignment which invokes the C++ copy operator to modify the default
129 bit-by-bit copy semantics of C++/C structures/classes.
133 The following code shows how you can copy around a 64 bit integer, as well as a <link linkend="GObject"><type>GObject</type></link>
134 instance pointer (sample code for this is located in the source tarball for this document in
135 <filename>sample/gtype/test.c</filename>):
137 static void test_int (void)
139 GValue a_value = G_VALUE_INIT;
140 GValue b_value = G_VALUE_INIT;
145 g_value_init (&a_value, G_TYPE_UINT64);
146 g_value_set_uint64 (&a_value, a);
148 g_value_init (&b_value, G_TYPE_UINT64);
149 g_value_copy (&a_value, &b_value);
151 b = g_value_get_uint64 (&b_value);
154 g_print ("Yay !! 10 lines of code to copy around a uint64.\n");
156 g_print ("Are you sure this is not a Z80 ?\n");
160 static void test_object (void)
163 GValue obj_vala = G_VALUE_INIT;
164 GValue obj_valb = G_VALUE_INIT;
165 obj = g_object_new (MAMAN_TYPE_BAR, NULL);
167 g_value_init (&obj_vala, MAMAN_TYPE_BAR);
168 g_value_set_object (&obj_vala, obj);
170 g_value_init (&obj_valb, G_TYPE_OBJECT);
172 /* g_value_copy's semantics for G_TYPE_OBJECT types is to copy the reference.
173 This function thus calls g_object_ref.
174 It is interesting to note that the assignment works here because
175 MAMAN_TYPE_BAR is a G_TYPE_OBJECT.
177 g_value_copy (&obj_vala, &obj_valb);
179 g_object_unref (G_OBJECT (obj));
180 g_object_unref (G_OBJECT (obj));
183 The important point about the above code is that the exact semantics of the copy calls
184 is undefined since they depend on the implementation of the copy function. Certain
185 copy functions might decide to allocate a new chunk of memory and then to copy the
186 data from the source to the destination. Others might want to simply increment
187 the reference count of the instance and copy the reference to the new GValue.
191 The value_table used to specify these assignment functions is defined in
192 <filename>gtype.h</filename> and is thoroughly described in the
193 API documentation provided with GObject (for once ;-) which is why we will
194 not detail its exact semantics.
196 typedef struct _GTypeValueTable GTypeValueTable;
197 struct _GTypeValueTable
199 void (*value_init) (GValue *value);
200 void (*value_free) (GValue *value);
201 void (*value_copy) (const GValue *src_value,
203 /* varargs functionality (optional) */
204 gpointer (*value_peek_pointer) (const GValue *value);
205 gchar *collect_format;
206 gchar* (*collect_value) (GValue *value,
207 guint n_collect_values,
208 GTypeCValue *collect_values,
209 guint collect_flags);
211 gchar* (*lcopy_value) (const GValue *value,
212 guint n_collect_values,
213 GTypeCValue *collect_values,
214 guint collect_flags);
217 Interestingly, it is also very unlikely
218 you will ever need to specify a value_table during type registration
219 because these value_tables are inherited from the parent types for
220 non-fundamental types which means that unless you want to write a
221 fundamental type (not a great idea!), you will not need to provide
222 a new value_table since you will inherit the value_table structure
223 from your parent type.
227 <sect1 id="gtype-conventions">
228 <title>Conventions</title>
232 There are a number of conventions users are expected to follow when creating new types
233 which are to be exported in a header file:
236 Use the <function>object_method</function> pattern for function names: to invoke
237 the method named foo on an instance of object type bar, call
238 <function>bar_foo</function>.
240 <listitem><para>Use prefixing to avoid namespace conflicts with other projects.
241 If your library (or application) is named <emphasis>Maman</emphasis>,
244 <emphasis>Maman</emphasis> is the French word for <emphasis>mum</emphasis>
245 or <emphasis>mother</emphasis> - nothing more and nothing less.
249 prefix all your function names with <emphasis>maman_</emphasis>.
250 For example: <function>maman_object_method</function>.
252 <listitem><para>Create a macro named <function>PREFIX_TYPE_OBJECT</function> which always
253 returns the GType for the associated object type. For an object of type
254 <emphasis>Bar</emphasis> in a library prefixed by <emphasis>maman</emphasis>,
255 use: <function>MAMAN_TYPE_BAR</function>.
256 It is common although not a convention to implement this macro using either a global
257 static variable or a function named <function>prefix_object_get_type</function>.
258 We will follow the function pattern wherever possible in this document.
260 <listitem><para>Create a macro named <function>PREFIX_OBJECT (obj)</function> which
261 returns a pointer of type <type>PrefixObject</type>. This macro is used to enforce
262 static type safety by doing explicit casts wherever needed. It also enforces
263 dynamic type safety by doing runtime checks. It is possible to disable the dynamic
264 type checks in production builds (see <link linkend="glib-building">building glib</link>).
265 For example, we would create
266 <function>MAMAN_BAR (obj)</function> to keep the previous example.
268 <listitem><para>If the type is classed, create a macro named
269 <function>PREFIX_OBJECT_CLASS (klass)</function>. This macro
270 is strictly equivalent to the previous casting macro: it does static casting with
271 dynamic type checking of class structures. It is expected to return a pointer
272 to a class structure of type <type>PrefixObjectClass</type>. Again, an example is:
273 <function>MAMAN_BAR_CLASS</function>.
275 <listitem><para>Create a macro named <function>PREFIX_IS_BAR (obj)</function>: this macro is expected
276 to return a <type>gboolean</type> which indicates whether or not the input
277 object instance pointer of type BAR.
279 <listitem><para>If the type is classed, create a macro named
280 <function>PREFIX_IS_OBJECT_CLASS (klass)</function> which, as above, returns a boolean
281 if the input class pointer is a pointer to a class of type OBJECT.
283 <listitem><para>If the type is classed, create a macro named
284 <function>PREFIX_OBJECT_GET_CLASS (obj)</function>
285 which returns the class pointer associated to an instance of a given type. This macro
286 is used for static and dynamic type safety purposes (just like the previous casting
290 The implementation of these macros is pretty straightforward: a number of simple-to-use
291 macros are provided in <filename>gtype.h</filename>. For the example we used above, we would
292 write the following trivial code to declare the macros:
294 #define MAMAN_TYPE_BAR (maman_bar_get_type ())
295 #define MAMAN_BAR(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), MAMAN_TYPE_BAR, MamanBar))
296 #define MAMAN_BAR_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), MAMAN_TYPE_BAR, MamanBarClass))
297 #define MAMAN_IS_BAR(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), MAMAN_TYPE_BAR))
298 #define MAMAN_IS_BAR_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), MAMAN_TYPE_BAR))
299 #define MAMAN_BAR_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), MAMAN_TYPE_BAR, MamanBarClass))
301 <note><simpara>Stick to the naming <varname>klass</varname> as <varname>class</varname> is a registered c++ keyword.</simpara></note>
305 The following code shows how to implement the <function>maman_bar_get_type</function>
308 GType maman_bar_get_type (void)
310 static GType type = 0;
312 const GTypeInfo info = {
313 /* You fill this structure. */
315 type = g_type_register_static (G_TYPE_OBJECT,
325 If you have no special requirements you can use the
326 <function><link linkend="G-DEFINE-TYPE:CAPS">G_DEFINE_TYPE</link></function>
327 macro to define a class:
329 G_DEFINE_TYPE (MamanBar, maman_bar, G_TYPE_OBJECT)
335 <sect1 id="gtype-non-instantiable">
336 <title>Non-instantiable non-classed fundamental types</title>
339 A lot of types are not instantiable by the type system and do not have
340 a class. Most of these types are fundamental trivial types such as <emphasis>gchar</emphasis>,
341 registered in <function>_g_value_types_init</function> (in <filename>gvaluetypes.c</filename>).
345 To register such a type in the type system, you just need to fill the
346 <link linkend="GTypeInfo"><type>GTypeInfo</type></link> structure with zeros since these types are also most of the time
351 NULL, /* base_init */
352 NULL, /* base_destroy */
353 NULL, /* class_init */
354 NULL, /* class_destroy */
355 NULL, /* class_data */
356 0, /* instance_size */
358 NULL, /* instance_init */
359 NULL, /* value_table */
361 static const GTypeValueTable value_table = {
362 value_init_long0, /* value_init */
363 NULL, /* value_free */
364 value_copy_long0, /* value_copy */
365 NULL, /* value_peek_pointer */
366 "i", /* collect_format */
367 value_collect_int, /* collect_value */
368 "p", /* lcopy_format */
369 value_lcopy_char, /* lcopy_value */
371 info.value_table = &value_table;
372 type = g_type_register_fundamental (G_TYPE_CHAR, "gchar", &info, &finfo, 0);
378 Having non-instantiable types might seem a bit useless: what good is a type
379 if you cannot instantiate an instance of that type ? Most of these types
380 are used in conjunction with <link linkend="GValue"><type>GValue</type></link>s: a GValue is initialized
381 with an integer or a string and it is passed around by using the registered
382 type's value_table. <link linkend="GValue"><type>GValue</type></link>s (and by extension these trivial fundamental
383 types) are most useful when used in conjunction with object properties and signals.
388 <sect1 id="gtype-instantiable-classed">
389 <title>Instantiable classed types: objects</title>
392 Types which are registered with a class and are declared instantiable are
393 what most closely resembles an <emphasis>object</emphasis>.
394 Although <link linkend="GObject"><type>GObject</type></link>s (detailed in <xref linkend="chapter-gobject"/>)
395 are the most well known type of instantiable
396 classed types, other kinds of similar objects used as the base of an inheritance
397 hierarchy have been externally developed and they are all built on the fundamental
398 features described below.
402 For example, the code below shows how you could register
403 such a fundamental object type in the type system:
407 /* instance members */
414 void (*do_action_public_virtual) (MamanBar *self, guint8 i);
416 void (*do_action_public_pure_virtual) (MamanBar *self, guint8 i);
419 #define MAMAN_TYPE_BAR (maman_bar_get_type ())
422 maman_bar_get_type (void)
424 static GType type = 0;
426 const GTypeInfo info = {
427 sizeof (MamanBarClass),
428 NULL, /* base_init */
429 NULL, /* base_finalize */
430 (GClassInitFunc) foo_class_init,
431 NULL, /* class_finalize */
432 NULL, /* class_data */
435 (GInstanceInitFunc) NULL /* instance_init */
437 type = g_type_register_static (G_TYPE_OBJECT,
444 Upon the first call to <function>maman_bar_get_type</function>, the type named
445 <emphasis>BarType</emphasis> will be registered in the type system as inheriting
446 from the type <emphasis>G_TYPE_OBJECT</emphasis>.
450 Every object must define two structures: its class structure and its
451 instance structure. All class structures must contain as first member
452 a <link linkend="GTypeClass"><type>GTypeClass</type></link> structure. All instance structures must contain as first
453 member a <link linkend="GTypeInstance"><type>GTypeInstance</type></link> structure. The declaration of these C types,
454 coming from <filename>gtype.h</filename> is shown below:
460 struct _GTypeInstance
465 These constraints allow the type system to make sure that every object instance
466 (identified by a pointer to the object's instance structure) contains in its
467 first bytes a pointer to the object's class structure.
470 This relationship is best explained by an example: let's take object B which
471 inherits from object A:
475 GTypeInstance parent;
480 GTypeClass parent_class;
481 void (*method_a) (void);
482 void (*method_b) (void);
493 void (*method_c) (void);
494 void (*method_d) (void);
497 The C standard mandates that the first field of a C structure is stored starting
498 in the first byte of the buffer used to hold the structure's fields in memory.
499 This means that the first field of an instance of an object B is A's first field
500 which in turn is GTypeInstance's first field which in turn is g_class, a pointer
501 to B's class structure.
505 Thanks to these simple conditions, it is possible to detect the type of every
506 object instance by doing:
509 b->parent.parent.g_class->g_type
514 ((GTypeInstance*)b)->g_class->g_type
518 <sect2 id="gtype-instantiable-classed-init-done">
519 <title>Initialization and Destruction</title>
522 instantiation of these types can be done with
523 <function><link linkend="g-type-create-instance">g_type_create_instance</link></function>:
525 GTypeInstance* g_type_create_instance (GType type);
526 void g_type_free_instance (GTypeInstance *instance);
528 <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> will look up the type information
529 structure associated to the type requested. Then, the instance size and instantiation
530 policy (if the n_preallocs field is set to a non-zero value, the type system allocates
531 the object's instance structures in chunks rather than mallocing for every instance)
532 declared by the user are used to get a buffer to hold the object's instance
537 If this is the first instance of the object ever created, the type system must create a class structure.
538 It allocates a buffer to hold the object's class structure and initializes it. The first part of the
539 class structure (ie: the embedded parent class structure) is initialized by copying the contents from
540 the class structure of the parent class. The rest of class structure is initialized to zero. If there
541 is no parent, the entire class structure is initialized to zero. The type system then invokes the
542 base_class_initialization functions (<link linkend="GBaseInitFunc"><type>GBaseInitFunc</type></link>) from topmost
543 fundamental object to bottom-most most derived object. The object's class_init
544 (<link linkend="GClassInitFunc"><type>GClassInitFunc</type></link>) function is invoked afterwards to complete
545 initialization of the class structure.
546 Finally, the object's interfaces are initialized (we will discuss interface initialization
547 in more detail later).
551 Once the type system has a pointer to an initialized class structure, it sets the object's
552 instance class pointer to the object's class structure and invokes the object's
553 instance_init (<link linkend="GInstanceInitFunc"><type>GInstanceInitFunc</type></link>)functions, from top-most fundamental
554 type to bottom-most most derived type.
558 Object instance destruction through <function><link linkend="g-type-free-instance">g_type_free_instance</link></function> is very simple:
559 the instance structure is returned to the instance pool if there is one and if this was the
560 last living instance of the object, the class is destroyed.
565 Class destruction (the concept of destruction is sometimes partly
566 referred to as finalization in GType) is the symmetric process of
567 the initialization: interfaces are destroyed first.
568 Then, the most derived
569 class_finalize (<link linkend="GClassFinalizeFunc"><type>GClassFinalizeFunc</type></link>) function is invoked. The
570 base_class_finalize (<link linkend="GBaseFinalizeFunc"><type>GBaseFinalizeFunc</type></link>) functions are
571 Finally invoked from bottom-most most-derived type to top-most fundamental type and
572 the class structure is freed.
576 As many readers have now understood it, the base initialization/finalization process is
577 very similar to the C++ constructor/destructor paradigm. The practical details are different
578 though and it is important not to get confused by superficial similarities.
579 GTypes have no instance destruction mechanism. It is
580 the user's responsibility to implement correct destruction semantics on top
581 of the existing GType code. (this is what GObject does. See
582 <xref linkend="chapter-gobject"/>)
583 Furthermore, C++ code equivalent to the base_init
584 and class_init callbacks of GType is usually not needed because C++ cannot really create object
589 The instantiation/finalization process can be summarized as follows:
590 <table id="gtype-init-fini-table">
591 <title>GType Instantiation/Finalization</title>
593 <colspec colwidth="*" colnum="1" align="left"/>
594 <colspec colwidth="*" colnum="2" align="left"/>
595 <colspec colwidth="8*" colnum="3" align="left"/>
599 <entry>Invocation time</entry>
600 <entry>Function Invoked</entry>
601 <entry>Function's parameters</entry>
606 <entry morerows="2">First call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> for target type</entry>
607 <entry>type's base_init function</entry>
608 <entry>On the inheritance tree of classes from fundamental type to target type.
609 base_init is invoked once for each class structure.</entry>
612 <!--entry>First call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> for target type</entry-->
613 <entry>target type's class_init function</entry>
614 <entry>On target type's class structure</entry>
617 <!--entry>First call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> for target type</entry-->
618 <entry>interface initialization, see
619 <xref linkend="gtype-non-instantiable-classed-init"/></entry>
623 <entry>Each call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> for target type</entry>
624 <entry>target type's instance_init function</entry>
625 <entry>On object's instance</entry>
628 <entry morerows="2">Last call to <function><link linkend="g-type-free-instance">g_type_free_instance</link></function> for target type</entry>
629 <entry>interface destruction, see
630 <xref linkend="gtype-non-instantiable-classed-dest"/></entry>
634 <!--entry>Last call to <function><link linkend="g-type-free-instance">g_type_free_instance</link></function> for target type</entry-->
635 <entry>target type's class_finalize function</entry>
636 <entry>On target type's class structure</entry>
639 <!--entry>Last call to <function><link linkend="g-type-free-instance">g_type_free_instance</link></function> for target type</entry-->
640 <entry>type's base_finalize function</entry>
641 <entry>On the inheritance tree of classes from fundamental type to target type.
642 base_finalize is invoked once for each class structure.</entry>
653 <sect1 id="gtype-non-instantiable-classed">
654 <title>Non-instantiable classed types: interfaces</title>
657 GType's interfaces are very similar to Java's interfaces. They allow
658 to describe a common API that several classes will adhere to.
659 Imagine the play, pause and stop buttons on hi-fi equipment - those can
660 be seen as a playback interface. Once you know what they do, you can
661 control your CD player, MP3 player or anything that uses these symbols.
662 To declare an interface you have to register a non-instantiable
663 classed type which derives from
664 <link linkend="GTypeInterface"><type>GTypeInterface</type></link>. The following piece of code declares such an interface.
666 #define MAMAN_TYPE_IBAZ (maman_ibaz_get_type ())
667 #define MAMAN_IBAZ(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), MAMAN_TYPE_IBAZ, MamanIbaz))
668 #define MAMAN_IS_IBAZ(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), MAMAN_TYPE_IBAZ))
669 #define MAMAN_IBAZ_GET_INTERFACE(inst) (G_TYPE_INSTANCE_GET_INTERFACE ((inst), MAMAN_TYPE_IBAZ, MamanIbazInterface))
671 typedef struct _MamanIbaz MamanIbaz; /* dummy object */
672 typedef struct _MamanIbazInterface MamanIbazInterface;
674 struct _MamanIbazInterface {
675 GTypeInterface parent;
677 void (*do_action) (MamanIbaz *self);
680 GType maman_ibaz_get_type (void);
682 void maman_ibaz_do_action (MamanIbaz *self);
684 The interface function, <function>maman_ibaz_do_action</function> is implemented
685 in a pretty simple way:
687 void maman_ibaz_do_action (MamanIbaz *self)
689 MAMAN_IBAZ_GET_INTERFACE (self)->do_action (self);
692 <function>maman_ibaz_get_type</function> registers a type named <emphasis>MamanIbaz</emphasis>
693 which inherits from G_TYPE_INTERFACE. All interfaces must be children of G_TYPE_INTERFACE in the
698 An interface is defined by only one structure which must contain as first member
699 a <link linkend="GTypeInterface"><type>GTypeInterface</type></link> structure. The interface structure is expected to
700 contain the function pointers of the interface methods. It is good style to
701 define helper functions for each of the interface methods which simply call
702 the interface' method directly: <function>maman_ibaz_do_action</function>
707 Once an interface type is registered, you must register implementations for these
708 interfaces. The function named <function>maman_baz_get_type</function> registers
709 a new GType named MamanBaz which inherits from <link linkend="GObject"><type>GObject</type></link> and which
710 implements the interface <type>MamanIbaz</type>.
712 static void maman_baz_do_action (MamanIbaz *self)
714 g_print ("Baz implementation of Ibaz interface Action.\n");
718 baz_interface_init (gpointer g_iface,
721 MamanIbazInterface *iface = (MamanIbazInterface *)g_iface;
722 iface->do_action = maman_baz_do_action;
726 maman_baz_get_type (void)
728 static GType type = 0;
730 const GTypeInfo info = {
731 sizeof (MamanBazClass),
732 NULL, /* base_init */
733 NULL, /* base_finalize */
734 NULL, /* class_init */
735 NULL, /* class_finalize */
736 NULL, /* class_data */
739 NULL /* instance_init */
741 const GInterfaceInfo ibaz_info = {
742 (GInterfaceInitFunc) baz_interface_init, /* interface_init */
743 NULL, /* interface_finalize */
744 NULL /* interface_data */
746 type = g_type_register_static (G_TYPE_OBJECT,
749 g_type_add_interface_static (type,
759 <function><link linkend="g-type-add-interface-static">g_type_add_interface_static</link></function> records in the type system that
760 a given type implements also <type>FooInterface</type>
761 (<function>foo_interface_get_type</function> returns the type of
762 <type>FooInterface</type>).
763 The <link linkend="GInterfaceInfo"><type>GInterfaceInfo</type></link> structure holds
764 information about the implementation of the interface:
766 struct _GInterfaceInfo
768 GInterfaceInitFunc interface_init;
769 GInterfaceFinalizeFunc interface_finalize;
770 gpointer interface_data;
776 If you have no special requirements you can use the
777 <link linkend="G-IMPLEMENT-INTERFACE:CAPS">G_IMPLEMENT_INTERFACE</link> macro
778 to implement an interface:
781 maman_baz_do_action (MamanIbaz *self)
783 g_print ("Baz implementation of Ibaz interface Action.\n");
787 maman_ibaz_interface_init (MamanIbazInterface *iface)
789 iface->do_action = maman_baz_do_action;
792 G_DEFINE_TYPE_WITH_CODE (MamanBaz, maman_baz, G_TYPE_OBJECT,
793 G_IMPLEMENT_INTERFACE (MAMAN_TYPE_IBAZ,
794 maman_ibaz_interface_init));
798 <sect2 id="gtype-non-instantiable-classed-init">
799 <title>Interface Initialization</title>
802 When an instantiable classed type which implements an interface
803 (either directly or by inheriting an implementation from a superclass)
804 is created for the first time, its class structure is initialized
805 following the process described in <xref linkend="gtype-instantiable-classed"/>.
806 After that, the interface implementations associated with
807 the type are initialized.
811 First a memory buffer is allocated to hold the interface structure. The parent's
812 interface structure is then copied over to the new interface structure (the parent
813 interface is already initialized at that point). If there is no parent interface,
814 the interface structure is initialized with zeros. The g_type and the g_instance_type
815 fields are then initialized: g_type is set to the type of the most-derived interface
816 and g_instance_type is set to the type of the most derived type which implements
821 The interface's <function>base_init</function> function is called,
822 and then the interface's <function>default_init</function> is invoked.
823 Finally if the type has registered an implementation of the interface,
824 the implementation's <function>interface_init</function>
825 function is invoked. If there are multiple implementations of an
826 interface the <function>base_init</function> and
827 <function>interface_init</function> functions will be invoked once
828 for each implementation initialized.
832 It is thus recommended to use a <function>default_init</function> function to
833 initialize an interface. This function is called only once for the interface no
834 matter how many implementations there are. The
835 <function>default_init</function> function is declared by
836 <link linkend="G-DEFINE-INTERFACE:CAPS">G_DEFINE_INTERFACE</link>
837 which can be used to define the interface:
839 G_DEFINE_INTERFACE (MamanIbaz, maman_ibaz, G_TYPE_OBJECT);
842 maman_ibaz_default_init (MamanIbazInterface *iface)
844 /* add properties and signals here, will only called once */
850 Or you can do that yourself in a GType function for your interface:
853 maman_ibaz_get_type (void)
855 static volatile gsize type_id = 0;
856 if (g_once_init_enter (&type_id)) {
857 const GTypeInfo info = {
858 sizeof (MamanIbazInterface),
859 NULL, /* base_init */
860 NULL, /* base_finalize */
861 maman_ibaz_default_init, /* class_init */
862 NULL, /* class_finalize */
863 NULL, /* class_data */
864 0, /* instance_size */
866 NULL /* instance_init */
868 GType type = g_type_register_static (G_TYPE_INTERFACE,
871 g_once_init_leave (&type_id, type);
877 maman_ibaz_default_init (MamanIbazInterface *iface)
879 /* add properties and signals here, will only called once */
885 If you have found the stuff about interface hairy, you are right: it is hairy but
886 there is not much I can do about it. What I can do is summarize what you need to know
891 <table id="ginterface-init-table">
892 <title>Interface Initialization</title>
894 <colspec colwidth="*" colnum="1" align="left"/>
895 <colspec colwidth="*" colnum="2" align="left"/>
896 <colspec colwidth="8*" colnum="3" align="left"/>
900 <entry>Invocation time</entry>
901 <entry>Function Invoked</entry>
902 <entry>Function's parameters</entry>
903 <entry>Remark</entry>
908 <entry>First call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function>
909 for <emphasis>any</emphasis> type implementing interface
911 <entry>interface's <function>base_init</function> function</entry>
912 <entry>On interface's vtable</entry>
913 <entry>Rarely necessary to use this. Called once per instantiated classed type implementing the interface.</entry>
916 <entry>First call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function>
917 for <emphasis>each</emphasis> type implementing interface
919 <entry>interface's <function>default_init</function> function</entry>
920 <entry>On interface's vtable</entry>
921 <entry>Register interface's signals, properties, etc. here. Will be called once.</entry>
924 <entry>First call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function>
925 for <emphasis>any</emphasis> type implementing interface
927 <entry>implementation's <function>interface_init</function> function</entry>
928 <entry>On interface's vtable</entry>
930 Initialize interface implementation. Called for each class that that
931 implements the interface. Initialize the interface method pointers
932 in the interface structure to the implementing class's implementation.
938 It is highly unlikely (i.e. I do not know of <emphasis>anyone</emphasis> who actually
939 used it) you will ever need other more fancy things such as the ones described in the
940 following section (<xref linkend="gtype-non-instantiable-classed-dest"/>).
945 <sect2 id="gtype-non-instantiable-classed-dest">
946 <title>Interface Destruction</title>
949 When the last instance of an instantiable type which registered
950 an interface implementation is destroyed, the interface's
951 implementations associated to the type are destroyed.
955 To destroy an interface implementation, GType first calls the
956 implementation's <function>interface_finalize</function> function
957 and then the interface's most-derived
958 <function>base_finalize</function> function.
962 Again, it is important to understand, as in
963 <xref linkend="gtype-non-instantiable-classed-init"/>,
964 that both <function>interface_finalize</function> and <function>base_finalize</function>
965 are invoked exactly once for the destruction of each implementation of an interface. Thus,
966 if you were to use one of these functions, you would need to use a static integer variable
967 which would hold the number of instances of implementations of an interface such that
968 the interface's class is destroyed only once (when the integer variable reaches zero).
972 The above process can be summarized as follows:
973 <table id="ginterface-fini-table">
974 <title>Interface Finalization</title>
976 <colspec colwidth="*" colnum="1" align="left"/>
977 <colspec colwidth="*" colnum="2" align="left"/>
978 <colspec colwidth="8*" colnum="3" align="left"/>
982 <entry>Invocation time</entry>
983 <entry>Function Invoked</entry>
984 <entry>Function's parameters</entry>
989 <entry morerows="1">Last call to <function><link linkend="g-type-free-instance">g_type_free_instance</link></function> for type
990 implementing interface
992 <entry>interface' interface_finalize function</entry>
993 <entry>On interface' vtable</entry>
996 <!--entry>Last call to <function><link linkend="g-type-free-instance">g_type_free_instance</link></function>for type
997 implementing interface
999 <entry>interface' base_finalize function</entry>
1000 <entry>On interface' vtable</entry>