docs/reference/gobject/html/gtype-instantiable-classed.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>Instantiable classed types: objects: GObject Reference Manual</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   7 <link rel="home" href="index.html" title="GObject Reference Manual">
   8 <link rel="up" href="chapter-gtype.html" title="The GLib Dynamic Type System">
   9 <link rel="prev" href="gtype-non-instantiable.html" title="Non-instantiable non-classed fundamental types">
  10 <link rel="next" href="gtype-non-instantiable-classed.html" title="Non-instantiable classed types: interfaces">
  11 <meta name="generator" content="GTK-Doc V1.25.1 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
  16 <td width="100%" align="left" class="shortcuts"></td>
  17 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
  18 <td><a accesskey="u" href="chapter-gtype.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
  19 <td><a accesskey="p" href="gtype-non-instantiable.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
  20 <td><a accesskey="n" href="gtype-non-instantiable-classed.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
  21 </tr></table>
  22 <div class="sect1">
  23 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  24 <a name="gtype-instantiable-classed"></a>Instantiable classed types: objects</h2></div></div></div>
  25 <p>
  26           This section covers the theory behind objects. See
  27           <a class="xref" href="howto-gobject.html" title="How to define and implement a new GObject"><i>How to define and implement a new GObject</i></a> for the recommended way to define a
  28           GObject.
  29         </p>
  30 <p>
  31           Types which are registered with a class and are declared instantiable are
  32           what most closely resembles an <span class="emphasis"><em>object</em></span>.
  33           Although <a class="link" href="gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a>s (detailed in <a class="xref" href="chapter-gobject.html" title="The GObject base class"><i>The GObject base class</i></a>)
  34           are the most well known type of instantiable
  35           classed types, other kinds of similar objects used as the base of an inheritance
  36           hierarchy have been externally developed and they are all built on the fundamental
  37           features described below.
  38         </p>
  39 <p>
  40           For example, the code below shows how you could register
  41           such a fundamental object type in the type system (using none of the
  42           GObject convenience API):
  43 </p>
  44 <div class="informalexample">
  45   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
  46     <tbody>
  47       <tr>
  48         <td class="listing_lines" align="right"><pre>1
  49 2
  50 3
  51 4
  52 5
  53 6
  54 7
  55 8
  56 9
  57 10
  58 11
  59 12
  60 13
  61 14
  62 15
  63 16
  64 17
  65 18
  66 19
  67 20
  68 21
  69 22
  70 23
  71 24
  72 25
  73 26
  74 27
  75 28
  76 29
  77 30
  78 31
  79 32
  80 33
  81 34
  82 35
  83 36
  84 37
  85 38
  86 39
  87 40
  88 41
  89 42
  90 43
  91 44</pre></td>
  92         <td class="listing_code"><pre class="programlisting"><span class="gtkdoc kwc">typedef</span> <span class="gtkdoc kwb">struct</span> <span class="gtkdoc opt">{</span>
  93   GObject parent<span class="gtkdoc opt">;</span>
  94
  95   <span class="comment">/* instance members */</span>
  96   gchar <span class="gtkdoc opt">*</span>filename<span class="gtkdoc opt">;</span>
  97 <span class="gtkdoc opt">}</span> ViewerFile<span class="gtkdoc opt">;</span>
  98
  99 <span class="gtkdoc kwc">typedef</span> <span class="gtkdoc kwb">struct</span> <span class="gtkdoc opt">{</span>
 100   GObjectClass parent<span class="gtkdoc opt">;</span>
 101
 102   <span class="comment">/* class members */</span>
 103   <span class="comment">/* the first is public, pure and virtual */</span>
 104   <span class="gtkdoc kwb">void</span> <span class="gtkdoc opt">(*</span>open<span class="gtkdoc opt">)  (</span>ViewerFile  <span class="gtkdoc opt">*</span>self<span class="gtkdoc opt">,</span>
 105                  GError     <span class="gtkdoc opt">**</span>error<span class="gtkdoc opt">);</span>
 106
 107   <span class="comment">/* the second is public and virtual */</span>
 108   <span class="gtkdoc kwb">void</span> <span class="gtkdoc opt">(*</span>close<span class="gtkdoc opt">) (</span>ViewerFile  <span class="gtkdoc opt">*</span>self<span class="gtkdoc opt">,</span>
 109                  GError     <span class="gtkdoc opt">**</span>error<span class="gtkdoc opt">);</span>
 110 <span class="gtkdoc opt">}</span> ViewerFileClass<span class="gtkdoc opt">;</span>
 111
 112 <span class="gtkdoc ppc">#define VIEWER_TYPE_FILE (viewer_file_get_type ())</span>
 113
 114 GType
 115 <span class="function">viewer_file_get_type</span> <span class="gtkdoc opt">(</span><span class="gtkdoc kwb">void</span><span class="gtkdoc opt">)</span>
 116 <span class="gtkdoc opt">{</span>
 117   <span class="gtkdoc kwb">static</span> GType type <span class="gtkdoc opt">=</span> <span class="number">0</span><span class="gtkdoc opt">;</span>
 118   <span class="keyword">if</span> <span class="gtkdoc opt">(</span>type <span class="gtkdoc opt">==</span> <span class="number">0</span><span class="gtkdoc opt">) {</span>
 119     <span class="gtkdoc kwb">const</span> GTypeInfo info <span class="gtkdoc opt">= {</span>
 120       <span class="keyword">sizeof</span> <span class="gtkdoc opt">(</span>ViewerFileClass<span class="gtkdoc opt">),</span>
 121       NULL<span class="gtkdoc opt">,</span>           <span class="comment">/* base_init */</span>
 122       NULL<span class="gtkdoc opt">,</span>           <span class="comment">/* base_finalize */</span>
 123       <span class="gtkdoc opt">(</span>GClassInitFunc<span class="gtkdoc opt">)</span> viewer_file_class_init<span class="gtkdoc opt">,</span>
 124       NULL<span class="gtkdoc opt">,</span>           <span class="comment">/* class_finalize */</span>
 125       NULL<span class="gtkdoc opt">,</span>           <span class="comment">/* class_data */</span>
 126       <span class="keyword">sizeof</span> <span class="gtkdoc opt">(</span>ViewerFile<span class="gtkdoc opt">),</span>
 127       <span class="number">0</span><span class="gtkdoc opt">,</span>              <span class="comment">/* n_preallocs */</span>
 128       <span class="gtkdoc opt">(</span>GInstanceInitFunc<span class="gtkdoc opt">)</span> NULL <span class="comment">/* instance_init */</span>
 129     <span class="gtkdoc opt">};</span>
 130     type <span class="gtkdoc opt">=</span> <span class="function"><a href="gobject-Type-Information.html#g-type-register-static">g_type_register_static</a></span> <span class="gtkdoc opt">(</span>G_TYPE_OBJECT<span class="gtkdoc opt">,</span>
 131                                    <span class="string">&quot;ViewerFile&quot;</span><span class="gtkdoc opt">,</span>
 132                                    <span class="gtkdoc opt">&amp;</span>info<span class="gtkdoc opt">,</span> <span class="number">0</span><span class="gtkdoc opt">);</span>
 133   <span class="gtkdoc opt">}</span>
 134   <span class="keyword">return</span> type<span class="gtkdoc opt">;</span>
 135 <span class="gtkdoc opt">}</span></pre></td>
 136       </tr>
 137     </tbody>
 138   </table>
 139 </div>
 140
 141 <p>
 142           Upon the first call to <code class="function">viewer_file_get_type</code>, the type named
 143           <span class="emphasis"><em>ViewerFile</em></span> will be registered in the type system as inheriting
 144           from the type <span class="emphasis"><em>G_TYPE_OBJECT</em></span>.
 145         </p>
 146 <p>
 147           Every object must define two structures: its class structure and its
 148           instance structure. All class structures must contain as first member
 149           a <a class="link" href="gobject-Type-Information.html#GTypeClass" title="struct GTypeClass"><span class="type">GTypeClass</span></a> structure. All instance structures must contain as first
 150           member a <a class="link" href="gobject-Type-Information.html#GTypeInstance" title="struct GTypeInstance"><span class="type">GTypeInstance</span></a> structure. The declaration of these C types,
 151           coming from <code class="filename">gtype.h</code> is shown below:
 152 </p>
 153 <div class="informalexample">
 154   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
 155     <tbody>
 156       <tr>
 157         <td class="listing_lines" align="right"><pre>1
 158 2
 159 3
 160 4
 161 5
 162 6
 163 7
 164 8</pre></td>
 165         <td class="listing_code"><pre class="programlisting"><span class="gtkdoc kwb">struct</span> _GTypeClass
 166 <span class="gtkdoc opt">{</span>
 167   GType g_type<span class="gtkdoc opt">;</span>
 168 <span class="gtkdoc opt">};</span>
 169 <span class="gtkdoc kwb">struct</span> _GTypeInstance
 170 <span class="gtkdoc opt">{</span>
 171   GTypeClass <span class="gtkdoc opt">*</span>g_class<span class="gtkdoc opt">;</span>
 172 <span class="gtkdoc opt">};</span></pre></td>
 173       </tr>
 174     </tbody>
 175   </table>
 176 </div>
 177
 178 <p>
 179           These constraints allow the type system to make sure that every object instance
 180           (identified by a pointer to the object's instance structure) contains in its
 181           first bytes a pointer to the object's class structure.
 182         </p>
 183 <p>
 184           This relationship is best explained by an example: let's take object B which
 185           inherits from object A:
 186 </p>
 187 <div class="informalexample">
 188   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
 189     <tbody>
 190       <tr>
 191         <td class="listing_lines" align="right"><pre>1
 192 2
 193 3
 194 4
 195 5
 196 6
 197 7
 198 8
 199 9
 200 10
 201 11
 202 12
 203 13
 204 14
 205 15
 206 16
 207 17
 208 18
 209 19
 210 20
 211 21
 212 22
 213 23</pre></td>
 214         <td class="listing_code"><pre class="programlisting"><span class="comment">/* A definitions */</span>
 215 <span class="gtkdoc kwc">typedef</span> <span class="gtkdoc kwb">struct</span> <span class="gtkdoc opt">{</span>
 216   GTypeInstance parent<span class="gtkdoc opt">;</span>
 217   <span class="gtkdoc kwb">int</span> field_a<span class="gtkdoc opt">;</span>
 218   <span class="gtkdoc kwb">int</span> field_b<span class="gtkdoc opt">;</span>
 219 <span class="gtkdoc opt">}</span> A<span class="gtkdoc opt">;</span>
 220 <span class="gtkdoc kwc">typedef</span> <span class="gtkdoc kwb">struct</span> <span class="gtkdoc opt">{</span>
 221   GTypeClass parent_class<span class="gtkdoc opt">;</span>
 222   <span class="gtkdoc kwb">void</span> <span class="gtkdoc opt">(*</span>method_a<span class="gtkdoc opt">) (</span><span class="gtkdoc kwb">void</span><span class="gtkdoc opt">);</span>
 223   <span class="gtkdoc kwb">void</span> <span class="gtkdoc opt">(*</span>method_b<span class="gtkdoc opt">) (</span><span class="gtkdoc kwb">void</span><span class="gtkdoc opt">);</span>
 224 <span class="gtkdoc opt">}</span> AClass<span class="gtkdoc opt">;</span>
 225
 226 <span class="comment">/* B definitions. */</span>
 227 <span class="gtkdoc kwc">typedef</span> <span class="gtkdoc kwb">struct</span> <span class="gtkdoc opt">{</span>
 228   A parent<span class="gtkdoc opt">;</span>
 229   <span class="gtkdoc kwb">int</span> field_c<span class="gtkdoc opt">;</span>
 230   <span class="gtkdoc kwb">int</span> field_d<span class="gtkdoc opt">;</span>
 231 <span class="gtkdoc opt">}</span> B<span class="gtkdoc opt">;</span>
 232 <span class="gtkdoc kwc">typedef</span> <span class="gtkdoc kwb">struct</span> <span class="gtkdoc opt">{</span>
 233   AClass parent_class<span class="gtkdoc opt">;</span>
 234   <span class="gtkdoc kwb">void</span> <span class="gtkdoc opt">(*</span>method_c<span class="gtkdoc opt">) (</span><span class="gtkdoc kwb">void</span><span class="gtkdoc opt">);</span>
 235   <span class="gtkdoc kwb">void</span> <span class="gtkdoc opt">(*</span>method_d<span class="gtkdoc opt">) (</span><span class="gtkdoc kwb">void</span><span class="gtkdoc opt">);</span>
 236 <span class="gtkdoc opt">}</span> BClass<span class="gtkdoc opt">;</span></pre></td>
 237       </tr>
 238     </tbody>
 239   </table>
 240 </div>
 241
 242 <p>
 243           The C standard mandates that the first field of a C structure is stored starting
 244           in the first byte of the buffer used to hold the structure's fields in memory.
 245           This means that the first field of an instance of an object B is A's first field
 246           which in turn is <span class="type">GTypeInstance</span>'s first field which in
 247           turn is <em class="structfield"><code>g_class</code></em>, a pointer
 248           to B's class structure.
 249         </p>
 250 <p>
 251           Thanks to these simple conditions, it is possible to detect the type of every
 252           object instance by doing:
 253 </p>
 254 <div class="informalexample">
 255   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
 256     <tbody>
 257       <tr>
 258         <td class="listing_lines" align="right"><pre>1
 259 2</pre></td>
 260         <td class="listing_code"><pre class="programlisting">B <span class="gtkdoc opt">*</span>b<span class="gtkdoc opt">;</span>
 261 b<span class="gtkdoc opt">-&gt;</span>parent<span class="gtkdoc opt">.</span>parent<span class="gtkdoc opt">.</span>g_class<span class="gtkdoc opt">-&gt;</span>g_type</pre></td>
 262       </tr>
 263     </tbody>
 264   </table>
 265 </div>
 266
 267 <p>
 268           or, more quickly:
 269 </p>
 270 <div class="informalexample">
 271   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
 272     <tbody>
 273       <tr>
 274         <td class="listing_lines" align="right"><pre>1
 275 2</pre></td>
 276         <td class="listing_code"><pre class="programlisting">B <span class="gtkdoc opt">*</span>b<span class="gtkdoc opt">;</span>
 277 <span class="gtkdoc opt">((</span>GTypeInstance <span class="gtkdoc opt">*)</span> b<span class="gtkdoc opt">)-&gt;</span>g_class<span class="gtkdoc opt">-&gt;</span>g_type</pre></td>
 278       </tr>
 279     </tbody>
 280   </table>
 281 </div>
 282
 283 <p>
 284         </p>
 285 <div class="sect2">
 286 <div class="titlepage"><div><div><h3 class="title">
 287 <a name="gtype-instantiable-classed-init-done"></a>Initialization and Destruction</h3></div></div></div>
 288 <p>
 289             instantiation of these types can be done with
 290             <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>,
 291             which will look up the type information
 292             structure associated with the type requested. Then, the instance size and instantiation
 293             policy (if the <em class="structfield"><code>n_preallocs</code></em> field is set
 294             to a non-zero value, the type system allocates
 295             the object's instance structures in chunks rather than mallocing for every instance)
 296             declared by the user are used to get a buffer to hold the object's instance
 297             structure.
 298           </p>
 299 <p>
 300             If this is the first instance of the object ever created, the type system must create a class structure.
 301             It allocates a buffer to hold the object's class structure and initializes it. The first part of the
 302             class structure (ie: the embedded parent class structure) is initialized by copying the contents from
 303             the class structure of the parent class. The rest of class structure is initialized to zero.  If there
 304             is no parent, the entire class structure is initialized to zero. The type system then invokes the
 305             <code class="function">base_class_initialization</code> functions
 306             (<a class="link" href="gobject-Type-Information.html#GBaseInitFunc" title="GBaseInitFunc ()"><span class="type">GBaseInitFunc</span></a>) from topmost
 307             fundamental object to bottom-most most derived object. The object's <code class="function">class_init</code>
 308             (<a class="link" href="gobject-Type-Information.html#GClassInitFunc" title="GClassInitFunc ()"><span class="type">GClassInitFunc</span></a>) function is invoked afterwards to complete
 309             initialization of the class structure.
 310             Finally, the object's interfaces are initialized (we will discuss interface initialization
 311             in more detail later).
 312           </p>
 313 <p>
 314             Once the type system has a pointer to an initialized class structure, it sets the object's
 315             instance class pointer to the object's class structure and invokes the object's
 316             <code class="function">instance_init</code>
 317             (<a class="link" href="gobject-Type-Information.html#GInstanceInitFunc" title="GInstanceInitFunc ()"><span class="type">GInstanceInitFunc</span></a>)
 318             functions, from top-most fundamental
 319             type to bottom-most most-derived type.
 320           </p>
 321 <p>
 322             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:
 323             the instance structure is returned to the instance pool if there is one and if this was the
 324             last living instance of the object, the class is destroyed.
 325           </p>
 326 <p>
 327             Class destruction (the concept of destruction is sometimes partly
 328             referred to as finalization in GType) is the symmetric process of
 329             the initialization: interfaces are destroyed first.
 330             Then, the most derived
 331             class_finalize (<a class="link" href="gobject-Type-Information.html#GClassFinalizeFunc" title="GClassFinalizeFunc ()"><span class="type">GClassFinalizeFunc</span></a>) function is invoked. Finally, the
 332             base_class_finalize (<a class="link" href="gobject-Type-Information.html#GBaseFinalizeFunc" title="GBaseFinalizeFunc ()"><span class="type">GBaseFinalizeFunc</span></a>) functions are
 333             invoked from bottom-most most-derived type to top-most fundamental type and
 334             the class structure is freed.
 335           </p>
 336 <p>
 337             The base initialization/finalization process is
 338             very similar to the C++ constructor/destructor paradigm. The practical details are different
 339             though and it is important not to get confused by superficial similarities.
 340             GTypes have no instance destruction mechanism. It is
 341             the user's responsibility to implement correct destruction semantics on top
 342             of the existing GType code. (This is what GObject does: see
 343             <a class="xref" href="chapter-gobject.html" title="The GObject base class"><i>The GObject base class</i></a>.)
 344            Furthermore, C++ code equivalent to the <code class="function">base_init</code>
 345            and <code class="function">class_init</code> callbacks of GType is usually not needed because C++ cannot really create object
 346            types at runtime.
 347           </p>
 348 <p>
 349             The instantiation/finalization process can be summarized as follows:
 350             </p>
 351 <div class="table">
 352 <a name="gtype-init-fini-table"></a><p class="title"><b>Table 1. GType Instantiation/Finalization</b></p>
 353 <div class="table-contents"><table class="table" summary="GType Instantiation/Finalization" border="1">
 354 <colgroup>
 355 <col align="left">
 356 <col align="left">
 357 <col align="left">
 358 </colgroup>
 359 <thead><tr>
 360 <th align="left">Invocation time</th>
 361 <th align="left">Function invoked</th>
 362 <th align="left">Function's parameters</th>
 363 </tr></thead>
 364 <tbody>
 365 <tr>
 366 <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>
 367 <td align="left">type's <code class="function">base_init</code> function</td>
 368 <td align="left">On the inheritance tree of classes from fundamental type to target type.
 369                       <code class="function">base_init</code> is invoked once for each class structure.</td>
 370 </tr>
 371 <tr>
 372 <td align="left">target type's <code class="function">class_init</code> function</td>
 373 <td align="left">On target type's class structure</td>
 374 </tr>
 375 <tr>
 376 <td align="left">interface initialization, see
 377                       <a class="xref" href="gtype-non-instantiable-classed.html#gtype-non-instantiable-classed-init" title="Interface Initialization">the section called “Interface Initialization”</a>
 378 </td>
 379 <td align="left"> </td>
 380 </tr>
 381 <tr>
 382 <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>
 383 <td align="left">target type's <code class="function">instance_init</code> function</td>
 384 <td align="left">On object's instance</td>
 385 </tr>
 386 <tr>
 387 <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>
 388 <td align="left">interface destruction, see
 389                       <a class="xref" href="gtype-non-instantiable-classed.html#gtype-non-instantiable-classed-dest" title="Interface Destruction">the section called “Interface Destruction”</a>
 390 </td>
 391 <td align="left"> </td>
 392 </tr>
 393 <tr>
 394 <td align="left">target type's <code class="function">class_finalize</code> function</td>
 395 <td align="left">On target type's class structure</td>
 396 </tr>
 397 <tr>
 398 <td align="left">type's <code class="function">base_finalize</code> function</td>
 399 <td align="left">On the inheritance tree of classes from fundamental type to target type.
 400                       <code class="function">base_finalize</code> is invoked once for each class structure.</td>
 401 </tr>
 402 </tbody>
 403 </table></div>
 404 </div>
 405 <p><br class="table-break">
 406           </p>
 407 </div>
 408 </div>
 409 <div class="footer">
 410 <hr>Generated by GTK-Doc V1.25.1</div>
 411 </body>
 412 </html>