RubyGems - gio2 - Versions diffs - 0.90.3-x86-mingw32 - Mend

gio2 0.90.3-x86-mingw32

Files changed (856) hide show

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

@@ -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>The GLib Dynamic Type System</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="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.15.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="2"><tr valign="middle">
+<td><a accesskey="p" href="ch01s02.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
+<td><a accesskey="u" href="pt01.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-conventions.html"><img src="right.png" width="24" height="24" 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>
+<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 <span class="type"><a class="link" href="gobject-Type-Information.html#GType" title="GType">GType</a></span> 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.
+        <sup>[<a name="id356493" href="#ftn.id356493" class="footnote">2</a>]</sup>
+      </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 by <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-init" title="g_type_init ()">g_type_init</a></code>, 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" type="disc">
+<li class="listitem"><p>
+            class size: the class_size field in <span class="type"><a class="link" href="gobject-Type-Information.html#GTypeInfo" title="GTypeInfo">GTypeInfo</a></span>.
+          </p></li>
+<li class="listitem"><p>
+            class initialization functions (C++ constructor): the base_init and
+            class_init fields in <span class="type"><a class="link" href="gobject-Type-Information.html#GTypeInfo" title="GTypeInfo">GTypeInfo</a></span>.
+          </p></li>
+<li class="listitem"><p>
+            class destruction functions (C++ destructor): the base_finalize and
+            class_finalize fields in <span class="type"><a class="link" href="gobject-Type-Information.html#GTypeInfo" title="GTypeInfo">GTypeInfo</a></span>.
+          </p></li>
+<li class="listitem"><p>
+            instance size (C++ parameter to new): the instance_size field in
+            <span class="type"><a class="link" href="gobject-Type-Information.html#GTypeInfo" title="GTypeInfo">GTypeInfo</a></span>.
+          </p></li>
+<li class="listitem"><p>
+            instantiation policy (C++ type of new operator): the n_preallocs
+            field in <span class="type"><a class="link" href="gobject-Type-Information.html#GTypeInfo" title="GTypeInfo">GTypeInfo</a></span>.
+          </p></li>
+<li class="listitem"><p>
+            copy functions (C++ copy operators): the value_table field in
+            <span class="type"><a class="link" href="gobject-Type-Information.html#GTypeInfo" title="GTypeInfo">GTypeInfo</a></span>.
+          </p></li>
+<li class="listitem"><p>
+            type characteristic flags: <span class="type"><a class="link" href="gobject-Type-Information.html#GTypeFlags" title="enum GTypeFlags">GTypeFlags</a></span>.
+          </p></li>
+</ul></div>
+<p>
+        Fundamental types are also defined by a set of <span class="type"><a class="link" href="gobject-Type-Information.html#GTypeFundamentalFlags" title="enum GTypeFundamentalFlags">GTypeFundamentalFlags</a></span>
+        which are stored in a <span class="type"><a class="link" href="gobject-Type-Information.html#GTypeFundamentalInfo" title="GTypeFundamentalInfo">GTypeFundamentalInfo</a></span>.
+        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 <span class="type"><a class="link" href="gobject-Generic-values.html#GValue" title="GValue">GValue</a></span> 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 <span class="type"><a class="link" href="gobject-Generic-values.html#GValue" title="GValue">GValue</a></span> to another <span class="type"><a class="link" href="gobject-Generic-values.html#GValue" title="GValue">GValue</a></span>. 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 <span class="type"><a class="link" href="gobject-The-Base-Object-Type.html#GObject">GObject</a></span>
+          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 = {0, };
+  GValue b_value = {0, };
+  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 = {0, };
+  GValue obj_valb = {0, };
+  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 width="100" align="left">
+<div class="footnote"><p><sup>[<a name="ftn.id356493" href="#id356493" class="para">2</a>] </sup>
+            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.15.1</div>
+</body>
+</html>

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

