ceph/src/boost/libs/variant/doc/misc.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
   3   "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
   4 <!--
   5     Copyright 2003, Eric Friedman, Itay Maman.
   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 <section id="variant.misc">
  11   <title>Miscellaneous Notes</title>
  12
  13 <using-namespace name="boost"/>
  14
  15 <section id="variant.versus-any">
  16   <title>Boost.Variant vs. Boost.Any</title>
  17
  18   <para>As a discriminated union container, the Variant library shares many
  19     of the same features of the <libraryname>Any</libraryname> library.
  20     However, since neither library wholly encapsulates the features of the
  21     other, one library cannot be generally recommended for use over the
  22     other.</para>
  23
  24   <para>That said, Boost.Variant has several advantages over Boost.Any,
  25     such as:
  26
  27     <itemizedlist>
  28       <listitem>Boost.Variant guarantees the type of its content is one of a
  29         finite, user-specified set of types.</listitem>
  30       <listitem>Boost.Variant provides <emphasis>compile-time</emphasis>
  31         checked visitation of its content. (By contrast, the current version
  32         of Boost.Any provides no visitation mechanism at all; but even if it
  33         did, it would need to be checked at run-time.)</listitem>
  34       <listitem>Boost.Variant enables generic visitation of its content.
  35         (Even if Boost.Any did provide a visitation mechanism, it would enable
  36         visitation only of explicitly-specified types.)</listitem>
  37       <listitem>Boost.Variant offers an efficient, stack-based storage scheme
  38         (avoiding the overhead of dynamic allocation).</listitem>
  39     </itemizedlist>
  40
  41   </para>
  42
  43   <para>Of course, Boost.Any has several advantages over Boost.Variant,
  44     such as:
  45
  46     <itemizedlist>
  47       <listitem>Boost.Any, as its name implies, allows virtually any type for
  48         its content, providing great flexibility.</listitem>
  49       <listitem>Boost.Any provides the no-throw guarantee of exception safety
  50         for its swap operation.</listitem>
  51       <listitem>Boost.Any makes little use of template metaprogramming
  52         techniques (avoiding potentially hard-to-read error messages and
  53         significant compile-time processor and memory demands).</listitem>
  54     </itemizedlist>
  55
  56   </para>
  57
  58 </section>
  59
  60 <section>
  61   <title>Portability</title>
  62
  63   <para>The library aims for 100% ANSI/ISO C++ conformance. However, this is
  64     strictly impossible due to the inherently non-portable nature of the
  65     <libraryname>Type Traits</libraryname> library's
  66     <code><classname>type_with_alignment</classname></code> facility. In
  67     practice though, no compilers or platforms have been discovered where this
  68     reliance on undefined behavior has been an issue.</para>
  69
  70   <para>Additionally, significant effort has been expended to ensure proper
  71     functioning despite various compiler bugs and other conformance problems.
  72     To date the library testsuite has
  73     been compiled and tested successfully on at least the following compilers
  74     for basic and advanced functionality:
  75
  76     <informaltable>
  77       <tgroup cols="5">
  78         <thead>
  79           <row>
  80             <entry></entry>
  81             <entry>Basic</entry>
  82             <entry>
  83               <code>variant&lt;T&amp;&gt;</code>
  84             </entry>
  85             <entry>
  86               <link linkend="variant.tutorial.over-sequence">
  87                 <code>make_variant_over</code>
  88               </link>
  89             </entry>
  90             <entry>
  91               <link linkend="variant.tutorial.recursive.recursive-variant">
  92                 <code>make_recursive_variant</code>
  93               </link>
  94             </entry>
  95           </row>
  96         </thead>
  97         <tbody>
  98           <row>
  99             <entry>Borland C++ 5.5.1 and 5.6.4</entry>
 100             <entry>X</entry>
 101             <entry>X</entry>
 102             <entry></entry>
 103             <entry></entry>
 104           </row>
 105           <row>
 106             <entry>Comeau C++ 4.3.0</entry>
 107             <entry>X</entry>
 108             <entry>X</entry>
 109             <entry>X</entry>
 110             <entry>X</entry>
 111           </row>
 112           <row>
 113             <entry>GNU GCC 3.3.1</entry>
 114             <entry>X</entry>
 115             <entry>X</entry>
 116             <entry>X</entry>
 117             <entry>X</entry>
 118           </row>
 119           <row>
 120             <entry>GNU GCC 2.95.3</entry>
 121             <entry>X</entry>
 122             <entry>X</entry>
 123             <entry></entry>
 124             <entry>X</entry>
 125           </row>
 126           <row>
 127             <entry>Intel C++ 7.0</entry>
 128             <entry>X</entry>
 129             <entry></entry>
 130             <entry>X</entry>
 131             <entry>X</entry>
 132           </row>
 133           <row>
 134             <entry>Metrowerks CodeWarrior 8.3</entry>
 135             <entry>X</entry>
 136             <entry></entry>
 137             <entry>X</entry>
 138             <entry>X</entry>
 139           </row>
 140           <row>
 141             <entry>Microsoft Visual C++ 7.1</entry>
 142             <entry>X</entry>
 143             <entry>X</entry>
 144             <entry>X</entry>
 145             <entry>X</entry>
 146           </row>
 147           <row>
 148             <entry>Microsoft Visual C++ 6 SP5 and 7</entry>
 149             <entry>X</entry>
 150             <entry></entry>
 151             <entry></entry>
 152             <entry></entry>
 153           </row>
 154         </tbody>
 155       </tgroup>
 156     </informaltable>
 157
 158   </para>
 159
 160   <para>Finally, the current state of the testsuite in CVS may be found on the
 161     <ulink url="http://boost.sourceforge.net/regression-logs">Test Summary</ulink>
 162     page. Please note, however, that this page reports on day-to-day changes
 163     to inter-release code found in the Boost CVS and thus likely does not
 164     match the state of code found in Boost releases.</para>
 165
 166 </section>
 167
 168 <section id="variant.troubleshooting">
 169   <title>Troubleshooting</title>
 170
 171 <para>Due to the heavy use of templates in the implementation of
 172   <code>variant</code>, it is not uncommon when compiling to encounter
 173   problems related to template instantiaton depth, compiler memory, etc. This
 174   section attempts to provide advice to common problems experienced on several
 175   popular compilers.</para>
 176
 177 <para>(This section is still in progress, with additional advice/feedback
 178   welcome. Please post to the Boost-Users list with any useful experiences you
 179   may have.)</para>
 180
 181   <section id="variant.troubleshooting.template-depth">
 182     <title>&quot;Template instantiation depth exceeds maximum&quot;</title>
 183
 184     <section id="variant.troubleshooting.template-depth.gcc">
 185       <title>GNU GCC</title>
 186       <para>The compiler option
 187         <code>-ftemplate-depth-<emphasis>NN</emphasis></code> can increase the
 188         maximum allowed instantiation depth. (Try
 189         <code>-ftemplate-depth-50</code>.)</para>
 190     </section>
 191   </section>
 192
 193   <section id="variant.troubleshooting.compiler-memory">
 194     <title>&quot;Internal heap limit reached&quot;</title>
 195
 196     <section id="variant.troubleshooting.compiler-memory.msvc">
 197       <title>Microsoft Visual C++</title>
 198       <para>The compiler option <code>/Zm<emphasis>NNN</emphasis></code> can
 199         increase the memory allocation limit. The <code>NNN</code> is a
 200         scaling percentage (i.e., <code>100</code> denotes the default limit).
 201         (Try <code>/Zm200</code>.)</para>
 202     </section>
 203   </section>
 204
 205 </section>
 206
 207 <section id="variant.ack">
 208   <title>Acknowledgments</title>
 209
 210 <para>Eric Friedman and Itay Maman designed the initial submission; Eric was
 211   the primary implementer.</para>
 212
 213 <para>Eric is also the library maintainer and has expanded upon the initial
 214   submission -- adding
 215   <code><classname>make_recursive_variant</classname></code>,
 216   <code><classname>make_variant_over</classname></code>, support for
 217   reference content, etc.</para>
 218
 219 <para>Andrei Alexandrescu's work in
 220     [<link linkend="variant.refs.ale01a">Ale01a</link>]
 221 and
 222     [<link linkend="variant.refs.ale02">Ale02</link>]
 223 inspired the library's design.</para>
 224
 225 <para>Jeff Garland was the formal review manager.</para>
 226
 227 <para>Douglas Gregor,
 228 Dave Abrahams,
 229 Anthony Williams,
 230 Fernando Cacciola,
 231 Joel de Guzman,
 232 Dirk Schreib,
 233 Brad King,
 234 Giovanni Bajo,
 235 Eugene Gladyshev,
 236 and others provided helpful feedback and suggestions to refine the semantics,
 237 interface, and implementation of the library.</para>
 238
 239 </section>
 240
 241 </section>