Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_33_1/doc/html/signalN.html @ 25

Last change on this file since 25 was 12, checked in by landauf, 18 years ago

added boost
File size: 22.0 KB
Line 
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Class template signalN</title>
5<link rel="stylesheet" href="boostbook.css" type="text/css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.69.1">
7<link rel="start" href="index.html" title="The Boost C++ Libraries">
8<link rel="up" href="signals/reference.html#header.boost.signal.hpp" title="Header &lt;boost/signal.hpp&gt;">
9<link rel="prev" href="signals/reference.html" title="Reference">
10<link rel="next" href="signal.html" title="Class template signal">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
13<table cellpadding="2" width="100%">
14<td valign="top"><img alt="boost.png (6897 bytes)" width="277" height="86" src="../../boost.png"></td>
15<td align="center"><a href="../../index.htm">Home</a></td>
16<td align="center"><a href="../../libs/libraries.htm">Libraries</a></td>
17<td align="center"><a href="../../people/people.htm">People</a></td>
18<td align="center"><a href="../../more/faq.htm">FAQ</a></td>
19<td align="center"><a href="../../more/index.htm">More</a></td>
20</table>
21<hr>
22<div class="spirit-nav">
23<a accesskey="p" href="signals/reference.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="signals/reference.html#header.boost.signal.hpp"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="signal.html"><img src="images/next.png" alt="Next"></a>
24</div>
25<div class="refentry" lang="en">
26<a name="signalN"></a><div class="titlepage"></div>
27<div class="refnamediv">
28<h2><span class="refentrytitle">Class template signalN</span></h2>
29<p>boost::signalN &#8212; Set of safe multicast callback types.</p>
30</div>
31<h2 xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="refsynopsisdiv-title">Synopsis</h2>
32<div xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="refsynopsisdiv"><pre class="synopsis"><span class="bold"><strong>template</strong></span>&lt;<span class="bold"><strong>typename</strong></span> R, <span class="bold"><strong>typename</strong></span> T1, <span class="bold"><strong>typename</strong></span> T2, ..., <span class="bold"><strong>typename</strong></span> TN,
33         <span class="bold"><strong>typename</strong></span> Combiner = <a href="last_value.html" title="Class template last_value">last_value</a>&lt;R&gt;, <span class="bold"><strong>typename</strong></span> Group = <span class="bold"><strong>int</strong></span>,
34         <span class="bold"><strong>typename</strong></span> GroupCompare = std::less&lt;Group&gt;,
35         <span class="bold"><strong>typename</strong></span> SlotFunction = <a href="functionN.html" title="Class template functionN">functionN</a>&lt;R, T1, T2, ..., TN&gt; &gt; 
36<span class="bold"><strong>class</strong></span> signalN : <span class="bold"><strong>public</strong></span> <a href="trackable.html" title="Class trackable">signals::trackable</a>,
37                <span class="bold"><strong>private</strong></span> noncopyable   <span class="emphasis"><em>// Exposition only</em></span>
38{
39<span class="bold"><strong>public</strong></span>:
40  <span class="emphasis"><em>// types</em></span>
41  <span class="bold"><strong>typedef</strong></span> <span class="bold"><strong>typename</strong></span> Combiner::result_type result_type;         
42  <span class="bold"><strong>typedef</strong></span> Combiner                       combiner_type;       
43  <span class="bold"><strong>typedef</strong></span> Group                          group_type;          
44  <span class="bold"><strong>typedef</strong></span> GroupCompare                   group_compare_type;  
45  <span class="bold"><strong>typedef</strong></span> SlotFunction                   slot_function_type;  
46  <span class="bold"><strong>typedef</strong></span> <a href="slot.html" title="Class template slot">slot</a>&lt;SlotFunction&gt;             slot_type;           
47  <span class="bold"><strong>typedef</strong></span> <span class="emphasis"><em>unspecified</em></span>                    slot_result_type;    
48  <span class="bold"><strong>typedef</strong></span> <span class="emphasis"><em>unspecified</em></span>                    slot_call_iterator;  
49  <span class="bold"><strong>typedef</strong></span> T1                             argument_type;         <span class="emphasis"><em>// If N == 1</em></span>
50  <span class="bold"><strong>typedef</strong></span> T1                             first_argument_type;   <span class="emphasis"><em>// If N == 2</em></span>
51  <span class="bold"><strong>typedef</strong></span> T2                             second_argument_type;  <span class="emphasis"><em>// If N == 2</em></span>
52  <span class="bold"><strong>typedef</strong></span> T1                             arg1_type;           
53  <span class="bold"><strong>typedef</strong></span> T2                             arg2_type;           
54     .
55     .
56     .
57  <span class="bold"><strong>typedef</strong></span> TN                             argN_type;           
58
59  <span class="emphasis"><em>// static constants</em></span>
60  <span class="bold"><strong>static</strong></span> <span class="bold"><strong>const</strong></span> <span class="bold"><strong>int</strong></span> arity = N;
61
62  <span class="emphasis"><em>// <a href="signalN.html#signalNconstruct-copy-destruct">construct/copy/destruct</a></em></span>
63  <a href="signalN.html#id2542236-bb">signalN</a>(<span class="bold"><strong>const</strong></span> combiner_type&amp; = combiner_type(),
64          <span class="bold"><strong>const</strong></span> group_compare_type&amp; = group_compare_type());
65  <a href="signalN.html#id2577993-bb">~signalN</a>();
66
67  <span class="emphasis"><em>// <a href="signalN.html#id2551386-bb">connection management</a></em></span>
68  <span class="type"><a href="connection.html" title="Class connection">signals::connection</a></span> 
69  <a href="signalN.html#id2584315-bb">connect</a>(<span class="bold"><strong>const</strong></span> slot_type&amp;, signals::connect_position = signals::at_back);
70  <span class="type"><a href="connection.html" title="Class connection">signals::connection</a></span> 
71  <a href="signalN.html#id2581263-bb">connect</a>(<span class="bold"><strong>const</strong></span> group_type&amp;, <span class="bold"><strong>const</strong></span> slot_type&amp;,
72          signals::connect_position = signals::at_back);
73  <span class="type"><span class="bold"><strong>void</strong></span></span> <a href="signalN.html#id2544431-bb">disconnect</a>(<span class="bold"><strong>const</strong></span> group_type&amp;);
74  <span class="bold"><strong>template</strong></span>&lt;<span class="bold"><strong>typename</strong></span> Slot&gt; <span class="type"><span class="bold"><strong>void</strong></span></span> <a href="signalN.html#id2556593-bb">disconnect</a>(<span class="bold"><strong>const</strong></span> Slot&amp;);
75  <span class="type"><span class="bold"><strong>void</strong></span></span> <a href="signalN.html#id2576703-bb">disconnect_all_slots</a>();
76  <span class="type"><span class="bold"><strong>bool</strong></span></span> <a href="signalN.html#id2567596-bb">empty</a>() <span class="bold"><strong>const</strong></span>;
77  <span class="type">std::size_t</span> <a href="signalN.html#id2337290-bb">num_slots</a>() <span class="bold"><strong>const</strong></span>;
78
79  <span class="emphasis"><em>// <a href="signalN.html#id2585919-bb">invocation</a></em></span>
80  <span class="type">result_type</span> <a href="signalN.html#id2578239-bb"><span class="bold"><strong>operator</strong></span>()</a>(arg1_type, arg2_type, ..., argN_type);
81  <span class="type">result_type</span> <a href="signalN.html#id2581156-bb"><span class="bold"><strong>operator</strong></span>()</a>(arg1_type, arg2_type, ..., argN_type) <span class="bold"><strong>const</strong></span>;
82
83  <span class="emphasis"><em>// <a href="signalN.html#id2566385-bb">combiner access</a></em></span>
84  <span class="type">combiner_type&amp;</span> <a href="signalN.html#id2412919-bb">combiner</a>();
85  <span class="type"><span class="bold"><strong>const</strong></span> combiner_type&amp;</span> <a href="signalN.html#id2586486-bb">combiner</a>() <span class="bold"><strong>const</strong></span>;
86};</pre></div>
87<div class="refsect1" lang="en">
88<a name="id2734528"></a><h2>Description</h2>
89<p>The class template <a href="signalN.html" title="Class template signalN">signalN</a> covers
90         several related classes signal0, signal1, signal2, etc.,
91         where the number suffix describes the number of function
92         parameters the signal and its connected slots will
93         take. Instead of enumerating all classes, a single pattern
94         <a href="signalN.html" title="Class template signalN">signalN</a> will be described, where N
95         represents the number of function parameters.</p>
96<div class="refsect2" lang="en">
97<a name="id2734553"></a><h3>
98<a name="signalNconstruct-copy-destruct"></a><code class="computeroutput">signalN</code> construct/copy/destruct</h3>
99<div class="orderedlist"><ol type="1">
100<li>
101<pre class="literallayout"><a name="id2542236-bb"></a>signalN(<span class="bold"><strong>const</strong></span> combiner_type&amp; combiner = combiner_type(),
102        <span class="bold"><strong>const</strong></span> group_compare_type&amp; compare = group_compare_type());</pre>
103<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Effects</span></b>:
104
105    Initializes the signal to contain no slots, copies the given combiner into internal storage, and stores the given group comparison function object to compare groups.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Postconditions</span></b>:
106
107    <code class="computeroutput">this-&gt;<a href="signalN.html#id2567596-bb">empty</a>()</code></p>
108</li>
109<li>
110<pre class="literallayout"><a name="id2577993-bb"></a>~signalN();</pre>
111<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Effects</span></b>:
112
113    Disconnects all slots connected to <code class="computeroutput">*this</code>.</p>
114</li>
115</ol></div>
116</div>
117<div class="refsect2" lang="en">
118<a name="id2734663"></a><h3>
119<a name="id2551386-bb"></a><code class="computeroutput">signalN</code> connection management</h3>
120<div class="orderedlist"><ol type="1">
121<li>
122<p><a name="id2551390-bb"></a></p>
123<pre class="literallayout"><span class="type"><a href="connection.html" title="Class connection">signals::connection</a></span> 
124<a name="id2584315-bb"></a>connect(<span class="bold"><strong>const</strong></span> slot_type&amp; slot,
125        signals::connect_position at = signals::at_back);
126<span class="type"><a href="connection.html" title="Class connection">signals::connection</a></span> 
127<a name="id2581263-bb"></a>connect(<span class="bold"><strong>const</strong></span> group_type&amp; group, <span class="bold"><strong>const</strong></span> slot_type&amp; slot,
128        signals::connect_position at = signals::at_back);</pre>
129<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Effects</span></b>:
130
131    Connects the signal this to the incoming
132          slot. If the slot is inactive, i.e., any of the trackable
133          objects bound by the slot call have been destroyed, then the
134          call to connect is a no-op. If the second version of
135          <code class="computeroutput">connect</code> is invoked, the
136          slot is associated with the given group. The <code class="computeroutput">at</code>
137          parameter specifies where the slot should be connected:
138          <code class="computeroutput">at_front</code> indicates that the slot will be
139          connected at the front of the list or group of slots and
140          <code class="computeroutput">at_back</code> indicates that the slot will be
141          connected at the back of the list or group of
142          slots.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Returns</span></b>:
143
144    A
145          <code class="computeroutput"><a href="connection.html" title="Class connection">signals::connection</a></code>
146          object that references the newly-created connection between
147          the signal and the slot; if the slot is inactive, returns a
148          disconnected connection.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Throws</span></b>:
149
150    This routine meets the strong exception guarantee,
151          where any exception thrown will cause the slot to not be
152          connected to the signal.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Complexity</span></b>:
153
154    Constant time when connecting a slot
155          without a group name or logarithmic in the number of groups
156          when connecting to a particular
157          group.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Notes</span></b>:
158
159    It is unspecified whether connecting a slot while the
160          signal is calling will result in the slot being called
161          immediately.</p>
162</li>
163<li>
164<p><a name="id2582644-bb"></a></p>
165<pre class="literallayout"><span class="type"><span class="bold"><strong>void</strong></span></span> <a name="id2544431-bb"></a>disconnect(<span class="bold"><strong>const</strong></span> group_type&amp; group);
166<span class="bold"><strong>template</strong></span>&lt;<span class="bold"><strong>typename</strong></span> Slot&gt; <span class="type"><span class="bold"><strong>void</strong></span></span> <a name="id2556593-bb"></a>disconnect(<span class="bold"><strong>const</strong></span> Slot&amp; slot);</pre>
167<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Effects</span></b>:
168
169    If the parameter is (convertible to) a
170          group name, any slots in the given group are
171          disconnected. Otherwise, any slots equal to the given slot
172          are disconnected.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Throws</span></b>:
173
174    Will not throw unless a user destructor or
175          equality operator <code class="computeroutput">==</code> throws. If either throws,
176          not all slots may be disconnected.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Complexity</span></b>:
177
178    If a group is given, O(lg g) + k where
179          g is the number of groups in the signal and k is the
180          number of slots in the group. Otherwise, linear in the
181          number of slots connected to the
182          signal.</p>
183</li>
184<li>
185<pre class="literallayout"><span class="type"><span class="bold"><strong>void</strong></span></span> <a name="id2576703-bb"></a>disconnect_all_slots();</pre>
186<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Effects</span></b>:
187
188    Disconnects all slots connected to the signal.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Postconditions</span></b>:
189
190    <code class="computeroutput">this-&gt;<a href="signalN.html#id2567596-bb">empty</a>()</code>.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Throws</span></b>:
191
192    If disconnecting a slot causes an exception to be
193          thrown, not all slots may be disconnected.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Complexity</span></b>:
194
195    Linear in the number of slots known to the
196          signal.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Notes</span></b>:
197
198    May be called at any time within the lifetime of the
199          signal, including during calls to the signal's slots.</p>
200</li>
201<li>
202<pre class="literallayout"><span class="type"><span class="bold"><strong>bool</strong></span></span> <a name="id2567596-bb"></a>empty() <span class="bold"><strong>const</strong></span>;</pre>
203<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Returns</span></b>:
204
205    <code class="computeroutput">true</code> if no slots
206          are connected to the signal, and
207          <code class="computeroutput">false</code> otherwise.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Throws</span></b>:
208
209    Will not throw.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Complexity</span></b>:
210
211    Linear in the number of slots known to the
212          signal.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Rationale</span></b>:
213
214    Slots can disconnect at any point in time,
215          including while those same slots are being invoked. It is
216          therefore possible that the implementation must search
217          through a list of disconnected slots to determine if any
218          slots are still connected.</p>
219</li>
220<li>
221<pre class="literallayout"><span class="type">std::size_t</span> <a name="id2337290-bb"></a>num_slots() <span class="bold"><strong>const</strong></span>;</pre>
222<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Returns</span></b>:
223
224    The number of slots connected to the signal<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Throws</span></b>:
225
226    Will not throw.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Complexity</span></b>:
227
228    Linear in the number of slots known to the
229          signal.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Rationale</span></b>:
230
231    Slots can disconnect at any point in time,
232          including while those same slots are being invoked. It is
233          therefore possible that the implementation must search
234          through a list of disconnected slots to determine how many
235          slots are still connected.</p>
236</li>
237</ol></div>
238</div>
239<div class="refsect2" lang="en">
240<a name="id2735148"></a><h3>
241<a name="id2585919-bb"></a><code class="computeroutput">signalN</code> invocation</h3>
242<div class="orderedlist"><ol type="1"><li>
243<p><a name="id2585923-bb"></a></p>
244<pre class="literallayout"><span class="type">result_type</span> <a name="id2578239-bb"></a><span class="bold"><strong>operator</strong></span>()(arg1_type a1, arg2_type a2, ... , argN_type aN);
245<span class="type">result_type</span> <a name="id2581156-bb"></a><span class="bold"><strong>operator</strong></span>()(arg1_type a1, arg2_type a2, ... , argN_type aN) <span class="bold"><strong>const</strong></span>;</pre>
246<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Effects</span></b>:
247
248    Invokes the combiner with a
249          <code class="computeroutput">slot_call_iterator</code> range
250          [first, last) corresponding to the sequence of calls to the
251          slots connected to signal
252          <code class="computeroutput">*this</code>. Dereferencing an
253          iterator in this range causes a slot call with the given set
254          of parameters <code class="computeroutput">(a1, a2, ...,
255          aN)</code>, the result of which is returned from
256          the iterator dereference operation.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Returns</span></b>:
257
258    The result returned by the combiner.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Throws</span></b>:
259
260    If an exception is thrown by a slot call, or if the
261          combiner does not dereference any slot past some given slot,
262          all slots after that slot in the internal list of connected
263          slots will not be invoked.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Notes</span></b>:
264
265    Only the slots associated with iterators that are
266          actually dereferenced will be invoked. Multiple dereferences
267          of the same iterator will not result in multiple slot
268          invocations, because the return value of the slot will be
269          cached.<p>The <code class="computeroutput">const</code> version of
270          the function call operator will invoke the combiner as
271          <code class="computeroutput">const</code>, whereas the
272          non-<code class="computeroutput">const</code> version will
273          invoke the combiner as
274          non-<code class="computeroutput">const</code>.</p><p>Calling the function call operator may invoke undefined
275          behavior if no slots are connected to the signal, depending
276          on the combiner used. The default combiner is well-defined
277          for zero slots when the return type is void but is undefined
278          when the return type is any other type (because there is no
279          way to synthesize a return value).</p></p>
280</li></ol></div>
281</div>
282<div class="refsect2" lang="en">
283<a name="id2735315"></a><h3>
284<a name="id2566385-bb"></a><code class="computeroutput">signalN</code> combiner access</h3>
285<div class="orderedlist"><ol type="1"><li>
286<p><a name="id2587510-bb"></a></p>
287<pre class="literallayout"><span class="type">combiner_type&amp;</span> <a name="id2412919-bb"></a>combiner();
288<span class="type"><span class="bold"><strong>const</strong></span> combiner_type&amp;</span> <a name="id2586486-bb"></a>combiner() <span class="bold"><strong>const</strong></span>;</pre>
289<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Returns</span></b>:
290
291    A reference to the stored combiner.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Throws</span></b>:
292
293    Will not throw.</p>
294</li></ol></div>
295</div>
296</div>
297</div>
298<table width="100%"><tr>
299<td align="left"></td>
300<td align="right"><small>Copyright © 2001-2004 Douglas Gregor</small></td>
301</tr></table>
302<hr>
303<div class="spirit-nav">
304<a accesskey="p" href="signals/reference.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="signals/reference.html#header.boost.signal.hpp"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="signal.html"><img src="images/next.png" alt="Next"></a>
305</div>
306</body>
307</html>
Note: See TracBrowser for help on using the repository browser.