]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 Frank Mori Hess 2007-2009 | |
6 | ||
7 | Distributed under the Boost Software License, Version 1.0. (See accompanying | |
8 | file 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> |