RubyGems - glib2 - Versions diffs - 2.2.4-x64-mingw32 - Mend

glib2 2.2.4-x64-mingw32

Files changed (2228) hide show

data/vendor/local/share/gtk-doc/html/gobject/ch01s02.html ADDED Viewed

@@ -0,0 +1,136 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>GObject Reference Manual: Exporting a C API</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
+<link rel="home" href="index.html" title="GObject Reference Manual">
+<link rel="up" href="chapter-intro.html" title="Background">
+<link rel="prev" href="chapter-intro.html" title="Background">
+<link rel="next" href="chapter-gtype.html" title="The GLib Dynamic Type System">
+<meta name="generator" content="GTK-Doc V1.21.1 (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="chapter-intro.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
+<td><a accesskey="p" href="chapter-intro.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
+<td><a accesskey="n" href="chapter-gtype.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
+</tr></table>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="id-1.3.2.6"></a>Exporting a C API</h2></div></div></div>
+<p>
+      C APIs are defined by a set of functions and global variables which are usually exported from a
+      binary. C functions have an arbitrary number of arguments and one return value. Each function is thus
+      uniquely identified by the function name and the set of C types which describe the function arguments
+      and return value. The global variables exported by the API are similarly identified by their name and
+      their type.
+    </p>
+<p>
+      A C API is thus merely defined by a set of names to which a set of types are associated. If you know the
+      function calling convention and the mapping of the C types to the machine types used by the platform you
+      are on, you can resolve the name of each function to find where the code associated to this function
+      is located in memory, and then construct a valid argument list for the function. Finally, all you have to
+      do is trigger a call to the target C function with the argument list.
+    </p>
+<p>
+      For the sake of discussion, here is a sample C function and the associated 32 bit x86
+      assembly code generated by GCC on my Linux box:
+</p>
+<pre class="programlisting">
+static void function_foo (int foo)
+{}
+int main (int argc, char *argv[])
+{
+        function_foo (10);
+        return 0;
+}
+push   $0xa
+call   0x80482f4 &lt;function_foo&gt;
+</pre>
+<p>
+      The assembly code shown above is pretty straightforward: the first instruction pushes
+      the hexadecimal value 0xa (decimal value 10) as a 32-bit integer on the stack and calls
+      <code class="function">function_foo</code>. As you can see, C function calls are implemented by
+      gcc by native function calls (this is probably the fastest implementation possible).
+    </p>
+<p>
+      Now, let's say we want to call the C function <code class="function">function_foo</code> from
+      a Python program. To do this, the Python interpreter needs to:
+      </p>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
+<li class="listitem"><p>Find where the function is located. This probably means finding the binary generated by the C compiler
+        which exports this function.</p></li>
+<li class="listitem"><p>Load the code of the function in executable memory.</p></li>
+<li class="listitem"><p>Convert the Python parameters to C-compatible parameters before calling
+        the function.</p></li>
+<li class="listitem"><p>Call the function with the right calling convention.</p></li>
+<li class="listitem"><p>Convert the return values of the C function to Python-compatible
+        variables to return them to the Python code.</p></li>
+</ul></div>
+<p>
+    </p>
+<p>
+      The process described above is pretty complex and there are a lot of ways to make it entirely automatic
+      and transparent to C and Python programmers:
+      </p>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
+<li class="listitem"><p>The first solution is to write by hand a lot of glue code, once for each function exported or imported,
+        which does the Python-to-C parameter conversion and the C-to-Python return value conversion. This glue code is then
+        linked with the interpreter which allows Python programs to call Python functions which delegate work to
+        C functions.</p></li>
+<li class="listitem"><p>Another, nicer solution is to automatically generate the glue code, once for each function exported or
+        imported, with a special compiler which
+        reads the original function signature.</p></li>
+<li class="listitem"><p>The solution used by GLib is to use the GType library which holds at runtime a description of
+        all the objects manipulated by the programmer. This so-called <span class="emphasis"><em>dynamic type</em></span>
+        <a href="#ftn.id-1.3.2.6.6.1.3.1.2" class="footnote" name="id-1.3.2.6.6.1.3.1.2"><sup class="footnote">[1]</sup></a>
+        library is then used by special generic glue code to automatically convert function parameters and
+        function calling conventions between different runtime domains.</p></li>
+</ul></div>
+<p>
+      The greatest advantage of the solution implemented by GType is that the glue code sitting at the runtime domain
+      boundaries is written once: the figure below states this more clearly.
+      </p>
+<div class="figure">
+<a name="id-1.3.2.6.6.2"></a><p class="title"><b>Figure 1. </b></p>
+<div class="figure-contents"><div class="mediaobject" align="center"><img src="glue.png" align="middle"></div></div>
+</div>
+<p><br class="figure-break">
+      Currently, there exist at least Python and Perl generic glue code which makes it possible to use
+      C objects written with GType directly in Python or Perl, with a minimum amount of work: there
+      is no need to generate huge amounts of glue code either automatically or by hand.
+    </p>
+<p>
+      Although that goal was arguably laudable, its pursuit has had a major influence on
+      the whole GType/GObject library. C programmers are likely to be puzzled at the complexity
+      of the features exposed in the following chapters if they forget that the GType/GObject library
+      was not only designed to offer OO-like features to C programmers but also transparent
+      cross-language interoperability.
+    </p>
+<div class="footnotes">
+<br><hr style="width:100; text-align:left;margin-left: 0">
+<div id="ftn.id-1.3.2.6.6.1.3.1.2" class="footnote"><p><a href="#id-1.3.2.6.6.1.3.1.2" class="para"><sup class="para">[1] </sup></a>
+            There are numerous different implementations of dynamic type systems: all C++
+            compilers have one, Java and .NET have one too. A dynamic type system allows you
+            to get information about every instantiated object at runtime. It can be implemented
+            by a process-specific database: every new object created registers the characteristics
+            of its associated type in the type system. It can also be implemented by introspection
+            interfaces. The common point between all these different type systems and implementations
+            is that they all allow you to query for object metadata at runtime.
+          </p></div>
+</div>
+</div>
+<div class="footer">
+<hr>
+          Generated by GTK-Doc V1.21.1</div>
+</body>
+</html>

