142 lines
7.0 KiB
XML
142 lines
7.0 KiB
XML
<?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>
|