ceph/src/boost/libs/signals2/doc/reference/connection.xml

   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>&amp;</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>&amp;&amp;</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>&amp;</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>&amp;&amp;</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-&gt;<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-&gt;<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>&amp;</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>&amp;</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>&amp;</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&lt;" cv="const">
 172             <type>bool</type>
 173             <parameter name="other">
 174               <paramtype>const <classname alt="signals2::connection">connection</classname>&amp;</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>&amp;</paramtype>
 195             </parameter>
 196             <parameter name="y">
 197               <paramtype><classname alt="signals2::connection">connection</classname>&amp;</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>&amp;</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>&amp;&amp;</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>&amp;&amp;</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>&amp;</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>&amp;&amp;</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>&amp;&amp;</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-&gt;<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>&amp;</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>&amp;</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>