1 <?xml version='1.0' encoding="ISO-8859-1"?> 2 <chapter id="chapter-gtype"> 3 <title>The GLib Dynamic Type System</title> 4 5 <para> 6 A type, as manipulated by the GLib type system, is much more generic than what 7 is usually understood as an Object type. It is best explained by looking at the 8 structure and the functions used to register new types in the type system. 9 <programlisting> 10 typedef struct _GTypeInfo GTypeInfo; 11 struct _GTypeInfo 12 { 13 /* interface types, classed types, instantiated types */ 14 guint16 class_size; 15 16 GBaseInitFunc base_init; 17 GBaseFinalizeFunc base_finalize; 18 19 /* classed types, instantiated types */ 20 GClassInitFunc class_init; 21 GClassFinalizeFunc class_finalize; 22 gconstpointer class_data; 23 24 /* instantiated types */ 25 guint16 instance_size; 26 guint16 n_preallocs; 27 GInstanceInitFunc instance_init; 28 29 /* value handling */ 30 const GTypeValueTable *value_table; 31 }; 32 GType g_type_register_static (GType parent_type, 33 const gchar *type_name, 34 const GTypeInfo *info, 35 GTypeFlags flags); 36 GType g_type_register_fundamental (GType type_id, 37 const gchar *type_name, 38 const GTypeInfo *info, 39 const GTypeFundamentalInfo *finfo, 40 GTypeFlags flags); 41 </programlisting> 42 </para> 43 44 <para> 45 <function><link linkend="g-type-register-static">g_type_register_static</link></function> and 46 <function><link linkend="g-type-register-fundamental">g_type_register_fundamental</link></function> 47 are the C functions, defined in 48 <filename>gtype.h</filename> and implemented in <filename>gtype.c</filename> 49 which you should use to register a new <type><link linkend="GType">GType</link></type> in the program's type system. 50 It is not likely you will ever need to use 51 <function><link linkend="g-type-register-fundamental">g_type_register_fundamental</link></function> (you have to be Tim Janik 52 to do that) but in case you want to, the last chapter explains how to create 53 new fundamental types. 54 <footnote> 55 <para> 56 Please note that there exists another registration function: the 57 <function><link linkend="g-type-register-dynamic">g_type_register_dynamic</link></function>. We will not discuss this 58 function here since its use is very similar to the <function>_static</function> 59 version. 60 </para> 61 </footnote> 62 </para> 63 64 <para> 65 Fundamental types are top-level types which do not derive from any other type 66 while other non-fundamental types derive from other types. 67 Upon initialization by <function><link linkend="g-type-init">g_type_init</link></function>, the type system not 68 only initializes its internal data structures but it also registers a number of core 69 types: some of these are fundamental types. Others are types derived from these 70 fundamental types. 71 </para> 72 73 <para> 74 Fundamental and non-fundamental types are defined by: 75 <itemizedlist> 76 <listitem><para> 77 class size: the class_size field in <type><link linkend="GTypeInfo">GTypeInfo</link></type>. 78 </para></listitem> 79 <listitem><para> 80 class initialization functions (C++ constructor): the base_init and 81 class_init fields in <type><link linkend="GTypeInfo">GTypeInfo</link></type>. 82 </para></listitem> 83 <listitem><para> 84 class destruction functions (C++ destructor): the base_finalize and 85 class_finalize fields in <type><link linkend="GTypeInfo">GTypeInfo</link></type>. 86 </para></listitem> 87 <listitem><para> 88 instance size (C++ parameter to new): the instance_size field in 89 <type><link linkend="GTypeInfo">GTypeInfo</link></type>. 90 </para></listitem> 91 <listitem><para> 92 instantiation policy (C++ type of new operator): the n_preallocs 93 field in <type><link linkend="GTypeInfo">GTypeInfo</link></type>. 94 </para></listitem> 95 <listitem><para> 96 copy functions (C++ copy operators): the value_table field in 97 <type><link linkend="GTypeInfo">GTypeInfo</link></type>. 98 </para></listitem> 99 <listitem><para> 100 type characteristic flags: <type><link linkend="GTypeFlags">GTypeFlags</link></type>. 101 </para></listitem> 102 </itemizedlist> 103 Fundamental types are also defined by a set of <type><link linkend="GTypeFundamentalFlags">GTypeFundamentalFlags</link></type> 104 which are stored in a <type><link linkend="GTypeFundamentalInfo">GTypeFundamentalInfo</link></type>. 105 Non-fundamental types are furthermore defined by the type of their parent which is 106 passed as the parent_type parameter to <function><link linkend="g-type-register-static">g_type_register_static</link></function> 107 and <function><link linkend="g-type-register-dynamic">g_type_register_dynamic</link></function>. 108 </para> 109 110 <sect1 id="gtype-copy"> 111 <title>Copy functions</title> 112 113 <para> 114 The major common point between <emphasis>all</emphasis> GLib types (fundamental and 115 non-fundamental, classed and non-classed, instantiable and non-instantiable) is that 116 they can all be manipulated through a single API to copy/assign them. 117 </para> 118 119 <para> 120 The <type><link linkend="GValue">GValue</link></type> structure is used as an abstract container for all of these 121 types. Its simplistic API (defined in <filename>gobject/gvalue.h</filename>) can be 122 used to invoke the value_table functions registered 123 during type registration: for example <function><link linkend="g-value-copy">g_value_copy</link></function> copies the 124 content of a <type><link linkend="GValue">GValue</link></type> to another <type><link linkend="GValue">GValue</link></type>. This is similar 125 to a C++ assignment which invokes the C++ copy operator to modify the default 126 bit-by-bit copy semantics of C++/C structures/classes. 127 </para> 128 129 <para> 130 The following code shows how you can copy around a 64 bit integer, as well as a <type><link linkend="GObject">GObject</link></type> 131 instance pointer (sample code for this is located in the source tarball for this document in 132 <filename>sample/gtype/test.c</filename>): 133 <programlisting> 134 static void test_int (void) 135 { 136 GValue a_value = {0, }; 137 GValue b_value = {0, }; 138 guint64 a, b; 139 140 a = 0xdeadbeaf; 141 142 g_value_init (&a_value, G_TYPE_UINT64); 143 g_value_set_uint64 (&a_value, a); 144 145 g_value_init (&b_value, G_TYPE_UINT64); 146 g_value_copy (&a_value, &b_value); 147 148 b = g_value_get_uint64 (&b_value); 149 150 if (a == b) { 151 g_print ("Yay !! 10 lines of code to copy around a uint64.\n"); 152 } else { 153 g_print ("Are you sure this is not a Z80 ?\n"); 154 } 155 } 156 157 static void test_object (void) 158 { 159 GObject *obj; 160 GValue obj_vala = {0, }; 161 GValue obj_valb = {0, }; 162 obj = g_object_new (MAMAN_TYPE_BAR, NULL); 163 164 g_value_init (&obj_vala, MAMAN_TYPE_BAR); 165 g_value_set_object (&obj_vala, obj); 166 167 g_value_init (&obj_valb, G_TYPE_OBJECT); 168 169 /* g_value_copy's semantics for G_TYPE_OBJECT types is to copy the reference. 170 This function thus calls g_object_ref. 171 It is interesting to note that the assignment works here because 172 MAMAN_TYPE_BAR is a G_TYPE_OBJECT. 173 */ 174 g_value_copy (&obj_vala, &obj_valb); 175 176 g_object_unref (G_OBJECT (obj)); 177 g_object_unref (G_OBJECT (obj)); 178 } 179 </programlisting> 180 The important point about the above code is that the exact semantics of the copy calls 181 is undefined since they depend on the implementation of the copy function. Certain 182 copy functions might decide to allocate a new chunk of memory and then to copy the 183 data from the source to the destination. Others might want to simply increment 184 the reference count of the instance and copy the reference to the new GValue. 185 </para> 186 187 <para> 188 The value_table used to specify these assignment functions is defined in 189 <filename>gtype.h</filename> and is thoroughly described in the 190 API documentation provided with GObject (for once ;-) which is why we will 191 not detail its exact semantics. 192 <programlisting> 193 typedef struct _GTypeValueTable GTypeValueTable; 194 struct _GTypeValueTable 195 { 196 void (*value_init) (GValue *value); 197 void (*value_free) (GValue *value); 198 void (*value_copy) (const GValue *src_value, 199 GValue *dest_value); 200 /* varargs functionality (optional) */ 201 gpointer (*value_peek_pointer) (const GValue *value); 202 gchar *collect_format; 203 gchar* (*collect_value) (GValue *value, 204 guint n_collect_values, 205 GTypeCValue *collect_values, 206 guint collect_flags); 207 gchar *lcopy_format; 208 gchar* (*lcopy_value) (const GValue *value, 209 guint n_collect_values, 210 GTypeCValue *collect_values, 211 guint collect_flags); 212 }; 213 </programlisting> 214 Interestingly, it is also very unlikely 215 you will ever need to specify a value_table during type registration 216 because these value_tables are inherited from the parent types for 217 non-fundamental types which means that unless you want to write a 218 fundamental type (not a great idea!), you will not need to provide 219 a new value_table since you will inherit the value_table structure 220 from your parent type. 221 </para> 222 </sect1> 223 224 <sect1 id="gtype-conventions"> 225 <title>Conventions</title> 226 227 228 <para> 229 There are a number of conventions users are expected to follow when creating new types 230 which are to be exported in a header file: 231 <itemizedlist> 232 <listitem><para> 233 Use the <function>object_method</function> pattern for function names: to invoke 234 the method named foo on an instance of object type bar, call 235 <function>bar_foo</function>. 236 </para></listitem> 237 <listitem><para>Use prefixing to avoid namespace conflicts with other projects. 238 If your library (or application) is named <emphasis>Maman</emphasis>, 239 <footnote> 240 <para> 241 <emphasis>Maman</emphasis> is the French word for <emphasis>mum</emphasis> 242 or <emphasis>mother</emphasis> - nothing more and nothing less. 243 </para> 244 </footnote> 245 246 prefix all your function names with <emphasis>maman_</emphasis>. 247 For example: <function>maman_object_method</function>. 248 </para></listitem> 249 <listitem><para>Create a macro named <function>PREFIX_TYPE_OBJECT</function> which always 250 returns the GType for the associated object type. For an object of type 251 <emphasis>Bar</emphasis> in a libray prefixed by <emphasis>maman</emphasis>, 252 use: <function>MAMAN_TYPE_BAR</function>. 253 It is common although not a convention to implement this macro using either a global 254 static variable or a function named <function>prefix_object_get_type</function>. 255 We will follow the function pattern wherever possible in this document. 256 </para></listitem> 257 <listitem><para>Create a macro named <function>PREFIX_OBJECT (obj)</function> which 258 returns a pointer of type <type>PrefixObject</type>. This macro is used to enforce 259 static type safety by doing explicit casts wherever needed. It also enforces 260 dynamic type safety by doing runtime checks. It is possible to disable the dynamic 261 type checks in production builds (see <link linkend="glib-building">building glib</link>). 262 For example, we would create 263 <function>MAMAN_BAR (obj)</function> to keep the previous example. 264 </para></listitem> 265 <listitem><para>If the type is classed, create a macro named 266 <function>PREFIX_OBJECT_CLASS (klass)</function>. This macro 267 is strictly equivalent to the previous casting macro: it does static casting with 268 dynamic type checking of class structures. It is expected to return a pointer 269 to a class structure of type <type>PrefixObjectClass</type>. Again, an example is: 270 <function>MAMAN_BAR_CLASS</function>. 271 </para></listitem> 272 <listitem><para>Create a macro named <function>PREFIX_IS_BAR (obj)</function>: this macro is expected 273 to return a <type>gboolean</type> which indicates whether or not the input 274 object instance pointer of type BAR. 275 </para></listitem> 276 <listitem><para>If the type is classed, create a macro named 277 <function>PREFIX_IS_OBJECT_CLASS (klass)</function> which, as above, returns a boolean 278 if the input class pointer is a pointer to a class of type OBJECT. 279 </para></listitem> 280 <listitem><para>If the type is classed, create a macro named 281 <function>PREFIX_OBJECT_GET_CLASS (obj)</function> 282 which returns the class pointer associated to an instance of a given type. This macro 283 is used for static and dynamic type safety purposes (just like the previous casting 284 macros). 285 </para></listitem> 286 </itemizedlist> 287 The implementation of these macros is pretty straightforward: a number of simple-to-use 288 macros are provided in <filename>gtype.h</filename>. For the example we used above, we would 289 write the following trivial code to declare the macros: 290 <programlisting> 291 #define MAMAN_TYPE_BAR (maman_bar_get_type ()) 292 #define MAMAN_BAR(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), MAMAN_TYPE_BAR, MamanBar)) 293 #define MAMAN_BAR_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), MAMAN_TYPE_BAR, MamanBarClass)) 294 #define MAMAN_IS_BAR(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), MAMAN_TYPE_BAR)) 295 #define MAMAN_IS_BAR_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), MAMAN_TYPE_BAR)) 296 #define MAMAN_BAR_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), MAMAN_TYPE_BAR, MamanBarClass)) 297 </programlisting> 298 <note><simpara>Stick to the naming <varname>klass</varname> as <varname>class</varname> is a registered c++ keyword.</simpara></note> 299 </para> 300 301 <para> 302 The following code shows how to implement the <function>maman_bar_get_type</function> 303 function: 304 <programlisting> 305 GType maman_bar_get_type (void) 306 { 307 static GType type = 0; 308 if (type == 0) { 309 static const GTypeInfo info = { 310 /* You fill this structure. */ 311 }; 312 type = g_type_register_static (G_TYPE_OBJECT, 313 "MamanBarType", 314 &info, 0); 315 } 316 return type; 317 } 318 </programlisting> 319 </para> 320 321 <para> 322 When having no special requirements you also can use the <function>G_DEFINE_TYPE</function> 323 macro: 324 <programlisting> 325 G_DEFINE_TYPE (MamanBar, maman_bar, G_TYPE_OBJECT) 326 </programlisting> 327 </para> 328 329 </sect1> 330 331 <sect1 id="gtype-non-instantiable"> 332 <title>Non-instantiable non-classed fundamental types</title> 333 334 <para> 335 A lot of types are not instantiable by the type system and do not have 336 a class. Most of these types are fundamental trivial types such as <emphasis>gchar</emphasis>, 337 registered in <function>g_value_types_init</function> (in <filename>gvaluetypes.c</filename>). 338 </para> 339 340 <para> 341 To register such a type in the type system, you just need to fill the 342 <type><link linkend="GTypeInfo">GTypeInfo</link></type> structure with zeros since these types are also most of the time 343 fundamental: 344 <programlisting> 345 GTypeInfo info = { 346 0, /* class_size */ 347 NULL, /* base_init */ 348 NULL, /* base_destroy */ 349 NULL, /* class_init */ 350 NULL, /* class_destroy */ 351 NULL, /* class_data */ 352 0, /* instance_size */ 353 0, /* n_preallocs */ 354 NULL, /* instance_init */ 355 NULL, /* value_table */ 356 }; 357 static const GTypeValueTable value_table = { 358 value_init_long0, /* value_init */ 359 NULL, /* value_free */ 360 value_copy_long0, /* value_copy */ 361 NULL, /* value_peek_pointer */ 362 "i", /* collect_format */ 363 value_collect_int, /* collect_value */ 364 "p", /* lcopy_format */ 365 value_lcopy_char, /* lcopy_value */ 366 }; 367 info.value_table = &value_table; 368 type = g_type_register_fundamental (G_TYPE_CHAR, "gchar", &info, &finfo, 0); 369 </programlisting> 370 </para> 371 372 373 <para> 374 Having non-instantiable types might seem a bit useless: what good is a type 375 if you cannot instantiate an instance of that type ? Most of these types 376 are used in conjunction with <type><link linkend="GValue">GValue</link></type>s: a GValue is initialized 377 with an integer or a string and it is passed around by using the registered 378 type's value_table. <type><link linkend="GValue">GValue</link></type>s (and by extension these trivial fundamental 379 types) are most useful when used in conjunction with object properties and signals. 380 </para> 381 382 </sect1> 383 384 <sect1 id="gtype-instantiable-classed"> 385 <title>Instantiable classed types: objects</title> 386 387 <para> 388 Types which are registered with a class and are declared instantiable are 389 what most closely resembles an <emphasis>object</emphasis>. 390 Although <type><link linkend="GObject">GObject</link></type>s (detailed in <xref linkend="chapter-gobject"/>) 391 are the most well known type of instantiable 392 classed types, other kinds of similar objects used as the base of an inheritance 393 hierarchy have been externally developed and they are all built on the fundamental 394 features described below. 395 </para> 396 397 <para> 398 For example, the code below shows how you could register 399 such a fundamental object type in the type system: 400 <programlisting> 401 typedef struct { 402 GObject parent; 403 /* instance members */ 404 int field_a; 405 } MamanBar; 406 407 typedef struct { 408 GObjectClass parent; 409 /* class members */ 410 void (*do_action_public_virtual) (MamanBar *self, guint8 i); 411 412 void (*do_action_public_pure_virtual) (MamanBar *self, guint8 i); 413 } MamanBarClass; 414 415 #define MAMAN_TYPE_BAR (maman_bar_get_type ()) 416 417 GType 418 maman_bar_get_type (void) 419 { 420 static GType type = 0; 421 if (type == 0) { 422 static const GTypeInfo info = { 423 sizeof (MamanBarClass), 424 NULL, /* base_init */ 425 NULL, /* base_finalize */ 426 (GClassInitFunc) foo_class_init, 427 NULL, /* class_finalize */ 428 NULL, /* class_data */ 429 sizeof (MamanBar), 430 0, /* n_preallocs */ 431 (GInstanceInitFunc) NULL /* instance_init */ 432 }; 433 type = g_type_register_static (G_TYPE_OBJECT, 434 "BarType", 435 &info, 0); 436 } 437 return type; 438 } 439 </programlisting> 440 Upon the first call to <function>maman_bar_get_type</function>, the type named 441 <emphasis>BarType</emphasis> will be registered in the type system as inheriting 442 from the type <emphasis>G_TYPE_OBJECT</emphasis>. 443 </para> 444 445 <para> 446 Every object must define two structures: its class structure and its 447 instance structure. All class structures must contain as first member 448 a <type><link linkend="GTypeClass">GTypeClass</link></type> structure. All instance structures must contain as first 449 member a <type><link linkend="GTypeInstance">GTypeInstance</link></type> structure. The declaration of these C types, 450 coming from <filename>gtype.h</filename> is shown below: 451 <programlisting> 452 struct _GTypeClass 453 { 454 GType g_type; 455 }; 456 struct _GTypeInstance 457 { 458 GTypeClass *g_class; 459 }; 460 </programlisting> 461 These constraints allow the type system to make sure that every object instance 462 (identified by a pointer to the object's instance structure) contains in its 463 first bytes a pointer to the object's class structure. 464 </para> 465 <para> 466 This relationship is best explained by an example: let's take object B which 467 inherits from object A: 468 <programlisting> 469 /* A definitions */ 470 typedef struct { 471 GTypeInstance parent; 472 int field_a; 473 int field_b; 474 } A; 475 typedef struct { 476 GTypeClass parent_class; 477 void (*method_a) (void); 478 void (*method_b) (void); 479 } AClass; 480 481 /* B definitions. */ 482 typedef struct { 483 A parent; 484 int field_c; 485 int field_d; 486 } B; 487 typedef struct { 488 AClass parent_class; 489 void (*method_c) (void); 490 void (*method_d) (void); 491 } BClass; 492 </programlisting> 493 The C standard mandates that the first field of a C structure is stored starting 494 in the first byte of the buffer used to hold the structure's fields in memory. 495 This means that the first field of an instance of an object B is A's first field 496 which in turn is GTypeInstance's first field which in turn is g_class, a pointer 497 to B's class structure. 498 </para> 499 500 <para> 501 Thanks to these simple conditions, it is possible to detect the type of every 502 object instance by doing: 503 <programlisting> 504 B *b; 505 b->parent.parent.g_class->g_type 506 </programlisting> 507 or, more quickly: 508 <programlisting> 509 B *b; 510 ((GTypeInstance*)b)->g_class->g_type 511 </programlisting> 512 </para> 513 514 <sect2 id="gtype-instantiable-classed-init-done"> 515 <title>Initialization and Destruction</title> 516 517 <para> 518 instantiation of these types can be done with 519 <function><link linkend="g-type-create-instance">g_type_create_instance</link></function>: 520 <programlisting> 521 GTypeInstance* g_type_create_instance (GType type); 522 void g_type_free_instance (GTypeInstance *instance); 523 </programlisting> 524 <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> will look up the type information 525 structure associated to the type requested. Then, the instance size and instantiation 526 policy (if the n_preallocs field is set to a non-zero value, the type system allocates 527 the object's instance structures in chunks rather than mallocing for every instance) 528 declared by the user are used to get a buffer to hold the object's instance 529 structure. 530 </para> 531 532 <para> 533 If this is the first instance of the object ever created, the type system must create 534 a class structure: it allocates a buffer to hold the object's class structure and 535 initializes it. It first copies the parent's class structure over this structure 536 (if there is no parent, it initializes it to zero). It then invokes the 537 base_class_initialization functions (<type><link linkend="GBaseInitFunc">GBaseInitFunc</link></type>) from topmost 538 fundamental object to bottom-most most derived object. The object's class_init 539 (<type><link linkend="GClassInitFunc">GClassInitFunc</link></type>) function is invoked afterwards to complete 540 initialization of the class structure. 541 Finally, the object's interfaces are initialized (we will discuss interface initialization 542 in more detail later). 543 </para> 544 545 <para> 546 Once the type system has a pointer to an initialized class structure, it sets the object's 547 instance class pointer to the object's class structure and invokes the object's 548 instance_init (<type><link linkend="GInstanceInitFunc">GInstanceInitFunc</link></type>)functions, from top-most fundamental 549 type to bottom-most most derived type. 550 </para> 551 552 <para> 553 Object instance destruction through <function><link linkend="g-type-free-instance">g_type_free_instance</link></function> is very simple: 554 the instance structure is returned to the instance pool if there is one and if this was the 555 last living instance of the object, the class is destroyed. 556 </para> 557 558 559 <para> 560 Class destruction (the concept of destruction is sometimes partly 561 referred to as finalization in GType) is the symmetric process of 562 the initialization: interfaces are destroyed first. 563 Then, the most derived 564 class_finalize (<type><link linkend="ClassFinalizeFunc">ClassFinalizeFunc</link></type>) function is invoked. The 565 base_class_finalize (<type><link linkend="GBaseFinalizeFunc">GBaseFinalizeFunc</link></type>) functions are 566 Finally invoked from bottom-most most-derived type to top-most fundamental type and 567 the class structure is freed. 568 </para> 569 570 <para> 571 As many readers have now understood it, the base initialization/finalization process is 572 very similar to the C++ constructor/destructor paradigm. The practical details are different 573 though and it is important not to get confused by superficial similarities. 574 GTypes have no instance destruction mechanism. It is 575 the user's responsibility to implement correct destruction semantics on top 576 of the existing GType code. (this is what GObject does. See 577 <xref linkend="chapter-gobject"/>) 578 Furthermore, C++ code equivalent to the base_init 579 and class_init callbacks of GType is usually not needed because C++ cannot really create object 580 types at runtime. 581 </para> 582 583 <para> 584 The instantiation/finalization process can be summarized as follows: 585 <table id="gtype-init-fini-table"> 586 <title>GType Instantiation/Finalization</title> 587 <tgroup cols="3"> 588 <colspec colwidth="*" colnum="1" align="left"/> 589 <colspec colwidth="*" colnum="2" align="left"/> 590 <colspec colwidth="8*" colnum="3" align="left"/> 591 592 <thead> 593 <row> 594 <entry>Invocation time</entry> 595 <entry>Function Invoked</entry> 596 <entry>Function's parameters</entry> 597 </row> 598 </thead> 599 <tbody> 600 <row> 601 <entry morerows="2">First call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> for target type</entry> 602 <entry>type's base_init function</entry> 603 <entry>On the inheritance tree of classes from fundamental type to target type. 604 base_init is invoked once for each class structure.</entry> 605 </row> 606 <row> 607 <!--entry>First call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> for target type</entry--> 608 <entry>target type's class_init function</entry> 609 <entry>On target type's class structure</entry> 610 </row> 611 <row> 612 <!--entry>First call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> for target type</entry--> 613 <entry>interface initialization, see 614 <xref linkend="gtype-non-instantiable-classed-init"/></entry> 615 <entry></entry> 616 </row> 617 <row> 618 <entry>Each call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> for target type</entry> 619 <entry>target type's instance_init function</entry> 620 <entry>On object's instance</entry> 621 </row> 622 <row> 623 <entry morerows="2">Last call to <function><link linkend="g-type-free-instance">g_type_free_instance</link></function> for target type</entry> 624 <entry>interface destruction, see 625 <xref linkend="gtype-non-instantiable-classed-dest"/></entry> 626 <entry></entry> 627 </row> 628 <row> 629 <!--entry>Last call to <function><link linkend="g-type-free-instance">g_type_free_instance</link></function> for target type</entry--> 630 <entry>target type's class_finalize function</entry> 631 <entry>On target type's class structure</entry> 632 </row> 633 <row> 634 <!--entry>Last call to <function><link linkend="g-type-free-instance">g_type_free_instance</link></function> for target type</entry--> 635 <entry>type's base_finalize function</entry> 636 <entry>On the inheritance tree of classes from fundamental type to target type. 637 base_finalize is invoked once for each class structure.</entry> 638 </row> 639 </tbody> 640 </tgroup> 641 </table> 642 </para> 643 644 </sect2> 645 646 </sect1> 647 648 <sect1 id="gtype-non-instantiable-classed"> 649 <title>Non-instantiable classed types: interfaces</title> 650 651 <para> 652 GType's interfaces are very similar to Java's interfaces. They allow 653 to describe a common API that several classes will adhere to. 654 Imagine the play, pause and stop buttons on hi-fi equipment - those can 655 be seen as a playback interface. Once you know what they do, you can 656 control your CD player, MP3 player or anything that uses these symbols. 657 To declare an interface you have to register a non-instantiable 658 classed type which derives from 659 <type><link linkend="GTypeInterface">GTypeInterface</link></type>. The following piece of code declares such an interface. 660 <programlisting> 661 #define MAMAN_IBAZ_TYPE (maman_ibaz_get_type ()) 662 #define MAMAN_IBAZ(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), MAMAN_IBAZ_TYPE, MamanIbaz)) 663 #define MAMAN_IS_IBAZ(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), MAMAN_IBAZ_TYPE)) 664 #define MAMAN_IBAZ_GET_INTERFACE(inst) (G_TYPE_INSTANCE_GET_INTERFACE ((inst), MAMAN_IBAZ_TYPE, MamanIbazInterface)) 665 666 typedef struct _MamanIbaz MamanIbaz; /* dummy object */ 667 typedef struct _MamanIbazInterface MamanIbazInterface; 668 669 struct _MamanIbazInterface { 670 GTypeInterface parent; 671 672 void (*do_action) (MamanIbaz *self); 673 }; 674 675 GType maman_ibaz_get_type (void); 676 677 void maman_ibaz_do_action (MamanIbaz *self); 678 </programlisting> 679 The interface function, <function>maman_ibaz_do_action</function> is implemented 680 in a pretty simple way: 681 <programlisting> 682 void maman_ibaz_do_action (MamanIbaz *self) 683 { 684 MAMAN_IBAZ_GET_INTERFACE (self)->do_action (self); 685 } 686 </programlisting> 687 <function>maman_ibaz_get_type</function> registers a type named <emphasis>MamanIBaz</emphasis> 688 which inherits from G_TYPE_INTERFACE. All interfaces must be children of G_TYPE_INTERFACE in the 689 inheritance tree. 690 </para> 691 692 <para> 693 An interface is defined by only one structure which must contain as first member 694 a <type><link linkend="GTypeInterface">GTypeInterface</link></type> structure. The interface structure is expected to 695 contain the function pointers of the interface methods. It is good style to 696 define helper functions for each of the interface methods which simply call 697 the interface' method directly: <function>maman_ibaz_do_action</function> 698 is one of these. 699 </para> 700 701 <para> 702 Once an interface type is registered, you must register implementations for these 703 interfaces. The function named <function>maman_baz_get_type</function> registers 704 a new GType named MamanBaz which inherits from <type><link linkend="GObject">GObject</link></type> and which 705 implements the interface <type>MamanIBaz</type>. 706 <programlisting> 707 static void maman_baz_do_action (MamanIbaz *self) 708 { 709 g_print ("Baz implementation of IBaz interface Action.\n"); 710 } 711 712 713 static void 714 baz_interface_init (gpointer g_iface, 715 gpointer iface_data) 716 { 717 MamanIbazInterface *iface = (MamanIbazInterface *)g_iface; 718 iface->do_action = maman_baz_do_action; 719 } 720 721 GType 722 maman_baz_get_type (void) 723 { 724 static GType type = 0; 725 if (type == 0) { 726 static const GTypeInfo info = { 727 sizeof (MamanBazInterface), 728 NULL, /* base_init */ 729 NULL, /* base_finalize */ 730 NULL, /* class_init */ 731 NULL, /* class_finalize */ 732 NULL, /* class_data */ 733 sizeof (MamanBaz), 734 0, /* n_preallocs */ 735 NULL /* instance_init */ 736 }; 737 static const GInterfaceInfo ibaz_info = { 738 (GInterfaceInitFunc) baz_interface_init, /* interface_init */ 739 NULL, /* interface_finalize */ 740 NULL /* interface_data */ 741 }; 742 type = g_type_register_static (G_TYPE_OBJECT, 743 "MamanBazType", 744 &info, 0); 745 g_type_add_interface_static (type, 746 MAMAN_IBAZ_TYPE, 747 &ibaz_info); 748 } 749 return type; 750 } 751 </programlisting> 752 </para> 753 754 <para> 755 <function><link linkend="g-type-add-interface-static">g_type_add_interface_static</link></function> records in the type system that 756 a given type implements also <type>FooInterface</type> 757 (<function>foo_interface_get_type</function> returns the type of 758 <type>FooInterface</type>). 759 The <type><link linkend="GInterfaceInfo">GInterfaceInfo</link></type> structure holds 760 information about the implementation of the interface: 761 <programlisting> 762 struct _GInterfaceInfo 763 { 764 GInterfaceInitFunc interface_init; 765 GInterfaceFinalizeFunc interface_finalize; 766 gpointer interface_data; 767 }; 768 </programlisting> 769 </para> 770 771 <sect2 id="gtype-non-instantiable-classed-init"> 772 <title>Interface Initialization</title> 773 774 <para> 775 When an instantiable classed type which registered an interface 776 implementation is created for the first time, its class structure 777 is initialized following the process 778 described in <xref linkend="gtype-instantiable-classed"/>. 779 After that, the interface implementations associated with 780 the type are initialized. 781 </para> 782 783 <para> 784 First a memory buffer is allocated to hold the interface structure. The parent's 785 interface structure is then copied over to the new interface structure (the parent 786 interface is already initialized at that point). If there is no parent interface, 787 the interface structure is initialized with zeros. The g_type and the g_instance_type 788 fields are then initialized: g_type is set to the type of the most-derived interface 789 and g_instance_type is set to the type of the most derived type which implements 790 this interface. 791 </para> 792 793 <para> 794 Finally, the interface' most-derived <function>base_init</function> function and then 795 the implementation's <function>interface_init</function> 796 function are invoked. It is important to understand that if there are multiple 797 implementations of an interface the <function>base_init</function> and 798 <function>interface_init</function> functions will be 799 invoked once for each implementation initialized. 800 </para> 801 802 <para> 803 It is thus common for base_init functions to hold a local static boolean variable 804 which makes sure that the interface type is initialized only once even if there are 805 multiple implementations of the interface: 806 <programlisting> 807 static void 808 maman_ibaz_base_init (gpointer g_iface) 809 { 810 static gboolean initialized = FALSE; 811 812 if (!initialized) { 813 /* create interface signals here. */ 814 initialized = TRUE; 815 } 816 } 817 </programlisting> 818 </para> 819 820 <para> 821 If you have found the stuff about interface hairy, you are right: it is hairy but 822 there is not much I can do about it. What I can do is summarize what you need to know 823 about interfaces: 824 </para> 825 826 <para> 827 The above process can be summarized as follows: 828 <table id="ginterface-init-table"> 829 <title>Interface Initialization</title> 830 <tgroup cols="3"> 831 <colspec colwidth="*" colnum="1" align="left"/> 832 <colspec colwidth="*" colnum="2" align="left"/> 833 <colspec colwidth="8*" colnum="3" align="left"/> 834 835 <thead> 836 <row> 837 <entry>Invocation time</entry> 838 <entry>Function Invoked</entry> 839 <entry>Function's parameters</entry> 840 <entry>Remark</entry> 841 </row> 842 </thead> 843 <tbody> 844 <row> 845 <entry morerows="1">First call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> for type 846 implementing interface 847 </entry> 848 <entry>interface' base_init function</entry> 849 <entry>On interface' vtable</entry> 850 <entry>Register interface' signals here (use a local static 851 boolean variable as described above to make sure not to register them 852 twice.).</entry> 853 </row> 854 <row> 855 <!--entry>First call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> for type 856 implementing interface 857 </entry--> 858 <entry>interface' interface_init function</entry> 859 <entry>On interface' vtable</entry> 860 <entry> 861 Initialize interface' implementation. That is, initialize the interface 862 method pointers in the interface structure to the function's implementation. 863 </entry> 864 </row> 865 </tbody> 866 </tgroup> 867 </table> 868 It is highly unlikely (i.e. I do not know of <emphasis>anyone</emphasis> who actually 869 used it) you will ever need other more fancy things such as the ones described in the 870 following section (<xref linkend="gtype-non-instantiable-classed-dest"/>). 871 </para> 872 873 </sect2> 874 875 <sect2 id="gtype-non-instantiable-classed-dest"> 876 <title>Interface Destruction</title> 877 878 <para> 879 When the last instance of an instantiable type which registered 880 an interface implementation is destroyed, the interface's 881 implementations associated to the type are destroyed. 882 </para> 883 884 <para> 885 To destroy an interface implementation, GType first calls the 886 implementation's <function>interface_finalize</function> function 887 and then the interface's most-derived 888 <function>base_finalize</function> function. 889 </para> 890 891 <para> 892 Again, it is important to understand, as in 893 <xref linkend="gtype-non-instantiable-classed-init"/>, 894 that both <function>interface_finalize</function> and <function>base_finalize</function> 895 are invoked exactly once for the destruction of each implementation of an interface. Thus, 896 if you were to use one of these functions, you would need to use a static integer variable 897 which would hold the number of instances of implementations of an interface such that 898 the interface's class is destroyed only once (when the integer variable reaches zero). 899 </para> 900 901 <para> 902 The above process can be summarized as follows: 903 <table id="ginterface-init-table"> 904 <title>Interface Finalization</title> 905 <tgroup cols="3"> 906 <colspec colwidth="*" colnum="1" align="left"/> 907 <colspec colwidth="*" colnum="2" align="left"/> 908 <colspec colwidth="8*" colnum="3" align="left"/> 909 910 <thead> 911 <row> 912 <entry>Invocation time</entry> 913 <entry>Function Invoked</entry> 914 <entry>Function's parameters</entry> 915 </row> 916 </thead> 917 <tbody> 918 <row> 919 <entry morerows="1">Last call to <function><link linkend="g-type-free-instance">g_type_free_instance</link></function> for type 920 implementing interface 921 </entry> 922 <entry>interface' interface_finalize function</entry> 923 <entry>On interface' vtable</entry> 924 </row> 925 <row> 926 <!--entry>Last call to <function><link linkend="g-type-free-instance">g_type_free_instance</link></function>for type 927 implementing interface 928 </entry--> 929 <entry>interface' base_finalize function</entry> 930 <entry>On interface' vtable</entry> 931 </row> 932 </tbody> 933 </tgroup> 934 </table> 935 </para> 936 </sect2> 937 </sect1> 938 </chapter> 939
