123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372 |
- <?xml version="1.0" encoding="utf-8"?>
- <!DOCTYPE header PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
- "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
- <!--
- Copyright Douglas Gregor 2001-2004
- Copyright Frank Mori Hess 2007-2009
- Distributed under the Boost Software License, Version 1.0. (See accompanying
- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
- -->
- <header name="boost/signals2/connection.hpp" last-revision="$Date: 2007-03-06 16:51:55 -0500 (Tue, 06 Mar 2007) $">
- <namespace name="boost">
- <namespace name="signals2">
- <class name="connection">
- <!-- Models LessThanComparable and EqualityComparable -->
- <purpose>Query/disconnect a signal-slot connection.</purpose>
- <description>
- <para>The <classname>signals2::connection</classname> class represents
- a connection between a Signal and a Slot. It is a
- lightweight object that has the ability to query whether the
- signal and slot are currently connected, and to disconnect
- the signal and slot. It is always safe to query or
- disconnect a connection.</para>
- <section>
- <title>Thread Safety</title>
- <para>The methods of the <code>connection</code> class are thread-safe with the exception
- of <methodname>swap</methodname> and the assignment operator. A <code>connection</code> object
- should not be accessed concurrently when either of these operations is in progress.
- However, it is always safe to access a different <code>connection</code> object
- in another thread, even if the two <code>connection</code> objects are copies
- of each other which refer to the same underlying connection.
- </para>
- </section>
- </description>
- <constructor>
- <effects><para>Sets the currently represented connection to the
- NULL connection.</para></effects>
- <postconditions><para><computeroutput>!this-><methodname>connected</methodname>()</computeroutput>.</para></postconditions>
- <throws><para>Will not throw.</para></throws>
- </constructor>
- <constructor>
- <parameter name="other">
- <paramtype>const <classname alt="signals2::connection">connection</classname>&</paramtype>
- </parameter>
- <effects><para><computeroutput>this</computeroutput> references
- the connection referenced by
- <computeroutput>other</computeroutput>.</para></effects>
- <throws><para>Will not throw.</para></throws>
- </constructor>
- <constructor>
- <parameter name="other">
- <paramtype><classname alt="signals2::connection">connection</classname>&&</paramtype>
- </parameter>
- <description><para>Move constructor.</para></description>
- <effects><para><computeroutput>this</computeroutput> references
- the connection formerly referenced by
- <computeroutput>other</computeroutput>. The moved-from <computeroutput>other</computeroutput>
- no longer references any connection.</para></effects>
- <throws><para>Will not throw.</para></throws>
- </constructor>
- <copy-assignment>
- <parameter name="rhs">
- <paramtype>const <classname alt="signals2::connection">connection</classname>&</paramtype>
- </parameter>
- <effects><para><computeroutput>this</computeroutput> references
- the connection referenced by
- <computeroutput>rhs</computeroutput>.</para></effects>
- <throws><para>Will not throw.</para></throws>
- </copy-assignment>
- <copy-assignment>
- <parameter name="rhs">
- <paramtype><classname alt="signals2::connection">connection</classname>&&</paramtype>
- </parameter>
- <description><para>Move assignment.</para></description>
- <effects><para><computeroutput>this</computeroutput> references
- the connection formerly referenced by
- <computeroutput>rhs</computeroutput>. The moved-from <computeroutput>rhs</computeroutput>
- no longer references any connection.</para></effects>
- <throws><para>Will not throw.</para></throws>
- </copy-assignment>
- <method-group name="connection management">
- <method name="disconnect" cv="const">
- <type>void</type>
- <effects><para>If
- <computeroutput>this-><methodname>connected</methodname>()</computeroutput>,
- disconnects the signal and slot referenced by this;
- otherwise, this operation is a no-op.</para></effects>
- <postconditions><para><computeroutput>!this-><methodname>connected</methodname>()</computeroutput>.</para></postconditions>
- </method>
- <method name="connected" cv="const">
- <type>bool</type>
- <returns><para><computeroutput>true</computeroutput> if this
- references a non-NULL connection that is still active
- (connected), and <computeroutput>false</computeroutput>
- otherwise.</para></returns>
- <throws><para>Will not throw.</para></throws>
- </method>
- </method-group>
- <method-group name="blocking">
- <method name="blocked" cv="const">
- <type>bool</type>
- <description>
- <para>
- Queries if the connection is blocked. A connection may be blocked by creating a
- <classname>boost::signals2::shared_connection_block</classname> object.
- </para>
- </description>
- <returns><para><code>true</code> if the associated slot is either disconnected or blocked, <code>false</code> otherwise.</para></returns>
- <throws><para>Will not throw.</para></throws>
- </method>
- </method-group>
- <method-group name="modifiers">
- <method name="swap">
- <type>void</type>
- <parameter name="other">
- <paramtype><classname alt="signals2::connection">connection</classname>&</paramtype>
- </parameter>
- <effects><para>Swaps the connections referenced in
- <computeroutput>this</computeroutput> and
- <computeroutput>other</computeroutput>.</para></effects>
- <throws><para>Will not throw.</para></throws>
- </method>
- </method-group>
- <method-group name="comparisons">
- <method name="operator==" cv="const">
- <type>bool</type>
- <parameter name="other">
- <paramtype>const <classname alt="signals2::connection">connection</classname>&</paramtype>
- </parameter>
- <returns><para><computeroutput>true</computeroutput> if
- <computeroutput>this</computeroutput> and
- <computeroutput>other</computeroutput> reference the same
- connection or both reference the NULL connection, and
- <computeroutput>false</computeroutput>
- otherwise.</para></returns>
- <throws><para>Will not throw.</para></throws>
- </method>
- <method name="operator!=" cv="const">
- <type>bool</type>
- <parameter name="other">
- <paramtype>const <classname alt="signals2::connection">connection</classname>&</paramtype>
- </parameter>
- <returns><para><computeroutput>!(*this == other)</computeroutput></para></returns>
- <throws><para>Will not throw.</para></throws>
- </method>
- <method name="operator<" cv="const">
- <type>bool</type>
- <parameter name="other">
- <paramtype>const <classname alt="signals2::connection">connection</classname>&</paramtype>
- </parameter>
- <returns><para><computeroutput>true</computeroutput> if the
- connection referenced by
- <computeroutput>this</computeroutput> precedes the
- connection referenced by
- <computeroutput>other</computeroutput> based on some
- unspecified ordering, and
- <computeroutput>false</computeroutput>
- otherwise.</para></returns>
- <throws><para>Will not throw.</para></throws>
- </method>
- </method-group>
- <free-function-group name="specialized algorithms">
- <function name="swap">
- <type>void</type>
- <parameter name="x">
- <paramtype><classname alt="signals2::connection">connection</classname>&</paramtype>
- </parameter>
- <parameter name="y">
- <paramtype><classname alt="signals2::connection">connection</classname>&</paramtype>
- </parameter>
- <effects><para><computeroutput>x.swap(y)</computeroutput></para></effects>
- <throws><para>Will not throw.</para></throws>
- </function>
- </free-function-group>
- </class>
- <class name="scoped_connection">
- <inherit access="public">
- <type><classname alt="signals2::connection">connection</classname></type>
- </inherit>
- <purpose>Limits a signal-slot connection lifetime to a particular scope.</purpose>
- <access name="public">
- <constructor>
- <postconditions>
- <para><code><methodname alt="connection::connected">connected</methodname>() == false </code></para>
- </postconditions>
- <description>
- <para>Default constructs an empty scoped_connection.</para>
- </description>
- <throws><para>Will not throw.</para></throws>
- </constructor>
- <constructor>
- <parameter name="other">
- <paramtype>const <classname alt="signals2::connection">connection</classname>&</paramtype>
- </parameter>
- <effects><para><computeroutput>this</computeroutput> references
- the connection referenced by
- <computeroutput>other</computeroutput>.</para></effects>
- <postconditions>
- <para><code><methodname alt="connection::connected">connected</methodname>() == other.connected()</code></para>
- </postconditions>
- <throws><para>Will not throw.</para></throws>
- </constructor>
- <constructor>
- <parameter name="other">
- <paramtype><classname alt="signals2::scoped_connection">scoped_connection</classname>&&</paramtype>
- </parameter>
- <description><para>Move constructor.</para></description>
- <effects><para><computeroutput>this</computeroutput> references
- the connection formerly referenced by
- <computeroutput>other</computeroutput>. The moved-from <computeroutput>other</computeroutput>
- no longer references any connection.</para></effects>
- <throws><para>Will not throw.</para></throws>
- </constructor>
- <constructor>
- <parameter name="other">
- <paramtype><classname alt="signals2::connection">connection</classname>&&</paramtype>
- </parameter>
- <description><para>Move constructor.</para></description>
- <effects><para><computeroutput>this</computeroutput> references
- the connection formerly referenced by
- <computeroutput>other</computeroutput>. The moved-from <computeroutput>other</computeroutput>
- no longer references any connection.</para></effects>
- <throws><para>Will not throw.</para></throws>
- </constructor>
- <copy-assignment>
- <parameter name="rhs">
- <paramtype>const <classname alt="signals2::connection">connection</classname>&</paramtype>
- </parameter>
- <description><para>Copy assignment from unscoped connection.</para></description>
- <effects><para><computeroutput>this</computeroutput> references
- the connection referenced by
- <computeroutput>rhs</computeroutput>. If <code>this</code> already references another
- connection, the old connection will be disconnected first.</para></effects>
- <postconditions>
- <para><code><methodname alt="connection::connected">connected</methodname>() == other.connected()</code></para>
- </postconditions>
- <throws><para>Will not throw.</para></throws>
- </copy-assignment>
- <copy-assignment>
- <parameter name="rhs">
- <paramtype><classname alt="signals2::scoped_connection">scoped_connection</classname>&&</paramtype>
- </parameter>
- <description><para>Move assignment.</para></description>
- <effects><para><computeroutput>this</computeroutput> references
- the connection formerly referenced by
- <computeroutput>rhs</computeroutput>. The moved-from <computeroutput>rhs</computeroutput>
- no longer references any connection. If <code>this</code> already references another
- connection, the old connection will be disconnected first.</para></effects>
- <throws><para>Will not throw.</para></throws>
- </copy-assignment>
- <copy-assignment>
- <parameter name="rhs">
- <paramtype><classname alt="signals2::connection">connection</classname>&&</paramtype>
- </parameter>
- <description><para>Move assignment.</para></description>
- <effects><para><computeroutput>this</computeroutput> references
- the connection formerly referenced by
- <computeroutput>rhs</computeroutput>. The moved-from <computeroutput>rhs</computeroutput>
- no longer references any connection. If <code>this</code> already references another
- connection, the old connection will be disconnected first.</para></effects>
- <throws><para>Will not throw.</para></throws>
- </copy-assignment>
- <destructor>
- <effects><para>If
- <computeroutput>this-><methodname alt="connection::connected">connected</methodname>()</computeroutput>,
- disconnects the signal-slot connection.</para></effects>
- </destructor>
- <method-group name="public methods">
- <method name="release">
- <type><classname alt="signals2::connection">connection</classname></type>
- <effects>
- <para>
- Releases the connection so it will not be disconnected by the <code>scoped_connection</code>
- when it is destroyed or reassigned. The <code>scoped_connection</code> is reset to
- the NULL connection after this call completes.
- </para>
- </effects>
- <postconditions>
- <para><code><methodname alt="connection::connected">connected</methodname>() == false</code></para>
- </postconditions>
- <returns>
- <para>A <classname alt="signals2::connection">connection</classname> object referencing the connection which was
- released by the <code>scoped_connection</code>.
- </para>
- </returns>
- </method>
- </method-group>
- </access>
- <access name="private">
- <constructor>
- <parameter name="other">
- <paramtype>const <classname alt="signals2::scoped_connection">scoped_connection</classname>&</paramtype>
- </parameter>
- <description>
- <para>The scoped_connection class is not copyable. It may only be copy constructed from an unscoped
- <classname alt="signals2::connection">connection</classname> object.</para>
- </description>
- </constructor>
- <copy-assignment>
- <parameter name="rhs">
- <paramtype>const <classname alt="signals2::scoped_connection">scoped_connection</classname>&</paramtype>
- </parameter>
- <description>
- <para>The scoped_connection class is not copyable. It may only be copy assigned from an unscoped
- <classname alt="signals2::connection">connection</classname> object.</para>
- </description>
- </copy-assignment>
- </access>
- <description>
- <para>A <classname alt="signals2::connection">connection</classname> which automatically disconnects on destruction.</para>
- <section>
- <title>Thread Safety</title>
- <para>The methods of the <code>scoped_connection</code> class (including those
- inherited from its base <code>connection</code> class) are thread-safe with the exception
- of <methodname>signals2::connection::swap</methodname>, <methodname>release</methodname>, and
- the assignment operator. A <code>scoped_connection</code> object
- should not be accessed concurrently when any of these operations is in progress.
- However, it is always safe to access a different <code>connection</code> object
- in another thread, even if it references the same underlying signal-slot connection.
- </para>
- </section>
- </description>
- </class>
- </namespace>
- </namespace>
- </header>
|