summaryrefslogtreecommitdiff
path: root/doc/html/signals/s05.html
blob: 27523e1b5e504c4e2cac614971a968c5084d3241 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Design Overview</title>
<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
<link rel="up" href="../signals.html" title="Chapter&#160;35.&#160;Boost.Signals">
<link rel="prev" href="s04.html" title="Frequently Asked Questions">
<link rel="next" href="s06.html" title="Design Rationale">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
<td align="center"><a href="../../../index.html">Home</a></td>
<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="s04.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../signals.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="s06.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="idp523973888"></a>Design Overview</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="s05.html#idp523974912">Type Erasure</a></span></dt>
<dt><span class="section"><a href="s05.html#idp523982176"><code class="computeroutput">connection</code> class</a></span></dt>
<dt><span class="section"><a href="s05.html#idp523995440">Slot Call Iterator</a></span></dt>
<dt><span class="section"><a href="s05.html#idp524017728"><code class="computeroutput">visit_each</code> function template</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="idp523974912"></a>Type Erasure</h3></div></div></div>
<p>"Type erasure", where static type information is eliminated
    by the use of dynamically dispatched interfaces, is used
    extensively within the Boost.Signals library to reduce the amount
    of code generated by template instantiation. Each signal must
    manage a list of slots and their associated connections, along
    with a <code class="computeroutput">std::map</code> to map from group identifiers to
    their associated connections. However, instantiating this map for
    every token type, and perhaps within each translation unit (for
    some popular template instantiation strategies) increase compile
    time overhead and space overhead.</p>
<p> To combat this so-called "template bloat", we use
    Boost.Function and Boost.Any to store unknown types and
    operations. Then, all of the code for handling the list of slots
    and the mapping from slot identifiers to connections is factored
    into the class <code class="computeroutput">signal_base</code>
    that deals exclusively with the <code class="computeroutput">any</code> and
    <code class="computeroutput"><a class="link" href="../boost/function.html" title="Class template function">function</a></code> objects, hiding the
    actual implementations using the well-known pimpl idiom. The
    actual <code class="computeroutput"><a class="link" href="../boost/signalN.html" title="Class template signalN">signalN</a></code> class templates
    deal only with code that will change depending on the number of
    arguments or which is inherently template-dependent (such as
    connection).</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="idp523982176"></a><code class="computeroutput">connection</code> class</h3></div></div></div>
<p> The <code class="computeroutput"><a class="link" href="../boost/signals/connection.html" title="Class connection">connection</a></code> class is
    central to the behavior of the Boost.Signals library. It is the
    only entity within the Boost.Signals system that has knowledge of
    all objects that are associated by a given connection. To be
    specific, the <code class="computeroutput"><a class="link" href="../boost/signals/connection.html" title="Class connection">connection</a></code> class
    itself is merely a thin wrapper over a
    <code class="computeroutput">shared_ptr</code> to a
    <code class="computeroutput">basic_connection</code> object.</p>
<p> <code class="computeroutput"><a class="link" href="../boost/signals/connection.html" title="Class connection">connection</a></code> objects are
    stored by all participants in the Signals system: each
    <code class="computeroutput"><a class="link" href="../boost/signals/trackable.html" title="Class trackable">trackable</a></code> object contains a
    list of <code class="computeroutput"><a class="link" href="../boost/signals/connection.html" title="Class connection">connection</a></code> objects
    describing all connections it is a part of; similarly, all signals
    contain a set of pairs that define a slot. The pairs consist of a
    slot function object (generally a Boost.Function object) and a
    <code class="computeroutput"><a class="link" href="../boost/signals/connection.html" title="Class connection">connection</a></code> object (that will
    disconnect on destruction). Finally, the mapping from slot groups
    to slots is based on the key value in a
    <code class="computeroutput">std::multimap</code> (the stored data
    in the <code class="computeroutput">std::multimap</code> is the
    slot pair).</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="idp523995440"></a>Slot Call Iterator</h3></div></div></div>
<p> The slot call iterator is conceptually a stack of iterator
    adaptors that modify the behavior of the underlying iterator
    through the list of slots. The following table describes the type
    and behavior of each iterator adaptor required. Note that this is
    only a conceptual model: the implementation collapses all these
    layers into a single iterator adaptor because several popular
    compilers failed to compile the implementation of the conceptual
    model.</p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th align="left">Iterator Adaptor</th>
