doc/html/signals/s05.html

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