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 &</type>
+ <parameter name="tracked_object">
+ <paramtype>const ForeignWeakPtr &</paramtype>
+ </parameter>
+ <parameter name="SFINAE">
+ <paramtype>typename weak_ptr_traits<ForeignWeakPtr>::shared_type *</paramtype>
+ <default>0</default>
+ </parameter>
+ </signature>
+ <signature>
+ <template>
+ <template-type-parameter name="ForeignSharedPtr"/>
+ </template>
+ <type>slot &</type>
+ <parameter name="tracked_object">
+ <paramtype>const ForeignSharedPtr &</paramtype>
+ </parameter>
+ <parameter name="SFINAE">
+ <paramtype>typename shared_ptr_traits<ForeignSharedPtr>::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">