Subject: [Boost-commit] svn:boost r50781 - in sandbox/thread_safe_signals/trunk/libs/signals2/doc: . reference
From: fmhess_at_[hidden]
Date: 2009-01-25 21:54:03
Author: fmhess
Date: 2009-01-25 21:54:02 EST (Sun, 25 Jan 2009)
New Revision: 50781
URL: http://svn.boost.org/trac/boost/changeset/50781
Log:
Added reference documentation for deconstruct and deconstruct_access.
Added:
sandbox/thread_safe_signals/trunk/libs/signals2/doc/reference/deconstruct.xml (contents, props changed)
Text files modified:
sandbox/thread_safe_signals/trunk/libs/signals2/doc/Makefile | 1 +
sandbox/thread_safe_signals/trunk/libs/signals2/doc/reference/deconstruct_ptr.xml | 24 ++++++++++++++++++------
sandbox/thread_safe_signals/trunk/libs/signals2/doc/reference/reference.xml | 1 +
3 files changed, 20 insertions(+), 6 deletions(-)
Modified: sandbox/thread_safe_signals/trunk/libs/signals2/doc/Makefile
==============================================================================
--- sandbox/thread_safe_signals/trunk/libs/signals2/doc/Makefile (original)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/doc/Makefile 2009-01-25 21:54:02 EST (Sun, 25 Jan 2009)
@@ -13,6 +13,7 @@
thread_safety.xml \
tutorial.xml \
reference/connection.xml \
+ reference/deconstruct.xml \
reference/deconstruct_ptr.xml \
reference/dummy_mutex.xml \
reference/last_value.xml \
Added: sandbox/thread_safe_signals/trunk/libs/signals2/doc/reference/deconstruct.xml
==============================================================================
--- (empty file)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/doc/reference/deconstruct.xml 2009-01-25 21:54:02 EST (Sun, 25 Jan 2009)
@@ -0,0 +1,119 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE header PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
+ "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+<header name="boost/signals2/deconstruct.hpp" last-revision="$Date: 2007-03-06 16:51:55 -0500 (Tue, 06 Mar 2007) $">
+ <using-namespace name="boost"/>
+ <using-namespace name="boost::signals2"/>
+ <namespace name="boost">
+ <namespace name="signals2">
+ <overloaded-function name="deconstruct">
+ <signature>
+ <template>
+ <template-type-parameter name="T"/>
+ </template>
+ <type>shared_ptr<T></type>
+ </signature>
+ <signature>
+ <template>
+ <template-type-parameter name="T"/>
+ <template-type-parameter name="A1"/>
+ </template>
+ <type>shared_ptr<T></type>
+ <parameter name="arg1"><paramtype>const A1 &</paramtype></parameter>
+ </signature>
+ <signature>
+ <template>
+ <template-type-parameter name="T"/>
+ <template-type-parameter name="A1"/>
+ <template-type-parameter name="A2"/>
+ </template>
+ <type>shared_ptr<T></type>
+ <parameter name="arg1"><paramtype>const A1 &</paramtype></parameter>
+ <parameter name="arg2"><paramtype>const A2 &</paramtype></parameter>
+ </signature>
+ <signature>
+ <template>
+ <template-type-parameter name="T"/>
+ <template-type-parameter name="A1"/>
+ <template-type-parameter name="A2, ..."/>
+ <template-type-parameter name="AN"/>
+ </template>
+ <type>shared_ptr<T></type>
+ <parameter name="arg1"><paramtype>const A1 &</paramtype></parameter>
+ <parameter name="arg2"><paramtype>const A2 &</paramtype></parameter>
+ <parameter name=""><paramtype>...</paramtype></parameter>
+ <parameter name="argN"><paramtype>const AN &</paramtype></parameter>
+ <purpose>this is my purpose</purpose>
+ </signature>
+
+ <purpose>Create a <code>shared_ptr</code> which supports post-constructors and pre-destructors.</purpose>
+
+ <effects>
+ <para>Creates a <code>shared_ptr<T></code> and its owned object using only a single allocation,
+ in a manner similar
+ to that of <functionname>boost::make_shared()</functionname>. In addition, <code>deconstruct</code>
+ supports postconstructors and predestructors for types derived from either the
+ <classname>postconstructible</classname> or <classname>predestructible</classname> base classes.
+ If <code>T</code> is derived from <classname>postconstructible</classname>
+ then <code>postconstruct()</code> will be called on the newly constructed object
+ after it is passed to its owning <code>shared_ptr</code>.
+ If <code>T</code> is derived from <classname>predestructible</classname>
+ then the deleter of the returned <classname>shared_ptr</classname> will call
+ <code>predestruct()</code> on the owned object prior to deleting it with
+ <functionname>checked_delete</functionname>.
+ </para>
+ <para>
+ Any arguments passed to a
+ <code>deconstruct()</code> call are forwarded to the matching constructor of the
+ template type
+ <code>T</code>.
+ </para>
+ </effects>
+ <notes>
+ <para>If your compiler supports the C++0x features of rvalue references
+ and variadic templates, then <code>deconstruct</code> will perform perfect
+ forwarding of arguments to the <code>T</code> constructor, using
+ a prototype of:
+ </para>
+ <programlisting>template< typename T, typename... Args > boost::shared_ptr< T > deconstruct( Args && ... args );</programlisting>
+ <para>Otherwise, argument forwarding is performed via const references, as specified in
+ the synopsis. In order to pass non-const references to a constructor, you will need
+ to wrap them in reference wrappers using <functionname>boost::ref</functionname>.
+ </para>
+ <para>You may give all the <code>deconstruct</code> overloads access to your class'
+ private and protected constructors by
+ declaring <classname>deconstruct_access</classname> a friend. Using private
+ constructors in conjunction with <classname>deconstruct_access</classname>
+ can be useful to
+ ensure <classname>postconstructible</classname> or <classname>predestructible</classname>
+ objects are always created
+ properly using <code>deconstruct</code>.
+ </para>
+ <para>
+ See also <functionname>deconstruct_ptr</functionname>, which is similar to <code>deconstruct</code>,
+ except it more closely resembles the constructors of <classname>shared_ptr</classname> rather
+ than the <functionname>boost::make_shared</functionname> factory function.
+ </para>
+ </notes>
+ <returns><para>A <code>shared_ptr<T></code> owning a newly allocated object of
+ type <code>T</code>.</para>
+ </returns>
+ </overloaded-function>
+ <class name="deconstruct_access">
+ <purpose>Gives <functionname>deconstruct</functionname> access to private/protected constructors.</purpose>
+ <description>
+ <para>
+ Declaring <code>deconstruct_access</code> a friend to your class will give the
+ <functionname>deconstruct</functionname> factory function access to your class' private and
+ protected constructors. Using private
+ constructors in conjunction with <code>deconstruct_access</code>
+ can be useful to
+ ensure <classname>postconstructible</classname> or <classname>predestructible</classname>
+ objects are always created
+ properly using <code>deconstruct</code>.
+ </para>
+ </description>
+ </class>
+ </namespace>
+ </namespace>
+</header>
Modified: sandbox/thread_safe_signals/trunk/libs/signals2/doc/reference/deconstruct_ptr.xml
==============================================================================
--- sandbox/thread_safe_signals/trunk/libs/signals2/doc/reference/deconstruct_ptr.xml (original)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/doc/reference/deconstruct_ptr.xml 2009-01-25 21:54:02 EST (Sun, 25 Jan 2009)
@@ -26,13 +26,25 @@
<purpose>Create a <code>shared_ptr</code> which supports post-constructors and pre-destructors.</purpose>
- <effects><para>Creates a <code>shared_ptr<T></code> by passing the <code>pointer</code> and
- <code>deleter</code> parameters to the <code>shared_ptr</code> constructor. If no
- <code>deleter</code> is specified, then <classname>predestructing_deleter</classname> is
- used as the default. If <code>T</code> is derived from <classname>postconstructible</classname>
- (and <code>pointer</code> is not a null pointer),
- then <code>pointer->postconstruct()</code> will be called after the <code>shared_ptr</code> is constructed.</para>
+ <effects>
+ <para>Creates a <code>shared_ptr<T></code> by passing the <code>pointer</code> and
+ <code>deleter</code> parameters to the <code>shared_ptr</code> constructor. If no
+ <code>deleter</code> is specified, then <classname>predestructing_deleter</classname> is
+ used as the default. If <code>T</code> is derived from <classname>postconstructible</classname>
+ (and <code>pointer</code> is not a null pointer),
+ then <code>pointer->postconstruct()</code> will be called after the <code>shared_ptr</code> is constructed.
+ </para>
</effects>
+ <notes>
+ <para>
+ See also <functionname>deconstruct</functionname>, which is similar to <code>deconstruct_ptr</code>,
+ except it resembles the <functionname>boost::make_shared</functionname> factory function
+ rather than the constructors of <classname>shared_ptr</classname>. The
+ <functionname>deconstruct</functionname> factory function creates the
+ <classname>shared_ptr</classname> and the object it owns efficiently with a single allocation,
+ and can be given access to private or protected constructors.
+ </para>
+ </notes>
<returns><para>A <code>shared_ptr<T></code> owning <code>pointer</code>.</para></returns>
</overloaded-function>
Modified: sandbox/thread_safe_signals/trunk/libs/signals2/doc/reference/reference.xml
==============================================================================
--- sandbox/thread_safe_signals/trunk/libs/signals2/doc/reference/reference.xml (original)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/doc/reference/reference.xml 2009-01-25 21:54:02 EST (Sun, 25 Jan 2009)
@@ -11,6 +11,7 @@
</header>
<xi:include href="connection.xml"/>
+ <xi:include href="deconstruct.xml"/>
<xi:include href="deconstruct_ptr.xml"/>
<xi:include href="dummy_mutex.xml"/>
<xi:include href="last_value.xml"/>