libstdc++-v3/doc/xml/manual/using.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
   4 [ ]>
   5
   6 <chapter id="manual.intro.using" xreflabel="Using">
   7 <?dbhtml filename="using.html"?>
   8
   9 <title>Using</title>
  10
  11   <sect1 id="manual.intro.using.lib" xreflabel="Lib">
  12     <title>Linking Library Binary Files</title>
  13
  14     <para>
  15       If you only built a static library (libstdc++.a), or if you
  16       specified static linking, you don't have to worry about this.
  17       But if you built a shared library (libstdc++.so) and linked
  18       against it, then you will need to find that library when you run
  19       the executable.
  20     </para>
  21     <para>
  22       Methods vary for different platforms and different styles, but
  23       the usual ones are printed to the screen during installation.
  24       They include:
  25     </para>
  26     <itemizedlist>
  27       <listitem>
  28         <para>
  29           At runtime set LD_LIBRARY_PATH in your environment
  30           correctly, so that the shared library for libstdc++ can be
  31           found and loaded.  Be certain that you understand all of the
  32           other implications and behavior of LD_LIBRARY_PATH first
  33           (few people do, and they get into trouble).
  34         </para>
  35       </listitem>
  36       <listitem>
  37         <para>
  38           Compile the path to find the library at runtime into the
  39           program.  This can be done by passing certain options to
  40           g++, which will in turn pass them on to the linker.  The
  41           exact format of the options is dependent on which linker you
  42           use:
  43         </para>
  44         <itemizedlist>
  45           <listitem>
  46             <para>
  47               GNU ld (default on Linux):<literal>-Wl,--rpath,<filename class="directory">destdir</filename>/lib</literal>
  48             </para>
  49           </listitem>
  50           <listitem>
  51             <para>
  52               IRIX ld:<literal>
  53               -Wl,-rpath,<filename class="directory">destdir</filename>/lib</literal>
  54             </para>
  55           </listitem>
  56           <listitem>
  57           <para>
  58           Solaris ld:<literal>-Wl,-R<filename class="directory">destdir</filename>/lib</literal>
  59           </para>
  60           </listitem>
  61           <listitem>
  62             <para>
  63               More...?  Let us know!
  64             </para>
  65           </listitem>
  66         </itemizedlist>
  67       </listitem>
  68     </itemizedlist>
  69     <para>
  70       Use the <command>ldd</command> utility to show which library the
  71       system thinks it will get at runtime.
  72     </para>
  73     <para>
  74       A libstdc++.la file is also installed, for use with Libtool.  If
  75       you use Libtool to create your executables, these details are
  76       taken care of for you.
  77     </para>
  78   </sect1>
  79
  80   <sect1 id="manual.intro.using.headers" xreflabel="Headers">
  81     <title>Headers</title>
  82
  83     <sect2 id="manual.intro.using.headers.all" xreflabel="Header Files">
  84       <title>Header Files</title>
  85
  86    <para>
  87      The C++ standard specifies the entire set of header files that
  88      must be available to all hosted implementations.  Actually, the
  89      word &quot;files&quot; is a misnomer, since the contents of the
  90      headers don't necessarily have to be in any kind of external
  91      file.  The only rule is that when one <code>#include</code>'s a
  92      header, the contents of that header become available, no matter
  93      how.
  94    </para>
  95
  96    <para>
  97    That said, in practice files are used.
  98    </para>
  99
 100    <para>
 101      There are two main types of include files: header files related
 102      to a specific version of the ISO C++ standard (called Standard
 103      Headers), and all others (TR1, C++ ABI, and Extensions).
 104    </para>
 105
 106    <para>
 107      Two dialects of standard headers are supported, corresponding to
 108      the 1998 standard as updated for 2003, and the draft of the
 109      upcoming 200x standard.
 110    </para>
 111
 112    <para>
 113      C++98/03 include files. These are available in the default compilation mode, ie <code>-std=c++98</code> or <code>-std=gnu++98</code>.
 114    </para>
 115
 116 <table frame='all'>
 117 <title>C++ 1998 Library Headers</title>
 118 <tgroup cols='5' align='left' colsep='1' rowsep='1'>
 119 <colspec colname='c1'></colspec>
 120 <colspec colname='c2'></colspec>
 121 <colspec colname='c3'></colspec>
 122 <colspec colname='c4'></colspec>
 123 <tbody>
 124 <row><entry><filename class="headerfile">algorithm</filename></entry><entry><filename class="headerfile">iomanip</filename></entry><entry><filename class="headerfile">list</filename></entry><entry><filename class="headerfile">ostream</filename></entry><entry><filename class="headerfile">streambuf</filename></entry></row>
 125 <row><entry><filename class="headerfile">bitset</filename></entry><entry><filename class="headerfile">ios</filename></entry><entry><filename class="headerfile">locale</filename></entry><entry><filename class="headerfile">queue</filename></entry><entry><filename class="headerfile">string</filename></entry></row>
 126 <row><entry><filename class="headerfile">complex</filename></entry><entry><filename class="headerfile">iosfwd</filename></entry><entry><filename class="headerfile">map</filename></entry><entry><filename class="headerfile">set</filename></entry><entry><filename class="headerfile">typeinfo</filename></entry></row>
 127 <row><entry><filename class="headerfile">deque</filename></entry><entry><filename class="headerfile">iostream</filename></entry><entry><filename class="headerfile">memory</filename></entry><entry><filename class="headerfile">sstream</filename></entry><entry><filename class="headerfile">utility</filename></entry></row>
 128 <row><entry><filename class="headerfile">exception</filename></entry><entry><filename class="headerfile">istream</filename></entry><entry><filename class="headerfile">new</filename></entry><entry><filename class="headerfile">stack</filename></entry><entry><filename class="headerfile">valarray</filename></entry></row>
 129 <row><entry><filename class="headerfile">fstream</filename></entry><entry><filename class="headerfile">iterator</filename></entry><entry><filename class="headerfile">numeric</filename></entry><entry><filename class="headerfile">stdexcept</filename></entry><entry><filename class="headerfile">vector</filename></entry></row>
 130 <row><entry><filename class="headerfile">functional</filename></entry><entry><filename class="headerfile">limits</filename></entry></row>
 131 </tbody>
 132 </tgroup>
 133 </table>
 134
 135 <para></para>
 136 <table frame='all'>
 137 <title>C++ 1998 Library Headers for C Library Facilities</title>
 138 <tgroup cols='5' align='left' colsep='1' rowsep='1'>
 139 <colspec colname='c1'></colspec>
 140 <colspec colname='c2'></colspec>
 141 <colspec colname='c3'></colspec>
 142 <colspec colname='c4'></colspec>
 143 <tbody>
 144 <row><entry><filename class="headerfile">cassert</filename></entry><entry><filename class="headerfile">ciso646</filename></entry><entry><filename class="headerfile">csetjmp</filename></entry><entry><filename class="headerfile">cstdio</filename></entry><entry><filename class="headerfile">ctime</filename></entry></row>
 145 <row><entry><filename class="headerfile">cctype</filename></entry><entry><filename class="headerfile">climits</filename></entry><entry><filename class="headerfile">csignal</filename></entry><entry><filename class="headerfile">cstdlib</filename></entry><entry><filename class="headerfile">cwchar</filename></entry></row>
 146 <row><entry><filename class="headerfile">cerrno</filename></entry><entry><filename class="headerfile">clocale</filename></entry><entry><filename class="headerfile">cstdarg</filename></entry><entry><filename class="headerfile">cstring</filename></entry><entry><filename class="headerfile">cwctype</filename></entry></row>
 147 <row><entry><filename class="headerfile">cfloat</filename></entry><entry><filename class="headerfile">cmath</filename></entry><entry><filename class="headerfile">cstddef</filename></entry></row>
 148 </tbody>
 149 </tgroup>
 150 </table>
 151
 152 <para>C++0x include files. These are only available in C++0x compilation mode, ie <code>-std=c++0x</code> or <code>-std=gnu++0x</code>.
 153 </para>
 154
 155 <para></para>
 156 <table frame='all'>
 157 <title>C++ 200x Library Headers</title>
 158 <tgroup cols='5' align='left' colsep='1' rowsep='1'>
 159 <colspec colname='c1'></colspec>
 160 <colspec colname='c2'></colspec>
 161 <colspec colname='c3'></colspec>
 162 <colspec colname='c4'></colspec>
 163 <tbody>
 164 <row><entry><filename class="headerfile">algorithm</filename></entry><entry><filename class="headerfile">iomanip</filename></entry><entry><filename class="headerfile">locale</filename></entry><entry><filename class="headerfile">regex</filename></entry><entry><filename class="headerfile">tuple</filename></entry></row>
 165 <row><entry><filename class="headerfile">array</filename></entry><entry><filename class="headerfile">ios</filename></entry><entry><filename class="headerfile">map</filename></entry><entry><filename class="headerfile">set</filename></entry><entry><filename class="headerfile">typeinfo</filename></entry></row>
 166 <row><entry><filename class="headerfile">bitset</filename></entry><entry><filename class="headerfile">iosfwd</filename></entry><entry><filename class="headerfile">memory</filename></entry><entry><filename class="headerfile">sstream</filename></entry><entry><filename class="headerfile">type_traits</filename></entry></row>
 167 <row><entry><filename class="headerfile">complex</filename></entry><entry><filename class="headerfile">iostream</filename></entry><entry><filename class="headerfile">new</filename></entry><entry><filename class="headerfile">stack</filename></entry><entry><filename class="headerfile">unordered_map</filename></entry></row>
 168 <row><entry><filename class="headerfile">deque</filename></entry><entry><filename class="headerfile">istream</filename></entry><entry><filename class="headerfile">numeric</filename></entry><entry><filename class="headerfile">stdexcept</filename></entry><entry><filename class="headerfile">unordered_set</filename></entry></row>
 169 <row><entry><filename class="headerfile">exception</filename></entry><entry><filename class="headerfile">iterator</filename></entry><entry><filename class="headerfile">ostream</filename></entry><entry><filename class="headerfile">streambuf</filename></entry><entry><filename class="headerfile">utility</filename></entry></row>
 170 <row><entry><filename class="headerfile">fstream</filename></entry><entry><filename class="headerfile">limits</filename></entry><entry><filename class="headerfile">queue</filename></entry><entry><filename class="headerfile">string</filename></entry><entry><filename class="headerfile">valarray</filename></entry></row>
 171 <row><entry><filename class="headerfile">functional</filename></entry><entry><filename class="headerfile">list</filename></entry><entry><filename class="headerfile">random</filename></entry><entry><filename class="headerfile">system_error</filename></entry><entry><filename class="headerfile">vector</filename></entry></row>
 172 </tbody>
 173 </tgroup>
 174 </table>
 175
 176 <para></para>
 177
 178 <table frame='all'>
 179 <title>C++ 200x Library Headers for C Library Facilities</title>
 180 <tgroup cols='5' align='left' colsep='1' rowsep='1'>
 181 <colspec colname='c1'></colspec>
 182 <colspec colname='c2'></colspec>
 183 <colspec colname='c3'></colspec>
 184 <colspec colname='c4'></colspec>
 185 <colspec colname='c5'></colspec>
 186 <tbody>
 187 <row><entry><filename class="headerfile">cassert</filename></entry><entry><filename class="headerfile">cfloat</filename></entry><entry><filename class="headerfile">cmath</filename></entry><entry><filename class="headerfile">cstddef</filename></entry><entry><filename class="headerfile">ctgmath</filename></entry></row>
 188 <row><entry><filename class="headerfile">ccomplex</filename></entry><entry><filename class="headerfile">cinttypes</filename></entry><entry><filename class="headerfile">csetjmp</filename></entry><entry><filename class="headerfile">cstdint</filename></entry><entry><filename class="headerfile">ctime</filename></entry></row>
 189 <row><entry><filename class="headerfile">cctype</filename></entry><entry><filename class="headerfile">ciso646</filename></entry><entry><filename class="headerfile">csignal</filename></entry><entry><filename class="headerfile">cstdio</filename></entry><entry><filename class="headerfile">cuchar</filename></entry></row>
 190 <row><entry><filename class="headerfile">cerrno</filename></entry><entry><filename class="headerfile">climits</filename></entry><entry><filename class="headerfile">cstdarg</filename></entry><entry><filename class="headerfile">cstdlib</filename></entry><entry><filename class="headerfile">cwchar</filename></entry></row>
 191 <row><entry><filename class="headerfile">cfenv</filename></entry><entry><filename class="headerfile">clocale</filename></entry><entry><filename class="headerfile">cstdbool</filename></entry><entry><filename class="headerfile">cstring</filename></entry><entry><filename class="headerfile">cwctype</filename></entry></row>
 192 </tbody>
 193 </tgroup>
 194 </table>
 195
 196
 197 <para>
 198   In addition, TR1 includes as:
 199 </para>
 200
 201 <table frame='all'>
 202 <title>C++ TR1 Library Headers</title>
 203 <tgroup cols='5' align='left' colsep='1' rowsep='1'>
 204 <colspec colname='c1'></colspec>
 205 <colspec colname='c2'></colspec>
 206 <colspec colname='c3'></colspec>
 207 <colspec colname='c4'></colspec>
 208 <colspec colname='c5'></colspec>
 209 <tbody>
 210
 211 <row><entry><filename class="headerfile">tr1/array</filename></entry><entry><filename class="headerfile">tr1/memory</filename></entry><entry><filename class="headerfile">tr1/regex</filename></entry><entry><filename class="headerfile">tr1/type_traits</filename></entry><entry><filename class="headerfile">tr1/unordered_set</filename></entry></row>
 212 <row><entry><filename class="headerfile">tr1/complex</filename></entry><entry><filename class="headerfile">tr1/random</filename></entry><entry><filename class="headerfile">tr1/tuple</filename></entry><entry><filename class="headerfile">tr1/unordered_map</filename></entry><entry><filename class="headerfile">tr1/utility</filename></entry></row>
 213 <row><entry><filename class="headerfile">tr1/functional</filename></entry></row>
 214 </tbody>
 215 </tgroup>
 216 </table>
 217
 218 <para></para>
 219
 220
 221 <table frame='all'>
 222 <title>C++ TR1 Library Headers for C Library Facilities</title>
 223 <tgroup cols='5' align='left' colsep='1' rowsep='1'>
 224 <colspec colname='c1'></colspec>
 225 <colspec colname='c2'></colspec>
 226 <colspec colname='c3'></colspec>
 227 <colspec colname='c4'></colspec>
 228 <colspec colname='c5'></colspec>
 229 <tbody>
 230
 231 <row><entry><filename class="headerfile">tr1/cmath</filename></entry><entry><filename class="headerfile">tr1/cfloat</filename></entry><entry><filename class="headerfile">tr1/cstdarg</filename></entry><entry><filename class="headerfile">tr1/cstdio</filename></entry><entry><filename class="headerfile">tr1/ctime</filename></entry></row>
 232 <row><entry><filename class="headerfile">tr1/ccomplex</filename></entry><entry><filename class="headerfile">tr1/cinttypes</filename></entry><entry><filename class="headerfile">tr1/cstdbool</filename></entry><entry><filename class="headerfile">tr1/cstdlib</filename></entry><entry><filename class="headerfile">tr1/cwchar</filename></entry></row>
 233 <row><entry><filename class="headerfile">tr1/cfenv</filename></entry><entry><filename class="headerfile">tr1/climits</filename></entry><entry><filename class="headerfile">tr1/cstdint</filename></entry><entry><filename class="headerfile">tr1/ctgmath</filename></entry><entry><filename class="headerfile">tr1/cwctype</filename></entry></row>
 234 </tbody>
 235 </tgroup>
 236 </table>
 237
 238 <para>
 239   Also included are files for the C++ ABI interface:
 240 </para>
 241
 242 <table frame='all'>
 243 <title>C++ ABI Headers</title>
 244 <tgroup cols='2' align='left' colsep='1' rowsep='1'>
 245 <colspec colname='c1'></colspec>
 246 <colspec colname='c2'></colspec>
 247 <tbody>
 248 <row><entry><filename class="headerfile">cxxabi.h</filename></entry><entry><filename class="headerfile">cxxabi_forced.h</filename></entry></row>
 249 </tbody>
 250 </tgroup>
 251 </table>
 252
 253 <para>
 254   And a large variety of extensions.
 255 </para>
 256
 257 <table frame='all'>
 258 <title>Extension Headers</title>
 259 <tgroup cols='5' align='left' colsep='1' rowsep='1'>
 260 <colspec colname='c1'></colspec>
 261 <colspec colname='c2'></colspec>
 262 <colspec colname='c3'></colspec>
 263 <colspec colname='c4'></colspec>
 264 <colspec colname='c5'></colspec>
 265 <tbody>
 266
 267 <row><entry><filename class="headerfile">ext/algorithm</filename></entry><entry><filename class="headerfile">ext/debug_allocator.h</filename></entry><entry><filename class="headerfile">ext/mt_allocator.h</filename></entry><entry><filename class="headerfile">ext/pod_char_traits.h</filename></entry><entry><filename class="headerfile">ext/stdio_sync_filebuf.h</filename></entry></row>
 268 <row><entry><filename class="headerfile">ext/array_allocator.h</filename></entry><entry><filename class="headerfile">ext/enc_filebuf.h</filename></entry><entry><filename class="headerfile">ext/new_allocator.h</filename></entry><entry><filename class="headerfile">ext/pool_allocator.h</filename></entry><entry><filename class="headerfile">ext/throw_allocator.h</filename></entry></row>
 269 <row><entry><filename class="headerfile">ext/atomicity.h</filename></entry><entry><filename class="headerfile">ext/functional</filename></entry><entry><filename class="headerfile">ext/numeric</filename></entry><entry><filename class="headerfile">ext/rb_tree</filename></entry><entry><filename class="headerfile">ext/typelist.h</filename></entry></row>
 270 <row><entry><filename class="headerfile">ext/bitmap_allocator.h</filename></entry><entry><filename class="headerfile">ext/iterator</filename></entry><entry><filename class="headerfile">ext/numeric_traits.h</filename></entry><entry><filename class="headerfile">ext/rope</filename></entry><entry><filename class="headerfile">ext/type_traits.h</filename></entry></row>
 271 <row><entry><filename class="headerfile">ext/codecvt_specializations.h</filename></entry><entry><filename class="headerfile">ext/malloc_allocator.h</filename></entry><entry><filename class="headerfile">ext/pb_ds/assoc_container.h</filename></entry><entry><filename class="headerfile">ext/slist</filename></entry><entry><filename class="headerfile">ext/vstring.h</filename></entry></row>
 272 <row><entry><filename class="headerfile">ext/concurrence.h</filename></entry><entry><filename class="headerfile">ext/memory</filename></entry><entry><filename class="headerfile">ext/pb_ds/priority_queue.h</filename></entry><entry><filename class="headerfile">ext/stdio_filebuf.h</filename></entry></row>
 273 </tbody>
 274 </tgroup>
 275 </table>
 276
 277 <para></para>
 278
 279 <table frame='all'>
 280 <title>Extension Debug Headers</title>
 281 <tgroup cols='5' align='left' colsep='1' rowsep='1'>
 282 <colspec colname='c1'></colspec>
 283 <colspec colname='c2'></colspec>
 284 <colspec colname='c3'></colspec>
 285 <colspec colname='c4'></colspec>
 286 <colspec colname='c5'></colspec>
 287 <tbody>
 288
 289 <row><entry><filename class="headerfile">debug/bitset</filename></entry><entry><filename class="headerfile">debug/list</filename></entry><entry><filename class="headerfile">debug/set</filename></entry><entry><filename class="headerfile">debug/unordered_map</filename></entry><entry><filename class="headerfile">debug/vector</filename></entry></row>
 290 <row><entry><filename class="headerfile">debug/deque</filename></entry><entry><filename class="headerfile">debug/map</filename></entry><entry><filename class="headerfile">debug/string</filename></entry><entry><filename class="headerfile">debug/unordered_set</filename></entry></row>
 291 </tbody>
 292 </tgroup>
 293 </table>
 294
 295 <para></para>
 296
 297 <table frame='all'>
 298 <title>Extension Parallel Headers</title>
 299 <tgroup cols='2' align='left' colsep='1' rowsep='1'>
 300 <colspec colname='c1'></colspec>
 301 <colspec colname='c2'></colspec>
 302 <tbody>
 303 <row><entry><filename class="headerfile">parallel/algorithm</filename></entry><entry><filename class="headerfile">parallel/numeric</filename></entry></row>
 304 </tbody>
 305 </tgroup>
 306 </table>
 307
 308     </sect2>
 309
 310     <sect2 id="manual.intro.using.headers.mixing" xreflabel="Mixing Headers">
 311       <title>Mixing Headers</title>
 312
 313 <para> A few simple rules.
 314 </para>
 315
 316 <para>First, mixing different dialects of the standard headers is not
 317 possible. It's an all-or-nothing affair. Thus, code like
 318 </para>
 319
 320 <programlisting>
 321 #include &lt;array&gt;
 322 #include &lt;functional&gt;
 323 </programlisting>
 324
 325 <para>Implies C++0x mode. To use the entities in &lt;array&gt;, the C++0x
 326 compilation mode must be used, which implies the C++0x functionality
 327 (and deprecations) in &lt;functional&gt; will be present.
 328 </para>
 329
 330 <para>Second, the other headers can be included with either dialect of
 331 the standard headers, although features and types specific to C++0x
 332 are still only enabled when in C++0x compilation mode. So, to use
 333 rvalue references with <code>__gnu_cxx::vstring</code>, or to use the
 334 debug-mode versions of <code>std::unordered_map</code>, one must use
 335 the <code>std=gnu++0x</code> compiler flag. (Or <code>std=c++0x</code>, of course.)
 336 </para>
 337
 338 <para>A special case of the second rule is the mixing of TR1 and C++0x
 339 facilities. It is possible (although not especially prudent) to
 340 include both the TR1 version and the C++0x version of header in the
 341 same translation unit:
 342 </para>
 343
 344 <programlisting>
 345 #include &lt;tr1/type_traits&gt;
 346 #include &lt;type_traits&gt;
 347 </programlisting>
 348
 349 <para> Several parts of C++0x diverge quite substantially from TR1 predecessors.
 350 </para>
 351     </sect2>
 352
 353     <sect2 id="manual.intro.using.headers.cheaders" xreflabel="C Headers and">
 354       <title>The C Headers and <code>namespace std</code></title>
 355
 356 <para>
 357         The standard specifies that if one includes the C-style header
 358         (&lt;math.h&gt; in this case), the symbols will be available
 359         in the global namespace and perhaps in
 360         namespace <code>std::</code> (but this is no longer a firm
 361         requirement.) One the other hand, including the C++-style
 362         header (&lt;cmath&gt;) guarantees that the entities will be
 363         found in namespace std and perhaps in the global namespace.
 364       </para>
 365
 366 <para>
 367 Usage of C++-style headers is recommended, as then
 368 C-linkage names can be disambiguated by explicit qualification, such
 369 as by <code>std::abort</code>. In addition, the C++-style headers can
 370 use function overloading to provide a simpler interface to certain
 371 families of C-functions. For instance in &lt;cmath&gt;, the
 372 function <code>std::sin</code> has overloads for all the builtin
 373 floating-point types. This means that <code>std::sin</code> can be
 374 used uniformly, instead of a combination
 375 of <code>std::sinf</code>, <code>std::sin</code>,
 376 and <code>std::sinl</code>.
 377 </para>
 378     </sect2>
 379
 380     <sect2 id="manual.intro.using.headers.pre" xreflabel="Precompiled Headers">
 381       <title>Precompiled Headers</title>
 382
 383
 384 <para>There are three base header files that are provided. They can be
 385 used to precompile the standard headers and extensions into binary
 386 files that may the be used to speed compiles that use these headers.
 387 </para>
 388
 389
 390 <itemizedlist>
 391 <listitem>
 392   <para>stdc++.h</para>
 393 <para>Includes all standard headers. Actual content varies depending on
 394 language dialect.
 395 </para>
 396 </listitem>
 397
 398 <listitem>
 399   <para>stdtr1c++.h</para>
 400 <para>Includes all of &lt;stdc++.h&gt;, and adds all the TR1 headers.
 401 </para>
 402 </listitem>
 403
 404 <listitem><para>extc++.h</para>
 405 <para>Includes all of &lt;stdtr1c++.h&gt;, and adds all the Extension headers.
 406 </para></listitem>
 407 </itemizedlist>
 408
 409 <para>How to construct a .gch file from one of these base header files.</para>
 410
 411 <para>First, find the include directory for the compiler. One way to do
 412 this is:</para>
 413
 414 <programlisting>
 415 g++ -v hello.cc
 416
 417 #include &lt;...&gt; search starts here:
 418  /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0
 419 ...
 420 End of search list.
 421 </programlisting>
 422
 423
 424 <para>Then, create a precompiled header file with the same flags that
 425 will be used to compile other projects.</para>
 426
 427 <programlisting>
 428 g++ -Winvalid-pch -x c++-header -g -O2 -o ./stdc++.h.gch /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0/x86_64-unknown-linux-gnu/bits/stdc++.h
 429 </programlisting>
 430
 431 <para>The resulting file will be quite large: the current size is around
 432 thirty megabytes. </para>
 433
 434 <para>How to use the resulting file.</para>
 435
 436 <programlisting>
 437 g++ -I. -include stdc++.h  -H -g -O2 hello.cc
 438 </programlisting>
 439
 440 <para>Verification that the PCH file is being used is easy:</para>
 441
 442 <programlisting>
 443 g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe
 444 ! ./stdc++.h.gch
 445 . /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0/iostream
 446 . /mnt/share/bld/H-x86-gcc.20071201include/c++/4.3.0/string
 447 </programlisting>
 448
 449 <para>The exclamation point to the left of the <code>stdc++.h.gch</code> listing means that the generated PCH file was used, and thus the </para>
 450 <para></para>
 451
 452 <para> Detailed information about creating precompiled header files can be found in the GCC <ulink url="http://gcc.gnu.org/onlinedocs/gcc/Precompiled-Headers.html">documentation</ulink>.
 453 </para>
 454
 455
 456     </sect2>
 457   </sect1>
 458
 459   <sect1 id="manual.intro.using.namespaces" xreflabel="Namespaces">
 460     <title>Namespaces</title>
 461
 462     <sect2 id="manual.intro.using.namespaces.all" xreflabel="Available Namespaces">
 463       <title>Available Namespaces</title>
 464
 465
 466
 467 <para> There are three main namespaces.
 468 </para>
 469
 470 <itemizedlist>
 471   <listitem><para>std</para>
 472 <para>The ISO C++ standards specify that "all library entities are defined
 473 within namespace std." This includes namepaces nested
 474 within <code>namespace std</code>, such as <code>namespace
 475 std::tr1</code>.
 476 </para>
 477 </listitem>
 478 <listitem><para>abi</para>
 479 <para>Specified by the C++ ABI. This ABI specifies a number of type and
 480 function APIs supplemental to those required by the ISO C++ Standard,
 481 but necessary for interoperability.
 482 </para>
 483 </listitem>
 484
 485 <listitem><para>__gnu_</para>
 486 <para>Indicating one of several GNU extensions. Choices
 487 include <code>__gnu_cxx</code>, <code>__gnu_debug</code>, <code>__gnu_parallel</code>,
 488 and <code>__gnu_pbds</code>.
 489 </para></listitem>
 490 </itemizedlist>
 491
 492 <para> A complete list of implementation namespaces (including namespace contents) is available in the generated source <ulink url="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/namespaces.html">documentation</ulink>.
 493 </para>
 494
 495
 496     </sect2>
 497
 498     <sect2 id="manual.intro.using.namespaces.std" xreflabel="namespace std">
 499       <title>namespace std</title>
 500
 501
 502 <para>
 503       One standard requirement is that the library components are defined
 504       in <code>namespace std::</code>. Thus, in order to use these types or
 505       functions, one must do one of two things:
 506 </para>
 507
 508 <itemizedlist>
 509   <listitem><para>put a kind of <emphasis>using-declaration</emphasis> in your source
 510 (either <code>using namespace std;</code> or i.e. <code>using
 511 std::string;</code>) This approach works well for individual source files, but
 512 should not be used in a global context, like header files.
 513           </para></listitem> <listitem><para>use a <emphasis>fully
 514 qualified name</emphasis>for each library symbol
 515 (i.e. <code>std::string</code>, <code>std::cout</code>) Always can be
 516 used, and usually enhanced, by strategic use of typedefs. (In the
 517 cases where the qualified verbiage becomes unwieldy.)
 518           </para>
 519         </listitem>
 520 </itemizedlist>
 521
 522     </sect2>
 523
 524     <sect2 id="manual.intro.using.namespaces.comp" xreflabel="Using Namepace Composition">
 525       <title>Using Namespace Composition</title>
 526
 527 <para>
 528 Best practice in programming suggests sequestering new data or
 529 functionality in a sanely-named, unique namespace whenever
 530 possible. This is considered an advantage over dumping everything in
 531 the global namespace, as then name look-up can be explicitly enabled or
 532 disabled as above, symbols are consistently mangled without repetitive
 533 naming prefixes or macros, etc.
 534 </para>
 535
 536 <para>For instance, consider a project that defines most of its classes in <code>namespace gtk</code>. It is possible to
 537         adapt <code>namespace gtk</code> to <code>namespace std</code> by using a C++-feature called
 538         <emphasis>namespace composition</emphasis>. This is what happens if
 539         a <emphasis>using</emphasis>-declaration is put into a
 540         namespace-definition: the imported symbol(s) gets imported into the
 541         currently active namespace(s). For example:
 542 </para>
 543 <programlisting>
 544 namespace gtk
 545 {
 546   using std::string;
 547   using std::tr1::array;
 548
 549   class Window { ... };
 550 }
 551 </programlisting>
 552 <para>
 553         In this example, <code>std::string</code> gets imported into
 554         <code>namespace gtk</code>.  The result is that use of
 555         <code>std::string</code> inside namespace gtk can just use <code>string</code>, without the explicit qualification.
 556         As an added bonus,
 557         <code>std::string</code> does not get imported into
 558         the global namespace.  Additionally, a more elaborate arrangement can be made for backwards compatibility and portability, whereby the
 559         <code>using</code>-declarations can wrapped in macros that
 560         are set based on autoconf-tests to either &quot;&quot; or i.e. <code>using
 561           std::string;</code> (depending on whether the system has
 562         libstdc++ in <code>std::</code> or not).  (ideas from
 563         <email>llewelly@dbritsch.dsl.xmission.com</email>, Karl Nelson <email>kenelson@ece.ucdavis.edu</email>)
 564 </para>
 565
 566
 567     </sect2>
 568   </sect1>
 569
 570   <sect1 id="manual.intro.using.macros" xreflabel="Macros">
 571     <title>Macros</title>
 572
 573    <para>All pre-processor switches and configurations are all gathered
 574       in the file <code>c++config.h</code>, which is generated during
 575       the libstdc++ configuration and build process, and included by
 576       files part of the public libstdc++ API. Most of these macros
 577       should not be used by consumers of libstdc++, and are reserved
 578       for internal implementation use. <emphasis>These macros cannot be
 579       redefined</emphasis>. However, a select handful of these macro
 580       control libstdc++ extensions and extra features, or provide
 581       versioning information for the API, and are able to be used.
 582    </para>
 583
 584    <para>All library macros begin with <code>_GLIBCXX_</code> (except for
 585    versions 3.1.x to 3.3.x, which use <code>_GLIBCPP_</code>).
 586    </para>
 587
 588    <para>Below is the macro which users may check for library version
 589       information. </para>
 590
 591     <variablelist>
 592     <varlistentry>
 593       <term><code>__GLIBCXX__</code></term>
 594       <listitem>
 595         <para>The current version of
 596     libstdc++ in compressed ISO date format, form of an unsigned
 597     long. For details on the value of this particular macro for a
 598     particular release, please consult this <ulink url="abi.html">
 599     document</ulink>.
 600     </para>
 601     </listitem>
 602     </varlistentry>
 603     </variablelist>
 604
 605    <para>Below are the macros which users may change with #define/#undef or
 606       with -D/-U compiler flags.  The default state of the symbol is
 607       listed.</para>
 608
 609    <para><quote>Configurable</quote> (or <quote>Not configurable</quote>) means
 610       that the symbol is initially chosen (or not) based on
 611       --enable/--disable options at library build and configure time
 612       (documented <link linkend="manual.intro.setup.configure">here</link>), with the
 613       various --enable/--disable choices being translated to
 614       #define/#undef).
 615    </para>
 616
 617    <para> <acronym>ABI</acronym> means that changing from the default value may
 618   mean changing the <acronym>ABI</acronym> of compiled code. In other words, these
 619   choices control code which has already been compiled (i.e., in a
 620   binary such as libstdc++.a/.so).  If you explicitly #define or
 621   #undef these macros, the <emphasis>headers</emphasis> may see different code
 622   paths, but the <emphasis>libraries</emphasis> which you link against will not.
 623   Experimenting with different values with the expectation of
 624   consistent linkage requires changing the config headers before
 625   building/installing the library.
 626    </para>
 627
 628     <variablelist>
 629     <varlistentry><term><code>_GLIBCXX_DEPRECATED</code></term>
 630     <listitem>
 631       <para>
 632         Defined by default. Not configurable. ABI-changing. Turning this off
 633         removes older ARM-style iostreams code, and other anachronisms
 634         from the API.  This macro is dependent on the version of the
 635         standard being tracked, and as a result may give different results for
 636         <code>-std=c++98</code> and <code>-std=c++0x</code>. This may
 637         be useful in updating old C++ code which no longer meet the
 638         requirements of the language, or for checking current code
 639         against new language standards.
 640     </para>
 641     </listitem></varlistentry>
 642
 643     <varlistentry><term><code>_GLIBCXX_FORCE_NEW</code></term>
 644     <listitem>
 645       <para>
 646         Undefined by default. When defined, memory allocation and
 647         allocators controlled by libstdc++ call operator new/delete
 648         without caching and pooling. Configurable via
 649         <code>--enable-libstdcxx-allocator</code>. ABI-changing.
 650       </para>
 651     </listitem></varlistentry>
 652
 653
 654     <varlistentry><term><code>_GLIBCXX_CONCEPT_CHECKS</code></term>
 655     <listitem>
 656       <para>
 657         Undefined by default.  Configurable via
 658         <code>--enable-concept-checks</code>.  When defined, performs
 659         compile-time checking on certain template instantiations to
 660         detect violations of the requirements of the standard.  This
 661         is described in more detail <ulink
 662         url="../19_diagnostics/howto.html#3">here</ulink>.
 663       </para>
 664     </listitem></varlistentry>
 665
 666     <varlistentry><term><code>_GLIBCXX_DEBUG</code></term>
 667     <listitem>
 668       <para>
 669         Undefined by default. When defined, compiles
 670     user code using the <ulink url="../ext/debug.html#safe">libstdc++ debug
 671     mode</ulink>.
 672       </para>
 673     </listitem></varlistentry>
 674     <varlistentry><term><code>_GLIBCXX_DEBUG_PEDANTIC</code></term>
 675     <listitem>
 676       <para>
 677         Undefined by default. When defined while
 678     compiling with the <ulink url="../ext/debug.html#safe">libstdc++ debug
 679     mode</ulink>, makes the debug mode extremely picky by making the use
 680     of libstdc++ extensions and libstdc++-specific behavior into
 681     errors.
 682       </para>
 683     </listitem></varlistentry>
 684     <varlistentry><term><code>_GLIBCXX_PARALLEL</code></term>
 685     <listitem>
 686       <para>Undefined by default. When defined, compiles
 687     user code using the <ulink url="../ext/parallel_mode.html">libstdc++ parallel
 688     mode</ulink>.
 689       </para>
 690     </listitem></varlistentry>
 691     </variablelist>
 692
 693
 694   </sect1>
 695
 696   <sect1 id="manual.intro.using.concurrency" xreflabel="Concurrency">
 697     <title>Concurrency</title>
 698
 699    <para>This section discusses issues surrounding the proper compilation
 700       of multithreaded applications which use the Standard C++
 701       library.  This information is GCC-specific since the C++
 702       standard does not address matters of multithreaded applications.
 703    </para>
 704
 705     <sect2 id="manual.intro.using.concurrency.prereq" xreflabel="Thread Prereq">
 706       <title>Prerequisites</title>
 707
 708    <para>All normal disclaimers aside, multithreaded C++ application are
 709       only supported when libstdc++ and all user code was built with
 710       compilers which report (via <code> gcc/g++ -v </code>) the same thread
 711       model and that model is not <emphasis>single</emphasis>.  As long as your
 712       final application is actually single-threaded, then it should be
 713       safe to mix user code built with a thread model of
 714       <emphasis>single</emphasis> with a libstdc++ and other C++ libraries built
 715       with another thread model useful on the platform.  Other mixes
 716       may or may not work but are not considered supported.  (Thus, if
 717       you distribute a shared C++ library in binary form only, it may
 718       be best to compile it with a GCC configured with
 719       --enable-threads for maximal interchangeability and usefulness
 720       with a user population that may have built GCC with either
 721       --enable-threads or --disable-threads.)
 722    </para>
 723    <para>When you link a multithreaded application, you will probably
 724       need to add a library or flag to g++.  This is a very
 725       non-standardized area of GCC across ports.  Some ports support a
 726       special flag (the spelling isn't even standardized yet) to add
 727       all required macros to a compilation (if any such flags are
 728       required then you must provide the flag for all compilations not
 729       just linking) and link-library additions and/or replacements at
 730       link time.  The documentation is weak.  Here is a quick summary
 731       to display how ad hoc this is: On Solaris, both -pthreads and
 732       -threads (with subtly different meanings) are honored.  On OSF,
 733       -pthread and -threads (with subtly different meanings) are
 734       honored.  On Linux/i386, -pthread is honored.  On FreeBSD,
 735       -pthread is honored.  Some other ports use other switches.
 736       AFAIK, none of this is properly documented anywhere other than
 737       in ``gcc -dumpspecs'' (look at lib and cpp entries).
 738    </para>
 739
 740     </sect2>
 741
 742     <sect2 id="manual.intro.using.concurrency.thread_safety" xreflabel="Thread Safety">
 743       <title>Thread Safety</title>
 744
 745
 746 <para>
 747 We currently use the <ulink url="http://www.sgi.com/tech/stl/thread_safety.html">SGI STL</ulink> definition of thread safety.
 748 </para>
 749
 750
 751       <para>The library strives to be thread-safe when all of the following
 752          conditions are met:
 753       </para>
 754       <itemizedlist>
 755        <listitem>
 756        <para>The system's libc is itself thread-safe,
 757        </para>
 758        </listitem>
 759        <listitem>
 760          <para>
 761            The compiler in use reports a thread model other than
 762            'single'. This can be tested via output from <code>gcc
 763            -v</code>. Multi-thread capable versions of gcc output
 764            something like this:
 765          </para>
 766 <programlisting>
 767 %gcc -v
 768 Using built-in specs.
 769 ...
 770 Thread model: posix
 771 gcc version 4.1.2 20070925 (Red Hat 4.1.2-33)
 772 </programlisting>
 773
 774 <para>Look for "Thread model" lines that aren't equal to "single."</para>
 775        </listitem>
 776        <listitem>
 777        <para>
 778          Requisite command-line flags are used for atomic operations
 779          and threading. Examples of this include <code>-pthread</code>
 780          and <code>-march=native</code>, although specifics vary
 781          depending on the host environment. See <ulink
 782          url="http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html">Machine
 783          Dependent Options</ulink>.
 784        </para>
 785        </listitem>
 786        <listitem>
 787          <para>
 788            An implementation of atomicity.h functions
 789            exists for the architecture in question. See the internals documentation for more <ulink url="../ext/concurrence.html">details</ulink>.
 790        </para>
 791        </listitem>
 792
 793       </itemizedlist>
 794       <para>The user-code must guard against concurrent method calls which may
 795          access any particular library object's state.  Typically, the
 796          application programmer may infer what object locks must be held
 797          based on the objects referenced in a method call.  Without getting
 798          into great detail, here is an example which requires user-level
 799          locks:
 800       </para>
 801       <programlisting>
 802      library_class_a shared_object_a;
 803
 804      thread_main () {
 805        library_class_b *object_b = new library_class_b;
 806        shared_object_a.add_b (object_b);   // must hold lock for shared_object_a
 807        shared_object_a.mutate ();          // must hold lock for shared_object_a
 808      }
 809
 810      // Multiple copies of thread_main() are started in independent threads.</programlisting>
 811       <para>Under the assumption that object_a and object_b are never exposed to
 812          another thread, here is an example that should not require any
 813          user-level locks:
 814       </para>
 815       <programlisting>
 816      thread_main () {
 817        library_class_a object_a;
 818        library_class_b *object_b = new library_class_b;
 819        object_a.add_b (object_b);
 820        object_a.mutate ();
 821      } </programlisting>
 822       <para>All library objects are safe to use in a multithreaded program as
 823          long as each thread carefully locks out access by any other
 824          thread while it uses any object visible to another thread, i.e.,
 825          treat library objects like any other shared resource.  In general,
 826          this requirement includes both read and write access to objects;
 827          unless otherwise documented as safe, do not assume that two threads
 828          may access a shared standard library object at the same time.
 829       </para>
 830       <para>See chapters <ulink url="../17_intro/howto.html#3">17</ulink> (library
 831          introduction), <ulink url="../23_containers/howto.html#3">23</ulink>
 832          (containers), and <ulink url="../27_io/howto.html#9">27</ulink> (I/O) for
 833          more information.
 834       </para>
 835
 836
 837   </sect2>
 838   <sect2 id="manual.intro.using.concurrency.atomics" xreflabel="Atomics">
 839     <title>Atomics</title>
 840     <para>
 841     </para>
 842   </sect2>
 843
 844     <sect2 id="manual.intro.using.concurrency.io" xreflabel="IO">
 845       <title>IO</title>
 846    <para>I'll assume that you have already read the
 847       <ulink url="../17_intro/howto.html#3">general notes on library threads</ulink>,
 848       and the
 849       <ulink url="../23_containers/howto.html#3">notes on threaded container
 850       access</ulink> (you might not think of an I/O stream as a container, but
 851       the points made there also hold here).  If you have not read them,
 852       please do so first.
 853    </para>
 854    <para>This gets a bit tricky.  Please read carefully, and bear with me.
 855    </para>
 856
 857     <sect3 id="concurrency.io.structure" xreflabel="Structure">
 858       <title>Structure</title>
 859    <para>A wrapper
 860       type called <code>__basic_file</code> provides our abstraction layer
 861       for the <code>std::filebuf</code> classes.  Nearly all decisions dealing
 862       with actual input and output must be made in <code>__basic_file</code>.
 863    </para>
 864    <para>A generic locking mechanism is somewhat in place at the filebuf layer,
 865       but is not used in the current code.  Providing locking at any higher
 866       level is akin to providing locking within containers, and is not done
 867       for the same reasons (see the links above).
 868    </para>
 869     </sect3>
 870
 871     <sect3 id="concurrency.io.defaults" xreflabel="Defaults">
 872       <title>Defaults</title>
 873    <para>The __basic_file type is simply a collection of small wrappers around
 874       the C stdio layer (again, see the link under Structure).  We do no
 875       locking ourselves, but simply pass through to calls to <code>fopen</code>,
 876       <code>fwrite</code>, and so forth.
 877    </para>
 878    <para>So, for 3.0, the question of &quot;is multithreading safe for I/O&quot;
 879       must be answered with, &quot;is your platform's C library threadsafe
 880       for I/O?&quot;  Some are by default, some are not; many offer multiple
 881       implementations of the C library with varying tradeoffs of threadsafety
 882       and efficiency.  You, the programmer, are always required to take care
 883       with multiple threads.
 884    </para>
 885    <para>(As an example, the POSIX standard requires that C stdio FILE*
 886        operations are atomic.  POSIX-conforming C libraries (e.g, on Solaris
 887        and GNU/Linux) have an internal mutex to serialize operations on
 888        FILE*s.  However, you still need to not do stupid things like calling
 889        <code>fclose(fs)</code> in one thread followed by an access of
 890        <code>fs</code> in another.)
 891    </para>
 892    <para>So, if your platform's C library is threadsafe, then your
 893       <code>fstream</code> I/O operations will be threadsafe at the lowest
 894       level.  For higher-level operations, such as manipulating the data
 895       contained in the stream formatting classes (e.g., setting up callbacks
 896       inside an <code>std::ofstream</code>), you need to guard such accesses
 897       like any other critical shared resource.
 898    </para>
 899     </sect3>
 900
 901     <sect3 id="concurrency.io.future" xreflabel="Future">
 902       <title>Future</title>
 903    <para> A
 904       second choice may be available for I/O implementations:  libio.  This is
 905       disabled by default, and in fact will not currently work due to other
 906       issues.  It will be revisited, however.
 907    </para>
 908    <para>The libio code is a subset of the guts of the GNU libc (glibc) I/O
 909       implementation.  When libio is in use, the <code>__basic_file</code>
 910       type is basically derived from FILE.  (The real situation is more
 911       complex than that... it's derived from an internal type used to
 912       implement FILE.  See libio/libioP.h to see scary things done with
 913       vtbls.)  The result is that there is no &quot;layer&quot; of C stdio
 914       to go through; the filebuf makes calls directly into the same
 915       functions used to implement <code>fread</code>, <code>fwrite</code>,
 916       and so forth, using internal data structures.  (And when I say
 917       &quot;makes calls directly,&quot; I mean the function is literally
 918       replaced by a jump into an internal function.  Fast but frightening.
 919       *grin*)
 920    </para>
 921    <para>Also, the libio internal locks are used.  This requires pulling in
 922       large chunks of glibc, such as a pthreads implementation, and is one
 923       of the issues preventing widespread use of libio as the libstdc++
 924       cstdio implementation.
 925    </para>
 926    <para>But we plan to make this work, at least as an option if not a future
 927       default.  Platforms running a copy of glibc with a recent-enough
 928       version will see calls from libstdc++ directly into the glibc already
 929       installed.  For other platforms, a copy of the libio subsection will
 930       be built and included in libstdc++.
 931    </para>
 932     </sect3>
 933
 934     <sect3 id="concurrency.io.alt" xreflabel="Alt">
 935       <title>Alternatives</title>
 936    <para>Don't forget that other cstdio implementations are possible.  You could
 937       easily write one to perform your own forms of locking, to solve your
 938       &quot;interesting&quot; problems.
 939    </para>
 940     </sect3>
 941
 942     </sect2>
 943
 944     <sect2 id="manual.intro.using.concurrency.containers" xreflabel="Containers">
 945       <title>Containers</title>
 946
 947    <para>This section discusses issues surrounding the design of
 948       multithreaded applications which use Standard C++ containers.
 949       All information in this section is current as of the gcc 3.0
 950       release and all later point releases.  Although earlier gcc
 951       releases had a different approach to threading configuration and
 952       proper compilation, the basic code design rules presented here
 953       were similar.  For information on all other aspects of
 954       multithreading as it relates to libstdc++, including details on
 955       the proper compilation of threaded code (and compatibility between
 956       threaded and non-threaded code), see Chapter 17.
 957    </para>
 958    <para>Two excellent pages to read when working with the Standard C++
 959       containers and threads are
 960       <ulink url="http://www.sgi.com/tech/stl/thread_safety.html">SGI's
 961       http://www.sgi.com/tech/stl/thread_safety.html</ulink> and
 962       <ulink url="http://www.sgi.com/tech/stl/Allocators.html">SGI's
 963       http://www.sgi.com/tech/stl/Allocators.html</ulink>.
 964    </para>
 965    <para><emphasis>However, please ignore all discussions about the user-level
 966       configuration of the lock implementation inside the STL
 967       container-memory allocator on those pages.  For the sake of this
 968       discussion, libstdc++ configures the SGI STL implementation,
 969       not you.  This is quite different from how gcc pre-3.0 worked.
 970       In particular, past advice was for people using g++ to
 971       explicitly define _PTHREADS or other macros or port-specific
 972       compilation options on the command line to get a thread-safe
 973       STL.  This is no longer required for any port and should no
 974       longer be done unless you really know what you are doing and
 975       assume all responsibility.</emphasis>
 976    </para>
 977    <para>Since the container implementation of libstdc++ uses the SGI
 978       code, we use the same definition of thread safety as SGI when
 979       discussing design.  A key point that beginners may miss is the
 980       fourth major paragraph of the first page mentioned above
 981       (&quot;For most clients,&quot;...), which points out that
 982       locking must nearly always be done outside the container, by
 983       client code (that'd be you, not us).  There is a notable
 984       exceptions to this rule.  Allocators called while a container or
 985       element is constructed uses an internal lock obtained and
 986       released solely within libstdc++ code (in fact, this is the
 987       reason STL requires any knowledge of the thread configuration).
 988    </para>
 989    <para>For implementing a container which does its own locking, it is
 990       trivial to provide a wrapper class which obtains the lock (as
 991       SGI suggests), performs the container operation, and then
 992       releases the lock.  This could be templatized <emphasis>to a certain
 993       extent</emphasis>, on the underlying container and/or a locking
 994       mechanism.  Trying to provide a catch-all general template
 995       solution would probably be more trouble than it's worth.
 996    </para>
 997    <para>The STL implementation is currently configured to use the
 998       high-speed caching memory allocator.  Some people like to
 999       test and/or normally run threaded programs with a different
1000       default.  For all details about how to globally override this
1001       at application run-time see <ulink url="../ext/howto.html#3">here</ulink>.
1002    </para>
1003    <para>There is a better way (not standardized yet):  It is possible to
1004       force the malloc-based allocator on a per-case-basis for some
1005       application code.  The library team generally believes that this
1006       is a better way to tune an application for high-speed using this
1007       implementation of the STL.  There is
1008       <ulink url="../ext/howto.html#3">more information on allocators here</ulink>.
1009    </para>
1010
1011     </sect2>
1012   </sect1>
1013
1014   <sect1 id="manual.intro.using.exception_safety" xreflabel="Exception Safety">
1015     <title>Exception Safety</title>
1016     <para></para>
1017   </sect1>
1018
1019 <!-- Section 0x : Debug -->
1020 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
1021             parse="xml" href="debug.xml">
1022 </xi:include>
1023
1024 </chapter>