|
Server : Apache/2.2.17 (Unix) mod_ssl/2.2.17 OpenSSL/0.9.8e-fips-rhel5 DAV/2 PHP/5.2.17 System : Linux localhost 2.6.18-419.el5 #1 SMP Fri Feb 24 22:47:42 UTC 2017 x86_64 User : nobody ( 99) PHP Version : 5.2.17 Disable Function : NONE Directory : /proc/21572/root/usr/share/gtk-doc/html/gobject/ |
Upload File : |
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>The GObject messaging system</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.69.1">
<link rel="start" 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.6 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
<link rel="preface" href="pr01.html" title="Introduction">
<link rel="part" href="pt01.html" title="Part I. Concepts">
<link rel="chapter" href="ch01.html" title="Background">
<link rel="chapter" href="ch02.html" title="The Glib Dynamic Type System">
<link rel="chapter" href="chapter-gobject.html" title="The GObject base class">
<link rel="chapter" href="chapter-signal.html" title="The GObject messaging system">
<link rel="reference" href="rn01.html" title="API Reference">
<link rel="reference" href="rn02.html" title="Tools Reference">
<link rel="part" href="pt02.html" title="Part IV. Tutorial">
<link rel="chapter" href="howto-gobject.html" title="How To define and implement a new GObject?">
<link rel="chapter" href="howto-interface.html" title="How To define and implement Interfaces?">
<link rel="chapter" href="howto-signals.html" title="Howto create and use signals">
<link rel="part" href="pt03.html" title="Part V. Related Tools">
<link rel="chapter" href="tools-gob.html" title="GObject builder">
<link rel="chapter" href="tools-ginspector.html" title="Graphical inspection of Gobjects">
<link rel="chapter" href="tools-refdb.html" title="Debugging reference count problems">
<link rel="chapter" href="tools-gtkdoc.html" title="Writing API docs">
<link rel="index" href="ix01.html" title="Index">
<link rel="index" href="ix02.html" title="Index of deprecated symbols">
<link rel="index" href="ix03.html" title="Index of new symbols in 2.2">
<link rel="index" href="ix04.html" title="Index of new symbols in 2.4">
<link rel="index" href="ix05.html" title="Index of new symbols in 2.6">
<link rel="index" href="ix06.html" title="Index of new symbols in 2.8">
<link rel="index" href="ix07.html" title="Index of new symbols in 2.10">
<link rel="index" href="ix08.html" title="Index of new symbols in 2.12">
</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" lang="en">
<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#id2623283">C Closures</a></span></dt>
<dt><span class="sect2"><a href="chapter-signal.html#id2623380">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" lang="en">
<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 type="disc">
<li>
<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><p>
the user_data pointer which is passed to the callback upon invocation of the closure
</p></li>
<li><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 href="gobject-Closures.html#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="id2623144" href="#ftn.id2623144">7</a>]</sup>
The GObject library provides a simple <span class="type"><a href="gobject-Closures.html#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 href="gobject-Closures.html#GClosure">GClosure</a></span> provides simple services:
</p>
<div class="itemizedlist"><ul type="disc">
<li><p>
Invocation (<code class="function"><a href="gobject-Closures.html#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 invocator.
</p></li>
<li><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 href="gobject-Closures.html#g-closure-add-finalize-notifier">g_closure_add_finalize_notifier</a></code>
(finalization notification), <code class="function"><a href="gobject-Closures.html#g-closure-add-invalidate-notifier">g_closure_add_invalidate_notifier</a></code>
(invalidation notification) and
<code class="function"><a href="gobject-Closures.html#g-closure-add-marshal-guards">g_closure_add_marshal_guards</a></code> (invocation notification).
There exist symmetric de-registration functions for finalization and invalidation
events (<code class="function"><a href="gobject-Closures.html#g-closure-remove-finalize-notifier">g_closure_remove_finalize_notifier</a></code> and
<code class="function"><a href="gobject-Closures.html#g-closure-remove-invalidate-notifier">g_closure_remove_invalidate_notifier</a></code>) but not for the invocation
process.
<sup>[<a name="id2623272" href="#ftn.id2623272">8</a>]</sup>
</p></li>
</ul></div>
<p>
</p>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id2623283"></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 the simple <span class="type"><a href="gobject-Closures.html#GCClosure">GCClosure</a></span>s
which have a pretty minimal API or the even simpler <code class="function"><a href="gobject-Signals.html#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 href="gobject-Closures.html#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 href="gobject-Closures.html#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 href="gobject-Closures.html#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" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id2623380"></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->data;
callback = (GMarshalFunc_VOID__INT) (marshal_data ? marshal_data : cc->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 tupple 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>pygtk</em></span> module in Gnome cvs server).
</p>
</div>
</div>
<div class="footnotes">
<br><hr width="100" align="left">
<div class="footnote"><p><sup>[<a name="ftn.id2623144" href="#id2623144">7</a>] </sup>
In Practice, Closures sit at the boundary of language runtimes: if you are
writing python code and one of your Python callback receives a signal from
one of GTK+ widgets, 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.id2623272" href="#id2623272">8</a>] </sup>
Closures are refcounted and notify listeners of their destruction in a two-stage
process: the invalidation notifiers are invoked before the finalization notifiers.
</p></div>
</div>
</div>
</body>
</html>