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 Frank Mori Hess 2007-2009 6 7Distributed under the Boost Software License, Version 1.0. (See accompanying 8file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 9--> 10<header name="boost/signals2/shared_connection_block.hpp" last-revision="$Date: 2007-03-06 16:51:55 -0500 (Tue, 06 Mar 2007) $"> 11 <using-namespace name="boost::signals2"/> 12 <using-namespace name="boost"/> 13 <using-class name="boost::signals2::connection"/> 14 <namespace name="boost"> 15 <namespace name="signals2"> 16 <class name="shared_connection_block"> 17 <purpose>Blocks a connection between a signal and a slot.</purpose> 18 19 <description> 20 <para>A <code>shared_connection_block</code> object blocks a 21 connection, preventing the associated slot from executing when the 22 associated signal is invoked. The connection will remain 23 blocked until every <code>shared_connection_block</code> that references 24 the connection 25 releases its block. A <code>shared_connection_block</code> releases 26 its block when it is destroyed or its 27 <methodname>unblock</methodname> method is called.</para> 28 <para>A <code>shared_connection_block</code> is safe to use even 29 after the <classname>signals2::connection</classname> object it was constructed 30 from has been destroyed, or the connection it references has been 31 disconnected.</para> 32 <para> 33 Note, blocking a connection does not guarantee the associated slot 34 has finished execution if it is already in the process of being run 35 when the connection block goes into effect. This is similar 36 to the behaviour of disconnect, in that blocking a connection 37 will not wait for the connection's associated slot to complete execution. 38 This situation may arise in a multi-threaded environment if the 39 connection block goes into effect concurrently with signal invocation, 40 or in a single-threaded environment if a slot blocks its own 41 connection. 42 </para> 43 </description> 44 45 <constructor> 46 <parameter name="conn"> 47 <paramtype>const <classname>boost::signals2::connection</classname> &</paramtype> 48 <default>connection()</default> 49 </parameter> 50 <parameter name="initially_blocking"> 51 <paramtype>bool</paramtype> 52 <default>true</default> 53 </parameter> 54 55 <effects> 56 <para>Creates a <code>shared_connection_block</code> which can block 57 the connection referenced by <code>conn</code>. The <code>shared_connection_block</code> 58 will initially block the connection if and only if the 59 <code>initially_blocking</code> 60 parameter is <code>true</code>. The block on the connection may be released 61 by calling the <methodname>unblock</methodname> method, 62 or destroying the <code>shared_connection_block</code> object.</para> 63 <para>Default construction of a <code>shared_connection_block</code> results in a 64 <code>shared_connection_block</code> which references the NULL connection. 65 Such a <code>shared_connection_block</code> is safe to use, though not 66 particularly useful until it is assigned another 67 <code>shared_connection_block</code> which references a real connection. 68 </para> 69 </effects> 70 <postconditions><para><code>this->blocking() == initially_blocking</code></para></postconditions> 71 </constructor> 72 <constructor> 73 <parameter name="other"> 74 <paramtype>const boost::signals2::shared_connection_block &</paramtype> 75 </parameter> 76 77 <effects> 78 <para> 79 Copy constructs a <code>shared_connection_block</code> which references 80 the same connection as <code>other</code>. 81 </para> 82 </effects> 83 <postconditions> 84 <para><code>this->connection() == other.connection()</code></para> 85 <para><code>this->blocking() == other.blocking()</code></para> 86 </postconditions> 87 </constructor> 88 <destructor> 89 <effects><para>If <methodname>blocking</methodname>() is true, releases the connection block.</para></effects> 90 </destructor> 91 <copy-assignment> 92 <parameter name="rhs"> 93 <paramtype>const boost::signals2::shared_connection_block &</paramtype> 94 </parameter> 95 96 <effects> 97 <para> 98 Makes <code>this</code> reference the same connection as <code>rhs</code>. 99 </para> 100 </effects> 101 <postconditions> 102 <para><code>this->connection() == rhs.connection()</code></para> 103 <para><code>this->blocking() == rhs.blocking()</code></para> 104 </postconditions> 105 <throws><para>Will not throw.</para></throws> 106 </copy-assignment> 107 <method-group name="connection blocking"> 108 <method name="unblock"> 109 <type>void</type> 110 <effects><para>If <methodname>blocking</methodname>() is true, releases the connection block. 111 Note, the connection may remain blocked due to 112 other <code>shared_connection_block</code> objects.</para></effects> 113 <postconditions><para><code>this->blocking() == false</code>.</para></postconditions> 114 </method> 115 <method name="block"> 116 <type>void</type> 117 <effects><para>If <methodname>blocking</methodname>() is false, reasserts a block on 118 the connection.</para></effects> 119 <postconditions><para><code>this->blocking() == true</code>.</para></postconditions> 120 </method> 121 <method name="blocking" cv="const"> 122 <type>bool</type> 123 <returns><para><code>true</code> if <code>this</code> is asserting a block on the connection.</para></returns> 124 <notes><para><code>this->blocking() == true</code> implies <code><methodname>connection::blocked</methodname>() == true</code> 125 for the connection. However, <code>this->blocking() == false</code> does not necessarily imply 126 <code>connection::blocked() == false</code>, since the connection may be 127 blocked by another <code>shared_connection_block</code> object.</para></notes> 128 </method> 129 </method-group> 130 <method-group name="miscellaneous methods"> 131 <method name="connection" cv="const"> 132 <type><classname>boost::signals2::connection</classname></type> 133 <returns> 134 <para>A connection object for the connection referenced by <code>this</code>.</para> 135 </returns> 136 </method> 137 </method-group> 138 </class> 139 </namespace> 140 </namespace> 141</header> 142