|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r50646 - sandbox/thread_safe_signals/trunk/libs/signals2/doc
From: fmhess_at_[hidden]
Date: 2009-01-16 17:44:52
Author: fmhess
Date: 2009-01-16 17:44:51 EST (Fri, 16 Jan 2009)
New Revision: 50646
URL: http://svn.boost.org/trac/boost/changeset/50646
Log:
Starting to address some of the documentation weaknesses pointed
out during review. Added a section on portinf from Boost.Signals
based on one of the faq entries.
Added:
sandbox/thread_safe_signals/trunk/libs/signals2/doc/porting.xml (contents, props changed)
Text files modified:
sandbox/thread_safe_signals/trunk/libs/signals2/doc/Makefile | 1
sandbox/thread_safe_signals/trunk/libs/signals2/doc/design.xml | 2
sandbox/thread_safe_signals/trunk/libs/signals2/doc/faq.xml | 90 +--------------------------------------
sandbox/thread_safe_signals/trunk/libs/signals2/doc/introduction.xml | 2
sandbox/thread_safe_signals/trunk/libs/signals2/doc/rationale.xml | 18 ++++----
sandbox/thread_safe_signals/trunk/libs/signals2/doc/signals.xml | 2
sandbox/thread_safe_signals/trunk/libs/signals2/doc/tutorial.xml | 2
7 files changed, 19 insertions(+), 98 deletions(-)
Modified: sandbox/thread_safe_signals/trunk/libs/signals2/doc/Makefile
==============================================================================
--- sandbox/thread_safe_signals/trunk/libs/signals2/doc/Makefile (original)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/doc/Makefile 2009-01-16 17:44:51 EST (Fri, 16 Jan 2009)
@@ -7,6 +7,7 @@
design.xml \
faq.xml \
introduction.xml \
+ porting.xml \
rationale.xml \
signals.xml \
tests.xml \
Modified: sandbox/thread_safe_signals/trunk/libs/signals2/doc/design.xml
==============================================================================
--- sandbox/thread_safe_signals/trunk/libs/signals2/doc/design.xml (original)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/doc/design.xml 2009-01-16 17:44:51 EST (Fri, 16 Jan 2009)
@@ -1,7 +1,7 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
-<section last-revision="$Date: 2007-06-12 14:01:23 -0400 (Tue, 12 Jun 2007) $">
+<section last-revision="$Date: 2007-06-12 14:01:23 -0400 (Tue, 12 Jun 2007) $" id="signals2.design">
<title>Design Overview</title>
<using-namespace name="boost"/>
Modified: sandbox/thread_safe_signals/trunk/libs/signals2/doc/faq.xml
==============================================================================
--- sandbox/thread_safe_signals/trunk/libs/signals2/doc/faq.xml (original)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/doc/faq.xml 2009-01-16 17:44:51 EST (Fri, 16 Jan 2009)
@@ -1,7 +1,7 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
-<section last-revision="$Date: 2007-06-12 14:01:23 -0400 (Tue, 12 Jun 2007) $">
+<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"/>
@@ -34,93 +34,11 @@
That is, the objects will need to be owned by
<classname>shared_ptr</classname> and passed to the slot's
<methodname alt="slotN::track">track</methodname>() method before the slot is connected.
+ The <classname>trackable</classname> scheme of automatic connection management
+ is NOT thread-safe, and is only provided to ease porting of single-threaded
+ code from Boost.Signals to Boost.Signals2.
</para>
</answer>
</qandaentry>
- <qandaentry>
- <question><para>How has the API changed from the original Boost.Signals?</para></question>
- <answer>
- <para>In summary, the following changes have been made to the signals API:</para>
- <itemizedlist>
- <listitem>
- <para>
- Automatic connection management is achieved through the use of <classname>shared_ptr</classname>/<classname>weak_ptr</classname>
- and <methodname alt="slotN::track">slot::track</methodname>(), as opposed to the old <code>boost::trackable</code>
- base class.
- </para>
- </listitem>
- <listitem>
- <para>
- The <classname>slot</classname> class takes a new <code>Signature</code> template parameter,
- is useable as a function object, and is generally more featureful.
- </para>
- </listitem>
- <listitem>
- <para>
- The <classname>optional_last_value</classname> has replaced <classname>last_value</classname>
- as the default combiner for signals.
- </para>
- <para>
- The <classname>last_value</classname> combiner is still provided, and it
- throws an exception instead of requiring at least one slot to be connected
- on signal invocation (except for its void specialization which does not require any
- slots to be connected).
- </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 an
- additional ExtendedSlotFunction template parameter for specifying the underlying slot function
- type for the new extended slots.
- </para>
- </listitem>
- <listitem>
- <para>
- The <classname>signal</classname> class has an additional template parameter for specifying
- the mutex type used internally by the signal.
- </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>
- </listitem>
- <listitem>
- <para><code>boost::visit_each</code>, which was used to find <code>boost::trackable</code> objects,
- is gone.
- </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.
- </para>
- </listitem>
- <listitem>
- <para>Support for postconstructors (and predestructors) on objects managed by <classname>shared_ptr</classname>
- has been added with
- <functionname>deconstruct_ptr</functionname>, <classname>postconstructible</classname>,
- and <classname>predestructible</classname>. 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.
- </para>
- </listitem>
- <listitem>
- <para>The namespace <code>boost::signals</code> has been replaced by <code>boost::signals2</code>
- to avoid conflict with the original Signals implementation, and the Qt "signals" macro.
- Also, some classes and headers
- have been moved to comply with Boost's guidelines. For example, the signal class is now
- in the boost::signals2 namespace instead of the boost namespace,
- and it's header file is now at boost/signals2/signal.hpp instead of boost/signal.hpp.
- </para>
- </listitem>
- </itemizedlist>
- </answer>
- </qandaentry>
</qandaset>
</section>
Modified: sandbox/thread_safe_signals/trunk/libs/signals2/doc/introduction.xml
==============================================================================
--- sandbox/thread_safe_signals/trunk/libs/signals2/doc/introduction.xml (original)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/doc/introduction.xml 2009-01-16 17:44:51 EST (Fri, 16 Jan 2009)
@@ -26,7 +26,7 @@
combined.</para>
<section>
- <title>Signals2 (formerly known as thread_safe_signals)</title>
+ <title>Signals2</title>
<para>This documentation describes a thread-safe variant of the
original Boost.Signals library. There have been some changes to
the interface to support thread-safety, mostly with respect to
Added: sandbox/thread_safe_signals/trunk/libs/signals2/doc/porting.xml
==============================================================================
--- (empty file)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/doc/porting.xml 2009-01-16 17:44:51 EST (Fri, 16 Jan 2009)
@@ -0,0 +1,201 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
+ "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+<section last-revision="$Date: 2007-06-12 14:01:23 -0400 (Tue, 12 Jun 2007) $" id="signals2.porting">
+ <title>Porting from Boost.Signals to Boost.Signals2</title>
+
+ <using-namespace name="boost"/>
+ <using-namespace name="boost::signals2"/>
+
+ <para>The changes made to the Boost.Signals2 API compared to the original Boost.Signals
+ library are summarized below. We also provide some notes on
+ dealing with each change while porting existing Boost.Signals code to Boost.Signals2.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>The namespace <code>boost::signals</code> has been replaced by <code>boost::signals2</code>
+ to avoid conflict with the original Boost.Signals implementation, as well as the Qt "signals" macro.
+ All the Boost.Signals2 classes are inside the <code>boost::signals2</code> namespace,
+ unlike the original Boost.Signals which has some classes in the <code>boost</code>
+ namespace in addition to its own <code>boost::signals</code> namespace.
+ </para>
+ <para>
+ The Boost.Signals2 header files are contained in the
+ <code>boost/signals2/</code> subdirectory instead of the <code>boost/signals</code>
+ subdirectory used by the original Boost.Signals. Furthermore, all the headers except
+ for the convenience header <code>boost/signals2.hpp</code> are inside the
+ <code>boost/signals2/</code> subdirectory, unlike the original Boost.Signals which
+ keeps a few headers in the parent <code>boost/</code> directory
+ in addition to its own <code>boost/signals/</code> subdirectory.
+ </para>
+ <para>
+ For example, the <code>signal</code> class is now
+ in the <code>boost::signals2</code> namespace instead of the
+ <code>boost</code> namespace,
+ and it's header file is now at <code>boost/signals2/signal.hpp</code> instead of
+ <code>boost/signal.hpp</code>.
+ </para>
+ <para>
+ While porting, only trivial changes to <code>#include</code> directives
+ and namespace qualifications should be required to deal with these changes.
+ Furthermore, the new namespace and header locations for Boost.Signals2
+ allow it to coexist in the same program with the original Boost.Signals library,
+ and porting can be performed piecemeal.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Automatic connection management is now achieved through the use of
+ <classname>shared_ptr</classname>/<classname>weak_ptr</classname>
+ and <methodname alt="slotN::track">slot::track</methodname>(), as described in the
+ <link linkend="signals2.tutorial.connection-management">tutorial</link>.
+ However, the old (thread-unsafe) Boost.Signals scheme of automatic connection management
+ is still supported via the <classname>boost::signals2::trackable</classname> class.
+ </para>
+ <para>
+ If you do not intend to make your program multi-threaded, the easiest porting path is to simply replace
+ your uses of <code>boost::signals::trackable</code> as a base class with
+ <code>boost::signals2::trackable</code>. 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>
+ The <classname>slot</classname> class takes a new <code>Signature</code> template parameter,
+ is useable as a function object, and is 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> 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 do 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 on. 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" <code>combiner</code> and <code>set_combiner</code> functions.
+ However, it will require each call of the <code>combiner</code> method in your code
+ to be inspected manually, 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;
+//...
+
+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::shared_connection_block blocker(my_connection);
+ do_something();
+} // blocker goes out of scope here and releases its block on my_connection
+</programlisting>
+ </listitem>
+ <listitem>
+ <para>Support for postconstructors (and predestructors) on objects managed by <classname>shared_ptr</classname>
+ has been added with
+ <functionname>deconstruct_ptr</functionname>, <classname>postconstructible</classname>,
+ and <classname>predestructible</classname>. 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.
+ </para>
+ </listitem>
+ </itemizedlist>
+</section>
Modified: sandbox/thread_safe_signals/trunk/libs/signals2/doc/rationale.xml
==============================================================================
--- sandbox/thread_safe_signals/trunk/libs/signals2/doc/rationale.xml (original)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/doc/rationale.xml 2009-01-16 17:44:51 EST (Fri, 16 Jan 2009)
@@ -1,7 +1,7 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
-<section last-revision="$Date: 2007-06-12 14:01:23 -0400 (Tue, 12 Jun 2007) $">
+<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"/>
@@ -91,17 +91,17 @@
<para>Automatic connection management in Signals2
depends on the use of <classname>boost::shared_ptr</classname> to
manage the lifetimes of tracked objects. This is differs from
- the original Boost.Signals2 library, which instead relied on derivation
- from the <code><classname>boost::trackable</classname></code> class.
- The Boost.Signals2 library would be
+ the original Boost.Signals library, which instead relied on derivation
+ from the <code><classname>boost::signals::trackable</classname></code> class.
+ The library would be
notified of an object's destruction by the
- <code><classname>trackable</classname></code> destructor.
+ <code><classname>boost::signals::trackable</classname></code> destructor.
</para>
- <para>Unfortunately, the <code><classname>trackable</classname></code>
+ <para>Unfortunately, the <code><classname>boost::signals::trackable</classname></code>
scheme cannot be made thread safe due
to destructor ordering. The destructor of an class derived from
- <code><classname>trackable</classname></code> will always be
- called before the destructor of the base <code><classname>trackable</classname></code>
+ <code><classname>boost::signals::trackable</classname></code> will always be
+ called before the destructor of the base <code><classname>boost::signals::trackable</classname></code>
class. However, for thread-safety the connection between the signal and object
needs to be disconnected before the object runs its destructors.
Otherwise, if an object being destroyed
@@ -116,7 +116,7 @@
<classname>weak_ptr</classname>s expire. Additionally, signals
create their own temporary <classname>shared_ptr</classname>s to
all of a slot's tracked objects prior to invoking the slot. This
- insures none of the tracked objects from destruct in mid-invocation.
+ insures none of the tracked objects destruct in mid-invocation.
</para>
</section>
Modified: sandbox/thread_safe_signals/trunk/libs/signals2/doc/signals.xml
==============================================================================
--- sandbox/thread_safe_signals/trunk/libs/signals2/doc/signals.xml (original)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/doc/signals.xml 2009-01-16 17:44:51 EST (Fri, 16 Jan 2009)
@@ -27,6 +27,7 @@
<copyright>
<year>2007</year>
<year>2008</year>
+ <year>2009</year>
<holder>Frank Mori Hess</holder>
</copyright>
@@ -48,5 +49,6 @@
<xi:include href="faq.xml"/>
<xi:include href="design.xml"/>
<xi:include href="rationale.xml"/>
+ <xi:include href="porting.xml"/>
<xi:include href="tests.xml"/>
</library>
Modified: sandbox/thread_safe_signals/trunk/libs/signals2/doc/tutorial.xml
==============================================================================
--- sandbox/thread_safe_signals/trunk/libs/signals2/doc/tutorial.xml (original)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/doc/tutorial.xml 2009-01-16 17:44:51 EST (Fri, 16 Jan 2009)
@@ -758,7 +758,7 @@
</section>
-<section><title>Automatic connection management (Intermediate)</title>
+<section id="signals2.tutorial.connection-management"><title>Automatic connection management (Intermediate)</title>
<para>Boost.Signals2 can automatically track the lifetime of objects
involved in signal/slot connections, including automatic
disconnection of slots when objects involved in the slot call are
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