123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141 |
- <?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 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/shared_connection_block.hpp" last-revision="$Date: 2007-03-06 16:51:55 -0500 (Tue, 06 Mar 2007) $">
- <using-namespace name="boost::signals2"/>
- <using-namespace name="boost"/>
- <using-class name="boost::signals2::connection"/>
- <namespace name="boost">
- <namespace name="signals2">
- <class name="shared_connection_block">
- <purpose>Blocks a connection between a signal and a slot.</purpose>
- <description>
- <para>A <code>shared_connection_block</code> object blocks a
- connection, preventing the associated slot from executing when the
- associated signal is invoked. The connection will remain
- blocked until every <code>shared_connection_block</code> that references
- the connection
- releases its block. A <code>shared_connection_block</code> releases
- its block when it is destroyed or its
- <methodname>unblock</methodname> method is called.</para>
- <para>A <code>shared_connection_block</code> is safe to use even
- after the <classname>signals2::connection</classname> object it was constructed
- from has been destroyed, or the connection it references has been
- disconnected.</para>
- <para>
- Note, blocking a connection does not guarantee the associated slot
- has finished execution if it is already in the process of being run
- when the connection block goes into effect. This is similar
- to the behaviour of disconnect, in that blocking a connection
- will not wait for the connection's associated slot to complete execution.
- This situation may arise in a multi-threaded environment if the
- connection block goes into effect concurrently with signal invocation,
- or in a single-threaded environment if a slot blocks its own
- connection.
- </para>
- </description>
- <constructor>
- <parameter name="conn">
- <paramtype>const <classname>boost::signals2::connection</classname> &</paramtype>
- <default>connection()</default>
- </parameter>
- <parameter name="initially_blocking">
- <paramtype>bool</paramtype>
- <default>true</default>
- </parameter>
- <effects>
- <para>Creates a <code>shared_connection_block</code> which can block
- the connection referenced by <code>conn</code>. The <code>shared_connection_block</code>
- will initially block the connection if and only if the
- <code>initially_blocking</code>
- parameter is <code>true</code>. The block on the connection may be released
- by calling the <methodname>unblock</methodname> method,
- or destroying the <code>shared_connection_block</code> object.</para>
- <para>Default construction of a <code>shared_connection_block</code> results in a
- <code>shared_connection_block</code> which references the NULL connection.
- Such a <code>shared_connection_block</code> is safe to use, though not
- particularly useful until it is assigned another
- <code>shared_connection_block</code> which references a real connection.
- </para>
- </effects>
- <postconditions><para><code>this->blocking() == initially_blocking</code></para></postconditions>
- </constructor>
- <constructor>
- <parameter name="other">
- <paramtype>const boost::signals2::shared_connection_block &</paramtype>
- </parameter>
- <effects>
- <para>
- Copy constructs a <code>shared_connection_block</code> which references
- the same connection as <code>other</code>.
- </para>
- </effects>
- <postconditions>
- <para><code>this->connection() == other.connection()</code></para>
- <para><code>this->blocking() == other.blocking()</code></para>
- </postconditions>
- </constructor>
- <destructor>
- <effects><para>If <methodname>blocking</methodname>() is true, releases the connection block.</para></effects>
- </destructor>
- <copy-assignment>
- <parameter name="rhs">
- <paramtype>const boost::signals2::shared_connection_block &</paramtype>
- </parameter>
- <effects>
- <para>
- Makes <code>this</code> reference the same connection as <code>rhs</code>.
- </para>
- </effects>
- <postconditions>
- <para><code>this->connection() == rhs.connection()</code></para>
- <para><code>this->blocking() == rhs.blocking()</code></para>
- </postconditions>
- <throws><para>Will not throw.</para></throws>
- </copy-assignment>
- <method-group name="connection blocking">
- <method name="unblock">
- <type>void</type>
- <effects><para>If <methodname>blocking</methodname>() is true, releases the connection block.
- Note, the connection may remain blocked due to
- other <code>shared_connection_block</code> objects.</para></effects>
- <postconditions><para><code>this->blocking() == false</code>.</para></postconditions>
- </method>
- <method name="block">
- <type>void</type>
- <effects><para>If <methodname>blocking</methodname>() is false, reasserts a block on
- the connection.</para></effects>
- <postconditions><para><code>this->blocking() == true</code>.</para></postconditions>
- </method>
- <method name="blocking" cv="const">
- <type>bool</type>
- <returns><para><code>true</code> if <code>this</code> is asserting a block on the connection.</para></returns>
- <notes><para><code>this->blocking() == true</code> implies <code><methodname>connection::blocked</methodname>() == true</code>
- for the connection. However, <code>this->blocking() == false</code> does not necessarily imply
- <code>connection::blocked() == false</code>, since the connection may be
- blocked by another <code>shared_connection_block</code> object.</para></notes>
- </method>
- </method-group>
- <method-group name="miscellaneous methods">
- <method name="connection" cv="const">
- <type><classname>boost::signals2::connection</classname></type>
- <returns>
- <para>A connection object for the connection referenced by <code>this</code>.</para>
- </returns>
- </method>
- </method-group>
- </class>
- </namespace>
- </namespace>
- </header>
|