123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219 |
- <?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">
- <!--
- Copyright Frank Mori Hess 2009
- Distributed under the Boost Software License, Version 1.0. (See accompanying
- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
- -->
- <header name="boost/signals2/deconstruct.hpp" last-revision="$Date: 2007-03-06 16:51:55 -0500 (Tue, 06 Mar 2007) $">
- <using-namespace name="boost::signals2"/>
- <using-namespace name="boost"/>
- <namespace name="boost">
- <namespace name="signals2">
- <overloaded-function name="deconstruct">
- <signature>
- <template>
- <template-type-parameter name="T"/>
- </template>
- <type><classname>postconstructor_invoker</classname><T></type>
- </signature>
- <signature>
- <template>
- <template-type-parameter name="T"/>
- <template-type-parameter name="A1"/>
- </template>
- <type><classname>postconstructor_invoker</classname><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><classname>postconstructor_invoker</classname><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><classname>postconstructor_invoker</classname><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>
- </signature>
- <purpose>Create a <code>shared_ptr</code> with support for post-constructors and pre-destructors.</purpose>
- <description>
- <para>Creates an object and its owning <code>shared_ptr<T></code>
- (wrapped inside a <classname>postconstructor_invoker</classname>)
- 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. The returned
- <classname>shared_ptr</classname> is wrapped inside a <classname>postconstructor_invoker</classname>
- in order to provide the user with an opportunity to pass arguments to a postconstructor,
- while insuring the postconstructor is run before the wrapped
- <classname>shared_ptr</classname> is accessible.
- </para>
- <para>
- In order to use <code>deconstruct</code> you must define a postconstructor for your class.
- More specifically, you must define
- an <code>adl_postconstruct</code> function which can be found via argument-dependent
- lookup. Typically, this means defining an <code>adl_postconstruct</code> function
- in the same namespace as its associated class. See the reference for
- <classname>postconstructor_invoker</classname>
- for a specification of what arguments are passed to the <code>adl_postconstruct</code>
- call.
- </para>
- <para>
- Optionally, you may define a predestructor for your class. This is done by
- defining an <code>adl_predestruct</code> function which may be found
- by argument-dependent lookup. The deleter of the <classname>shared_ptr</classname>
- created by <code>deconstruct</code> will make an unqualified call to
- <code>adl_predestruct</code> with a single
- argument: a pointer to the object which is about to be deleted.
- As a convenience, the pointer will always be cast to point to a non-const type
- before being passed to <code>adl_predestruct</code>.
- If no user-defined <code>adl_predestruct</code> function is found via
- argument-dependent lookup, a default function (which does nothing) will
- be used. After <code>adl_predestruct</code> is called, the deleter
- will delete the object 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>. Arguments may also be passed to the class' associated
- <code>adl_postconstruct</code> function by using the
- <methodname>postconstructor_invoker::postconstruct()</methodname> methods.
- </para>
- </description>
- <notes>
- <para>If your compiler supports the C++11 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 > postconstructor_invoker< 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 your objects are only created by <code>deconstruct</code>, and thus
- their postconstructors or predestructors will always be called.
- </para>
- </notes>
- <returns><para>A <code>postconstructor_invoker<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>
- <class name="postconstructor_invoker">
- <method-group name="public methods">
- <method name="conversion-operator">
- <type>const shared_ptr<T> &</type>
- <description>
- <para>
- The conversion operator has the same effect as explicitly calling
- the <methodname>postconstruct</methodname> method with no arguments.
- </para>
- </description>
- </method>
- <overloaded-method name="postconstruct" cv="const">
- <signature>
- <type>const shared_ptr<T> &</type>
- </signature>
- <signature>
- <template>
- <template-type-parameter name="A1"/>
- </template>
- <type>const shared_ptr<T> &</type>
- <parameter name="a1"><paramtype>A1</paramtype></parameter>
- </signature>
- <signature>
- <template>
- <template-type-parameter name="A1"/>
- <template-type-parameter name="A2"/>
- </template>
- <type>const shared_ptr<T> &</type>
- <parameter name="a1"><paramtype>A1</paramtype></parameter>
- <parameter name="a2"><paramtype>A1</paramtype></parameter>
- </signature>
- <signature>
- <template>
- <template-type-parameter name="A1"/>
- <template-type-parameter name="A2, ..."/>
- <template-type-parameter name="AN"/>
- </template>
- <type>const shared_ptr<T> &</type>
- <parameter name="a1"><paramtype>A1</paramtype></parameter>
- <parameter name="a2"><paramtype>A1</paramtype></parameter>
- <parameter name=""><paramtype>...</paramtype></parameter>
- <parameter name="aN"><paramtype>A1</paramtype></parameter>
- </signature>
- <description>
- <para>
- The <code>postconstruct</code> methods make an unqualified call to
- <code>adl_postconstruct()</code> and then return the <classname>shared_ptr</classname>
- which was wrapped inside the <code>postconstructor_invoker</code>
- object by <functionname>deconstruct()</functionname>.
- The first two arguments passed to the
- <code>adl_postconstruct()</code> call are always the <classname>shared_ptr</classname>
- owning the object created by <functionname>deconstruct()</functionname>,
- followed by a ordinary pointer to the same object. As a convenience,
- the ordinary pointer
- will always be cast to point to a non-const type before being passed
- to <code>adl_postconstruct</code>. The remaining arguments passed to
- <code>adl_postconstruct</code> are whatever arguments the user may have
- passed to the <code>postconstruct</code>
- method.
- </para>
- </description>
- </overloaded-method>
- </method-group>
- <purpose>Pass arguments to and run postconstructors for objects created with <functionname>deconstruct()</functionname>.</purpose>
- <description>
- <para>
- Objects of type <code>postconstructor_invoker</code> are returned by calls to the
- <functionname>deconstruct()</functionname> factory function. These objects are intended
- to either be immediately assigned to a <classname>shared_ptr</classname> (in which case the
- class' conversion operator will perform the conversion by calling the
- <methodname>postconstruct</methodname> with no arguments), or to be converted
- to <classname>shared_ptr</classname> explicitly by the user calling one of
- the <methodname>postconstruct</methodname> methods.
- </para>
- </description>
- </class>
- </namespace>
- </namespace>
- </header>
|