<th align="left">Purpose</th>
</tr></thead>
<tbody>
<tr>
<td align="left"><p>Slot List Iterator</p></td>
<td align="left"><p>An iterator through the list of slots
            connected to a signal. The <code class="computeroutput">value_type</code> of this
            iterator will be
            <code class="computeroutput">std::pair&lt;any,
            connection&gt;</code>, where the
            <code class="computeroutput"><a class="link" href="../boost/any.html" title="Class any">any</a></code> contains an
            instance of the slot function type.</p></td>
</tr>
<tr>
<td align="left"><p>Filter Iterator Adaptor</p></td>
<td align="left"><p>This filtering iterator adaptor filters out
            slots that have been disconnected, so we never see a
            disconnected slot in later stages.</p></td>
</tr>
<tr>
<td align="left"><p>Projection Iterator Adaptor</p></td>
<td align="left"><p>The projection iterator adaptor returns a
            reference to the first member of the pair that constitutes
            a connected slot (e.g., just the
            <code class="computeroutput"><a class="link" href="../boost/any.html" title="Class any">boost::any</a></code> object that
            holds the slot function).</p></td>
</tr>
<tr>
<td align="left"><p>Transform Iterator Adaptor</p></td>
<td align="left"><p>This transform iterator adaptor performs an
            <code class="computeroutput"><a class="link" href="../boost/any_cast_idp424495968.html" title="Function any_cast">any_cast</a></code> to
            extract a reference to the slot function with the
            appropriate slot function type.</p></td>
</tr>
<tr>
<td align="left"><p>Transform Iterator Adaptor</p></td>
<td align="left"><p>This transform iterator adaptor calls the
            function object returned by dereferencing the underlying
            iterator with the set of arguments given to the signal
            itself, and returns the result of that slot
            call.</p></td>
</tr>
<tr>
<td align="left"><p>Input Caching Iterator Adaptor</p></td>
<td align="left"><p>This iterator adaptor caches the result of
            dereferencing the underlying iterator. Therefore,
            dereferencing this iterator multiple times will only
            result in the underlying iterator being dereferenced once;
            thus, a slot can only be called once but its result can be
            used multiple times.</p></td>
</tr>
<tr>
<td align="left"><p>Slot Call Iterator</p></td>
<td align="left"><p>Iterates over calls to each slot.</p></td>
</tr>
</tbody>
</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="idp524017728"></a><code class="computeroutput">visit_each</code> function template</h3></div></div></div>
<p> The <code class="computeroutput"><a class="link" href="../boost/visit_each.html" title="Function template visit_each">visit_each</a></code>
    function template is a mechanism for discovering objects that are
    stored within another object. Function template
    <code class="computeroutput"><a class="link" href="../boost/visit_each.html" title="Function template visit_each">visit_each</a></code> takes three
    arguments: an object to explore, a visitor function object that is
    invoked with each subobject, and the <code class="computeroutput">int</code> 0. </p>
<p> The third parameter is merely a temporary solution to the
    widespread lack of proper function template partial ordering. The
    primary <code class="computeroutput"><a class="link" href="../boost/visit_each.html" title="Function template visit_each">visit_each</a></code>
    function template specifies this third parameter type to be
    <code class="computeroutput">long</code>, whereas any user specializations must specify
    their third parameter to be of type <code class="computeroutput">int</code>. Thus, even
    though a broken compiler cannot tell the ordering between, e.g., a
    match against a parameter <code class="computeroutput">T</code> and a parameter
    <code class="computeroutput">A&lt;T&gt;</code>, it can determine that the conversion from
    the integer 0 to <code class="computeroutput">int</code> is better than the conversion to
    <code class="computeroutput">long</code>. The ordering determined by this conversion thus
    achieves partial ordering of the function templates in a limited,
    but successful, way. The following example illustrates the use of
    this technique:</p>
<pre class="programlisting">
template&lt;typename&gt; class A {};
template&lt;typename T&gt; void foo(T, long);
template&lt;typename T&gt; void foo(A&lt;T&gt;, int);
A&lt;T&gt; at;
foo(at, 0);
</pre>
<p> In this example, we assume that our compiler can not tell
    that <code class="computeroutput">A&lt;T&gt;</code> is a better match than
    <code class="computeroutput">T</code>, and therefore assume that the function templates
    cannot be ordered based on that parameter. Then the conversion
    from 0 to <code class="computeroutput">int</code> is better than the conversion from 0 to
    <code class="computeroutput">long</code>, and the second function template is
    chosen. </p>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2001-2004 Douglas Gregor<p>Use, modification and distribution is subject to the Boost
    Software License, Version 1.0. (See accompanying file
    <code class="filename">LICENSE_1_0.txt</code> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="s04.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../signals.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="s06.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>