|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r53548 - in trunk/libs/signals2/doc: . reference
From: fmhess_at_[hidden]
Date: 2009-06-01 13:58:36
Author: fmhess
Date: 2009-06-01 13:58:34 EDT (Mon, 01 Jun 2009)
New Revision: 53548
URL: http://svn.boost.org/trac/boost/changeset/53548
Log:
Fixed problems with classname elements producing links to classes
in old Boost.Signals when I meant them to link to Boost.Signals2
classes. Removed deprecated stuff from documentation and updated
wrt to changes made for the sake of the variadic template
implementation. Added section on changes to interface which will
appear in 1.40.
Text files modified:
trunk/libs/signals2/doc/examples.xml | 2
trunk/libs/signals2/doc/faq.xml | 6
trunk/libs/signals2/doc/porting.xml | 486 ++++++++++++++++++++++-----------------
trunk/libs/signals2/doc/rationale.xml | 20
trunk/libs/signals2/doc/reference/connection.xml | 40 +-
trunk/libs/signals2/doc/reference/deconstruct.xml | 2
trunk/libs/signals2/doc/reference/dummy_mutex.xml | 2
trunk/libs/signals2/doc/reference/last_value.xml | 7
trunk/libs/signals2/doc/reference/mutex.xml | 6
trunk/libs/signals2/doc/reference/optional_last_value.xml | 10
trunk/libs/signals2/doc/reference/shared_connection_block.xml | 6
trunk/libs/signals2/doc/reference/signal_header.xml | 173 ++++---------
trunk/libs/signals2/doc/reference/slot.xml | 186 ++++----------
trunk/libs/signals2/doc/reference/slot_base.xml | 4
trunk/libs/signals2/doc/reference/trackable.xml | 6
trunk/libs/signals2/doc/tests.xml | 16 -
trunk/libs/signals2/doc/thread_safety.xml | 10
trunk/libs/signals2/doc/tutorial.xml | 272 +--------------------
18 files changed, 473 insertions(+), 781 deletions(-)
Modified: trunk/libs/signals2/doc/examples.xml
==============================================================================
--- trunk/libs/signals2/doc/examples.xml (original)
+++ trunk/libs/signals2/doc/examples.xml 2009-06-01 13:58:34 EDT (Mon, 01 Jun 2009)
@@ -11,8 +11,8 @@
<section last-revision="$Date: 2007-06-12 14:01:23 -0400 (Tue, 12 Jun 2007) $" id="signals2.examples">
<title>Example programs</title>
- <using-namespace name="boost"/>
<using-namespace name="boost::signals2"/>
+ <using-namespace name="boost"/>
<section id="signals2.examples.misc">
<title>Miscellaneous Tutorial Examples</title>
Modified: trunk/libs/signals2/doc/faq.xml
==============================================================================
--- trunk/libs/signals2/doc/faq.xml (original)
+++ trunk/libs/signals2/doc/faq.xml 2009-06-01 13:58:34 EDT (Mon, 01 Jun 2009)
@@ -11,8 +11,8 @@
<section last-revision="$Date: 2007-06-12 14:01:23 -0400 (Tue, 12 Jun 2007) $" id="signals2.faq">
<title>Frequently Asked Questions</title>
- <using-namespace name="boost"/>
<using-namespace name="boost::signals2"/>
+ <using-namespace name="boost"/>
<qandaset>
<qandaentry>
@@ -40,8 +40,8 @@
with signal invocation, you will need to use automatic connection management.
That is, the objects will need to be owned by
<classname>shared_ptr</classname> and passed to the slot's
- <methodname alt="slotN::track">track</methodname>() method before the slot is connected.
- The <classname>trackable</classname> scheme of automatic connection management
+ <methodname alt="signals2::slot::track">track</methodname>() method before the slot is connected.
+ The <classname>signals2::trackable</classname> scheme of automatic connection management
is NOT thread-safe, and is only provided to ease porting of single-threaded
code from Boost.Signals to Boost.Signals2.
</para>
Modified: trunk/libs/signals2/doc/porting.xml
==============================================================================
--- trunk/libs/signals2/doc/porting.xml (original)
+++ trunk/libs/signals2/doc/porting.xml 2009-06-01 13:58:34 EDT (Mon, 01 Jun 2009)
@@ -7,221 +7,283 @@
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
-->
-<section last-revision="$Date: 2007-06-12 14:01:23 -0400 (Tue, 12 Jun 2007) $" id="signals2.porting">
- <title>Porting from Boost.Signals to Boost.Signals2</title>
-
- <using-namespace name="boost"/>
+<section last-revision="$Date: 2007-06-12 14:01:23 -0400 (Tue, 12 Jun 2007) $" id="signals2.api_changes">
+ <title>Signals2 API Changes</title>
<using-namespace name="boost::signals2"/>
+ <using-namespace name="boost"/>
+ <section id="signals2.porting">
+ <title>Porting from Boost.Signals to Boost.Signals2</title>
+ <para>The changes made to the Boost.Signals2 API compared to the original Boost.Signals
+ library are summarized below. We also provide some notes on
+ dealing with each change while porting existing Boost.Signals code to Boost.Signals2.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>The namespace <code>boost::signals</code> has been replaced by <code>boost::signals2</code>
+ to avoid conflict with the original Boost.Signals implementation, as well as the Qt "signals" macro.
+ All the Boost.Signals2 classes are inside the <code>boost::signals2</code> namespace,
+ unlike the original Boost.Signals which has some classes in the <code>boost</code>
+ namespace in addition to its own <code>boost::signals</code> namespace.
+ </para>
+ <para>
+ The Boost.Signals2 header files are contained in the
+ <code>boost/signals2/</code> subdirectory instead of the <code>boost/signals</code>
+ subdirectory used by the original Boost.Signals. Furthermore, all the headers except
+ for the convenience header <code>boost/signals2.hpp</code> are inside the
+ <code>boost/signals2/</code> subdirectory, unlike the original Boost.Signals which
+ keeps a few headers in the parent <code>boost/</code> directory
+ in addition to its own <code>boost/signals/</code> subdirectory.
+ </para>
+ <para>
+ For example, the <code>signal</code> class is now
+ in the <code>boost::signals2</code> namespace instead of the
+ <code>boost</code> namespace,
+ and it's header file is now at <code>boost/signals2/signal.hpp</code> instead of
+ <code>boost/signal.hpp</code>.
+ </para>
+ <para>
+ While porting, only trivial changes to <code>#include</code> directives
+ and namespace qualifications should be required to deal with these changes.
+ Furthermore, the new namespace and header locations for Boost.Signals2
+ allow it to coexist in the same program with the original Boost.Signals library,
+ and porting can be performed piecemeal.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Automatic connection management is now achieved through the use of
+ <classname>shared_ptr</classname>/<classname>weak_ptr</classname>
+ and <methodname>signals2::slot::track</methodname>(), as described in the
+ <link linkend="signals2.tutorial.connection-management">tutorial</link>.
+ However, the old (thread-unsafe) Boost.Signals scheme of automatic connection management
+ is still supported via the <classname>boost::signals2::trackable</classname> class.
+ </para>
+ <para>
+ If you do not intend to make your program multi-threaded, the easiest porting path is to simply replace
+ your uses of <classname>boost::signals::trackable</classname> as a base class with
+ <classname>boost::signals2::trackable</classname>. Boost.Signals2 uses the same
+ <functionname>boost::visit_each</functionname> mechanism to discover
+ <code>trackable</code> objects
+ as used by the original Boost.Signals library.
+ </para>
+ </listitem>
+ <listitem>
+ <para>Support for postconstructors (and predestructors) on objects managed by <classname>shared_ptr</classname>
+ has been added with
+ the <functionname>deconstruct</functionname> factory function.
+ This was motivated by the importance of
+ <code>shared_ptr</code> for the new connection tracking scheme, and the
+ inability to obtain a <code>shared_ptr</code> to an object in its constructor.
+ The use of <functionname>deconstruct</functionname> is described in the
+ <link linkend="signals2.tutorial.deconstruct">tutorial</link>.
+ </para>
+ <para>
+ The use of <functionname>deconstruct</functionname> is in no way required,
+ it is only provided in the hope
+ it may be useful. You may wish to use it if you are porting code where
+ a class creates connections to its own member functions in its constructor,
+ and you also
+ wish to use the new automatic connection management scheme. You could then
+ move the connection creation from the constructor to to the an
+ <code>adl_postconstruct</code> function, where
+ a reference to the owning <classname>shared_ptr</classname> is available for
+ passing to <methodname>signals2::slot::track</methodname>.
+ The <functionname>deconstruct</functionname> function would be used create objects
+ of the class and run their associated <code>adl_postconstruct</code> function.
+ You can enforce use of <functionname>deconstruct</functionname> by
+ making the class' constructors private and declaring
+ <classname>deconstruct_access</classname> a friend.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <classname>signals2::slot</classname> class takes a new <code>Signature</code> template parameter,
+ is useable as a function object, and has some additional features to support the
+ new Boost.Signals2 automatic connection management scheme.
+ </para>
+ <para>
+ The changes to the slot class should generally not cause any porting difficulties,
+ especially if you are using the <classname>boost::signals2::trackable</classname>
+ compatibility class mentioned above. If you are converting your code over to
+ use the new automatic connection management scheme, you will need to
+ employ some of the new slot features, as described in the
+ <link linkend="signals2.tutorial.connection-management">tutorial</link>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <classname>optional_last_value</classname> class has replaced <code>last_value</code>
+ as the default combiner for signals.
+ </para>
+ <para>
+ The <classname>signals2::last_value</classname> 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).
+ </para>
+ <para>
+ If you are porting signals which have a <code>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
+ <classname>optional_last_value</classname> returns a
+ <classname>boost::optional</classname> instead of a plain value. One simple
+ way to deal with this is to use <code>boost::optional::operator*()</code> to access the
+ value wrapped inside the returned <classname>boost::optional</classname>.
+ </para>
+ <para>
+ Alternatively, you could do a port by specifying the <code>Combiner</code> template parameter
+ for your <code>signals2::signal</code> to be <classname>signals2::last_value</classname>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <classname>signals2::signal</classname> class has an additional typedef
+ <classname>signals2::signal::extended_slot_type</classname>
+ and new <methodname>signals2::signal::connect_extended</methodname>()
+ methods. These allow connection of slots
+ which take an additional <classname>signals2::connection</classname> argument, giving them thread-safe
+ access to their signal/slot connection when they are invoked. There is also a
+ new <code>ExtendedSlotFunction</code> template parameter for specifying the underlying slot function
+ type for the new extended slots.
+ </para>
+ <para>
+ 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 <classname>signals2::connection</classname>
+ to the signal invoking them (for example to block or disconnect their connection)
+ you may wish to connect the slots with
+ <methodname>signals2::signal::connect_extended</methodname>().
+ 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 <link linkend="signals2.tutorial.extended-slot-type">tutorial</link>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <classname>signals2::signal</classname> class has a new <code>Mutex</code> template parameter for specifying
+ the mutex type used internally by the signal and its connections.
+ </para>
+ <para>
+ The <code>Mutex</code> template parameter can be left to its default value of
+ <classname>boost::signals2::mutex</classname> 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 <classname>dummy_mutex</classname>.
+ See the <link linkend="signals2.tutorial.signal-mutex-template-parameter">tutorial</link>
+ for more information on the <code>Mutex</code> parameter.
+ </para>
+ </listitem>
+ <listitem>
+ <para>The <code>signal::combiner()</code> method, which formerly returned a reference to the
+ signal's combiner has been replaced by <methodname>signals2::signal::combiner</methodname>
+ (which now returns the combiner by value) and <methodname>signals2::signal::set_combiner</methodname>.
+ </para>
+ <para>
+ During porting it should be straightforward to replace uses of the old reference-returning
+ <code>signal::combiner()</code>
+ function with the new "by-value" <methodname>signals2::signal::combiner</methodname>
+ and <methodname>signals2::signal::set_combiner</methodname> functions.
+ However, you will need to inspect each call of the <code>combiner</code> method in your code
+ to determine if your program logic has been broken by the changed
+ return type.
+ </para>
+ </listitem>
+ <listitem>
+ <para>Connections no longer have <code>block()</code> and <code>unblock()</code> methods. Blocking
+ of connections is now accomplished by creating <classname>shared_connection_block</classname> objects,
+ which provide RAII-style blocking.
+ </para>
+ <para>
+ If you have existing Boost.Signals code that blocks, for example:
+ </para>
+ <programlisting>
+ namespace bs = boost::signals;
- <para>The changes made to the Boost.Signals2 API compared to the original Boost.Signals
- library are summarized below. We also provide some notes on
- dealing with each change while porting existing Boost.Signals code to Boost.Signals2.
- </para>
- <itemizedlist>
- <listitem>
- <para>The namespace <code>boost::signals</code> has been replaced by <code>boost::signals2</code>
- to avoid conflict with the original Boost.Signals implementation, as well as the Qt "signals" macro.
- All the Boost.Signals2 classes are inside the <code>boost::signals2</code> namespace,
- unlike the original Boost.Signals which has some classes in the <code>boost</code>
- namespace in addition to its own <code>boost::signals</code> namespace.
- </para>
- <para>
- The Boost.Signals2 header files are contained in the
- <code>boost/signals2/</code> subdirectory instead of the <code>boost/signals</code>
- subdirectory used by the original Boost.Signals. Furthermore, all the headers except
- for the convenience header <code>boost/signals2.hpp</code> are inside the
- <code>boost/signals2/</code> subdirectory, unlike the original Boost.Signals which
- keeps a few headers in the parent <code>boost/</code> directory
- in addition to its own <code>boost/signals/</code> subdirectory.
- </para>
- <para>
- For example, the <code>signal</code> class is now
- in the <code>boost::signals2</code> namespace instead of the
- <code>boost</code> namespace,
- and it's header file is now at <code>boost/signals2/signal.hpp</code> instead of
- <code>boost/signal.hpp</code>.
- </para>
- <para>
- While porting, only trivial changes to <code>#include</code> directives
- and namespace qualifications should be required to deal with these changes.
- Furthermore, the new namespace and header locations for Boost.Signals2
- allow it to coexist in the same program with the original Boost.Signals library,
- and porting can be performed piecemeal.
- </para>
- </listitem>
- <listitem>
- <para>
- Automatic connection management is now achieved through the use of
- <classname>shared_ptr</classname>/<classname>weak_ptr</classname>
- and <methodname alt="slotN::track">slot::track</methodname>(), as described in the
- <link linkend="signals2.tutorial.connection-management">tutorial</link>.
- However, the old (thread-unsafe) Boost.Signals scheme of automatic connection management
- is still supported via the <classname>boost::signals2::trackable</classname> class.
- </para>
- <para>
- If you do not intend to make your program multi-threaded, the easiest porting path is to simply replace
- your uses of <classname>boost::signals::trackable</classname> as a base class with
- <classname>boost::signals2::trackable</classname>. Boost.Signals2 uses the same
- <functionname>boost::visit_each</functionname> mechanism to discover
- <classname>trackable</classname> objects
- as used by the original Boost.Signals library.
- </para>
- </listitem>
- <listitem>
- <para>Support for postconstructors (and predestructors) on objects managed by <classname>shared_ptr</classname>
- has been added with
- the <functionname>deconstruct</functionname> factory function.
- This was motivated by the importance of
- <code>shared_ptr</code> for the new connection tracking scheme, and the
- inability to obtain a <code>shared_ptr</code> to an object in its constructor.
- The use of <functionname>deconstruct</functionname> is described in the
- <link linkend="signals2.tutorial.deconstruct">tutorial</link>.
- </para>
- <para>
- The use of <functionname>deconstruct</functionname> is in no way required,
- it is only provided in the hope
- it may be useful. You may wish to use it if you are porting code where
- a class creates connections to its own member functions in its constructor,
- and you also
- wish to use the new automatic connection management scheme. You could then
- move the connection creation from the constructor to to the an
- <code>adl_postconstruct</code> function, where
- a reference to the owning <classname>shared_ptr</classname> is available for
- passing to <methodname alt="slotN::track">slot::track</methodname>.
- The <functionname>deconstruct</functionname> function would be used create objects
- of the class and run their associated <code>adl_postconstruct</code> function.
- You can enforce use of <functionname>deconstruct</functionname> by
- making the class' constructors private and declaring
- <classname>deconstruct_access</classname> a friend.
- </para>
- </listitem>
- <listitem>
- <para>
- The <classname>slot</classname> class takes a new <code>Signature</code> template parameter,
- is useable as a function object, and has some additional features to support the
- new Boost.Signals2 automatic connection management scheme.
- </para>
- <para>
- The changes to the slot class should generally not cause any porting difficulties,
- especially if you are using the <classname>boost::signals2::trackable</classname>
- compatibility class mentioned above. If you are converting your code over to
- use the new automatic connection management scheme, you will need to
- employ some of the new slot features, as described in the
- <link linkend="signals2.tutorial.connection-management">tutorial</link>.
- </para>
- </listitem>
- <listitem>
- <para>
- The <classname>optional_last_value</classname> class has replaced <classname>last_value</classname>
- as the default combiner for signals.
- </para>
- <para>
- The <classname>last_value</classname> 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).
- </para>
- <para>
- If you are porting signals which have a <code>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
- <classname>optional_last_value</classname> returns a
- <classname>boost::optional</classname> instead of a plain value. One simple
- way to deal with this is to use <code>boost::optional::operator*()</code> to access the
- value wrapped inside the returned <classname>boost::optional</classname>.
- </para>
- <para>
- Alternatively, you could do a port by specifying the <code>Combiner</code> template parameter
- for your <code>signals2::signal</code> to be <classname>last_value</classname>.
- </para>
- </listitem>
- <listitem>
- <para>
- The <classname>signal</classname> class has an additional typedef
- <classname alt="signalN::extended_slot_type">signal::extended_slot_type</classname>
- and new <methodname alt="signalN::connect_extended">signal::connect_extended</methodname>()
- methods. These allow connection of slots
- which take an additional <classname>connection</classname> argument, giving them thread-safe
- access to their signal/slot connection when they are invoked. There is also a
- new <code>ExtendedSlotFunction</code> template parameter for specifying the underlying slot function
- type for the new extended slots.
- </para>
- <para>
- 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 <classname>connection</classname>
- to the signal invoking them (for example to block or disconnect their connection)
- you may wish to connect the slots with
- <methodname alt="signalN::connect_extended">signal::connect_extended</methodname>().
- 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 <link linkend="signals2.tutorial.extended-slot-type">tutorial</link>.
- </para>
- </listitem>
- <listitem>
- <para>
- The <classname>signal</classname> class has a new <code>Mutex</code> template parameter for specifying
- the mutex type used internally by the signal and its connections.
- </para>
- <para>
- The <code>Mutex</code> template parameter can be left to its default value of
- <classname>boost::signals2::mutex</classname> 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 <classname>dummy_mutex</classname>.
- See the <link linkend="signals2.tutorial.signal-mutex-template-parameter">tutorial</link>
- for more information on the <code>Mutex</code> parameter.
- </para>
- </listitem>
- <listitem>
- <para>The <code>signal::combiner()</code> method, which formerly returned a reference to the
- signal's combiner has been replaced by <methodname alt="signalN::combiner">signal::combiner</methodname>
- (which now returns the combiner by value) and <methodname alt="signalN::set_combiner">signal::set_combiner</methodname>.
- </para>
- <para>
- During porting it should be straightforward to replace uses of the old reference-returning
- <code>signal::combiner()</code>
- function with the new "by-value" <methodname alt="signalN::combiner">signal::combiner</methodname>
- and <methodname alt="signalN::set_combiner">signal::set_combiner</methodname> functions.
- However, you will need to inspect each call of the <code>combiner</code> method in your code
- to determine if your program logic has been broken by the changed
- return type.
- </para>
- </listitem>
- <listitem>
- <para>Connections no longer have <code>block()</code> and <code>unblock()</code> methods. Blocking
- of connections is now accomplished by creating <classname>shared_connection_block</classname> objects,
- which provide RAII-style blocking.
- </para>
- <para>
- If you have existing Boost.Signals code that blocks, for example:
- </para>
- <programlisting>
-namespace bs = boost::signals;
-
-bs::connection my_connection;
-//...
+ bs::connection my_connection;
+ //...
-my_connection.block();
-do_something();
-my_connection.unblock();
-</programlisting>
- <para>
- then the version ported to Boost.Signals2 would look like:
- </para>
- <programlisting>
-namespace bs2 = boost::signals2;
+ my_connection.block();
+ do_something();
+ my_connection.unblock();
+ </programlisting>
+ <para>
+ then the version ported to Boost.Signals2 would look like:
+ </para>
+ <programlisting>
+ namespace bs2 = boost::signals2;
-bs2::connection my_connection;
-//...
+ 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
-</programlisting>
- </listitem>
- </itemizedlist>
+ {
+ bs2::shared_connection_block blocker(my_connection);
+ do_something();
+ } // blocker goes out of scope here and releases its block on my_connection
+ </programlisting>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section id="signals2.api_history">
+ <title>Signals2 API Development</title>
+ <section id="signals2.api_history.1-40">
+ <title>Version 1.40</title>
+ <para>
+ Version 1.40 adds a few new features to the <classname>shared_connection_block</classname>
+ class to make it more flexible:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <classname>shared_connection_block</classname> is now default constructible.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A <classname>shared_connection_block</classname> may now be constructed without
+ immediately blocking its connection.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <methodname>shared_connection_block::connection</methodname>() query has been
+ added, to provide access to the <code>shared_connection_block</code>s associated
+ connection.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>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++0x).
+ This change is mostly transparent to the user, however it does introduce a few
+ visible tweaks to the interface as described in the following.
+ </para>
+ <para>
+ The following library features are
+ deprecated, and are only available if your compiler is NOT using
+ variadic templates (i.e. BOOST_NO_VARIADIC_TEMPLATES is defined
+ by Boost.Config).
+ <itemizedlist>
+ <listitem>
+ <para>
+ The "portable syntax" signal and slot classes, i.e. signals2::signal0, signal1, etc.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The arg1_type, arg2_type, etc. member typedefs in the <classname>signals2::signal</classname> and
+ <classname>signals2::slot</classname> classes. They are replaced by the
+ template member classes <classname>signals2::signal::arg</classname> and
+ <classname>signals2::slot::arg</classname>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+ <section id="signals2.api_history.1-39">
+ <title>Version 1.39</title>
+ <para>Version 1.39 is the first release of Boost to include the Signals2 library.</para>
+ </section>
+ </section>
</section>
Modified: trunk/libs/signals2/doc/rationale.xml
==============================================================================
--- trunk/libs/signals2/doc/rationale.xml (original)
+++ trunk/libs/signals2/doc/rationale.xml 2009-06-01 13:58:34 EDT (Mon, 01 Jun 2009)
@@ -11,9 +11,9 @@
<section last-revision="$Date: 2007-06-12 14:01:23 -0400 (Tue, 12 Jun 2007) $" id="signals2.rationale">
<title>Design Rationale</title>
- <using-namespace name="boost"/>
<using-namespace name="boost::signals2"/>
- <using-class name="boost::signals2::signalN"/>
+ <using-namespace name="boost"/>
+ <using-class name="boost::signals2::signal"/>
<section>
<title>User-level Connection Management</title>
@@ -21,11 +21,11 @@
<para> 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><classname>connection</classname></code> object that enables
+ <code><classname>signals2::connection</classname></code> object that enables
connected/disconnected query, manual disconnection, and an
- automatic disconnection on destruction mode (<classname>scoped_connection</classname>).
+ automatic disconnection on destruction mode (<classname>signals2::scoped_connection</classname>).
In addition, two other interfaces are supported by the
- <methodname alt="signalN::disconnect">signal::disconnect</methodname> overloaded method:</para>
+ <methodname alt="signal::disconnect">signal::disconnect</methodname> overloaded method:</para>
<itemizedlist>
<listitem>
@@ -71,7 +71,7 @@
<para> This type of interface is supported in Boost.Signals2
via the slot grouping mechanism, and the overload of
- <methodname alt="signalN::disconnect">signal::disconnect</methodname>
+ <methodname alt="signal::disconnect">signal::disconnect</methodname>
which takes an argument of the signal's <code>Group</code> type.</para>
</listitem>
</itemizedlist>
@@ -112,7 +112,7 @@
</para>
<para>The new connection management scheme has the advantage of being
non-intrusive. Objects of any type may be tracked using the
- <classname>shared_ptr/weak_ptr</classname> scheme. The old
+ <classname>shared_ptr</classname>/<classname>weak_ptr</classname> scheme. The old
<code><classname>boost::signals::trackable</classname></code>
scheme requires the tracked objects to be derived from the <code>trackable</code>
base class, which is not always practical when interacting
@@ -296,7 +296,7 @@
<code>+=</code> operation: should it be a reference to the
signal itself, to enable <code>sig += slot1 += slot2</code>,
or should it return a
- <code><classname>connection</classname></code> for the
+ <code><classname>signals2::connection</classname></code> for the
newly-created signal/slot connection?</para>
</listitem>
@@ -327,9 +327,7 @@
<classname>boost::signals2::mutex</classname> is simply that the <classname>boost::mutex</classname>
class provided by the Boost.Thread library currently requires linking to libboost_thread.
The <classname>boost::signals2::mutex</classname> class allows Signals2 to remain
- a header-only library. In the future, <classname>boost::signals2::mutex</classname>
- will probably be turned into a typedef to <classname>std::mutex</classname> when
- compiling in C++0x mode. You may still choose to use <classname>boost::mutex</classname>
+ a header-only library. You may still choose to use <classname>boost::mutex</classname>
if you wish, by specifying it as the <code>Mutex</code> template type for your signals.
</para>
<para>
Modified: trunk/libs/signals2/doc/reference/connection.xml
==============================================================================
--- trunk/libs/signals2/doc/reference/connection.xml (original)
+++ trunk/libs/signals2/doc/reference/connection.xml 2009-06-01 13:58:34 EDT (Mon, 01 Jun 2009)
@@ -16,7 +16,7 @@
<purpose>Query/disconnect a signal-slot connection.</purpose>
<description>
- <para>The <classname>connection</classname> class represents
+ <para>The <classname>signals2::connection</classname> class represents
a connection between a Signal and a Slot. It is a
lightweight object that has the ability to query whether the
signal and slot are currently connected, and to disconnect
@@ -43,7 +43,7 @@
<constructor>
<parameter name="other">
- <paramtype>const <classname>connection</classname>&</paramtype>
+ <paramtype>const <classname alt="signals2::connection">connection</classname>&</paramtype>
</parameter>
<effects><para><computeroutput>this</computeroutput> references
@@ -55,7 +55,7 @@
<copy-assignment>
<parameter name="other">
- <paramtype>const <classname>connection</classname>&</paramtype>
+ <paramtype>const <classname alt="signals2::connection">connection</classname>&</paramtype>
</parameter>
<effects><para><computeroutput>this</computeroutput> references
@@ -104,7 +104,7 @@
<method name="swap">
<type>void</type>
<parameter name="other">
- <paramtype>const <classname>connection</classname>&</paramtype>
+ <paramtype>const <classname alt="signals2::connection">connection</classname>&</paramtype>
</parameter>
<effects><para>Swaps the connections referenced in
<computeroutput>this</computeroutput> and
@@ -118,7 +118,7 @@
<method name="operator==" cv="const">
<type>bool</type>
<parameter name="other">
- <paramtype>const <classname>connection</classname>&</paramtype>
+ <paramtype>const <classname alt="signals2::connection">connection</classname>&</paramtype>
</parameter>
<returns><para><computeroutput>true</computeroutput> if
@@ -134,7 +134,7 @@
<method name="operator!=" cv="const">
<type>bool</type>
<parameter name="other">
- <paramtype>const <classname>connection</classname>&</paramtype>
+ <paramtype>const <classname alt="signals2::connection">connection</classname>&</paramtype>
</parameter>
<returns><para><computeroutput>!(*this == other)</computeroutput></para></returns>
@@ -145,7 +145,7 @@
<method name="operator<" cv="const">
<type>bool</type>
<parameter name="other">
- <paramtype>const <classname>connection</classname>&</paramtype>
+ <paramtype>const <classname alt="signals2::connection">connection</classname>&</paramtype>
</parameter>
<returns><para><computeroutput>true</computeroutput> if the
@@ -165,10 +165,10 @@
<function name="swap">
<type>void</type>
<parameter name="x">
- <paramtype><classname>connection</classname>&</paramtype>
+ <paramtype><classname alt="signals2::connection">connection</classname>&</paramtype>
</parameter>
<parameter name="y">
- <paramtype><classname>connection</classname>&</paramtype>
+ <paramtype><classname alt="signals2::connection">connection</classname>&</paramtype>
</parameter>
<effects><para><computeroutput>x.swap(y)</computeroutput></para></effects>
@@ -179,7 +179,7 @@
<class name="scoped_connection">
<inherit access="public">
- <type><classname>connection</classname></type>
+ <type><classname alt="signals2::connection">connection</classname></type>
</inherit>
<purpose>Limits a signal-slot connection lifetime to a particular scope.</purpose>
@@ -196,7 +196,7 @@
</constructor>
<constructor>
<parameter name="other">
- <paramtype>const <classname>connection</classname>&</paramtype>
+ <paramtype>const <classname alt="signals2::connection">connection</classname>&</paramtype>
</parameter>
<effects><para><computeroutput>this</computeroutput> references
@@ -233,7 +233,7 @@
</postconditions>
</method>
<method name="release">
- <type><classname>connection</classname></type>
+ <type><classname alt="signals2::connection">connection</classname></type>
<effects>
<para>
Releases the connection so it will not be disconnected by the <code>scoped_connection</code>
@@ -245,7 +245,7 @@
<para><code><methodname alt="connection::connected">connected</methodname>() == false</code></para>
</postconditions>
<returns>
- <para>A <classname>connection</classname> object referencing the connection which was
+ <para>A <classname alt="signals2::connection">connection</classname> object referencing the connection which was
released by the <code>scoped_connection</code>.
</para>
</returns>
@@ -255,29 +255,29 @@
<access name="private">
<constructor>
<parameter name="other">
- <paramtype>const <classname>scoped_connection</classname>&</paramtype>
+ <paramtype>const <classname alt="signals2::scoped_connection">scoped_connection</classname>&</paramtype>
</parameter>
<description>
- <para>The scoped_connection class is not copyable. It may only be constructed from a <classname>connection</classname> object.</para>
+ <para>The scoped_connection class is not copyable. It may only be constructed from a <classname alt="signals2::connection">connection</classname> object.</para>
</description>
</constructor>
<copy-assignment>
<parameter name="rhs">
- <paramtype>const <classname>scoped_connection</classname>&</paramtype>
+ <paramtype>const <classname alt="signals2::scoped_connection">scoped_connection</classname>&</paramtype>
</parameter>
<description>
- <para>The scoped_connection class is not copyable. It may only be assigned from a <classname>connection</classname> object.</para>
+ <para>The scoped_connection class is not copyable. It may only be assigned from a <classname alt="signals2::connection">connection</classname> object.</para>
</description>
</copy-assignment>
</access>
<description>
- <para>A <classname>connection</classname> which automatically disconnects on destruction.</para>
+ <para>A <classname alt="signals2::connection">connection</classname> which automatically disconnects on destruction.</para>
<section>
<title>Thread Safety</title>
<para>The methods of the <code>scoped_connection</code> class (including those
inherited from its base <code>connection</code> class) are thread-safe with the exception
- of <methodname>connection::swap</methodname>, <methodname>release</methodname>, and
- the assignment operator A <code>scoped_connection</code> object
+ of <methodname>signals2::connection::swap</methodname>, <methodname>release</methodname>, and
+ the assignment operator. A <code>scoped_connection</code> object
should not be accessed concurrently when any of these operations is in progress.
However, it is always safe to access a different <code>connection</code> object
in another thread, even if it references the same underlying signal-slot connection.
Modified: trunk/libs/signals2/doc/reference/deconstruct.xml
==============================================================================
--- trunk/libs/signals2/doc/reference/deconstruct.xml (original)
+++ trunk/libs/signals2/doc/reference/deconstruct.xml 2009-06-01 13:58:34 EDT (Mon, 01 Jun 2009)
@@ -8,8 +8,8 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
-->
<header name="boost/signals2/deconstruct.hpp" last-revision="$Date: 2007-03-06 16:51:55 -0500 (Tue, 06 Mar 2007) $">
- <using-namespace name="boost"/>
<using-namespace name="boost::signals2"/>
+ <using-namespace name="boost"/>
<namespace name="boost">
<namespace name="signals2">
<overloaded-function name="deconstruct">
Modified: trunk/libs/signals2/doc/reference/dummy_mutex.xml
==============================================================================
--- trunk/libs/signals2/doc/reference/dummy_mutex.xml (original)
+++ trunk/libs/signals2/doc/reference/dummy_mutex.xml 2009-06-01 13:58:34 EDT (Mon, 01 Jun 2009)
@@ -8,8 +8,8 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
-->
<header name="boost/signals2/dummy_mutex.hpp" last-revision="$Date: 2007-03-06 16:51:55 -0500 (Tue, 06 Mar 2007) $">
- <using-namespace name="boost"/>
<using-namespace name="boost::signals2"/>
+ <using-namespace name="boost"/>
<namespace name="boost">
<namespace name="signals2">
<class name="dummy_mutex">
Modified: trunk/libs/signals2/doc/reference/last_value.xml
==============================================================================
--- trunk/libs/signals2/doc/reference/last_value.xml (original)
+++ trunk/libs/signals2/doc/reference/last_value.xml 2009-06-01 13:58:34 EDT (Mon, 01 Jun 2009)
@@ -61,7 +61,7 @@
<purpose>Evaluate an InputIterator sequence.</purpose>
<typedef name="result_type">
- <type><emphasis>unspecified</emphasis></type>
+ <type>void</type>
</typedef>
<method-group name="invocation">
@@ -79,6 +79,9 @@
<effects><para>Attempts to dereference every iterator in the sequence <computeroutput>[first, last)</computeroutput>.
</para></effects>
+ <throws>
+ <para>Unlike the non-void versions of <code>last_value</code>, the void specialization does not throw.</para>
+ </throws>
</method>
</method-group>
</class-specialization>
@@ -86,7 +89,7 @@
<class name="no_slots_error">
<inherit access="public"><classname>std::exception</classname></inherit>
<purpose>Indicates a combiner was unable to synthesize a return value.</purpose>
- <description>The <code>no_slots_error</code> exception may be thrown by <classname>last_value</classname>
+ <description>The <code>no_slots_error</code> exception may be thrown by <classname>signals2::last_value</classname>
when it is run but unable to obtain any results from its input iterators.
</description>
<method name="what" cv="const" specifiers="virtual">
Modified: trunk/libs/signals2/doc/reference/mutex.xml
==============================================================================
--- trunk/libs/signals2/doc/reference/mutex.xml (original)
+++ trunk/libs/signals2/doc/reference/mutex.xml 2009-06-01 13:58:34 EDT (Mon, 01 Jun 2009)
@@ -8,8 +8,8 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
-->
<header name="boost/signals2/mutex.hpp" last-revision="$Date: 2007-03-06 16:51:55 -0500 (Tue, 06 Mar 2007) $">
- <using-namespace name="boost"/>
<using-namespace name="boost::signals2"/>
+ <using-namespace name="boost"/>
<namespace name="boost">
<namespace name="signals2">
<class name="mutex">
@@ -34,9 +34,9 @@
<classname>boost::mutex</classname> class instead as the mutex type for your signals.
</para>
<para>
- You may wish to use a thread-unsafe signal in a multi-threaded program, if
+ You may wish to use a thread-unsafe signal, if
the signal is only used by a single thread. In that case, you may prefer to
- use the <classname>dummy_mutex</classname> class as the <code>Mutex</code>
+ use the <classname>signals2::dummy_mutex</classname> class as the <code>Mutex</code>
template type for your signal.
</para>
</description>
Modified: trunk/libs/signals2/doc/reference/optional_last_value.xml
==============================================================================
--- trunk/libs/signals2/doc/reference/optional_last_value.xml (original)
+++ trunk/libs/signals2/doc/reference/optional_last_value.xml 2009-06-01 13:58:34 EDT (Mon, 01 Jun 2009)
@@ -23,7 +23,7 @@
<para>
<code>optional_last_value</code> is the default Combiner template type for signals in the
Boost.Signals2 library. The advantage of <code>optional_last_value</code> over
- <classname>last_value</classname> is that <code>optional_last_value</code>
+ <classname>signals2::last_value</classname> is that <code>optional_last_value</code>
can return an empty <classname>boost::optional</classname>. rather
than throwing an exception, when
its <code>InputIterator</code> sequence is empty.
@@ -66,17 +66,17 @@
<purpose>Evaluate an InputIterator sequence.</purpose>
<description>
- <para>This specialization of <classname>optional_last_value</classname> is provided
+ <para>This specialization of <classname>signals2::optional_last_value</classname> is provided
to cope with the fact that there is no such thing as an
<code><classname>optional</classname><void></code>, which
<classname>optional_last_value</classname> would otherwise try to
- use as its <code>result_type</code>. Therefore,
- this specialization leaves the <code>result_type</code> unspecified.
+ use as its <code>result_type</code>. This specialization
+ instead sets the <code>result_type</code> to be <code>void</code>.
</para>
</description>
<typedef name="result_type">
- <type><emphasis>unspecified</emphasis></type>
+ <type>void</type>
</typedef>
<method-group name="invocation">
Modified: trunk/libs/signals2/doc/reference/shared_connection_block.xml
==============================================================================
--- trunk/libs/signals2/doc/reference/shared_connection_block.xml (original)
+++ trunk/libs/signals2/doc/reference/shared_connection_block.xml 2009-06-01 13:58:34 EDT (Mon, 01 Jun 2009)
@@ -8,8 +8,8 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
-->
<header name="boost/signals2/shared_connection_block.hpp" last-revision="$Date: 2007-03-06 16:51:55 -0500 (Tue, 06 Mar 2007) $">
- <using-namespace name="boost"/>
<using-namespace name="boost::signals2"/>
+ <using-namespace name="boost"/>
<using-class name="boost::signals2::connection"/>
<namespace name="boost">
<namespace name="signals2">
@@ -26,7 +26,7 @@
its block when it is destroyed or its
<methodname>unblock</methodname> method is called.</para>
<para>A <code>shared_connection_block</code> is safe to use even
- after the <classname>connection</classname> object it was constructed
+ after the <classname>signals2::connection</classname> object it was constructed
from has been destroyed, or the connection it references has been
disconnected.</para>
<para>
@@ -138,4 +138,4 @@
</class>
</namespace>
</namespace>
-</header>
\ No newline at end of file
+</header>
Modified: trunk/libs/signals2/doc/reference/signal_header.xml
==============================================================================
--- trunk/libs/signals2/doc/reference/signal_header.xml (original)
+++ trunk/libs/signals2/doc/reference/signal_header.xml 2009-06-01 13:58:34 EDT (Mon, 01 Jun 2009)
@@ -9,23 +9,21 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
-->
<header name="boost/signals2/signal.hpp" last-revision="$Date: 2007-03-06 16:51:55 -0500 (Tue, 06 Mar 2007) $">
- <using-namespace name="boost"/>
<using-namespace name="boost::signals2"/>
+ <using-namespace name="boost"/>
<namespace name="boost">
<namespace name="signals2">
<enum name="connect_position">
<enumvalue name="at_front"/>
<enumvalue name="at_back"/>
</enum>
- <class name="signalN">
+ <class name="signal">
<template>
- <template-type-parameter name="R"/>
- <template-type-parameter name="T1"/>
- <template-type-parameter name="T2"/>
- <template-varargs/>
- <template-type-parameter name="TN"/>
+ <template-type-parameter name="Signature">
+ <purpose>Function type R (T1, T2, ..., TN)</purpose>
+ </template-type-parameter>
<template-type-parameter name="Combiner">
- <default><classname>optional_last_value</classname><R></default>
+ <default><classname>boost::signals2::optional_last_value</classname><R></default>
</template-type-parameter>
<template-type-parameter name="Group">
<default>int</default>
@@ -34,31 +32,29 @@
<default><classname>std::less</classname><Group></default>
</template-type-parameter>
<template-type-parameter name="SlotFunction">
- <default><classname>functionN</classname><R, T1, T2, ..., TN></default>
+ <default><classname>boost::function</classname><Signature></default>
</template-type-parameter>
<template-type-parameter name="ExtendedSlotFunction">
- <default><classname>functionN</classname><R, const <classname>connection</classname> &, T1, T2, ..., TN></default>
+ <default><classname>boost::function</classname><R (const <classname alt="signals2::connection">connection</classname> &, T1, T2, ..., TN)></default>
</template-type-parameter>
<template-type-parameter name="Mutex">
- <default><classname>mutex</classname></default>
+ <default><classname>boost::signals2::mutex</classname></default>
</template-type-parameter>
</template>
<inherit access="public">
- <type><classname>signal_base</classname></type>
+ <type><classname>boost::signals2::signal_base</classname></type>
</inherit>
- <purpose>Set of safe multicast callback types.</purpose>
+ <purpose>Safe multicast callback.</purpose>
<description>
- <para>The class template <classname>signalN</classname> covers
- several related classes signal0, signal1, signal2, etc.,
- where the number suffix describes the number of function
- parameters the signal and its connected slots will
- take. Instead of enumerating all classes, a single pattern
- <classname>signalN</classname> will be described, where N
- represents the number of function parameters.</para>
+ <para>
+ See the <link linkend="signals2.tutorial">tutorial</link>
+ for more information on how to use the signal class.
+ </para>
</description>
+ <typedef name="signature_type"><type>Signature</type></typedef>
<typedef name="result_type">
<type>typename Combiner::result_type</type>
</typedef>
@@ -67,54 +63,66 @@
<typedef name="group_compare_type"><type>GroupCompare</type></typedef>
<typedef name="slot_function_type"><type>SlotFunction</type></typedef>
<typedef name="slot_type">
- <type>typename <classname>slotN</classname><R, T1, T2, ..., TN, SlotFunction></type>
+ <type>typename <classname>signals2::slot</classname><Signature, SlotFunction></type>
</typedef>
<typedef name="extended_slot_function_type"><type>ExtendedSlotFunction</type></typedef>
<typedef name="extended_slot_type">
- <type>typename <classname>slotN</classname><R, const <classname>connection</classname> &, T1, ..., TN, ExtendedSlotFunction></type>
+ <type>typename <classname>signals2::slot</classname><R (const <classname alt="signals2::connection">connection</classname> &, T1, ..., TN), ExtendedSlotFunction></type>
<description>
<para>Slots of the <code>extended_slot_type</code> may be connected to the signal using the
<methodname>connect_extended</methodname> methods. The <code>extended_slot_type</code>
- has an additional <classname>connection</classname> argument in its signature,
+ has an additional <classname>signals2::connection</classname> argument in its signature,
which gives slot functions access to their connection to the signal
invoking them.
</para>
</description>
</typedef>
<typedef name="slot_result_type">
- <type><emphasis>implementation-detail</emphasis></type>
+ <type>typename SlotFunction::result_type</type>
<description>
<para>
This is the type returned when dereferencing the input iterators passed to the signal's
- combiner. It is usually <code>slot_function_type::result_type</code> unless that
- type is <code>void</code>, in which case <code>slot_result_type</code> is
- unspecified.
+ combiner.
</para>
</description>
</typedef>
<typedef name="slot_call_iterator">
<type><emphasis>unspecified</emphasis></type>
+ <description>
+ <para>
+ The input iterator type passed to the combiner when the signal is invoked.
+ </para>
+ </description>
</typedef>
<typedef name="argument_type">
<type>T1</type>
- <purpose>If N == 1</purpose>
+ <purpose>Exists iff iff arity == 1</purpose>
</typedef>
<typedef name="first_argument_type">
<type>T1</type>
- <purpose>If N == 2</purpose>
+ <purpose>Exists iff iff arity == 2</purpose>
</typedef>
<typedef name="second_argument_type">
<type>T2</type>
- <purpose>If N == 2</purpose>
+ <purpose>Exists iff iff arity == 2</purpose>
</typedef>
- <typedef name="arg1_type"><type>T1</type></typedef>
- <typedef name="arg2_type"><type>T2</type></typedef>
- <typedef name="..."><type/></typedef>
- <typedef name="argN_type"><type>TN</type></typedef>
+
+ <class name="arg">
+ <template>
+ <template-nontype-parameter name="n">
+ <type>unsigned</type>
+ </template-nontype-parameter>
+ </template>
+ <typedef name="type">
+ <type>Tn</type>
+ <purpose>The type of the <classname alt="signals2::signal">signal</classname>'s (n+1)th argument</purpose>
+ </typedef>
+ </class>
<static-constant name="arity">
<type>int</type>
<default>N</default>
+ <purpose>The number of arguments taken by the signal.</purpose>
</static-constant>
<constructor>
@@ -139,7 +147,7 @@
<method-group name="connection management">
<overloaded-method name="connect">
<signature>
- <type><classname>connection</classname></type>
+ <type><classname alt="signals2::connection">connection</classname></type>
<parameter name="slot">
<paramtype>const slot_type&</paramtype>
</parameter>
@@ -150,7 +158,7 @@
</signature>
<signature>
- <type><classname>connection</classname></type>
+ <type><classname alt="signals2::connection">connection</classname></type>
<parameter name="group">
<paramtype>const group_type&</paramtype>
</parameter>
@@ -177,7 +185,7 @@
slots.</para></effects>
<returns><para>A
- <computeroutput><classname>connection</classname></computeroutput>
+ <computeroutput><classname>signals2::connection</classname></computeroutput>
object that references the newly-created connection between
the signal and the slot; if the slot is inactive, returns a
disconnected connection.</para></returns>
@@ -197,7 +205,7 @@
</overloaded-method>
<overloaded-method name="connect_extended">
<signature>
- <type><classname>connection</classname></type>
+ <type><classname alt="signals2::connection">connection</classname></type>
<parameter name="slot">
<paramtype>const extended_slot_type&</paramtype>
</parameter>
@@ -208,7 +216,7 @@
</signature>
<signature>
- <type><classname>connection</classname></type>
+ <type><classname alt="signals2::connection">connection</classname></type>
<parameter name="group">
<paramtype>const group_type&</paramtype>
</parameter>
@@ -225,7 +233,7 @@
The <code>connect_extended</code> methods work the same as the <methodname>connect</methodname>
methods, except they take slots of type <classname>extended_slot_type</classname>.
This is useful if a slot needs to access the connection between it and the
- signal invoking it, for example if it wishes to disconnect or block the connection.
+ signal invoking it, for example if it wishes to disconnect or block its own connection.
</para>
</description>
</overloaded-method>
@@ -254,9 +262,9 @@
are disconnected.
</para>
<para>Note, the <code>slot_func</code>
- argument should not be an actual <classname alt="slotN">signals2::slot</classname>
+ argument should not be an actual <classname>signals2::slot</classname>
object (which does not even support <code>operator==</code>), but rather
- the functor you wrapped inside a <classname alt="slotN">signals2::slot</classname>
+ the functor you wrapped inside a <classname>signals2::slot</classname>
when you initially made the connection.
</para></effects>
@@ -326,18 +334,18 @@
<overloaded-method name="operator()">
<signature>
<type>result_type</type>
- <parameter name="a1"><paramtype>arg1_type</paramtype></parameter>
- <parameter name="a2"><paramtype>arg2_type</paramtype></parameter>
+ <parameter name="a1"><paramtype>arg<0>::type</paramtype></parameter>
+ <parameter name="a2"><paramtype>arg<1>::type</paramtype></parameter>
<parameter><paramtype>...</paramtype></parameter>
- <parameter name="aN"><paramtype>argN_type</paramtype></parameter>
+ <parameter name="aN"><paramtype>arg<N-1>::type</paramtype></parameter>
</signature>
<signature cv="const">
<type>result_type</type>
- <parameter name="a1"><paramtype>arg1_type</paramtype></parameter>
- <parameter name="a2"><paramtype>arg2_type</paramtype></parameter>
+ <parameter name="a1"><paramtype>arg<0>::type</paramtype></parameter>
+ <parameter name="a2"><paramtype>arg<1>::type</paramtype></parameter>
<parameter><paramtype>...</paramtype></parameter>
- <parameter name="aN"><paramtype>argN_type</paramtype></parameter>
+ <parameter name="aN"><paramtype>arg<N-1>::type</paramtype></parameter>
</signature>
<effects><para>Invokes the combiner with a
@@ -369,7 +377,7 @@
non-<computeroutput>const</computeroutput> version will
invoke the combiner as
non-<computeroutput>const</computeroutput>.</para>
- </notes>
+ </notes>
</overloaded-method>
</method-group>
@@ -390,73 +398,6 @@
</method>
</method-group>
</class>
-
- <class name="signal">
- <template>
- <template-type-parameter name="Signature">
- <purpose>Function type R (T1, T2, ..., TN)</purpose>
- </template-type-parameter>
- <template-type-parameter name="Combiner">
- <default><classname>optional_last_value</classname><R></default>
- </template-type-parameter>
- <template-type-parameter name="Group">
- <default>int</default>
- </template-type-parameter>
- <template-type-parameter name="GroupCompare">
- <default><classname>std::less</classname><Group></default>
- </template-type-parameter>
- <template-type-parameter name="SlotFunction">
- <default><classname>function</classname><Signature></default>
- </template-type-parameter>
- <template-type-parameter name="ExtendedSlotFunction">
- <default><classname>function</classname><R (const <classname>connection</classname> &, T1, T2, ..., TN)></default>
- </template-type-parameter>
- <template-type-parameter name="Mutex">
- <default><classname>mutex</classname></default>
- </template-type-parameter>
- </template>
-
- <inherit access="public">
- <type><classname>signalN</classname><R, T1, T2, ..., TN, Combiner, Group, GroupCompare, SlotFunction, ExtendedSlotFunction, Mutex></type>
- </inherit>
- <purpose>Safe multicast callback.</purpose>
-
- <description>
- <para>Class template <classname>signal</classname> is a thin
- wrapper around the numbered class templates <classname
- alt="signalN">signal0</classname>, <classname
- alt="signalN">signal1</classname>, etc. It accepts a function
- type with N arguments instead of N separate arguments, and
- derives from the appropriate <classname>signalN</classname>
- instantiation.</para>
-
- <para>All functionality of this class template is in its base
- class <classname>signalN</classname>.</para>
- <para>
- The large number of template parameters for the <code>signal</code> class
- can be an inconvenience. The
- the <classname>signal_type</classname> metafunction is provided to
- overcome this problem. It uses the Boost.Parameter library
- to permit specification of the <code>signal</code> class' template type parameters
- as named parameters.
- </para>
- </description>
-
- <constructor>
- <parameter name="combiner">
- <paramtype>const combiner_type&</paramtype>
- <default>combiner_type()</default>
- </parameter>
- <parameter name="compare">
- <paramtype>const group_compare_type&</paramtype>
- <default>group_compare_type()</default>
- </parameter>
-
- <effects><para>Initializes the base class with the given combiner
- and comparison objects.</para></effects>
- </constructor>
- <typedef name="signature_type"><type>Signature</type></typedef>
- </class>
</namespace>
</namespace>
</header>
Modified: trunk/libs/signals2/doc/reference/slot.xml
==============================================================================
--- trunk/libs/signals2/doc/reference/slot.xml (original)
+++ trunk/libs/signals2/doc/reference/slot.xml 2009-06-01 13:58:34 EDT (Mon, 01 Jun 2009)
@@ -9,36 +9,41 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
-->
<header name="boost/signals2/slot.hpp" last-revision="$Date: 2007-03-06 16:51:55 -0500 (Tue, 06 Mar 2007) $">
- <using-namespace name="boost"/>
<using-namespace name="boost::signals2"/>
- <using-class name="boost::signals2::signalN"/>
+ <using-namespace name="boost"/>
+ <using-class name="boost::signals2::signal"/>
<using-class name="boost::signals2::slot_base"/>
<namespace name="boost">
<namespace name="signals2">
- <class name="slotN">
+ <class name="slot">
<template>
- <template-type-parameter name="R"/>
- <template-type-parameter name="T1"/>
- <template-type-parameter name="T2"/>
- <template-varargs/>
- <template-type-parameter name="TN"/>
+ <template-type-parameter name="Signature">
+ <purpose>Function type R (T1, T2, ..., TN)</purpose>
+ </template-type-parameter>
<template-type-parameter name="SlotFunction">
- <default><classname>functionN</classname><R, T1, T2, ..., TN></default>
+ <default><classname>boost::function</classname><R (T1, T2, ..., TN)></default>
</template-type-parameter>
</template>
<inherit access="public">
- <type><classname>slot_base</classname></type>
+ <type><classname>boost::signals2::slot_base</classname></type>
</inherit>
<purpose>Pass slots as function arguments, and associate tracked objects with a slot.</purpose>
<description>
- <para>The class template <classname>slotN</classname> covers
- several related classes slot0, slot1, slot2, etc.,
- where the number suffix describes the number of function
- parameters the slot will
- take. Instead of enumerating all classes, a single pattern
- <classname>slotN</classname> will be described, where N
- represents the number of function parameters.</para>
+ <para>A slot consists of a polymorphic function wrapper (<classname>boost::function</classname> by default)
+ plus a container of <code>weak_ptr</code>s which identify the slot's "tracked objects". If any of the
+ tracked objects expire, the slot will automatically disable itself. That is, the slot's function
+ call operator will throw an exception instead of forwarding the function call to the slot's
+ polymorphic function wrapper. Additionally, a slot will automatically lock all the tracked objects
+ as <code>shared_ptr</code> during invocation, to prevent any of them from expiring while
+ the polymorphic function wrapper is being run.
+ </para>
+ <para>
+ The slot constructor will search for <classname>signals2::signal</classname> and
+ <classname>signals2::trackable</classname> inside incoming function objects and
+ automatically track them. It does so by applying a visitor
+ to the incoming functors with <functionname>boost::visit_each</functionname>.
+ </para>
</description>
<typedef name="result_type">
@@ -46,30 +51,42 @@
</typedef>
<typedef name="argument_type">
<type>T1</type>
- <purpose>If N == 1</purpose>
+ <purpose>Exists iff arity == 1</purpose>
</typedef>
<typedef name="first_argument_type">
<type>T1</type>
- <purpose>If N == 2</purpose>
+ <purpose>Exists iff arity == 2</purpose>
</typedef>
<typedef name="second_argument_type">
<type>T2</type>
- <purpose>If N == 2</purpose>
+ <purpose>Exists iff arity == 2</purpose>
+ </typedef>
+ <typedef name="signature_type">
+ <type>Signature</type>
</typedef>
- <typedef name="arg1_type"><type>T1</type></typedef>
- <typedef name="arg2_type"><type>T2</type></typedef>
- <typedef name="..."><type/></typedef>
- <typedef name="argN_type"><type>TN</type></typedef>
<typedef name="slot_function_type">
<type>SlotFunction</type>
</typedef>
+ <class name="arg">
+ <template>
+ <template-nontype-parameter name="n">
+ <type>unsigned</type>
+ </template-nontype-parameter>
+ </template>
+ <typedef name="type">
+ <type>Tn</type>
+ <purpose>The type of the <classname alt="signals2::slot">slot</classname>'s (n+1)th argument</purpose>
+ </typedef>
+ </class>
+
<static-constant name="arity">
<type>int</type>
<default>N</default>
+ <purpose>The number of arguments taken by the slot.</purpose>
</static-constant>
- <constructor>
+ <constructor>
<template>
<template-type-parameter name="Slot"/>
</template>
@@ -86,7 +103,7 @@
constructed.
</para>
<para>In this special case where the template type parameter <code>Slot</code> is
- a compatible <classname>signal</classname> or <classname>signalN</classname> type,
+ a compatible <classname>signals2::signal</classname> type,
the signal will automatically be added to the slot's tracked object list.
Otherwise, the slot's tracked object list is initially empty.
</para>
@@ -94,25 +111,6 @@
</constructor>
<constructor>
<template>
- <template-type-parameter name="OtherR"/>
- <template-type-parameter name="OtherT1"/>
- <template-type-parameter name="OtherT2"/>
- <template-varargs/>
- <template-type-parameter name="OtherTN"/>
- <template-type-parameter name="OtherSlotFunction"/>
- </template>
-
- <parameter name="other_slot">
- <paramtype>const slotN<OtherR, OtherT1, OtherT2, ..., OtherTN, OtherSlotFunction> &</paramtype>
- </parameter>
-
- <effects>
- <para>Initializes <code>this</code> with a copy of
- <code>other_slot</code>'s <code>SlotFunction</code> object and tracked object list.
- </para></effects>
- </constructor>
- <constructor>
- <template>
<template-type-parameter name="OtherSignature"/>
<template-type-parameter name="OtherSlotFunction"/>
</template>
@@ -154,7 +152,7 @@
<effects>
<para>Syntactic sugar for <code>bind()</code> when the constructor is passed more than
one argument. As if:
- <code>slotN(boost::bind(f, a1, a2, ..., aN))</code>
+ <code>slot(boost::bind(f, a1, a2, ..., aN))</code>
</para></effects>
</constructor>
@@ -162,18 +160,18 @@
<overloaded-method name="operator()">
<signature>
<type>result_type</type>
- <parameter name="a1"><paramtype>arg1_type</paramtype></parameter>
- <parameter name="a2"><paramtype>arg2_type</paramtype></parameter>
+ <parameter name="a1"><paramtype>arg<0>::type</paramtype></parameter>
+ <parameter name="a2"><paramtype>arg<1>::_type</paramtype></parameter>
<parameter><paramtype>...</paramtype></parameter>
- <parameter name="aN"><paramtype>argN_type</paramtype></parameter>
+ <parameter name="aN"><paramtype>arg<N-1>::type</paramtype></parameter>
</signature>
<signature cv="const">
<type>result_type</type>
- <parameter name="a1"><paramtype>arg1_type</paramtype></parameter>
- <parameter name="a2"><paramtype>arg2_type</paramtype></parameter>
+ <parameter name="a1"><paramtype>arg<0>::type</paramtype></parameter>
+ <parameter name="a2"><paramtype>arg<1>::_type</paramtype></parameter>
<parameter><paramtype>...</paramtype></parameter>
- <parameter name="aN"><paramtype>argN_type</paramtype></parameter>
+ <parameter name="aN"><paramtype>arg<N-1>::type</paramtype></parameter>
</signature>
<effects><para>Calls the slot's <code>SlotFunction</code> object.
@@ -196,28 +194,28 @@
<method-group name="tracking">
<overloaded-method name="track">
<signature>
- <type>slotN &</type>
+ <type>slot &</type>
<parameter name="tracked_object">
<paramtype>const weak_ptr<void> &</paramtype>
</parameter>
</signature>
<signature>
- <type>slotN &</type>
+ <type>slot &</type>
<parameter name="tracked_signal">
- <paramtype>const <classname>signal_base</classname> &</paramtype>
+ <paramtype>const <classname>signals2::signal_base</classname> &</paramtype>
</parameter>
</signature>
<signature>
- <type>slotN &</type>
+ <type>slot &</type>
<parameter name="tracked_slot">
- <paramtype>const <classname>slot_base</classname> &</paramtype>
+ <paramtype>const <classname>signals2::slot_base</classname> &</paramtype>
</parameter>
</signature>
<effects>
<para>
Adds object(s) to the slot's tracked object list. Should any of the
tracked objects expire, then subsequent attempts to call the slot's <code>operator()</code>
- or <code>lock()</code> methods will throw an <classname>expired_slot</classname> exception.
+ or <code>lock()</code> methods will throw an <classname>signals2::expired_slot</classname> exception.
</para>
<para>When tracking a signal, a <classname>shared_ptr</classname>
internal to the signal class is used for tracking. The signal does not
@@ -246,78 +244,6 @@
</overloaded-method>
</method-group>
</class>
-
- <class name="slot">
- <template>
- <template-type-parameter name="Signature">
- <purpose>Function type R (T1, T2, ..., TN)</purpose>
- </template-type-parameter>
- <template-type-parameter name="SlotFunction">
- <default><classname>function</classname><Signature></default>
- </template-type-parameter>
- </template>
-
- <inherit access="public"><classname>slotN</classname><R, T1, T2, ..., TN, SlotFunction></inherit>
- <purpose>Pass slots as function arguments, and associate tracked objects with a slot.</purpose>
-
- <description>
- <para>Class template <classname>slot</classname> is a thin
- wrapper around the numbered class templates <classname
- alt="slotN">slot0</classname>, <classname
- alt="slotN">slot1</classname>, etc. It accepts a function
- type with N arguments instead of N separate arguments, and
- derives from the appropriate <classname>slotN</classname>
- instantiation.</para>
-
- <para>All functionality of this class template is in its base
- class <classname>slotN</classname>.</para>
- </description>
-
- <constructor>
- <template>
- <template-type-parameter name="F"/>
- </template>
-
- <parameter name="f">
- <paramtype>const F &</paramtype>
- </parameter>
-
- <effects>
- <para>Passes argument to the base type <classname>slotN</classname> constructor.</para>
- </effects>
- </constructor>
- <constructor>
- <template>
- <template-type-parameter name="Func"/>
- <template-type-parameter name="Arg1"/>
- <template-type-parameter name="Arg2"/>
- <template-varargs/>
- <template-type-parameter name="ArgN"/>
- </template>
-
- <parameter name="f">
- <paramtype>const Func &</paramtype>
- </parameter>
- <parameter name="a1">
- <paramtype>const Arg1 &</paramtype>
- </parameter>
- <parameter name="a2">
- <paramtype>const Arg2 &</paramtype>
- </parameter>
- <parameter>
- <paramtype>...</paramtype>
- </parameter>
- <parameter name="aN">
- <paramtype>const ArgN &</paramtype>
- </parameter>
-
- <effects>
- <para>Syntactic sugar for <code>bind()</code> when the constructor is passed more than
- one argument. As if:
- <code>slot(boost::bind(f, a1, a2, ..., aN))</code>
- </para></effects>
- </constructor>
- </class>
</namespace>
</namespace>
</header>
Modified: trunk/libs/signals2/doc/reference/slot_base.xml
==============================================================================
--- trunk/libs/signals2/doc/reference/slot_base.xml (original)
+++ trunk/libs/signals2/doc/reference/slot_base.xml 2009-06-01 13:58:34 EDT (Mon, 01 Jun 2009)
@@ -8,8 +8,8 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
-->
<header name="boost/signals2/slot_base.hpp" last-revision="$Date: 2007-03-06 16:51:55 -0500 (Tue, 06 Mar 2007) $">
- <using-namespace name="boost"/>
<using-namespace name="boost::signals2"/>
+ <using-namespace name="boost"/>
<namespace name="boost">
<namespace name="signals2">
<class name="slot_base">
@@ -55,4 +55,4 @@
</class>
</namespace>
</namespace>
-</header>
\ No newline at end of file
+</header>
Modified: trunk/libs/signals2/doc/reference/trackable.xml
==============================================================================
--- trunk/libs/signals2/doc/reference/trackable.xml (original)
+++ trunk/libs/signals2/doc/reference/trackable.xml 2009-06-01 13:58:34 EDT (Mon, 01 Jun 2009)
@@ -20,9 +20,9 @@
for new code. The <code>trackable</code> class is not thread-safe
since <code>trackable</code> objects disconnect their associated
connections in the <code>trackable</code> destructor.
- The <code>trackable</code> destructor is not run until
+ Since the <code>trackable</code> destructor is not run until
after the destructors of any derived classes have completed,
- which leaves a window where a partially destructed
+ that leaves open a window where a partially destructed
object can still have active connections.
</para>
@@ -30,7 +30,7 @@
The preferred method of automatic connection management
with Boost.Signals2 is to manage the lifetime of
tracked objects with <code>shared_ptr</code>s and
- to use the <methodname alt="slotN::track">slot::track</methodname>
+ to use the <methodname>signals2::slot::track</methodname>
method to track their lifetimes.</para>
<para>The <code>trackable</code> class provides automatic
Modified: trunk/libs/signals2/doc/tests.xml
==============================================================================
--- trunk/libs/signals2/doc/tests.xml (original)
+++ trunk/libs/signals2/doc/tests.xml 2009-06-01 13:58:34 EDT (Mon, 01 Jun 2009)
@@ -21,7 +21,7 @@
<run-test filename="dead_slot_test.cpp">
<lib>../../../libs/test/build/boost_test_exec_monitor</lib>
<purpose>
-<para>Ensure that calling <methodname alt="boost::signals2::signalN::connect">connect</methodname> with a slot
+<para>Ensure that calling <methodname alt="boost::signals2::signal::connect">connect</methodname> with a slot
that has already expired does not actually
connect to the slot.</para>
</purpose>
@@ -53,26 +53,12 @@
to make sure they are fixed and stay fixed.</para></purpose>
</run-test>
- <run-test filename="signal_n_test.cpp">
- <lib>../../../libs/test/build/boost_test_exec_monitor</lib>
- <purpose>
-<para>Basic test of signal/slot connections and invocation using the
-<classname>boost::signals2::signalN</classname> class templates.</para>
- </purpose>
- </run-test>
-
<run-test filename="signal_test.cpp">
<lib>../../../libs/test/build/boost_test_exec_monitor</lib>
<purpose>
<para>Basic test of signal/slot connections and invocation using the
<classname>boost::signals2::signal</classname> class template.</para>
</purpose>
- <if-fails>
-<para>The <classname>boost::signals2::signal</classname> class template may not
-be usable on your compiler. However, the
-<classname>boost::signals2::signalN</classname> class templates may still be
-usable.</para>
- </if-fails>
</run-test>
<run-test filename="track_test.cpp">
Modified: trunk/libs/signals2/doc/thread_safety.xml
==============================================================================
--- trunk/libs/signals2/doc/thread_safety.xml (original)
+++ trunk/libs/signals2/doc/thread_safety.xml 2009-06-01 13:58:34 EDT (Mon, 01 Jun 2009)
@@ -10,8 +10,8 @@
<section last-revision="$Date: 2007-06-12 14:01:23 -0400 (Tue, 12 Jun 2007) $" id="signals2.thread-safety">
<title>Thread-Safety</title>
- <using-namespace name="boost"/>
<using-namespace name="boost::signals2"/>
+ <using-namespace name="boost"/>
<section>
<title>Introduction</title>
@@ -24,7 +24,7 @@
relying on <classname>shared_ptr</classname> and <classname>weak_ptr</classname>,
as described in the <link linkend="signals2.tutorial.connection-management">tutorial</link>.
The second change was the introduction of a <code>Mutex</code> template type
- parameter to the <classname>signal</classname> class. This section details how
+ parameter to the <classname alt="signals2::signal">signal</classname> class. This section details how
the library employs these changes to provide thread-safety, and
the limits of the provided thread-safety.
</para>
@@ -42,7 +42,7 @@
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
- <methodname alt="signalN::operator()">signal::operator()</methodname>,
+ <methodname alt="signal::operator()">signal::operator()</methodname>,
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
@@ -112,7 +112,7 @@
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
- <methodname alt="signalN::set_combiner">signal::set_combiner</methodname>
+ <methodname alt="signal::set_combiner">signal::set_combiner</methodname>
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.
@@ -175,7 +175,7 @@
objects are copies and refer to the same underlying connection.
</para>
<para>
- The <classname alt="slotN">slot</classname> class has no internal mutex locking
+ The <classname>signals2::slot</classname> 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
Modified: trunk/libs/signals2/doc/tutorial.xml
==============================================================================
--- trunk/libs/signals2/doc/tutorial.xml (original)
+++ trunk/libs/signals2/doc/tutorial.xml 2009-06-01 13:58:34 EDT (Mon, 01 Jun 2009)
@@ -11,10 +11,10 @@
<section last-revision="$Date: 2007-06-12 14:01:23 -0400 (Tue, 12 Jun 2007) $" id="signals2.tutorial">
<title>Tutorial</title>
- <using-namespace name="boost"/>
<using-namespace name="boost::signals2"/>
- <using-class name="boost::signals2::signalN"/>
- <using-class name="boost::signals2::slotN"/>
+ <using-namespace name="boost"/>
+ <using-class name="boost::signals2::signal"/>
+ <using-class name="boost::signals2::slot"/>
<section>
<title>How to Read this Tutorial</title>
@@ -36,19 +36,6 @@
will not need to read the <emphasis>Advanced</emphasis> sections.</para>
</section>
-<section><title>Compatibility Note</title>
-
-<para>Boost.Signals2 has two syntactical forms: the preferred form and
-the compatibility form. The preferred form fits more closely with the
-C++ language and reduces the number of separate template parameters
-that need to be considered, often improving readability; however, the
-preferred form is not supported on all platforms due to compiler
-bugs. Users of Boost.Function, please note
-that the preferred syntactic form in Signals2 is equivalent to that of
-Function's preferred syntactic form.</para>
-
-</section>
-
<section><title>Hello, World! (Beginner)</title>
<para>The following example writes "Hello, World!" using signals and
slots. First, we create a signal <code>sig</code>, a signal that
@@ -60,36 +47,8 @@
World!".</para>
<programlisting><xi:include href="hello_world_def_code_snippet.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml"/></programlisting>
- <informaltable>
- <tgroup cols="2" align="left">
- <thead>
- <row>
- <entry>Preferred syntax</entry>
- <entry>Portable syntax</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
<programlisting><xi:include href="hello_world_single_code_snippet.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml"/></programlisting>
-</entry>
-<entry>
-<programlisting> // Signal with no arguments and a void return value
- boost::signals2::signal0<void> sig;
-
- // Connect a HelloWorld slot
- HelloWorld hello;
- sig.connect(hello);
-
- // Call all of the slots
- sig();
-</programlisting>
-</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
</section>
<section><title>Calling Multiple Slots</title>
@@ -110,33 +69,8 @@
<code>void</code> return value. This time, we connect both a
<code>hello</code> and a <code>world</code> slot to the same
signal, and when we call the signal both slots will be called.</para>
- <informaltable>
- <tgroup cols="2" align="left">
- <thead>
- <row>
- <entry>Preferred syntax</entry>
- <entry>Portable syntax</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
<programlisting><xi:include href="hello_world_multi_code_snippet.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml"/></programlisting>
- </entry>
- <entry>
-<programlisting> boost::signals2::signal0<void> sig;
-
- sig.connect(Hello());
- sig.connect(World());
-
- sig();
-</programlisting>
-</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
<para>By default, slots are pushed onto the back of the slot list,
so the output of this program will be as expected:</para>
<programlisting>
@@ -155,31 +89,8 @@
<code>connect</code> call that specifies the group. Group values
are, by default, <code>int</code>s, and are ordered by the integer
< relation. Here's how we construct Hello, World:</para>
- <informaltable>
- <tgroup cols="2" align="left">
- <thead>
- <row>
- <entry>Preferred syntax</entry>
- <entry>Portable syntax</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
<programlisting><xi:include href="hello_world_ordered_code_snippet.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml"/></programlisting>
-</entry>
- <entry>
-<programlisting> boost::signals2::signal0<void> sig;
-
- sig.connect(1, World()); // connect with group 1
- sig.connect(0, Hello()); // connect with group 0</programlisting>
-</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
<para>Invoking the signal will correctly print "Hello, World!", because the
<code>Hello</code> object is in group 0, which precedes group 1 where
the <code>World</code> object resides. The group
@@ -191,7 +102,7 @@
placed at the front or back of the slot list (by passing
<code>boost::signals2::at_front</code> or <code>boost::signals2::at_back</code>
as the last parameter to <code><methodname
-alt="boost::signals2::signalN::connect">connect</methodname></code>, respectively),
+alt="boost::signals2::signal::connect">connect</methodname></code>, respectively),
and default to the end of the list. When
a group is specified, the final <code>at_front</code> or <code>at_back</code>
parameter describes where the slot
@@ -227,36 +138,8 @@
these values.</para>
<programlisting><xi:include href="slot_arguments_slot_defs_code_snippet.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml"/></programlisting>
- <informaltable>
- <tgroup cols="2" align="left">
- <thead>
- <row>
- <entry>Preferred syntax</entry>
- <entry>Portable syntax</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
<programlisting><xi:include href="slot_arguments_main_code_snippet.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml"/></programlisting>
-</entry>
-<entry>
-<programlisting> boost::signals2::signal2<void, float, float> sig;
-
- sig.connect(&print_args);
- sig.connect(&print_sum);
- sig.connect(&print_product);
- sig.connect(&print_difference);
- sig.connect(&print_quotient);
-
- sig(5, 3);</programlisting>
-</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
<para>This program will print out the following:</para>
<programlisting>The arguments are 5 and 3
The sum is 8
@@ -290,26 +173,7 @@
return a value based on these results to be printed:</para>
<programlisting><xi:include href="signal_return_value_slot_defs_code_snippet.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml"/></programlisting>
- <informaltable>
- <tgroup cols="2" align="left">
- <thead>
- <row>
- <entry>Preferred syntax</entry>
- <entry>Portable syntax</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
<programlisting>boost::signals2::signal<float (float, float)> sig;</programlisting>
-</entry>
-<entry>
-<programlisting>boost::signals2::signal2<float, float, float> sig;</programlisting>
-</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
<programlisting><xi:include href="signal_return_value_main_code_snippet.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml"/></programlisting>
@@ -339,33 +203,10 @@
<para>We actually use this new function object type by installing it
as a combiner for our signal. The combiner template argument
follows the signal's calling signature:</para>
- <informaltable>
- <tgroup cols="2" align="left">
- <thead>
- <row>
- <entry>Preferred syntax</entry>
- <entry>Portable syntax</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
<programlisting>
<classname>boost::signals2::signal</classname><float (float x, float y),
maximum<float> > sig;
</programlisting>
-</entry>
-<entry>
-<programlisting>
-<classname alt="boost::signals2::signalN">boost::signals2::signal2</classname><float, float, float,
- maximum<float> > sig;
-</programlisting>
-</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
<para>Now we can connect slots that perform arithmetic functions and
use the signal:</para>
<programlisting><xi:include href="custom_combiners_maximum_usage_code_snippet.xml"
@@ -382,30 +223,9 @@
<para>
Again, we can create a signal with this new combiner:
</para>
- <informaltable>
- <tgroup cols="2" align="left">
- <thead>
- <row>
- <entry>Preferred syntax</entry>
- <entry>Portable syntax</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
<programlisting>
<classname>boost::signals2::signal</classname><float (float, float),
aggregate_values<std::vector<float> > > sig;</programlisting>
-</entry>
-<entry>
-<programlisting>
-<classname alt="boost::signals2::signalN">boost::signals2::signal2</classname><float, float, float,
- aggregate_values<std::vector<float> > > sig;</programlisting>
-</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
<programlisting><xi:include href="custom_combiners_aggregate_values_usage_code_snippet.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml"/></programlisting>
<para>The output of this program will contain 15, 8, 1.6667, and 2. It
@@ -457,7 +277,7 @@
when a slot should no longer be connected.</para>
<para>The entry point for managing connections explicitly is the
<code><classname>boost::signals2::connection</classname></code> class. The
-<code><classname>connection</classname></code> class uniquely represents the connection
+<code>connection</code> class uniquely represents the connection
between a particular signal and a particular slot. The
<code><methodname alt="connection::connected">connected</methodname>()</code> method checks if the signal and slot are
still connected, and the <code><methodname alt="connection::disconnect">disconnect()</methodname></code> method
@@ -502,7 +322,7 @@
<para>
Note, attempts to initialize a scoped_connection with the assignment syntax
will fail due to it being noncopyable. Either the explicit initialization syntax
- or default construction followed by assignment from a <classname>connection</classname>
+ or default construction followed by assignment from a <classname>signals2::connection</classname>
will work:
</para>
<programlisting>
@@ -521,34 +341,14 @@
<section><title>Disconnecting Equivalent Slots (Intermediate)</title>
<para>One can disconnect slots that are equivalent to a given function
object using a form of the
-<code><methodname alt="signalN::disconnect">signal::disconnect</methodname></code> method, so long as
+<code><methodname>signal::disconnect</methodname></code> method, so long as
the type of the function object has an accessible <code>==</code>
operator. For instance:
</para>
<programlisting><xi:include href="disconnect_by_slot_def_code_snippet.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml"/></programlisting>
- <informaltable>
- <tgroup cols="2" align="left">
- <thead>
- <row>
- <entry>Preferred syntax</entry>
- <entry>Portable syntax</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
<programlisting><classname>boost::signals2::signal</classname><void ()> sig;</programlisting>
-</entry>
-<entry>
-<programlisting><classname alt="boost::signals2::signalN">boost::signals2::signal0</classname><void> sig;</programlisting>
-</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
</section>
<programlisting><xi:include href="disconnect_by_slot_usage_code_snippet.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml"/></programlisting>
@@ -561,36 +361,12 @@
where clients connect to a news provider that then sends news to
all connected clients as information arrives. The news delivery
service may be constructed like this: </para>
- <informaltable>
- <tgroup cols="2" align="left">
- <thead>
- <row>
- <entry>Preferred syntax</entry>
- <entry>Portable syntax</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
<programlisting>
class NewsItem { /* ... */ };
typedef boost::signals2::signal<void (const NewsItem&)> signal_type;
signal_type deliverNews;
</programlisting>
-</entry>
-<entry>
-<programlisting>
-class NewsItem { /* ... */ };
-
-typedef boost::signals2::signal1<void, const NewsItem&> signal_type;
-signal_type deliverNews;
-</programlisting>
-</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
<para>Clients that wish to receive news updates need only connect a
function object that can receive news items to the
@@ -621,14 +397,14 @@
<code>deliverNews</code> knows about? Most likely, a segmentation
fault will occur. However, with Boost.Signals2 one may track any object
which is managed by a shared_ptr, by using
-<methodname alt="boost::signals2::slotN::track">slot::track</methodname>. A slot will automatically
+<methodname alt="boost::signals2::slot::track">slot::track</methodname>. A slot will automatically
disconnect when any of its tracked objects expire. In
addition, Boost.Signals2 will ensure that no tracked object expires
while the slot it is associated with is in mid-execution. It does so by creating
temporary shared_ptr copies of the slot's tracked objects before executing it.
To track <code>NewsMessageArea</code>, we use a shared_ptr to manage
its lifetime, and pass the shared_ptr to the slot via its
-<methodname alt="boost::signals2::slotN::track">slot::track</methodname>
+<methodname alt="boost::signals2::slot::track">slot::track</methodname>
method before connecting it,
e.g.:</para>
<programlisting>
@@ -640,7 +416,7 @@
</programlisting>
<para>
Note there is no explicit call to bind() needed in the above example. If the
- <classname alt="slotN">slot</classname> constructor is passed more than one
+ <classname>signals2::slot</classname> constructor is passed more than one
argument, it will automatically pass all the arguments to <code>bind</code> and use the
returned function object.
</para>
@@ -650,7 +426,7 @@
<code>newsMessageArea</code> itself, a copy of the <code>shared_ptr</code> would
have been bound into the slot function, preventing the <code>shared_ptr</code>
from expiring. However, the use of
- <methodname alt="boost::signals2::slotN::track">slot::track</methodname>
+ <methodname alt="boost::signals2::slot::track">slot::track</methodname>
implies we wish to allow the tracked object to expire, and automatically
disconnect the connection when this occurs.
</para>
@@ -807,10 +583,10 @@
</para>
<para>
For a slot to disconnect (or block) its invoking connection, it must have
- access to a <classname>connection</classname> object which references
+ access to a <classname>signals2::connection</classname> object which references
the invoking signal-slot connection. The difficulty is,
- the <classname>connection</classname> object is returned by the
- <methodname alt="signalN::connect">signal::connect</methodname>
+ the <code>connection</code> object is returned by the
+ <methodname>signal::connect</methodname>
method, and therefore is not available until after the slot is
already connected to the signal. This can be particularly troublesome
in a multi-threaded environment where the signal may be invoked
@@ -818,20 +594,20 @@
</para>
<para>
Therefore, the signal classes provide
- <methodname alt="signalN::connect_extended">signal::connect_extended</methodname>
+ <methodname>signal::connect_extended</methodname>
methods, which allow slots which take an extra argument to be connected to a signal.
- The extra argument is a <classname>connection</classname> object which refers
+ The extra argument is a <classname>signals2::connection</classname> object which refers
to the signal-slot connection currently invoking the slot.
- <methodname alt="signalN::connect_extended">signal::connect_extended</methodname>
+ <methodname>signal::connect_extended</methodname>
uses slots of the type given by the
- <classname alt="signalN::extended_slot_type">signal::extended_slot_type</classname>
+ <classname>signal::extended_slot_type</classname>
typedef.
</para>
<para>
The examples section includes an
<link linkend="signals2.examples.tutorial.extended_slot">extended_slot</link>
program which demonstrates the syntax for using
- <methodname alt="signalN::connect_extended">signal::connect_extended</methodname>.
+ <methodname>signal::connect_extended</methodname>.
</para>
</section>
@@ -839,7 +615,7 @@
<title>Changing the <code>Mutex</code> Type of a Signal (Advanced).</title>
<para>
For most cases the default type of <classname>boost::signals2::mutex</classname> for
- a <classname>signal</classname>'s <code>Mutex</code> template type parameter should
+ a <classname>signals2::signal</classname>'s <code>Mutex</code> template type parameter should
be fine. If you wish to use an alternate mutex type, it must be default-constructible
and fulfill the <code>Lockable</code> concept defined by the Boost.Thread library.
That is, it must have <code>lock()</code> and <code>unlock()</code> methods
@@ -847,18 +623,18 @@
but this library does not require try locking).
</para>
<para>
- The Boost.Signals2 library provides one alternate mutex class for use with <classname>signal</classname>:
+ The Boost.Signals2 library provides one alternate mutex class for use with <code>signal</code>:
<classname>boost::signals2::dummy_mutex</classname>. This is a fake mutex for
use in single-threaded programs, where locking a real mutex would be useless
- overhead. Other mutex types you could use with <classname>signal</classname> include
- <classname>boost::mutex</classname> and the <code>std::mutex</code> from
+ overhead. Other mutex types you could use with <code>signal</code> include
+ <classname>boost::mutex</classname>, or the <code>std::mutex</code> from
C++0x.
</para>
<para>
Changing a signal's <code>Mutex</code> template type parameter can be tedious, due to
the large number of template parameters which precede it. The
<classname>signal_type</classname> metafunction is particularly useful in this case,
- since it enables named template type parameters for the <classname>signal</classname>
+ since it enables named template type parameters for the <classname>signals2::signal</classname>
class. For example, to declare a signal which takes an <code>int</code> as
an argument and uses a <classname>boost::signals2::dummy_mutex</classname>
for its <code>Mutex</code> types, you could write:
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk