]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 | <!-- | |
5 | Copyright Frank Mori Hess 2009 | |
6 | ||
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) | |
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> |