Default page

Edit File: chapter-gtype.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>The GLib Dynamic Type System: GObject Reference Manual</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="GObject Reference Manual">
<link rel="up" href="pt01.html" title="Part I. Concepts">
<link rel="prev" href="ch01s02.html" title="Exporting a C API">
<link rel="next" href="gtype-conventions.html" title="Conventions">
<meta name="generator" content="GTK-Doc V1.32 (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="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><a accesskey="u" href="pt01.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="ch01s02.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="gtype-conventions.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="chapter">
<div class="titlepage"><div><div><h2 class="title">
<a name="chapter-gtype"></a>The GLib Dynamic Type System</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><a href="chapter-gtype.html#gtype-copy">Copy functions</a></dt>
<dt><a href="gtype-conventions.html">Conventions</a></dt>
<dt><a href="gtype-non-instantiable.html">Non-instantiable non-classed fundamental types</a></dt>
<dt><a href="gtype-instantiable-classed.html">Instantiable classed types: objects</a></dt>
<dd><dl><dt><a href="gtype-instantiable-classed.html#gtype-instantiable-classed-init-done">Initialization and Destruction</a></dt></dl></dd>
<dt><a href="gtype-non-instantiable-classed.html">Non-instantiable classed types: interfaces</a></dt>
<dd><dl>
<dt><a href="gtype-non-instantiable-classed.html#gtype-non-instantiable-classed-init">Interface Initialization</a></dt>
<dt><a href="gtype-non-instantiable-classed.html#gtype-non-instantiable-classed-dest">Interface Destruction</a></dt>
</dl></dd>
</dl></div>

 A type, as manipulated by the GLib type system, is much more generic than what
 is usually understood as an Object type. It is best explained by looking at the 
 structure and the functions used to register new types in the type system.
 
<div class="informalexample">
 <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
 <tbody>
 <tr>
 <td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31</pre></td>
 <td class="listing_code"><pre class="programlisting">typedef struct _GTypeInfo GTypeInfo;
struct _GTypeInfo
{
 /* interface types, classed types, instantiated types */
 guint16 class_size;
 
 GBaseInitFunc base_init;
 GBaseFinalizeFunc base_finalize;
 
 /* classed types, instantiated types */
 GClassInitFunc class_init;
 GClassFinalizeFunc class_finalize;
 gconstpointer class_data;
 
 /* instantiated types */
 guint16 instance_size;
 guint16 n_preallocs;
 GInstanceInitFunc instance_init;
 
 /* value handling */
 const GTypeValueTable *value_table;
};
GType g_type_register_static (GType parent_type,
 const gchar *type_name,
 const GTypeInfo *info,
 GTypeFlags flags);
GType g_type_register_fundamental (GType type_id,
 const gchar *type_name,
 const GTypeInfo *info,
 const GTypeFundamentalInfo *finfo,
 GTypeFlags flags);</pre></td>
 </tr>
 </tbody>
 </table>
</div>

<code class="function"><a class="link" href="gobject-Type-Information.html#g-type-register-static" title="g_type_register_static ()">g_type_register_static</a></code>,
 <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-register-dynamic" title="g_type_register_dynamic ()">g_type_register_dynamic</a></code> and 
 <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-register-fundamental" title="g_type_register_fundamental ()">g_type_register_fundamental</a></code>
 are the C functions, defined in
 <code class="filename">gtype.h</code> and implemented in <code class="filename">gtype.c</code>
 which you should use to register a new <a class="link" href="gobject-Type-Information.html#GType">GType</a> in the program's type system.
 It is not likely you will ever need to use 
 <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-register-fundamental" title="g_type_register_fundamental ()">g_type_register_fundamental</a></code>
 but in case you want to, the last chapter explains how to create
 new fundamental types.
 

 Fundamental types are top-level types which do not derive from any other type 
 while other non-fundamental types derive from other types.
 Upon initialization, the type system not only initializes its
 internal data structures but it also registers a number of core
 types: some of these are fundamental types. Others are types derived from these 
 fundamental types.
 

 Fundamental and non-fundamental types are defined by:
 
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
 class size: the class_size field in <a class="link" href="gobject-Type-Information.html#GTypeInfo" title="struct GTypeInfo">GTypeInfo</a>.
 </li>
<li class="listitem">
 class initialization functions (C++ constructor): the <code class="function">base_init</code> and 
 <code class="function">class_init</code> fields in <a class="link" href="gobject-Type-Information.html#GTypeInfo" title="struct GTypeInfo">GTypeInfo</a>.
 </li>
<li class="listitem">
 class destruction functions (C++ destructor): the base_finalize and 
 class_finalize fields in <a class="link" href="gobject-Type-Information.html#GTypeInfo" title="struct GTypeInfo">GTypeInfo</a>.
 </li>
<li class="listitem">
 instance size (C++ parameter to new): the instance_size field in 
 <a class="link" href="gobject-Type-Information.html#GTypeInfo" title="struct GTypeInfo">GTypeInfo</a>.
 </li>
