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 Douglas Gregor 2001-2004 6Copyright Frank Mori Hess 2007-2009 7 8Distributed under the Boost Software License, Version 1.0. (See accompanying 9file 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> 373