Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/doc/html/boost/signalN.html @ 47

Last change on this file since 47 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 21.6 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.68.1">
7<link rel="start" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
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 C++ Libraries" 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="boost.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="signals/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#boost.signalNconstruct-copy-destruct">construct/copy/destruct</a></em></span>
63  <a href="signalN.html#id761212-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#id686974-bb">~signalN</a>();
66
67  <span class="emphasis"><em>// <a href="signalN.html#id652928-bb">connection management</a></em></span>
68  <span class="type"><a href="signals/connection.html" title="Class connection">signals::connection</a></span> 
69  <a href="signalN.html#id1033842-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="signals/connection.html" title="Class connection">signals::connection</a></span> 
71  <a href="signalN.html#id659445-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#id896208-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#id716715-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#id1009588-bb">disconnect_all_slots</a>();
76  <span class="type"><span class="bold"><strong>bool</strong></span></span> <a href="signalN.html#id687816-bb">empty</a>() <span class="bold"><strong>const</strong></span>;
77  <span class="type">std::size_t</span> <a href="signalN.html#id1219258-bb">num_slots</a>() <span class="bold"><strong>const</strong></span>;
78
79  <span class="emphasis"><em>// <a href="signalN.html#id998721-bb">invocation</a></em></span>
80  <span class="type">result_type</span> <a href="signalN.html#id624150-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#id1036608-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#id692589-bb">combiner access</a></em></span>
84  <span class="type">combiner_type&amp;</span> <a href="signalN.html#id646755-bb">combiner</a>();
85  <span class="type"><span class="bold"><strong>const</strong></span> combiner_type&amp;</span> <a href="signalN.html#id833200-bb">combiner</a>() <span class="bold"><strong>const</strong></span>;
86};</pre></div>
87<div class="refsect1" lang="en">
88<a name="id1629344"></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="id1629372"></a><h3>
98<a name="boost.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="id761212-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<div class="variablelist"><table border="0">
104<col align="left" valign="top">
105<tbody>
106<tr>
107<td>
108<span class="term">Effects:</span></td>
109<td>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.</td>
110</tr>
111<tr>
112<td>
113<span class="term">Postconditions:</span></td>
114<td><code class="computeroutput">this-&gt;<a href="signalN.html#id687816-bb">empty</a>()</code></td>
115</tr>
116</tbody>
117</table></div>
118</li>
119<li>
120<pre class="literallayout"><a name="id686974-bb"></a>~signalN();</pre>
121<div class="variablelist"><table border="0">
122<col align="left" valign="top">
123<tbody><tr>
124<td>
125<span class="term">Effects:</span></td>
126<td>Disconnects all slots connected to <code class="computeroutput">*this</code>.</td>
127</tr></tbody>
128</table></div>
129</li>
130</ol></div>
131</div>
132<div class="refsect2" lang="en">
133<a name="id1629484"></a><h3>
134<a name="id652928-bb"></a><code class="computeroutput">signalN</code> connection management</h3>
135<div class="orderedlist"><ol type="1">
136<li>
137<p><a name="id652932-bb"></a></p>
138<pre class="literallayout"><span class="type"><a href="signals/connection.html" title="Class connection">signals::connection</a></span> 
139<a name="id1033842-bb"></a>connect(<span class="bold"><strong>const</strong></span> slot_type&amp; slot,
140        signals::connect_position at = signals::at_back);
141<span class="type"><a href="signals/connection.html" title="Class connection">signals::connection</a></span> 
142<a name="id659445-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,
143        signals::connect_position at = signals::at_back);</pre>
144<div class="variablelist"><table border="0">
145<col align="left" valign="top">
146<tbody>
147<tr>
148<td>
149<span class="term">Effects:</span></td>
150<td>Connects the signal this to the incoming
151          slot. If the slot is inactive, i.e., any of the trackable
152          objects bound by the slot call have been destroyed, then the
153          call to connect is a no-op. If the second version of
154          <code class="computeroutput">connect</code> is invoked, the
155          slot is associated with the given group. The <code class="computeroutput">at</code>
156          parameter specifies where the slot should be connected:
157          <code class="computeroutput">at_front</code> indicates that the slot will be
158          connected at the front of the list or group of slots and
159          <code class="computeroutput">at_back</code> indicates that the slot will be
160          connected at the back of the list or group of
161          slots.</td>
162</tr>
163<tr>
164<td>
165<span class="term">Returns:</span></td>
166<td>A
167          <code class="computeroutput"><a href="signals/connection.html" title="Class connection">signals::connection</a></code>
168          object that references the newly-created connection between
169          the signal and the slot; if the slot is inactive, returns a
170          disconnected connection.</td>
171</tr>
172<tr>
173<td>
174<span class="term">Throws:</span></td>
175<td>This routine meets the strong exception guarantee,
176          where any exception thrown will cause the slot to not be
177          connected to the signal.</td>
178</tr>
179<tr>
180<td>
181<span class="term">Complexity:</span></td>
182<td>Constant time when connecting a slot
183          without a group name or logarithmic in the number of groups
184          when connecting to a particular
185          group.</td>
186</tr>
187<tr>
188<td>
189<span class="term">Notes:</span></td>
190<td>It is unspecified whether connecting a slot while the
191          signal is calling will result in the slot being called
192          immediately.</td>
193</tr>
194</tbody>
195</table></div>
196</li>
197<li>
198<p><a name="id896205-bb"></a></p>
199<pre class="literallayout"><span class="type"><span class="bold"><strong>void</strong></span></span> <a name="id896208-bb"></a>disconnect(<span class="bold"><strong>const</strong></span> group_type&amp; group);
200<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="id716715-bb"></a>disconnect(<span class="bold"><strong>const</strong></span> Slot&amp; slot);</pre>
201<div class="variablelist"><table border="0">
202<col align="left" valign="top">
203<tbody>
204<tr>
205<td>
206<span class="term">Effects:</span></td>
207<td>If the parameter is (convertible to) a
208          group name, any slots in the given group are
209          disconnected. Otherwise, any slots equal to the given slot
210          are disconnected.</td>
211</tr>
212<tr>
213<td>
214<span class="term">Throws:</span></td>
215<td>Will not throw unless a user destructor or
216          equality operator <code class="computeroutput">==</code> throws. If either throws,
217          not all slots may be disconnected.</td>
218</tr>
219<tr>
220<td>
221<span class="term">Complexity:</span></td>
222<td>If a group is given, O(lg g) + k where
223          g is the number of groups in the signal and k is the
224          number of slots in the group. Otherwise, linear in the
225          number of slots connected to the
226          signal.</td>
227</tr>
228</tbody>
229</table></div>
230</li>
231<li>
232<pre class="literallayout"><span class="type"><span class="bold"><strong>void</strong></span></span> <a name="id1009588-bb"></a>disconnect_all_slots();</pre>
233<div class="variablelist"><table border="0">
234<col align="left" valign="top">
235<tbody>
236<tr>
237<td>
238<span class="term">Effects:</span></td>
239<td>Disconnects all slots connected to the signal.</td>
240</tr>
241<tr>
242<td>
243<span class="term">Postconditions:</span></td>
244<td>
245<code class="computeroutput">this-&gt;<a href="signalN.html#id687816-bb">empty</a>()</code>.</td>
246</tr>
247<tr>
248<td>
249<span class="term">Throws:</span></td>
250<td>If disconnecting a slot causes an exception to be
251          thrown, not all slots may be disconnected.</td>
252</tr>
253<tr>
254<td>
255<span class="term">Complexity:</span></td>
256<td>Linear in the number of slots known to the
257          signal.</td>
258</tr>
259<tr>
260<td>
261<span class="term">Notes:</span></td>
262<td>May be called at any time within the lifetime of the
263          signal, including during calls to the signal's slots.</td>
264</tr>
265</tbody>
266</table></div>
267</li>
268<li>
269<pre class="literallayout"><span class="type"><span class="bold"><strong>bool</strong></span></span> <a name="id687816-bb"></a>empty() <span class="bold"><strong>const</strong></span>;</pre>
270<div class="variablelist"><table border="0">
271<col align="left" valign="top">
272<tbody>
273<tr>
274<td>
275<span class="term">Returns:</span></td>
276<td>
277<code class="computeroutput">true</code> if no slots
278          are connected to the signal, and
279          <code class="computeroutput">false</code> otherwise.</td>
280</tr>
281<tr>
282<td>
283<span class="term">Throws:</span></td>
284<td>Will not throw.</td>
285</tr>
286<tr>
287<td>
288<span class="term">Complexity:</span></td>
289<td>Linear in the number of slots known to the
290          signal.</td>
291</tr>
292<tr>
293<td>
294<span class="term">Rationale:</span></td>
295<td>Slots can disconnect at any point in time,
296          including while those same slots are being invoked. It is
297          therefore possible that the implementation must search
298          through a list of disconnected slots to determine if any
299          slots are still connected.</td>
300</tr>
301</tbody>
302</table></div>
303</li>
304<li>
305<pre class="literallayout"><span class="type">std::size_t</span> <a name="id1219258-bb"></a>num_slots() <span class="bold"><strong>const</strong></span>;</pre>
306<div class="variablelist"><table border="0">
307<col align="left" valign="top">
308<tbody>
309<tr>
310<td>
311<span class="term">Returns:</span></td>
312<td>The number of slots connected to the signal</td>
313</tr>
314<tr>
315<td>
316<span class="term">Throws:</span></td>
317<td>Will not throw.</td>
318</tr>
319<tr>
320<td>
321<span class="term">Complexity:</span></td>
322<td>Linear in the number of slots known to the
323          signal.</td>
324</tr>
325<tr>
326<td>
327<span class="term">Rationale:</span></td>
328<td>Slots can disconnect at any point in time,
329          including while those same slots are being invoked. It is
330          therefore possible that the implementation must search
331          through a list of disconnected slots to determine how many
332          slots are still connected.</td>
333</tr>
334</tbody>
335</table></div>
336</li>
337</ol></div>
338</div>
339<div class="refsect2" lang="en">
340<a name="id1629970"></a><h3>
341<a name="id998721-bb"></a><code class="computeroutput">signalN</code> invocation</h3>
342<div class="orderedlist"><ol type="1"><li>
343<p><a name="id998725-bb"></a></p>
344<pre class="literallayout"><span class="type">result_type</span> <a name="id624150-bb"></a><span class="bold"><strong>operator</strong></span>()(arg1_type a1, arg2_type a2, ..., argN_type aN);
345<span class="type">result_type</span> <a name="id1036608-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>
346<div class="variablelist"><table border="0">
347<col align="left" valign="top">
348<tbody>
349<tr>
350<td>
351<span class="term">Effects:</span></td>
352<td>Invokes the combiner with a
353          <code class="computeroutput">slot_call_iterator</code> range
354          [first, last) corresponding to the sequence of calls to the
355          slots connected to signal
356          <code class="computeroutput">*this</code>. Dereferencing an
357          iterator in this range causes a slot call with the given set
358          of parameters <code class="computeroutput">(a1, a2, ...,
359          aN)</code>, the result of which is returned from
360          the iterator dereference operation.</td>
361</tr>
362<tr>
363<td>
364<span class="term">Returns:</span></td>
365<td>The result returned by the combiner.</td>
366</tr>
367<tr>
368<td>
369<span class="term">Throws:</span></td>
370<td>If an exception is thrown by a slot call, or if the
371          combiner does not dereference any slot past some given slot,
372          all slots after that slot in the internal list of connected
373          slots will not be invoked.</td>
374</tr>
375<tr>
376<td>
377<span class="term">Notes:</span></td>
378<td>
379<p>Only the slots associated with iterators that are
380          actually dereferenced will be invoked. Multiple dereferences
381          of the same iterator will not result in multiple slot
382          invocations, because the return value of the slot will be
383          cached.</p>
384<p>The <code class="computeroutput">const</code> version of
385          the function call operator will invoke the combiner as
386          <code class="computeroutput">const</code>, whereas the
387          non-<code class="computeroutput">const</code> version will
388          invoke the combiner as
389          non-<code class="computeroutput">const</code>.</p>
390<p>Calling the function call operator may invoke undefined
391          behavior if no slots are connected to the signal, depending
392          on the combiner used. The default combiner is well-defined
393          for zero slots when the return type is void but is undefined
394          when the return type is any other type (because there is no
395          way to synthesize a return value).</p>
396</td>
397</tr>
398</tbody>
399</table></div>
400</li></ol></div>
401</div>
402<div class="refsect2" lang="en">
403<a name="id1630135"></a><h3>
404<a name="id692589-bb"></a><code class="computeroutput">signalN</code> combiner access</h3>
405<div class="orderedlist"><ol type="1"><li>
406<p><a name="id692592-bb"></a></p>
407<pre class="literallayout"><span class="type">combiner_type&amp;</span> <a name="id646755-bb"></a>combiner();
408<span class="type"><span class="bold"><strong>const</strong></span> combiner_type&amp;</span> <a name="id833200-bb"></a>combiner() <span class="bold"><strong>const</strong></span>;</pre>
409<div class="variablelist"><table border="0">
410<col align="left" valign="top">
411<tbody>
412<tr>
413<td>
414<span class="term">Returns:</span></td>
415<td>A reference to the stored combiner.</td>
416</tr>
417<tr>
418<td>
419<span class="term">Throws:</span></td>
420<td>Will not throw.</td>
421</tr>
422</tbody>
423</table></div>
424</li></ol></div>
425</div>
426</div>
427</div>
428<table width="100%"><tr>
429<td align="left"></td>
430<td align="right"><small>Copyright © 2001-2004 Douglas Gregor</small></td>
431</tr></table>
432<hr>
433<div class="spirit-nav">
434<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>
435</div>
436</body>
437</html>
Note: See TracBrowser for help on using the repository browser.