[Boost-commit] svn:boost r65532 - in trunk/libs/signals2/doc: . reference

Subject: [Boost-commit] svn:boost r65532 - in trunk/libs/signals2/doc: . reference
From: fmhess_at_[hidden]
Date: 2010-09-22 10:49:27

Author: fmhess
Date: 2010-09-22 10:49:23 EDT (Wed, 22 Sep 2010)
New Revision: 65532
URL: http://svn.boost.org/trac/boost/changeset/65532

Log:
Added docs for new slot::track_foreign method.

Text files modified: 
   trunk/libs/signals2/doc/porting.xml        |     8 +++++                                   
   trunk/libs/signals2/doc/reference/slot.xml |    55 ++++++++++++++++++++++++++++++++++++++++
   trunk/libs/signals2/doc/tutorial.xml       |     5 +++                                     
   3 files changed, 68 insertions(+), 0 deletions(-)

Modified: trunk/libs/signals2/doc/porting.xml
==============================================================================
--- trunk/libs/signals2/doc/porting.xml	(original)
+++ trunk/libs/signals2/doc/porting.xml	2010-09-22 10:49:23 EDT (Wed, 22 Sep 2010)
@@ -227,6 +227,14 @@
   </section>
   <section id="signals2.api_history">
     <title>Signals2 API Development</title>
+    <section id="signals2.api_history.1-45">
+      <title>Version 1.4x</title>
+      <para>
+        Version 1.45 added <methodname>slot::track_foreign</methodname>().  This method allows tracking
+        of objects owned by <code>shared_ptr</code> classes other than <classname>boost::shared_ptr</classname>,
+        for example <classname>std::shared_ptr</classname>.
+      </para>
+    </section>
     <section id="signals2.api_history.1-40">
       <title>Version 1.40</title>
       <para>

Modified: trunk/libs/signals2/doc/reference/slot.xml
==============================================================================
--- trunk/libs/signals2/doc/reference/slot.xml	(original)
+++ trunk/libs/signals2/doc/reference/slot.xml	2010-09-22 10:49:23 EDT (Wed, 22 Sep 2010)
@@ -230,6 +230,61 @@
             </effects>
             <returns><para><code>*this</code></para></returns>
           </overloaded-method>
+          <overloaded-method name="track_foreign">
+            <signature>
+              <template>
+                <template-type-parameter name="ForeignWeakPtr"/>
+              </template>
+              <type>slot &amp;</type>
+              <parameter name="tracked_object">
+                <paramtype>const ForeignWeakPtr &amp;</paramtype>
+              </parameter>
+              <parameter name="SFINAE">
+                <paramtype>typename weak_ptr_traits&lt;ForeignWeakPtr&gt;::shared_type *</paramtype>
+                <default>0</default>
+              </parameter>
+            </signature>
+            <signature>
+              <template>
+                <template-type-parameter name="ForeignSharedPtr"/>
+              </template>
+              <type>slot &amp;</type>
+              <parameter name="tracked_object">
+                <paramtype>const ForeignSharedPtr &amp;</paramtype>
+              </parameter>
+              <parameter name="SFINAE">
+                <paramtype>typename shared_ptr_traits&lt;ForeignSharedPtr&gt;::weak_type *</paramtype>
+                <default>0</default>
+              </parameter>
+            </signature>
+            <effects>
+              <para>
+                The <code>track_foreign</code>() method behaves similarly to calling the <methodname>track</methodname>() method
+                with a <classname>boost::shared_ptr</classname> or <classname>boost::weak_ptr</classname> argument.
+                However, <code>track_foreign</code> is more flexible in that it will accept <code>shared_ptr</code>
+                or <code>weak_ptr</code> classes from outside of boost (most significantly <code>std::shared_ptr</code>
+                or <code>std::weak_ptr</code>).
+              </para>
+              <para>
+                In order to use a particular <code>shared_ptr</code> class with this function, a specialization of
+                <classname>boost::signals2::shared_ptr_traits</classname> must exist for it.
+                Also, a specialization of <classname>boost::signals2::weak_ptr_traits</classname> must
+                be provided for its corresponding <code>weak_ptr</code> class.
+                The <code>shared_ptr_traits</code> specialization must include a <code>weak_type</code>
+                member typedef which specifies the
+                corresponding <code>weak_ptr</code> type of the <code>shared_ptr</code> class.
+                Similarly, the <code>weak_ptr_traits</code> specialization must include a <code>shared_type</code>
+                member typedef which specifies the corresponding <code>shared_ptr</code> type of the
+                <code>weak_ptr</code> class.  Specializations
+                for <code>std::shared_ptr</code> and <code>std::weak_ptr</code> are already provided by the signals2 library.
+                For other <code>shared_ptr</code> classes, you must provide the specializations.
+              </para>
+              <para>The second argument "SFINAE" may be ignored, it is used to resolve the overload between
+                either <code>shared_ptr</code> or <code>weak_ptr</code> objects passed in as the first argument.
+              </para>
+            </effects>
+            <returns><para><code>*this</code></para></returns>
+          </overloaded-method>
         </method-group>
 
         <method-group name="slot function access">

Modified: trunk/libs/signals2/doc/tutorial.xml
==============================================================================
--- trunk/libs/signals2/doc/tutorial.xml	(original)
+++ trunk/libs/signals2/doc/tutorial.xml	2010-09-22 10:49:23 EDT (Wed, 22 Sep 2010)
@@ -430,6 +430,11 @@
   implies we wish to allow the tracked object to expire, and automatically
   disconnect the connection when this occurs.
 </para>
+<para>
+  <code>shared_ptr</code> classes other than <classname>boost::shared_ptr</classname>
+  (such as <code>std::shared_ptr</code>) may also be tracked for connection management
+  purposes.  They are supported by the <methodname>slot::track_foreign</methodname> method.
+</para>
 </section>
 
   <section id="signals2.tutorial.deconstruct">