]>
Commit | Line | Data |
---|---|---|
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 Douglas Gregor 2001-2004 | |
6 | Copyright Frank Mori Hess 2007-2009 | |
7 | ||
8 | Distributed under the Boost Software License, Version 1.0. (See accompanying | |
9 | file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) | |
10 | --> | |
11 | <header name="boost/signals2/connection.hpp" last-revision="$Date: 2007-03-06 16:51:55 -0500 (Tue, 06 Mar 2007) $"> | |
12 | <namespace name="boost"> | |
13 | <namespace name="signals2"> | |
14 | <class name="connection"> | |
15 | <!-- Models LessThanComparable and EqualityComparable --> | |
16 | <purpose>Query/disconnect a signal-slot connection.</purpose> | |
17 | ||
18 | <description> | |
19 | <para>The <classname>signals2::connection</classname> class represents | |
20 | a connection between a Signal and a Slot. It is a | |
21 | lightweight object that has the ability to query whether the | |
22 | signal and slot are currently connected, and to disconnect | |
23 | the signal and slot. It is always safe to query or | |
24 | disconnect a connection.</para> | |
25 | <section> | |
26 | <title>Thread Safety</title> | |
27 | <para>The methods of the <code>connection</code> class are thread-safe with the exception | |
28 | of <methodname>swap</methodname> and the assignment operator. A <code>connection</code> object | |
29 | should not be accessed concurrently when either of these operations is in progress. | |
30 | However, it is always safe to access a different <code>connection</code> object | |
31 | in another thread, even if the two <code>connection</code> objects are copies | |
32 | of each other which refer to the same underlying connection. | |
33 | </para> | |
34 | </section> | |
35 | </description> | |
36 | ||
37 | <constructor> | |
38 | <effects><para>Sets the currently represented connection to the | |
39 | NULL connection.</para></effects> | |
40 | <postconditions><para><computeroutput>!this-><methodname>connected</methodname>()</computeroutput>.</para></postconditions> | |
41 | <throws><para>Will not throw.</para></throws> | |
42 | </constructor> | |
43 | ||
44 | <constructor> | |
45 | <parameter name="other"> | |
46 | <paramtype>const <classname alt="signals2::connection">connection</classname>&</paramtype> | |
47 | </parameter> | |
48 | ||
49 | <effects><para><computeroutput>this</computeroutput> references | |
50 | the connection referenced by | |
51 | <computeroutput>other</computeroutput>.</para></effects> | |
52 | ||
53 | <throws><para>Will not throw.</para></throws> | |
54 | </constructor> | |
55 | ||
56 | <constructor> | |
57 | <parameter name="other"> | |
58 | <paramtype><classname alt="signals2::connection">connection</classname>&&</paramtype> | |
59 | </parameter> | |
60 | <description><para>Move constructor.</para></description> | |
61 | <effects><para><computeroutput>this</computeroutput> references | |
62 | the connection formerly referenced by | |
63 | <computeroutput>other</computeroutput>. The moved-from <computeroutput>other</computeroutput> | |
64 | no longer references any connection.</para></effects> | |
65 | ||
66 | <throws><para>Will not throw.</para></throws> | |
67 | </constructor> | |
68 | ||
69 | <copy-assignment> | |
70 | <parameter name="rhs"> | |
71 | <paramtype>const <classname alt="signals2::connection">connection</classname>&</paramtype> | |
72 | </parameter> | |
73 | ||
74 | <effects><para><computeroutput>this</computeroutput> references | |
75 | the connection referenced by | |
76 | <computeroutput>rhs</computeroutput>.</para></effects> | |
77 | ||
78 | <throws><para>Will not throw.</para></throws> | |
79 | </copy-assignment> | |
80 | ||
81 | <copy-assignment> | |
82 | <parameter name="rhs"> | |
83 | <paramtype><classname alt="signals2::connection">connection</classname>&&</paramtype> | |
84 | </parameter> | |
85 | <description><para>Move assignment.</para></description> | |
86 | <effects><para><computeroutput>this</computeroutput> references | |
87 | the connection formerly referenced by | |
88 | <computeroutput>rhs</computeroutput>. The moved-from <computeroutput>rhs</computeroutput> | |
89 | no longer references any connection.</para></effects> | |
90 | ||
91 | <throws><para>Will not throw.</para></throws> | |
92 | </copy-assignment> | |
93 | ||
94 | <method-group name="connection management"> | |
95 | <method name="disconnect" cv="const"> | |
96 | <type>void</type> | |
97 | <effects><para>If | |
98 | <computeroutput>this-><methodname>connected</methodname>()</computeroutput>, | |
99 | disconnects the signal and slot referenced by this; | |
100 | otherwise, this operation is a no-op.</para></effects> | |
101 | ||
102 | <postconditions><para><computeroutput>!this-><methodname>connected</methodname>()</computeroutput>.</para></postconditions> | |
103 | </method> | |
104 | ||
105 | <method name="connected" cv="const"> | |
106 | <type>bool</type> | |
107 | <returns><para><computeroutput>true</computeroutput> if this | |
108 | references a non-NULL connection that is still active | |
109 | (connected), and <computeroutput>false</computeroutput> | |
110 | otherwise.</para></returns> | |
111 | <throws><para>Will not throw.</para></throws> | |
112 | </method> | |
113 | </method-group> | |
114 | ||
115 | <method-group name="blocking"> | |
116 | <method name="blocked" cv="const"> | |
117 | <type>bool</type> | |
118 | <description> | |
119 | <para> | |
120 | Queries if the connection is blocked. A connection may be blocked by creating a | |
121 | <classname>boost::signals2::shared_connection_block</classname> object. | |
122 | </para> | |
123 | </description> | |
124 | <returns><para><code>true</code> if the associated slot is either disconnected or blocked, <code>false</code> otherwise.</para></returns> | |
125 | <throws><para>Will not throw.</para></throws> | |
126 | </method> | |
127 | </method-group> | |
128 | ||
129 | <method-group name="modifiers"> | |
130 | <method name="swap"> | |
131 | <type>void</type> | |
132 | <parameter name="other"> | |
133 | <paramtype><classname alt="signals2::connection">connection</classname>&</paramtype> | |
134 | </parameter> | |
135 | <effects><para>Swaps the connections referenced in | |
136 | <computeroutput>this</computeroutput> and | |
137 | <computeroutput>other</computeroutput>.</para></effects> | |
138 | ||
139 | <throws><para>Will not throw.</para></throws> | |
140 | </method> | |
141 | </method-group> | |
142 | ||
143 | <method-group name="comparisons"> | |
144 | <method name="operator==" cv="const"> | |
145 | <type>bool</type> | |
146 | <parameter name="other"> | |
147 | <paramtype>const <classname alt="signals2::connection">connection</classname>&</paramtype> | |
148 | </parameter> | |
149 | ||
150 | <returns><para><computeroutput>true</computeroutput> if | |
151 | <computeroutput>this</computeroutput> and | |
152 | <computeroutput>other</computeroutput> reference the same | |
153 | connection or both reference the NULL connection, and | |
154 | <computeroutput>false</computeroutput> | |
155 | otherwise.</para></returns> | |
156 | ||
157 | <throws><para>Will not throw.</para></throws> | |
158 | </method> | |
159 | ||
160 | <method name="operator!=" cv="const"> | |
161 | <type>bool</type> | |
162 | <parameter name="other"> | |
163 | <paramtype>const <classname alt="signals2::connection">connection</classname>&</paramtype> | |
164 | </parameter> | |
165 | ||
166 | <returns><para><computeroutput>!(*this == other)</computeroutput></para></returns> | |
167 | ||
168 | <throws><para>Will not throw.</para></throws> | |
169 | </method> | |
170 | ||
171 | <method name="operator<" cv="const"> | |
172 | <type>bool</type> | |
173 | <parameter name="other"> | |
174 | <paramtype>const <classname alt="signals2::connection">connection</classname>&</paramtype> | |
175 | </parameter> | |
176 | ||
177 | <returns><para><computeroutput>true</computeroutput> if the | |
178 | connection referenced by | |
179 | <computeroutput>this</computeroutput> precedes the | |
180 | connection referenced by | |
181 | <computeroutput>other</computeroutput> based on some | |
182 | unspecified ordering, and | |
183 | <computeroutput>false</computeroutput> | |
184 | otherwise.</para></returns> | |
185 | ||
186 | <throws><para>Will not throw.</para></throws> | |
187 | </method> | |
188 | </method-group> | |
189 | ||
190 | <free-function-group name="specialized algorithms"> | |
191 | <function name="swap"> | |
192 | <type>void</type> | |
193 | <parameter name="x"> | |
194 | <paramtype><classname alt="signals2::connection">connection</classname>&</paramtype> | |
195 | </parameter> | |
196 | <parameter name="y"> | |
197 | <paramtype><classname alt="signals2::connection">connection</classname>&</paramtype> | |
198 | </parameter> | |
199 | ||
200 | <effects><para><computeroutput>x.swap(y)</computeroutput></para></effects> | |
201 | <throws><para>Will not throw.</para></throws> | |
202 | </function> | |
203 | </free-function-group> | |
204 | </class> | |
205 | ||
206 | <class name="scoped_connection"> | |
207 | <inherit access="public"> | |
208 | <type><classname alt="signals2::connection">connection</classname></type> | |
209 | </inherit> | |
210 | <purpose>Limits a signal-slot connection lifetime to a particular scope.</purpose> | |
211 | ||
212 | <access name="public"> | |
213 | <constructor> | |
214 | <postconditions> | |
215 | <para><code><methodname alt="connection::connected">connected</methodname>() == false </code></para> | |
216 | </postconditions> | |
217 | <description> | |
218 | <para>Default constructs an empty scoped_connection.</para> | |
219 | </description> | |
220 | ||
221 | <throws><para>Will not throw.</para></throws> | |
222 | </constructor> | |
223 | <constructor> | |
224 | <parameter name="other"> | |
225 | <paramtype>const <classname alt="signals2::connection">connection</classname>&</paramtype> | |
226 | </parameter> | |
227 | ||
228 | <effects><para><computeroutput>this</computeroutput> references | |
229 | the connection referenced by | |
230 | <computeroutput>other</computeroutput>.</para></effects> | |
231 | ||
232 | <postconditions> | |
233 | <para><code><methodname alt="connection::connected">connected</methodname>() == other.connected()</code></para> | |
234 | </postconditions> | |
235 | ||
236 | <throws><para>Will not throw.</para></throws> | |
237 | </constructor> | |
238 | ||
239 | <constructor> | |
240 | <parameter name="other"> | |
241 | <paramtype><classname alt="signals2::scoped_connection">scoped_connection</classname>&&</paramtype> | |
242 | </parameter> | |
243 | <description><para>Move constructor.</para></description> | |
244 | <effects><para><computeroutput>this</computeroutput> references | |
245 | the connection formerly referenced by | |
246 | <computeroutput>other</computeroutput>. The moved-from <computeroutput>other</computeroutput> | |
247 | no longer references any connection.</para></effects> | |
248 | ||
249 | <throws><para>Will not throw.</para></throws> | |
250 | </constructor> | |
251 | ||
252 | <constructor> | |
253 | <parameter name="other"> | |
254 | <paramtype><classname alt="signals2::connection">connection</classname>&&</paramtype> | |
255 | </parameter> | |
256 | <description><para>Move constructor.</para></description> | |
257 | <effects><para><computeroutput>this</computeroutput> references | |
258 | the connection formerly referenced by | |
259 | <computeroutput>other</computeroutput>. The moved-from <computeroutput>other</computeroutput> | |
260 | no longer references any connection.</para></effects> | |
261 | ||
262 | <throws><para>Will not throw.</para></throws> | |
263 | </constructor> | |
264 | ||
265 | <copy-assignment> | |
266 | <parameter name="rhs"> | |
267 | <paramtype>const <classname alt="signals2::connection">connection</classname>&</paramtype> | |
268 | </parameter> | |
269 | <description><para>Copy assignment from unscoped connection.</para></description> | |
270 | <effects><para><computeroutput>this</computeroutput> references | |
271 | the connection referenced by | |
272 | <computeroutput>rhs</computeroutput>. If <code>this</code> already references another | |
273 | connection, the old connection will be disconnected first.</para></effects> | |
274 | <postconditions> | |
275 | <para><code><methodname alt="connection::connected">connected</methodname>() == other.connected()</code></para> | |
276 | </postconditions> | |
277 | ||
278 | <throws><para>Will not throw.</para></throws> | |
279 | </copy-assignment> | |
280 | ||
281 | <copy-assignment> | |
282 | <parameter name="rhs"> | |
283 | <paramtype><classname alt="signals2::scoped_connection">scoped_connection</classname>&&</paramtype> | |
284 | </parameter> | |
285 | <description><para>Move assignment.</para></description> | |
286 | <effects><para><computeroutput>this</computeroutput> references | |
287 | the connection formerly referenced by | |
288 | <computeroutput>rhs</computeroutput>. The moved-from <computeroutput>rhs</computeroutput> | |
289 | no longer references any connection. If <code>this</code> already references another | |
290 | connection, the old connection will be disconnected first.</para></effects> | |
291 | ||
292 | <throws><para>Will not throw.</para></throws> | |
293 | </copy-assignment> | |
294 | ||
295 | <copy-assignment> | |
296 | <parameter name="rhs"> | |
297 | <paramtype><classname alt="signals2::connection">connection</classname>&&</paramtype> | |
298 | </parameter> | |
299 | <description><para>Move assignment.</para></description> | |
300 | <effects><para><computeroutput>this</computeroutput> references | |
301 | the connection formerly referenced by | |
302 | <computeroutput>rhs</computeroutput>. The moved-from <computeroutput>rhs</computeroutput> | |
303 | no longer references any connection. If <code>this</code> already references another | |
304 | connection, the old connection will be disconnected first.</para></effects> | |
305 | ||
306 | <throws><para>Will not throw.</para></throws> | |
307 | </copy-assignment> | |
308 | ||
309 | <destructor> | |
310 | <effects><para>If | |
311 | <computeroutput>this-><methodname alt="connection::connected">connected</methodname>()</computeroutput>, | |
312 | disconnects the signal-slot connection.</para></effects> | |
313 | </destructor> | |
314 | <method-group name="public methods"> | |
315 | <method name="release"> | |
316 | <type><classname alt="signals2::connection">connection</classname></type> | |
317 | <effects> | |
318 | <para> | |
319 | Releases the connection so it will not be disconnected by the <code>scoped_connection</code> | |
320 | when it is destroyed or reassigned. The <code>scoped_connection</code> is reset to | |
321 | the NULL connection after this call completes. | |
322 | </para> | |
323 | </effects> | |
324 | <postconditions> | |
325 | <para><code><methodname alt="connection::connected">connected</methodname>() == false</code></para> | |
326 | </postconditions> | |
327 | <returns> | |
328 | <para>A <classname alt="signals2::connection">connection</classname> object referencing the connection which was | |
329 | released by the <code>scoped_connection</code>. | |
330 | </para> | |
331 | </returns> | |
332 | </method> | |
333 | </method-group> | |
334 | </access> | |
335 | <access name="private"> | |
336 | <constructor> | |
337 | <parameter name="other"> | |
338 | <paramtype>const <classname alt="signals2::scoped_connection">scoped_connection</classname>&</paramtype> | |
339 | </parameter> | |
340 | <description> | |
341 | <para>The scoped_connection class is not copyable. It may only be copy constructed from an unscoped | |
342 | <classname alt="signals2::connection">connection</classname> object.</para> | |
343 | </description> | |
344 | </constructor> | |
345 | <copy-assignment> | |
346 | <parameter name="rhs"> | |
347 | <paramtype>const <classname alt="signals2::scoped_connection">scoped_connection</classname>&</paramtype> | |
348 | </parameter> | |
349 | <description> | |
350 | <para>The scoped_connection class is not copyable. It may only be copy assigned from an unscoped | |
351 | <classname alt="signals2::connection">connection</classname> object.</para> | |
352 | </description> | |
353 | </copy-assignment> | |
354 | </access> | |
355 | <description> | |
356 | <para>A <classname alt="signals2::connection">connection</classname> which automatically disconnects on destruction.</para> | |
357 | <section> | |
358 | <title>Thread Safety</title> | |
359 | <para>The methods of the <code>scoped_connection</code> class (including those | |
360 | inherited from its base <code>connection</code> class) are thread-safe with the exception | |
361 | of <methodname>signals2::connection::swap</methodname>, <methodname>release</methodname>, and | |
362 | the assignment operator. A <code>scoped_connection</code> object | |
363 | should not be accessed concurrently when any of these operations is in progress. | |
364 | However, it is always safe to access a different <code>connection</code> object | |
365 | in another thread, even if it references the same underlying signal-slot connection. | |
366 | </para> | |
367 | </section> | |
368 | </description> | |
369 | </class> | |
370 | </namespace> | |
371 | </namespace> | |
372 | </header> |