nexmon – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 office 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>
7  
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;
18  
19 GBaseInitFunc base_init;
20 GBaseFinalizeFunc base_finalize;
21  
22 /* classed types, instantiated types */
23 GClassInitFunc class_init;
24 GClassFinalizeFunc class_finalize;
25 gconstpointer class_data;
26  
27 /* instantiated types */
28 guint16 instance_size;
29 guint16 n_preallocs;
30 GInstanceInitFunc instance_init;
31  
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>
46  
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>
59  
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>
68  
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>
105  
106 <sect1 id="gtype-copy">
107 <title>Copy functions</title>
108  
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>
114  
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>
124  
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;
134  
135 a = 0xdeadbeef;
136  
137 g_value_init (&amp;a_value, G_TYPE_UINT64);
138 g_value_set_uint64 (&amp;a_value, a);
139  
140 g_value_init (&amp;b_value, G_TYPE_UINT64);
141 g_value_copy (&amp;a_value, &amp;b_value);
142  
143 b = g_value_get_uint64 (&amp;b_value);
144  
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 }
151  
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);
158  
159 g_value_init (&amp;obj_vala, VIEWER_TYPE_FILE);
160 g_value_set_object (&amp;obj_vala, obj);
161  
162 g_value_init (&amp;obj_valb, G_TYPE_OBJECT);
163  
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 (&amp;obj_vala, &amp;obj_valb);
170  
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>
181  
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>
194  
195 <sect1 id="gtype-conventions">
196 <title>Conventions</title>
197  
198  
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>
271  
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>
280  
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 &amp;info, 0);
295 }
296 return type;
297 }
298 </programlisting></informalexample>
299 </para>
300  
301 </sect1>
302  
303 <sect1 id="gtype-non-instantiable">
304 <title>Non-instantiable non-classed fundamental types</title>
305  
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>
311  
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 = &amp;value_table;
341 type = g_type_register_fundamental (G_TYPE_CHAR, "gchar", &amp;info, &amp;finfo, 0);
342 </programlisting></informalexample>
343 </para>
344  
345  
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>
354  
355 </sect1>
356  
357 <sect1 id="gtype-instantiable-classed">
358 <title>Instantiable classed types: objects</title>
359  
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>
365  
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>
375  
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;
383  
384 /* instance members */
385 gchar *filename;
386 } ViewerFile;
387  
388 typedef struct {
389 GObjectClass parent;
390  
391 /* class members */
392 /* the first is public, pure and virtual */
393 void (*open) (ViewerFile *self,
394 GError **error);
395  
396 /* the second is public and virtual */
397 void (*close) (ViewerFile *self,
398 GError **error);
399 } ViewerFileClass;
400  
401 #define VIEWER_TYPE_FILE (viewer_file_get_type ())
402  
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 &amp;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>
430  
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;
466  
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>
486  
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>
500  
501 <sect2 id="gtype-instantiable-classed-init-done">
502 <title>Initialization and Destruction</title>
503  
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>
515  
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>
530  
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>
539  
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>
545  
546  
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>
557  
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>
570  
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"/>
579  
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>
631  
632 </sect2>
633  
634 </sect1>
635  
636 <sect1 id="gtype-non-instantiable-classed">
637 <title>Non-instantiable classed types: interfaces</title>
638  
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>
644  
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)
657  
658 struct _ViewerEditableInterface {
659 GTypeInterface parent;
660  
661 void (*save) (ViewerEditable *self,
662 GError **error);
663 };
664  
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;
676  
677 g_return_if_fail (VIEWER_IS_EDITABLE (self));
678 g_return_if_fail (error == NULL || *error == NULL);
679  
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>
689  
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>
698  
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 }
709  
710 static void
711 viewer_file_editable_interface_init (ViewerEditableInterface *iface)
712 {
713 iface->save = viewer_file_save;
714 }
715  
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>
721  
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 }
735  
736 static void
737 viewer_file_editable_interface_init (gpointer g_iface,
738 gpointer iface_data)
739 {
740 ViewerEditableInterface *iface = g_iface;
741  
742 iface->save = viewer_file_save;
743 }
744  
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 &amp;info, 0);
769 g_type_add_interface_static (type,
770 VIEWER_TYPE_EDITABLE,
771 &amp;editable_info);
772 }
773 return type;
774 }
775 </programlisting></informalexample>
776 </para>
777  
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>
794  
795 <sect2 id="gtype-non-instantiable-classed-init">
796 <title>Interface Initialization</title>
797  
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>
806  
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>
819  
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>
830  
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);
840  
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>
848  
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 (&amp;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 &amp;info, 0);
871 g_once_init_leave (&amp;type_id, type);
872 }
873 return type_id;
874 }
875  
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>
883  
884 <para>
885 In summary, interface initialization uses the following functions:
886 </para>
887  
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"/>
895  
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>
937  
938 </sect2>
939  
940 <sect2 id="gtype-non-instantiable-classed-dest">
941 <title>Interface Destruction</title>
942  
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>
948  
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>
955  
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>
965  
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"/>
974  
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>