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">
5 Copyright Frank Mori Hess 2009
7 Distributed under the Boost Software License, Version 1.0. (See accompanying
8 file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
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">
18 <template-type-parameter name=
"T"/>
20 <type><classname>postconstructor_invoker
</classname><T
></type>
24 <template-type-parameter name=
"T"/>
25 <template-type-parameter name=
"A1"/>
27 <type><classname>postconstructor_invoker
</classname><T
></type>
28 <parameter name=
"arg1"><paramtype>const A1
&</paramtype></parameter>
32 <template-type-parameter name=
"T"/>
33 <template-type-parameter name=
"A1"/>
34 <template-type-parameter name=
"A2"/>
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>
42 <template-type-parameter name=
"T"/>
43 <template-type-parameter name=
"A1"/>
44 <template-type-parameter name=
"A2, ..."/>
45 <template-type-parameter name=
"AN"/>
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>
54 <purpose>Create a
<code>shared_ptr
</code> with support for post-constructors and pre-destructors.
</purpose>
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,
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.
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>
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>.
94 Any arguments passed to a
95 <code>deconstruct()
</code> call are forwarded to the matching constructor of the
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.
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
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>.
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>
118 ensure your objects are only created by
<code>deconstruct
</code>, and thus
119 their postconstructors or predestructors will always be called.
122 <returns><para>A
<code>postconstructor_invoker
<T
></code> owning a newly allocated object of
123 type
<code>T
</code>.
</para>
125 </overloaded-function>
126 <class name=
"deconstruct_access">
127 <purpose>Gives
<functionname>deconstruct
</functionname> access to private/protected constructors.
</purpose>
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>
135 ensure
<classname>postconstructible
</classname> or
<classname>predestructible
</classname>
136 objects are always created
137 properly using
<code>deconstruct
</code>.
141 <class name=
"postconstructor_invoker">
142 <method-group name=
"public methods">
143 <method name=
"conversion-operator">
144 <type>const shared_ptr
<T
> &</type>
147 The conversion operator has the same effect as explicitly calling
148 the
<methodname>postconstruct
</methodname> method with no arguments.
152 <overloaded-method name=
"postconstruct" cv=
"const">
154 <type>const shared_ptr
<T
> &</type>
158 <template-type-parameter name=
"A1"/>
160 <type>const shared_ptr
<T
> &</type>
161 <parameter name=
"a1"><paramtype>A1
</paramtype></parameter>
165 <template-type-parameter name=
"A1"/>
166 <template-type-parameter name=
"A2"/>
168 <type>const shared_ptr
<T
> &</type>
169 <parameter name=
"a1"><paramtype>A1
</paramtype></parameter>
170 <parameter name=
"a2"><paramtype>A1
</paramtype></parameter>
174 <template-type-parameter name=
"A1"/>
175 <template-type-parameter name=
"A2, ..."/>
176 <template-type-parameter name=
"AN"/>
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>
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,
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>
204 <purpose>Pass arguments to and run postconstructors for objects created with
<functionname>deconstruct()
</functionname>.
</purpose>
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.