[Boost-commit] svn:boost r51150 - sandbox/thread_safe_signals/trunk/libs/signals2/doc

Subject: [Boost-commit] svn:boost r51150 - sandbox/thread_safe_signals/trunk/libs/signals2/doc
From: fmhess_at_[hidden]
Date: 2009-02-09 16:37:44

Author: fmhess
Date: 2009-02-09 16:37:44 EST (Mon, 09 Feb 2009)
New Revision: 51150
URL: http://svn.boost.org/trac/boost/changeset/51150

Log:
Added paragraphs to rationale about optional_last_value
and mutex types.

Text files modified: 
   sandbox/thread_safe_signals/trunk/libs/signals2/doc/faq.xml       |     3 +++                                     
   sandbox/thread_safe_signals/trunk/libs/signals2/doc/rationale.xml |    35 ++++++++++++++++++++++++++++++++++-     
   2 files changed, 37 insertions(+), 1 deletions(-)

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-02-09 16:37:44 EST (Mon, 09 Feb 2009)
@@ -38,6 +38,9 @@
           is NOT thread-safe, and is only provided to ease porting of single-threaded
           code from Boost.Signals to Boost.Signals2.
         </para>
+        <para>See the documentation section on <link linkend="signals2.thread-safety">thread-safety</link>
+          for more information.
+        </para>
       </answer>
     </qandaentry>
   </qandaset>

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-02-09 16:37:44 EST (Mon, 09 Feb 2009)
@@ -114,6 +114,21 @@
   </section>
 
   <section>
+    <title><code>optional_last_value</code> as the Default Combiner</title>
+    <para>
+      The default combiner for Boost.Signals2 has changed from the <code>last_value</code>
+      combiner used as the default by the original Boost.Signals library.
+      This is because <code>last_value</code> requires that at least 1 slot be
+      connected to a signal when it is invoked (except for its void specialization).
+      In a multi-threaded environment where signal invocations and slot connections
+      and disconnections may be happening concurrently, it is difficult
+      to fulfill this requirement.  When using <classname>optional_last_value</classname>,
+      there is no requirement for any slots to be connected when a signal
+      is invoked, since in that case the combiner may simply return an empty
+      <classname>boost::optional</classname>.
+    </para>
+  </section>
+  <section>
     <title>Combiner Interface</title>
 
     <para> The Combiner interface was chosen to mimic a call to an
@@ -297,7 +312,25 @@
       </listitem>
     </itemizedlist>
   </section>
-
+  <section>
+    <title>Signals2 Mutex Classes</title>
+    <para>
+      The Boost.Signals2 library provides 2 mutex classes: <classname>boost::signals2::mutex</classname>,
+      and <classname>boost::signals2::dummy_mutex</classname>.  The motivation for providing
+      <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>
+      if you wish, by specifying it as the <code>Mutex</code> template type for your signals.
+    </para>
+    <para>
+      The <classname>boost::signals2::dummy_mutex</classname> class is provided to allow
+      performance sensitive single-threaded applications to minimize overhead by avoiding unneeded
+      mutex locking.
+    </para>
+  </section>
   <section>
     <title>Comparison with other Signal/Slot implementations</title>