[boost-doc-zh commit] r245 - 1.39.0新增 signals2 库的E文文
- From: codesite-noreply@xxxxxxxxxx
- To: boost-doc-zh-notify@xxxxxxxxxxxxx
- Date: Fri, 08 May 2009 04:57:13 +0000
Author: alai04
Date: Thu May 7 20:34:38 2009
New Revision: 245
Added:
trunk/doc/html/signals2/
trunk/doc/html/signals2.html
trunk/doc/html/signals2/examples.html
trunk/doc/html/signals2/faq.html
trunk/doc/html/signals2/porting.html
trunk/doc/html/signals2/rationale.html
trunk/doc/html/signals2/reference.html
trunk/doc/html/signals2/tests.html
trunk/doc/html/signals2/thread-safety.html
trunk/doc/html/signals2/tutorial.html
trunk/libs/signals2/
trunk/libs/signals2/doc/
trunk/libs/signals2/doc/examples.xml
trunk/libs/signals2/doc/faq.xml
trunk/libs/signals2/doc/introduction.xml
trunk/libs/signals2/doc/porting.xml
trunk/libs/signals2/doc/rationale.xml
trunk/libs/signals2/doc/reference/
trunk/libs/signals2/doc/reference/connection.xml
trunk/libs/signals2/doc/reference/deconstruct.xml
trunk/libs/signals2/doc/reference/dummy_mutex.xml
trunk/libs/signals2/doc/reference/last_value.xml
trunk/libs/signals2/doc/reference/mutex.xml
trunk/libs/signals2/doc/reference/optional_last_value.xml
trunk/libs/signals2/doc/reference/reference.xml
trunk/libs/signals2/doc/reference/shared_connection_block.xml
trunk/libs/signals2/doc/reference/signal_base.xml
trunk/libs/signals2/doc/reference/signal_header.xml
trunk/libs/signals2/doc/reference/signal_type.xml
trunk/libs/signals2/doc/reference/slot.xml
trunk/libs/signals2/doc/reference/slot_base.xml
trunk/libs/signals2/doc/reference/trackable.xml
trunk/libs/signals2/doc/reference/visit_each.xml
trunk/libs/signals2/doc/signals.xml
trunk/libs/signals2/doc/tests.xml
trunk/libs/signals2/doc/thread_safety.xml
trunk/libs/signals2/doc/tutorial.xml
trunk/libs/signals2/index.html
Log:
1.39.0新增 signals2 库的E文文
Added: trunk/doc/html/signals2.html
==============================================================================
--- (empty file)
+++ trunk/doc/html/signals2.html Thu May 7 20:34:38 2009
@@ -0,0 +1,151 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Chapter�17.�Boost.Signals2</title>
+<link rel="stylesheet" href="boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.3">
+<link rel="home" href="index.html" title="The Boost C++ Libraries
BoostBook Documentation Subset">
+<link rel="up" href="libraries.html" title="Part�I.�The Boost C++
Libraries (BoostBook Subset)">
+<link rel="prev" href="signals/tests.html" title="Testsuite">
+<link rel="next" href="signals2/tutorial.html" title="Tutorial">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084"
alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86"
src="../../boost.png"></td>
+<td align="center"><a href="../../index.html">Home</a></td>
+<td align="center"><a href="../../libs/libraries.htm">Libraries</a></td>
+<td align="center"><a
href="http://www.boost.org/users/people.html";>People</a></td>
+<td align="center"><a
href="http://www.boost.org/users/faq.html";>FAQ</a></td>
+<td align="center"><a href="../../more/index.htm">More</a></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="signals/tests.html"><img
src="../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u"
href="libraries.html"><img src="../../doc/html/images/up.png"
alt="Up"></a><a accesskey="h" href="index.html"><img
src="../../doc/html/images/home.png" alt="Home"></a><a accesskey="n"
href="signals2/tutorial.html"><img src="../../doc/html/images/next.png"
alt="Next"></a>
+</div>
+<div class="chapter" lang="en">
+<div class="titlepage"><div>
+<div><h2 class="title">
+<a name="signals2"></a>Chapter�17.�Boost.Signals2</h2></div>
+<div><div class="author"><h3 class="author">
+<span class="firstname">Douglas</span> <span class="surname">Gregor</span>
+</h3></div></div>
+<div><div class="author"><h3 class="author">
+<span class="firstname">Frank</span> <span class="othername">Mori</span>
<span class="surname">Hess</span>
+</h3></div></div>
+<div><p class="copyright">Copyright � 2001-2004 Douglas Gregor</p></div>
+<div><p class="copyright">Copyright � 2007-2009 Frank Mori Hess</p></div>
+<div><div class="legalnotice">
+<a name="id3351304"></a><p>Distributed under the Boost
+ Software License, Version 1.0. (See accompanying file
+ <code class="filename">LICENSE_1_0.txt</code> or copy at <a
href="http://www.boost.org/LICENSE_1_0.txt";
target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)</p>
+</div></div>
+</div></div>
+<div class="toc">
+<p><b>Table of Contents</b></p>
+<dl>
+<dt><span class="section"><a
href="signals2.html#id3351328">Introduction</a></span></dt>
+<dd><dl><dt><span class="section"><a
href="signals2.html#id3351365">Signals2</a></span></dt></dl></dd>
+<dt><span class="section"><a
href="signals2/tutorial.html">Tutorial</a></span></dt>
+<dd><dl>
+<dt><span class="section"><a href="signals2/tutorial.html#id3351397">How
to Read this Tutorial</a></span></dt>
+<dt><span class="section"><a
href="signals2/tutorial.html#id3351460">Compatibility Note</a></span></dt>
+<dt><span class="section"><a
href="signals2/tutorial.html#id3351478">Hello, World!
(Beginner)</a></span></dt>
+<dt><span class="section"><a
href="signals2/tutorial.html#id3351586">Calling Multiple
Slots</a></span></dt>
+<dt><span class="section"><a
href="signals2/tutorial.html#id3351941">Passing Values to and from
Slots</a></span></dt>
+<dt><span class="section"><a
href="signals2/tutorial.html#id3352571">Connection
Management</a></span></dt>
+<dt><span class="section"><a
href="signals2/tutorial.html#signals2.tutorial.document-view">Example:
Document-View</a></span></dt>
+<dt><span class="section"><a
href="signals2/tutorial.html#signals2.tutorial.extended-slot-type">Giving a
Slot Access to its Connection (Advanced)</a></span></dt>
+<dt><span class="section"><a
href="signals2/tutorial.html#signals2.tutorial.signal-mutex-template-parameter">Changing
the Mutex Type of a Signal (Advanced).</a></span></dt>
+<dt><span class="section"><a
href="signals2/tutorial.html#id3353969">Linking against the Signals2
library</a></span></dt>
+</dl></dd>
+<dt><span class="section"><a href="signals2/examples.html">Example
programs</a></span></dt>
+<dd><dl>
+<dt><span class="section"><a
href="signals2/examples.html#signals2.examples.misc">Miscellaneous Tutorial
Examples</a></span></dt>
+<dt><span class="section"><a
href="signals2/examples.html#signals2.examples.document-view">Document-View</a></span></dt>
+<dt><span class="section"><a
href="signals2/examples.html#signals2.examples.deconstruct">Postconstructors
and Predestructors with deconstruct()</a></span></dt>
+</dl></dd>
+<dt><span class="section"><a
href="signals2/reference.html">Reference</a></span></dt>
+<dd><dl>
+<dt><span class="section"><a
href="signals2/reference.html#header.boost.signals2_hpp">Header
<boost/signals2.hpp></a></span></dt>
+<dt><span class="section"><a
href="signals2/reference.html#header.boost.signals2.connection_hpp">Header
<boost/signals2/connection.hpp></a></span></dt>
+<dt><span class="section"><a
href="signals2/reference.html#header.boost.signals2.deconstruct_hpp">Header
<boost/signals2/deconstruct.hpp></a></span></dt>
+<dt><span class="section"><a
href="signals2/reference.html#header.boost.signals2.dummy_mutex_hpp">Header
<boost/signals2/dummy_mutex.hpp></a></span></dt>
+<dt><span class="section"><a
href="signals2/reference.html#header.boost.signals2.last_value_hpp">Header
<boost/signals2/last_value.hpp></a></span></dt>
+<dt><span class="section"><a
href="signals2/reference.html#header.boost.signals2.mutex_hpp">Header
<boost/signals2/mutex.hpp></a></span></dt>
+<dt><span class="section"><a
href="signals2/reference.html#header.boost.signals2.optional_last_value_hpp">Header
<boost/signals2/optional_last_value.hpp></a></span></dt>
+<dt><span class="section"><a
href="signals2/reference.html#header.boost.signals2.shared_connection_block_hpp">Header
<boost/signals2/shared_connection_block.hpp></a></span></dt>
+<dt><span class="section"><a
href="signals2/reference.html#header.boost.signals2.signal_hpp">Header
<boost/signals2/signal.hpp></a></span></dt>
+<dt><span class="section"><a
href="signals2/reference.html#header.boost.signals2.signal_base_hpp">Header
<boost/signals2/signal_base.hpp></a></span></dt>
+<dt><span class="section"><a
href="signals2/reference.html#header.boost.signals2.signal_type_hpp">Header
<boost/signals2/signal_type.hpp></a></span></dt>
+<dt><span class="section"><a
href="signals2/reference.html#header.boost.signals2.slot_hpp">Header
<boost/signals2/slot.hpp></a></span></dt>
+<dt><span class="section"><a
href="signals2/reference.html#header.boost.signals2.slot_base_hpp">Header
<boost/signals2/slot_base.hpp></a></span></dt>
+<dt><span class="section"><a
href="signals2/reference.html#header.boost.signals2.trackable_hpp">Header
<boost/signals2/trackable.hpp></a></span></dt>
+</dl></dd>
+<dt><span class="section"><a
href="signals2/thread-safety.html">Thread-Safety</a></span></dt>
+<dd><dl>
+<dt><span class="section"><a
href="signals2/thread-safety.html#id3385400">Introduction</a></span></dt>
+<dt><span class="section"><a
href="signals2/thread-safety.html#id3385455">Signals and
combiners</a></span></dt>
+<dt><span class="section"><a
href="signals2/thread-safety.html#id3385620">Connections and other
classes</a></span></dt>
+</dl></dd>
+<dt><span class="section"><a href="signals2/faq.html">Frequently Asked
Questions</a></span></dt>
+<dt><span class="section"><a href="signals2/rationale.html">Design
Rationale</a></span></dt>
+<dd><dl>
+<dt><span class="section"><a
href="signals2/rationale.html#id3385960">User-level Connection
Management</a></span></dt>
+<dt><span class="section"><a
href="signals2/rationale.html#id3386133">Automatic Connection
Management</a></span></dt>
+<dt><span class="section"><a
href="signals2/rationale.html#id3386287">optional_last_value as the Default
Combiner</a></span></dt>
+<dt><span class="section"><a
href="signals2/rationale.html#id3386348">Combiner Interface</a></span></dt>
+<dt><span class="section"><a
href="signals2/rationale.html#id3386428">Connection Interfaces: +=
operator</a></span></dt>
+<dt><span class="section"><a
href="signals2/rationale.html#id3386600">Signals2 Mutex
Classes</a></span></dt>
+<dt><span class="section"><a
href="signals2/rationale.html#id3386712">Comparison with other Signal/Slot
implementations</a></span></dt>
+</dl></dd>
+<dt><span class="section"><a href="signals2/porting.html">Porting from
Boost.Signals to Boost.Signals2</a></span></dt>
+<dt><span class="section"><a
href="signals2/tests.html">Testsuite</a></span></dt>
+<dd><dl><dt><span class="section"><a
href="signals2/tests.html#id3387753">Acceptance
tests</a></span></dt></dl></dd>
+</dl>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="id3351328"></a>Introduction</h2></div></div></div>
+<div class="toc"><dl><dt><span class="section"><a
href="signals2.html#id3351365">Signals2</a></span></dt></dl></div>
+<p>The Boost.Signals2 library is an implementation of a managed
+ signals and slots system. Signals represent callbacks with multiple
+ targets, and are also called publishers or events in similar
+ systems. Signals are connected to some set of slots, which are
+ callback receivers (also called event targets or subscribers), which
+ are called when the signal is "emitted."</p>
+<p>Signals and slots are managed, in that signals and slots (or,
+ more properly, objects that occur as part of the slots) can track
+ connections and are capable of automatically disconnecting signal/slot
+ connections when either is destroyed. This enables the user to make
+ signal/slot connections without expending a great effort to manage the
+ lifetimes of those connections with regard to the lifetimes of all
+ objects involved.</p>
+<p>When signals are connected to multiple slots, there is a
+ question regarding the relationship between the return values of the
+ slots and the return value of the signals. Boost.Signals2 allows the
+ user to specify the manner in which multiple return values are
+ combined.</p>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id3351365"></a>Signals2</h3></div></div></div>
+<p>This documentation describes a thread-safe variant of the
+ original Boost.Signals library. There have been some changes to
+ the interface to support thread-safety, mostly with respect to
+ automatic connection management. This implementation was written by
+ Frank Mori Hess. Acknowledgements are also due to Timmo Stange, Peter
+ Dimov, and Gottlob Frege for ideas and feedback, and to Douglas Gregor
+ for the original version of Boost.Signals this effort was based on.
+ </p>
+</div>
+</div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision";
width="100%"><tr>
+<td align="left"><p><small>Last revised: June 12, 2007 at 14:01:23
-0400</small></p></td>
+<td align="right"><div class="copyright-footer"></div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="signals/tests.html"><img
src="../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u"
href="libraries.html"><img src="../../doc/html/images/up.png"
alt="Up"></a><a accesskey="h" href="index.html"><img
src="../../doc/html/images/home.png" alt="Home"></a><a accesskey="n"
href="signals2/tutorial.html"><img src="../../doc/html/images/next.png"
alt="Next"></a>
+</div>
+</body>
+</html>
Added: trunk/doc/html/signals2/examples.html
==============================================================================
--- (empty file)
+++ trunk/doc/html/signals2/examples.html Thu May 7 20:34:38 2009
@@ -0,0 +1,249 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Example programs</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.3">
+<link rel="home" href="../index.html" title="The Boost C++ Libraries
BoostBook Documentation Subset">
+<link rel="up" href="../signals2.html" title="Chapter�17.�Boost.Signals2">
+<link rel="prev" href="tutorial.html" title="Tutorial">
+<link rel="next" href="reference.html" title="Reference">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084"
alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86"
src="../../../boost.png"></td>
+<td align="center"><a href="../../../index.html">Home</a></td>
+<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
+<td align="center"><a
href="http://www.boost.org/users/people.html";>People</a></td>
+<td align="center"><a
href="http://www.boost.org/users/faq.html";>FAQ</a></td>
+<td align="center"><a href="../../../more/index.htm">More</a></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="tutorial.html"><img
src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u"
href="../signals2.html"><img src="../../../doc/html/images/up.png"
alt="Up"></a><a accesskey="h" href="../index.html"><img
src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n"
href="reference.html"><img src="../../../doc/html/images/next.png"
alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="signals2.examples"></a>Example programs</h2></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a
href="examples.html#signals2.examples.misc">Miscellaneous Tutorial
Examples</a></span></dt>
+<dt><span class="section"><a
href="examples.html#signals2.examples.document-view">Document-View</a></span></dt>
+<dt><span class="section"><a
href="examples.html#signals2.examples.deconstruct">Postconstructors and
Predestructors with deconstruct()</a></span></dt>
+</dl></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="signals2.examples.misc"></a>Miscellaneous Tutorial
Examples</h3></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a
href="examples.html#signals2.examples.tutorial.hello_world_slot">hello_world_slot</a></span></dt>
+<dt><span class="section"><a
href="examples.html#signals2.examples.tutorial.hello_world_multi_slot">hello_world_multi_slot</a></span></dt>
+<dt><span class="section"><a
href="examples.html#signals2.examples.tutorial.ordering_slots">ordering_slots</a></span></dt>
+<dt><span class="section"><a
href="examples.html#signals2.examples.tutorial.slot_arguments">slot_arguments</a></span></dt>
+<dt><span class="section"><a
href="examples.html#signals2.examples.tutorial.signal_return_value">signal_return_value</a></span></dt>
+<dt><span class="section"><a
href="examples.html#signals2.examples.tutorial.custom_combiners">custom_combiners</a></span></dt>
+<dt><span class="section"><a
href="examples.html#signals2.examples.tutorial.disconnect_and_block">disconnect_and_block</a></span></dt>
+<dt><span class="section"><a
href="examples.html#signals2.examples.tutorial.passing_slots">passing_slots</a></span></dt>
+<dt><span class="section"><a
href="examples.html#signals2.examples.tutorial.extended_slot">extended_slot</a></span></dt>
+</dl></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a
name="signals2.examples.tutorial.hello_world_slot"></a>hello_world_slot</h4></div></div></div>
+<p>
+ This example is a basic example of connecting a slot to a signal
+ and then invoking the signal.
+ </p>
+<p>
+ Download <a
href="../../../libs/signals2/example/hello_world_slot.cpp"
target="_top">hello_world_slot.cpp</a>.
+ </p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a
name="signals2.examples.tutorial.hello_world_multi_slot"></a>hello_world_multi_slot</h4></div></div></div>
+<p>
+ This example extends the hello_world_slot example slightly by
connecting more than one
+ slot to the signal before invoking it.
+ </p>
+<p>
+ Download <a
href="../../../libs/signals2/example/hello_world_multi_slot.cpp"
target="_top">hello_world_multi_slot.cpp</a>.
+ </p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a
name="signals2.examples.tutorial.ordering_slots"></a>ordering_slots</h4></div></div></div>
+<p>
+ This example extends the hello_world_multi_slot example slightly by
+ using slot groups to specify
+ the order slots should be invoked.
+ </p>
+<p>
+ Download <a
href="../../../libs/signals2/example/ordering_slots.cpp"
target="_top">ordering_slots.cpp</a>.
+ </p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a
name="signals2.examples.tutorial.slot_arguments"></a>slot_arguments</h4></div></div></div>
+<p>
+ The slot_arguments program shows how to pass arguments from a
signal invocation to slots.
+ </p>
+<p>
+ Download <a
href="../../../libs/signals2/example/slot_arguments.cpp"
target="_top">slot_arguments.cpp</a>.
+ </p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a
name="signals2.examples.tutorial.signal_return_value"></a>signal_return_value</h4></div></div></div>
+<p>
+ This example shows how to return a value from slots to the signal
invocation.
+ It uses the default <code class="computeroutput"><a class="link"
href="../boost/signals2/optional_last_value.html" title="Class template
optional_last_value">optional_last_value</a></code> combiner.
+ </p>
+<p>
+ Download <a
href="../../../libs/signals2/example/signal_return_value.cpp"
target="_top">signal_return_value.cpp</a>.
+ </p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a
name="signals2.examples.tutorial.custom_combiners"></a>custom_combiners</h4></div></div></div>
+<p>
+ This example shows more returning of values from slots to the
signal invocation.
+ This time, custom combiners are defined and used.
+ </p>
+<p>
+ Download <a
href="../../../libs/signals2/example/custom_combiners.cpp"
target="_top">custom_combiners.cpp</a>.
+ </p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a
name="signals2.examples.tutorial.disconnect_and_block"></a>disconnect_and_block</h4></div></div></div>
+<p>
+ This example demonstrates various means of manually disconnecting
slots, as well as temporarily
+ blocking them via <code class="computeroutput"><a class="link"
href="../boost/signals2/shared_connection_block.html" title="Class
shared_connection_block">shared_connection_block</a></code>.
+ </p>
+<p>
+ Download <a
href="../../../libs/signals2/example/disconnect_and_block.cpp"
target="_top">disconnect_and_block.cpp</a>.
+ </p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a
name="signals2.examples.tutorial.passing_slots"></a>passing_slots</h4></div></div></div>
+<p>
+ This example demonstrates the passing of slot functions to a
private signal
+ through a non-template interface.
+ </p>
+<p>
+ Download <a
href="../../../libs/signals2/example/passing_slots.cpp"
target="_top">passing_slots.cpp</a>.
+ </p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a
name="signals2.examples.tutorial.extended_slot"></a>extended_slot</h4></div></div></div>
+<p>
+ This example demonstrates connecting an extended slot to a
signal. An extended slot
+ accepts a reference to its invoking signal-slot connection as an
additional argument,
+ permitting the slot to temporarily block or permanently disconnect
itself.
+ </p>
+<p>
+ Download <a
href="../../../libs/signals2/example/extended_slot.cpp"
target="_top">extended_slot.cpp</a>.
+ </p>
+</div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a
name="signals2.examples.document-view"></a>Document-View</h3></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a
href="examples.html#signals2.examples.document-view.doc_view">doc_view</a></span></dt>
+<dt><span class="section"><a
href="examples.html#signals2.examples.document-view.doc_view_acm">doc_view_acm</a></span></dt>
+<dt><span class="section"><a
href="examples.html#signals2.examples.document-view.doc_view_acm_deconstruct">doc_view_acm_deconstruct</a></span></dt>
+</dl></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a
name="signals2.examples.document-view.doc_view"></a>doc_view</h4></div></div></div>
+<p>
+ This is the document-view example program which is described in the
+ <a class="link"
href="tutorial.html#signals2.tutorial.document-view" title="Example:
Document-View">tutorial</a>. It shows
+ usage of a signal and slots to implement two different views of
+ a text document.
+ </p>
+<p>
+ Download <a href="../../../libs/signals2/example/doc_view.cpp"
target="_top">doc_view.cpp</a>.
+ </p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a
name="signals2.examples.document-view.doc_view_acm"></a>doc_view_acm</h4></div></div></div>
+<p>
+ This program modifies the original doc_view.cpp example to employ
+ automatic connection management.
+ </p>
+<p>
+ Download <a href="../../../libs/signals2/example/doc_view_acm.cpp"
target="_top">doc_view_acm.cpp</a>.
+ </p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a
name="signals2.examples.document-view.doc_view_acm_deconstruct"></a>doc_view_acm_deconstruct</h4></div></div></div>
+<p>
+ This program modifies the doc_view_acm.cpp example to use
postconstructors
+ and the <code class="computeroutput"><a class="link"
href="../boost/signals2/deconstruct.html" title="Function
deconstruct">deconstruct()</a></code> factory function.
+ </p>
+<p>
+ Download <a
href="../../../libs/signals2/example/doc_view_acm_deconstruct.cpp"
target="_top">doc_view_acm_deconstruct.cpp</a>.
+ </p>
+</div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="signals2.examples.deconstruct"></a>Postconstructors and
Predestructors with <code class="computeroutput">deconstruct()</code>
+</h3></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a
href="examples.html#signals2.examples.deconstruct.postconstructor_ex1">postconstructor_ex1</a></span></dt>
+<dt><span class="section"><a
href="examples.html#signals2.examples.deconstruct.postconstructor_ex2">postconstructor_ex2</a></span></dt>
+<dt><span class="section"><a
href="examples.html#signals2.examples.deconstruct.predestructor_example">predestructor_example</a></span></dt>
+</dl></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a
name="signals2.examples.deconstruct.postconstructor_ex1"></a>postconstructor_ex1</h4></div></div></div>
+<p>
+ This program is a basic example of how to define a class with a
postconstructor which
+ uses <code class="computeroutput"><a class="link"
href="../boost/signals2/deconstruct.html" title="Function
deconstruct">deconstruct()</a></code> as its factory function.
+ </p>
+<p>
+ Download <a
href="../../../libs/signals2/example/postconstructor_ex1.cpp"
target="_top">postconstructor_ex1</a>.
+ </p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a
name="signals2.examples.deconstruct.postconstructor_ex2"></a>postconstructor_ex2</h4></div></div></div>
+<p>
+ This program extends the postconstructor_ex1 example slightly, by
additionally passing arguments from
+ the <code class="computeroutput"><a class="link"
href="../boost/signals2/deconstruct.html" title="Function
deconstruct">deconstruct()</a></code> call through to the class' constructor
+ and postconstructor.
+ </p>
+<p>
+ Download <a
href="../../../libs/signals2/example/postconstructor_ex2.cpp"
target="_top">postconstructor_ex2</a>.
+ </p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a
name="signals2.examples.deconstruct.predestructor_example"></a>predestructor_example</h4></div></div></div>
+<p>
+ This program is a basic example of how to define a class with a
predestructor which
+ uses <code class="computeroutput"><a class="link"
href="../boost/signals2/deconstruct.html" title="Function
deconstruct">deconstruct()</a></code> as its factory function.
+ </p>
+<p>
+ Download <a
href="../../../libs/signals2/example/predestructor_example.cpp"
target="_top">predestructor_example</a>.
+ </p>
+</div>
+</div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision";
width="100%"><tr>
+<td align="left"><p><small>Last revised: June 12, 2007 at 14:01:23
-0400</small></p></td>
+<td align="right"><div class="copyright-footer">Copyright � 2001-2004
Douglas Gregor<br>Copyright � 2007-2009 Frank Mori Hess<p>Distributed under
the Boost
+ Software License, Version 1.0. (See accompanying file
+ <code class="filename">LICENSE_1_0.txt</code> or copy at <a
href="http://www.boost.org/LICENSE_1_0.txt";
target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)</p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="tutorial.html"><img
src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u"
href="../signals2.html"><img src="../../../doc/html/images/up.png"
alt="Up"></a><a accesskey="h" href="../index.html"><img
src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n"
href="reference.html"><img src="../../../doc/html/images/next.png"
alt="Next"></a>
+</div>
+</body>
+</html>
Added: trunk/doc/html/signals2/faq.html
==============================================================================
--- (empty file)
+++ trunk/doc/html/signals2/faq.html Thu May 7 20:34:38 2009
@@ -0,0 +1,96 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Frequently Asked Questions</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.3">
+<link rel="home" href="../index.html" title="The Boost C++ Libraries
BoostBook Documentation Subset">
+<link rel="up" href="../signals2.html" title="Chapter�17.�Boost.Signals2">
+<link rel="prev" href="thread-safety.html" title="Thread-Safety">
+<link rel="next" href="rationale.html" title="Design Rationale">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084"
alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86"
src="../../../boost.png"></td>
+<td align="center"><a href="../../../index.html">Home</a></td>
+<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
+<td align="center"><a
href="http://www.boost.org/users/people.html";>People</a></td>
+<td align="center"><a
href="http://www.boost.org/users/faq.html";>FAQ</a></td>
+<td align="center"><a href="../../../more/index.htm">More</a></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="thread-safety.html"><img
src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u"
href="../signals2.html"><img src="../../../doc/html/images/up.png"
alt="Up"></a><a accesskey="h" href="../index.html"><img
src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n"
href="rationale.html"><img src="../../../doc/html/images/next.png"
alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="signals2.faq"></a>Frequently Asked
Questions</h2></div></div></div>
+<div class="qandaset">
+<dl>
+<dt>1. <a href="faq.html#id3385844">Don't noncopyable signal semantics
mean that a class
+ with a signal member will be noncopyable as well?</a>
+</dt>
+<dt>2. <a href="faq.html#id3385867">Is Boost.Signals2 thread-safe?</a>
+</dt>
+</dl>
+<table border="0" summary="Q and A Set">
+<col align="left" width="1%">
+<tbody>
+<tr class="question">
+<td align="left" valign="top">
+<a name="id3385844"></a><a name="id3385846"></a><p><b>1.</b></p>
+</td>
+<td align="left" valign="top"><p>Don't noncopyable signal semantics mean
that a class
+ with a signal member will be noncopyable as well?</p></td>
+</tr>
+<tr class="answer">
+<td align="left" valign="top"></td>
+<td align="left" valign="top"><p>No. The compiler will not be able to
generate a copy
+ constructor or copy assignment operator for your class if it
+ has a signal as a member, but you are free to write your own
+ copy constructor and/or copy assignment operator. Just don't
+ try to copy the signal.</p></td>
+</tr>
+<tr class="question">
+<td align="left" valign="top">
+<a name="id3385867"></a><a name="id3385869"></a><p><b>2.</b></p>
+</td>
+<td align="left" valign="top"><p>Is Boost.Signals2 thread-safe?</p></td>
+</tr>
+<tr class="answer">
+<td align="left" valign="top"></td>
+<td align="left" valign="top">
+<p>
+ Yes, as long as the Mutex template parameter is not set to
+ a fake mutex type like <code class="computeroutput"><a
class="link" href="../boost/signals2/dummy_mutex.html" title="Class
dummy_mutex">boost::signals2::dummy_mutex</a></code>.
+ Also, if your slots depend on objects which may be destroyed
concurrently
+ with signal invocation, you will need to use automatic
connection management.
+ That is, the objects will need to be owned by
+ <code class="computeroutput">shared_ptr</code> and passed to the
slot's
+ <code class="computeroutput"><a class="link"
href="../boost/signals2/slotN.html#id1187184-bb">track</a></code>() method
before the slot is connected.
+ The <code class="computeroutput"><a class="link"
href="../boost/signals2/trackable.html" title="Class
trackable">trackable</a></code> scheme of automatic connection management
+ is NOT thread-safe, and is only provided to ease porting of
single-threaded
+ code from Boost.Signals to Boost.Signals2.
+ </p>
+<p>See the documentation section on <a class="link"
href="thread-safety.html" title="Thread-Safety">thread-safety</a>
+ for more information.
+ </p>
+</td>
+</tr>
+</tbody>
+</table>
+</div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision";
width="100%"><tr>
+<td align="left"><p><small>Last revised: June 12, 2007 at 14:01:23
-0400</small></p></td>
+<td align="right"><div class="copyright-footer">Copyright � 2001-2004
Douglas Gregor<br>Copyright � 2007-2009 Frank Mori Hess<p>Distributed under
the Boost
+ Software License, Version 1.0. (See accompanying file
+ <code class="filename">LICENSE_1_0.txt</code> or copy at <a
href="http://www.boost.org/LICENSE_1_0.txt";
target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)</p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="thread-safety.html"><img
src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u"
href="../signals2.html"><img src="../../../doc/html/images/up.png"
alt="Up"></a><a accesskey="h" href="../index.html"><img
src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n"
href="rationale.html"><img src="../../../doc/html/images/next.png"
alt="Next"></a>
+</div>
+</body>
+</html>
Added: trunk/doc/html/signals2/porting.html
==============================================================================
--- (empty file)
+++ trunk/doc/html/signals2/porting.html Thu May 7 20:34:38 2009
@@ -0,0 +1,252 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Porting from Boost.Signals to Boost.Signals2</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.3">
+<link rel="home" href="../index.html" title="The Boost C++ Libraries
BoostBook Documentation Subset">
+<link rel="up" href="../signals2.html" title="Chapter�17.�Boost.Signals2">
+<link rel="prev" href="rationale.html" title="Design Rationale">
+<link rel="next" href="tests.html" title="Testsuite">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084"
alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86"
src="../../../boost.png"></td>
+<td align="center"><a href="../../../index.html">Home</a></td>
+<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
+<td align="center"><a
href="http://www.boost.org/users/people.html";>People</a></td>
+<td align="center"><a
href="http://www.boost.org/users/faq.html";>FAQ</a></td>
+<td align="center"><a href="../../../more/index.htm">More</a></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="rationale.html"><img
src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u"
href="../signals2.html"><img src="../../../doc/html/images/up.png"
alt="Up"></a><a accesskey="h" href="../index.html"><img
src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n"
href="tests.html"><img src="../../../doc/html/images/next.png"
alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="signals2.porting"></a>Porting from Boost.Signals to
Boost.Signals2</h2></div></div></div>
+<p>The changes made to the Boost.Signals2 API compared to the original
Boost.Signals
+ library are summarized below. We also provide some notes on
+ dealing with each change while porting existing Boost.Signals code to
Boost.Signals2.
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+<p>The namespace <code class="computeroutput">boost::signals</code> has
been replaced by <code class="computeroutput">boost::signals2</code>
+ to avoid conflict with the original Boost.Signals implementation,
as well as the Qt "signals" macro.
+ All the Boost.Signals2 classes are inside the <code
class="computeroutput">boost::signals2</code> namespace,
+ unlike the original Boost.Signals which has some classes in the
<code class="computeroutput">boost</code>
+ namespace in addition to its own <code
class="computeroutput">boost::signals</code> namespace.
+ </p>
+<p>
+ The Boost.Signals2 header files are contained in the
+ <code class="computeroutput">boost/signals2/</code> subdirectory
instead of the <code class="computeroutput">boost/signals</code>
+ subdirectory used by the original Boost.Signals. Furthermore, all
the headers except
+ for the convenience header <code
class="computeroutput">boost/signals2.hpp</code> are inside the
+ <code class="computeroutput">boost/signals2/</code> subdirectory,
unlike the original Boost.Signals which
+ keeps a few headers in the parent <code
class="computeroutput">boost/</code> directory
+ in addition to its own <code
class="computeroutput">boost/signals/</code> subdirectory.
+ </p>
+<p>
+ For example, the <code class="computeroutput">signal</code> class
is now
+ in the <code class="computeroutput">boost::signals2</code>
namespace instead of the
+ <code class="computeroutput">boost</code> namespace,
+ and it's header file is now at <code
class="computeroutput">boost/signals2/signal.hpp</code> instead of
+ <code class="computeroutput">boost/signal.hpp</code>.
+ </p>
+<p>
+ While porting, only trivial changes to <code
class="computeroutput">#include</code> directives
+ and namespace qualifications should be required to deal with these
changes.
+ Furthermore, the new namespace and header locations for
Boost.Signals2
+ allow it to coexist in the same program with the original
Boost.Signals library,
+ and porting can be performed piecemeal.
+ </p>
+</li>
+<li>
+<p>
+ Automatic connection management is now achieved through the use of
+ <code class="computeroutput">shared_ptr</code>/<code
class="computeroutput">weak_ptr</code>
+ and <code class="computeroutput"><a class="link"
href="../boost/signals2/slotN.html#id1187184-bb">slot::track</a></code>(),
as described in the
+ <a class="link"
href="tutorial.html#signals2.tutorial.connection-management"
title="Automatic Connection Management (Intermediate)">tutorial</a>.
+ However, the old (thread-unsafe) Boost.Signals scheme of automatic
connection management
+ is still supported via the <code class="computeroutput"><a
class="link" href="../boost/signals2/trackable.html" title="Class
trackable">boost::signals2::trackable</a></code> class.
+ </p>
+<p>
+ If you do not intend to make your program multi-threaded, the
easiest porting path is to simply replace
+ your uses of <code class="computeroutput"><a class="link"
href="../boost/signals/trackable.html" title="Class
trackable">boost::signals::trackable</a></code> as a base class with
+ <code class="computeroutput"><a class="link"
href="../boost/signals2/trackable.html" title="Class
trackable">boost::signals2::trackable</a></code>. Boost.Signals2 uses the
same
+ <code class="computeroutput"><a class="link"
href="../boost/visit_each.html" title="Function template
visit_each">boost::visit_each</a></code> mechanism to discover
+ <code class="computeroutput"><a class="link"
href="../boost/signals2/trackable.html" title="Class
trackable">trackable</a></code> objects
+ as used by the original Boost.Signals library.
+ </p>
+</li>
+<li>
+<p>Support for postconstructors (and predestructors) on objects managed by
<code class="computeroutput">shared_ptr</code>
+ has been added with
+ the <code class="computeroutput"><a class="link"
href="../boost/signals2/deconstruct.html" title="Function
deconstruct">deconstruct</a></code> factory function.
+ This was motivated by the importance of
+ <code class="computeroutput">shared_ptr</code> for the new
connection tracking scheme, and the
+ inability to obtain a <code
class="computeroutput">shared_ptr</code> to an object in its constructor.
+ The use of <code class="computeroutput"><a class="link"
href="../boost/signals2/deconstruct.html" title="Function
deconstruct">deconstruct</a></code> is described in the
+ <a class="link" href="tutorial.html#signals2.tutorial.deconstruct"
title="Postconstructors and Predestructors (Advanced)">tutorial</a>.
+ </p>
+<p>
+ The use of <code class="computeroutput"><a class="link"
href="../boost/signals2/deconstruct.html" title="Function
deconstruct">deconstruct</a></code> is in no way required,
+ it is only provided in the hope
+ it may be useful. You may wish to use it if you are porting code
where
+ a class creates connections to its own member functions in its
constructor,
+ and you also
+ wish to use the new automatic connection management scheme. You
could then
+ move the connection creation from the constructor to to the an
+ <code class="computeroutput">adl_postconstruct</code> function,
where
+ a reference to the owning <code
class="computeroutput">shared_ptr</code> is available for
+ passing to <code class="computeroutput"><a class="link"
href="../boost/signals2/slotN.html#id1187184-bb">slot::track</a></code>.
+ The <code class="computeroutput"><a class="link"
href="../boost/signals2/deconstruct.html" title="Function
deconstruct">deconstruct</a></code> function would be used create objects
+ of the class and run their associated <code
class="computeroutput">adl_postconstruct</code> function.
+ You can enforce use of <code class="computeroutput"><a
class="link" href="../boost/signals2/deconstruct.html" title="Function
deconstruct">deconstruct</a></code> by
+ making the class' constructors private and declaring
+ <code class="computeroutput"><a class="link"
href="../boost/signals2/deconstruct_access.html" title="Class
deconstruct_access">deconstruct_access</a></code> a friend.
+ </p>
+</li>
+<li>
+<p>
+ The <code class="computeroutput"><a class="link"
href="../boost/slot.html" title="Class template slot">slot</a></code> class
takes a new <code class="computeroutput">Signature</code> template
parameter,
+ is useable as a function object, and has some additional features
to support the
+ new Boost.Signals2 automatic connection management scheme.
+ </p>
+<p>
+ The changes to the slot class should generally not cause any
porting difficulties,
+ especially if you are using the <code class="computeroutput"><a
class="link" href="../boost/signals2/trackable.html" title="Class
trackable">boost::signals2::trackable</a></code>
+ compatibility class mentioned above. If you are converting your
code over to
+ use the new automatic connection management scheme, you will need
to
+ employ some of the new slot features, as described in the
+ <a class="link"
href="tutorial.html#signals2.tutorial.connection-management"
title="Automatic Connection Management (Intermediate)">tutorial</a>.
+ </p>
+</li>
+<li>
+<p>
+ The <code class="computeroutput"><a class="link"
href="../boost/signals2/optional_last_value.html" title="Class template
optional_last_value">optional_last_value</a></code> class has replaced
<code class="computeroutput"><a class="link"
href="../boost/last_value.html" title="Class template
last_value">last_value</a></code>
+ as the default combiner for signals.
+ </p>
+<p>
+ The <code class="computeroutput"><a class="link"
href="../boost/last_value.html" title="Class template
last_value">last_value</a></code> combiner is still provided, although its
+ behavior is slightly changed in that it
+ throws an exception when no slots are connected on signal
invocation, instead of
+ always requiring at least one slot to be connected (except for its
void specialization
+ which never required any slots to be connected).
+ </p>
+<p>
+ If you are porting signals which have a <code
class="computeroutput">void</code> return type in their signature
+ and they use the default combiner, there are no changes required.
If you are
+ using the default combiner with a non-void return type and care
about the
+ value returned from signal invocation, you will have to take into
account that
+ <code class="computeroutput"><a class="link"
href="../boost/signals2/optional_last_value.html" title="Class template
optional_last_value">optional_last_value</a></code> returns a
+ <code class="computeroutput">boost::optional</code> instead of a
plain value. One simple
+ way to deal with this is to use <code
class="computeroutput">boost::optional::operator*()</code> to access the
+ value wrapped inside the returned <code
class="computeroutput">boost::optional</code>.
+ </p>
+<p>
+ Alternatively, you could do a port by specifying the <code
class="computeroutput">Combiner</code> template parameter
+ for your <code class="computeroutput">signals2::signal</code> to
be <code class="computeroutput"><a class="link"
href="../boost/last_value.html" title="Class template
last_value">last_value</a></code>.
+ </p>
+</li>
+<li>
+<p>
+ The <code class="computeroutput"><a class="link"
href="../boost/signal.html" title="Class template signal">signal</a></code>
class has an additional typedef
+ <code class="computeroutput"><a class="link"
href="../boost/signals2/signalN.html#boost.signals2.signalN.extended_slot_type">signal::extended_slot_type</a></code>
+ and new <code class="computeroutput"><a class="link"
href="../boost/signals2/signalN.html#id1208227-bb">signal::connect_extended</a></code>()
+ methods. These allow connection of slots
+ which take an additional <code class="computeroutput"><a
class="link" href="../boost/signals2/connection.html" title="Class
connection">connection</a></code> argument, giving them thread-safe
+ access to their signal/slot connection when they are invoked.
There is also a
+ new <code class="computeroutput">ExtendedSlotFunction</code>
template parameter for specifying the underlying slot function
+ type for the new extended slots.
+ </p>
+<p>
+ These additions should have no effect on porting unless you are
also converting
+ your program from a single threaded program into a multi-threaded
one. In that case,
+ if you have slots which need access to their <code
class="computeroutput"><a class="link"
href="../boost/signals2/connection.html" title="Class
connection">connection</a></code>
+ to the signal invoking them (for example to block or disconnect
their connection)
+ you may wish to connect the slots with
+ <code class="computeroutput"><a class="link"
href="../boost/signals2/signalN.html#id1208227-bb">signal::connect_extended</a></code>().
+ This also requires adding an additional connection argument to the
slot.
+ More information on how and why to use extended slots is available
+ in the <a class="link"
href="tutorial.html#signals2.tutorial.extended-slot-type" title="Giving a
Slot Access to its Connection (Advanced)">tutorial</a>.
+ </p>
+</li>
+<li>
+<p>
+ The <code class="computeroutput"><a class="link"
href="../boost/signal.html" title="Class template signal">signal</a></code>
class has a new <code class="computeroutput">Mutex</code> template
parameter for specifying
+ the mutex type used internally by the signal and its connections.
+ </p>
+<p>
+ The <code class="computeroutput">Mutex</code> template parameter
can be left to its default value of
+ <code class="computeroutput"><a class="link"
href="../boost/signals2/mutex.html" title="Class
mutex">boost::signals2::mutex</a></code> and should have little effect on
porting.
+ However, if you have a single-threaded program and are
+ concerned about incuring a performance overhead from unneeded
mutex locking, you may
+ wish to use a different mutex for your signals such as <code
class="computeroutput"><a class="link"
href="../boost/signals2/dummy_mutex.html" title="Class
dummy_mutex">dummy_mutex</a></code>.
+ See the <a class="link"
href="tutorial.html#signals2.tutorial.signal-mutex-template-parameter"
title="Changing the Mutex Type of a Signal (Advanced).">tutorial</a>
+ for more information on the <code
class="computeroutput">Mutex</code> parameter.
+ </p>
+</li>
+<li>
+<p>The <code class="computeroutput">signal::combiner()</code> method,
which formerly returned a reference to the
+ signal's combiner has been replaced by <code
class="computeroutput"><a class="link"
href="../boost/signalN.html#id1242709-bb">signal::combiner</a></code>
+ (which now returns the combiner by value) and <code
class="computeroutput"><a class="link"
href="../boost/signals2/signalN.html#id2375152-bb">signal::set_combiner</a></code>.
+ </p>
+<p>
+ During porting it should be straightforward to replace uses of the
old reference-returning
+ <code class="computeroutput">signal::combiner()</code>
+ function with the new "by-value" <code class="computeroutput"><a
class="link"
href="../boost/signalN.html#id1242709-bb">signal::combiner</a></code>
+ and <code class="computeroutput"><a class="link"
href="../boost/signals2/signalN.html#id2375152-bb">signal::set_combiner</a></code>
functions.
+ However, you will need to inspect each call of the <code
class="computeroutput">combiner</code> method in your code
+ to determine if your program logic has been broken by the changed
+ return type.
+ </p>
+</li>
+<li>
+<p>Connections no longer have <code class="computeroutput">block()</code>
and <code class="computeroutput">unblock()</code> methods. Blocking
+ of connections is now accomplished by creating <code
class="computeroutput"><a class="link"
href="../boost/signals2/shared_connection_block.html" title="Class
shared_connection_block">shared_connection_block</a></code> objects,
+ which provide RAII-style blocking.
+ </p>
+<p>
+ If you have existing Boost.Signals code that blocks, for example:
+ </p>
+<pre class="programlisting">
+namespace bs = boost::signals;
+
+bs::connection my_connection;
+//...
+
+my_connection.block();
+do_something();
+my_connection.unblock();
+</pre>
+<p>
+ then the version ported to Boost.Signals2 would look like:
+ </p>
+<pre class="programlisting">
+namespace bs2 = boost::signals2;
+
+bs2::connection my_connection;
+//...
+
+{
+ bs2::shared_connection_block blocker(my_connection);
+ do_something();
+} // blocker goes out of scope here and releases its block on my_connection
+</pre>
+</li>
+</ul></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision";
width="100%"><tr>
+<td align="left"><p><small>Last revised: June 12, 2007 at 14:01:23
-0400</small></p></td>
+<td align="right"><div class="copyright-footer">Copyright � 2001-2004
Douglas Gregor<br>Copyright � 2007-2009 Frank Mori Hess<p>Distributed under
the Boost
+ Software License, Version 1.0. (See accompanying file
+ <code class="filename">LICENSE_1_0.txt</code> or copy at <a
href="http://www.boost.org/LICENSE_1_0.txt";
target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)</p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="rationale.html"><img
src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u"
href="../signals2.html"><img src="../../../doc/html/images/up.png"
alt="Up"></a><a accesskey="h" href="../index.html"><img
src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n"
href="tests.html"><img src="../../../doc/html/images/next.png"
alt="Next"></a>
+</div>
+</body>
+</html>
Added: trunk/doc/html/signals2/rationale.html
==============================================================================
--- (empty file)
+++ trunk/doc/html/signals2/rationale.html Thu May 7 20:34:38 2009
@@ -0,0 +1,401 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Design Rationale</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.3">
+<link rel="home" href="../index.html" title="The Boost C++ Libraries
BoostBook Documentation Subset">
+<link rel="up" href="../signals2.html" title="Chapter�17.�Boost.Signals2">
+<link rel="prev" href="faq.html" title="Frequently Asked Questions">
+<link rel="next" href="porting.html" title="Porting from Boost.Signals to
Boost.Signals2">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084"
alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86"
src="../../../boost.png"></td>
+<td align="center"><a href="../../../index.html">Home</a></td>
+<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
+<td align="center"><a
href="http://www.boost.org/users/people.html";>People</a></td>
+<td align="center"><a
href="http://www.boost.org/users/faq.html";>FAQ</a></td>
+<td align="center"><a href="../../../more/index.htm">More</a></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="faq.html"><img
src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u"
href="../signals2.html"><img src="../../../doc/html/images/up.png"
alt="Up"></a><a accesskey="h" href="../index.html"><img
src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n"
href="porting.html"><img src="../../../doc/html/images/next.png"
alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="signals2.rationale"></a>Design Rationale</h2></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="rationale.html#id3385960">User-level
Connection Management</a></span></dt>
+<dt><span class="section"><a href="rationale.html#id3386133">Automatic
Connection Management</a></span></dt>
+<dt><span class="section"><a
href="rationale.html#id3386287">optional_last_value as the Default
Combiner</a></span></dt>
+<dt><span class="section"><a href="rationale.html#id3386348">Combiner
Interface</a></span></dt>
+<dt><span class="section"><a href="rationale.html#id3386428">Connection
Interfaces: += operator</a></span></dt>
+<dt><span class="section"><a href="rationale.html#id3386600">Signals2
Mutex Classes</a></span></dt>
+<dt><span class="section"><a href="rationale.html#id3386712">Comparison
with other Signal/Slot implementations</a></span></dt>
+</dl></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id3385960"></a>User-level Connection
Management</h3></div></div></div>
+<p> Users need to have fine control over the connection of
+ signals to slots and their eventual disconnection. The primary approach
+ taken by Boost.Signals2 is to return a
+ <code class="computeroutput"><a class="link"
href="../boost/signals2/connection.html" title="Class
connection">connection</a></code> object that enables
+ connected/disconnected query, manual disconnection, and an
+ automatic disconnection on destruction mode (<code
class="computeroutput"><a class="link"
href="../boost/signals2/scoped_connection.html" title="Class
scoped_connection">scoped_connection</a></code>).
+ In addition, two other interfaces are supported by the
+ <code class="computeroutput"><a class="link"
href="../boost/signalN.html#id1242363-bb">signal::disconnect</a></code>
overloaded method:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p><span class="bold"><strong>Pass slot to
+ disconnect</strong></span>: in this interface model, the
+ disconnection of a slot connected with
+ <code class="computeroutput">sig.<a class="link"
href="../boost/signals2/signalN.html#id1284885-bb">connect</a>(typeof(sig)::slot_type(slot_func))</code>
is
+ performed via
+ <code class="computeroutput">sig.<a class="link"
href="../boost/signals2/signalN.html#id1280164-bb">disconnect</a>(slot_func)</code>.
Internally,
+ a linear search using slot comparison is performed and the
+ slot, if found, is removed from the list. Unfortunately,
+ querying connectedness ends up as a
+ linear-time operation.</p></li>
+<li>
+<p><span class="bold"><strong>Pass a token to
+ disconnect</strong></span>: this approach identifies slots with a
+ token that is easily comparable (e.g., a string), enabling
+ slots to be arbitrary function objects. While this approach is
+ essentially equivalent to the connection approach taken by
Boost.Signals2,
+ it is possibly more error-prone for several reasons:</p>
+<div class="itemizedlist"><ul type="circle">
+<li><p>Connections and disconnections must be paired, so
+ the problem becomes similar to the problems incurred when
+ pairing <code class="computeroutput">new</code> and <code
class="computeroutput">delete</code> for
+ dynamic memory allocation. While errors of this sort would
+ not be catastrophic for a signals and slots
+ implementation, their detection is generally
+ nontrivial.</p></li>
+<li><p>If tokens are not unique, two slots may have
+ the same name and be indistinguishable. In
+ environments where many connections will be made
+ dynamically, name generation becomes an additional task
+ for the user.</p></li>
+</ul></div>
+<p> This type of interface is supported in Boost.Signals2
+ via the slot grouping mechanism, and the overload of
+ <code class="computeroutput"><a class="link"
href="../boost/signalN.html#id1242363-bb">signal::disconnect</a></code>
+ which takes an argument of the signal's <code
class="computeroutput">Group</code> type.</p>
+</li>
+</ul></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id3386133"></a>Automatic Connection
Management</h3></div></div></div>
+<p>Automatic connection management in Signals2
+ depends on the use of <code
class="computeroutput">boost::shared_ptr</code> to
+ manage the lifetimes of tracked objects. This is differs from
+ the original Boost.Signals library, which instead relied on
derivation
+ from the <code class="computeroutput"><a class="link"
href="../boost/signals/trackable.html" title="Class
trackable">boost::signals::trackable</a></code> class.
+ The library would be
+ notified of an object's destruction by the
+ <code class="computeroutput"><a class="link"
href="../boost/signals/trackable.html" title="Class
trackable">boost::signals::trackable</a></code> destructor.
+ </p>
+<p>Unfortunately, the <code class="computeroutput"><a class="link"
href="../boost/signals/trackable.html" title="Class
trackable">boost::signals::trackable</a></code>
+ scheme cannot be made thread safe due
+ to destructor ordering. The destructor of an class derived from
+ <code class="computeroutput"><a class="link"
href="../boost/signals/trackable.html" title="Class
trackable">boost::signals::trackable</a></code> will always be
+ called before the destructor of the base <code
class="computeroutput"><a class="link"
href="../boost/signals/trackable.html" title="Class
trackable">boost::signals::trackable</a></code>
+ class. However, for thread-safety the connection between the signal
and object
+ needs to be disconnected before the object runs its destructors.
+ Otherwise, if an object being destroyed
+ in one thread is connected to a signal concurrently
+ invoking in another thread, the signal may call into
+ a partially destroyed object.
+ </p>
+<p>We solve this problem by requiring that tracked objects be
+ managed by <code class="computeroutput">shared_ptr</code>. Slots
keep a
+ <code class="computeroutput">weak_ptr</code> to every object the
slot depends
+ on. Connections to a slot are disconnected when any of its tracked
+ <code class="computeroutput">weak_ptr</code>s expire. Additionally,
signals
+ create their own temporary <code
class="computeroutput">shared_ptr</code>s to
+ all of a slot's tracked objects prior to invoking the slot. This
+ insures none of the tracked objects destruct in mid-invocation.
+ </p>
+<p>The new connection management scheme has the advantage of being
+ non-intrusive. Objects of any type may be tracked using the
+ <code class="computeroutput">shared_ptr/weak_ptr</code> scheme. The
old
+ <code class="computeroutput"><a class="link"
href="../boost/signals/trackable.html" title="Class
trackable">boost::signals::trackable</a></code>
+ scheme requires the tracked objects to be derived from the <code
class="computeroutput">trackable</code>
+ base class, which is not always practical when interacting
+ with classes from 3rd party libraries.
+ </p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id3386287"></a><code
class="computeroutput">optional_last_value</code> as the Default
Combiner</h3></div></div></div>
+<p>
+ The default combiner for Boost.Signals2 has changed from the <code
class="computeroutput">last_value</code>
+ combiner used by default in the original Boost.Signals library.
+ This is because <code class="computeroutput">last_value</code>
requires that at least 1 slot be
+ connected to the signal when it is invoked (except for the <code
class="computeroutput">last_value<void></code> specialization).
+ In a multi-threaded environment where signal invocations and slot
connections
+ and disconnections may be happening concurrently, it is difficult
+ to fulfill this requirement. When using <code
class="computeroutput"><a class="link"
href="../boost/signals2/optional_last_value.html" title="Class template
optional_last_value">optional_last_value</a></code>,
+ there is no requirement for slots to be connected when a signal
+ is invoked, since in that case the combiner may simply return an
empty
+ <code class="computeroutput">boost::optional</code>.
+ </p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id3386348"></a>Combiner Interface</h3></div></div></div>
+<p> The Combiner interface was chosen to mimic a call to an
+ algorithm in the C++ standard library. It is felt that by viewing
+ slot call results as merely a sequence of values accessed by input
+ iterators, the combiner interface would be most natural to a
+ proficient C++ programmer. Competing interface design generally
+ required the combiners to be constructed to conform to an
+ interface that would be customized for (and limited to) the
+ Signals2 library. While these interfaces are generally enable more
+ straighforward implementation of the signals & slots
+ libraries, the combiners are unfortunately not reusable (either in
+ other signals & slots libraries or within other generic
+ algorithms), and the learning curve is steepened slightly to learn
+ the specific combiner interface.</p>
+<p> The Signals2 formulation of combiners is based on the
+ combiner using the "pull" mode of communication, instead of the
+ more complex "push" mechanism. With a "pull" mechanism, the
+ combiner's state can be kept on the stack and in the program
+ counter, because whenever new data is required (i.e., calling the
+ next slot to retrieve its return value), there is a simple
+ interface to retrieve that data immediately and without returning
+ from the combiner's code. Contrast this with the "push" mechanism,
+ where the combiner must keep all state in class members because
+ the combiner's routines will be invoked for each signal
+ called. Compare, for example, a combiner that returns the maximum
+ element from calling the slots. If the maximum element ever
+ exceeds 100, no more slots are to be called.</p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th align="left"><p>Pull</p></th>
+<th align="left"><p>Push</p></th>
+</tr></thead>
+<tbody><tr>
+<td align="left">
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision";
class="table-programlisting">
+struct pull_max {
+ typedef int result_type;
+
+ template<typename InputIterator>
+ result_type operator()(InputIterator first,
+ InputIterator last)
+ {
+ if (first == last)
+ throw std::runtime_error("Empty!");
+
+ int max_value = *first++;
+ while(first != last && *first <= 100) {
+ if (*first > max_value)
+ max_value = *first;
+ ++first;
+ }
+
+ return max_value;
+ }
+};
+</pre>
+</td>
+<td align="left">
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision";
class="table-programlisting">
+struct push_max {
+ typedef int result_type;
+
+ push_max() : max_value(), got_first(false) {}
+
+ // returns false when we want to stop
+ bool operator()(int result) {
+ if (result > 100)
+ return false;
+
+ if (!got_first) {
+ got_first = true;
+ max_value = result;
+ return true;
+ }
+
+ if (result > max_value)
+ max_value = result;
+
+ return true;
+ }
+
+ int get_value() const
+ {
+ if (!got_first)
+ throw std::runtime_error("Empty!");
+ return max_value;
+ }
+
+private:
+ int max_value;
+ bool got_first;
+};
+</pre>
+</td>
+</tr></tbody>
+</table></div>
+<p>There are several points to note in these examples. The
+ "pull" version is a reusable function object that is based on an
+ input iterator sequence with an integer <code
class="computeroutput">value_type</code>,
+ and is very straightforward in design. The "push" model, on the
+ other hand, relies on an interface specific to the caller and is
+ not generally reusable. It also requires extra state values to
+ determine, for instance, if any elements have been
+ received. Though code quality and ease-of-use is generally
+ subjective, the "pull" model is clearly shorter and more reusable
+ and will often be construed as easier to write and understand,
+ even outside the context of a signals & slots library.</p>
+<p> The cost of the "pull" combiner interface is paid in the
+ implementation of the Signals2 library itself. To correctly handle
+ slot disconnections during calls (e.g., when the dereference
+ operator is invoked), one must construct the iterator to skip over
+ disconnected slots. Additionally, the iterator must carry with it
+ the set of arguments to pass to each slot (although a reference to
+ a structure containing those arguments suffices), and must cache
+ the result of calling the slot so that multiple dereferences don't
+ result in multiple calls. This apparently requires a large degree
+ of overhead, though if one considers the entire process of
+ invoking slots one sees that the overhead is nearly equivalent to
+ that in the "push" model, but we have inverted the control
+ structures to make iteration and dereference complex (instead of
+ making combiner state-finding complex).</p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id3386428"></a>Connection Interfaces: +=
operator</h3></div></div></div>
+<p> Boost.Signals2 supports a connection syntax with the form
+ <code class="computeroutput">sig.<a class="link"
href="../boost/signals2/signalN.html#id1284885-bb">connect</a>(slot)</code>,
but a
+ more terse syntax <code class="computeroutput">sig += slot</code> has
been suggested (and
+ has been used by other signals & slots implementations). There
+ are several reasons as to why this syntax has been
+ rejected:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p><span class="bold"><strong>It's unnecessary</strong></span>: the
+ connection syntax supplied by Boost.Signals2 is no less
+ powerful that that supplied by the <code
class="computeroutput">+=</code>
+ operator. The savings in typing (<code
class="computeroutput">connect()</code>
+ vs. <code class="computeroutput">+=</code>) is essentially
negligible. Furthermore,
+ one could argue that calling <code
class="computeroutput">connect()</code> is more
+ readable than an overload of <code
class="computeroutput">+=</code>.</p></li>
+<li><p><span class="bold"><strong>Ambiguous return type</strong></span>:
+ there is an ambiguity concerning the return value of the
+ <code class="computeroutput">+=</code> operation: should it be a
reference to the
+ signal itself, to enable <code class="computeroutput">sig += slot1
+= slot2</code>,
+ or should it return a
+ <code class="computeroutput"><a class="link"
href="../boost/signals2/connection.html" title="Class
connection">connection</a></code> for the
+ newly-created signal/slot connection?</p></li>
+<li>
+<p><span class="bold"><strong>Gateway to operators -=,
+ +</strong></span>: when one has added a connection operator
+ <code class="computeroutput">+=</code>, it seems natural to have a
disconnection
+ operator <code class="computeroutput">-=</code>. However, this
presents problems when
+ the library allows arbitrary function objects to implicitly
+ become slots, because slots are no longer comparable. </p>
+<p> The second obvious addition when one has
+ <code class="computeroutput">operator+=</code> would be to add a
<code class="computeroutput">+</code>
+ operator that supports addition of multiple slots, followed by
+ assignment to a signal. However, this would require
+ implementing <code class="computeroutput">+</code> such that it
can accept any two
+ function objects, which is technically infeasible.</p>
+</li>
+</ul></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id3386600"></a>Signals2 Mutex Classes</h3></div></div></div>
+<p>
+ The Boost.Signals2 library provides 2 mutex classes: <code
class="computeroutput"><a class="link" href="../boost/signals2/mutex.html"
title="Class mutex">boost::signals2::mutex</a></code>,
+ and <code class="computeroutput"><a class="link"
href="../boost/signals2/dummy_mutex.html" title="Class
dummy_mutex">boost::signals2::dummy_mutex</a></code>. The motivation for
providing
+ <code class="computeroutput"><a class="link"
href="../boost/signals2/mutex.html" title="Class
mutex">boost::signals2::mutex</a></code> is simply that the <code
class="computeroutput">boost::mutex</code>
+ class provided by the Boost.Thread library currently requires
linking to libboost_thread.
+ The <code class="computeroutput"><a class="link"
href="../boost/signals2/mutex.html" title="Class
mutex">boost::signals2::mutex</a></code> class allows Signals2 to remain
+ a header-only library. In the future, <code
class="computeroutput"><a class="link" href="../boost/signals2/mutex.html"
title="Class mutex">boost::signals2::mutex</a></code>
+ will probably be turned into a typedef to <code
class="computeroutput">std::mutex</code> when
+ compiling in C++0x mode. You may still choose to use <code
class="computeroutput">boost::mutex</code>
+ if you wish, by specifying it as the <code
class="computeroutput">Mutex</code> template type for your signals.
+ </p>
+<p>
+ The <code class="computeroutput"><a class="link"
href="../boost/signals2/dummy_mutex.html" title="Class
dummy_mutex">boost::signals2::dummy_mutex</a></code> class is provided to
allow
+ performance sensitive single-threaded applications to minimize
overhead by avoiding unneeded
+ mutex locking.
+ </p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id3386712"></a>Comparison with other Signal/Slot
implementations</h3></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a
href="rationale.html#id3386718">libsigc++</a></span></dt>
+<dt><span class="section"><a href="rationale.html#id3386790">.NET
delegates</a></span></dt>
+</dl></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="id3386718"></a>libsigc++</h4></div></div></div>
+<p> <a href="http://libsigc.sourceforge.net"; target="_top">libsigc++</a>
is a C++
+ signals & slots library that originally started as part of
+ an initiative to wrap the C interfaces to <a
href="http://www.gtk.org"; target="_top">GTK</a> libraries in C++, and has
+ grown to be a separate library maintained by Karl Nelson. There
+ are many similarities between libsigc++ and Boost.Signals2, and
+ indeed the original Boost.Signals was strongly influenced by
+ Karl Nelson and libsigc++. A cursory inspection of each library will
find a
+ similar syntax for the construction of signals and in the use of
+ connections. There
+ are some major differences in design that separate these
+ libraries:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p><span class="bold"><strong>Slot definitions</strong></span>:
+ slots in libsigc++ are created using a set of primitives
+ defined by the library. These primitives allow binding of
+ objects (as part of the library), explicit adaptation from
+ the argument and return types of the signal to the argument
+ and return types of the slot (libsigc++ is, by default, more
+ strict about types than Boost.Signals2).</p></li>
+<li><p><span class="bold"><strong>Combiner/Marshaller
+ interface</strong></span>: the equivalent to Boost.Signals2
+ combiners in libsigc++ are the marshallers. Marshallers are
+ similar to the "push" interface described in Combiner
+ Interface, and a proper treatment of the topic is given
+ there.</p></li>
+</ul></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="id3386790"></a>.NET delegates</h4></div></div></div>
+<p> <a href="http://www.microsoft.com"; target="_top">Microsoft</a>
+ has introduced the .NET Framework and an associated set of
+ languages and language extensions, one of which is the
+ delegate. Delegates are similar to signals and slots, but they
+ are more limited than most C++ signals and slots implementations
+ in that they:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p>Require exact type matches between a delegate and what
+ it is calling.</p></li>
+<li><p>Only return the result of the last target called, with no option
for customization.</p></li>
+<li><p>Must call a method with <code class="computeroutput">this</code>
already
+ bound.</p></li>
+</ul></div>
+</div>
+</div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision";
width="100%"><tr>
+<td align="left"><p><small>Last revised: June 12, 2007 at 14:01:23
-0400</small></p></td>
+<td align="right"><div class="copyright-footer">Copyright � 2001-2004
Douglas Gregor<br>Copyright � 2007-2009 Frank Mori Hess<p>Distributed under
the Boost
+ Software License, Version 1.0. (See accompanying file
+ <code class="filename">LICENSE_1_0.txt</code> or copy at <a
href="http://www.boost.org/LICENSE_1_0.txt";
target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)</p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="faq.html"><img
src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u"
href="../signals2.html"><img src="../../../doc/html/images/up.png"
alt="Up"></a><a accesskey="h" href="../index.html"><img
src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n"
href="porting.html"><img src="../../../doc/html/images/next.png"
alt="Next"></a>
+</div>
+</body>
+</html>
Added: trunk/doc/html/signals2/reference.html
==============================================================================
--- (empty file)
+++ trunk/doc/html/signals2/reference.html Thu May 7 20:34:38 2009
@@ -0,0 +1,234 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Reference</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.3">
+<link rel="home" href="../index.html" title="The Boost C++ Libraries
BoostBook Documentation Subset">
+<link rel="up" href="../signals2.html" title="Chapter�17.�Boost.Signals2">
+<link rel="prev" href="examples.html" title="Example programs">
+<link rel="next" href="../boost/signals2/connection.html" title="Class
connection">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084"
alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86"
src="../../../boost.png"></td>
+<td align="center"><a href="../../../index.html">Home</a></td>
+<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
+<td align="center"><a
href="http://www.boost.org/users/people.html";>People</a></td>
+<td align="center"><a
href="http://www.boost.org/users/faq.html";>FAQ</a></td>
+<td align="center"><a href="../../../more/index.htm">More</a></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="examples.html"><img
src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u"
href="../signals2.html"><img src="../../../doc/html/images/up.png"
alt="Up"></a><a accesskey="h" href="../index.html"><img
src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n"
href="../boost/signals2/connection.html"><img
src="../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="signals2.reference"></a>Reference</h2></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a
href="reference.html#header.boost.signals2_hpp">Header
<boost/signals2.hpp></a></span></dt>
+<dt><span class="section"><a
href="reference.html#header.boost.signals2.connection_hpp">Header
<boost/signals2/connection.hpp></a></span></dt>
+<dt><span class="section"><a
href="reference.html#header.boost.signals2.deconstruct_hpp">Header
<boost/signals2/deconstruct.hpp></a></span></dt>
+<dt><span class="section"><a
href="reference.html#header.boost.signals2.dummy_mutex_hpp">Header
<boost/signals2/dummy_mutex.hpp></a></span></dt>
+<dt><span class="section"><a
href="reference.html#header.boost.signals2.last_value_hpp">Header
<boost/signals2/last_value.hpp></a></span></dt>
+<dt><span class="section"><a
href="reference.html#header.boost.signals2.mutex_hpp">Header
<boost/signals2/mutex.hpp></a></span></dt>
+<dt><span class="section"><a
href="reference.html#header.boost.signals2.optional_last_value_hpp">Header
<boost/signals2/optional_last_value.hpp></a></span></dt>
+<dt><span class="section"><a
href="reference.html#header.boost.signals2.shared_connection_block_hpp">Header
<boost/signals2/shared_connection_block.hpp></a></span></dt>
+<dt><span class="section"><a
href="reference.html#header.boost.signals2.signal_hpp">Header
<boost/signals2/signal.hpp></a></span></dt>
+<dt><span class="section"><a
href="reference.html#header.boost.signals2.signal_base_hpp">Header
<boost/signals2/signal_base.hpp></a></span></dt>
+<dt><span class="section"><a
href="reference.html#header.boost.signals2.signal_type_hpp">Header
<boost/signals2/signal_type.hpp></a></span></dt>
+<dt><span class="section"><a
href="reference.html#header.boost.signals2.slot_hpp">Header
<boost/signals2/slot.hpp></a></span></dt>
+<dt><span class="section"><a
href="reference.html#header.boost.signals2.slot_base_hpp">Header
<boost/signals2/slot_base.hpp></a></span></dt>
+<dt><span class="section"><a
href="reference.html#header.boost.signals2.trackable_hpp">Header
<boost/signals2/trackable.hpp></a></span></dt>
+</dl></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="header.boost.signals2_hpp"></a>Header <<a
href="../../../boost/signals2.hpp"
target="_top">boost/signals2.hpp</a>></h3></div></div></div>
+<p>
+ Including the "boost/signals2.hpp" header pulls in all the other
headers of the Signals2
+ library. It is provided as a convenience.
+ </p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="header.boost.signals2.connection_hpp"></a>Header <<a
href="../../../boost/signals2/connection.hpp"
target="_top">boost/signals2/connection.hpp</a>></h3></div></div></div>
+<pre class="synopsis"><span class="bold"><strong>namespace</strong></span>
boost {
+ <span class="bold"><strong>namespace</strong></span> signals2 {
+ <span class="bold"><strong>class</strong></span> <a class="link"
href="../boost/signals2/connection.html" title="Class
connection">connection</a>;
+ <span class="type"><span
class="bold"><strong>void</strong></span></span> <a class="link"
href="../boost/signals2/connection.html#boost.signals2.swap_id1223150">swap</a>(<a
class="link" href="../boost/signals2/connection.html" title="Class
connection">connection</a>&, <a class="link"
href="../boost/signals2/connection.html" title="Class
connection">connection</a>&);
+ <span class="bold"><strong>class</strong></span> <a class="link"
href="../boost/signals2/scoped_connection.html" title="Class
scoped_connection">scoped_connection</a>;
+ }
+}</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="header.boost.signals2.deconstruct_hpp"></a>Header <<a
href="../../../boost/signals2/deconstruct.hpp"
target="_top">boost/signals2/deconstruct.hpp</a>></h3></div></div></div>
+<pre class="synopsis"><span class="bold"><strong>namespace</strong></span>
boost {
+ <span class="bold"><strong>namespace</strong></span> signals2 {
+ <span class="bold"><strong>class</strong></span> <a class="link"
href="../boost/signals2/deconstruct_access.html" title="Class
deconstruct_access">deconstruct_access</a>;
+ <span class="bold"><strong>class</strong></span> <a class="link"
href="../boost/signals2/postconstructor_invoker.html" title="Class
postconstructor_invoker">postconstructor_invoker</a>;
+ <span class="bold"><strong>template</strong></span><<span
class="bold"><strong>typename</strong></span> T> <span class="type"><a
class="link" href="../boost/signals2/postconstructor_invoker.html"
title="Class
postconstructor_invoker">postconstructor_invoker</a><T></span> <a
class="link" href="../boost/signals2/deconstruct.html" title="Function
deconstruct">deconstruct</a>();
+ <span class="bold"><strong>template</strong></span><<span
class="bold"><strong>typename</strong></span> T, <span
class="bold"><strong>typename</strong></span> A1>
+ <span class="type"><a class="link"
href="../boost/signals2/postconstructor_invoker.html" title="Class
postconstructor_invoker">postconstructor_invoker</a><T></span> <a
class="link" href="../boost/signals2/deconstruct.html" title="Function
deconstruct">deconstruct</a>(<span
class="bold"><strong>const</strong></span> A1 &);
+ <span class="bold"><strong>template</strong></span><<span
class="bold"><strong>typename</strong></span> T, <span
class="bold"><strong>typename</strong></span> A1, <span
class="bold"><strong>typename</strong></span> A2>
+ <span class="type"><a class="link"
href="../boost/signals2/postconstructor_invoker.html" title="Class
postconstructor_invoker">postconstructor_invoker</a><T></span> <a
class="link" href="../boost/signals2/deconstruct.html" title="Function
deconstruct">deconstruct</a>(<span
class="bold"><strong>const</strong></span> A1 &, <span
class="bold"><strong>const</strong></span> A2 &);
+ <span class="bold"><strong>template</strong></span><<span
class="bold"><strong>typename</strong></span> T, <span
class="bold"><strong>typename</strong></span> A1, <span
class="bold"><strong>typename</strong></span> A2, ..., <span
class="bold"><strong>typename</strong></span> AN>
+ <span class="type"><a class="link"
href="../boost/signals2/postconstructor_invoker.html" title="Class
postconstructor_invoker">postconstructor_invoker</a><T></span>
+ <a class="link" href="../boost/signals2/deconstruct.html"
title="Function deconstruct">deconstruct</a>(<span
class="bold"><strong>const</strong></span> A1 &, <span
class="bold"><strong>const</strong></span> A2 &, ..., <span
class="bold"><strong>const</strong></span> AN &);
+ }
+}</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="header.boost.signals2.dummy_mutex_hpp"></a>Header <<a
href="../../../boost/signals2/dummy_mutex.hpp"
target="_top">boost/signals2/dummy_mutex.hpp</a>></h3></div></div></div>
+<pre class="synopsis"><span class="bold"><strong>namespace</strong></span>
boost {
+ <span class="bold"><strong>namespace</strong></span> signals2 {
+ <span class="bold"><strong>class</strong></span> <a class="link"
href="../boost/signals2/dummy_mutex.html" title="Class
dummy_mutex">dummy_mutex</a>;
+ }
+}</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="header.boost.signals2.last_value_hpp"></a>Header <<a
href="../../../boost/signals2/last_value.hpp"
target="_top">boost/signals2/last_value.hpp</a>></h3></div></div></div>
+<pre class="synopsis"><span class="bold"><strong>namespace</strong></span>
boost {
+ <span class="bold"><strong>namespace</strong></span> signals2 {
+ <span class="bold"><strong>template</strong></span><<span
class="bold"><strong>typename</strong></span> T> <span
class="bold"><strong>class</strong></span> <a class="link"
href="../boost/signals2/last_value.html" title="Class template
last_value">last_value</a>;
+
+ <span class="bold"><strong>template</strong></span><> <span
class="bold"><strong>class</strong></span> <a class="link"
href="../boost/signals2/last_value_void_id2328948.html" title="Class
last_value<void>">last_value</a><<span
class="bold"><strong>void</strong></span>>;
+
+ <span class="bold"><strong>class</strong></span> <a class="link"
href="../boost/signals2/no_slots_error.html" title="Class
no_slots_error">no_slots_error</a>;
+ }
+}</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="header.boost.signals2.mutex_hpp"></a>Header <<a
href="../../../boost/signals2/mutex.hpp"
target="_top">boost/signals2/mutex.hpp</a>></h3></div></div></div>
+<pre class="synopsis"><span class="bold"><strong>namespace</strong></span>
boost {
+ <span class="bold"><strong>namespace</strong></span> signals2 {
+ <span class="bold"><strong>class</strong></span> <a class="link"
href="../boost/signals2/mutex.html" title="Class mutex">mutex</a>;
+ }
+}</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="header.boost.signals2.optional_last_value_hpp"></a>Header <<a
href="../../../boost/signals2/optional_last_value.hpp"
target="_top">boost/signals2/optional_last_value.hpp</a>></h3></div></div></div>
+<pre class="synopsis"><span class="bold"><strong>namespace</strong></span>
boost {
+ <span class="bold"><strong>namespace</strong></span> signals2 {
+ <span class="bold"><strong>template</strong></span><<span
class="bold"><strong>typename</strong></span> T> <span
class="bold"><strong>class</strong></span> <a class="link"
href="../boost/signals2/optional_last_value.html" title="Class template
optional_last_value">optional_last_value</a>;
+
+ <span class="bold"><strong>template</strong></span><> <span
class="bold"><strong>class</strong></span> <a class="link"
href="../boost/signals2/optional_last_value_voi_id2360959.html"
title="Class
optional_last_value<void>">optional_last_value</a><<span
class="bold"><strong>void</strong></span>>;
+ }
+}</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="header.boost.signals2.shared_connection_block_hpp"></a>Header
<<a href="../../../boost/signals2/shared_connection_block.hpp"
target="_top">boost/signals2/shared_connection_block.hpp</a>></h3></div></div></div>
+<pre class="synopsis"><span class="bold"><strong>namespace</strong></span>
boost {
+ <span class="bold"><strong>namespace</strong></span> signals2 {
+ <span class="bold"><strong>class</strong></span> <a class="link"
href="../boost/signals2/shared_connection_block.html" title="Class
shared_connection_block">shared_connection_block</a>;
+ }
+}</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="header.boost.signals2.signal_hpp"></a>Header <<a
href="../../../boost/signals2/signal.hpp"
target="_top">boost/signals2/signal.hpp</a>></h3></div></div></div>
+<pre class="synopsis"><span class="bold"><strong>namespace</strong></span>
boost {
+ <span class="bold"><strong>namespace</strong></span> signals2 {
+
+ <span class="bold"><strong>enum</strong></span> <a
name="boost.signals2.connect_position"></a>connect_position { at_front,
at_back };
+
+ <span class="bold"><strong>template</strong></span><<span
class="bold"><strong>typename</strong></span> R, <span
class="bold"><strong>typename</strong></span> T1, <span
class="bold"><strong>typename</strong></span> T2, ..., <span
class="bold"><strong>typename</strong></span> TN,
+ <span class="bold"><strong>typename</strong></span> Combiner
= <a class="link" href="../boost/signals2/optional_last_value.html"
title="Class template optional_last_value">optional_last_value</a><R>,
+ <span class="bold"><strong>typename</strong></span> Group =
<span class="bold"><strong>int</strong></span>, <span
class="bold"><strong>typename</strong></span> GroupCompare =
std::less<Group>,
+ <span class="bold"><strong>typename</strong></span>
SlotFunction = <a class="link" href="../boost/functionN.html" title="Class
template functionN">functionN</a><R, T1, T2, ..., TN>,
+ <span class="bold"><strong>typename</strong></span>
ExtendedSlotFunction = <a class="link" href="../boost/functionN.html"
title="Class template functionN">functionN</a><R, <span
class="bold"><strong>const</strong></span> <a class="link"
href="../boost/signals2/connection.html" title="Class
connection">connection</a> &, T1, T2, ..., TN>,
+ <span class="bold"><strong>typename</strong></span> Mutex =
<a class="link" href="../boost/signals2/mutex.html" title="Class
mutex">mutex</a>>
+ <span class="bold"><strong>class</strong></span> <a class="link"
href="../boost/signals2/signalN.html" title="Class template
signalN">signalN</a>;
+ <span class="bold"><strong>template</strong></span><<span
class="bold"><strong>typename</strong></span> Signature, <span
class="bold"><strong>typename</strong></span> Combiner = <a class="link"
href="../boost/signals2/optional_last_value.html" title="Class template
optional_last_value">optional_last_value</a><R>,
+ <span class="bold"><strong>typename</strong></span> Group =
<span class="bold"><strong>int</strong></span>, <span
class="bold"><strong>typename</strong></span> GroupCompare =
std::less<Group>,
+ <span class="bold"><strong>typename</strong></span>
SlotFunction = <a class="link" href="../boost/function.html" title="Class
template function">function</a><Signature>,
+ <span class="bold"><strong>typename</strong></span>
ExtendedSlotFunction = <a class="link" href="../boost/function.html"
title="Class template function">function</a><R (<span
class="bold"><strong>const</strong></span> <a class="link"
href="../boost/signals2/connection.html" title="Class
connection">connection</a> &, T1, T2, ..., TN)>,
+ <span class="bold"><strong>typename</strong></span> Mutex =
<a class="link" href="../boost/signals2/mutex.html" title="Class
mutex">mutex</a>>
+ <span class="bold"><strong>class</strong></span> <a class="link"
href="../boost/signals2/signal.html" title="Class template
signal">signal</a>;
+ }
+}</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="header.boost.signals2.signal_base_hpp"></a>Header <<a
href="../../../boost/signals2/signal_base.hpp"
target="_top">boost/signals2/signal_base.hpp</a>></h3></div></div></div>
+<pre class="synopsis"><span class="bold"><strong>namespace</strong></span>
boost {
+ <span class="bold"><strong>namespace</strong></span> signals2 {
+ <span class="bold"><strong>class</strong></span> <a class="link"
href="../boost/signals2/signal_base.html" title="Class
signal_base">signal_base</a>;
+ }
+}</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="header.boost.signals2.signal_type_hpp"></a>Header <<a
href="../../../boost/signals2/signal_type.hpp"
target="_top">boost/signals2/signal_type.hpp</a>></h3></div></div></div>
+<pre class="synopsis"><span class="bold"><strong>namespace</strong></span>
boost {
+ <span class="bold"><strong>namespace</strong></span> signals2 {
+ <span class="bold"><strong>template</strong></span><<span
class="bold"><strong>typename</strong></span> A0, <span
class="bold"><strong>typename</strong></span> A1 = boost::parameter::void_,
+ <span class="bold"><strong>typename</strong></span> A2 =
boost::parameter::void_,
+ <span class="bold"><strong>typename</strong></span> A3 =
boost::parameter::void_,
+ <span class="bold"><strong>typename</strong></span> A4 =
boost::parameter::void_,
+ <span class="bold"><strong>typename</strong></span> A5 =
boost::parameter::void_,
+ <span class="bold"><strong>typename</strong></span> A6 =
boost::parameter::void_>
+ <span class="bold"><strong>class</strong></span> <a class="link"
href="../boost/signals2/signal_type.html" title="Class template
signal_type">signal_type</a>;
+ <span class="bold"><strong>namespace</strong></span> keywords {
+ <span class="bold"><strong>template</strong></span><<span
class="bold"><strong>typename</strong></span> Signature> <span
class="bold"><strong>class</strong></span> <a class="link"
href="../boost/signals2/keywords/signature_type.html" title="Class template
signature_type">signature_type</a>;
+ <span class="bold"><strong>template</strong></span><<span
class="bold"><strong>typename</strong></span> Combiner> <span
class="bold"><strong>class</strong></span> <a class="link"
href="../boost/signals2/keywords/combiner_type.html" title="Class template
combiner_type">combiner_type</a>;
+ <span class="bold"><strong>template</strong></span><<span
class="bold"><strong>typename</strong></span> Group> <span
class="bold"><strong>class</strong></span> <a class="link"
href="../boost/signals2/keywords/group_type.html" title="Class template
group_type">group_type</a>;
+ <span class="bold"><strong>template</strong></span><<span
class="bold"><strong>typename</strong></span> GroupCompare> <span
class="bold"><strong>class</strong></span> <a class="link"
href="../boost/signals2/keywords/group_compare_type.html" title="Class
template group_compare_type">group_compare_type</a>;
+ <span class="bold"><strong>template</strong></span><<span
class="bold"><strong>typename</strong></span> SlotFunction> <span
class="bold"><strong>class</strong></span> <a class="link"
href="../boost/signals2/keywords/slot_function_type.html" title="Class
template slot_function_type">slot_function_type</a>;
+ <span class="bold"><strong>template</strong></span><<span
class="bold"><strong>typename</strong></span> ExtendedSlotFunction>
<span class="bold"><strong>class</strong></span> <a class="link"
href="../boost/signals2/keywords/extended_slot_function__id1223012.html"
title="Class template
extended_slot_function_type">extended_slot_function_type</a>;
+ <span class="bold"><strong>template</strong></span><<span
class="bold"><strong>typename</strong></span> Mutex> <span
class="bold"><strong>class</strong></span> <a class="link"
href="../boost/signals2/keywords/mutex_type.html" title="Class template
mutex_type">mutex_type</a>;
+ }
+ }
+}</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="header.boost.signals2.slot_hpp"></a>Header <<a
href="../../../boost/signals2/slot.hpp"
target="_top">boost/signals2/slot.hpp</a>></h3></div></div></div>
+<pre class="synopsis"><span class="bold"><strong>namespace</strong></span>
boost {
+ <span class="bold"><strong>namespace</strong></span> signals2 {
+ <span class="bold"><strong>template</strong></span><<span
class="bold"><strong>typename</strong></span> R, <span
class="bold"><strong>typename</strong></span> T1, <span
class="bold"><strong>typename</strong></span> T2, ..., <span
class="bold"><strong>typename</strong></span> TN,
+ <span class="bold"><strong>typename</strong></span>
SlotFunction = <a class="link" href="../boost/functionN.html" title="Class
template functionN">functionN</a><R, T1, T2, ..., TN> >
+ <span class="bold"><strong>class</strong></span> <a class="link"
href="../boost/signals2/slotN.html" title="Class template slotN">slotN</a>;
+ <span class="bold"><strong>template</strong></span><<span
class="bold"><strong>typename</strong></span> Signature, <span
class="bold"><strong>typename</strong></span> SlotFunction = <a
class="link" href="../boost/function.html" title="Class template
function">function</a><Signature> >
+ <span class="bold"><strong>class</strong></span> <a class="link"
href="../boost/signals2/slot.html" title="Class template slot">slot</a>;
+ }
+}</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="header.boost.signals2.slot_base_hpp"></a>Header <<a
href="../../../boost/signals2/slot_base.hpp"
target="_top">boost/signals2/slot_base.hpp</a>></h3></div></div></div>
+<pre class="synopsis"><span class="bold"><strong>namespace</strong></span>
boost {
+ <span class="bold"><strong>namespace</strong></span> signals2 {
+ <span class="bold"><strong>class</strong></span> <a class="link"
href="../boost/signals2/slot_base.html" title="Class
slot_base">slot_base</a>;
+ <span class="bold"><strong>class</strong></span> <a class="link"
href="../boost/signals2/expired_slot.html" title="Class
expired_slot">expired_slot</a>;
+ }
+}</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="header.boost.signals2.trackable_hpp"></a>Header <<a
href="../../../boost/signals2/trackable.hpp"
target="_top">boost/signals2/trackable.hpp</a>></h3></div></div></div>
+<pre class="synopsis"><span class="bold"><strong>namespace</strong></span>
boost {
+ <span class="bold"><strong>namespace</strong></span> signals2 {
+ <span class="bold"><strong>class</strong></span> <a class="link"
href="../boost/signals2/trackable.html" title="Class
trackable">trackable</a>;
+ }
+}</pre>
+</div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision";
width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright � 2001-2004
Douglas Gregor<br>Copyright � 2007-2009 Frank Mori Hess<p>Distributed under
the Boost
+ Software License, Version 1.0. (See accompanying file
+ <code class="filename">LICENSE_1_0.txt</code> or copy at <a
href="http://www.boost.org/LICENSE_1_0.txt";
target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)</p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="examples.html"><img
src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u"
href="../signals2.html"><img src="../../../doc/html/images/up.png"
alt="Up"></a><a accesskey="h" href="../index.html"><img
src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n"
href="../boost/signals2/connection.html"><img
src="../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
Added: trunk/doc/html/signals2/tests.html
==============================================================================
--- (empty file)
+++ trunk/doc/html/signals2/tests.html Thu May 7 20:34:38 2009
@@ -0,0 +1,127 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Testsuite</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.3">
+<link rel="home" href="../index.html" title="The Boost C++ Libraries
BoostBook Documentation Subset">
+<link rel="up" href="../signals2.html" title="Chapter�17.�Boost.Signals2">
+<link rel="prev" href="porting.html" title="Porting from Boost.Signals to
Boost.Signals2">
+<link rel="next" href="../boost_staticassert.html"
title="Chapter�18.�Boost.StaticAssert">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084"
alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86"
src="../../../boost.png"></td>
+<td align="center"><a href="../../../index.html">Home</a></td>
+<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
+<td align="center"><a
href="http://www.boost.org/users/people.html";>People</a></td>
+<td align="center"><a
href="http://www.boost.org/users/faq.html";>FAQ</a></td>
+<td align="center"><a href="../../../more/index.htm">More</a></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="porting.html"><img
src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u"
href="../signals2.html"><img src="../../../doc/html/images/up.png"
alt="Up"></a><a accesskey="h" href="../index.html"><img
src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n"
href="../boost_staticassert.html"><img
src="../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="signals2.tests"></a>Testsuite</h2></div></div></div>
+<div class="toc"><dl><dt><span class="section"><a
href="tests.html#id3387753">Acceptance tests</a></span></dt></dl></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id3387753"></a>Acceptance tests</h3></div></div></div>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>Test</th>
+<th>Type</th>
+<th>Description</th>
+<th>If failing...</th>
+</tr></thead>
+<tbody>
+<tr>
+<td><p><a href="../../../libs/signals2/test/connection_test.cpp"
target="_top">connection_test.cpp</a></p></td>
+<td><p>run</p></td>
+<td><p>Test functionality of <code class="computeroutput"><a class="link"
href="../boost/signals2/connection.html" title="Class
connection">boost::signals2::connection</a></code>
+ and <code class="computeroutput"><a class="link"
href="../boost/signals2/scoped_connection.html" title="Class
scoped_connection">boost::signals2::scoped_connection</a></code>
+ objects, including release() and swap().</p></td>
+<td>�</td>
+</tr>
+<tr>
+<td><p><a href="../../../libs/signals2/test/dead_slot_test.cpp"
target="_top">dead_slot_test.cpp</a></p></td>
+<td><p>run</p></td>
+<td><p>Ensure that calling <code class="computeroutput"><a class="link"
href="../boost/signals2/signalN.html#id1284885-bb">connect</a></code> with
a slot
+that has already expired does not actually
+connect to the slot.</p></td>
+<td>�</td>
+</tr>
+<tr>
+<td><p><a href="../../../libs/signals2/test/deconstruct_test.cpp"
target="_top">deconstruct_test.cpp</a></p></td>
+<td><p>run</p></td>
+<td><p>Test postconstruction/predestruction functionality of
+ <code class="computeroutput"><a class="link"
href="../boost/signals2/deconstruct.html" title="Function
deconstruct">boost::signals2::deconstruct</a></code>.</p></td>
+<td>�</td>
+</tr>
+<tr>
+<td><p><a href="../../../libs/signals2/test/deletion_test.cpp"
target="_top">deletion_test.cpp</a></p></td>
+<td><p>run</p></td>
+<td><p>Test deletion of slots.</p></td>
+<td>�</td>
+</tr>
+<tr>
+<td><p><a href="../../../libs/signals2/test/ordering_test.cpp"
target="_top">ordering_test.cpp</a></p></td>
+<td><p>run</p></td>
+<td><p>Test slot group ordering.</p></td>
+<td>�</td>
+</tr>
+<tr>
+<td><p><a href="../../../libs/signals2/test/regression_test.cpp"
target="_top">regression_test.cpp</a></p></td>
+<td><p>run</p></td>
+<td><p>Tests for various bugs that have occurred in the past,
+ to make sure they are fixed and stay fixed.</p></td>
+<td>�</td>
+</tr>
+<tr>
+<td><p><a href="../../../libs/signals2/test/signal_n_test.cpp"
target="_top">signal_n_test.cpp</a></p></td>
+<td><p>run</p></td>
+<td><p>Basic test of signal/slot connections and invocation using the
+<code class="computeroutput"><a class="link"
href="../boost/signals2/signalN.html" title="Class template
signalN">boost::signals2::signalN</a></code> class templates.</p></td>
+<td>�</td>
+</tr>
+<tr>
+<td><p><a href="../../../libs/signals2/test/signal_test.cpp"
target="_top">signal_test.cpp</a></p></td>
+<td><p>run</p></td>
+<td><p>Basic test of signal/slot connections and invocation using the
+<code class="computeroutput"><a class="link"
href="../boost/signals2/signal.html" title="Class template
signal">boost::signals2::signal</a></code> class template.</p></td>
+<td><p>The <code class="computeroutput"><a class="link"
href="../boost/signals2/signal.html" title="Class template
signal">boost::signals2::signal</a></code> class template may not
+be usable on your compiler. However, the
+<code class="computeroutput"><a class="link"
href="../boost/signals2/signalN.html" title="Class template
signalN">boost::signals2::signalN</a></code> class templates may still be
+usable.</p></td>
+</tr>
+<tr>
+<td><p><a href="../../../libs/signals2/test/track_test.cpp"
target="_top">track_test.cpp</a></p></td>
+<td><p>run</p></td>
+<td><p>Test automatic connection management of signals
+ and slots.</p></td>
+<td>�</td>
+</tr>
+</tbody>
+</table></div>
+</div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision";
width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright � 2001-2004
Douglas Gregor<br>Copyright � 2007-2009 Frank Mori Hess<p>Distributed under
the Boost
+ Software License, Version 1.0. (See accompanying file
+ <code class="filename">LICENSE_1_0.txt</code> or copy at <a
href="http://www.boost.org/LICENSE_1_0.txt";
target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)</p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="porting.html"><img
src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u"
href="../signals2.html"><img src="../../../doc/html/images/up.png"
alt="Up"></a><a accesskey="h" href="../index.html"><img
src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n"
href="../boost_staticassert.html"><img
src="../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
Added: trunk/doc/html/signals2/thread-safety.html
==============================================================================
--- (empty file)
+++ trunk/doc/html/signals2/thread-safety.html Thu May 7 20:34:38 2009
@@ -0,0 +1,220 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Thread-Safety</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.3">
+<link rel="home" href="../index.html" title="The Boost C++ Libraries
BoostBook Documentation Subset">
+<link rel="up" href="../signals2.html" title="Chapter�17.�Boost.Signals2">
+<link rel="prev" href="../boost/signals2/trackable.html" title="Class
trackable">
+<link rel="next" href="faq.html" title="Frequently Asked Questions">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084"
alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86"
src="../../../boost.png"></td>
+<td align="center"><a href="../../../index.html">Home</a></td>
+<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
+<td align="center"><a
href="http://www.boost.org/users/people.html";>People</a></td>
+<td align="center"><a
href="http://www.boost.org/users/faq.html";>FAQ</a></td>
+<td align="center"><a href="../../../more/index.htm">More</a></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../boost/signals2/trackable.html"><img
src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u"
href="../signals2.html"><img src="../../../doc/html/images/up.png"
alt="Up"></a><a accesskey="h" href="../index.html"><img
src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n"
href="faq.html"><img src="../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="signals2.thread-safety"></a>Thread-Safety</h2></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a
href="thread-safety.html#id3385400">Introduction</a></span></dt>
+<dt><span class="section"><a href="thread-safety.html#id3385455">Signals
and combiners</a></span></dt>
+<dt><span class="section"><a
href="thread-safety.html#id3385620">Connections and other
classes</a></span></dt>
+</dl></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id3385400"></a>Introduction</h3></div></div></div>
+<p>
+ The primary motivation for Boost.Signals2 is to provide a version of
+ the original Boost.Signals library which can be used safely in a
+ multi-threaded environment.
+ This is achieved primarily through two changes from the original
Boost.Signals
+ API. One is the introduction of a new automatic connection
management scheme
+ relying on <code class="computeroutput">shared_ptr</code> and <code
class="computeroutput">weak_ptr</code>,
+ as described in the <a class="link"
href="tutorial.html#signals2.tutorial.connection-management"
title="Automatic Connection Management (Intermediate)">tutorial</a>.
+ The second change was the introduction of a <code
class="computeroutput">Mutex</code> template type
+ parameter to the <code class="computeroutput"><a class="link"
href="../boost/signal.html" title="Class template signal">signal</a></code>
class. This section details how
+ the library employs these changes to provide thread-safety, and
+ the limits of the provided thread-safety.
+ </p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id3385455"></a>Signals and combiners</h3></div></div></div>
+<p>
+ Each signal object default-constructs a <code
class="computeroutput">Mutex</code> object to protect
+ its internal state. Furthermore, a <code
class="computeroutput">Mutex</code> is created
+ each time a new slot is connected to the signal, to protect the
+ associated signal-slot connection.
+ </p>
+<p>
+ A signal's mutex is automatically locked whenever any of the
+ signal's methods are called. The mutex is usually held until the
+ method completes, however there is one major exception to this
rule. When
+ a signal is invoked by calling
+ <code class="computeroutput">signal::operator()</code>,
+ the invocation first acquires a lock on the signal's mutex. Then
+ it obtains a handle to the signal's slot list and combiner. Next
+ it releases the signal's mutex, before invoking the combiner to
+ iterate through the slot list. Thus no mutexes are held by the
+ signal while a slot is executing. This design choice
+ makes it impossible for user code running in a slot
+ to deadlock against any of the
+ mutexes used internally by the Boost.Signals2 library.
+ It also prevents slots from accidentally causing
+ recursive locking attempts on any of the library's internal mutexes.
+ Therefore, if you invoke a signal concurrently from multiple threads,
+ it is possible for the signal's combiner to be invoked concurrently
+ and thus the slots to execute concurrently.
+ </p>
+<p>
+ During a combiner invocation, the following steps are performed in
order to
+ find the next callable slot while iterating through the signal's
+ slot list.
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li><p>The <code class="computeroutput">Mutex</code> associated with the
connection to the
+ slot is locked.</p></li>
+<li><p>All the tracked <code class="computeroutput">weak_ptr</code>
associated with the
+ slot are copied into temporary <code
class="computeroutput">shared_ptr</code> which
+ will be kept alive until the invocation is done with the slot.
If this fails due
+ to any of the
+ <code class="computeroutput">weak_ptr</code> being expired, the
connection is
+ automatically disconnected. Therefore a slot will never be run
+ if any of its tracked <code
class="computeroutput">weak_ptr</code> have expired,
+ and none of its tracked <code
class="computeroutput">weak_ptr</code> will
+ expire while the slot is running.
+ </p></li>
+<li><p>
+ The slot's connection is checked to see if it is blocked
+ or disconnected, and then the connection's mutex is unlocked.
If the connection
+ was either blocked or disconnected, we
+ start again from the beginning with the next slot in the slot
list.
+ Otherwise, we commit to executing the slot when the combiner next
+ dereferences the slot call iterator (unless the combiner should
increment
+ the iterator without ever dereferencing it).
+ </p></li>
+</ul></div>
+<p>
+ Note that since we unlock the connection's mutex before executing
+ its associated slot, it is possible a slot will still be executing
+ after it has been disconnected by a
+ <code class="computeroutput"><a class="link"
href="../boost/signals2/connection.html#id1278410-bb">connection::disconnect</a>()</code>,
if
+ the disconnect was called concurrently with signal invocation.
+ </p>
+<p>
+ You may have noticed above that during signal invocation, the
invocation only
+ obtains handles to the signal's slot list and combiner while holding
the
+ signal's mutex. Thus concurrent signal invocations may still wind up
+ accessing the
+ same slot list and combiner concurrently. So what happens if the
slot list is modified,
+ for example by connecting a new slot, while a signal
+ invocation is in progress concurrently? If the slot list is already
in use,
+ the signal performs a deep copy of the slot list before modifying it.
+ Thus the a concurrent signal invocation will continue to use the old
unmodified slot list,
+ undisturbed by modifications made to the newly created deep copy of
the slot list.
+ Future signal invocations will receive a handle to the newly created
deep
+ copy of the slot list, and the old slot list will be destroyed once
it
+ is no longer in use. Similarly, if you change a signal's combiner
with
+ <code class="computeroutput"><a class="link"
href="../boost/signals2/signalN.html#id2375152-bb">signal::set_combiner</a></code>
+ while a signal invocation is running concurrently, the concurrent
+ signal invocation will continue to use the old combiner undisturbed,
+ while future signal invocations will receive a handle to the new
combiner.
+ </p>
+<p>
+ The fact that concurrent signal invocations use the same combiner
object
+ means you need to insure any custom combiner you write is
thread-safe.
+ So if your combiner maintains state which is modified when the
combiner
+ is invoked, you
+ may need to protect that state with a mutex. Be aware, if you hold
+ a mutex in your combiner while dereferencing slot call iterators,
+ you run the risk of deadlocks and recursive locking if any of
+ the slots cause additional mutex locking to occur. One way to avoid
+ these perils is for your combiner to release any locks before
+ dereferencing a slot call iterator. The combiner classes provided by
+ the Boost.Signals2 library are all thread-safe, since they do not
maintain
+ any state across invocations.
+ </p>
+<p>
+ Suppose a user writes a slot which connects another slot to the
invoking signal.
+ Will the newly connected slot be run during the same signal
invocation in
+ which the new connection was made? The answer is no. Connecting a
new slot
+ modifies the signal's slot list, and as explained above, a signal
invocation
+ already in progress will not see any modifications made to the slot
list.
+ </p>
+<p>
+ Suppose a user writes a slot which disconnects another slot from the
invoking signal.
+ Will the disconnected slot be prevented from running during the same
signal invocation,
+ if it appears later in the slot list than the slot which
disconnected it?
+ This time the answer is yes. Even if the disconnected slot is still
+ present in the signal's slot list, each slot is checked to see if it
is
+ disconnected or blocked immediately before it is executed (or not
executed as
+ the case may be), as was described in more detail above.
+ </p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id3385620"></a>Connections and other
classes</h3></div></div></div>
+<p>
+ The methods of the <code class="computeroutput"><a class="link"
href="../boost/signals2/connection.html" title="Class
connection">signals2::connection</a></code> class are thread-safe,
+ with the exception of assignment and swap. This is achived via
locking the mutex
+ associated with the object's underlying signal-slot connection.
Assignment and
+ swap are not thread-safe because the mutex protects the underlying
connection
+ which a <code class="computeroutput"><a class="link"
href="../boost/signals2/connection.html" title="Class
connection">signals2::connection</a></code> object references, not
+ the <code class="computeroutput"><a class="link"
href="../boost/signals2/connection.html" title="Class
connection">signals2::connection</a></code> object itself. That is,
+ there may be many copies of a <code class="computeroutput"><a
class="link" href="../boost/signals2/connection.html" title="Class
connection">signals2::connection</a></code> object,
+ all of which reference the same underlying connection. There is not
a mutex
+ for each <code class="computeroutput"><a class="link"
href="../boost/signals2/connection.html" title="Class
connection">signals2::connection</a></code> object, there is only
+ a single mutex protecting the underlying connection they reference.
+ </p>
+<p>The <code class="computeroutput"><a class="link"
href="../boost/signals2/shared_connection_block.html" title="Class
shared_connection_block">shared_connection_block</a></code> class obtains
some thread-safety
+ from the <code class="computeroutput">Mutex</code> protecting the
underlying connection which is blocked
+ and unblocked. The internal reference counting which is used to
keep track of
+ how many <code class="computeroutput"><a class="link"
href="../boost/signals2/shared_connection_block.html" title="Class
shared_connection_block">shared_connection_block</a></code> objects are
asserting
+ blocks on their underlying connection is also thread-safe (the
implementation
+ relies on <code class="computeroutput">shared_ptr</code> for the
reference counting).
+ However, individual <code class="computeroutput"><a class="link"
href="../boost/signals2/shared_connection_block.html" title="Class
shared_connection_block">shared_connection_block</a></code> objects
+ should not be accessed concurrently by multiple threads. As long as
two
+ threads each have their own <code class="computeroutput"><a
class="link" href="../boost/signals2/shared_connection_block.html"
title="Class shared_connection_block">shared_connection_block</a></code>
object,
+ then they may use them in safety, even if both <code
class="computeroutput"><a class="link"
href="../boost/signals2/shared_connection_block.html" title="Class
shared_connection_block">shared_connection_block</a></code>
+ objects are copies and refer to the same underlying connection.
+ </p>
+<p>
+ The <code class="computeroutput"><a class="link"
href="../boost/signals2/slotN.html" title="Class template
slotN">slot</a></code> class has no internal mutex locking
+ built into it. It is expected that slot objects will be created then
+ connected to a signal in a single thread. Once they have been
copied into
+ a signal's slot list, they are protected by the mutex associated with
+ each signal-slot connection.
+ </p>
+<p>The <code class="computeroutput"><a class="link"
href="../boost/signals2/trackable.html" title="Class
trackable">signals2::trackable</a></code> class does NOT provide
+ thread-safe automatic connection management. In particular, it
leaves open the
+ possibility of a signal invocation calling into a partially
destructed object
+ if the trackable-derived object is destroyed in a different thread
from the
+ one invoking the signal.
+ <code class="computeroutput"><a class="link"
href="../boost/signals2/trackable.html" title="Class
trackable">signals2::trackable</a></code> is only provided as a convenience
+ for porting single-threaded code from Boost.Signals to
Boost.Signals2.
+ </p>
+</div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision";
width="100%"><tr>
+<td align="left"><p><small>Last revised: June 12, 2007 at 14:01:23
-0400</small></p></td>
+<td align="right"><div class="copyright-footer">Copyright � 2001-2004
Douglas Gregor<br>Copyright � 2007-2009 Frank Mori Hess<p>Distributed under
the Boost
+ Software License, Version 1.0. (See accompanying file
+ <code class="filename">LICENSE_1_0.txt</code> or copy at <a
href="http://www.boost.org/LICENSE_1_0.txt";
target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)</p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../boost/signals2/trackable.html"><img
src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u"
href="../signals2.html"><img src="../../../doc/html/images/up.png"
alt="Up"></a><a accesskey="h" href="../index.html"><img
src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n"
href="faq.html"><img src="../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
Added: trunk/doc/html/signals2/tutorial.html
==============================================================================
--- (empty file)
+++ trunk/doc/html/signals2/tutorial.html Thu May 7 20:34:38 2009
@@ -0,0 +1,1196 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Tutorial</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.3">
+<link rel="home" href="../index.html" title="The Boost C++ Libraries
BoostBook Documentation Subset">
+<link rel="up" href="../signals2.html" title="Chapter�17.�Boost.Signals2">
+<link rel="prev" href="../signals2.html"
title="Chapter�17.�Boost.Signals2">
+<link rel="next" href="examples.html" title="Example programs">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084"
alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86"
src="../../../boost.png"></td>
+<td align="center"><a href="../../../index.html">Home</a></td>
+<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
+<td align="center"><a
href="http://www.boost.org/users/people.html";>People</a></td>
+<td align="center"><a
href="http://www.boost.org/users/faq.html";>FAQ</a></td>
+<td align="center"><a href="../../../more/index.htm">More</a></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../signals2.html"><img
src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u"
href="../signals2.html"><img src="../../../doc/html/images/up.png"
alt="Up"></a><a accesskey="h" href="../index.html"><img
src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n"
href="examples.html"><img src="../../../doc/html/images/next.png"
alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="signals2.tutorial"></a>Tutorial</h2></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="tutorial.html#id3351397">How to Read
this Tutorial</a></span></dt>
+<dt><span class="section"><a href="tutorial.html#id3351460">Compatibility
Note</a></span></dt>
+<dt><span class="section"><a href="tutorial.html#id3351478">Hello, World!
(Beginner)</a></span></dt>
+<dt><span class="section"><a href="tutorial.html#id3351586">Calling
Multiple Slots</a></span></dt>
+<dt><span class="section"><a href="tutorial.html#id3351941">Passing Values
to and from Slots</a></span></dt>
+<dt><span class="section"><a href="tutorial.html#id3352571">Connection
Management</a></span></dt>
+<dt><span class="section"><a
href="tutorial.html#signals2.tutorial.document-view">Example:
Document-View</a></span></dt>
+<dt><span class="section"><a
href="tutorial.html#signals2.tutorial.extended-slot-type">Giving a Slot
Access to its Connection (Advanced)</a></span></dt>
+<dt><span class="section"><a
href="tutorial.html#signals2.tutorial.signal-mutex-template-parameter">Changing
the Mutex Type of a Signal (Advanced).</a></span></dt>
+<dt><span class="section"><a href="tutorial.html#id3353969">Linking
against the Signals2 library</a></span></dt>
+</dl></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id3351397"></a>How to Read this Tutorial</h3></div></div></div>
+<p>This tutorial is not meant to be read linearly. Its top-level
+structure roughly separates different concepts in the library
+(e.g., handling calling multiple slots, passing values to and from
+slots) and in each of these concepts the basic ideas are presented
+first and then more complex uses of the library are described
+later. Each of the sections is marked <span
class="emphasis"><em>Beginner</em></span>,
+<span class="emphasis"><em>Intermediate</em></span>, or <span
class="emphasis"><em>Advanced</em></span> to help guide the
+reader. The <span class="emphasis"><em>Beginner</em></span> sections
include information that all
+library users should know; one can make good use of the Signals2
+library after having read only the <span
class="emphasis"><em>Beginner</em></span> sections. The
+<span class="emphasis"><em>Intermediate</em></span> sections build on the
<span class="emphasis"><em>Beginner</em></span>
+sections with slightly more complex uses of the library. Finally,
+the <span class="emphasis"><em>Advanced</em></span> sections detail very
advanced uses of the
+Signals2 library, that often require a solid working knowledge of
+the <span class="emphasis"><em>Beginner</em></span> and <span
class="emphasis"><em>Intermediate</em></span> topics; most users
+will not need to read the <span class="emphasis"><em>Advanced</em></span>
sections.</p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id3351460"></a>Compatibility Note</h3></div></div></div>
+<p>Boost.Signals2 has two syntactical forms: the preferred form and
+the compatibility form. The preferred form fits more closely with the
+C++ language and reduces the number of separate template parameters
+that need to be considered, often improving readability; however, the
+preferred form is not supported on all platforms due to compiler
+bugs. Users of Boost.Function, please note
+that the preferred syntactic form in Signals2 is equivalent to that of
+Function's preferred syntactic form.</p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id3351478"></a>Hello, World! (Beginner)</h3></div></div></div>
+<p>The following example writes "Hello, World!" using signals and
+slots. First, we create a signal <code class="computeroutput">sig</code>,
a signal that
+takes no arguments and has a void return value. Next, we connect
+the <code class="computeroutput">hello</code> function object to the
signal using the
+<code class="computeroutput">connect</code> method. Finally, use the signal
+<code class="computeroutput">sig</code> like a function to call the slots,
which in turns
+invokes <code class="computeroutput">HelloWorld::operator()</code> to
print "Hello,
+World!".</p>
+<pre class="programlisting"><code class="computeroutput">struct HelloWorld
+{
+ void operator()() const
+ {
+ std::cout << "Hello, World!" << std::endl;
+ }
+};
+</code></pre>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th align="left">Preferred syntax</th>
+<th align="left">Portable syntax</th>
+</tr></thead>
+<tbody><tr>
+<td align="left">
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision";
class="table-programlisting"><code class="computeroutput"> // Signal with
no arguments and a void return value
+ boost::signals2::signal<void ()> sig;
+
+ // Connect a HelloWorld slot
+ HelloWorld hello;
+ sig.connect(hello);
+
+ // Call all of the slots
+ sig();
+</code></pre>
+</td>
+<td align="left">
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision";
class="table-programlisting"> // Signal with no arguments and a void
return value
+ boost::signals2::signal0<void> sig;
+
+ // Connect a HelloWorld slot
+ HelloWorld hello;
+ sig.connect(hello);
+
+ // Call all of the slots
+ sig();
+</pre>
+</td>
+</tr></tbody>
+</table></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id3351586"></a>Calling Multiple Slots</h3></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="tutorial.html#id3351590">Connecting
Multiple Slots (Beginner)</a></span></dt>
+<dt><span class="section"><a href="tutorial.html#id3351728">Ordering Slot
Call Groups (Intermediate)</a></span></dt>
+</dl></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="id3351590"></a>Connecting Multiple Slots
(Beginner)</h4></div></div></div>
+<p>Calling a single slot from a signal isn't very interesting, so
+we can make the Hello, World program more interesting by splitting
+the work of printing "Hello, World!" into two completely separate
+slots. The first slot will print "Hello" and may look like
+this:</p>
+<pre class="programlisting"><code class="computeroutput">struct Hello
+{
+ void operator()() const
+ {
+ std::cout << "Hello";
+ }
+};
+</code></pre>
+<p>The second slot will print ", World!" and a newline, to complete
+the program. The second slot may look like this:</p>
+<pre class="programlisting"><code class="computeroutput">struct World
+{
+ void operator()() const
+ {
+ std::cout << ", World!" << std::endl;
+ }
+};
+</code></pre>
+<p>Like in our previous example, we can create a signal
+<code class="computeroutput">sig</code> that takes no arguments and has a
+<code class="computeroutput">void</code> return value. This time, we
connect both a
+<code class="computeroutput">hello</code> and a <code
class="computeroutput">world</code> slot to the same
+signal, and when we call the signal both slots will be called.</p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th align="left">Preferred syntax</th>
+<th align="left">Portable syntax</th>
+</tr></thead>
+<tbody><tr>
+<td align="left">
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision";
class="table-programlisting"><code class="computeroutput">
boost::signals2::signal<void ()> sig;
+
+ sig.connect(Hello());
+ sig.connect(World());
+
+ sig();
+</code></pre>
+ </td>
+<td align="left">
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision";
class="table-programlisting"> boost::signals2::signal0<void> sig;
+
+ sig.connect(Hello());
+ sig.connect(World());
+
+ sig();
+</pre>
+</td>
+</tr></tbody>
+</table></div>
+<p>By default, slots are pushed onto the back of the slot list,
+so the output of this program will be as expected:</p>
+<pre class="programlisting">
+Hello, World!
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="id3351728"></a>Ordering Slot Call Groups
(Intermediate)</h4></div></div></div>
+<p>Slots are free to have side effects, and that can mean that some
+slots will have to be called before others even if they are not connected
in that order. The Boost.Signals2
+library allows slots to be placed into groups that are ordered in
+some way. For our Hello, World program, we want "Hello" to be
+printed before ", World!", so we put "Hello" into a group that must
+be executed before the group that ", World!" is in. To do this, we
+can supply an extra parameter at the beginning of the
+<code class="computeroutput">connect</code> call that specifies the group.
Group values
+are, by default, <code class="computeroutput">int</code>s, and are ordered
by the integer
+< relation. Here's how we construct Hello, World:</p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th align="left">Preferred syntax</th>
+<th align="left">Portable syntax</th>
+</tr></thead>
+<tbody><tr>
+<td align="left">
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision";
class="table-programlisting"><code class="computeroutput">
boost::signals2::signal<void ()> sig;
+
+ sig.connect(1, World()); // connect with group 1
+ sig.connect(0, Hello()); // connect with group 0
+</code></pre>
+</td>
+<td align="left">
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision";
class="table-programlisting"> boost::signals2::signal0<void> sig;
+
+ sig.connect(1, World()); // connect with group 1
+ sig.connect(0, Hello()); // connect with group 0</pre>
+</td>
+</tr></tbody>
+</table></div>
+<p>Invoking the signal will correctly print "Hello, World!", because the
+<code class="computeroutput">Hello</code> object is in group 0, which
precedes group 1 where
+the <code class="computeroutput">World</code> object resides. The group
+parameter is, in fact, optional. We omitted it in the first Hello,
+World example because it was unnecessary when all of the slots are
+independent. So what happens if we mix calls to connect that use the
+group parameter and those that don't? The "unnamed" slots (i.e., those
+that have been connected without specifying a group name) can be
+placed at the front or back of the slot list (by passing
+<code class="computeroutput">boost::signals2::at_front</code> or <code
class="computeroutput">boost::signals2::at_back</code>
+as the last parameter to <code class="computeroutput"><a class="link"
href="../boost/signals2/signalN.html#id1284885-bb">connect</a></code>,
respectively),
+and default to the end of the list. When
+a group is specified, the final <code
class="computeroutput">at_front</code> or <code
class="computeroutput">at_back</code>
+parameter describes where the slot
+will be placed within the group ordering. Ungrouped slots connected with
+<code class="computeroutput">at_front</code> will always precede all
grouped slots. Ungrouped
+slots connected with <code class="computeroutput">at_back</code> will
always succeed all
+grouped slots.
+</p>
+<p>
+ If we add a new slot to our example like this:
+</p>
+<pre class="programlisting"><code class="computeroutput">struct GoodMorning
+{
+ void operator()() const
+ {
+ std::cout << "... and good morning!" << std::endl;
+ }
+};
+</code></pre>
+<pre class="programlisting"><code class="computeroutput"> // by default
slots are connected at the end of the slot list
+ sig.connect(GoodMorning());
+
+ // slots are invoked this order:
+ // 1) ungrouped slots connected with boost::signals2::at_front
+ // 2) grouped slots according to ordering of their groups
+ // 3) ungrouped slots connected with boost::signals2::at_back
+ sig();
+</code></pre>
+<p>... we will get the result we wanted:</p>
+<pre class="programlisting">
+Hello, World!
+... and good morning!
+</pre>
+</div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id3351941"></a>Passing Values to and from
Slots</h3></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="tutorial.html#id3351946">Slot Arguments
(Beginner)</a></span></dt>
+<dt><span class="section"><a href="tutorial.html#id3352101">Signal Return
Values (Advanced)</a></span></dt>
+</dl></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="id3351946"></a>Slot Arguments (Beginner)</h4></div></div></div>
+<p>Signals can propagate arguments to each of the slots they call.
+For instance, a signal that propagates mouse motion events might
+want to pass along the new mouse coordinates and whether the mouse
+buttons are pressed.</p>
+<p>As an example, we'll create a signal that passes two
+<code class="computeroutput">float</code> arguments to its slots. Then
we'll create a few
+slots that print the results of various arithmetic operations on
+these values.</p>
+<pre class="programlisting"><code class="computeroutput">void
print_args(float x, float y)
+{
+ std::cout << "The arguments are " << x << " and "
<< y << std::endl;
+}
+
+void print_sum(float x, float y)
+{
+ std::cout << "The sum is " << x + y << std::endl;
+}
+
+void print_product(float x, float y)
+{
+ std::cout << "The product is " << x * y << std::endl;
+}
+
+void print_difference(float x, float y)
+{
+ std::cout << "The difference is " << x - y <<
std::endl;
+}
+
+void print_quotient(float x, float y)
+{
+ std::cout << "The quotient is " << x / y << std::endl;
+}
+</code></pre>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th align="left">Preferred syntax</th>
+<th align="left">Portable syntax</th>
+</tr></thead>
+<tbody><tr>
+<td align="left">
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision";
class="table-programlisting"><code class="computeroutput">
boost::signals2::signal<void (float, float)> sig;
+
+ sig.connect(&print_args);
+ sig.connect(&print_sum);
+ sig.connect(&print_product);
+ sig.connect(&print_difference);
+ sig.connect(&print_quotient);
+
+ sig(5., 3.);
+</code></pre>
+</td>
+<td align="left">
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision";
class="table-programlisting"> boost::signals2::signal2<void, float,
float> sig;
+
+ sig.connect(&print_args);
+ sig.connect(&print_sum);
+ sig.connect(&print_product);
+ sig.connect(&print_difference);
+ sig.connect(&print_quotient);
+
+ sig(5, 3);</pre>
+</td>
+</tr></tbody>
+</table></div>
+<p>This program will print out the following:</p>
+<pre class="programlisting">The arguments are 5 and 3
+The sum is 8
+The product is 15
+The difference is 2
+The quotient is 1.66667</pre>
+<p>So any values that are given to <code class="computeroutput">sig</code>
when it is
+called like a function are passed to each of the slots. We have to
+declare the types of these values up front when we create the
+signal. The type <code class="computeroutput"><a class="link"
href="../boost/signals2/signal.html" title="Class template
signal">boost::signals2::signal</a><void (float,
+float)></code> means that the signal has a <code
class="computeroutput">void</code>
+return value and takes two <code class="computeroutput">float</code>
values. Any slot
+connected to <code class="computeroutput">sig</code> must therefore be
able to take two
+<code class="computeroutput">float</code> values.</p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="id3352101"></a>Signal Return Values
(Advanced)</h4></div></div></div>
+<p>Just as slots can receive arguments, they can also return
+values. These values can then be returned back to the caller of the
+signal through a <em class="firstterm">combiner</em>. The combiner is a
mechanism
+that can take the results of calling slots (there many be no
+results or a hundred; we don't know until the program runs) and
+coalesces them into a single result to be returned to the caller.
+The single result is often a simple function of the results of the
+slot calls: the result of the last slot call, the maximum value
+returned by any slot, or a container of all of the results are some
+possibilities.</p>
+<p>We can modify our previous arithmetic operations example
+slightly so that the slots all return the results of computing the
+product, quotient, sum, or difference. Then the signal itself can
+return a value based on these results to be printed:</p>
+<pre class="programlisting"><code class="computeroutput">float
product(float x, float y) { return x * y; }
+float quotient(float x, float y) { return x / y; }
+float sum(float x, float y) { return x + y; }
+float difference(float x, float y) { return x - y; }
+</code></pre>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th align="left">Preferred syntax</th>
+<th align="left">Portable syntax</th>
+</tr></thead>
+<tbody><tr>
+<td align="left">
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision";
class="table-programlisting">boost::signals2::signal<float (float,
float)> sig;</pre>
+</td>
+<td align="left">
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision";
class="table-programlisting">boost::signals2::signal2<float, float,
float> sig;</pre>
+</td>
+</tr></tbody>
+</table></div>
+<pre class="programlisting"><code class="computeroutput">
sig.connect(&product);
+ sig.connect(&quotient);
+ sig.connect(&sum);
+ sig.connect(&difference);
+
+ // The default combiner returns a boost::optional containing the return
+ // value of the last slot in the slot list, in this case the
+ // difference function.
+ std::cout << *sig(5, 3) << std::endl;
+</code></pre>
+<p>This example program will output <code class="computeroutput">2</code>.
This is because the
+default behavior of a signal that has a return type
+(<code class="computeroutput">float</code>, the first template argument
given to the
+<code class="computeroutput"><a class="link"
href="../boost/signals2/signal.html" title="Class template
signal">boost::signals2::signal</a></code> class template) is to call all
slots and
+then return a <code class="computeroutput">boost::optional</code>
containing
+the result returned by the last slot called. This
+behavior is admittedly silly for this example, because slots have
+no side effects and the result is the last slot connected.</p>
+<p>A more interesting signal result would be the maximum of the
+values returned by any slot. To do this, we create a custom
+combiner that looks like this:</p>
+<pre class="programlisting"><code class="computeroutput">// combiner which
returns the maximum value returned by all slots
+template<typename T>
+struct maximum
+{
+ typedef T result_type;
+
+ template<typename InputIterator>
+ T operator()(InputIterator first, InputIterator last) const
+ {
+ // If there are no slots to call, just return the
+ // default-constructed value
+ if(first == last ) return T();
+ T max_value = *first++;
+ while (first != last) {
+ if (max_value < *first)
+ max_value = *first;
+ ++first;
+ }
+
+ return max_value;
+ }
+};
+</code></pre>
+<p>The <code class="computeroutput">maximum</code> class template acts as
a function
+object. Its result type is given by its template parameter, and
+this is the type it expects to be computing the maximum based on
+(e.g., <code class="computeroutput">maximum<float></code> would find
the maximum
+<code class="computeroutput">float</code> in a sequence of <code
class="computeroutput">float</code>s). When a
+<code class="computeroutput">maximum</code> object is invoked, it is given
an input
+iterator sequence <code class="computeroutput">[first, last)</code> that
includes the
+results of calling all of the slots. <code
class="computeroutput">maximum</code> uses this
+input iterator sequence to calculate the maximum element, and
+returns that maximum value.</p>
+<p>We actually use this new function object type by installing it
+as a combiner for our signal. The combiner template argument
+follows the signal's calling signature:</p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th align="left">Preferred syntax</th>
+<th align="left">Portable syntax</th>
+</tr></thead>
+<tbody><tr>
+<td align="left">
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision";
class="table-programlisting">
+<code class="computeroutput"><a class="link"
href="../boost/signals2/signal.html" title="Class template
signal">boost::signals2::signal</a></code><float (float x, float y),
+ maximum<float> > sig;
+</pre>
+</td>
+<td align="left">
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision";
class="table-programlisting">
+<code class="computeroutput"><a class="link"
href="../boost/signals2/signalN.html" title="Class template
signalN">boost::signals2::signal2</a></code><float, float, float,
+ maximum<float> > sig;
+</pre>
+</td>
+</tr></tbody>
+</table></div>
+<p>Now we can connect slots that perform arithmetic functions and
+use the signal:</p>
+<pre class="programlisting"><code class="computeroutput">
sig.connect(&product);
+ sig.connect(&quotient);
+ sig.connect(&sum);
+ sig.connect(&difference);
+
+ // Outputs the maximum value returned by the connected slots, in this
case
+ // 15 from the product function.
+ std::cout << "maximum: " << sig(5, 3) << std::endl;
+</code></pre>
+<p>The output of this program will be <code
class="computeroutput">15</code>, because
+regardless of the order in which the slots are connected, the product
+of 5 and 3 will be larger than the quotient, sum, or
+difference.</p>
+<p>In other cases we might want to return all of the values
+computed by the slots together, in one large data structure. This
+is easily done with a different combiner:</p>
+<pre class="programlisting"><code class="computeroutput">//
aggregate_values is a combiner which places all the values returned
+// from slots into a container
+template<typename Container>
+struct aggregate_values
+{
+ typedef Container result_type;
+
+ template<typename InputIterator>
+ Container operator()(InputIterator first, InputIterator last) const
+ {
+ Container values;
+
+ while(first != last) {
+ values.push_back(*first);
+ ++first;
+ }
+ return values;
+ }
+};
+</code></pre>
+<p>
+Again, we can create a signal with this new combiner:
+</p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th align="left">Preferred syntax</th>
+<th align="left">Portable syntax</th>
+</tr></thead>
+<tbody><tr>
+<td align="left">
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision";
class="table-programlisting">
+<code class="computeroutput"><a class="link"
href="../boost/signals2/signal.html" title="Class template
signal">boost::signals2::signal</a></code><float (float, float),
+ aggregate_values<std::vector<float> > > sig;</pre>
+</td>
+<td align="left">
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision";
class="table-programlisting">
+<code class="computeroutput"><a class="link"
href="../boost/signals2/signalN.html" title="Class template
signalN">boost::signals2::signal2</a></code><float, float, float,
+ aggregate_values<std::vector<float> > > sig;</pre>
+</td>
+</tr></tbody>
+</table></div>
+<pre class="programlisting"><code class="computeroutput">
sig.connect(&quotient);
+ sig.connect(&product);
+ sig.connect(&sum);
+ sig.connect(&difference);
+
+ std::vector<float> results = sig(5, 3);
+ std::cout << "aggregate values: ";
+ std::copy(results.begin(), results.end(),
+ std::ostream_iterator<float>(std::cout, " "));
+ std::cout << "\n";
+</code></pre>
+<p>The output of this program will contain 15, 8, 1.6667, and 2. It
+is interesting here that
+the first template argument for the <code
class="computeroutput">signal</code> class,
+<code class="computeroutput">float</code>, is not actually the return type
of the signal.
+Instead, it is the return type used by the connected slots and will
+also be the <code class="computeroutput">value_type</code> of the input
iterators passed
+to the combiner. The combiner itself is a function object and its
+<code class="computeroutput">result_type</code> member type becomes the
return type of the
+signal.</p>
+<p>The input iterators passed to the combiner transform dereference
+operations into slot calls. Combiners therefore have the option to
+invoke only some slots until some particular criterion is met. For
+instance, in a distributed computing system, the combiner may ask
+each remote system whether it will handle the request. Only one
+remote system needs to handle a particular request, so after a
+remote system accepts the work we do not want to ask any other
+remote systems to perform the same task. Such a combiner need only
+check the value returned when dereferencing the iterator, and
+return when the value is acceptable. The following combiner returns
+the first non-NULL pointer to a <code
class="computeroutput">FulfilledRequest</code> data
+structure, without asking any later slots to fulfill the
+request:</p>
+<pre class="programlisting">
+struct DistributeRequest {
+ typedef FulfilledRequest* result_type;
+
+ template<typename InputIterator>
+ result_type operator()(InputIterator first, InputIterator last) const
+ {
+ while (first != last) {
+ if (result_type fulfilled = *first)
+ return fulfilled;
+ ++first;
+ }
+ return 0;
+ }
+};
+</pre>
+</div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id3352571"></a>Connection Management</h3></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="tutorial.html#id3352576">Disconnecting
Slots (Beginner)</a></span></dt>
+<dt><span class="section"><a href="tutorial.html#id3352660">Blocking Slots
(Beginner)</a></span></dt>
+<dt><span class="section"><a href="tutorial.html#id3352717">Scoped
Connections (Intermediate)</a></span></dt>
+<dt><span class="section"><a href="tutorial.html#id3352816">Disconnecting
Equivalent Slots (Intermediate)</a></span></dt>
+<dt><span class="section"><a
href="tutorial.html#signals2.tutorial.connection-management">Automatic
Connection Management (Intermediate)</a></span></dt>
+<dt><span class="section"><a
href="tutorial.html#signals2.tutorial.deconstruct">Postconstructors and
Predestructors (Advanced)</a></span></dt>
+<dt><span class="section"><a href="tutorial.html#id3353362">When Can
Disconnections Occur? (Intermediate)</a></span></dt>
+<dt><span class="section"><a href="tutorial.html#id3353436">Passing Slots
(Intermediate)</a></span></dt>
+</dl></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="id3352576"></a>Disconnecting Slots
(Beginner)</h4></div></div></div>
+<p>Slots aren't expected to exist indefinitely after they are
+connected. Often slots are only used to receive a few events and
+are then disconnected, and the programmer needs control to decide
+when a slot should no longer be connected.</p>
+<p>The entry point for managing connections explicitly is the
+<code class="computeroutput"><a class="link"
href="../boost/signals2/connection.html" title="Class
connection">boost::signals2::connection</a></code> class. The
+<code class="computeroutput"><a class="link"
href="../boost/signals2/connection.html" title="Class
connection">connection</a></code> class uniquely represents the connection
+between a particular signal and a particular slot. The
+<code class="computeroutput"><a class="link"
href="../boost/signals2/connection.html#id1186298-bb">connected</a>()</code>
method checks if the signal and slot are
+still connected, and the <code class="computeroutput"><a class="link"
href="../boost/signals2/connection.html#id1278410-bb">disconnect()</a></code>
method
+disconnects the signal and slot if they are connected before it is
+called. Each call to the signal's <code
class="computeroutput">connect()</code> method
+returns a connection object, which can be used to determine if the
+connection still exists or to disconnect the signal and slot.</p>
+<pre class="programlisting"><code class="computeroutput">
boost::signals2::connection c = sig.connect(HelloWorld());
+ std::cout << "c is connected\n";
+ sig(); // Prints "Hello, World!"
+
+ c.disconnect(); // Disconnect the HelloWorld object
+ std::cout << "c is disconnected\n";
+ sig(); // Does nothing: there are no connected slots
+</code></pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="id3352660"></a>Blocking Slots (Beginner)</h4></div></div></div>
+<p>Slots can be temporarily "blocked", meaning that they will be
+ignored when the signal is invoked but have not been permanently
disconnected.
+This is typically used to prevent infinite recursion in cases where
+otherwise running a slot would cause the signal it is connected to to be
+invoked again. A
+<code class="computeroutput"><a class="link"
href="../boost/signals2/shared_connection_block.html" title="Class
shared_connection_block">boost::signals2::shared_connection_block</a></code>
object will
+temporarily block a slot. The connection is unblocked by either
+destroying or calling
+<code class="computeroutput"><a class="link"
href="../boost/signals2/shared_connection_block.html#id1183652-bb">unblock</a></code>
+on all the
+<code class="computeroutput">shared_connection_block</code> objects that
reference the connection.
+Here is an example of
+blocking/unblocking slots:</p>
+<pre class="programlisting"><code class="computeroutput">
boost::signals2::connection c = sig.connect(HelloWorld());
+ std::cout << "c is not blocked.\n";
+ sig(); // Prints "Hello, World!"
+
+ {
+ boost::signals2::shared_connection_block block(c); // block the slot
+ std::cout << "c is blocked.\n";
+ sig(); // No output: the slot is blocked
+ } // shared_connection_block going out of scope unblocks the slot
+ std::cout << "c is not blocked.\n";
+ sig(); // Prints "Hello, World!"}
+</code></pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="id3352717"></a>Scoped Connections
(Intermediate)</h4></div></div></div>
+<p>The <code class="computeroutput"><a class="link"
href="../boost/signals2/scoped_connection.html" title="Class
scoped_connection">boost::signals2::scoped_connection</a></code> class
+references a signal/slot connection that will be disconnected when
+the <code class="computeroutput">scoped_connection</code> class goes out
of scope. This
+ability is useful when a connection need only be temporary,
+e.g.,</p>
+<pre class="programlisting"><code class="computeroutput"> {
+ boost::signals2::scoped_connection c(sig.connect(ShortLived()));
+ sig(); // will call ShortLived function object
+ } // scoped_connection goes out of scope and disconnects
+
+ sig(); // ShortLived function object no longer connected to sig
+</code></pre>
+<p>
+ Note, attempts to initialize a scoped_connection with the assignment
syntax
+ will fail due to it being noncopyable. Either the explicit
initialization syntax
+ or default construction followed by assignment from a <code
class="computeroutput"><a class="link"
href="../boost/signals2/connection.html" title="Class
connection">connection</a></code>
+ will work:
+</p>
+<pre class="programlisting">
+// doesn't compile due to compiler attempting to copy a temporary
scoped_connection object
+// boost::signals2::scoped_connection c0 = sig.<code
class="computeroutput"><a class="link"
href="../boost/signals2/signalN.html#id1284885-bb">connect</a></code>(ShortLived());
+
+// okay
+boost::signals2::scoped_connection c1(sig.<code class="computeroutput"><a
class="link"
href="../boost/signals2/signalN.html#id1284885-bb">connect</a></code>(ShortLived()));
+
+// also okay
+boost::signals2::scoped_connection c2;
+c2 = sig.<code class="computeroutput"><a class="link"
href="../boost/signals2/signalN.html#id1284885-bb">connect</a></code>(ShortLived());
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="id3352816"></a>Disconnecting Equivalent Slots
(Intermediate)</h4></div></div></div>
+<p>One can disconnect slots that are equivalent to a given function
+object using a form of the
+<code class="computeroutput"><a class="link"
href="../boost/signalN.html#id1242363-bb">signal::disconnect</a></code>
method, so long as
+the type of the function object has an accessible <code
class="computeroutput">==</code>
+operator. For instance:
+
+</p>
+<pre class="programlisting"><code class="computeroutput">void foo() {
std::cout << "foo"; }
+void bar() { std::cout << "bar\n"; }
+</code></pre>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th align="left">Preferred syntax</th>
+<th align="left">Portable syntax</th>
+</tr></thead>
+<tbody><tr>
+<td align="left">
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision";
class="table-programlisting"><code class="computeroutput"><a class="link"
href="../boost/signals2/signal.html" title="Class template
signal">boost::signals2::signal</a></code><void ()> sig;</pre>
+</td>
+<td align="left">
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision";
class="table-programlisting"><code class="computeroutput"><a class="link"
href="../boost/signals2/signalN.html" title="Class template
signalN">boost::signals2::signal0</a></code><void> sig;</pre>
+</td>
+</tr></tbody>
+</table></div>
+</div>
+<pre class="programlisting"><code class="computeroutput">
sig.connect(&foo);
+ sig.connect(&bar);
+ sig();
+
+ // disconnects foo, but not bar
+ sig.disconnect(&foo);
+ sig();
+</code></pre>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="signals2.tutorial.connection-management"></a>Automatic Connection
Management (Intermediate)</h4></div></div></div>
+<p>Boost.Signals2 can automatically track the lifetime of objects
+involved in signal/slot connections, including automatic
+disconnection of slots when objects involved in the slot call are
+destroyed. For instance, consider a simple news delivery service,
+where clients connect to a news provider that then sends news to
+all connected clients as information arrives. The news delivery
+service may be constructed like this: </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th align="left">Preferred syntax</th>
+<th align="left">Portable syntax</th>
+</tr></thead>
+<tbody><tr>
+<td align="left">
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision";
class="table-programlisting">
+class NewsItem { /* ... */ };
+
+typedef boost::signals2::signal<void (const NewsItem&)>
signal_type;
+signal_type deliverNews;
+</pre>
+</td>
+<td align="left">
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision";
class="table-programlisting">
+class NewsItem { /* ... */ };
+
+typedef boost::signals2::signal1<void, const NewsItem&>
signal_type;
+signal_type deliverNews;
+</pre>
+</td>
+</tr></tbody>
+</table></div>
+<p>Clients that wish to receive news updates need only connect a
+function object that can receive news items to the
+<code class="computeroutput">deliverNews</code> signal. For instance, we
may have a
+special message area in our application specifically for news,
+e.g.,:</p>
+<pre class="programlisting">
+struct NewsMessageArea : public MessageArea
+{
+public:
+ // ...
+
+ void displayNews(const NewsItem& news) const
+ {
+ messageText = news.text();
+ update();
+ }
+};
+
+// ...
+NewsMessageArea *newsMessageArea = new NewsMessageArea(/* ... */);
+// ...
+deliverNews.<code class="computeroutput"><a class="link"
href="../boost/signals2/signalN.html#id1284885-bb">connect</a></code>(boost::bind(&NewsMessageArea::displayNews,
+ newsMessageArea, _1));
+</pre>
+<p>However, what if the user closes the news message area,
+destroying the <code class="computeroutput">newsMessageArea</code> object
that
+<code class="computeroutput">deliverNews</code> knows about? Most likely,
a segmentation
+fault will occur. However, with Boost.Signals2 one may track any object
+which is managed by a shared_ptr, by using
+<code class="computeroutput"><a class="link"
href="../boost/signals2/slotN.html#id1187184-bb">slot::track</a></code>. A
slot will automatically
+disconnect when any of its tracked objects expire. In
+addition, Boost.Signals2 will ensure that no tracked object expires
+while the slot it is associated with is in mid-execution. It does so by
creating
+temporary shared_ptr copies of the slot's tracked objects before executing
it.
+To track <code class="computeroutput">NewsMessageArea</code>, we use a
shared_ptr to manage
+its lifetime, and pass the shared_ptr to the slot via its
+<code class="computeroutput"><a class="link"
href="../boost/signals2/slotN.html#id1187184-bb">slot::track</a></code>
+method before connecting it,
+e.g.:</p>
+<pre class="programlisting">
+// ...
+boost::shared_ptr<NewsMessageArea> newsMessageArea(new
NewsMessageArea(/* ... */));
+// ...
+deliverNews.<code class="computeroutput"><a class="link"
href="../boost/signals2/signalN.html#id1284885-bb">connect</a></code>(signal_type::slot_type(&NewsMessageArea::displayNews,
+ newsMessageArea.get(), _1).track(newsMessageArea));
+</pre>
+<p>
+ Note there is no explicit call to bind() needed in the above example.
If the
+ <code class="computeroutput"><a class="link"
href="../boost/signals2/slotN.html" title="Class template
slotN">slot</a></code> constructor is passed more than one
+ argument, it will automatically pass all the arguments to <code
class="computeroutput">bind</code> and use the
+ returned function object.
+</p>
+<p>Also note, we pass an ordinary pointer as the
+ second argument to the slot constructor, using <code
class="computeroutput">newsMessageArea.get()</code>
+ instead of passing the <code class="computeroutput">shared_ptr</code>
itself. If we had passed the
+ <code class="computeroutput">newsMessageArea</code> itself, a copy of
the <code class="computeroutput">shared_ptr</code> would
+ have been bound into the slot function, preventing the <code
class="computeroutput">shared_ptr</code>
+ from expiring. However, the use of
+ <code class="computeroutput"><a class="link"
href="../boost/signals2/slotN.html#id1187184-bb">slot::track</a></code>
+ implies we wish to allow the tracked object to expire, and automatically
+ disconnect the connection when this occurs.
+</p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="signals2.tutorial.deconstruct"></a>Postconstructors and
Predestructors (Advanced)</h4></div></div></div>
+<p>One limitation of using <code class="computeroutput">shared_ptr</code>
for tracking is that
+ an object cannot setup tracking of itself in its constructor.
However, it is
+ possible to set up tracking in a post-constructor which is called
after the
+ object has been created and passed to a <code
class="computeroutput">shared_ptr</code>.
+ The Boost.Signals2
+ library provides support for post-constructors and pre-destructors
+ via the <code class="computeroutput"><a class="link"
href="../boost/signals2/deconstruct.html" title="Function
deconstruct">deconstruct()</a></code> factory function.
+ </p>
+<p>
+ For most cases, the simplest and most robust way to setup
postconstructors
+ for a class is to define an associated <code
class="computeroutput">adl_postconstruct</code> function
+ which can be found by <code class="computeroutput"><a class="link"
href="../boost/signals2/deconstruct.html" title="Function
deconstruct">deconstruct()</a></code>,
+ make the class' constructors private, and give <code
class="computeroutput"><a class="link"
href="../boost/signals2/deconstruct.html" title="Function
deconstruct">deconstruct</a></code>
+ access to the private constructors by declaring <code
class="computeroutput"><a class="link"
href="../boost/signals2/deconstruct_access.html" title="Class
deconstruct_access">deconstruct_access</a></code>
+ a friend. This will ensure that objects of the class may only be
created
+ through the <code class="computeroutput"><a class="link"
href="../boost/signals2/deconstruct.html" title="Function
deconstruct">deconstruct()</a></code> function, and their
+ associated <code class="computeroutput">adl_postconstruct()</code>
function will always be called.
+ </p>
+<p>The <a class="link" href="examples.html#signals2.examples.deconstruct"
title="Postconstructors and Predestructors with deconstruct()">examples</a>
section
+ contains several examples of defining classes with postconstructors
and
+ predestructors, and creating objects of these classes using
+ <code class="computeroutput"><a class="link"
href="../boost/signals2/deconstruct.html" title="Function
deconstruct">deconstruct()</a></code>
+ </p>
+<p>
+ Be aware that the postconstructor/predestructor support in
Boost.Signals2
+ is in no way essential to the use of the library. The use of
+ <code class="computeroutput"><a class="link"
href="../boost/signals2/deconstruct.html" title="Function
deconstruct">deconstruct</a></code>
+ is purely optional. One alternative is to
+ define static factory functions for your classes. The
+ factory function can create an object, pass ownership of the object
to
+ a <code class="computeroutput">shared_ptr</code>, setup tracking for
the object,
+ then return the <code class="computeroutput">shared_ptr</code>.
+ </p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="id3353362"></a>When Can Disconnections Occur?
(Intermediate)</h4></div></div></div>
+<p>Signal/slot disconnections occur when any of these conditions
+occur:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p>The connection is explicitly disconnected via the connection's
+<code class="computeroutput">disconnect</code> method directly, or
indirectly via the
+signal's <code class="computeroutput">disconnect</code> method, or
+<code class="computeroutput">scoped_connection</code>'s
destructor.</p></li>
+<li><p>An object tracked by the slot is
+destroyed.</p></li>
+<li><p>The signal is destroyed.</p></li>
+</ul></div>
+<p>These events can occur at any time without disrupting a signal's
+calling sequence. If a signal/slot connection is disconnected at
+any time during a signal's calling sequence, the calling sequence
+will still continue but will not invoke the disconnected slot.
+Additionally, a signal may be destroyed while it is in a calling
+sequence, and which case it will complete its slot call sequence
+but may not be accessed directly.</p>
+<p>Signals may be invoked recursively (e.g., a signal A calls a
+slot B that invokes signal A...). The disconnection behavior does
+not change in the recursive case, except that the slot calling
+sequence includes slot calls for all nested invocations of the
+signal.</p>
+<p>
+ Note, even after a connection is disconnected, its's associated slot
+ may still be in the process of executing. In other words, disconnection
+ does not block waiting for the connection's associated slot to complete
execution.
+ This situation may occur in a multi-threaded environment if the
+ disconnection occurs concurrently with signal invocation,
+ or in a single-threaded environment if a slot disconnects itself.
+</p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="id3353436"></a>Passing Slots (Intermediate)</h4></div></div></div>
+<p>Slots in the Boost.Signals2 library are created from arbitrary
+function objects, and therefore have no fixed type. However, it is
+commonplace to require that slots be passed through interfaces that
+cannot be templates. Slots can be passed via the
+<code class="computeroutput">slot_type</code> for each particular signal
type and any
+function object compatible with the signature of the signal can be
+passed to a <code class="computeroutput">slot_type</code> parameter. For
instance:</p>
+<pre class="programlisting"><code class="computeroutput">// a pretend GUI
button
+class Button
+{
+ typedef boost::signals2::signal<void (int x, int y)> OnClick;
+public:
+ typedef OnClick::slot_type OnClickSlotType;
+ // forward slots through Button interface to its private signal
+ boost::signals2::connection doOnClick(const OnClickSlotType & slot);
+
+ // simulate user clicking on GUI button at coordinates 52, 38
+ void simulateClick();
+private:
+ OnClick onClick;
+};
+
+boost::signals2::connection Button::doOnClick(const OnClickSlotType &
slot)
+{
+ return onClick.connect(slot);
+}
+
+void Button::simulateClick()
+{
+ onClick(52, 38);
+}
+
+void printCoordinates(long x, long y)
+{
+ std::cout << "(" << x << ", " << y
<< ")\n";
+}
+</code></pre>
+<pre class="programlisting">
+<code class="computeroutput"> Button button;
+ button.doOnClick(&printCoordinates);
+ button.simulateClick();
+</code></pre>
+<p>The <code class="computeroutput">doOnClick</code> method is now
functionally equivalent
+to the <code class="computeroutput">connect</code> method of the <code
class="computeroutput">onClick</code>
+signal, but the details of the <code
class="computeroutput">doOnClick</code> method can be
+hidden in an implementation detail file.</p>
+</div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="signals2.tutorial.document-view"></a>Example:
Document-View</h3></div></div></div>
+<p>Signals can be used to implement flexible Document-View
+ architectures. The document will contain a signal to which each of
+ the views can connect. The following <code
class="computeroutput">Document</code> class
+ defines a simple text document that supports mulitple views. Note
+ that it stores a single signal to which all of the views will be
+ connected.</p>
+<pre class="programlisting"><code class="computeroutput">class Document
+{
+public:
+ typedef boost::signals2::signal<void ()> signal_t;
+
+public:
+ Document()
+ {}
+
+ /* Connect a slot to the signal which will be emitted whenever
+ text is appended to the document. */
+ boost::signals2::connection connect(const signal_t::slot_type
&subscriber)
+ {
+ return m_sig.connect(subscriber);
+ }
+
+ void append(const char* s)
+ {
+ m_text += s;
+ m_sig();
+ }
+
+ const std::string& getText() const
+ {
+ return m_text;
+ }
+
+private:
+ signal_t m_sig;
+ std::string m_text;
+};
+</code></pre>
+<p>
+ Next, we can begin to define views. The
+ following <code class="computeroutput">TextView</code> class provides
a simple view of the
+ document text.
+ </p>
+<pre class="programlisting"><code class="computeroutput">class TextView
+{
+public:
+ TextView(Document& doc): m_document(doc)
+ {
+ m_connection =
m_document.connect(boost::bind(&TextView::refresh, this));
+ }
+
+ ~TextView()
+ {
+ m_connection.disconnect();
+ }
+
+ void refresh() const
+ {
+ std::cout << "TextView: " << m_document.getText()
<< std::endl;
+ }
+private:
+ Document& m_document;
+ boost::signals2::connection m_connection;
+};
+</code></pre>
+<p>Alternatively, we can provide a view of the document
+ translated into hex values using the <code
class="computeroutput">HexView</code>
+ view:</p>
+<pre class="programlisting"><code class="computeroutput">class HexView
+{
+public:
+ HexView(Document& doc): m_document(doc)
+ {
+ m_connection =
m_document.connect(boost::bind(&HexView::refresh, this));
+ }
+
+ ~HexView()
+ {
+ m_connection.disconnect();
+ }
+
+ void refresh() const
+ {
+ const std::string& s = m_document.getText();
+
+ std::cout << "HexView:";
+
+ for (std::string::const_iterator it = s.begin(); it != s.end();
++it)
+ std::cout << ' ' << std::hex <<
static_cast<int>(*it);
+
+ std::cout << std::endl;
+ }
+private:
+ Document& m_document;
+ boost::signals2::connection m_connection;
+};
+</code></pre>
+<p>
+ To tie the example together, here is a
+ simple <code class="computeroutput">main</code> function that sets up
two views and then
+ modifies the document:
+ </p>
+<pre class="programlisting"><code class="computeroutput">int main(int
argc, char* argv[])
+{
+ Document doc;
+ TextView v1(doc);
+ HexView v2(doc);
+
+ doc.append(argc == 2 ? argv[1] : "Hello world!");
+ return 0;
+}
+</code></pre>
+<p>The complete example source, contributed by Keith MacDonald,
+ is available in the <a class="link"
href="examples.html#signals2.examples.document-view"
title="Document-View">examples</a> section.
+ We also provide variations on the program which employ automatic
connection management
+ to disconnect views on their destruction.
+ </p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="signals2.tutorial.extended-slot-type"></a>Giving a Slot Access to
its Connection (Advanced)</h3></div></div></div>
+<p>
+ You may encounter situations where you wish to disconnect or block a
slot's
+ connection from within the slot itself. For example, suppose you
have a group
+ of asynchronous tasks, each of which emits a signal when it
completes.
+ You wish to connect a slot to all the tasks to retrieve their
results as
+ each completes. Once a
+ given task completes and the slot is run, the slot no longer needs
to be
+ connected to the completed task.
+ Therefore, you may wish to clean up old connections by having the
slot
+ disconnect its invoking connection when it runs.
+ </p>
+<p>
+ For a slot to disconnect (or block) its invoking connection, it must
have
+ access to a <code class="computeroutput"><a class="link"
href="../boost/signals2/connection.html" title="Class
connection">connection</a></code> object which references
+ the invoking signal-slot connection. The difficulty is,
+ the <code class="computeroutput"><a class="link"
href="../boost/signals2/connection.html" title="Class
connection">connection</a></code> object is returned by the
+ <code class="computeroutput"><a class="link"
href="../boost/signalN.html#id1215527-bb">signal::connect</a></code>
+ method, and therefore is not available until after the slot is
+ already connected to the signal. This can be particularly
troublesome
+ in a multi-threaded environment where the signal may be invoked
+ concurrently by a different thread while the slot is being connected.
+ </p>
+<p>
+ Therefore, the signal classes provide
+ <code class="computeroutput"><a class="link"
href="../boost/signals2/signalN.html#id1208227-bb">signal::connect_extended</a></code>
+ methods, which allow slots which take an extra argument to be
connected to a signal.
+ The extra argument is a <code class="computeroutput"><a class="link"
href="../boost/signals2/connection.html" title="Class
connection">connection</a></code> object which refers
+ to the signal-slot connection currently invoking the slot.
+ <code class="computeroutput"><a class="link"
href="../boost/signals2/signalN.html#id1208227-bb">signal::connect_extended</a></code>
+ uses slots of the type given by the
+ <code class="computeroutput"><a class="link"
href="../boost/signals2/signalN.html#boost.signals2.signalN.extended_slot_type">signal::extended_slot_type</a></code>
+ typedef.
+ </p>
+<p>
+ The examples section includes an
+ <a class="link"
href="examples.html#signals2.examples.tutorial.extended_slot"
title="extended_slot">extended_slot</a>
+ program which demonstrates the syntax for using
+ <code class="computeroutput"><a class="link"
href="../boost/signals2/signalN.html#id1208227-bb">signal::connect_extended</a></code>.
+ </p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="signals2.tutorial.signal-mutex-template-parameter"></a>Changing
the <code class="computeroutput">Mutex</code> Type of a Signal
(Advanced).</h3></div></div></div>
+<p>
+ For most cases the default type of <code class="computeroutput"><a
class="link" href="../boost/signals2/mutex.html" title="Class
mutex">boost::signals2::mutex</a></code> for
+ a <code class="computeroutput"><a class="link"
href="../boost/signal.html" title="Class template
signal">signal</a></code>'s <code class="computeroutput">Mutex</code>
template type parameter should
+ be fine. If you wish to use an alternate mutex type, it must be
default-constructible
+ and fulfill the <code class="computeroutput">Lockable</code> concept
defined by the Boost.Thread library.
+ That is, it must have <code class="computeroutput">lock()</code> and
<code class="computeroutput">unlock()</code> methods
+ (the <code class="computeroutput">Lockable</code> concept also
includes a <code class="computeroutput">try_lock()</code> method
+ but this library does not require try locking).
+ </p>
+<p>
+ The Boost.Signals2 library provides one alternate mutex class for
use with <code class="computeroutput"><a class="link"
href="../boost/signal.html" title="Class template signal">signal</a></code>:
+ <code class="computeroutput"><a class="link"
href="../boost/signals2/dummy_mutex.html" title="Class
dummy_mutex">boost::signals2::dummy_mutex</a></code>. This is a fake mutex
for
+ use in single-threaded programs, where locking a real mutex would be
useless
+ overhead. Other mutex types you could use with <code
class="computeroutput"><a class="link" href="../boost/signal.html"
title="Class template signal">signal</a></code> include
+ <code class="computeroutput">boost::mutex</code> and the <code
class="computeroutput">std::mutex</code> from
+ C++0x.
+ </p>
+<p>
+ Changing a signal's <code class="computeroutput">Mutex</code>
template type parameter can be tedious, due to
+ the large number of template parameters which precede it. The
+ <code class="computeroutput"><a class="link"
href="../boost/signals2/signal_type.html" title="Class template
signal_type">signal_type</a></code> metafunction is particularly useful in
this case,
+ since it enables named template type parameters for the <code
class="computeroutput"><a class="link" href="../boost/signal.html"
title="Class template signal">signal</a></code>
+ class. For example, to declare a signal which takes an <code
class="computeroutput">int</code> as
+ an argument and uses a <code class="computeroutput"><a class="link"
href="../boost/signals2/dummy_mutex.html" title="Class
dummy_mutex">boost::signals2::dummy_mutex</a></code>
+ for its <code class="computeroutput">Mutex</code> types, you could
write:
+ </p>
+<pre class="programlisting">namespace bs2 = boost::signals2;
+using bs2::keywords;
+bs2::signal_type<void (int), mutex_type<bs2::dummy_mutex>
>::type sig;
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id3353969"></a>Linking against the Signals2
library</h3></div></div></div>
+<p>Unlike the original Boost.Signals library, Boost.Signals2 is currently
header-only.
+ </p>
+</div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision";
width="100%"><tr>
+<td align="left"><p><small>Last revised: June 12, 2007 at 14:01:23
-0400</small></p></td>
+<td align="right"><div class="copyright-footer">Copyright � 2001-2004
Douglas Gregor<br>Copyright � 2007-2009 Frank Mori Hess<p>Distributed under
the Boost
+ Software License, Version 1.0. (See accompanying file
+ <code class="filename">LICENSE_1_0.txt</code> or copy at <a
href="http://www.boost.org/LICENSE_1_0.txt";
target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)</p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../signals2.html"><img
src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u"
href="../signals2.html"><img src="../../../doc/html/images/up.png"
alt="Up"></a><a accesskey="h" href="../index.html"><img
src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n"
href="examples.html"><img src="../../../doc/html/images/next.png"
alt="Next"></a>
+</div>
+</body>
+</html>
Added: trunk/libs/signals2/doc/examples.xml
==============================================================================
--- (empty file)
+++ trunk/libs/signals2/doc/examples.xml Thu May 7 20:34:38 2009
@@ -0,0 +1,180 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
+ "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd";>
+<!--
+Copyright Douglas Gregor 2001-2004
+Copyright Frank Mori Hess 2007-2009
+
+Distributed under the Boost Software License, Version 1.0. (See
accompanying
+file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+-->
+<section last-revision="$Date: 2007-06-12 14:01:23 -0400 (Tue, 12 Jun
2007) $" id="signals2.examples">
+ <title>Example programs</title>
+
+ <using-namespace name="boost"/>
+ <using-namespace name="boost::signals2"/>
+
+ <section id="signals2.examples.misc">
+ <title>Miscellaneous Tutorial Examples</title>
+ <section id="signals2.examples.tutorial.hello_world_slot">
+ <title>hello_world_slot</title>
+ <para>
+ This example is a basic example of connecting a slot to a signal
+ and then invoking the signal.
+ </para>
+ <para>
+ Download <ulink
url="boost:/libs/signals2/example/hello_world_slot.cpp">hello_world_slot.cpp</ulink>.
+ </para>
+ </section>
+ <section id="signals2.examples.tutorial.hello_world_multi_slot">
+ <title>hello_world_multi_slot</title>
+ <para>
+ This example extends the hello_world_slot example slightly by
connecting more than one
+ slot to the signal before invoking it.
+ </para>
+ <para>
+ Download <ulink
url="boost:/libs/signals2/example/hello_world_multi_slot.cpp">hello_world_multi_slot.cpp</ulink>.
+ </para>
+ </section>
+ <section id="signals2.examples.tutorial.ordering_slots">
+ <title>ordering_slots</title>
+ <para>
+ This example extends the hello_world_multi_slot example slightly by
+ using slot groups to specify
+ the order slots should be invoked.
+ </para>
+ <para>
+ Download <ulink
url="boost:/libs/signals2/example/ordering_slots.cpp">ordering_slots.cpp</ulink>.
+ </para>
+ </section>
+ <section id="signals2.examples.tutorial.slot_arguments">
+ <title>slot_arguments</title>
+ <para>
+ The slot_arguments program shows how to pass arguments from a
signal invocation to slots.
+ </para>
+ <para>
+ Download <ulink
url="boost:/libs/signals2/example/slot_arguments.cpp">slot_arguments.cpp</ulink>.
+ </para>
+ </section>
+ <section id="signals2.examples.tutorial.signal_return_value">
+ <title>signal_return_value</title>
+ <para>
+ This example shows how to return a value from slots to the signal
invocation.
+ It uses the default <classname>optional_last_value</classname>
combiner.
+ </para>
+ <para>
+ Download <ulink
url="boost:/libs/signals2/example/signal_return_value.cpp">signal_return_value.cpp</ulink>.
+ </para>
+ </section>
+ <section id="signals2.examples.tutorial.custom_combiners">
+ <title>custom_combiners</title>
+ <para>
+ This example shows more returning of values from slots to the
signal invocation.
+ This time, custom combiners are defined and used.
+ </para>
+ <para>
+ Download <ulink
url="boost:/libs/signals2/example/custom_combiners.cpp">custom_combiners.cpp</ulink>.
+ </para>
+ </section>
+ <section id="signals2.examples.tutorial.disconnect_and_block">
+ <title>disconnect_and_block</title>
+ <para>
+ This example demonstrates various means of manually disconnecting
slots, as well as temporarily
+ blocking them via <classname>shared_connection_block</classname>.
+ </para>
+ <para>
+ Download <ulink
url="boost:/libs/signals2/example/disconnect_and_block.cpp">disconnect_and_block.cpp</ulink>.
+ </para>
+ </section>
+ <section id="signals2.examples.tutorial.passing_slots">
+ <title>passing_slots</title>
+ <para>
+ This example demonstrates the passing of slot functions to a
private signal
+ through a non-template interface.
+ </para>
+ <para>
+ Download <ulink
url="boost:/libs/signals2/example/passing_slots.cpp">passing_slots.cpp</ulink>.
+ </para>
+ </section>
+ <section id="signals2.examples.tutorial.extended_slot">
+ <title>extended_slot</title>
+ <para>
+ This example demonstrates connecting an extended slot to a
signal. An extended slot
+ accepts a reference to its invoking signal-slot connection as an
additional argument,
+ permitting the slot to temporarily block or permanently disconnect
itself.
+ </para>
+ <para>
+ Download <ulink
url="boost:/libs/signals2/example/extended_slot.cpp">extended_slot.cpp</ulink>.
+ </para>
+ </section>
+ </section>
+ <section id="signals2.examples.document-view">
+ <title>Document-View</title>
+ <section id="signals2.examples.document-view.doc_view">
+ <title>doc_view</title>
+ <para>
+ This is the document-view example program which is described in the
+ <link linkend="signals2.tutorial.document-view">tutorial</link>.
It shows
+ usage of a signal and slots to implement two different views of
+ a text document.
+ </para>
+ <para>
+ Download <ulink
url="boost:/libs/signals2/example/doc_view.cpp">doc_view.cpp</ulink>.
+ </para>
+ </section>
+ <section id="signals2.examples.document-view.doc_view_acm">
+ <title>doc_view_acm</title>
+ <para>
+ This program modifies the original doc_view.cpp example to employ
+ automatic connection management.
+ </para>
+ <para>
+ Download <ulink
url="boost:/libs/signals2/example/doc_view_acm.cpp">doc_view_acm.cpp</ulink>.
+ </para>
+ </section>
+ <section id="signals2.examples.document-view.doc_view_acm_deconstruct">
+ <title>doc_view_acm_deconstruct</title>
+ <para>
+ This program modifies the doc_view_acm.cpp example to use
postconstructors
+ and the <functionname>deconstruct()</functionname> factory
function.
+ </para>
+ <para>
+ Download <ulink
url="boost:/libs/signals2/example/doc_view_acm_deconstruct.cpp">doc_view_acm_deconstruct.cpp</ulink>.
+ </para>
+ </section>
+ </section>
+ <section id="signals2.examples.deconstruct">
+ <title>Postconstructors and Predestructors with
<code>deconstruct()</code></title>
+ <section id="signals2.examples.deconstruct.postconstructor_ex1">
+ <title>postconstructor_ex1</title>
+ <para>
+ This program is a basic example of how to define a class with a
postconstructor which
+ uses <functionname>deconstruct()</functionname> as its factory
function.
+ </para>
+ <para>
+ Download <ulink
url="boost:/libs/signals2/example/postconstructor_ex1.cpp">postconstructor_ex1</ulink>.
+ </para>
+ </section>
+ <section id="signals2.examples.deconstruct.postconstructor_ex2">
+ <title>postconstructor_ex2</title>
+ <para>
+ This program extends the postconstructor_ex1 example slightly, by
additionally passing arguments from
+ the <functionname>deconstruct()</functionname> call through to the
class' constructor
+ and postconstructor.
+ </para>
+ <para>
+ Download <ulink
url="boost:/libs/signals2/example/postconstructor_ex2.cpp">postconstructor_ex2</ulink>.
+ </para>
+ </section>
+ <section id="signals2.examples.deconstruct.predestructor_example">
+ <title>predestructor_example</title>
+ <para>
+ This program is a basic example of how to define a class with a
predestructor which
+ uses <functionname>deconstruct()</functionname> as its factory
function.
+ </para>
+ <para>
+ Download <ulink
url="boost:/libs/signals2/example/predestructor_example.cpp">predestructor_example</ulink>.
+ </para>
+ </section>
+ </section>
+</section>
Added: trunk/libs/signals2/doc/faq.xml
==============================================================================
--- (empty file)
+++ trunk/libs/signals2/doc/faq.xml Thu May 7 20:34:38 2009
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
+ "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd";>
+<!--
+Copyright Douglas Gregor 2001-2004
+Copyright Frank Mori Hess 2007-2009
+
+Distributed under the Boost Software License, Version 1.0. (See
accompanying
+file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+-->
+<section last-revision="$Date: 2007-06-12 14:01:23 -0400 (Tue, 12 Jun
2007) $" id="signals2.faq">
+ <title>Frequently Asked Questions</title>
+
+ <using-namespace name="boost"/>
+ <using-namespace name="boost::signals2"/>
+
+ <qandaset>
+ <qandaentry>
+ <question>
+ <para>Don't noncopyable signal semantics mean that a class
+ with a signal member will be noncopyable as well?</para>
+ </question>
+ <answer>
+ <para>No. The compiler will not be able to generate a copy
+ constructor or copy assignment operator for your class if it
+ has a signal as a member, but you are free to write your own
+ copy constructor and/or copy assignment operator. Just don't
+ try to copy the signal.</para>
+ </answer>
+ </qandaentry>
+ <qandaentry>
+ <question>
+ <para>Is Boost.Signals2 thread-safe?</para>
+ </question>
+ <answer>
+ <para>
+ Yes, as long as the Mutex template parameter is not set to
+ a fake mutex type like
<classname>boost::signals2::dummy_mutex</classname>.
+ Also, if your slots depend on objects which may be destroyed
concurrently
+ with signal invocation, you will need to use automatic
connection management.
+ That is, the objects will need to be owned by
+ <classname>shared_ptr</classname> and passed to the slot's
+ <methodname alt="slotN::track">track</methodname>() method
before the slot is connected.
+ The <classname>trackable</classname> scheme of automatic
connection management
+ is NOT thread-safe, and is only provided to ease porting of
single-threaded
+ code from Boost.Signals to Boost.Signals2.
+ </para>
+ <para>See the documentation section on <link
linkend="signals2.thread-safety">thread-safety</link>
+ for more information.
+ </para>
+ </answer>
+ </qandaentry>
+ </qandaset>
+</section>
Added: trunk/libs/signals2/doc/introduction.xml
==============================================================================
--- (empty file)
+++ trunk/libs/signals2/doc/introduction.xml Thu May 7 20:34:38 2009
@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
+ "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd";>
+<!--
+Copyright Douglas Gregor 2001-2004
+Copyright Frank Mori Hess 2007-2009
+
+Distributed under the Boost Software License, Version 1.0. (See
accompanying
+file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+-->
+<section last-revision="$Date: 2007-06-12 14:01:23 -0400 (Tue, 12 Jun
2007) $">
+ <title>Introduction</title>
+
+ <para>The Boost.Signals2 library is an implementation of a managed
+ signals and slots system. Signals represent callbacks with multiple
+ targets, and are also called publishers or events in similar
+ systems. Signals are connected to some set of slots, which are
+ callback receivers (also called event targets or subscribers), which
+ are called when the signal is "emitted."</para>
+
+ <para>Signals and slots are managed, in that signals and slots (or,
+ more properly, objects that occur as part of the slots) can track
+ connections and are capable of automatically disconnecting signal/slot
+ connections when either is destroyed. This enables the user to make
+ signal/slot connections without expending a great effort to manage the
+ lifetimes of those connections with regard to the lifetimes of all
+ objects involved.</para>
+
+ <para>When signals are connected to multiple slots, there is a
+ question regarding the relationship between the return values of the
+ slots and the return value of the signals. Boost.Signals2 allows the
+ user to specify the manner in which multiple return values are
+ combined.</para>
+
+ <section>
+ <title>Signals2</title>
+ <para>This documentation describes a thread-safe variant of the
+ original Boost.Signals library. There have been some changes to
+ the interface to support thread-safety, mostly with respect to
+ automatic connection management. This implementation was written by
+ Frank Mori Hess. Acknowledgements are also due to Timmo Stange, Peter
+ Dimov, and Gottlob Frege for ideas and feedback, and to Douglas Gregor
+ for the original version of Boost.Signals this effort was based on.
+ </para>
+ </section>
+</section>
Added: trunk/libs/signals2/doc/porting.xml
==============================================================================
--- (empty file)
+++ trunk/libs/signals2/doc/porting.xml Thu May 7 20:34:38 2009
@@ -0,0 +1,227 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
+ "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd";>
+<!--
+Copyright Frank Mori Hess 2007-2009
+
+Distributed under the Boost Software License, Version 1.0. (See
accompanying
+file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+-->
+<section last-revision="$Date: 2007-06-12 14:01:23 -0400 (Tue, 12 Jun
2007) $" id="signals2.porting">
+ <title>Porting from Boost.Signals to Boost.Signals2</title>
+
+ <using-namespace name="boost"/>
+ <using-namespace name="boost::signals2"/>
+
+ <para>The changes made to the Boost.Signals2 API compared to the
original Boost.Signals
+ library are summarized below. We also provide some notes on
+ dealing with each change while porting existing Boost.Signals code to
Boost.Signals2.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>The namespace <code>boost::signals</code> has been replaced by
<code>boost::signals2</code>
+ to avoid conflict with the original Boost.Signals implementation,
as well as the Qt "signals" macro.
+ All the Boost.Signals2 classes are inside the
<code>boost::signals2</code> namespace,
+ unlike the original Boost.Signals which has some classes in the
<code>boost</code>
+ namespace in addition to its own <code>boost::signals</code>
namespace.
+ </para>
+ <para>
+ The Boost.Signals2 header files are contained in the
+ <code>boost/signals2/</code> subdirectory instead of the
<code>boost/signals</code>
+ subdirectory used by the original Boost.Signals. Furthermore, all
the headers except
+ for the convenience header <code>boost/signals2.hpp</code> are
inside the
+ <code>boost/signals2/</code> subdirectory, unlike the original
Boost.Signals which
+ keeps a few headers in the parent <code>boost/</code> directory
+ in addition to its own <code>boost/signals/</code> subdirectory.
+ </para>
+ <para>
+ For example, the <code>signal</code> class is now
+ in the <code>boost::signals2</code> namespace instead of the
+ <code>boost</code> namespace,
+ and it's header file is now at
<code>boost/signals2/signal.hpp</code> instead of
+ <code>boost/signal.hpp</code>.
+ </para>
+ <para>
+ While porting, only trivial changes to <code>#include</code>
directives
+ and namespace qualifications should be required to deal with these
changes.
+ Furthermore, the new namespace and header locations for
Boost.Signals2
+ allow it to coexist in the same program with the original
Boost.Signals library,
+ and porting can be performed piecemeal.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Automatic connection management is now achieved through the use of
+ <classname>shared_ptr</classname>/<classname>weak_ptr</classname>
+ and <methodname alt="slotN::track">slot::track</methodname>(), as
described in the
+ <link
linkend="signals2.tutorial.connection-management">tutorial</link>.
+ However, the old (thread-unsafe) Boost.Signals scheme of automatic
connection management
+ is still supported via the
<classname>boost::signals2::trackable</classname> class.
+ </para>
+ <para>
+ If you do not intend to make your program multi-threaded, the
easiest porting path is to simply replace
+ your uses of <classname>boost::signals::trackable</classname> as a
base class with
+ <classname>boost::signals2::trackable</classname>. Boost.Signals2
uses the same
+ <functionname>boost::visit_each</functionname> mechanism to
discover
+ <classname>trackable</classname> objects
+ as used by the original Boost.Signals library.
+ </para>
+ </listitem>
+ <listitem>
+ <para>Support for postconstructors (and predestructors) on objects
managed by <classname>shared_ptr</classname>
+ has been added with
+ the <functionname>deconstruct</functionname> factory function.
+ This was motivated by the importance of
+ <code>shared_ptr</code> for the new connection tracking scheme,
and the
+ inability to obtain a <code>shared_ptr</code> to an object in its
constructor.
+ The use of <functionname>deconstruct</functionname> is described
in the
+ <link linkend="signals2.tutorial.deconstruct">tutorial</link>.
+ </para>
+ <para>
+ The use of <functionname>deconstruct</functionname> is in no way
required,
+ it is only provided in the hope
+ it may be useful. You may wish to use it if you are porting code
where
+ a class creates connections to its own member functions in its
constructor,
+ and you also
+ wish to use the new automatic connection management scheme. You
could then
+ move the connection creation from the constructor to to the an
+ <code>adl_postconstruct</code> function, where
+ a reference to the owning <classname>shared_ptr</classname> is
available for
+ passing to <methodname alt="slotN::track">slot::track</methodname>.
+ The <functionname>deconstruct</functionname> function would be
used create objects
+ of the class and run their associated
<code>adl_postconstruct</code> function.
+ You can enforce use of <functionname>deconstruct</functionname> by
+ making the class' constructors private and declaring
+ <classname>deconstruct_access</classname> a friend.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <classname>slot</classname> class takes a new
<code>Signature</code> template parameter,
+ is useable as a function object, and has some additional features
to support the
+ new Boost.Signals2 automatic connection management scheme.
+ </para>
+ <para>
+ The changes to the slot class should generally not cause any
porting difficulties,
+ especially if you are using the
<classname>boost::signals2::trackable</classname>
+ compatibility class mentioned above. If you are converting your
code over to
+ use the new automatic connection management scheme, you will need
to
+ employ some of the new slot features, as described in the
+ <link
==============================================================================
Diff truncated at 200k characters
Other related posts:
- » [boost-doc-zh commit] r245 - 1.39.0新增 signals2 库的E文文 - codesite-noreply
