| blob | df63c2dee05ffb0325f1cf455ad8d23dc6459b66 |
1 <?xml version='1.0' encoding="UTF-8"?>
2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4 ]>
5 <chapter id="chapter-gtype">
6 <title>The GLib Dynamic Type System</title>
8 <para>
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.
12 <informalexample><programlisting>
13 typedef struct _GTypeInfo GTypeInfo;
14 struct _GTypeInfo
15 {
16 /* interface types, classed types, instantiated types */
17 guint16 class_size;
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;
29 guint16 n_preallocs;
30 GInstanceInitFunc instance_init;
32 /* value handling */
33 const GTypeValueTable *value_table;
34 };
35 GType g_type_register_static (GType parent_type,
36 const gchar *type_name,
37 const GTypeInfo *info,
38 GTypeFlags flags);
39 GType g_type_register_fundamental (GType type_id,
40 const gchar *type_name,
41 const GTypeInfo *info,
42 const GTypeFundamentalInfo *finfo,
43 GTypeFlags flags);
44 </programlisting></informalexample>
45 </para>
47 <para>
48 <function><link linkend="g-type-register-static">g_type_register_static</link></function>,
49 <function><link linkend="g-type-register-dynamic">g_type_register_dynamic</link></function> and
50 <function><link linkend="g-type-register-fundamental">g_type_register_fundamental</link></function>
51 are the C functions, defined in
52 <filename>gtype.h</filename> and implemented in <filename>gtype.c</filename>
53 which you should use to register a new <link linkend="GType"><type>GType</type></link> in the program's type system.
54 It is not likely you will ever need to use
55 <function><link linkend="g-type-register-fundamental">g_type_register_fundamental</link></function>
56 but in case you want to, the last chapter explains how to create
57 new fundamental types.
58 </para>
60 <para>
61 Fundamental types are top-level types which do not derive from any other type
62 while other non-fundamental types derive from other types.
63 Upon initialization, the type system not only initializes its
64 internal data structures but it also registers a number of core
65 types: some of these are fundamental types. Others are types derived from these
66 fundamental types.
67 </para>
69 <para>
70 Fundamental and non-fundamental types are defined by:
71 <itemizedlist>
72 <listitem><para>
73 class size: the class_size field in <link linkend="GTypeInfo"><type>GTypeInfo</type></link>.
74 </para></listitem>
75 <listitem><para>
76 class initialization functions (C++ constructor): the <function>base_init</function> and
77 <function>class_init</function> fields in <link linkend="GTypeInfo"><type>GTypeInfo</type></link>.
78 </para></listitem>
79 <listitem><para>
80 class destruction functions (C++ destructor): the base_finalize and
81 class_finalize fields in <link linkend="GTypeInfo"><type>GTypeInfo</type></link>.
82 </para></listitem>
83 <listitem><para>
84 instance size (C++ parameter to new): the instance_size field in
85 <link linkend="GTypeInfo"><type>GTypeInfo</type></link>.
86 </para></listitem>
87 <listitem><para>
88 instantiation policy (C++ type of new operator): the n_preallocs
89 field in <link linkend="GTypeInfo"><type>GTypeInfo</type></link>.
90 </para></listitem>
91 <listitem><para>
92 copy functions (C++ copy operators): the value_table field in
93 <link linkend="GTypeInfo"><type>GTypeInfo</type></link>.
94 </para></listitem>
95 <listitem><para>
96 type characteristic flags: <link linkend="GTypeFlags"><type>GTypeFlags</type></link>.
97 </para></listitem>
98 </itemizedlist>
99 Fundamental types are also defined by a set of <link linkend="GTypeFundamentalFlags"><type>GTypeFundamentalFlags</type></link>
100 which are stored in a <link linkend="GTypeFundamentalInfo"><type>GTypeFundamentalInfo</type></link>.
101 Non-fundamental types are furthermore defined by the type of their parent which is
102 passed as the parent_type parameter to <function><link linkend="g-type-register-static">g_type_register_static</link></function>
103 and <function><link linkend="g-type-register-dynamic">g_type_register_dynamic</link></function>.
104 </para>
106 <sect1 id="gtype-copy">
107 <title>Copy functions</title>
109 <para>
110 The major common point between <emphasis>all</emphasis> GLib types (fundamental and
111 non-fundamental, classed and non-classed, instantiable and non-instantiable) is that
112 they can all be manipulated through a single API to copy/assign them.
113 </para>
115 <para>
116 The <link linkend="GValue"><type>GValue</type></link> structure is used as an abstract container for all of these
117 types. Its simplistic API (defined in <filename>gobject/gvalue.h</filename>) can be
118 used to invoke the value_table functions registered
119 during type registration: for example <function><link linkend="g-value-copy">g_value_copy</link></function> copies the
120 content of a <link linkend="GValue"><type>GValue</type></link> to another <link linkend="GValue"><type>GValue</type></link>. This is similar
121 to a C++ assignment which invokes the C++ copy operator to modify the default
122 bit-by-bit copy semantics of C++/C structures/classes.
123 </para>
125 <para>
126 The following code shows how you can copy around a 64 bit integer, as well as a <link linkend="GObject"><type>GObject</type></link>
127 instance pointer:
128 <informalexample><programlisting>
129 static void test_int (void)
130 {
131 GValue a_value = G_VALUE_INIT;
132 GValue b_value = G_VALUE_INIT;
133 guint64 a, b;
135 a = 0xdeadbeef;
137 g_value_init (&a_value, G_TYPE_UINT64);
138 g_value_set_uint64 (&a_value, a);
140 g_value_init (&b_value, G_TYPE_UINT64);
141 g_value_copy (&a_value, &b_value);
143 b = g_value_get_uint64 (&b_value);
145 if (a == b) {
146 g_print ("Yay !! 10 lines of code to copy around a uint64.\n");
147 } else {
148 g_print ("Are you sure this is not a Z80 ?\n");
149 }
150 }
152 static void test_object (void)
153 {
154 GObject *obj;
155 GValue obj_vala = G_VALUE_INIT;
156 GValue obj_valb = G_VALUE_INIT;
157 obj = g_object_new (VIEWER_TYPE_FILE, NULL);
159 g_value_init (&obj_vala, VIEWER_TYPE_FILE);
160 g_value_set_object (&obj_vala, obj);
162 g_value_init (&obj_valb, G_TYPE_OBJECT);
164 /* g_value_copy's semantics for G_TYPE_OBJECT types is to copy the reference.
165 * This function thus calls g_object_ref.
166 * It is interesting to note that the assignment works here because
167 * VIEWER_TYPE_FILE is a G_TYPE_OBJECT.
168 */
169 g_value_copy (&obj_vala, &obj_valb);
171 g_object_unref (G_OBJECT (obj));
172 g_object_unref (G_OBJECT (obj));
173 }
174 </programlisting></informalexample>
175 The important point about the above code is that the exact semantics of the copy calls
176 is undefined since they depend on the implementation of the copy function. Certain
177 copy functions might decide to allocate a new chunk of memory and then to copy the
178 data from the source to the destination. Others might want to simply increment
179 the reference count of the instance and copy the reference to the new GValue.
180 </para>
182 <para>
183 The value table used to specify these assignment functions is
184 documented in
185 <link linkend="GTypeValueTable"><type>GTypeValueTable</type></link>.
186 </para>
187 <para>
188 Interestingly, it is also very unlikely
189 you will ever need to specify a value_table during type registration
190 because these value_tables are inherited from the parent types for
191 non-fundamental types.
192 </para>
193 </sect1>
195 <sect1 id="gtype-conventions">
196 <title>Conventions</title>
199 <para>
200 There are a number of conventions users are expected to follow when creating new types
201 which are to be exported in a header file:
202 <itemizedlist>
203 <listitem><para>
204 Type names (including object names) must be at least three
205 characters long and start with ‘a–z’, ‘A–Z’ or ‘_’.
206 </para></listitem>
207 <listitem><para>
208 Use the <function>object_method</function> pattern for function names: to invoke
209 the method named <function>save</function> on an instance of object type <type>file</type>, call
210 <function>file_save</function>.
211 </para></listitem>
212 <listitem><para>Use prefixing to avoid namespace conflicts with other projects.
213 If your library (or application) is named <emphasis>Viewer</emphasis>,
214 prefix all your function names with <emphasis>viewer_</emphasis>.
215 For example: <function>viewer_object_method</function>.
216 </para></listitem>
217 <listitem><para>Create a macro named <function>PREFIX_TYPE_OBJECT</function> which always
218 returns the GType for the associated object type. For an object of type
219 <emphasis>File</emphasis> in the <emphasis>Viewer</emphasis> namespace,
220 use: <function>VIEWER_TYPE_FILE</function>.
221 This macro is implemented using a function named
222 <function>prefix_object_get_type</function>; for example, <function>viewer_file_get_type</function>.
223 </para></listitem>
224 <listitem>
225 <para>
226 Use <link linkend="G-DECLARE-FINAL-TYPE:CAPS"><function>G_DECLARE_FINAL_TYPE</function></link>
227 or <link linkend="G-DECLARE-DERIVABLE-TYPE:CAPS"><function>G_DECLARE_DERIVABLE_TYPE</function></link>
228 to define various other conventional macros for your object:
229 </para>
230 <itemizedlist>
231 <listitem><para><function>PREFIX_OBJECT (obj)</function>, which
232 returns a pointer of type <type>PrefixObject</type>. This macro is used to enforce
233 static type safety by doing explicit casts wherever needed. It also enforces
234 dynamic type safety by doing runtime checks. It is possible to disable the dynamic
235 type checks in production builds (see <link linkend="glib-building">building GLib</link>).
236 For example, we would create
237 <function>VIEWER_FILE (obj)</function> to keep the previous example.
238 </para></listitem>
239 <listitem><para><function>PREFIX_OBJECT_CLASS (klass)</function>, which
240 is strictly equivalent to the previous casting macro: it does static casting with
241 dynamic type checking of class structures. It is expected to return a pointer
242 to a class structure of type <type>PrefixObjectClass</type>. An example is:
243 <function>VIEWER_FILE_CLASS</function>.
244 </para></listitem>
245 <listitem><para><function>PREFIX_IS_OBJECT (obj)</function>, which
246 returns a <type>gboolean</type> which indicates whether the input
247 object instance pointer is non-<type>NULL</type> and of type <type>OBJECT</type>.
248 For example, <function>VIEWER_IS_FILE</function>.
249 </para></listitem>
250 <listitem><para><function>PREFIX_IS_OBJECT_CLASS (klass)</function>, which returns a boolean
251 if the input class pointer is a pointer to a class of type OBJECT.
252 For example, <function>VIEWER_IS_FILE_CLASS</function>.
253 </para></listitem>
254 <listitem><para><function>PREFIX_OBJECT_GET_CLASS (obj)</function>,
255 which returns the class pointer associated to an instance of a given type. This macro
256 is used for static and dynamic type safety purposes (just like the previous casting
257 macros).
258 For example, <function>VIEWER_FILE_GET_CLASS</function>.
259 </para></listitem>
260 </itemizedlist>
261 </listitem>
262 </itemizedlist>
263 The implementation of these macros is pretty straightforward: a number of simple-to-use
264 macros are provided in <filename>gtype.h</filename>. For the example we used above, we would
265 write the following trivial code to declare the macros:
266 <informalexample><programlisting>
267 #define VIEWER_TYPE_FILE viewer_file_get_type ()
268 G_DECLARE_FINAL_TYPE (ViewerFile, viewer_file, VIEWER, FILE, GObject)
269 </programlisting></informalexample>
270 </para>
272 <para>
273 Unless your code has special requirements, you can use the
274 <function><link linkend="G-DEFINE-TYPE:CAPS">G_DEFINE_TYPE</link></function>
275 macro to define a class:
276 <informalexample><programlisting>
277 G_DEFINE_TYPE (ViewerFile, viewer_file, G_TYPE_OBJECT)
278 </programlisting></informalexample>
279 </para>
281 <para>
282 Otherwise, the <function>viewer_file_get_type</function> function must be
283 implemented manually:
284 <informalexample><programlisting>
285 GType viewer_file_get_type (void)
286 {
287 static GType type = 0;
288 if (type == 0) {
289 const GTypeInfo info = {
290 /* You fill this structure. */
291 };
292 type = g_type_register_static (G_TYPE_OBJECT,
293 "ViewerFile",
294 &info, 0);
295 }
296 return type;
297 }
298 </programlisting></informalexample>
299 </para>
301 </sect1>
303 <sect1 id="gtype-non-instantiable">
304 <title>Non-instantiable non-classed fundamental types</title>
306 <para>
307 A lot of types are not instantiable by the type system and do not have
308 a class. Most of these types are fundamental trivial types such as <emphasis>gchar</emphasis>,
309 and are already registered by GLib.
310 </para>
312 <para>
313 In the rare case of needing to register such a type in the type
314 system, fill a
315 <link linkend="GTypeInfo"><type>GTypeInfo</type></link> structure with zeros since these types are also most of the time
316 fundamental:
317 <informalexample><programlisting>
318 GTypeInfo info = {
319 0, /* class_size */
320 NULL, /* base_init */
321 NULL, /* base_destroy */
322 NULL, /* class_init */
323 NULL, /* class_destroy */
324 NULL, /* class_data */
325 0, /* instance_size */
326 0, /* n_preallocs */
327 NULL, /* instance_init */
328 NULL, /* value_table */
329 };
330 static const GTypeValueTable value_table = {
331 value_init_long0, /* value_init */
332 NULL, /* value_free */
333 value_copy_long0, /* value_copy */
334 NULL, /* value_peek_pointer */
335 "i", /* collect_format */
336 value_collect_int, /* collect_value */
337 "p", /* lcopy_format */
338 value_lcopy_char, /* lcopy_value */
339 };
340 info.value_table = &value_table;
341 type = g_type_register_fundamental (G_TYPE_CHAR, "gchar", &info, &finfo, 0);
342 </programlisting></informalexample>
343 </para>
346 <para>
347 Having non-instantiable types might seem a bit useless: what good is a type
348 if you cannot instantiate an instance of that type ? Most of these types
349 are used in conjunction with <link linkend="GValue"><type>GValue</type></link>s: a GValue is initialized
350 with an integer or a string and it is passed around by using the registered
351 type's value_table. <link linkend="GValue"><type>GValue</type></link>s (and by extension these trivial fundamental
352 types) are most useful when used in conjunction with object properties and signals.
353 </para>
355 </sect1>
357 <sect1 id="gtype-instantiable-classed">
358 <title>Instantiable classed types: objects</title>
360 <para>
361 This section covers the theory behind objects. See
362 <xref linkend="howto-gobject"/> for the recommended way to define a
363 GObject.
364 </para>
366 <para>
367 Types which are registered with a class and are declared instantiable are
368 what most closely resembles an <emphasis>object</emphasis>.
369 Although <link linkend="GObject"><type>GObject</type></link>s (detailed in <xref linkend="chapter-gobject"/>)
370 are the most well known type of instantiable
371 classed types, other kinds of similar objects used as the base of an inheritance
372 hierarchy have been externally developed and they are all built on the fundamental
373 features described below.
374 </para>
376 <para>
377 For example, the code below shows how you could register
378 such a fundamental object type in the type system (using none of the
379 GObject convenience API):
380 <informalexample><programlisting>
381 typedef struct {
382 GObject parent;
384 /* instance members */
385 gchar *filename;
386 } ViewerFile;
388 typedef struct {
389 GObjectClass parent;
391 /* class members */
392 /* the first is public, pure and virtual */
393 void (*open) (ViewerFile *self,
394 GError **error);
396 /* the second is public and virtual */
397 void (*close) (ViewerFile *self,
398 GError **error);
399 } ViewerFileClass;
401 #define VIEWER_TYPE_FILE (viewer_file_get_type ())
403 GType
404 viewer_file_get_type (void)
405 {
406 static GType type = 0;
407 if (type == 0) {
408 const GTypeInfo info = {
409 sizeof (ViewerFileClass),
410 NULL, /* base_init */
411 NULL, /* base_finalize */
412 (GClassInitFunc) viewer_file_class_init,
413 NULL, /* class_finalize */
414 NULL, /* class_data */
415 sizeof (ViewerFile),
416 0, /* n_preallocs */
417 (GInstanceInitFunc) NULL /* instance_init */
418 };
419 type = g_type_register_static (G_TYPE_OBJECT,
420 "ViewerFile",
421 &info, 0);
422 }
423 return type;
424 }
425 </programlisting></informalexample>
426 Upon the first call to <function>viewer_file_get_type</function>, the type named
427 <emphasis>ViewerFile</emphasis> will be registered in the type system as inheriting
428 from the type <emphasis>G_TYPE_OBJECT</emphasis>.
429 </para>
431 <para>
432 Every object must define two structures: its class structure and its
433 instance structure. All class structures must contain as first member
434 a <link linkend="GTypeClass"><type>GTypeClass</type></link> structure. All instance structures must contain as first
435 member a <link linkend="GTypeInstance"><type>GTypeInstance</type></link> structure. The declaration of these C types,
436 coming from <filename>gtype.h</filename> is shown below:
437 <informalexample><programlisting>
438 struct _GTypeClass
439 {
440 GType g_type;
441 };
442 struct _GTypeInstance
443 {
444 GTypeClass *g_class;
445 };
446 </programlisting></informalexample>
447 These constraints allow the type system to make sure that every object instance
448 (identified by a pointer to the object's instance structure) contains in its
449 first bytes a pointer to the object's class structure.
450 </para>
451 <para>
452 This relationship is best explained by an example: let's take object B which
453 inherits from object A:
454 <informalexample><programlisting>
455 /* A definitions */
456 typedef struct {
457 GTypeInstance parent;
458 int field_a;
459 int field_b;
460 } A;
461 typedef struct {
462 GTypeClass parent_class;
463 void (*method_a) (void);
464 void (*method_b) (void);
465 } AClass;
467 /* B definitions. */
468 typedef struct {
469 A parent;
470 int field_c;
471 int field_d;
472 } B;
473 typedef struct {
474 AClass parent_class;
475 void (*method_c) (void);
476 void (*method_d) (void);
477 } BClass;
478 </programlisting></informalexample>
479 The C standard mandates that the first field of a C structure is stored starting
480 in the first byte of the buffer used to hold the structure's fields in memory.
481 This means that the first field of an instance of an object B is A's first field
482 which in turn is <type>GTypeInstance</type>'s first field which in
483 turn is <structfield>g_class</structfield>, a pointer
484 to B's class structure.
485 </para>
487 <para>
488 Thanks to these simple conditions, it is possible to detect the type of every
489 object instance by doing:
490 <informalexample><programlisting>
491 B *b;
492 b->parent.parent.g_class->g_type
493 </programlisting></informalexample>
494 or, more quickly:
495 <informalexample><programlisting>
496 B *b;
497 ((GTypeInstance *) b)->g_class->g_type
498 </programlisting></informalexample>
499 </para>
501 <sect2 id="gtype-instantiable-classed-init-done">
502 <title>Initialization and Destruction</title>
504 <para>
505 instantiation of these types can be done with
506 <function><link linkend="g-type-create-instance">g_type_create_instance</link></function>,
507 which will look up the type information
508 structure associated with the type requested. Then, the instance size and instantiation
509 policy (if the <structfield>n_preallocs</structfield> field is set
510 to a non-zero value, the type system allocates
511 the object's instance structures in chunks rather than mallocing for every instance)
512 declared by the user are used to get a buffer to hold the object's instance
513 structure.
514 </para>
516 <para>
517 If this is the first instance of the object ever created, the type system must create a class structure.
518 It allocates a buffer to hold the object's class structure and initializes it. The first part of the
519 class structure (ie: the embedded parent class structure) is initialized by copying the contents from
520 the class structure of the parent class. The rest of class structure is initialized to zero. If there
521 is no parent, the entire class structure is initialized to zero. The type system then invokes the
522 <function>base_class_initialization</function> functions
523 (<link linkend="GBaseInitFunc"><type>GBaseInitFunc</type></link>) from topmost
524 fundamental object to bottom-most most derived object. The object's <function>class_init</function>
525 (<link linkend="GClassInitFunc"><type>GClassInitFunc</type></link>) function is invoked afterwards to complete
526 initialization of the class structure.
527 Finally, the object's interfaces are initialized (we will discuss interface initialization
528 in more detail later).
529 </para>
531 <para>
532 Once the type system has a pointer to an initialized class structure, it sets the object's
533 instance class pointer to the object's class structure and invokes the object's
534 <function>instance_init</function>
535 (<link linkend="GInstanceInitFunc"><type>GInstanceInitFunc</type></link>)
536 functions, from top-most fundamental
537 type to bottom-most most-derived type.
538 </para>
540 <para>
541 Object instance destruction through <function><link linkend="g-type-free-instance">g_type_free_instance</link></function> is very simple:
542 the instance structure is returned to the instance pool if there is one and if this was the
543 last living instance of the object, the class is destroyed.
544 </para>
547 <para>
548 Class destruction (the concept of destruction is sometimes partly
549 referred to as finalization in GType) is the symmetric process of
550 the initialization: interfaces are destroyed first.
551 Then, the most derived
552 class_finalize (<link linkend="GClassFinalizeFunc"><type>GClassFinalizeFunc</type></link>) function is invoked. Finally, the
553 base_class_finalize (<link linkend="GBaseFinalizeFunc"><type>GBaseFinalizeFunc</type></link>) functions are
554 invoked from bottom-most most-derived type to top-most fundamental type and
555 the class structure is freed.
556 </para>
558 <para>
559 The base initialization/finalization process is
560 very similar to the C++ constructor/destructor paradigm. The practical details are different
561 though and it is important not to get confused by superficial similarities.
562 GTypes have no instance destruction mechanism. It is
563 the user's responsibility to implement correct destruction semantics on top
564 of the existing GType code. (This is what GObject does: see
565 <xref linkend="chapter-gobject"/>.)
566 Furthermore, C++ code equivalent to the <function>base_init</function>
567 and <function>class_init</function> callbacks of GType is usually not needed because C++ cannot really create object
568 types at runtime.
569 </para>
571 <para>
572 The instantiation/finalization process can be summarized as follows:
573 <table id="gtype-init-fini-table">
574 <title>GType Instantiation/Finalization</title>
575 <tgroup cols="3">
576 <colspec colwidth="*" colnum="1" align="left"/>
577 <colspec colwidth="*" colnum="2" align="left"/>
578 <colspec colwidth="8*" colnum="3" align="left"/>
580 <thead>
581 <row>
582 <entry>Invocation time</entry>
583 <entry>Function invoked</entry>
584 <entry>Function's parameters</entry>
585 </row>
586 </thead>
587 <tbody>
588 <row>
589 <entry morerows="2">First call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> for target type</entry>
590 <entry>type's <function>base_init</function> function</entry>
591 <entry>On the inheritance tree of classes from fundamental type to target type.
592 <function>base_init</function> is invoked once for each class structure.</entry>
593 </row>
594 <row>
595 <!--entry>First call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> for target type</entry-->
596 <entry>target type's <function>class_init</function> function</entry>
597 <entry>On target type's class structure</entry>
598 </row>
599 <row>
600 <!--entry>First call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> for target type</entry-->
601 <entry>interface initialization, see
602 <xref linkend="gtype-non-instantiable-classed-init"/></entry>
603 <entry></entry>
604 </row>
605 <row>
606 <entry>Each call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> for target type</entry>
607 <entry>target type's <function>instance_init</function> function</entry>
608 <entry>On object's instance</entry>
609 </row>
610 <row>
611 <entry morerows="2">Last call to <function><link linkend="g-type-free-instance">g_type_free_instance</link></function> for target type</entry>
612 <entry>interface destruction, see
613 <xref linkend="gtype-non-instantiable-classed-dest"/></entry>
614 <entry></entry>
615 </row>
616 <row>
617 <!--entry>Last call to <function><link linkend="g-type-free-instance">g_type_free_instance</link></function> for target type</entry-->
618 <entry>target type's <function>class_finalize</function> function</entry>
619 <entry>On target type's class structure</entry>
620 </row>
621 <row>
622 <!--entry>Last call to <function><link linkend="g-type-free-instance">g_type_free_instance</link></function> for target type</entry-->
623 <entry>type's <function>base_finalize</function> function</entry>
624 <entry>On the inheritance tree of classes from fundamental type to target type.
625 <function>base_finalize</function> is invoked once for each class structure.</entry>
626 </row>
627 </tbody>
628 </tgroup>
629 </table>
630 </para>
632 </sect2>
634 </sect1>
636 <sect1 id="gtype-non-instantiable-classed">
637 <title>Non-instantiable classed types: interfaces</title>
639 <para>
640 This section covers the theory behind interfaces. See
641 <xref linkend="howto-interface"/> for the recommended way to define an
642 interface.
643 </para>
645 <para>
646 GType's interfaces are very similar to Java's interfaces. They allow
647 to describe a common API that several classes will adhere to.
648 Imagine the play, pause and stop buttons on hi-fi equipment — those can
649 be seen as a playback interface. Once you know what they do, you can
650 control your CD player, MP3 player or anything that uses these symbols.
651 To declare an interface you have to register a non-instantiable
652 classed type which derives from
653 <link linkend="GTypeInterface"><type>GTypeInterface</type></link>. The following piece of code declares such an interface.
654 <informalexample><programlisting>
655 #define VIEWER_TYPE_EDITABLE viewer_editable_get_type ()
656 G_DECLARE_INTERFACE (ViewerEditable, viewer_editable, VIEWER, EDITABLE, GObject)
658 struct _ViewerEditableInterface {
659 GTypeInterface parent;
661 void (*save) (ViewerEditable *self,
662 GError **error);
663 };
665 void viewer_editable_save (ViewerEditable *self,
666 GError **error);
667 </programlisting></informalexample>
668 The interface function, <function>viewer_editable_save</function> is implemented
669 in a pretty simple way:
670 <informalexample><programlisting>
671 void
672 viewer_editable_save (ViewerEditable *self,
673 GError **error)
674 {
675 ViewerEditableinterface *iface;
677 g_return_if_fail (VIEWER_IS_EDITABLE (self));
678 g_return_if_fail (error == NULL || *error == NULL);
680 iface = VIEWER_EDITABLE_GET_INTERFACE (self);
681 g_return_if_fail (iface->save != NULL);
682 iface->save (self);
683 }
684 </programlisting></informalexample>
685 <function>viewer_editable_get_type</function> registers a type named <emphasis>ViewerEditable</emphasis>
686 which inherits from <type>G_TYPE_INTERFACE</type>. All interfaces must
687 be children of <type>G_TYPE_INTERFACE</type> in the inheritance tree.
688 </para>
690 <para>
691 An interface is defined by only one structure which must contain as first member
692 a <link linkend="GTypeInterface"><type>GTypeInterface</type></link> structure. The interface structure is expected to
693 contain the function pointers of the interface methods. It is good style to
694 define helper functions for each of the interface methods which simply call
695 the interface's method directly: <function>viewer_editable_save</function>
696 is one of these.
697 </para>
699 <para>
700 If you have no special requirements you can use the
701 <link linkend="G-IMPLEMENT-INTERFACE:CAPS">G_IMPLEMENT_INTERFACE</link> macro
702 to implement an interface:
703 <informalexample><programlisting>
704 static void
705 viewer_file_save (ViewerEditable *self)
706 {
707 g_print ("File implementation of editable interface save method.\n");
708 }
710 static void
711 viewer_file_editable_interface_init (ViewerEditableInterface *iface)
712 {
713 iface->save = viewer_file_save;
714 }
716 G_DEFINE_TYPE_WITH_CODE (ViewerFile, viewer_file, VIEWER_TYPE_FILE,
717 G_IMPLEMENT_INTERFACE (VIEWER_TYPE_EDITABLE,
718 viewer_file_editable_interface_init));
719 </programlisting></informalexample>
720 </para>
722 <para>
723 If your code does have special requirements, you must write a custom
724 <function>get_type</function> function to register your GType which
725 inherits from some <link linkend="GObject"><type>GObject</type></link>
726 and which implements the interface <type>ViewerEditable</type>. For
727 example, this code registers a new <type>ViewerFile</type> class which
728 implements <type>ViewerEditable</type>:
729 <informalexample><programlisting>
730 static void
731 viewer_file_save (ViewerEditable *editable)
732 {
733 g_print ("File implementation of editable interface save method.\n");
734 }
736 static void
737 viewer_file_editable_interface_init (gpointer g_iface,
738 gpointer iface_data)
739 {
740 ViewerEditableInterface *iface = g_iface;
742 iface->save = viewer_file_save;
743 }
745 GType
746 viewer_file_get_type (void)
747 {
748 static GType type = 0;
749 if (type == 0) {
750 const GTypeInfo info = {
751 sizeof (ViewerFileClass),
752 NULL, /* base_init */
753 NULL, /* base_finalize */
754 NULL, /* class_init */
755 NULL, /* class_finalize */
756 NULL, /* class_data */
757 sizeof (ViewerFile),
758 0, /* n_preallocs */
759 NULL /* instance_init */
760 };
761 const GInterfaceInfo editable_info = {
762 (GInterfaceInitFunc) viewer_file_editable_interface_init, /* interface_init */
763 NULL, /* interface_finalize */
764 NULL /* interface_data */
765 };
766 type = g_type_register_static (VIEWER_TYPE_FILE,
767 "ViewerFile",
768 &info, 0);
769 g_type_add_interface_static (type,
770 VIEWER_TYPE_EDITABLE,
771 &editable_info);
772 }
773 return type;
774 }
775 </programlisting></informalexample>
776 </para>
778 <para>
779 <function><link linkend="g-type-add-interface-static">g_type_add_interface_static</link></function> records in the type system that
780 a given type implements also <type>FooInterface</type>
781 (<function>foo_interface_get_type</function> returns the type of
782 <type>FooInterface</type>).
783 The <link linkend="GInterfaceInfo"><type>GInterfaceInfo</type></link> structure holds
784 information about the implementation of the interface:
785 <informalexample><programlisting>
786 struct _GInterfaceInfo
787 {
788 GInterfaceInitFunc interface_init;
789 GInterfaceFinalizeFunc interface_finalize;
790 gpointer interface_data;
791 };
792 </programlisting></informalexample>
793 </para>
795 <sect2 id="gtype-non-instantiable-classed-init">
796 <title>Interface Initialization</title>
798 <para>
799 When an instantiable classed type which implements an interface
800 (either directly or by inheriting an implementation from a superclass)
801 is created for the first time, its class structure is initialized
802 following the process described in <xref linkend="gtype-instantiable-classed"/>.
803 After that, the interface implementations associated with
804 the type are initialized.
805 </para>
807 <para>
808 First a memory buffer is allocated to hold the interface structure. The parent's
809 interface structure is then copied over to the new interface structure (the parent
810 interface is already initialized at that point). If there is no parent interface,
811 the interface structure is initialized with zeros. The
812 <structfield>g_type</structfield> and the
813 <structfield>g_instance_type</structfield> fields are then
814 initialized: <structfield>g_type</structfield> is set to the type of
815 the most-derived interface and
816 <structfield>g_instance_type</structfield> is set to the type of the
817 most derived type which implements this interface.
818 </para>
820 <para>
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.
829 </para>
831 <para>
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:
838 <informalexample><programlisting>
839 G_DEFINE_INTERFACE (ViewerEditable, viewer_editable, G_TYPE_OBJECT);
841 static void
842 viewer_editable_default_init (ViewerEditableInterface *iface)
843 {
844 /* add properties and signals here, will only be called once */
845 }
846 </programlisting></informalexample>
847 </para>
849 <para>
850 Or you can do that yourself in a GType function for your interface:
851 <informalexample><programlisting>
852 GType
853 viewer_editable_get_type (void)
854 {
855 static volatile gsize type_id = 0;
856 if (g_once_init_enter (&type_id)) {
857 const GTypeInfo info = {
858 sizeof (ViewerEditableInterface),
859 NULL, /* base_init */
860 NULL, /* base_finalize */
861 viewer_editable_default_init, /* class_init */
862 NULL, /* class_finalize */
863 NULL, /* class_data */
864 0, /* instance_size */
865 0, /* n_preallocs */
866 NULL /* instance_init */
867 };
868 GType type = g_type_register_static (G_TYPE_INTERFACE,
869 "ViewerEditable",
870 &info, 0);
871 g_once_init_leave (&type_id, type);
872 }
873 return type_id;
874 }
876 static void
877 viewer_editable_default_init (ViewerEditableInterface *iface)
878 {
879 /* add properties and signals here, will only called once */
880 }
881 </programlisting></informalexample>
882 </para>
884 <para>
885 In summary, interface initialization uses the following functions:
886 </para>
888 <para>
889 <table id="ginterface-init-table">
890 <title>Interface Initialization</title>
891 <tgroup cols="3">
892 <colspec colwidth="*" colnum="1" align="left"/>
893 <colspec colwidth="*" colnum="2" align="left"/>
894 <colspec colwidth="8*" colnum="3" align="left"/>
896 <thead>
897 <row>
898 <entry>Invocation time</entry>
899 <entry>Function Invoked</entry>
900 <entry>Function's parameters</entry>
901 <entry>Remark</entry>
902 </row>
903 </thead>
904 <tbody>
905 <row>
906 <entry>First call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function>
907 for <emphasis>any</emphasis> type implementing interface
908 </entry>
909 <entry>interface's <function>base_init</function> function</entry>
910 <entry>On interface's vtable</entry>
911 <entry>Rarely necessary to use this. Called once per instantiated classed type implementing the interface.</entry>
912 </row>
913 <row>
914 <entry>First call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function>
915 for <emphasis>each</emphasis> type implementing interface
916 </entry>
917 <entry>interface's <function>default_init</function> function</entry>
918 <entry>On interface's vtable</entry>
919 <entry>Register interface's signals, properties, etc. here. Will be called once.</entry>
920 </row>
921 <row>
922 <entry>First call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function>
923 for <emphasis>any</emphasis> type implementing interface
924 </entry>
925 <entry>implementation's <function>interface_init</function> function</entry>
926 <entry>On interface's vtable</entry>
927 <entry>
928 Initialize interface implementation. Called for each class that that
929 implements the interface. Initialize the interface method pointers
930 in the interface structure to the implementing class's implementation.
931 </entry>
932 </row>
933 </tbody>
934 </tgroup>
935 </table>
936 </para>
938 </sect2>
940 <sect2 id="gtype-non-instantiable-classed-dest">
941 <title>Interface Destruction</title>
943 <para>
944 When the last instance of an instantiable type which registered
945 an interface implementation is destroyed, the interface's
946 implementations associated to the type are destroyed.
947 </para>
949 <para>
950 To destroy an interface implementation, GType first calls the
951 implementation's <function>interface_finalize</function> function
952 and then the interface's most-derived
953 <function>base_finalize</function> function.
954 </para>
956 <para>
957 Again, it is important to understand, as in
958 <xref linkend="gtype-non-instantiable-classed-init"/>,
959 that both <function>interface_finalize</function> and <function>base_finalize</function>
960 are invoked exactly once for the destruction of each implementation of an interface. Thus,
961 if you were to use one of these functions, you would need to use a static integer variable
962 which would hold the number of instances of implementations of an interface such that
963 the interface's class is destroyed only once (when the integer variable reaches zero).
964 </para>
966 <para>
967 The above process can be summarized as follows:
968 <table id="ginterface-fini-table">
969 <title>Interface Finalization</title>
970 <tgroup cols="3">
971 <colspec colwidth="*" colnum="1" align="left"/>
972 <colspec colwidth="*" colnum="2" align="left"/>
973 <colspec colwidth="8*" colnum="3" align="left"/>
975 <thead>
976 <row>
977 <entry>Invocation time</entry>
978 <entry>Function Invoked</entry>
979 <entry>Function's parameters</entry>
980 </row>
981 </thead>
982 <tbody>
983 <row>
984 <entry morerows="1">Last call to <function><link linkend="g-type-free-instance">g_type_free_instance</link></function> for type
985 implementing interface
986 </entry>
987 <entry>interface's <function>interface_finalize</function> function</entry>
988 <entry>On interface's vtable</entry>
989 </row>
990 <row>
991 <!--entry>Last call to <function><link linkend="g-type-free-instance">g_type_free_instance</link></function>for type
992 implementing interface
993 </entry-->
994 <entry>interface's <function>base_finalize</function> function</entry>
995 <entry>On interface's vtable</entry>
996 </row>
997 </tbody>
998 </tgroup>
999 </table>
1000 </para>
1001 </sect2>
1002 </sect1>
1003 </chapter>