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

Subject: [Boost-commit] svn:boost r51141 - sandbox/thread_safe_signals/trunk/libs/signals2/doc
From: fmhess_at_[hidden]
Date: 2009-02-09 10:50:15

Author: fmhess
Date: 2009-02-09 10:50:14 EST (Mon, 09 Feb 2009)
New Revision: 51141
URL: http://svn.boost.org/trac/boost/changeset/51141

Log:
Added link from postconstructor section of tutorial
to deconstruct example programs.  Added a warning about
binding a shared_ptr you intended to track to a slot.

Text files modified: 
   sandbox/thread_safe_signals/trunk/libs/signals2/doc/examples.xml |     2 +-                                      
   sandbox/thread_safe_signals/trunk/libs/signals2/doc/tutorial.xml |    25 +++++++++++++++++++++----               
   2 files changed, 22 insertions(+), 5 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 10:50:14 EST (Mon, 09 Feb 2009)
@@ -137,7 +137,7 @@
     </section>
   </section>
   <section id="signals2.examples.deconstruct">
-    <title>Postconstructors and Predestructors with <functionname>deconstruct()</functionname></title>
+    <title>Postconstructors and Predestructors with <code>deconstruct()</code></title>
     <section id="signals2.examples.deconstruct.postconstructor_ex1">
       <title>postconstructor_ex1</title>
       <para>

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 10:50:14 EST (Mon, 09 Feb 2009)
@@ -631,10 +631,22 @@
 deliverNews.<methodname>connect</methodname>(signal_type::slot_type(&amp;NewsMessageArea::displayNews,
   newsMessageArea.get(), _1).track(newsMessageArea));
 </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
-argument, it will automatically pass all the arguments to <code>bind</code> and use the
-returned function object.</para>
+<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
+  argument, it will automatically pass all the arguments to <code>bind</code> and use the
+  returned function object.
+</para>
+<para>Also note, we pass an ordinary pointer as the
+  second argument to the slot constructor, using <code>newsMessageArea.get()</code>
+  instead of passing the <code>shared_ptr</code> itself.  If we had passed the
+  <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>
+  implies we wish to allow the tracked object to expire, and automatically
+  disconnect the connection when this occurs.
+</para>
 </section>
 
   <section id="signals2.tutorial.deconstruct">
@@ -657,6 +669,11 @@
       through the <functionname>deconstruct()</functionname> function, and their
       associated <code>adl_postconstruct()</code> function will always be called.
     </para>
+    <para>The <link linkend="signals2.examples.deconstruct">examples</link> section
+      contains several examples of defining classes with postconstructors and
+      predestructors, and creating objects of these classes using
+      <functionname>deconstruct()</functionname>
+    </para>
     <para>
       Be aware that the postconstructor/predestructor support in Boost.Signals2
       is in no way essential to the use of the library.  The use of