[Boost-commit] svn:boost r51149 - in sandbox/thread_safe_signals/trunk/libs/signals2: doc example

Subject: [Boost-commit] svn:boost r51149 - in sandbox/thread_safe_signals/trunk/libs/signals2: doc example
From: fmhess_at_[hidden]
Date: 2009-02-09 16:03:21

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

Log:
Added example and tutorial section for using extended slots.

Added:
   sandbox/thread_safe_signals/trunk/libs/signals2/example/extended_slot.cpp   (contents, props changed)
Text files modified: 
   sandbox/thread_safe_signals/trunk/libs/signals2/doc/examples.xml |    12 ++++++++++++                            
   sandbox/thread_safe_signals/trunk/libs/signals2/doc/tutorial.xml |    37 +++++++++++++++++++++++++++++++++++++   
   2 files changed, 49 insertions(+), 0 deletions(-)

Modified: sandbox/thread_safe_signals/trunk/libs/signals2/doc/examples.xml
==============================================================================
--- sandbox/thread_safe_signals/trunk/libs/signals2/doc/examples.xml	(original)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/doc/examples.xml	2009-02-09 16:03:20 EST (Mon, 09 Feb 2009)
@@ -97,6 +97,18 @@
         Download <ulink url="../../../../libs/signals2/example/passing_slots.cpp">passing_slots.cpp</ulink>.
       </para>
     </section>
+    <section id="signals2.examples.tutorial.extended_slot">
+      <title>extended_slot</title>
+      <para>
+        This example demonstrates connecting an extended slot to a signal.  An extended slot
+        accepts a reference to its invoking signal-slot connection as an additional argument,
+        permitting the slot to temporarily block or permanently disconnect itself.
+      </para>
+      <para>
+  <!-- FIXME: url needs to have two "../" stripped from it to work once we are merged into main boost doc build -->
+        Download <ulink url="../../../../libs/signals2/example/extended_slot.cpp">extended_slot.cpp</ulink>.
+      </para>
+    </section>
   </section>
   <section id="signals2.examples.document-view">
     <title>Document-View</title>

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-02-09 16:03:20 EST (Mon, 09 Feb 2009)
@@ -788,6 +788,43 @@
   <section id="signals2.tutorial.extended-slot-type">
     <title>Giving a Slot Access to its Connection (Advanced)</title>
     <para>
+      You may encounter situations where you wish to disconnect or block a slot's
+      connection from within the slot itself.  For example, suppose you have a group
+      of asynchronous tasks, each of which emits a signal when it completes.
+      You wish to connect a slot to all the tasks to retrieve their results as
+      each completes.  Once a
+      given task completes and the slot is run, the slot no longer needs to be
+      connected to the completed task.
+      Therefore, you may wish to clean up old connections by having the slot
+      disconnect its invoking connection when it runs.
+    </para>
+    <para>
+      For a slot to disconnect (or block) its invoking connection, it must have
+      access to a <classname>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>
+      method, and therefore is not available until after the slot is
+      already connected to the signal.  This can be particularly troublesome
+      in a multi-threaded environment where the signal may be invoked
+      concurrently by a different thread while the slot is being connected.
+    </para>
+    <para>
+      Therefore, the signal classes provide
+      <methodname alt="signalN::connect_extended">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
+      to the signal-slot connection currently invoking the slot.
+      <methodname alt="signalN::connect_extended">signal::connect_extended</methodname>
+      uses slots of the type given by the
+      <classname alt="signalN::extended_slot_type">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>.
     </para>
   </section>
 

Added: sandbox/thread_safe_signals/trunk/libs/signals2/example/extended_slot.cpp
==============================================================================
--- (empty file)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/example/extended_slot.cpp	2009-02-09 16:03:20 EST (Mon, 09 Feb 2009)
@@ -0,0 +1,41 @@
+// Example program for connecting an extended slot,
+// using a signal's connect_extended and extended_slot_type.
+//
+// Copyright Frank Mori Hess 2009.
+//
+// Use, modification and
+// distribution is subject to 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)
+// For more information, see http://www.boost.org
+
+#include <boost/signals2/signal.hpp>
+#include <iostream>
+#include <string>
+
+namespace bs2 = boost::signals2;
+
+void single_shot_slot(const bs2::connection &conn, const std::string &message)
+{
+  conn.disconnect();
+  std::cout << message;
+}
+
+int main()
+{
+  typedef bs2::signal<void (void)> sig_type;
+  sig_type sig;
+  {
+    sig_type::extended_slot_type hello(&single_shot_slot, _1, "Hello");
+    sig.connect_extended(hello);
+  }
+  sig();  // prints "Hello"
+  {
+    sig_type::extended_slot_type world(&single_shot_slot, _1, ", World!\n");
+    sig.connect_extended(world);
+  }
+  sig();  // only prints ", World!\n" since hello slot has disconnected itself
+  sig();  // prints nothing, world slot has disconnected itself
+
+  return 0;
+};