@@ -0,0 +1,92 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>Background</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="pt01.html" title="Part I. Concepts">
+<link rel="prev" href="pt01.html" title="Part I. Concepts">
+<link rel="next" href="ch01s02.html" title="Exporting a C API">
+<meta name="generator" content="GTK-Doc V1.15.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="2"><tr valign="middle">
+<td><a accesskey="p" href="pt01.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
+<td><a accesskey="u" href="pt01.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="ch01s02.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
+</tr></table>
+<div class="chapter">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="chapter-intro"></a>Background</h2></div></div></div>
+<div class="toc"><dl>
+<dt><span class="sect1"><a href="chapter-intro.html#id313385">Data types and programming</a></span></dt>
+<dt><span class="sect1"><a href="ch01s02.html">Exporting a C API</a></span></dt>
+</dl></div>
+<p>
+    GObject, and its lower-level type system, GType, are used by GTK+ and most GNOME libraries to
+    provide:
+    </p>
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem"><p>object-oriented C-based APIs and</p></li>
+<li class="listitem"><p>automatic transparent API bindings to other compiled
+      or interpreted languages.</p></li>
+</ul></div>
+<p>
+  </p>
+<p>
+    A lot of programmers are used to working with compiled-only or dynamically interpreted-only
+    languages and do not understand the challenges associated with cross-language interoperability.
+    This introduction tries to provide an insight into these challenges and briefly describes
+    the solution chosen by GLib.
+  </p>
+<p>
+    The following chapters go into greater detail into how GType and GObject work and
+    how you can use them as a C programmer. It is useful to keep in mind that
+    allowing access to C objects from other interpreted languages was one of the major design
+    goals: this can often explain the sometimes rather convoluted APIs and features present
+    in this library.
+  </p>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="id313385"></a>Data types and programming</h2></div></div></div>
+<p>
+      One could say (I have seen such definitions used in some textbooks on programming language theory)
+      that a programming language is merely a way to create data types and manipulate them. Most languages
+      provide a number of language-native types and a few primitives to create more complex types based
+      on these primitive types.
+    </p>
+<p>
+      In C, the language provides types such as <span class="emphasis"><em>char</em></span>, <span class="emphasis"><em>long</em></span>,
+      <span class="emphasis"><em>pointer</em></span>. During compilation of C code, the compiler maps these
+      language types to the compiler's target architecture machine types. If you are using a C interpreter
+      (I have never seen one myself but it is possible :), the interpreter (the program which interprets
+      the source code and executes it) maps the language types to the machine types of the target machine at
+      runtime, during the program execution (or just before execution if it uses a Just In Time compiler engine).
+    </p>
+<p>
+      Perl and Python are interpreted languages which do not really provide type definitions similar
+      to those used by C. Perl and Python programmers manipulate variables and the type of the variables
+      is decided only upon the first assignment or upon the first use which forces a type on the variable.
+      The interpreter also often provides a lot of automatic conversions from one type to the other. For example,
+      in Perl, a variable which holds an integer can be automatically converted to a string given the
+      required context:
+</p>
+<pre class="programlisting">
+my $tmp = 10;
+print "this is an integer converted to a string:" . $tmp . "\n";
+</pre>
+<p>
+      Of course, it is also often possible to explicitly specify conversions when the default conversions provided
+      by the language are not intuitive.
+    </p>
+</div>
+</div>
+<div class="footer">
+<hr>
+          Generated by GTK-Doc V1.15.1</div>
+</body>
+</html>

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

