[DEV] add v1.76.0

This commit is contained in:
2021-10-05 21:37:46 +02:00
parent a97e9ae7d4
commit d0115b733d
45133 changed files with 4744437 additions and 1026325 deletions

View File

@@ -0,0 +1,347 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Signals2 API Changes</title>
<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
<link rel="up" href="../signals2.html" title="Chapter 36. 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/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../signals2.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="tests.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="signals2.api_changes"></a>Signals2 API Changes</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="api_changes.html#signals2.porting">Porting from Boost.Signals to Boost.Signals2</a></span></dt>
<dt><span class="section"><a href="api_changes.html#signals2.api_history">Signals2 API Development</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="signals2.porting"></a>Porting from Boost.Signals to Boost.Signals2</h3></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 class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<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 class="listitem">
<p>
Automatic connection management is now achieved through the use of
<code class="computeroutput"><a class="link" href="../boost/shared_ptr.html" title="Class template shared_ptr">shared_ptr</a></code>/<code class="computeroutput">weak_ptr</code>
and <code class="computeroutput"><a class="link" href="../boost/signals2/slot.html#id-1_3_37_6_12_5_1_1_17_1-bb">signals2::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">boost::signals::trackable</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">boost::visit_each</code> mechanism to discover
<code class="computeroutput">trackable</code> objects
as used by the original Boost.Signals library.
</p>
</li>
<li class="listitem">
<p>Support for postconstructors (and predestructors) on objects managed by <code class="computeroutput"><a class="link" href="../boost/shared_ptr.html" title="Class template shared_ptr">shared_ptr</a></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"><a class="link" href="../boost/shared_ptr.html" title="Class template shared_ptr">shared_ptr</a></code> is available for
passing to <code class="computeroutput"><a class="link" href="../boost/signals2/slot.html#id-1_3_37_6_12_5_1_1_17_1-bb">signals2::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 class="listitem">
<p>
The <code class="computeroutput"><a class="link" href="../boost/signals2/slot.html" title="Class template slot">signals2::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 class="listitem">
<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">last_value</code>
as the default combiner for signals.
</p>
<p>
The <code class="computeroutput"><a class="link" href="../boost/signals2/last_value.html" title="Class template last_value">signals2::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/signals2/last_value.html" title="Class template last_value">signals2::last_value</a></code>.
</p>
</li>
<li class="listitem">
<p>
The <code class="computeroutput"><a class="link" href="../boost/signals2/signal.html" title="Class template signal">signals2::signal</a></code> class has an additional typedef
<code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#boost.signals2.signal.extended_slot_type">signals2::signal::extended_slot_type</a></code>
and new <code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#id-1_3_37_6_9_3_1_2_24_2-bb">signals2::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">signals2::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">signals2::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/signal.html#id-1_3_37_6_9_3_1_2_24_2-bb">signals2::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 class="listitem">
<p>
The <code class="computeroutput"><a class="link" href="../boost/signals2/signal.html" title="Class template signal">signals2::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 class="listitem">
<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/signals2/signal.html#id-1_3_37_6_9_3_1_2_26_1-bb">signals2::signal::combiner</a></code>
(which now returns the combiner by value) and <code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#id-1_3_37_6_9_3_1_2_26_2-bb">signals2::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/signals2/signal.html#id-1_3_37_6_9_3_1_2_26_1-bb">signals2::signal::combiner</a></code>
and <code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#id-1_3_37_6_9_3_1_2_26_2-bb">signals2::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 class="listitem">
<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>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="signals2.api_history"></a>Signals2 API Development</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="api_changes.html#signals2.api_history.1-56">Version 1.56</a></span></dt>
<dt><span class="section"><a href="api_changes.html#signals2.api_history.1-45">Version 1.45</a></span></dt>
<dt><span class="section"><a href="api_changes.html#signals2.api_history.1-40">Version 1.40</a></span></dt>
<dt><span class="section"><a href="api_changes.html#signals2.api_history.1-39">Version 1.39</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="signals2.api_history.1-56"></a>Version 1.56</h4></div></div></div>
<p>
Version 1.56 modified the behavior of the signal destructor, in that it no longer
explicitly calls disconnect_all_slots. Any signal invocations running
concurrently with the signal destructor should now complete normally, rather
than skipping all remaining slots. Once all concurrent signal invocations
complete, all connections to the deleted signal will still ultimately
be disconnected. This change brings Boost.Signals2
behavior closer to the behavior of the original Boost.Signals library.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="signals2.api_history.1-45"></a>Version 1.45</h4></div></div></div>
<p>
Version 1.45 added <code class="computeroutput"><a class="link" href="../boost/signals2/slot.html#id-1_3_37_6_12_5_1_1_17_2-bb">slot::track_foreign</a></code>(). This method allows tracking
of objects owned by <code class="computeroutput">shared_ptr</code> classes other than <code class="computeroutput"><a class="link" href="../boost/shared_ptr.html" title="Class template shared_ptr">boost::shared_ptr</a></code>,
for example <code class="computeroutput">std::shared_ptr</code>.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="signals2.api_history.1-40"></a>Version 1.40</h4></div></div></div>
<p>
Version 1.40 adds a few new features to 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 to make it more flexible:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>
<code class="computeroutput"><a class="link" href="../boost/signals2/shared_connection_block.html" title="Class shared_connection_block">shared_connection_block</a></code> is now default constructible.
</p></li>
<li class="listitem"><p>
A <code class="computeroutput"><a class="link" href="../boost/signals2/shared_connection_block.html" title="Class shared_connection_block">shared_connection_block</a></code> may now be constructed without
immediately blocking its connection.
</p></li>
<li class="listitem"><p>
The <code class="computeroutput"><a class="link" href="../boost/signals2/shared_connection_block.html#id-1_3_37_6_8_4_1_1_8_1-bb">shared_connection_block::connection</a></code>() query has been
added, to provide access to the <code class="computeroutput">shared_connection_block</code>s associated
connection.
</p></li>
</ul></div>
<p>
</p>
<p>Version 1.40 also introduces a variadic templates implementation of
Signals2, which is used when Boost detects compiler support for variadic templates
(variadic templates are a new feature of C++11).
This change is mostly transparent to the user, however it does introduce a few
visible tweaks to the interface as described in the following.
</p>
<p>
The following library features are
deprecated, and are only available if your compiler is NOT using
variadic templates (i.e. BOOST_NO_CXX11_VARIADIC_TEMPLATES is defined
by Boost.Config).
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>
The "portable syntax" signal and slot classes, i.e. signals2::signal0, signal1, etc.
</p></li>
<li class="listitem"><p>
The arg1_type, arg2_type, etc. member typedefs in the <code class="computeroutput"><a class="link" href="../boost/signals2/signal.html" title="Class template signal">signals2::signal</a></code> and
<code class="computeroutput"><a class="link" href="../boost/signals2/slot.html" title="Class template slot">signals2::slot</a></code> classes. They are replaced by the
template member classes <code class="computeroutput"><a class="link" href="../boost/signals2/signal/arg.html" title="Class template arg">signals2::signal::arg</a></code> and
<code class="computeroutput"><a class="link" href="../boost/signals2/slot/arg.html" title="Class template arg">signals2::slot::arg</a></code>.
</p></li>
</ul></div>
<p>
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="signals2.api_history.1-39"></a>Version 1.39</h4></div></div></div>
<p>Version 1.39 is the first release of Boost to include the Signals2 library.</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="rationale.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../signals2.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="tests.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,250 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Example programs</title>
<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
<link rel="up" href="../signals2.html" title="Chapter 36. 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/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../signals2.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="reference.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<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 class="toc">
<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 <code class="computeroutput">deconstruct()</code></a></span></dt>
</dl></div>
<div class="section">
<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 class="toc">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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 class="toc">
<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">
<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">
<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">
<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">
<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 class="toc">
<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">
<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">
<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">
<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/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../signals2.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="reference.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

