-<?xml version='1.0'?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
-[ ]>
-
-<chapter id="manual.intro.using" xreflabel="Using">
-<?dbhtml filename="using.html"?>
-
-<title>Using</title>
-
- <sect1 id="manual.intro.using.lib" xreflabel="Lib">
- <title>Linking Library Binary Files</title>
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="manual.intro.using" xreflabel="Using">
+ <info><title>Using</title></info>
+ <?dbhtml filename="using.html"?>
+ <section xml:id="manual.intro.using.flags" xreflabel="Flags"><info><title>Command Options</title></info>
+
<para>
- If you only built a static library (libstdc++.a), or if you
- specified static linking, you don't have to worry about this.
- But if you built a shared library (libstdc++.so) and linked
- against it, then you will need to find that library when you run
- the executable.
+ The set of features available in the GNU C++ library is shaped
+ by
+ several <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/gcc-4.3.2//gcc/Invoking-GCC.html">GCC
+ Command Options</link>. Options that impact libstdc++ are
+ enumerated and detailed in the table below.
</para>
+
<para>
- Methods vary for different platforms and different styles, but
- the usual ones are printed to the screen during installation.
- They include:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- At runtime set LD_LIBRARY_PATH in your environment
- correctly, so that the shared library for libstdc++ can be
- found and loaded. Be certain that you understand all of the
- other implications and behavior of LD_LIBRARY_PATH first
- (few people do, and they get into trouble).
- </para>
- </listitem>
- <listitem>
- <para>
- Compile the path to find the library at runtime into the
- program. This can be done by passing certain options to
- g++, which will in turn pass them on to the linker. The
- exact format of the options is dependent on which linker you
- use:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- GNU ld (default on Linux):<literal>-Wl,--rpath,<filename class="directory">destdir</filename>/lib</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- IRIX ld:<literal>
- -Wl,-rpath,<filename class="directory">destdir</filename>/lib</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- Solaris ld:<literal>-Wl,-R<filename class="directory">destdir</filename>/lib</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- More...? Let us know!
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
- <para>
- Use the <command>ldd</command> utility to show which library the
- system thinks it will get at runtime.
+ By default, <command>g++</command> is equivalent to <command>g++ -std=gnu++98</command>. The standard library also defaults to this dialect.
</para>
- <para>
- A libstdc++.la file is also installed, for use with Libtool. If
- you use Libtool to create your executables, these details are
- taken care of for you.
- </para>
- </sect1>
- <sect1 id="manual.intro.using.headers" xreflabel="Headers">
- <title>Headers</title>
+ <table frame="all">
+<title>C++ Command Options</title>
+
+<tgroup cols="2" align="left" colsep="1" rowsep="1">
+<colspec colname="c1"/>
+<colspec colname="c2"/>
+
+ <thead>
+ <row>
+ <entry>Option Flags</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><literal>-std=c++98</literal></entry>
+ <entry>Use the 1998 ISO C++ standard plus amendments.</entry>
+ </row>
+
+ <row>
+ <entry><literal>-std=gnu++98</literal></entry>
+ <entry>As directly above, with GNU extensions.</entry>
+ </row>
+
+ <row>
+ <entry><literal>-std=c++0x</literal></entry>
+ <entry>Use the working draft of the upcoming ISO C++0x standard.</entry>
+ </row>
+
+ <row>
+ <entry><literal>-std=gnu++0x</literal></entry>
+ <entry>As directly above, with GNU extensions.</entry>
+ </row>
+
+ <row>
+ <entry><literal>-fexceptions</literal></entry>
+ <entry>See <link linkend="intro.using.exception.no">exception-free dialect</link></entry>
+ </row>
+
+ <row>
+ <entry><literal>-frtti</literal></entry>
+ <entry>As above, but RTTI-free dialect.</entry>
+ </row>
+
+ <row>
+ <entry><literal>-pthread</literal> or <literal>-pthreads</literal></entry>
+ <entry>For ISO C++0x <thread>, <future>,
+ <mutex>, or <condition_variable>.</entry>
+ </row>
+
+ <row>
+ <entry><literal>-fopenmp</literal></entry>
+ <entry>For <link linkend="manual.ext.parallel_mode">parallel</link> mode.</entry>
+ </row>
+ </tbody>
- <sect2 id="manual.intro.using.headers.all" xreflabel="Header Files">
- <title>Header Files</title>
+</tgroup>
+</table>
+
+ </section>
+
+ <section xml:id="manual.intro.using.headers" xreflabel="Headers"><info><title>Headers</title></info>
+ <?dbhtml filename="using_headers.html"?>
+
+
+ <section xml:id="manual.intro.using.headers.all" xreflabel="Header Files"><info><title>Header Files</title></info>
+
<para>
The C++ standard specifies the entire set of header files that
must be available to all hosted implementations. Actually, the
- word "files" is a misnomer, since the contents of the
+ word "files" is a misnomer, since the contents of the
headers don't necessarily have to be in any kind of external
file. The only rule is that when one <code>#include</code>'s a
header, the contents of that header become available, no matter
That said, in practice files are used.
</para>
- <para>
+ <para>
There are two main types of include files: header files related
to a specific version of the ISO C++ standard (called Standard
Headers), and all others (TR1, C++ ABI, and Extensions).
C++98/03 include files. These are available in the default compilation mode, i.e. <code>-std=c++98</code> or <code>-std=gnu++98</code>.
</para>
-<table frame='all'>
+<table frame="all">
<title>C++ 1998 Library Headers</title>
-<tgroup cols='5' align='left' colsep='1' rowsep='1'>
-<colspec colname='c1'></colspec>
-<colspec colname='c2'></colspec>
-<colspec colname='c3'></colspec>
-<colspec colname='c4'></colspec>
+
+<tgroup cols="5" align="left" colsep="1" rowsep="1">
+<colspec colname="c1"/>
+<colspec colname="c2"/>
+<colspec colname="c3"/>
+<colspec colname="c4"/>
+<colspec colname="c5"/>
<tbody>
-<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>
-<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>
-<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>
-<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>
-<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>
-<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>
-<row><entry><filename class="headerfile">functional</filename></entry><entry><filename class="headerfile">limits</filename></entry></row>
+<row>
+<entry><filename class="headerfile">algorithm</filename></entry>
+<entry><filename class="headerfile">bitset</filename></entry>
+<entry><filename class="headerfile">complex</filename></entry>
+<entry><filename class="headerfile">deque</filename></entry>
+<entry><filename class="headerfile">exception</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">fstream</filename></entry>
+<entry><filename class="headerfile">functional</filename></entry>
+<entry><filename class="headerfile">iomanip</filename></entry>
+<entry><filename class="headerfile">ios</filename></entry>
+<entry><filename class="headerfile">iosfwd</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">iostream</filename></entry>
+<entry><filename class="headerfile">istream</filename></entry>
+<entry><filename class="headerfile">iterator</filename></entry>
+<entry><filename class="headerfile">limits</filename></entry>
+<entry><filename class="headerfile">list</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">locale</filename></entry>
+<entry><filename class="headerfile">map</filename></entry>
+<entry><filename class="headerfile">memory</filename></entry>
+<entry><filename class="headerfile">new</filename></entry>
+<entry><filename class="headerfile">numeric</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">ostream</filename></entry>
+<entry><filename class="headerfile">queue</filename></entry>
+<entry><filename class="headerfile">set</filename></entry>
+<entry><filename class="headerfile">sstream</filename></entry>
+<entry><filename class="headerfile">stack</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">stdexcept</filename></entry>
+<entry><filename class="headerfile">streambuf</filename></entry>
+<entry><filename class="headerfile">string</filename></entry>
+<entry><filename class="headerfile">utility</filename></entry>
+<entry><filename class="headerfile">typeinfo</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">valarray</filename></entry>
+<entry><filename class="headerfile">vector</filename></entry>
+</row>
</tbody>
</tgroup>
</table>
-<para></para>
-<table frame='all'>
+<para/>
+<table frame="all">
<title>C++ 1998 Library Headers for C Library Facilities</title>
-<tgroup cols='5' align='left' colsep='1' rowsep='1'>
-<colspec colname='c1'></colspec>
-<colspec colname='c2'></colspec>
-<colspec colname='c3'></colspec>
-<colspec colname='c4'></colspec>
+
+<tgroup cols="5" align="left" colsep="1" rowsep="1">
+<colspec colname="c1"/>
+<colspec colname="c2"/>
+<colspec colname="c3"/>
+<colspec colname="c4"/>
+<colspec colname="c5"/>
<tbody>
-<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>
-<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>
-<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>
-<row><entry><filename class="headerfile">cfloat</filename></entry><entry><filename class="headerfile">cmath</filename></entry><entry><filename class="headerfile">cstddef</filename></entry></row>
+<row>
+<entry><filename class="headerfile">cassert</filename></entry>
+<entry><filename class="headerfile">cerrno</filename></entry>
+<entry><filename class="headerfile">cctype</filename></entry>
+<entry><filename class="headerfile">cfloat</filename></entry>
+<entry><filename class="headerfile">ciso646</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">climits</filename></entry>
+<entry><filename class="headerfile">clocale</filename></entry>
+<entry><filename class="headerfile">cmath</filename></entry>
+<entry><filename class="headerfile">csetjmp</filename></entry>
+<entry><filename class="headerfile">csignal</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">cstdarg</filename></entry>
+<entry><filename class="headerfile">cstddef</filename></entry>
+<entry><filename class="headerfile">cstdio</filename></entry>
+<entry><filename class="headerfile">cstdlib</filename></entry>
+<entry><filename class="headerfile">cstring</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">ctime</filename></entry>
+<entry><filename class="headerfile">cwchar</filename></entry>
+<entry><filename class="headerfile">cwctype</filename></entry>
+</row>
</tbody>
</tgroup>
</table>
-<para>C++0x include files. These are only available in C++0x compilation mode, i.e. <code>-std=c++0x</code> or <code>-std=gnu++0x</code>.
+<para>
+C++0x include files. These are only available in C++0x compilation
+mode, i.e. <literal>-std=c++0x</literal> or <literal>-std=gnu++0x</literal>.
</para>
-<para></para>
-<table frame='all'>
+<para/>
+<table frame="all">
<title>C++ 200x Library Headers</title>
-<tgroup cols='5' align='left' colsep='1' rowsep='1'>
-<colspec colname='c1'></colspec>
-<colspec colname='c2'></colspec>
-<colspec colname='c3'></colspec>
-<colspec colname='c4'></colspec>
+
+<tgroup cols="5" align="left" colsep="1" rowsep="1">
+<colspec colname="c1"/>
+<colspec colname="c2"/>
+<colspec colname="c3"/>
+<colspec colname="c4"/>
+<colspec colname="c5"/>
<tbody>
-<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>
-<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>
-<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>
-<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>
-<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>
-<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>
-<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>
-<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>
-<row><entry><filename class="headerfile">condition_variable</filename></entry><entry><filename class="headerfile">mutex</filename></entry><entry><filename class="headerfile">thread</filename></entry><entry></entry><entry></entry></row>
+
+<row>
+<entry><filename class="headerfile">algorithm</filename></entry>
+<entry><filename class="headerfile">array</filename></entry>
+<entry><filename class="headerfile">bitset</filename></entry>
+<entry><filename class="headerfile">chrono</filename></entry>
+<entry><filename class="headerfile">complex</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">condition_variable</filename></entry>
+<entry><filename class="headerfile">deque</filename></entry>
+<entry><filename class="headerfile">exception</filename></entry>
+<entry><filename class="headerfile">forward_list</filename></entry>
+<entry><filename class="headerfile">fstream</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">functional</filename></entry>
+<entry><filename class="headerfile">future</filename></entry>
+<entry><filename class="headerfile">initalizer_list</filename></entry>
+<entry><filename class="headerfile">iomanip</filename></entry>
+<entry><filename class="headerfile">ios</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">iosfwd</filename></entry>
+<entry><filename class="headerfile">iostream</filename></entry>
+<entry><filename class="headerfile">istream</filename></entry>
+<entry><filename class="headerfile">iterator</filename></entry>
+<entry><filename class="headerfile">limits</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">list</filename></entry>
+<entry><filename class="headerfile">locale</filename></entry>
+<entry><filename class="headerfile">map</filename></entry>
+<entry><filename class="headerfile">memory</filename></entry>
+<entry><filename class="headerfile">mutex</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">new</filename></entry>
+<entry><filename class="headerfile">numeric</filename></entry>
+<entry><filename class="headerfile">ostream</filename></entry>
+<entry><filename class="headerfile">queue</filename></entry>
+<entry><filename class="headerfile">random</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">ratio</filename></entry>
+<entry><filename class="headerfile">regex</filename></entry>
+<entry><filename class="headerfile">set</filename></entry>
+<entry><filename class="headerfile">sstream</filename></entry>
+<entry><filename class="headerfile">stack</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">stdexcept</filename></entry>
+<entry><filename class="headerfile">streambuf</filename></entry>
+<entry><filename class="headerfile">string</filename></entry>
+<entry><filename class="headerfile">system_error</filename></entry>
+<entry><filename class="headerfile">thread</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">tuple</filename></entry>
+<entry><filename class="headerfile">type_traits</filename></entry>
+<entry><filename class="headerfile">typeinfo</filename></entry>
+<entry><filename class="headerfile">unordered_map</filename></entry>
+<entry><filename class="headerfile">unordered_set</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">utility</filename></entry>
+<entry><filename class="headerfile">valarray</filename></entry>
+<entry><filename class="headerfile">vector</filename></entry>
+</row>
+
</tbody>
</tgroup>
</table>
-<para></para>
+<para/>
-<table frame='all'>
+<table frame="all">
<title>C++ 200x Library Headers for C Library Facilities</title>
-<tgroup cols='5' align='left' colsep='1' rowsep='1'>
-<colspec colname='c1'></colspec>
-<colspec colname='c2'></colspec>
-<colspec colname='c3'></colspec>
-<colspec colname='c4'></colspec>
-<colspec colname='c5'></colspec>
+
+<tgroup cols="5" align="left" colsep="1" rowsep="1">
+<colspec colname="c1"/>
+<colspec colname="c2"/>
+<colspec colname="c3"/>
+<colspec colname="c4"/>
+<colspec colname="c5"/>
<tbody>
-<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>
-<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>
-<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>
-<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>
-<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>
-<row><entry><filename class="headerfile">cstdatomic</filename></entry><entry></entry><entry></entry><entry></entry><entry></entry></row>
+<row>
+<entry><filename class="headerfile">cassert</filename></entry>
+<entry><filename class="headerfile">ccomplex</filename></entry>
+<entry><filename class="headerfile">cctype</filename></entry>
+<entry><filename class="headerfile">cerrno</filename></entry>
+<entry><filename class="headerfile">cfenv</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">cfloat</filename></entry>
+<entry><filename class="headerfile">cinttypes</filename></entry>
+<entry><filename class="headerfile">ciso646</filename></entry>
+<entry><filename class="headerfile">climits</filename></entry>
+<entry><filename class="headerfile">clocale</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">cmath</filename></entry>
+<entry><filename class="headerfile">csetjmp</filename></entry>
+<entry><filename class="headerfile">csignal</filename></entry>
+<entry><filename class="headerfile">cstdarg</filename></entry>
+<entry><filename class="headerfile">cstdbool</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">cstddef</filename></entry>
+<entry><filename class="headerfile">cstdint</filename></entry>
+<entry><filename class="headerfile">cstdlib</filename></entry>
+<entry><filename class="headerfile">cstdio</filename></entry>
+<entry><filename class="headerfile">cstring</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">ctgmath</filename></entry>
+<entry><filename class="headerfile">ctime</filename></entry>
+<entry><filename class="headerfile">cuchar</filename></entry>
+<entry><filename class="headerfile">cwchar</filename></entry>
+<entry><filename class="headerfile">cwctype</filename></entry>
+</row>
</tbody>
</tgroup>
</table>
In addition, TR1 includes as:
</para>
-<table frame='all'>
-<title>C++ TR1 Library Headers</title>
-<tgroup cols='5' align='left' colsep='1' rowsep='1'>
-<colspec colname='c1'></colspec>
-<colspec colname='c2'></colspec>
-<colspec colname='c3'></colspec>
-<colspec colname='c4'></colspec>
-<colspec colname='c5'></colspec>
+<table frame="all">
+<title>C++ TR 1 Library Headers</title>
+
+<tgroup cols="5" align="left" colsep="1" rowsep="1">
+<colspec colname="c1"/>
+<colspec colname="c2"/>
+<colspec colname="c3"/>
+<colspec colname="c4"/>
+<colspec colname="c5"/>
<tbody>
-<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>
-<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>
-<row><entry><filename class="headerfile">tr1/functional</filename></entry></row>
+<row>
+<entry><filename class="headerfile">tr1/array</filename></entry>
+<entry><filename class="headerfile">tr1/complex</filename></entry>
+<entry><filename class="headerfile">tr1/memory</filename></entry>
+<entry><filename class="headerfile">tr1/functional</filename></entry>
+<entry><filename class="headerfile">tr1/random</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">tr1/regex</filename></entry>
+<entry><filename class="headerfile">tr1/tuple</filename></entry>
+<entry><filename class="headerfile">tr1/type_traits</filename></entry>
+<entry><filename class="headerfile">tr1/unordered_map</filename></entry>
+<entry><filename class="headerfile">tr1/unordered_set</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">tr1/utility</filename></entry>
+</row>
+
</tbody>
</tgroup>
</table>
-<para></para>
+<para/>
+
+<table frame="all">
+<title>C++ TR 1 Library Headers for C Library Facilities</title>
-<table frame='all'>
-<title>C++ TR1 Library Headers for C Library Facilities</title>
-<tgroup cols='5' align='left' colsep='1' rowsep='1'>
-<colspec colname='c1'></colspec>
-<colspec colname='c2'></colspec>
-<colspec colname='c3'></colspec>
-<colspec colname='c4'></colspec>
-<colspec colname='c5'></colspec>
+<tgroup cols="5" align="left" colsep="1" rowsep="1">
+<colspec colname="c1"/>
+<colspec colname="c2"/>
+<colspec colname="c3"/>
+<colspec colname="c4"/>
+<colspec colname="c5"/>
<tbody>
-<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>
-<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>
-<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>
+<row>
+<entry><filename class="headerfile">tr1/ccomplex</filename></entry>
+<entry><filename class="headerfile">tr1/cfenv</filename></entry>
+<entry><filename class="headerfile">tr1/cfloat</filename></entry>
+<entry><filename class="headerfile">tr1/cmath</filename></entry>
+<entry><filename class="headerfile">tr1/cinttypes</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">tr1/climits</filename></entry>
+<entry><filename class="headerfile">tr1/cstdarg</filename></entry>
+<entry><filename class="headerfile">tr1/cstdbool</filename></entry>
+<entry><filename class="headerfile">tr1/cstdint</filename></entry>
+<entry><filename class="headerfile">tr1/cstdio</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">tr1/cstdlib</filename></entry>
+<entry><filename class="headerfile">tr1/ctgmath</filename></entry>
+<entry><filename class="headerfile">tr1/ctime</filename></entry>
+<entry><filename class="headerfile">tr1/cwchar</filename></entry>
+<entry><filename class="headerfile">tr1/cwctype</filename></entry>
+</row>
+
+</tbody>
+</tgroup>
+</table>
+
+
+<para>Decimal floating-point arithmetic is available if the C++
+compiler supports scalar decimal floating-point types defined via
+<code>__attribute__((mode(SD|DD|LD)))</code>.
+</para>
+
+<table frame="all">
+<title>C++ TR 24733 Decimal Floating-Point Header</title>
+
+<tgroup cols="1" align="left" colsep="1" rowsep="1">
+<colspec colname="c1"/>
+<tbody>
+<row>
+<entry><filename class="headerfile">decimal/decimal</filename></entry>
+</row>
</tbody>
</tgroup>
</table>
Also included are files for the C++ ABI interface:
</para>
-<table frame='all'>
+<table frame="all">
<title>C++ ABI Headers</title>
-<tgroup cols='2' align='left' colsep='1' rowsep='1'>
-<colspec colname='c1'></colspec>
-<colspec colname='c2'></colspec>
+
+<tgroup cols="2" align="left" colsep="1" rowsep="1">
+<colspec colname="c1"/>
+<colspec colname="c2"/>
<tbody>
<row><entry><filename class="headerfile">cxxabi.h</filename></entry><entry><filename class="headerfile">cxxabi_forced.h</filename></entry></row>
</tbody>
And a large variety of extensions.
</para>
-<table frame='all'>
+<table frame="all">
<title>Extension Headers</title>
-<tgroup cols='5' align='left' colsep='1' rowsep='1'>
-<colspec colname='c1'></colspec>
-<colspec colname='c2'></colspec>
-<colspec colname='c3'></colspec>
-<colspec colname='c4'></colspec>
-<colspec colname='c5'></colspec>
+
+<tgroup cols="5" align="left" colsep="1" rowsep="1">
+<colspec colname="c1"/>
+<colspec colname="c2"/>
+<colspec colname="c3"/>
+<colspec colname="c4"/>
+<colspec colname="c5"/>
<tbody>
-<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>
-<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>
-<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>
-<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>
-<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>
-<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>
+<row>
+<entry><filename class="headerfile">ext/algorithm</filename></entry>
+<entry><filename class="headerfile">ext/atomicity.h</filename></entry>
+<entry><filename class="headerfile">ext/array_allocator.h</filename></entry>
+<entry><filename class="headerfile">ext/bitmap_allocator.h</filename></entry>
+<entry><filename class="headerfile">ext/cast.h</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">ext/codecvt_specializations.h</filename></entry>
+<entry><filename class="headerfile">ext/concurrence.h</filename></entry>
+<entry><filename class="headerfile">ext/debug_allocator.h</filename></entry>
+<entry><filename class="headerfile">ext/enc_filebuf.h</filename></entry>
+<entry><filename class="headerfile">ext/extptr_allocator.h</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">ext/functional</filename></entry>
+<entry><filename class="headerfile">ext/iterator</filename></entry>
+<entry><filename class="headerfile">ext/malloc_allocator.h</filename></entry>
+<entry><filename class="headerfile">ext/memory</filename></entry>
+<entry><filename class="headerfile">ext/mt_allocator.h</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">ext/new_allocator.h</filename></entry>
+<entry><filename class="headerfile">ext/numeric</filename></entry>
+<entry><filename class="headerfile">ext/numeric_traits.h</filename></entry>
+<entry><filename class="headerfile">ext/pb_ds/assoc_container.h</filename></entry>
+<entry><filename class="headerfile">ext/pb_ds/priority_queue.h</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">ext/pod_char_traits.h</filename></entry>
+<entry><filename class="headerfile">ext/pool_allocator.h</filename></entry>
+<entry><filename class="headerfile">ext/rb_tree</filename></entry>
+<entry><filename class="headerfile">ext/rope</filename></entry>
+<entry><filename class="headerfile">ext/slist</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">ext/stdio_filebuf.h</filename></entry>
+<entry><filename class="headerfile">ext/stdio_sync_filebuf.h</filename></entry>
+<entry><filename class="headerfile">ext/throw_allocator.h</filename></entry>
+<entry><filename class="headerfile">ext/typelist.h</filename></entry>
+<entry><filename class="headerfile">ext/type_traits.h</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">ext/vstring.h</filename></entry>
+</row>
+
</tbody>
</tgroup>
</table>
-<para></para>
+<para/>
-<table frame='all'>
+<table frame="all">
<title>Extension Debug Headers</title>
-<tgroup cols='5' align='left' colsep='1' rowsep='1'>
-<colspec colname='c1'></colspec>
-<colspec colname='c2'></colspec>
-<colspec colname='c3'></colspec>
-<colspec colname='c4'></colspec>
-<colspec colname='c5'></colspec>
+
+<tgroup cols="5" align="left" colsep="1" rowsep="1">
+<colspec colname="c1"/>
+<colspec colname="c2"/>
+<colspec colname="c3"/>
+<colspec colname="c4"/>
+<colspec colname="c5"/>
<tbody>
-<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>
-<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>
+<row>
+<entry><filename class="headerfile">debug/bitset</filename></entry>
+<entry><filename class="headerfile">debug/deque</filename></entry>
+<entry><filename class="headerfile">debug/list</filename></entry>
+<entry><filename class="headerfile">debug/map</filename></entry>
+<entry><filename class="headerfile">debug/set</filename></entry>
+</row>
+
+<row>
+<entry><filename class="headerfile">debug/string</filename></entry>
+<entry><filename class="headerfile">debug/unordered_map</filename></entry>
+<entry><filename class="headerfile">debug/unordered_set</filename></entry>
+<entry><filename class="headerfile">debug/vector</filename></entry>
+</row>
+
</tbody>
</tgroup>
</table>
-<para></para>
+<para/>
+
+<table frame="all">
+<title>Extension Profile Headers</title>
+
+<tgroup cols="4" align="left" colsep="1" rowsep="1">
+<colspec colname="c1"/>
+<colspec colname="c2"/>
+<colspec colname="c3"/>
+<colspec colname="c4"/>
+<tbody>
+
+<row>
+<entry><filename class="headerfile">profile/bitset</filename></entry>
+<entry><filename class="headerfile">profile/deque</filename></entry>
+<entry><filename class="headerfile">profile/list</filename></entry>
+<entry><filename class="headerfile">profile/map</filename></entry>
+</row>
+
+<row>
+<entry><filename class="headerfile">profile/set</filename></entry>
+<entry><filename class="headerfile">profile/unordered_map</filename></entry>
+<entry><filename class="headerfile">profile/unordered_set</filename></entry>
+<entry><filename class="headerfile">profile/vector</filename></entry>
+</row>
+
+</tbody>
+</tgroup>
+</table>
-<table frame='all'>
+<para/>
+
+<table frame="all">
<title>Extension Parallel Headers</title>
-<tgroup cols='2' align='left' colsep='1' rowsep='1'>
-<colspec colname='c1'></colspec>
-<colspec colname='c2'></colspec>
+
+<tgroup cols="2" align="left" colsep="1" rowsep="1">
+<colspec colname="c1"/>
+<colspec colname="c2"/>
<tbody>
-<row><entry><filename class="headerfile">parallel/algorithm</filename></entry><entry><filename class="headerfile">parallel/numeric</filename></entry></row>
+<row>
+<entry><filename class="headerfile">parallel/algorithm</filename></entry>
+<entry><filename class="headerfile">parallel/numeric</filename></entry>
+</row>
</tbody>
</tgroup>
</table>
- </sect2>
+ </section>
- <sect2 id="manual.intro.using.headers.mixing" xreflabel="Mixing Headers">
- <title>Mixing Headers</title>
+ <section xml:id="manual.intro.using.headers.mixing" xreflabel="Mixing Headers"><info><title>Mixing Headers</title></info>
+
<para> A few simple rules.
</para>
<para> Several parts of C++0x diverge quite substantially from TR1 predecessors.
</para>
- </sect2>
+ </section>
- <sect2 id="manual.intro.using.headers.cheaders" xreflabel="C Headers and">
- <title>The C Headers and <code>namespace std</code></title>
+ <section xml:id="manual.intro.using.headers.cheaders" xreflabel="C Headers and"><info><title>The C Headers and <code>namespace std</code></title></info>
+
<para>
The standard specifies that if one includes the C-style header
(<math.h> in this case), the symbols will be available
in the global namespace and perhaps in
namespace <code>std::</code> (but this is no longer a firm
- requirement.) One the other hand, including the C++-style
+ requirement.) On the other hand, including the C++-style
header (<cmath>) guarantees that the entities will be
found in namespace std and perhaps in the global namespace.
</para>
of <code>std::sinf</code>, <code>std::sin</code>,
and <code>std::sinl</code>.
</para>
- </sect2>
+ </section>
- <sect2 id="manual.intro.using.headers.pre" xreflabel="Precompiled Headers">
- <title>Precompiled Headers</title>
+ <section xml:id="manual.intro.using.headers.pre" xreflabel="Precompiled Headers"><info><title>Precompiled Headers</title></info>
+
<para>There are three base header files that are provided. They can be
<para>How to use the resulting file.</para>
<programlisting>
-g++ -I. -include stdc++.h -H -g -O2 hello.cc
+g++ -I. -include stdc++.h -H -g -O2 hello.cc
</programlisting>
<para>Verification that the PCH file is being used is easy:</para>
</programlisting>
<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>
-<para></para>
+<para/>
-<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>.
+<para> Detailed information about creating precompiled header files can be found in the GCC <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/gcc/Precompiled-Headers.html">documentation</link>.
</para>
+ </section>
+ </section>
+
+
+ <section xml:id="manual.intro.using.macros" xreflabel="Macros"><info><title>Macros</title></info>
+ <?dbhtml filename="using_macros.html"?>
+
+
+ <para>
+ All library macros begin with <code>_GLIBCXX_</code>.
+ </para>
+
+ <para>
+ Furthermore, all pre-processor macros, switches, and
+ configuration options are gathered in the
+ file <filename class="headerfile">c++config.h</filename>, which
+ is generated during the libstdc++ configuration and build
+ process. This file is then included when needed by files part of
+ the public libstdc++ API, like <ios>. Most of these macros
+ should not be used by consumers of libstdc++, and are reserved
+ for internal implementation use. <emphasis>These macros cannot
+ be redefined</emphasis>.
+ </para>
+
+ <para>
+ A select handful of macros control libstdc++ extensions and extra
+ features, or provide versioning information for the API. Only
+ those macros listed below are offered for consideration by the
+ general public.
+ </para>
+
+ <para>Below is the macro which users may check for library version
+ information. </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><code>__GLIBCXX__</code></term>
+ <listitem>
+ <para>The current version of
+ libstdc++ in compressed ISO date format, form of an unsigned
+ long. For details on the value of this particular macro for a
+ particular release, please consult this <link linkend="appendix.porting.abi">
+ document</link>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Below are the macros which users may change with #define/#undef or
+ with -D/-U compiler flags. The default state of the symbol is
+ listed.</para>
+
+ <para><quote>Configurable</quote> (or <quote>Not configurable</quote>) means
+ that the symbol is initially chosen (or not) based on
+ --enable/--disable options at library build and configure time
+ (documented <link linkend="manual.intro.setup.configure">here</link>), with the
+ various --enable/--disable choices being translated to
+ #define/#undef).
+ </para>
+
+ <para> <acronym>ABI</acronym> means that changing from the default value may
+ mean changing the <acronym>ABI</acronym> of compiled code. In other words, these
+ choices control code which has already been compiled (i.e., in a
+ binary such as libstdc++.a/.so). If you explicitly #define or
+ #undef these macros, the <emphasis>headers</emphasis> may see different code
+ paths, but the <emphasis>libraries</emphasis> which you link against will not.
+ Experimenting with different values with the expectation of
+ consistent linkage requires changing the config headers before
+ building/installing the library.
+ </para>
+
+ <variablelist>
+ <varlistentry><term><code>_GLIBCXX_USE_DEPRECATED</code></term>
+ <listitem>
+ <para>
+ Defined by default. Not configurable. ABI-changing. Turning this off
+ removes older ARM-style iostreams code, and other anachronisms
+ from the API. This macro is dependent on the version of the
+ standard being tracked, and as a result may give different results for
+ <code>-std=c++98</code> and <code>-std=c++0x</code>. This may
+ be useful in updating old C++ code which no longer meet the
+ requirements of the language, or for checking current code
+ against new language standards.
+ </para>
+ </listitem></varlistentry>
+
+ <varlistentry><term><code>_GLIBCXX_FORCE_NEW</code></term>
+ <listitem>
+ <para>
+ Undefined by default. When defined, memory allocation and
+ allocators controlled by libstdc++ call operator new/delete
+ without caching and pooling. Configurable via
+ <code>--enable-libstdcxx-allocator</code>. ABI-changing.
+ </para>
+ </listitem></varlistentry>
+
+
+ <varlistentry><term><code>_GLIBCXX_CONCEPT_CHECKS</code></term>
+ <listitem>
+ <para>
+ Undefined by default. Configurable via
+ <code>--enable-concept-checks</code>. When defined, performs
+ compile-time checking on certain template instantiations to
+ detect violations of the requirements of the standard. This
+ is described in more detail <link linkend="manual.ext.compile_checks">here</link>.
+ </para>
+ </listitem></varlistentry>
+
+ <varlistentry><term><code>_GLIBCXX_DEBUG</code></term>
+ <listitem>
+ <para>
+ Undefined by default. When defined, compiles user code using
+ the <link linkend="manual.ext.debug_mode">debug mode</link>.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term><code>_GLIBCXX_DEBUG_PEDANTIC</code></term>
+ <listitem>
+ <para>
+ Undefined by default. When defined while compiling with
+ the <link linkend="manual.ext.debug_mode">debug mode</link>, makes
+ the debug mode extremely picky by making the use of libstdc++
+ extensions and libstdc++-specific behavior into errors.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term><code>_GLIBCXX_PARALLEL</code></term>
+ <listitem>
+ <para>Undefined by default. When defined, compiles user code
+ using the <link linkend="manual.ext.parallel_mode">parallel
+ mode</link>.
+ </para>
+ </listitem></varlistentry>
+
+ <varlistentry><term><code>_GLIBCXX_PROFILE</code></term>
+ <listitem>
+ <para>Undefined by default. When defined, compiles user code
+ using the <link linkend="manual.ext.profile_mode">profile
+ mode</link>.
+ </para>
+ </listitem></varlistentry>
+ </variablelist>
- </sect2>
- </sect1>
+ </section>
- <sect1 id="manual.intro.using.namespaces" xreflabel="Namespaces">
- <title>Namespaces</title>
+ <section xml:id="manual.intro.using.namespaces" xreflabel="Namespaces"><info><title>Namespaces</title></info>
+ <?dbhtml filename="using_namespaces.html"?>
+
- <sect2 id="manual.intro.using.namespaces.all" xreflabel="Available Namespaces">
- <title>Available Namespaces</title>
+ <section xml:id="manual.intro.using.namespaces.all" xreflabel="Available Namespaces"><info><title>Available Namespaces</title></info>
+
</para></listitem>
</itemizedlist>
-<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>.
+<para> A complete list of implementation namespaces (including namespace contents) is available in the generated source <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/namespaces.html">documentation</link>.
</para>
- </sect2>
+ </section>
- <sect2 id="manual.intro.using.namespaces.std" xreflabel="namespace std">
- <title>namespace std</title>
+ <section xml:id="manual.intro.using.namespaces.std" xreflabel="namespace std"><info><title>namespace std</title></info>
+
<para>
std::string;</code>) This approach works well for individual source files, but
should not be used in a global context, like header files.
</para></listitem> <listitem><para>use a <emphasis>fully
-qualified name</emphasis>for each library symbol
+qualified name</emphasis> for each library symbol
(i.e. <code>std::string</code>, <code>std::cout</code>) Always can be
used, and usually enhanced, by strategic use of typedefs. (In the
cases where the qualified verbiage becomes unwieldy.)
</listitem>
</itemizedlist>
- </sect2>
+ </section>
- <sect2 id="manual.intro.using.namespaces.comp" xreflabel="Using Namespace Composition">
- <title>Using Namespace Composition</title>
+ <section xml:id="manual.intro.using.namespaces.comp" xreflabel="Using Namespace Composition"><info><title>Using Namespace Composition</title></info>
+
<para>
Best practice in programming suggests sequestering new data or
currently active namespace(s). For example:
</para>
<programlisting>
-namespace gtk
+namespace gtk
{
using std::string;
using std::tr1::array;
<para>
In this example, <code>std::string</code> gets imported into
<code>namespace gtk</code>. The result is that use of
- <code>std::string</code> inside namespace gtk can just use <code>string</code>, without the explicit qualification.
- As an added bonus,
+ <code>std::string</code> inside namespace gtk can just use <code>string</code>, without the explicit qualification.
+ As an added bonus,
<code>std::string</code> does not get imported into
the global namespace. Additionally, a more elaborate arrangement can be made for backwards compatibility and portability, whereby the
<code>using</code>-declarations can wrapped in macros that
- are set based on autoconf-tests to either "" or i.e. <code>using
+ are set based on autoconf-tests to either "" or i.e. <code>using
std::string;</code> (depending on whether the system has
libstdc++ in <code>std::</code> or not). (ideas from
- <email>llewelly@dbritsch.dsl.xmission.com</email>, Karl Nelson <email>kenelson@ece.ucdavis.edu</email>)
+ Llewelly and Karl Nelson)
</para>
- </sect2>
- </sect1>
+ </section>
+ </section>
- <sect1 id="manual.intro.using.macros" xreflabel="Macros">
- <title>Macros</title>
+ <section xml:id="manual.intro.using.linkage" xreflabel="Linkage"><info><title>Linking</title></info>
+ <?dbhtml filename="using_dynamic_or_shared.html"?>
+
- <para>All pre-processor switches and configurations are all gathered
- in the file <code>c++config.h</code>, which is generated during
- the libstdc++ configuration and build process, and included by
- files part of the public libstdc++ API. Most of these macros
- should not be used by consumers of libstdc++, and are reserved
- for internal implementation use. <emphasis>These macros cannot be
- redefined</emphasis>. However, a select handful of these macro
- control libstdc++ extensions and extra features, or provide
- versioning information for the API, and are able to be used.
- </para>
+ <section xml:id="manual.intro.using.linkage.freestanding" xreflabel="Freestanding"><info><title>Almost Nothing</title></info>
+
+ <para>
+ Or as close as it gets: freestanding. This is a minimal
+ configuration, with only partial support for the standard
+ library. Assume only the following header files can be used:
+ </para>
- <para>All library macros begin with <code>_GLIBCXX_</code> (except for
- versions 3.1.x to 3.3.x, which use <code>_GLIBCPP_</code>).
- </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <filename class="headerfile">cstdarg</filename>
+ </para>
+ </listitem>
- <para>Below is the macro which users may check for library version
- information. </para>
+ <listitem>
+ <para>
+ <filename class="headerfile">cstddef</filename>
+ </para>
+ </listitem>
- <variablelist>
- <varlistentry>
- <term><code>__GLIBCXX__</code></term>
- <listitem>
- <para>The current version of
- libstdc++ in compressed ISO date format, form of an unsigned
- long. For details on the value of this particular macro for a
- particular release, please consult this <ulink url="abi.html">
- document</ulink>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
+ <listitem>
+ <para>
+ <filename class="headerfile">cstdlib</filename>
+ </para>
+ </listitem>
- <para>Below are the macros which users may change with #define/#undef or
- with -D/-U compiler flags. The default state of the symbol is
- listed.</para>
+ <listitem>
+ <para>
+ <filename class="headerfile">exception</filename>
+ </para>
+ </listitem>
- <para><quote>Configurable</quote> (or <quote>Not configurable</quote>) means
- that the symbol is initially chosen (or not) based on
- --enable/--disable options at library build and configure time
- (documented <link linkend="manual.intro.setup.configure">here</link>), with the
- various --enable/--disable choices being translated to
- #define/#undef).
- </para>
+ <listitem>
+ <para>
+ <filename class="headerfile">limits</filename>
+ </para>
+ </listitem>
- <para> <acronym>ABI</acronym> means that changing from the default value may
- mean changing the <acronym>ABI</acronym> of compiled code. In other words, these
- choices control code which has already been compiled (i.e., in a
- binary such as libstdc++.a/.so). If you explicitly #define or
- #undef these macros, the <emphasis>headers</emphasis> may see different code
- paths, but the <emphasis>libraries</emphasis> which you link against will not.
- Experimenting with different values with the expectation of
- consistent linkage requires changing the config headers before
- building/installing the library.
- </para>
+ <listitem>
+ <para>
+ <filename class="headerfile">new</filename>
+ </para>
+ </listitem>
- <variablelist>
- <varlistentry><term><code>_GLIBCXX_DEPRECATED</code></term>
- <listitem>
- <para>
- Defined by default. Not configurable. ABI-changing. Turning this off
- removes older ARM-style iostreams code, and other anachronisms
- from the API. This macro is dependent on the version of the
- standard being tracked, and as a result may give different results for
- <code>-std=c++98</code> and <code>-std=c++0x</code>. This may
- be useful in updating old C++ code which no longer meet the
- requirements of the language, or for checking current code
- against new language standards.
- </para>
- </listitem></varlistentry>
+ <listitem>
+ <para>
+ <filename class="headerfile">exception</filename>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <filename class="headerfile">typeinfo</filename>
+ </para>
+ </listitem>
+ </itemizedlist>
- <varlistentry><term><code>_GLIBCXX_FORCE_NEW</code></term>
- <listitem>
<para>
- Undefined by default. When defined, memory allocation and
- allocators controlled by libstdc++ call operator new/delete
- without caching and pooling. Configurable via
- <code>--enable-libstdcxx-allocator</code>. ABI-changing.
+ In addition, throw in
</para>
- </listitem></varlistentry>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <filename class="headerfile">cxxabi.h</filename>.
+ </para>
+ </listitem>
+ </itemizedlist>
- <varlistentry><term><code>_GLIBCXX_CONCEPT_CHECKS</code></term>
- <listitem>
<para>
- Undefined by default. Configurable via
- <code>--enable-concept-checks</code>. When defined, performs
- compile-time checking on certain template instantiations to
- detect violations of the requirements of the standard. This
- is described in more detail <ulink
- url="../19_diagnostics/howto.html#3">here</ulink>.
+ In the
+ C++0x <link linkend="manual.intro.using.flags">dialect</link> add
</para>
- </listitem></varlistentry>
- <varlistentry><term><code>_GLIBCXX_DEBUG</code></term>
- <listitem>
- <para>
- Undefined by default. When defined, compiles
- user code using the <ulink url="../ext/debug.html#safe">libstdc++ debug
- mode</ulink>.
+ <itemizedlist>
+ <listitem>
+ <para>
+ <filename class="headerfile">initializer_list</filename>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename class="headerfile">type_traits</filename>
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para> There exists a library that offers runtime support for
+ just these headers, and it is called
+ <filename class="libraryfile">libsupc++.a</filename>. To use it, compile with <command>gcc</command> instead of <command>g++</command>, like so:
</para>
- </listitem></varlistentry>
- <varlistentry><term><code>_GLIBCXX_DEBUG_PEDANTIC</code></term>
- <listitem>
+
<para>
- Undefined by default. When defined while
- compiling with the <ulink url="../ext/debug.html#safe">libstdc++ debug
- mode</ulink>, makes the debug mode extremely picky by making the use
- of libstdc++ extensions and libstdc++-specific behavior into
- errors.
+ <command>gcc foo.cc -lsupc++</command>
</para>
- </listitem></varlistentry>
- <varlistentry><term><code>_GLIBCXX_PARALLEL</code></term>
- <listitem>
- <para>Undefined by default. When defined, compiles
- user code using the <ulink url="../ext/parallel_mode.html">libstdc++ parallel
- mode</ulink>.
+
+ <para>
+ No attempt is made to verify that only the minimal subset
+ identified above is actually used at compile time. Violations
+ are diagnosed as undefined symbols at link time.
</para>
- </listitem></varlistentry>
- </variablelist>
+ </section>
+
+ <section xml:id="manual.intro.using.linkage.dynamic" xreflabel="Dynamic and Shared"><info><title>Finding Dynamic or Shared Libraries</title></info>
+
+
+ <para>
+ If the only library built is the static library
+ (<filename class="libraryfile">libstdc++.a</filename>), or if
+ specifying static linking, this section is can be skipped. But
+ if building or using a shared library
+ (<filename class="libraryfile">libstdc++.so</filename>), then
+ additional location information will need to be provided.
+ </para>
+ <para>
+ But how?
+ </para>
+ <para>
+A quick read of the relevant part of the GCC
+ manual, <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/gcc/Invoking-G_002b_002b.html#Invoking-G_002b_002b">Compiling
+ C++ Programs</link>, specifies linking against a C++
+ library. More details from the
+ GCC <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/faq.html#rpath">FAQ</link>,
+ which states <emphasis>GCC does not, by default, specify a
+ location so that the dynamic linker can find dynamic libraries at
+ runtime.</emphasis>
+ </para>
+ <para>
+ Users will have to provide this information.
+ </para>
+ <para>
+ Methods vary for different platforms and different styles, and
+ are printed to the screen during installation. To summarize:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ At runtime set <literal>LD_LIBRARY_PATH</literal> in your
+ environment correctly, so that the shared library for
+ libstdc++ can be found and loaded. Be certain that you
+ understand all of the other implications and behavior
+ of <literal>LD_LIBRARY_PATH</literal> first.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ Compile the path to find the library at runtime into the
+ program. This can be done by passing certain options to
+ <command>g++</command>, which will in turn pass them on to
+ the linker. The exact format of the options is dependent on
+ which linker you use:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ GNU ld (default on Linux):
+ <literal>-Wl,-rpath,</literal><filename class="directory">destdir/lib</filename>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ IRIX ld:
+ <literal>-Wl,-rpath,</literal><filename class="directory">destdir/lib</filename>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Solaris ld:
+ <literal>-Wl,-R</literal><filename class="directory">destdir/lib</filename>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>
+ Some linkers allow you to specify the path to the library by
+ setting <literal>LD_RUN_PATH</literal> in your environment
+ when linking.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ On some platforms the system administrator can configure the
+ dynamic linker to always look for libraries in
+ <filename class="directory">destdir/lib</filename>, for example
+ by using the <command>ldconfig</command> utility on Linux
+ or the <command>crle</command> utility on Solaris. This is a
+ system-wide change which can make the system unusable so if you
+ are unsure then use one of the other methods described above.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Use the <command>ldd</command> utility on the linked executable
+ to show
+ which <filename class="libraryfile">libstdc++.so</filename>
+ library the system will get at runtime.
+ </para>
+ <para>
+ A <filename class="libraryfile">libstdc++.la</filename> file is
+ also installed, for use with Libtool. If you use Libtool to
+ create your executables, these details are taken care of for
+ you.
+ </para>
+ </section>
+ </section>
- </sect1>
-
- <sect1 id="manual.intro.using.concurrency" xreflabel="Concurrency">
- <title>Concurrency</title>
+ <section xml:id="manual.intro.using.concurrency" xreflabel="Concurrency"><info><title>Concurrency</title></info>
+ <?dbhtml filename="using_concurrency.html"?>
+
<para>This section discusses issues surrounding the proper compilation
of multithreaded applications which use the Standard C++
standard does not address matters of multithreaded applications.
</para>
- <sect2 id="manual.intro.using.concurrency.prereq" xreflabel="Thread Prereq">
- <title>Prerequisites</title>
+ <section xml:id="manual.intro.using.concurrency.prereq" xreflabel="Thread Prereq"><info><title>Prerequisites</title></info>
+
<para>All normal disclaimers aside, multithreaded C++ application are
only supported when libstdc++ and all user code was built with
in ``gcc -dumpspecs'' (look at lib and cpp entries).
</para>
- </sect2>
-
- <sect2 id="manual.intro.using.concurrency.thread_safety" xreflabel="Thread Safety">
- <title>Thread Safety</title>
+ </section>
+ <section xml:id="manual.intro.using.concurrency.thread_safety" xreflabel="Thread Safety"><info><title>Thread Safety</title></info>
+
<para>
-We currently use the <ulink url="http://www.sgi.com/tech/stl/thread_safety.html">SGI STL</ulink> definition of thread safety.
+In the terms of the 2011 C++ standard a thread-safe program is one which
+does not perform any conflicting non-atomic operations on memory locations
+and so does not contain any data races.
+The standard places requirements on the library to ensure that no data
+races are caused by the library itself or by programs which use the
+library correctly (as described below).
+The C++11 memory model and library requirements are a more formal version
+of the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.sgi.com/tech/stl/thread_safety.html">SGI STL</link> definition of thread safety, which the library used
+prior to the 2011 standard.
</para>
<para>The library strives to be thread-safe when all of the following
- conditions are met:
+ conditions are met:
</para>
<itemizedlist>
<listitem>
Requisite command-line flags are used for atomic operations
and threading. Examples of this include <code>-pthread</code>
and <code>-march=native</code>, although specifics vary
- depending on the host environment. See <ulink
- url="http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html">Machine
- Dependent Options</ulink>.
+ depending on the host environment. See <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html">Machine
+ Dependent Options</link>.
</para>
</listitem>
<listitem>
<para>
An implementation of atomicity.h functions
- exists for the architecture in question. See the internals documentation for more <ulink url="../ext/concurrence.html">details</ulink>.
+ exists for the architecture in question. See the internals documentation for more <link linkend="internals.thread_safety">details</link>.
</para>
</listitem>
</itemizedlist>
- <para>The user-code must guard against concurrent method calls which may
- access any particular library object's state. Typically, the
- application programmer may infer what object locks must be held
- based on the objects referenced in a method call. Without getting
- into great detail, here is an example which requires user-level
- locks:
+
+ <para>The user code must guard against concurrent function calls which
+ access any particular library object's state when one or more of
+ those accesses modifies the state. An object will be modified by
+ invoking a non-const member function on it or passing it as a
+ non-const argument to a library function. An object will not be
+ modified by invoking a const member function on it or passing it to
+ a function as a pointer- or reference-to-const.
+ Typically, the application
+ programmer may infer what object locks must be held based on the
+ objects referenced in a function call and whether the objects are
+ accessed as const or non-const. Without getting
+ into great detail, here is an example which requires user-level
+ locks:
</para>
<programlisting>
library_class_a shared_object_a;
- thread_main () {
+ void thread_main () {
library_class_b *object_b = new library_class_b;
shared_object_a.add_b (object_b); // must hold lock for shared_object_a
shared_object_a.mutate (); // must hold lock for shared_object_a
// Multiple copies of thread_main() are started in independent threads.</programlisting>
<para>Under the assumption that object_a and object_b are never exposed to
- another thread, here is an example that should not require any
- user-level locks:
+ another thread, here is an example that does not require any
+ user-level locks:
</para>
<programlisting>
- thread_main () {
+ void thread_main () {
library_class_a object_a;
library_class_b *object_b = new library_class_b;
object_a.add_b (object_b);
object_a.mutate ();
} </programlisting>
- <para>All library objects are safe to use in a multithreaded program as
- long as each thread carefully locks out access by any other
- thread while it uses any object visible to another thread, i.e.,
- treat library objects like any other shared resource. In general,
- this requirement includes both read and write access to objects;
- unless otherwise documented as safe, do not assume that two threads
- may access a shared standard library object at the same time.
+
+ <para>All library types are safe to use in a multithreaded program
+ if objects are not shared between threads or as
+ long each thread carefully locks out access by any other
+ thread while it modifies any object visible to another thread.
+ Unless otherwise documented, the only exceptions to these rules
+ are atomic operations on the types in
+ <filename class="headerfile"><atomic></filename>
+ and lock/unlock operations on the standard mutex types in
+ <filename class="headerfile"><mutex></filename>. These
+ atomic operations allow concurrent accesses to the same object
+ without introducing data races.
</para>
- <para>See chapters <ulink url="../17_intro/howto.html#3">17</ulink> (library
- introduction), <ulink url="../23_containers/howto.html#3">23</ulink>
- (containers), and <ulink url="../27_io/howto.html#9">27</ulink> (I/O) for
- more information.
+
+ <para>The following member functions of standard containers can be
+ considered to be const for the purposes of avoiding data races:
+ <code>begin</code>, <code>end</code>, <code>rbegin</code>, <code>rend</code>,
+ <code>front</code>, <code>back</code>, <code>data</code>,
+ <code>find</code>, <code>lower_bound</code>, <code>upper_bound</code>,
+ <code>equal_range</code>, <code>at</code>
+ and, except in associative or unordered associative containers,
+ <code>operator[]</code>. In other words, although they are non-const
+ so that they can return mutable iterators, those member functions
+ will not modify the container.
+ Accessing an iterator might cause a non-modifying access to
+ the container the iterator refers to (for example incrementing a
+ list iterator must access the pointers between nodes, which are part
+ of the container and so conflict with other accesses to the container).
</para>
+ <para>Programs which follow the rules above will not encounter data
+ races in library code, even when using library types which share
+ state between distinct objects. In the example below the
+ <code>shared_ptr</code> objects share a reference count, but
+ because the code does not perform any non-const operations on the
+ globally-visible object, the library ensures that the reference
+ count updates are atomic and do not introduce data races:
+ </para>
+ <programlisting>
+ std::shared_ptr<int> global_sp;
+
+ void thread_main() {
+ auto local_sp = global_sp; // OK, copy constructor's parameter is reference-to-const
+
+ int i = *global_sp; // OK, operator* is const
+ int j = *local_sp; // OK, does not operate on global_sp
+
+ // *global_sp = 2; // NOT OK, modifies int visible to other threads
+ // *local_sp = 2; // NOT OK, modifies int visible to other threads
+
+ // global_sp.reset(); // NOT OK, reset is non-const
+ local_sp.reset(); // OK, does not operate on global_sp
+ }
+
+ int main() {
+ global_sp.reset(new int(1));
+ std::thread t1(thread_main);
+ std::thread t2(thread_main);
+ t1.join();
+ t2.join();
+ }
+ </programlisting>
+
+ <para>For further details of the C++11 memory model see Hans-J. Boehm's
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.hpl.hp.com/personal/Hans_Boehm/c++mm/user-faq.html">Threads
+ and memory model for C++</link> pages, particularly the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.hpl.hp.com/personal/Hans_Boehm/c++mm/threadsintro.html">introduction</link>
+ and <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.hpl.hp.com/personal/Hans_Boehm/c++mm/user-faq.html">FAQ</link>.
+ </para>
- </sect2>
- <sect2 id="manual.intro.using.concurrency.atomics" xreflabel="Atomics">
- <title>Atomics</title>
+ </section>
+ <section xml:id="manual.intro.using.concurrency.atomics" xreflabel="Atomics"><info><title>Atomics</title></info>
+
<para>
</para>
- </sect2>
-
- <sect2 id="manual.intro.using.concurrency.io" xreflabel="IO">
- <title>IO</title>
- <para>I'll assume that you have already read the
- <ulink url="../17_intro/howto.html#3">general notes on library threads</ulink>,
- and the
- <ulink url="../23_containers/howto.html#3">notes on threaded container
- access</ulink> (you might not think of an I/O stream as a container, but
- the points made there also hold here). If you have not read them,
- please do so first.
- </para>
- <para>This gets a bit tricky. Please read carefully, and bear with me.
+ </section>
+
+ <section xml:id="manual.intro.using.concurrency.io" xreflabel="IO"><info><title>IO</title></info>
+
+ <para>This gets a bit tricky. Please read carefully, and bear with me.
</para>
- <sect3 id="concurrency.io.structure" xreflabel="Structure">
- <title>Structure</title>
+ <section xml:id="concurrency.io.structure" xreflabel="Structure"><info><title>Structure</title></info>
+
<para>A wrapper
type called <code>__basic_file</code> provides our abstraction layer
for the <code>std::filebuf</code> classes. Nearly all decisions dealing
level is akin to providing locking within containers, and is not done
for the same reasons (see the links above).
</para>
- </sect3>
+ </section>
- <sect3 id="concurrency.io.defaults" xreflabel="Defaults">
- <title>Defaults</title>
+ <section xml:id="concurrency.io.defaults" xreflabel="Defaults"><info><title>Defaults</title></info>
+
<para>The __basic_file type is simply a collection of small wrappers around
the C stdio layer (again, see the link under Structure). We do no
locking ourselves, but simply pass through to calls to <code>fopen</code>,
<code>fwrite</code>, and so forth.
</para>
- <para>So, for 3.0, the question of "is multithreading safe for I/O"
- must be answered with, "is your platform's C library threadsafe
- for I/O?" Some are by default, some are not; many offer multiple
+ <para>So, for 3.0, the question of "is multithreading safe for I/O"
+ must be answered with, "is your platform's C library threadsafe
+ for I/O?" Some are by default, some are not; many offer multiple
implementations of the C library with varying tradeoffs of threadsafety
and efficiency. You, the programmer, are always required to take care
with multiple threads.
inside an <code>std::ofstream</code>), you need to guard such accesses
like any other critical shared resource.
</para>
- </sect3>
+ </section>
- <sect3 id="concurrency.io.future" xreflabel="Future">
- <title>Future</title>
+ <section xml:id="concurrency.io.future" xreflabel="Future"><info><title>Future</title></info>
+
<para> A
second choice may be available for I/O implementations: libio. This is
disabled by default, and in fact will not currently work due to other
type is basically derived from FILE. (The real situation is more
complex than that... it's derived from an internal type used to
implement FILE. See libio/libioP.h to see scary things done with
- vtbls.) The result is that there is no "layer" of C stdio
+ vtbls.) The result is that there is no "layer" of C stdio
to go through; the filebuf makes calls directly into the same
functions used to implement <code>fread</code>, <code>fwrite</code>,
and so forth, using internal data structures. (And when I say
- "makes calls directly," I mean the function is literally
+ "makes calls directly," I mean the function is literally
replaced by a jump into an internal function. Fast but frightening.
*grin*)
</para>
installed. For other platforms, a copy of the libio subsection will
be built and included in libstdc++.
</para>
- </sect3>
+ </section>
- <sect3 id="concurrency.io.alt" xreflabel="Alt">
- <title>Alternatives</title>
+ <section xml:id="concurrency.io.alt" xreflabel="Alt"><info><title>Alternatives</title></info>
+
<para>Don't forget that other cstdio implementations are possible. You could
easily write one to perform your own forms of locking, to solve your
- "interesting" problems.
+ "interesting" problems.
</para>
- </sect3>
+ </section>
- </sect2>
+ </section>
- <sect2 id="manual.intro.using.concurrency.containers" xreflabel="Containers">
- <title>Containers</title>
+ <section xml:id="manual.intro.using.concurrency.containers" xreflabel="Containers"><info><title>Containers</title></info>
+
<para>This section discusses issues surrounding the design of
multithreaded applications which use Standard C++ containers.
</para>
<para>Two excellent pages to read when working with the Standard C++
containers and threads are
- <ulink url="http://www.sgi.com/tech/stl/thread_safety.html">SGI's
- http://www.sgi.com/tech/stl/thread_safety.html</ulink> and
- <ulink url="http://www.sgi.com/tech/stl/Allocators.html">SGI's
- http://www.sgi.com/tech/stl/Allocators.html</ulink>.
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.sgi.com/tech/stl/thread_safety.html">SGI's
+ http://www.sgi.com/tech/stl/thread_safety.html</link> and
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.sgi.com/tech/stl/Allocators.html">SGI's
+ http://www.sgi.com/tech/stl/Allocators.html</link>.
</para>
<para><emphasis>However, please ignore all discussions about the user-level
configuration of the lock implementation inside the STL
code, we use the same definition of thread safety as SGI when
discussing design. A key point that beginners may miss is the
fourth major paragraph of the first page mentioned above
- ("For most clients,"...), which points out that
+ (<emphasis>For most clients...</emphasis>), which points out that
locking must nearly always be done outside the container, by
client code (that'd be you, not us). There is a notable
exceptions to this rule. Allocators called while a container or
mechanism. Trying to provide a catch-all general template
solution would probably be more trouble than it's worth.
</para>
- <para>The STL implementation is currently configured to use the
- high-speed caching memory allocator. Some people like to
- test and/or normally run threaded programs with a different
- default. For all details about how to globally override this
- at application run-time see <ulink url="../ext/howto.html#3">here</ulink>.
- </para>
- <para>There is a better way (not standardized yet): It is possible to
- force the malloc-based allocator on a per-case-basis for some
- application code. The library team generally believes that this
- is a better way to tune an application for high-speed using this
- implementation of the STL. There is
- <ulink url="../ext/howto.html#3">more information on allocators here</ulink>.
+ <para>The library implementation may be configured to use the
+ high-speed caching memory allocator, which complicates thread
+ safety issues. For all details about how to globally override
+ this at application run-time
+ see <link linkend="manual.intro.using.macros">here</link>. Also
+ useful are details
+ on <link linkend="std.util.memory.allocator">allocator</link>
+ options and capabilities.
</para>
- </sect2>
- </sect1>
-
- <sect1 id="manual.intro.using.exception" xreflabel="Exceptions">
- <title>Exceptions</title>
+ </section>
+</section>
- <sect2 id="intro.using.exception.propagating" xreflabel="Propagating Exceptions">
-
- <title>Propagating Exceptions aka Exception Neutrality</title>
- <para>
- </para>
- </sect2>
-
- <sect2 id="intro.using.exception.safety" xreflabel="Exception Safety">
- <title>Exception Safety</title>
- <para>
- </para>
- </sect2>
-
- <sect2 id="intro.using.exception.no" xreflabel="-fno-exceptions">
- <title>Support for <literal>-fno-exceptions</literal></title>
- <para>
- </para>
- </sect2>
-
- </sect1>
+<!-- Section 0x : Exception policies, expectations, topics -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="using_exceptions.xml">
+</xi:include>
<!-- Section 0x : Debug -->
-<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
- parse="xml" href="debug.xml">
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="debug.xml">
</xi:include>
</chapter>