| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| <title>Instantiable classed types: objects</title> |
| <meta name="generator" content="DocBook XSL Stylesheets V1.75.2"> |
| <link rel="home" href="index.html" title="GObject Reference Manual"> |
| <link rel="up" href="chapter-gtype.html" title="The GLib Dynamic Type System"> |
| <link rel="prev" href="gtype-non-instantiable.html" title="Non-instantiable non-classed fundamental types"> |
| <link rel="next" href="gtype-non-instantiable-classed.html" title="Non-instantiable classed types: interfaces"> |
| <meta name="generator" content="GTK-Doc V1.14 (XML mode)"> |
| <link rel="stylesheet" href="style.css" type="text/css"> |
| </head> |
| <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
| <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle"> |
| <td><a accesskey="p" href="gtype-non-instantiable.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td> |
| <td><a accesskey="u" href="chapter-gtype.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td> |
| <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td> |
| <th width="100%" align="center">GObject Reference Manual</th> |
| <td><a accesskey="n" href="gtype-non-instantiable-classed.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td> |
| </tr></table> |
| <div class="sect1" title="Instantiable classed types: objects"> |
| <div class="titlepage"><div><div><h2 class="title" style="clear: both"> |
| <a name="gtype-instantiable-classed"></a>Instantiable classed types: objects</h2></div></div></div> |
| <p> |
| Types which are registered with a class and are declared instantiable are |
| what most closely resembles an <span class="emphasis"><em>object</em></span>. |
| Although <span class="type"><a class="link" href="gobject-The-Base-Object-Type.html#GObject">GObject</a></span>s (detailed in <a class="xref" href="chapter-gobject.html" title="The GObject base class"><i>The GObject base class</i></a>) |
| are the most well known type of instantiable |
| classed types, other kinds of similar objects used as the base of an inheritance |
| hierarchy have been externally developed and they are all built on the fundamental |
| features described below. |
| </p> |
| <p> |
| For example, the code below shows how you could register |
| such a fundamental object type in the type system: |
| </p> |
| <pre class="programlisting"> |
| typedef struct { |
| GObject parent; |
| /* instance members */ |
| int field_a; |
| } MamanBar; |
| |
| typedef struct { |
| GObjectClass parent; |
| /* class members */ |
| void (*do_action_public_virtual) (MamanBar *self, guint8 i); |
| |
| void (*do_action_public_pure_virtual) (MamanBar *self, guint8 i); |
| } MamanBarClass; |
| |
| #define MAMAN_TYPE_BAR (maman_bar_get_type ()) |
| |
| GType |
| maman_bar_get_type (void) |
| { |
| static GType type = 0; |
| if (type == 0) { |
| static const GTypeInfo info = { |
| sizeof (MamanBarClass), |
| NULL, /* base_init */ |
| NULL, /* base_finalize */ |
| (GClassInitFunc) foo_class_init, |
| NULL, /* class_finalize */ |
| NULL, /* class_data */ |
| sizeof (MamanBar), |
| 0, /* n_preallocs */ |
| (GInstanceInitFunc) NULL /* instance_init */ |
| }; |
| type = g_type_register_static (G_TYPE_OBJECT, |
| "BarType", |
| &info, 0); |
| } |
| return type; |
| } |
| </pre> |
| <p> |
| Upon the first call to <code class="function">maman_bar_get_type</code>, the type named |
| <span class="emphasis"><em>BarType</em></span> will be registered in the type system as inheriting |
| from the type <span class="emphasis"><em>G_TYPE_OBJECT</em></span>. |
| </p> |
| <p> |
| Every object must define two structures: its class structure and its |
| instance structure. All class structures must contain as first member |
| a <span class="type"><a class="link" href="gobject-Type-Information.html#GTypeClass" title="GTypeClass">GTypeClass</a></span> structure. All instance structures must contain as first |
| member a <span class="type"><a class="link" href="gobject-Type-Information.html#GTypeInstance" title="GTypeInstance">GTypeInstance</a></span> structure. The declaration of these C types, |
| coming from <code class="filename">gtype.h</code> is shown below: |
| </p> |
| <pre class="programlisting"> |
| struct _GTypeClass |
| { |
| GType g_type; |
| }; |
| struct _GTypeInstance |
| { |
| GTypeClass *g_class; |
| }; |
| </pre> |
| <p> |
| These constraints allow the type system to make sure that every object instance |
| (identified by a pointer to the object's instance structure) contains in its |
| first bytes a pointer to the object's class structure. |
| </p> |
| <p> |
| This relationship is best explained by an example: let's take object B which |
| inherits from object A: |
| </p> |
| <pre class="programlisting"> |
| /* A definitions */ |
| typedef struct { |
| GTypeInstance parent; |
| int field_a; |
| int field_b; |
| } A; |
| typedef struct { |
| GTypeClass parent_class; |
| void (*method_a) (void); |
| void (*method_b) (void); |
| } AClass; |
| |
| /* B definitions. */ |
| typedef struct { |
| A parent; |
| int field_c; |
| int field_d; |
| } B; |
| typedef struct { |
| AClass parent_class; |
| void (*method_c) (void); |
| void (*method_d) (void); |
| } BClass; |
| </pre> |
| <p> |
| The C standard mandates that the first field of a C structure is stored starting |
| in the first byte of the buffer used to hold the structure's fields in memory. |
| This means that the first field of an instance of an object B is A's first field |
| which in turn is GTypeInstance's first field which in turn is g_class, a pointer |
| to B's class structure. |
| </p> |
| <p> |
| Thanks to these simple conditions, it is possible to detect the type of every |
| object instance by doing: |
| </p> |
| <pre class="programlisting"> |
| B *b; |
| b->parent.parent.g_class->g_type |
| </pre> |
| <p> |
| or, more quickly: |
| </p> |
| <pre class="programlisting"> |
| B *b; |
| ((GTypeInstance*)b)->g_class->g_type |
| </pre> |
| <p> |
| </p> |
| <div class="sect2" title="Initialization and Destruction"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="gtype-instantiable-classed-init-done"></a>Initialization and Destruction</h3></div></div></div> |
| <p> |
| instantiation of these types can be done with |
| <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-create-instance" title="g_type_create_instance ()">g_type_create_instance</a></code>: |
| </p> |
| <pre class="programlisting"> |
| GTypeInstance* g_type_create_instance (GType type); |
| void g_type_free_instance (GTypeInstance *instance); |
| </pre> |
| <p> |
| <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-create-instance" title="g_type_create_instance ()">g_type_create_instance</a></code> will look up the type information |
| structure associated to the type requested. Then, the instance size and instantiation |
| policy (if the n_preallocs field is set to a non-zero value, the type system allocates |
| the object's instance structures in chunks rather than mallocing for every instance) |
| declared by the user are used to get a buffer to hold the object's instance |
| structure. |
| </p> |
| <p> |
| If this is the first instance of the object ever created, the type system must create |
| a class structure: it allocates a buffer to hold the object's class structure and |
| initializes it. It first copies the parent's class structure over this structure |
| (if there is no parent, it initializes it to zero). It then invokes the |
| base_class_initialization functions (<span class="type"><a class="link" href="gobject-Type-Information.html#GBaseInitFunc" title="GBaseInitFunc ()">GBaseInitFunc</a></span>) from topmost |
| fundamental object to bottom-most most derived object. The object's class_init |
| (<span class="type"><a class="link" href="gobject-Type-Information.html#GClassInitFunc" title="GClassInitFunc ()">GClassInitFunc</a></span>) function is invoked afterwards to complete |
| initialization of the class structure. |
| Finally, the object's interfaces are initialized (we will discuss interface initialization |
| in more detail later). |
| </p> |
| <p> |
| Once the type system has a pointer to an initialized class structure, it sets the object's |
| instance class pointer to the object's class structure and invokes the object's |
| instance_init (<span class="type"><a class="link" href="gobject-Type-Information.html#GInstanceInitFunc" title="GInstanceInitFunc ()">GInstanceInitFunc</a></span>)functions, from top-most fundamental |
| type to bottom-most most derived type. |
| </p> |
| <p> |
| Object instance destruction through <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-free-instance" title="g_type_free_instance ()">g_type_free_instance</a></code> is very simple: |
| the instance structure is returned to the instance pool if there is one and if this was the |
| last living instance of the object, the class is destroyed. |
| </p> |
| <p> |
| Class destruction (the concept of destruction is sometimes partly |
| referred to as finalization in GType) is the symmetric process of |
| the initialization: interfaces are destroyed first. |
| Then, the most derived |
| class_finalize (<span class="type">ClassFinalizeFunc</span>) function is invoked. The |
| base_class_finalize (<span class="type"><a class="link" href="gobject-Type-Information.html#GBaseFinalizeFunc" title="GBaseFinalizeFunc ()">GBaseFinalizeFunc</a></span>) functions are |
| Finally invoked from bottom-most most-derived type to top-most fundamental type and |
| the class structure is freed. |
| </p> |
| <p> |
| As many readers have now understood it, the base initialization/finalization process is |
| very similar to the C++ constructor/destructor paradigm. The practical details are different |
| though and it is important not to get confused by superficial similarities. |
| GTypes have no instance destruction mechanism. It is |
| the user's responsibility to implement correct destruction semantics on top |
| of the existing GType code. (this is what GObject does. See |
| <a class="xref" href="chapter-gobject.html" title="The GObject base class"><i>The GObject base class</i></a>) |
| Furthermore, C++ code equivalent to the base_init |
| and class_init callbacks of GType is usually not needed because C++ cannot really create object |
| types at runtime. |
| </p> |
| <p> |
| The instantiation/finalization process can be summarized as follows: |
| </p> |
| <div class="table"> |
| <a name="gtype-init-fini-table"></a><p class="title"><b>Table 1. GType Instantiation/Finalization</b></p> |
| <div class="table-contents"><table summary="GType Instantiation/Finalization" border="1"> |
| <colgroup> |
| <col align="left"> |
| <col align="left"> |
| <col align="left"> |
| </colgroup> |
| <thead><tr> |
| <th align="left">Invocation time</th> |
| <th align="left">Function Invoked</th> |
| <th align="left">Function's parameters</th> |
| </tr></thead> |
| <tbody> |
| <tr> |
| <td rowspan="3" align="left">First call to <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-create-instance" title="g_type_create_instance ()">g_type_create_instance</a></code> for target type</td> |
| <td align="left">type's base_init function</td> |
| <td align="left">On the inheritance tree of classes from fundamental type to target type. |
| base_init is invoked once for each class structure.</td> |
| </tr> |
| <tr> |
| <td align="left">target type's class_init function</td> |
| <td align="left">On target type's class structure</td> |
| </tr> |
| <tr> |
| <td align="left">interface initialization, see |
| <a class="xref" href="gtype-non-instantiable-classed.html#gtype-non-instantiable-classed-init" title="Interface Initialization">the section called “Interface Initialization”</a> |
| </td> |
| <td align="left"> </td> |
| </tr> |
| <tr> |
| <td align="left">Each call to <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-create-instance" title="g_type_create_instance ()">g_type_create_instance</a></code> for target type</td> |
| <td align="left">target type's instance_init function</td> |
| <td align="left">On object's instance</td> |
| </tr> |
| <tr> |
| <td rowspan="3" align="left">Last call to <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-free-instance" title="g_type_free_instance ()">g_type_free_instance</a></code> for target type</td> |
| <td align="left">interface destruction, see |
| <a class="xref" href="gtype-non-instantiable-classed.html#gtype-non-instantiable-classed-dest" title="Interface Destruction">the section called “Interface Destruction”</a> |
| </td> |
| <td align="left"> </td> |
| </tr> |
| <tr> |
| <td align="left">target type's class_finalize function</td> |
| <td align="left">On target type's class structure</td> |
| </tr> |
| <tr> |
| <td align="left">type's base_finalize function</td> |
| <td align="left">On the inheritance tree of classes from fundamental type to target type. |
| base_finalize is invoked once for each class structure.</td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <p><br class="table-break"> |
| </p> |
| </div> |
| </div> |
| <div class="footer"> |
| <hr> |
| Generated by GTK-Doc V1.14</div> |
| </body> |
| </html> |
