| <?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++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 > 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> |