100
doc/html/signals2/faq.html Normal file
View File

@@ -0,0 +1,100 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Frequently Asked Questions</title>
<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
<link rel="up" href="../signals2.html" title="Chapter 36. 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/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../signals2.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="rationale.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<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">
<a name="id-1.3.37.8.2"></a><dl>
<dt>1. <a href="faq.html#id-1.3.37.8.2.1">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#id-1.3.37.8.2.2">Is Boost.Signals2 thread-safe?</a>
</dt>
</dl>
<table border="0" style="width: 100%;">
<colgroup>
<col align="left" width="1%">
<col>
</colgroup>
<tbody>
<tr class="question">
<td align="left" valign="top">
<a name="id-1.3.37.8.2.1"></a><a name="id-1.3.37.8.2.1.1"></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="id-1.3.37.8.2.2"></a><a name="id-1.3.37.8.2.2.1"></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"><a class="link" href="../boost/shared_ptr.html" title="Class template shared_ptr">shared_ptr</a></code> and passed to the slot's
<code class="computeroutput"><a class="link" href="../boost/signals2/slot.html#id-1_3_37_6_12_5_1_1_17_1-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">signals2::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/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../signals2.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="rationale.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,400 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Design Rationale</title>
<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
<link rel="up" href="../signals2.html" title="Chapter 36. Boost.Signals2">
<link rel="prev" href="faq.html" title="Frequently Asked Questions">
<link rel="next" href="api_changes.html" title="Signals2 API Changes">
</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/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../signals2.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="api_changes.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<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 class="toc">
<dt><span class="section"><a href="rationale.html#id-1.3.37.9.2">User-level Connection Management</a></span></dt>
<dt><span class="section"><a href="rationale.html#id-1.3.37.9.3">Automatic Connection Management</a></span></dt>
<dt><span class="section"><a href="rationale.html#id-1.3.37.9.4"><code class="computeroutput">optional_last_value</code> as the Default Combiner</a></span></dt>
<dt><span class="section"><a href="rationale.html#id-1.3.37.9.5">Combiner Interface</a></span></dt>
<dt><span class="section"><a href="rationale.html#id-1.3.37.9.6">Connection Interfaces: += operator</a></span></dt>
<dt><span class="section"><a href="rationale.html#id-1.3.37.9.7">Signals2 Mutex Classes</a></span></dt>
<dt><span class="section"><a href="rationale.html#id-1.3.37.9.8">Comparison with other Signal/Slot implementations</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="id-1.3.37.9.2"></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">signals2::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">signals2::scoped_connection</a></code>).
In addition, two other interfaces are supported by the
<code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#id-1_3_37_6_9_3_1_2_24_3-bb">signal::disconnect</a></code> overloaded method:</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><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/signal.html#id-1_3_37_6_9_3_1_2_24_1-bb">connect</a>(typeof(sig)::slot_type(slot_func))</code> is
performed via
<code class="computeroutput">sig.<a class="link" href="../boost/signals2/signal.html#id-1_3_37_6_9_3_1_2_24_3-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 class="listitem">
<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 class="itemizedlist" style="list-style-type: circle; ">
<li class="listitem"><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 class="listitem"><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/signals2/signal.html#id-1_3_37_6_9_3_1_2_24_3-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">
<div class="titlepage"><div><div><h3 class="title">
<a name="id-1.3.37.9.3"></a>Automatic Connection Management</h3></div></div></div>
<p>Automatic connection management in Signals2
depends on the use of <code class="computeroutput"><a class="link" href="../boost/shared_ptr.html" title="Class template shared_ptr">boost::shared_ptr</a></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">boost::signals::trackable</code> class.
The library would be
notified of an object's destruction by the
<code class="computeroutput">boost::signals::trackable</code> destructor.
</p>
<p>Unfortunately, the <code class="computeroutput">boost::signals::trackable</code>
scheme cannot be made thread safe due
to destructor ordering. The destructor of an class derived from
<code class="computeroutput">boost::signals::trackable</code> will always be
called before the destructor of the base <code class="computeroutput">boost::signals::trackable</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"><a class="link" href="../boost/shared_ptr.html" title="Class template shared_ptr">shared_ptr</a></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"><a class="link" href="../boost/shared_ptr.html" title="Class template shared_ptr">shared_ptr</a></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"><a class="link" href="../boost/shared_ptr.html" title="Class template shared_ptr">shared_ptr</a></code>/<code class="computeroutput">weak_ptr</code> scheme. The old
<code class="computeroutput">boost::signals::trackable</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">
<div class="titlepage"><div><div><h3 class="title">
<a name="id-1.3.37.9.4"></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&lt;void&gt;</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">
<div class="titlepage"><div><div><h3 class="title">
<a name="id-1.3.37.9.5"></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 &amp; slots
libraries, the combiners are unfortunately not reusable (either in
other signals &amp; 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&lt;typename InputIterator&gt;
result_type operator()(InputIterator first,
InputIterator last)
{
if (first == last)
throw std::runtime_error("Empty!");
int max_value = *first++;
while(first != last &amp;&amp; *first &lt;= 100) {
if (*first &gt; 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 &gt; 100)
return false;
if (!got_first) {
got_first = true;
max_value = result;
return true;
}
if (result &gt; 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 &amp; 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">
<div class="titlepage"><div><div><h3 class="title">
<a name="id-1.3.37.9.6"></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/signal.html#id-1_3_37_6_9_3_1_2_24_1-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 &amp; slots implementations). There
are several reasons as to why this syntax has been
rejected:</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><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 class="listitem"><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">signals2::connection</a></code> for the
newly-created signal/slot connection?</p></li>
<li class="listitem">
<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">
<div class="titlepage"><div><div><h3 class="title">
<a name="id-1.3.37.9.7"></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. 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">
<div class="titlepage"><div><div><h3 class="title">
<a name="id-1.3.37.9.8"></a>Comparison with other Signal/Slot implementations</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="rationale.html#id-1.3.37.9.8.2">libsigc++</a></span></dt>
<dt><span class="section"><a href="rationale.html#id-1.3.37.9.8.3">.NET delegates</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="id-1.3.37.9.8.2"></a>libsigc++</h4></div></div></div>
<p> <a href="http://libsigc.sourceforge.net" target="_top">libsigc++</a> is a C++
signals &amp; 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 class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><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 class="listitem"><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">
<div class="titlepage"><div><div><h4 class="title">
<a name="id-1.3.37.9.8.3"></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 class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>Require exact type matches between a delegate and what
it is calling.</p></li>
<li class="listitem"><p>Only return the result of the last target called, with no option for customization.</p></li>
<li class="listitem"><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/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../signals2.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="api_changes.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,232 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Reference</title>
<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
<link rel="up" href="../signals2.html" title="Chapter 36. 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/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../signals2.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../boost/signals2/connection.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<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 class="toc">
<dt><span class="section"><a href="reference.html#header.boost.signals2_hpp">Header &lt;boost/signals2.hpp&gt;</a></span></dt>
<dt><span class="section"><a href="reference.html#header.boost.signals2.connection_hpp">Header &lt;boost/signals2/connection.hpp&gt;</a></span></dt>
<dt><span class="section"><a href="reference.html#header.boost.signals2.deconstruct_hpp">Header &lt;boost/signals2/deconstruct.hpp&gt;</a></span></dt>
<dt><span class="section"><a href="reference.html#header.boost.signals2.dummy_mutex_hpp">Header &lt;boost/signals2/dummy_mutex.hpp&gt;</a></span></dt>
<dt><span class="section"><a href="reference.html#header.boost.signals2.last_value_hpp">Header &lt;boost/signals2/last_value.hpp&gt;</a></span></dt>
<dt><span class="section"><a href="reference.html#header.boost.signals2.mutex_hpp">Header &lt;boost/signals2/mutex.hpp&gt;</a></span></dt>
<dt><span class="section"><a href="reference.html#header.boost.signals2.optional_last_value_hpp">Header &lt;boost/signals2/optional_last_value.hpp&gt;</a></span></dt>
<dt><span class="section"><a href="reference.html#header.boost.signals2.shared_connection_block_hpp">Header &lt;boost/signals2/shared_connection_block.hpp&gt;</a></span></dt>
<dt><span class="section"><a href="reference.html#header.boost.signals2.signal_hpp">Header &lt;boost/signals2/signal.hpp&gt;</a></span></dt>
<dt><span class="section"><a href="reference.html#header.boost.signals2.signal_base_hpp">Header &lt;boost/signals2/signal_base.hpp&gt;</a></span></dt>
<dt><span class="section"><a href="reference.html#header.boost.signals2.signal_type_hpp">Header &lt;boost/signals2/signal_type.hpp&gt;</a></span></dt>
<dt><span class="section"><a href="reference.html#header.boost.signals2.slot_hpp">Header &lt;boost/signals2/slot.hpp&gt;</a></span></dt>
<dt><span class="section"><a href="reference.html#header.boost.signals2.slot_base_hpp">Header &lt;boost/signals2/slot_base.hpp&gt;</a></span></dt>
<dt><span class="section"><a href="reference.html#header.boost.signals2.trackable_hpp">Header &lt;boost/signals2/trackable.hpp&gt;</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="header.boost.signals2_hpp"></a>Header &lt;<a href="../../../boost/signals2.hpp" target="_top">boost/signals2.hpp</a>&gt;</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">
<div class="titlepage"><div><div><h3 class="title">
<a name="header.boost.signals2.connection_hpp"></a>Header &lt;<a href="../../../boost/signals2/connection.hpp" target="_top">boost/signals2/connection.hpp</a>&gt;</h3></div></div></div>
<pre class="synopsis"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span>
<span class="keyword">namespace</span> <span class="identifier">signals2</span> <span class="special">{</span>
<span class="keyword">class</span> <a class="link" href="../boost/signals2/connection.html" title="Class connection">connection</a><span class="special">;</span>
<span class="keyword">void</span> <a class="link" href="../boost/signals2/connection.html#boost.signals2.connection.swap"><span class="identifier">swap</span></a><span class="special">(</span><a class="link" href="../boost/signals2/connection.html" title="Class connection">connection</a><span class="special">&amp;</span><span class="special">,</span> <a class="link" href="../boost/signals2/connection.html" title="Class connection">connection</a><span class="special">&amp;</span><span class="special">)</span><span class="special">;</span>
<span class="keyword">class</span> <a class="link" href="../boost/signals2/scoped_connection.html" title="Class scoped_connection">scoped_connection</a><span class="special">;</span>
<span class="special">}</span>
<span class="special">}</span></pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="header.boost.signals2.deconstruct_hpp"></a>Header &lt;<a href="../../../boost/signals2/deconstruct.hpp" target="_top">boost/signals2/deconstruct.hpp</a>&gt;</h3></div></div></div>
<pre class="synopsis"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span>
<span class="keyword">namespace</span> <span class="identifier">signals2</span> <span class="special">{</span>
<span class="keyword">class</span> <a class="link" href="../boost/signals2/deconstruct_access.html" title="Class deconstruct_access">deconstruct_access</a><span class="special">;</span>
<span class="keyword">class</span> <a class="link" href="../boost/signals2/postconstructor_invoker.html" title="Class postconstructor_invoker">postconstructor_invoker</a><span class="special">;</span>
<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> T<span class="special">&gt;</span> <a class="link" href="../boost/signals2/postconstructor_invoker.html" title="Class postconstructor_invoker">postconstructor_invoker</a><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <a class="link" href="../boost/signals2/deconstruct.html" title="Function deconstruct"><span class="identifier">deconstruct</span></a><span class="special">(</span><span class="special">)</span><span class="special">;</span>
<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> T<span class="special">,</span> <span class="keyword">typename</span> A1<span class="special">&gt;</span>
<a class="link" href="../boost/signals2/postconstructor_invoker.html" title="Class postconstructor_invoker">postconstructor_invoker</a><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <a class="link" href="../boost/signals2/deconstruct.html" title="Function deconstruct"><span class="identifier">deconstruct</span></a><span class="special">(</span><span class="keyword">const</span> <span class="identifier">A1</span> <span class="special">&amp;</span><span class="special">)</span><span class="special">;</span>
<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> T<span class="special">,</span> <span class="keyword">typename</span> A1<span class="special">,</span> <span class="keyword">typename</span> A2<span class="special">&gt;</span>
<a class="link" href="../boost/signals2/postconstructor_invoker.html" title="Class postconstructor_invoker">postconstructor_invoker</a><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <a class="link" href="../boost/signals2/deconstruct.html" title="Function deconstruct"><span class="identifier">deconstruct</span></a><span class="special">(</span><span class="keyword">const</span> <span class="identifier">A1</span> <span class="special">&amp;</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">A2</span> <span class="special">&amp;</span><span class="special">)</span><span class="special">;</span>
<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> T<span class="special">,</span> <span class="keyword">typename</span> A1<span class="special">,</span> <span class="keyword">typename</span> A2, ...<span class="special">,</span> <span class="keyword">typename</span> AN<span class="special">&gt;</span>
<a class="link" href="../boost/signals2/postconstructor_invoker.html" title="Class postconstructor_invoker">postconstructor_invoker</a><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span>
<a class="link" href="../boost/signals2/deconstruct.html" title="Function deconstruct"><span class="identifier">deconstruct</span></a><span class="special">(</span><span class="keyword">const</span> <span class="identifier">A1</span> <span class="special">&amp;</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">A2</span> <span class="special">&amp;</span><span class="special">,</span> <span class="special">...</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">AN</span> <span class="special">&amp;</span><span class="special">)</span><span class="special">;</span>
<span class="special">}</span>
<span class="special">}</span></pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="header.boost.signals2.dummy_mutex_hpp"></a>Header &lt;<a href="../../../boost/signals2/dummy_mutex.hpp" target="_top">boost/signals2/dummy_mutex.hpp</a>&gt;</h3></div></div></div>
<pre class="synopsis"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span>
<span class="keyword">namespace</span> <span class="identifier">signals2</span> <span class="special">{</span>
<span class="keyword">class</span> <a class="link" href="../boost/signals2/dummy_mutex.html" title="Class dummy_mutex">dummy_mutex</a><span class="special">;</span>
<span class="special">}</span>
<span class="special">}</span></pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="header.boost.signals2.last_value_hpp"></a>Header &lt;<a href="../../../boost/signals2/last_value.hpp" target="_top">boost/signals2/last_value.hpp</a>&gt;</h3></div></div></div>
<pre class="synopsis"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span>
<span class="keyword">namespace</span> <span class="identifier">signals2</span> <span class="special">{</span>
<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> T<span class="special">&gt;</span> <span class="keyword">class</span> <a class="link" href="../boost/signals2/last_value.html" title="Class template last_value">last_value</a><span class="special">;</span>
<span class="keyword">template</span><span class="special">&lt;</span><span class="special">&gt;</span> <span class="keyword">class</span> <a class="link" href="../boost/signals2/last_valu_1_3_37_6_5_1_1_2.html" title="Class last_value&lt;void&gt;">last_value</a><span class="special">&lt;</span><span class="keyword">void</span><span class="special">&gt;</span><span class="special">;</span>
<span class="keyword">class</span> <a class="link" href="../boost/signals2/no_slots_error.html" title="Class no_slots_error">no_slots_error</a><span class="special">;</span>
<span class="special">}</span>
<span class="special">}</span></pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="header.boost.signals2.mutex_hpp"></a>Header &lt;<a href="../../../boost/signals2/mutex.hpp" target="_top">boost/signals2/mutex.hpp</a>&gt;</h3></div></div></div>
<pre class="synopsis"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span>
<span class="keyword">namespace</span> <span class="identifier">signals2</span> <span class="special">{</span>
<span class="keyword">class</span> <a class="link" href="../boost/signals2/mutex.html" title="Class mutex">mutex</a><span class="special">;</span>
<span class="special">}</span>
<span class="special">}</span></pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="header.boost.signals2.optional_last_value_hpp"></a>Header &lt;<a href="../../../boost/signals2/optional_last_value.hpp" target="_top">boost/signals2/optional_last_value.hpp</a>&gt;</h3></div></div></div>
<pre class="synopsis"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span>
<span class="keyword">namespace</span> <span class="identifier">signals2</span> <span class="special">{</span>
<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> T<span class="special">&gt;</span> <span class="keyword">class</span> <a class="link" href="../boost/signals2/optional_last_value.html" title="Class template optional_last_value">optional_last_value</a><span class="special">;</span>
<span class="keyword">template</span><span class="special">&lt;</span><span class="special">&gt;</span> <span class="keyword">class</span> <a class="link" href="../boost/signals2/optional__1_3_37_6_7_1_1_2.html" title="Class optional_last_value&lt;void&gt;">optional_last_value</a><span class="special">&lt;</span><span class="keyword">void</span><span class="special">&gt;</span><span class="special">;</span>
<span class="special">}</span>
<span class="special">}</span></pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="header.boost.signals2.shared_connection_block_hpp"></a>Header &lt;<a href="../../../boost/signals2/shared_connection_block.hpp" target="_top">boost/signals2/shared_connection_block.hpp</a>&gt;</h3></div></div></div>
<pre class="synopsis"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span>
<span class="keyword">namespace</span> <span class="identifier">signals2</span> <span class="special">{</span>
<span class="keyword">class</span> <a class="link" href="../boost/signals2/shared_connection_block.html" title="Class shared_connection_block">shared_connection_block</a><span class="special">;</span>
<span class="special">}</span>
<span class="special">}</span></pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="header.boost.signals2.signal_hpp"></a>Header &lt;<a href="../../../boost/signals2/signal.hpp" target="_top">boost/signals2/signal.hpp</a>&gt;</h3></div></div></div>
<pre class="synopsis"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span>
<span class="keyword">namespace</span> <span class="identifier">signals2</span> <span class="special">{</span>
<span class="keyword">enum</span> <a name="boost.signals2.connect_position"></a>connect_position <span class="special">{</span> at_front, at_back <span class="special">}</span><span class="special">;</span>
<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> Signature<span class="special">,</span>
<span class="keyword">typename</span> Combiner <span class="special">=</span> <a class="link" href="../boost/signals2/optional_last_value.html" title="Class template optional_last_value">boost::signals2::optional_last_value</a><span class="special">&lt;</span><span class="identifier">R</span><span class="special">&gt;</span><span class="special">,</span>
<span class="keyword">typename</span> Group <span class="special">=</span> <span class="keyword">int</span><span class="special">,</span> <span class="keyword">typename</span> GroupCompare <span class="special">=</span> std::less<span class="special">&lt;</span><span class="identifier">Group</span><span class="special">&gt;</span><span class="special">,</span>
<span class="keyword">typename</span> SlotFunction <span class="special">=</span> <a class="link" href="../boost/function.html" title="Class template function">boost::function</a><span class="special">&lt;</span><span class="identifier">Signature</span><span class="special">&gt;</span><span class="special">,</span>
<span class="keyword">typename</span> ExtendedSlotFunction <span class="special">=</span> <a class="link" href="../boost/function.html" title="Class template function">boost::function</a><span class="special">&lt;</span><span class="identifier">R</span> <span class="special">(</span><span class="keyword">const</span> <a class="link" href="../boost/signals2/connection.html" title="Class connection">connection</a> <span class="special">&amp;</span><span class="special">,</span> <span class="identifier">T1</span><span class="special">,</span> <span class="identifier">T2</span><span class="special">,</span> <span class="special">...</span><span class="special">,</span> <span class="identifier">TN</span><span class="special">)</span><span class="special">&gt;</span><span class="special">,</span>
<span class="keyword">typename</span> Mutex <span class="special">=</span> <a class="link" href="../boost/signals2/mutex.html" title="Class mutex">boost::signals2::mutex</a><span class="special">&gt;</span>
<span class="keyword">class</span> <a class="link" href="../boost/signals2/signal.html" title="Class template signal">signal</a><span class="special">;</span>
<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> Signature<span class="special">,</span> <span class="keyword">typename</span> Combiner<span class="special">,</span> <span class="keyword">typename</span> Group<span class="special">,</span>
<span class="keyword">typename</span> GroupCompare<span class="special">,</span> <span class="keyword">typename</span> SlotFunction<span class="special">,</span>
<span class="keyword">typename</span> ExtendedSlotFunction<span class="special">,</span> <span class="keyword">typename</span> Mutex<span class="special">&gt;</span>
<span class="keyword">void</span> <a class="link" href="../boost/signals2/signal.html#boost.signals2.signal.swap"><span class="identifier">swap</span></a><span class="special">(</span><a class="link" href="../boost/signals2/signal.html" title="Class template signal">signal</a><span class="special">&lt;</span><span class="identifier">Signature</span><span class="special">,</span> <span class="identifier">Combiner</span><span class="special">,</span> <span class="identifier">Group</span><span class="special">,</span> <span class="identifier">GroupCompare</span><span class="special">,</span> <span class="identifier">SlotFunction</span><span class="special">,</span> <span class="identifier">ExtendedSlotFunction</span><span class="special">,</span> <span class="identifier">Mutex</span><span class="special">&gt;</span><span class="special">&amp;</span><span class="special">,</span>
<a class="link" href="../boost/signals2/signal.html" title="Class template signal">signal</a><span class="special">&lt;</span><span class="identifier">Signature</span><span class="special">,</span> <span class="identifier">Combiner</span><span class="special">,</span> <span class="identifier">Group</span><span class="special">,</span> <span class="identifier">GroupCompare</span><span class="special">,</span> <span class="identifier">SlotFunction</span><span class="special">,</span> <span class="identifier">ExtendedSlotFunction</span><span class="special">,</span> <span class="identifier">Mutex</span><span class="special">&gt;</span><span class="special">&amp;</span><span class="special">)</span><span class="special">;</span>
<span class="special">}</span>
<span class="special">}</span></pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="header.boost.signals2.signal_base_hpp"></a>Header &lt;<a href="../../../boost/signals2/signal_base.hpp" target="_top">boost/signals2/signal_base.hpp</a>&gt;</h3></div></div></div>
<pre class="synopsis"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span>
<span class="keyword">namespace</span> <span class="identifier">signals2</span> <span class="special">{</span>
<span class="keyword">class</span> <a class="link" href="../boost/signals2/signal_base.html" title="Class signal_base">signal_base</a><span class="special">;</span>
<span class="special">}</span>
<span class="special">}</span></pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="header.boost.signals2.signal_type_hpp"></a>Header &lt;<a href="../../../boost/signals2/signal_type.hpp" target="_top">boost/signals2/signal_type.hpp</a>&gt;</h3></div></div></div>
<pre class="synopsis"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span>
<span class="keyword">namespace</span> <span class="identifier">signals2</span> <span class="special">{</span>
<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> A0<span class="special">,</span> <span class="keyword">typename</span> A1 <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">parameter</span><span class="special">::</span><span class="identifier">void_</span><span class="special">,</span>
<span class="keyword">typename</span> A2 <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">parameter</span><span class="special">::</span><span class="identifier">void_</span><span class="special">,</span>
<span class="keyword">typename</span> A3 <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">parameter</span><span class="special">::</span><span class="identifier">void_</span><span class="special">,</span>
<span class="keyword">typename</span> A4 <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">parameter</span><span class="special">::</span><span class="identifier">void_</span><span class="special">,</span>
<span class="keyword">typename</span> A5 <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">parameter</span><span class="special">::</span><span class="identifier">void_</span><span class="special">,</span>
<span class="keyword">typename</span> A6 <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">parameter</span><span class="special">::</span><span class="identifier">void_</span><span class="special">&gt;</span>
<span class="keyword">class</span> <a class="link" href="../boost/signals2/signal_type.html" title="Class template signal_type">signal_type</a><span class="special">;</span>
<span class="keyword">namespace</span> <span class="identifier">keywords</span> <span class="special">{</span>
<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> Signature<span class="special">&gt;</span> <span class="keyword">class</span> <a class="link" href="../boost/signals2/keywords/signature_type.html" title="Class template signature_type">signature_type</a><span class="special">;</span>
<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> Combiner<span class="special">&gt;</span> <span class="keyword">class</span> <a class="link" href="../boost/signals2/keywords/combiner_type.html" title="Class template combiner_type">combiner_type</a><span class="special">;</span>
<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> Group<span class="special">&gt;</span> <span class="keyword">class</span> <a class="link" href="../boost/signals2/keywords/group_type.html" title="Class template group_type">group_type</a><span class="special">;</span>
<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> GroupCompare<span class="special">&gt;</span> <span class="keyword">class</span> <a class="link" href="../boost/signals2/keywords/group_compare_type.html" title="Class template group_compare_type">group_compare_type</a><span class="special">;</span>
<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> SlotFunction<span class="special">&gt;</span> <span class="keyword">class</span> <a class="link" href="../boost/signals2/keywords/slot_function_type.html" title="Class template slot_function_type">slot_function_type</a><span class="special">;</span>
<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> ExtendedSlotFunction<span class="special">&gt;</span> <span class="keyword">class</span> <a class="link" href="../boost/signals2/keywords/extend_1_3_37_6_11_1_1_1_6.html" title="Class template extended_slot_function_type">extended_slot_function_type</a><span class="special">;</span>
<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> Mutex<span class="special">&gt;</span> <span class="keyword">class</span> <a class="link" href="../boost/signals2/keywords/mutex_type.html" title="Class template mutex_type">mutex_type</a><span class="special">;</span>
<span class="special">}</span>
<span class="special">}</span>
<span class="special">}</span></pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="header.boost.signals2.slot_hpp"></a>Header &lt;<a href="../../../boost/signals2/slot.hpp" target="_top">boost/signals2/slot.hpp</a>&gt;</h3></div></div></div>
<pre class="synopsis"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span>
<span class="keyword">namespace</span> <span class="identifier">signals2</span> <span class="special">{</span>
<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> Signature<span class="special">,</span>
<span class="keyword">typename</span> SlotFunction <span class="special">=</span> <a class="link" href="../boost/function.html" title="Class template function">boost::function</a><span class="special">&lt;</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T1</span><span class="special">,</span> <span class="identifier">T2</span><span class="special">,</span> <span class="special">...</span><span class="special">,</span> <span class="identifier">TN</span><span class="special">)</span><span class="special">&gt;</span> <span class="special">&gt;</span>
<span class="keyword">class</span> <a class="link" href="../boost/signals2/slot.html" title="Class template slot">slot</a><span class="special">;</span>
<span class="special">}</span>
<span class="special">}</span></pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="header.boost.signals2.slot_base_hpp"></a>Header &lt;<a href="../../../boost/signals2/slot_base.hpp" target="_top">boost/signals2/slot_base.hpp</a>&gt;</h3></div></div></div>
<pre class="synopsis"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span>
<span class="keyword">namespace</span> <span class="identifier">signals2</span> <span class="special">{</span>
<span class="keyword">class</span> <a class="link" href="../boost/signals2/slot_base.html" title="Class slot_base">slot_base</a><span class="special">;</span>
<span class="keyword">class</span> <a class="link" href="../boost/signals2/expired_slot.html" title="Class expired_slot">expired_slot</a><span class="special">;</span>
<span class="special">}</span>
<span class="special">}</span></pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="header.boost.signals2.trackable_hpp"></a>Header &lt;<a href="../../../boost/signals2/trackable.hpp" target="_top">boost/signals2/trackable.hpp</a>&gt;</h3></div></div></div>
<pre class="synopsis"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span>
<span class="keyword">namespace</span> <span class="identifier">signals2</span> <span class="special">{</span>
<span class="keyword">class</span> <a class="link" href="../boost/signals2/trackable.html" title="Class trackable">trackable</a><span class="special">;</span>
<span class="special">}</span>
<span class="special">}</span></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/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../signals2.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../boost/signals2/connection.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,118 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Testsuite</title>
<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
<link rel="up" href="../signals2.html" title="Chapter 36. Boost.Signals2">
<link rel="prev" href="api_changes.html" title="Signals2 API Changes">
<link rel="next" href="../stacktrace.html" title="Chapter 37. Boost.Stacktrace 1.0">
</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="api_changes.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../signals2.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../stacktrace.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<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 class="toc"><dt><span class="section"><a href="tests.html#id-1.3.37.11.2">Acceptance tests</a></span></dt></dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="id-1.3.37.11.2"></a>Acceptance tests</h3></div></div></div>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col width="1in">
<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/signal.html#id-1_3_37_6_9_3_1_2_24_1-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_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> </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="api_changes.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../signals2.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../stacktrace.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,221 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Thread-Safety</title>
<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
<link rel="up" href="../signals2.html" title="Chapter 36. 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/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../signals2.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="faq.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<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 class="toc">
<dt><span class="section"><a href="thread-safety.html#id-1.3.37.7.2">Introduction</a></span></dt>
<dt><span class="section"><a href="thread-safety.html#id-1.3.37.7.3">Signals and combiners</a></span></dt>
<dt><span class="section"><a href="thread-safety.html#id-1.3.37.7.4">Connections and other classes</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="id-1.3.37.7.2"></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"><a class="link" href="../boost/shared_ptr.html" title="Class template shared_ptr">shared_ptr</a></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/signals2/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">
<div class="titlepage"><div><div><h3 class="title">
<a name="id-1.3.37.7.3"></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"><a class="link" href="../boost/signals2/signal.html#id-1_3_37_6_9_3_1_2_25_1-bb">signal::operator()</a></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 class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>The <code class="computeroutput">Mutex</code> associated with the connection to the
slot is locked.</p></li>
<li class="listitem"><p>All the tracked <code class="computeroutput">weak_ptr</code> associated with the
slot are copied into temporary <code class="computeroutput"><a class="link" href="../boost/shared_ptr.html" title="Class template shared_ptr">shared_ptr</a></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 class="listitem"><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#id-1_3_37_6_2_1_1_1_8_1-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/signal.html#id-1_3_37_6_9_3_1_2_26_2-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">
<div class="titlepage"><div><div><h3 class="title">
<a name="id-1.3.37.7.4"></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"><a class="link" href="../boost/shared_ptr.html" title="Class template shared_ptr">shared_ptr</a></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/slot.html" title="Class template slot">signals2::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/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../signals2.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="faq.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

File diff suppressed because it is too large Load Diff