1<?xml version="1.0" encoding="utf-8"?> 2<!DOCTYPE header PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" 3 "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> 4<!-- 5Copyright Frank Mori Hess 2009 6 7Distributed under the Boost Software License, Version 1.0. (See accompanying 8file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 9--> 10<header name="boost/signals2/deconstruct.hpp" last-revision="$Date: 2007-03-06 16:51:55 -0500 (Tue, 06 Mar 2007) $"> 11 <using-namespace name="boost::signals2"/> 12 <using-namespace name="boost"/> 13 <namespace name="boost"> 14 <namespace name="signals2"> 15 <overloaded-function name="deconstruct"> 16 <signature> 17 <template> 18 <template-type-parameter name="T"/> 19 </template> 20 <type><classname>postconstructor_invoker</classname><T></type> 21 </signature> 22 <signature> 23 <template> 24 <template-type-parameter name="T"/> 25 <template-type-parameter name="A1"/> 26 </template> 27 <type><classname>postconstructor_invoker</classname><T></type> 28 <parameter name="arg1"><paramtype>const A1 &</paramtype></parameter> 29 </signature> 30 <signature> 31 <template> 32 <template-type-parameter name="T"/> 33 <template-type-parameter name="A1"/> 34 <template-type-parameter name="A2"/> 35 </template> 36 <type><classname>postconstructor_invoker</classname><T></type> 37 <parameter name="arg1"><paramtype>const A1 &</paramtype></parameter> 38 <parameter name="arg2"><paramtype>const A2 &</paramtype></parameter> 39 </signature> 40 <signature> 41 <template> 42 <template-type-parameter name="T"/> 43 <template-type-parameter name="A1"/> 44 <template-type-parameter name="A2, ..."/> 45 <template-type-parameter name="AN"/> 46 </template> 47 <type><classname>postconstructor_invoker</classname><T></type> 48 <parameter name="arg1"><paramtype>const A1 &</paramtype></parameter> 49 <parameter name="arg2"><paramtype>const A2 &</paramtype></parameter> 50 <parameter name=""><paramtype>...</paramtype></parameter> 51 <parameter name="argN"><paramtype>const AN &</paramtype></parameter> 52 </signature> 53 54 <purpose>Create a <code>shared_ptr</code> with support for post-constructors and pre-destructors.</purpose> 55 56 <description> 57 <para>Creates an object and its owning <code>shared_ptr<T></code> 58 (wrapped inside a <classname>postconstructor_invoker</classname>) 59 using only a single allocation, 60 in a manner similar 61 to that of <functionname>boost::make_shared()</functionname>. In addition, <code>deconstruct</code> 62 supports postconstructors and predestructors. The returned 63 <classname>shared_ptr</classname> is wrapped inside a <classname>postconstructor_invoker</classname> 64 in order to provide the user with an opportunity to pass arguments to a postconstructor, 65 while insuring the postconstructor is run before the wrapped 66 <classname>shared_ptr</classname> is accessible. 67 </para> 68 <para> 69 In order to use <code>deconstruct</code> you must define a postconstructor for your class. 70 More specifically, you must define 71 an <code>adl_postconstruct</code> function which can be found via argument-dependent 72 lookup. Typically, this means defining an <code>adl_postconstruct</code> function 73 in the same namespace as its associated class. See the reference for 74 <classname>postconstructor_invoker</classname> 75 for a specification of what arguments are passed to the <code>adl_postconstruct</code> 76 call. 77 </para> 78 <para> 79 Optionally, you may define a predestructor for your class. This is done by 80 defining an <code>adl_predestruct</code> function which may be found 81 by argument-dependent lookup. The deleter of the <classname>shared_ptr</classname> 82 created by <code>deconstruct</code> will make an unqualified call to 83 <code>adl_predestruct</code> with a single 84 argument: a pointer to the object which is about to be deleted. 85 As a convenience, the pointer will always be cast to point to a non-const type 86 before being passed to <code>adl_predestruct</code>. 87 If no user-defined <code>adl_predestruct</code> function is found via 88 argument-dependent lookup, a default function (which does nothing) will 89 be used. After <code>adl_predestruct</code> is called, the deleter 90 will delete the object with 91 <functionname>checked_delete</functionname>. 92 </para> 93 <para> 94 Any arguments passed to a 95 <code>deconstruct()</code> call are forwarded to the matching constructor of the 96 template type 97 <code>T</code>. Arguments may also be passed to the class' associated 98 <code>adl_postconstruct</code> function by using the 99 <methodname>postconstructor_invoker::postconstruct()</methodname> methods. 100 </para> 101 </description> 102 <notes> 103 <para>If your compiler supports the C++11 features of rvalue references 104 and variadic templates, then <code>deconstruct</code> will perform perfect 105 forwarding of arguments to the <code>T</code> constructor, using 106 a prototype of: 107 </para> 108 <programlisting>template< typename T, typename... Args > postconstructor_invoker< T > deconstruct( Args && ... args );</programlisting> 109 <para>Otherwise, argument forwarding is performed via const references, as specified in 110 the synopsis. In order to pass non-const references to a constructor, you will need 111 to wrap them in reference wrappers using <functionname>boost::ref</functionname>. 112 </para> 113 <para>You may give all the <code>deconstruct</code> overloads access to your class' 114 private and protected constructors by 115 declaring <classname>deconstruct_access</classname> a friend. Using private 116 constructors in conjunction with <classname>deconstruct_access</classname> 117 can be useful to 118 ensure your objects are only created by <code>deconstruct</code>, and thus 119 their postconstructors or predestructors will always be called. 120 </para> 121 </notes> 122 <returns><para>A <code>postconstructor_invoker<T></code> owning a newly allocated object of 123 type <code>T</code>.</para> 124 </returns> 125 </overloaded-function> 126 <class name="deconstruct_access"> 127 <purpose>Gives <functionname>deconstruct</functionname> access to private/protected constructors.</purpose> 128 <description> 129 <para> 130 Declaring <code>deconstruct_access</code> a friend to your class will give the 131 <functionname>deconstruct</functionname> factory function access to your class' private and 132 protected constructors. Using private 133 constructors in conjunction with <code>deconstruct_access</code> 134 can be useful to 135 ensure <classname>postconstructible</classname> or <classname>predestructible</classname> 136 objects are always created 137 properly using <code>deconstruct</code>. 138 </para> 139 </description> 140 </class> 141 <class name="postconstructor_invoker"> 142 <method-group name="public methods"> 143 <method name="conversion-operator"> 144 <type>const shared_ptr<T> &</type> 145 <description> 146 <para> 147 The conversion operator has the same effect as explicitly calling 148 the <methodname>postconstruct</methodname> method with no arguments. 149 </para> 150 </description> 151 </method> 152 <overloaded-method name="postconstruct" cv="const"> 153 <signature> 154 <type>const shared_ptr<T> &</type> 155 </signature> 156 <signature> 157 <template> 158 <template-type-parameter name="A1"/> 159 </template> 160 <type>const shared_ptr<T> &</type> 161 <parameter name="a1"><paramtype>A1</paramtype></parameter> 162 </signature> 163 <signature> 164 <template> 165 <template-type-parameter name="A1"/> 166 <template-type-parameter name="A2"/> 167 </template> 168 <type>const shared_ptr<T> &</type> 169 <parameter name="a1"><paramtype>A1</paramtype></parameter> 170 <parameter name="a2"><paramtype>A1</paramtype></parameter> 171 </signature> 172 <signature> 173 <template> 174 <template-type-parameter name="A1"/> 175 <template-type-parameter name="A2, ..."/> 176 <template-type-parameter name="AN"/> 177 </template> 178 <type>const shared_ptr<T> &</type> 179 <parameter name="a1"><paramtype>A1</paramtype></parameter> 180 <parameter name="a2"><paramtype>A1</paramtype></parameter> 181 <parameter name=""><paramtype>...</paramtype></parameter> 182 <parameter name="aN"><paramtype>A1</paramtype></parameter> 183 </signature> 184 <description> 185 <para> 186 The <code>postconstruct</code> methods make an unqualified call to 187 <code>adl_postconstruct()</code> and then return the <classname>shared_ptr</classname> 188 which was wrapped inside the <code>postconstructor_invoker</code> 189 object by <functionname>deconstruct()</functionname>. 190 The first two arguments passed to the 191 <code>adl_postconstruct()</code> call are always the <classname>shared_ptr</classname> 192 owning the object created by <functionname>deconstruct()</functionname>, 193 followed by a ordinary pointer to the same object. As a convenience, 194 the ordinary pointer 195 will always be cast to point to a non-const type before being passed 196 to <code>adl_postconstruct</code>. The remaining arguments passed to 197 <code>adl_postconstruct</code> are whatever arguments the user may have 198 passed to the <code>postconstruct</code> 199 method. 200 </para> 201 </description> 202 </overloaded-method> 203 </method-group> 204 <purpose>Pass arguments to and run postconstructors for objects created with <functionname>deconstruct()</functionname>.</purpose> 205 <description> 206 <para> 207 Objects of type <code>postconstructor_invoker</code> are returned by calls to the 208 <functionname>deconstruct()</functionname> factory function. These objects are intended 209 to either be immediately assigned to a <classname>shared_ptr</classname> (in which case the 210 class' conversion operator will perform the conversion by calling the 211 <methodname>postconstruct</methodname> with no arguments), or to be converted 212 to <classname>shared_ptr</classname> explicitly by the user calling one of 213 the <methodname>postconstruct</methodname> methods. 214 </para> 215 </description> 216 </class> 217 </namespace> 218 </namespace> 219</header> 220