Boost logo

Boost-Commit :

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">


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