<li class="listitem">
 instantiation policy (C++ type of new operator): the n_preallocs
 field in <a class="link" href="gobject-Type-Information.html#GTypeInfo" title="struct GTypeInfo">GTypeInfo</a>.
 </li>
<li class="listitem">
 copy functions (C++ copy operators): the value_table field in 
 <a class="link" href="gobject-Type-Information.html#GTypeInfo" title="struct GTypeInfo">GTypeInfo</a>.
 </li>
<li class="listitem">
 type characteristic flags: <a class="link" href="gobject-Type-Information.html#GTypeFlags" title="enum GTypeFlags">GTypeFlags</a>.
 </li>
</ul></div>

 Fundamental types are also defined by a set of <a class="link" href="gobject-Type-Information.html#GTypeFundamentalFlags" title="enum GTypeFundamentalFlags">GTypeFundamentalFlags</a> 
 which are stored in a <a class="link" href="gobject-Type-Information.html#GTypeFundamentalInfo" title="struct GTypeFundamentalInfo">GTypeFundamentalInfo</a>.
 Non-fundamental types are furthermore defined by the type of their parent which is
 passed as the parent_type parameter to <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-register-static" title="g_type_register_static ()">g_type_register_static</a></code>
 and <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-register-dynamic" title="g_type_register_dynamic ()">g_type_register_dynamic</a></code>.
 
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="gtype-copy"></a>Copy functions</h2></div></div></div>

 The major common point between all GLib types (fundamental and 
 non-fundamental, classed and non-classed, instantiable and non-instantiable) is that
 they can all be manipulated through a single API to copy/assign them.
 

 The <a class="link" href="gobject-Generic-values.html#GValue">GValue</a> structure is used as an abstract container for all of these 
 types. Its simplistic API (defined in <code class="filename">gobject/gvalue.h</code>) can be 
 used to invoke the value_table functions registered
 during type registration: for example <code class="function"><a class="link" href="gobject-Generic-values.html#g-value-copy" title="g_value_copy ()">g_value_copy</a></code> copies the 
 content of a <a class="link" href="gobject-Generic-values.html#GValue">GValue</a> to another <a class="link" href="gobject-Generic-values.html#GValue">GValue</a>. This is similar
 to a C++ assignment which invokes the C++ copy operator to modify the default
 bit-by-bit copy semantics of C++/C structures/classes.
 

 The following code shows how you can copy around a 64 bit integer, as well as a <a class="link" href="gobject-The-Base-Object-Type.html#GObject">GObject</a>
 instance pointer:

<div class="informalexample">
 <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
 <tbody>
 <tr>
 <td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45</pre></td>
 <td class="listing_code"><pre class="programlisting">static void test_int (void)
{
 GValue a_value = G_VALUE_INIT;
 GValue b_value = G_VALUE_INIT;
 guint64 a, b;

a = 0xdeadbeef;

g_value_init (&a_value, G_TYPE_UINT64);
 g_value_set_uint64 (&a_value, a);

g_value_init (&b_value, G_TYPE_UINT64);
 g_value_copy (&a_value, &b_value);

b = g_value_get_uint64 (&b_value);

if (a == b) {
 g_print ("Yay !! 10 lines of code to copy around a uint64.\n");
 } else {
 g_print ("Are you sure this is not a Z80 ?\n");
 }
}

static void test_object (void)
{
 GObject *obj;
 GValue obj_vala = G_VALUE_INIT;
 GValue obj_valb = G_VALUE_INIT;
 obj = g_object_new (VIEWER_TYPE_FILE, NULL);

g_value_init (&obj_vala, VIEWER_TYPE_FILE);
 g_value_set_object (&obj_vala, obj);

g_value_init (&obj_valb, G_TYPE_OBJECT);

/* g_value_copy's semantics for G_TYPE_OBJECT types is to copy the reference.
 * This function thus calls g_object_ref.
 * It is interesting to note that the assignment works here because
 * VIEWER_TYPE_FILE is a G_TYPE_OBJECT.
 */
 g_value_copy (&obj_vala, &obj_valb);

g_object_unref (G_OBJECT (obj));
 g_object_unref (G_OBJECT (obj));
}</pre></td>
 </tr>
 </tbody>
 </table>
</div>

The important point about the above code is that the exact semantics of the copy calls
 is undefined since they depend on the implementation of the copy function. Certain 
 copy functions might decide to allocate a new chunk of memory and then to copy the 
 data from the source to the destination. Others might want to simply increment
 the reference count of the instance and copy the reference to the new GValue.
 

 The value table used to specify these assignment functions is
 documented in
 <a class="link" href="gobject-Type-Information.html#GTypeValueTable" title="struct GTypeValueTable">GTypeValueTable</a>.
 

 Interestingly, it is also very unlikely
 you will ever need to specify a value_table during type registration
 because these value_tables are inherited from the parent types for
 non-fundamental types.
 
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.32</div>
</body>
</html>