data/vendor/local/share/gtk-doc/html/gobject/chapter-gobject.html ADDED Viewed

@@ -0,0 +1,290 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>GObject Reference Manual: The GObject base class</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.78.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="gtype-non-instantiable-classed.html" title="Non-instantiable classed types: interfaces">
+<link rel="next" href="gobject-memory.html" title="Object memory management">
+<meta name="generator" content="GTK-Doc V1.21.1 (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="gtype-non-instantiable-classed.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
+<td><a accesskey="n" href="gobject-memory.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-gobject"></a>The GObject base class</h2></div></div></div>
+<div class="toc"><dl class="toc">
+<dt><span class="sect1"><a href="chapter-gobject.html#gobject-instantiation">Object instantiation</a></span></dt>
+<dt><span class="sect1"><a href="gobject-memory.html">Object memory management</a></span></dt>
+<dd><dl>
+<dt><span class="sect2"><a href="gobject-memory.html#gobject-memory-refcount">Reference count</a></span></dt>
+<dt><span class="sect2"><a href="gobject-memory.html#gobject-memory-weakref">Weak References</a></span></dt>
+<dt><span class="sect2"><a href="gobject-memory.html#gobject-memory-cycles">Reference counts and cycles</a></span></dt>
+</dl></dd>
+<dt><span class="sect1"><a href="gobject-properties.html">Object properties</a></span></dt>
+<dd><dl><dt><span class="sect2"><a href="gobject-properties.html#gobject-multi-properties">Accessing multiple properties at once</a></span></dt></dl></dd>
+</dl></div>
+<p>
+    The previous chapter discussed the details of GLib's Dynamic Type System.
+    The GObject library also contains an implementation for a base fundamental
+    type named <a class="link" href="gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a>.
+  </p>
+<p>
+    <a class="link" href="gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a> is a fundamental classed instantiable type. It implements:
+    </p>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
+<li class="listitem"><p>Memory management with reference counting</p></li>
+<li class="listitem"><p>Construction/Destruction of instances</p></li>
+<li class="listitem"><p>Generic per-object properties with set/get function pairs</p></li>
+<li class="listitem"><p>Easy use of signals</p></li>
+</ul></div>
+<p>
+    All the GNOME libraries which use the GLib type system (like GTK+ and GStreamer)
+    inherit from <a class="link" href="gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a> which is why it is important to understand
+    the details of how it works.
+  </p>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="gobject-instantiation"></a>Object instantiation</h2></div></div></div>
+<p>
+      The <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-new" title="g_object_new ()">g_object_new</a></code>
+      family of functions can be used to instantiate any GType which inherits
+      from the GObject base type. All these functions make sure the class and
+      instance structures have been correctly initialized by GLib's type system
+      and then invoke at one point or another the constructor class method
+      which is used to:
+      </p>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
+<li class="listitem"><p>
+            Allocate and clear memory through <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></li>
+<li class="listitem"><p>
+            Initialize the object's instance with the construction properties.
+          </p></li>
+</ul></div>
+<p>
+     Although one can expect all class and instance members (except the fields
+     pointing to the parents) to be set to zero, some consider it good practice
+     to explicitly set them.
+    </p>
+<p>
+      Objects which inherit from GObject are allowed to override this
+      constructor class method: they should however chain to their parent
+      constructor method before doing so:
+</p>
+<pre class="programlisting">
+  GObject *(* constructor) (GType                  gtype,
+                            guint                  n_properties,
+                            GObjectConstructParam *properties);
+</pre>
+<p>
+    </p>
+<p>
+      The example below shows how <span class="type">MamanBar</span> overrides the parent's constructor:
+</p>
+<pre class="programlisting">
+#define MAMAN_TYPE_BAR                  (maman_bar_get_type ())
+#define MAMAN_BAR(obj)                  (G_TYPE_CHECK_INSTANCE_CAST ((obj), MAMAN_TYPE_BAR, MamanBar))
+#define MAMAN_IS_BAR(obj)               (G_TYPE_CHECK_INSTANCE_TYPE ((obj), MAMAN_TYPE_BAR))
+#define MAMAN_BAR_CLASS(klass)          (G_TYPE_CHECK_CLASS_CAST ((klass), MAMAN_TYPE_BAR, MamanBarClass))
+#define MAMAN_IS_BAR_CLASS(klass)       (G_TYPE_CHECK_CLASS_TYPE ((klass), MAMAN_TYPE_BAR))
+#define MAMAN_BAR_GET_CLASS(obj)        (G_TYPE_INSTANCE_GET_CLASS ((obj), MAMAN_TYPE_BAR, MamanBarClass))
+typedef struct _MamanBar        MamanBar;
+typedef struct _MamanBarClass   MamanBarClass;
+struct _MamanBar
+{
+  GObject parent_instance;
+  /* instance members */
+};
+struct _MamanBarClass
+{
+  GObjectClass parent_class;
+  /* class members */
+};
+/* will create maman_bar_get_type and set maman_bar_parent_class */
+G_DEFINE_TYPE (MamanBar, maman_bar, G_TYPE_OBJECT);
+static GObject *
+maman_bar_constructor (GType                  gtype,
+                       guint                  n_properties,
+                       GObjectConstructParam *properties)
+{
+  GObject *obj;
+  {
+    /* Always chain up to the parent constructor */
+    obj = G_OBJECT_CLASS (maman_bar_parent_class)-&gt;constructor (gtype, n_properties, properties);
+  }
+  /* update the object state depending on constructor properties */
+  return obj;
+}
+static void
+maman_bar_class_init (MamanBarClass *klass)
+{
+  GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
+  gobject_class-&gt;constructor = maman_bar_constructor;
+}
+static void
+maman_bar_init (MamanBar *self)
+{
+  /* initialize the object */
+}
+</pre>
+<p>
+      If the user instantiates an object <span class="type">MamanBar</span> with:
+</p>
+<pre class="programlisting">
+MamanBar *bar = g_object_new (MAMAN_TYPE_BAR, NULL);
+</pre>
+<p>
+      If this is the first instantiation of such an object, the
+      <code class="function">maman_bar_class_init</code> function will be invoked
+      after any <code class="function">maman_bar_base_class_init</code> function.
+      This will make sure the class structure of this new object is
+      correctly initialized. Here, <code class="function">maman_bar_class_init</code>
+      is expected to override the object's class methods and setup the
+      class' own methods. In the example above, the constructor method is
+      the only overridden method: it is set to
+      <code class="function">maman_bar_constructor</code>.
+    </p>
+<p>
+      Once <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-new" title="g_object_new ()">g_object_new</a></code> has obtained a reference to an initialized
+      class structure, it invokes its constructor method to create an instance of the new
+      object. Since it has just been overridden by <code class="function">maman_bar_class_init</code>
+      to <code class="function">maman_bar_constructor</code>, the latter is called and, because it
+      was implemented correctly, it chains up to its parent's constructor. In
+      order to find the parent class and chain up to the parent class
+      constructor, we can use the <code class="literal">maman_bar_parent_class</code>
+      pointer that has been set up for us by the
+      <code class="literal">G_DEFINE_TYPE</code> macro.
+    </p>
+<p>
+      Finally, at one point or another, <code class="function">g_object_constructor</code> is invoked
+      by the last constructor in the chain. This function allocates the object's instance' buffer
+      through <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>
+      which means that the instance_init function is invoked at this point if one
+      was registered. After instance_init returns, the object is fully initialized and should be
+      ready to answer any user-request. When <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>
+      returns, <code class="function">g_object_constructor</code> sets the construction properties
+      (i.e. the properties which were given to <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-new" title="g_object_new ()">g_object_new</a></code>) and returns
+      to the user's constructor which is then allowed to do useful instance initialization...
+    </p>
+<p>
+      The process described above might seem a bit complicated, but it can be
+      summarized easily by the table below which lists the functions invoked
+      by <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-new" title="g_object_new ()">g_object_new</a></code>
+      and their order of invocation:
+    </p>
+<p>
+      </p>
+<div class="table">
+<a name="gobject-construction-table"></a><p class="title"><b>Table 4. <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-new" title="g_object_new ()">g_object_new</a></code></b></p>
+<div class="table-contents"><table summary="g_object_new" 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>
+<th>Remark</th>
+</tr></thead>
+<tbody>
+<tr>
+<td rowspan="4" align="left">First call to <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-new" title="g_object_new ()">g_object_new</a></code> for target type</td>
+<td align="left">target 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>
+<td>
+                I have no real idea on how this can be used. If you have a good real-life
+                example of how a class' base_init can be used, please, let me know.
+              </td>
+</tr>
+<tr>
+<td align="left">target type's class_init function</td>
+<td align="left">On target type's class structure</td>
+<td>
+                Here, you should make sure to initialize or override class methods (that is,
+                assign to each class' method its function pointer) and create the signals and
+                the properties associated to your object.
+              </td>
+</tr>
+<tr>
+<td align="left">interface' base_init function</td>
+<td align="left">On interface' vtable</td>
+<td> </td>
+</tr>
+<tr>
+<td align="left">interface' interface_init function</td>
+<td align="left">On interface' vtable</td>
+<td> </td>
+</tr>
+<tr>
+<td rowspan="2" align="left">Each call to <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-new" title="g_object_new ()">g_object_new</a></code> for target type</td>
+<td align="left">target type's class constructor method: GObjectClass-&gt;constructor</td>
+<td align="left">On object's instance</td>
+<td>
+                If you need to complete the object initialization after all the construction properties
+                are set, override the constructor method and make sure to chain up to the object's
+                parent class before doing your own initialization.
+                In doubt, do not override the constructor method.
+              </td>
+</tr>
+<tr>
+<td align="left">type's instance_init function</td>
+<td align="left">On the inheritance tree of classes from fundamental type to target type.
+              the instance_init provided for each type is invoked once for each instance
+              structure.</td>
+<td>
+                Provide an instance_init function to initialize your object before its construction
+                properties are set. This is the preferred way to initialize a GObject instance.
+                This function is equivalent to C++ constructors.
+              </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<p><br class="table-break">
+    </p>
+<p>
+      Readers should feel concerned about one little twist in the order in
+      which functions are invoked: while, technically, the class' constructor
+      method is called <span class="emphasis"><em>before</em></span> the GType's instance_init
+      function (since <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> which calls instance_init is called by
+      <code class="function">g_object_constructor</code> which is the top-level class
+      constructor method and to which users are expected to chain to), the
+      user's code which runs in a user-provided constructor will always
+      run <span class="emphasis"><em>after</em></span> GType's instance_init function since the
+      user-provided constructor <span class="emphasis"><em>must</em></span> (you've been warned)
+      chain up <span class="emphasis"><em>before</em></span> doing anything useful.
+    </p>
+</div>
+</div>
+<div class="footer">
+<hr>
+          Generated by GTK-Doc V1.21.1</div>
+</body>
+</html>

data/vendor/local/share/gtk-doc/html/gobject/chapter-gtype.html ADDED Viewed

@@ -0,0 +1,263 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>GObject Reference Manual: The GLib Dynamic Type System</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.78.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.21.1 (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><span class="sect1"><a href="chapter-gtype.html#gtype-copy">Copy functions</a></span></dt>
+<dt><span class="sect1"><a href="gtype-conventions.html">Conventions</a></span></dt>
+<dt><span class="sect1"><a href="gtype-non-instantiable.html">Non-instantiable non-classed fundamental types</a></span></dt>
+<dt><span class="sect1"><a href="gtype-instantiable-classed.html">Instantiable classed types: objects</a></span></dt>
+<dd><dl><dt><span class="sect2"><a href="gtype-instantiable-classed.html#gtype-instantiable-classed-init-done">Initialization and Destruction</a></span></dt></dl></dd>
+<dt><span class="sect1"><a href="gtype-non-instantiable-classed.html">Non-instantiable classed types: interfaces</a></span></dt>
+<dd><dl>
+<dt><span class="sect2"><a href="gtype-non-instantiable-classed.html#gtype-non-instantiable-classed-init">Interface Initialization</a></span></dt>
+<dt><span class="sect2"><a href="gtype-non-instantiable-classed.html#gtype-non-instantiable-classed-dest">Interface Destruction</a></span></dt>
+</dl></dd>
+</dl></div>
+<p>
+        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.
+        </p>
+<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>
+<p>
+      </p>
+<p>
+        <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-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" title="GType"><span class="type">GType</span></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> (you have to be Tim Janik
+        to do that) but in case you want to, the last chapter explains how to create
+        new fundamental types.
+        <a href="#ftn.id-1.3.3.3.7" class="footnote" name="id-1.3.3.3.7"><sup class="footnote">[2]</sup></a>
+      </p>
+<p>
+        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.
+      </p>
+<p>
+        Fundamental and non-fundamental types are defined by:
+        </p>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
+<li class="listitem"><p>
+            class size: the class_size field in <a class="link" href="gobject-Type-Information.html#GTypeInfo" title="struct GTypeInfo"><span class="type">GTypeInfo</span></a>.
+          </p></li>
+<li class="listitem"><p>
+            class initialization functions (C++ constructor): the base_init and
+            class_init fields in <a class="link" href="gobject-Type-Information.html#GTypeInfo" title="struct GTypeInfo"><span class="type">GTypeInfo</span></a>.
+          </p></li>
+<li class="listitem"><p>
+            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"><span class="type">GTypeInfo</span></a>.
+          </p></li>
+<li class="listitem"><p>
+            instance size (C++ parameter to new): the instance_size field in
+            <a class="link" href="gobject-Type-Information.html#GTypeInfo" title="struct GTypeInfo"><span class="type">GTypeInfo</span></a>.
+          </p></li>
+<li class="listitem"><p>
+            instantiation policy (C++ type of new operator): the n_preallocs
+            field in <a class="link" href="gobject-Type-Information.html#GTypeInfo" title="struct GTypeInfo"><span class="type">GTypeInfo</span></a>.
+          </p></li>
+<li class="listitem"><p>
+            copy functions (C++ copy operators): the value_table field in
+            <a class="link" href="gobject-Type-Information.html#GTypeInfo" title="struct GTypeInfo"><span class="type">GTypeInfo</span></a>.
+          </p></li>
+<li class="listitem"><p>
+            type characteristic flags: <a class="link" href="gobject-Type-Information.html#GTypeFlags" title="enum GTypeFlags"><span class="type">GTypeFlags</span></a>.
+          </p></li>
+</ul></div>
+<p>
+        Fundamental types are also defined by a set of <a class="link" href="gobject-Type-Information.html#GTypeFundamentalFlags" title="enum GTypeFundamentalFlags"><span class="type">GTypeFundamentalFlags</span></a>
+        which are stored in a <a class="link" href="gobject-Type-Information.html#GTypeFundamentalInfo" title="struct GTypeFundamentalInfo"><span class="type">GTypeFundamentalInfo</span></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>.
+      </p>
+<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>
+<p>
+          The major common point between <span class="emphasis"><em>all</em></span> 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.
+        </p>
+<p>
+          The <a class="link" href="gobject-Generic-values.html#GValue" title="GValue"><span class="type">GValue</span></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" title="GValue"><span class="type">GValue</span></a> to another <a class="link" href="gobject-Generic-values.html#GValue" title="GValue"><span class="type">GValue</span></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.
+        </p>
+<p>
+          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"><span class="type">GObject</span></a>
+          instance pointer (sample code for this is located in the source tarball for this document in
+          <code class="filename">sample/gtype/test.c</code>):
+</p>
+<pre class="programlisting">
+static void test_int (void)
+{
+  GValue a_value = G_VALUE_INIT;
+  GValue b_value = G_VALUE_INIT;
+  guint64 a, b;
+  a = 0xdeadbeaf;
+  g_value_init (&amp;a_value, G_TYPE_UINT64);
+  g_value_set_uint64 (&amp;a_value, a);
+  g_value_init (&amp;b_value, G_TYPE_UINT64);
+  g_value_copy (&amp;a_value, &amp;b_value);
+  b = g_value_get_uint64 (&amp;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 (MAMAN_TYPE_BAR, NULL);
+  g_value_init (&amp;obj_vala, MAMAN_TYPE_BAR);
+  g_value_set_object (&amp;obj_vala, obj);
+  g_value_init (&amp;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
+     MAMAN_TYPE_BAR is a G_TYPE_OBJECT.
+   */
+  g_value_copy (&amp;obj_vala, &amp;obj_valb);
+  g_object_unref (G_OBJECT (obj));
+  g_object_unref (G_OBJECT (obj));
+}
+</pre>
+<p>
+          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.
+        </p>
+<p>
+          The value_table used to specify these assignment functions is defined in
+          <code class="filename">gtype.h</code> and is thoroughly described in the
+          API documentation provided with GObject (for once ;-) which is why we will
+          not detail its exact semantics.
+          </p>
+<pre class="programlisting">
+typedef struct _GTypeValueTable         GTypeValueTable;
+struct _GTypeValueTable
+{
+  void     (*value_init)         (GValue       *value);
+  void     (*value_free)         (GValue       *value);
+  void     (*value_copy)         (const GValue *src_value,
+                                  GValue       *dest_value);
+  /* varargs functionality (optional) */
+  gpointer (*value_peek_pointer) (const GValue *value);
+  gchar            *collect_format;
+  gchar*   (*collect_value)      (GValue       *value,
+                                  guint         n_collect_values,
+                                  GTypeCValue  *collect_values,
+                                  guint                collect_flags);
+  gchar            *lcopy_format;
+  gchar*   (*lcopy_value)        (const GValue *value,
+                                  guint         n_collect_values,
+                                  GTypeCValue  *collect_values,
+                                  guint                collect_flags);
+};
+          </pre>
+<p>
+          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 which means that unless you want to write a
+          fundamental type (not a great idea!), you will not need to provide
+          a new value_table since you will inherit the value_table structure
+          from your parent type.
+        </p>
+</div>
+<div class="footnotes">
+<br><hr style="width:100; text-align:left;margin-left: 0">
+<div id="ftn.id-1.3.3.3.7" class="footnote"><p><a href="#id-1.3.3.3.7" class="para"><sup class="para">[2] </sup></a>
+            Please note that there exists another registration function: the
+            <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>. We will not discuss this
+            function here since its use is very similar to the <code class="function">_static</code>
+            version.
+          </p></div>
+</div>
+</div>
+<div class="footer">
+<hr>
+          Generated by GTK-Doc V1.21.1</div>
+</body>
+</html>