@@ -0,0 +1,214 @@
+<!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 GObject messaging system</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="pt01.html" title="Part I. Concepts">
+<link rel="prev" href="gobject-properties.html" title="Object properties">
+<link rel="next" href="signal.html" title="Signals">
+<meta name="generator" content="GTK-Doc V1.15.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="2"><tr valign="middle">
+<td><a accesskey="p" href="gobject-properties.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
+<td><a accesskey="u" href="pt01.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="signal.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
+</tr></table>
+<div class="chapter">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="chapter-signal"></a>The GObject messaging system</h2></div></div></div>
+<div class="toc"><dl>
+<dt><span class="sect1"><a href="chapter-signal.html#closure">Closures</a></span></dt>
+<dd><dl>
+<dt><span class="sect2"><a href="chapter-signal.html#id386863">C Closures</a></span></dt>
+<dt><span class="sect2"><a href="chapter-signal.html#id382891">Non-C closures (for the fearless)</a></span></dt>
+</dl></dd>
+<dt><span class="sect1"><a href="signal.html">Signals</a></span></dt>
+<dd><dl>
+<dt><span class="sect2"><a href="signal.html#signal-registration">Signal registration</a></span></dt>
+<dt><span class="sect2"><a href="signal.html#signal-connection">Signal connection</a></span></dt>
+<dt><span class="sect2"><a href="signal.html#signal-emission">Signal emission</a></span></dt>
+<dt><span class="sect2"><a href="signal.html#signal-detail">The <span class="emphasis"><em>detail</em></span> argument</a></span></dt>
+</dl></dd>
+</dl></div>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="closure"></a>Closures</h2></div></div></div>
+<p>
+      Closures are central to the concept of asynchronous signal delivery
+      which is widely used throughout GTK+ and GNOME applications. A closure is an
+      abstraction, a generic representation of a callback. It is a small structure
+      which contains three objects:
+      </p>
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem">
+<p>a function pointer (the callback itself) whose prototype looks like:
+</p>
+<pre class="programlisting">
+return_type function_callback (... , gpointer user_data);
+</pre>
+<p>
+        </p>
+</li>
+<li class="listitem"><p>
+           the user_data pointer which is passed to the callback upon invocation of the closure
+          </p></li>
+<li class="listitem"><p>
+           a function pointer which represents the destructor of the closure: whenever the
+           closure's refcount reaches zero, this function will be called before the closure
+           structure is freed.
+          </p></li>
+</ul></div>
+<p>
+    </p>
+<p>
+      The <span class="type"><a class="link" href="gobject-Closures.html#GClosure" title="GClosure">GClosure</a></span> structure represents the common functionality of all
+      closure implementations: there exists a different Closure implementation for
+      each separate runtime which wants to use the GObject type system.
+      <sup>[<a name="id359882" href="#ftn.id359882" class="footnote">6</a>]</sup>
+      The GObject library provides a simple <span class="type"><a class="link" href="gobject-Closures.html#GCClosure" title="GCClosure">GCClosure</a></span> type which
+      is a specific implementation of closures to be used with C/C++ callbacks.
+    </p>
+<p>
+      A <span class="type"><a class="link" href="gobject-Closures.html#GClosure" title="GClosure">GClosure</a></span> provides simple services:
+      </p>
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem"><p>
+          Invocation (<code class="function"><a class="link" href="gobject-Closures.html#g-closure-invoke" title="g_closure_invoke ()">g_closure_invoke</a></code>): this is what closures
+          were created for: they hide the details of callback invocation from the
+          callback invoker.</p></li>
+<li class="listitem"><p>
+          Notification: the closure notifies listeners of certain events such as
+          closure invocation, closure invalidation and closure finalization. Listeners
+          can be registered with <code class="function"><a class="link" href="gobject-Closures.html#g-closure-add-finalize-notifier" title="g_closure_add_finalize_notifier ()">g_closure_add_finalize_notifier</a></code>
+          (finalization notification), <code class="function"><a class="link" href="gobject-Closures.html#g-closure-add-invalidate-notifier" title="g_closure_add_invalidate_notifier ()">g_closure_add_invalidate_notifier</a></code>
+          (invalidation notification) and
+          <code class="function"><a class="link" href="gobject-Closures.html#g-closure-add-marshal-guards" title="g_closure_add_marshal_guards ()">g_closure_add_marshal_guards</a></code> (invocation notification).
+          There exist symmetric deregistration functions for finalization and invalidation
+          events (<code class="function"><a class="link" href="gobject-Closures.html#g-closure-remove-finalize-notifier" title="g_closure_remove_finalize_notifier ()">g_closure_remove_finalize_notifier</a></code> and
+          <code class="function"><a class="link" href="gobject-Closures.html#g-closure-remove-invalidate-notifier" title="g_closure_remove_invalidate_notifier ()">g_closure_remove_invalidate_notifier</a></code>) but not for the invocation
+          process.
+          <sup>[<a name="id386852" href="#ftn.id386852" class="footnote">7</a>]</sup></p></li>
+</ul></div>
+<p>
+    </p>
+<div class="sect2">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id386863"></a>C Closures</h3></div></div></div>
+<p>
+        If you are using C or C++
+        to connect a callback to a given event, you will either use simple <span class="type"><a class="link" href="gobject-Closures.html#GCClosure" title="GCClosure">GCClosure</a></span>s
+        which have a pretty minimal API or the even simpler <code class="function"><a class="link" href="gobject-Signals.html#g-signal-connect" title="g_signal_connect()">g_signal_connect</a></code>
+        functions (which will be presented a bit later :).
+</p>
+<pre class="programlisting">
+GClosure *g_cclosure_new             (GCallback      callback_func,
+                                      gpointer       user_data,
+                                      GClosureNotify destroy_data);
+GClosure *g_cclosure_new_swap        (GCallback      callback_func,
+                                      gpointer       user_data,
+                                      GClosureNotify destroy_data);
+GClosure *g_signal_type_cclosure_new (GType          itype,
+                                      guint          struct_offset);
+</pre>
+<p>
+      </p>
+<p>
+        <code class="function"><a class="link" href="gobject-Closures.html#g-cclosure-new" title="g_cclosure_new ()">g_cclosure_new</a></code> will create a new closure which can invoke the
+        user-provided callback_func with the user-provided user_data as last parameter. When the closure
+        is finalized (second stage of the destruction process), it will invoke the destroy_data function
+        if the user has supplied one.
+      </p>
+<p>
+        <code class="function"><a class="link" href="gobject-Closures.html#g-cclosure-new-swap" title="g_cclosure_new_swap ()">g_cclosure_new_swap</a></code> will create a new closure which can invoke the
+        user-provided callback_func with the user-provided user_data as first parameter (instead of being the
+        last parameter as with <code class="function"><a class="link" href="gobject-Closures.html#g-cclosure-new" title="g_cclosure_new ()">g_cclosure_new</a></code>). When the closure
+        is finalized (second stage of the destruction process), it will invoke the destroy_data
+        function if the user has supplied one.
+      </p>
+</div>
+<div class="sect2">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id382891"></a>Non-C closures (for the fearless)</h3></div></div></div>
+<p>
+        As was explained above, closures hide the details of callback invocation. In C,
+        callback invocation is just like function invocation: it is a matter of creating
+        the correct stack frame for the called function and executing a <span class="emphasis"><em>call</em></span>
+        assembly instruction.
+      </p>
+<p>
+        C closure marshallers transform the array of GValues which represent
+        the parameters to the target function into a C-style function parameter list, invoke
+        the user-supplied C function with this new parameter list, get the return value of the
+        function, transform it into a GValue and return this GValue to the marshaller caller.
+      </p>
+<p>
+        The following code implements a simple marshaller in C for a C function which takes an
+        integer as first parameter and returns void.
+</p>
+<pre class="programlisting">
+g_cclosure_marshal_VOID__INT (GClosure     *closure,
+                              GValue       *return_value,
+                              guint         n_param_values,
+                              const GValue *param_values,
+                              gpointer      invocation_hint,
+                              gpointer      marshal_data)
+{
+  typedef void (*GMarshalFunc_VOID__INT) (gpointer     data1,
+                                          gint         arg_1,
+                                          gpointer     data2);
+  register GMarshalFunc_VOID__INT callback;
+  register GCClosure *cc = (GCClosure*) closure;
+  register gpointer data1, data2;
+  g_return_if_fail (n_param_values == 2);
+  data1 = g_value_peek_pointer (param_values + 0);
+  data2 = closure-&gt;data;
+  callback = (GMarshalFunc_VOID__INT) (marshal_data ? marshal_data : cc-&gt;callback);
+  callback (data1,
+            g_marshal_value_peek_int (param_values + 1),
+            data2);
+}
+</pre>
+<p>
+      </p>
+<p>
+        Of course, there exist other kinds of marshallers. For example, James Henstridge
+        wrote a generic Python marshaller which is used by all Python closures (a Python closure
+        is used to have Python-based callback be invoked by the closure invocation process).
+        This Python marshaller transforms the input GValue list representing the function
+        parameters into a Python tuple which is the equivalent structure in Python (you can
+        look in <code class="function">pyg_closure_marshal</code> in <code class="filename">pygtype.c</code>
+        in the <span class="emphasis"><em>pygobject</em></span> module in the GNOME source code repository).
+      </p>
+</div>
+</div>
+<div class="footnotes">
+<br><hr width="100" align="left">
+<div class="footnote"><p><sup>[<a name="ftn.id359882" href="#id359882" class="para">6</a>] </sup>
+        In practice, closures sit at the boundary of language runtimes: if you are
+        writing Python code and one of your Python callbacks receives a signal from
+        a GTK+ widget, the C code in GTK+ needs to execute your Python
+        code. The closure invoked by the GTK+ object invokes the Python callback:
+        it behaves as a normal C object for GTK+ and as a normal Python object for
+        Python code.
+      </p></div>
+<div class="footnote"><p><sup>[<a name="ftn.id386852" href="#id386852" class="para">7</a>] </sup>
+            Closures are reference counted and notify listeners of their destruction in a two-stage
+            process: the invalidation notifiers are invoked before the finalization notifiers.
+          </p></div>
+</div>
+</div>
+<div class="footer">
+<hr>
+          Generated by GTK-Doc V1.15.1</div>
+</body>
+</html>