3b2b3556c1
* doc/xml/faq.xml: Update outdated allocator documentation. * doc/xml/manual/allocator.xml: Likewise. * doc/xml/manual/debug.xml: Likewise. * doc/xml/manual/evolution.xml: Likewise. * doc/xml/manual/using.xml: Likewise. From-SVN: r187068
1599 lines
59 KiB
XML
1599 lines
59 KiB
XML
<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>
|
|
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>
|
|
By default, <command>g++</command> is equivalent to <command>g++ -std=gnu++98</command>. The standard library also defaults to this dialect.
|
|
</para>
|
|
|
|
<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++11</literal></entry>
|
|
<entry>Use the 2011 ISO C++ standard.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><literal>-std=gnu++11</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++11 <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>
|
|
|
|
</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
|
|
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
|
|
how.
|
|
</para>
|
|
|
|
<para>
|
|
That said, in practice files are used.
|
|
</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).
|
|
</para>
|
|
|
|
<para>
|
|
Two dialects of standard headers are supported, corresponding to
|
|
the 1998 standard as updated for 2003, and the current 2011 standard.
|
|
</para>
|
|
|
|
<para>
|
|
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">
|
|
<title>C++ 1998 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">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/>
|
|
<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 colname="c2"/>
|
|
<colspec colname="c3"/>
|
|
<colspec colname="c4"/>
|
|
<colspec colname="c5"/>
|
|
<tbody>
|
|
<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++11 include files. These are only available in C++11 compilation
|
|
mode, i.e. <literal>-std=c++11</literal> or <literal>-std=gnu++11</literal>.
|
|
</para>
|
|
|
|
<para/>
|
|
<table frame="all">
|
|
<title>C++ 2011 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">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/>
|
|
|
|
<table frame="all">
|
|
<title>C++ 2011 Library Headers for C Library Facilities</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">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>
|
|
|
|
|
|
<para>
|
|
In addition, TR1 includes as:
|
|
</para>
|
|
|
|
<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/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/>
|
|
|
|
|
|
<table frame="all">
|
|
<title>C++ TR 1 Library Headers for C Library Facilities</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/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>
|
|
|
|
<para>
|
|
Also included are files for the C++ ABI interface:
|
|
</para>
|
|
|
|
<table frame="all">
|
|
<title>C++ ABI Headers</title>
|
|
|
|
<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>
|
|
</tgroup>
|
|
</table>
|
|
|
|
<para>
|
|
And a large variety of extensions.
|
|
</para>
|
|
|
|
<table frame="all">
|
|
<title>Extension 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">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/>
|
|
|
|
<table frame="all">
|
|
<title>Extension Debug 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">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/>
|
|
|
|
<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>
|
|
|
|
<para/>
|
|
|
|
<table frame="all">
|
|
<title>Extension Parallel Headers</title>
|
|
|
|
<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>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
</section>
|
|
|
|
<section xml:id="manual.intro.using.headers.mixing" xreflabel="Mixing Headers"><info><title>Mixing Headers</title></info>
|
|
|
|
|
|
<para> A few simple rules.
|
|
</para>
|
|
|
|
<para>First, mixing different dialects of the standard headers is not
|
|
possible. It's an all-or-nothing affair. Thus, code like
|
|
</para>
|
|
|
|
<programlisting>
|
|
#include <array>
|
|
#include <functional>
|
|
</programlisting>
|
|
|
|
<para>Implies C++11 mode. To use the entities in <array>, the C++11
|
|
compilation mode must be used, which implies the C++11 functionality
|
|
(and deprecations) in <functional> will be present.
|
|
</para>
|
|
|
|
<para>Second, the other headers can be included with either dialect of
|
|
the standard headers, although features and types specific to C++11
|
|
are still only enabled when in C++11 compilation mode. So, to use
|
|
rvalue references with <code>__gnu_cxx::vstring</code>, or to use the
|
|
debug-mode versions of <code>std::unordered_map</code>, one must use
|
|
the <code>std=gnu++11</code> compiler flag. (Or <code>std=c++11</code>, of course.)
|
|
</para>
|
|
|
|
<para>A special case of the second rule is the mixing of TR1 and C++11
|
|
facilities. It is possible (although not especially prudent) to
|
|
include both the TR1 version and the C++11 version of header in the
|
|
same translation unit:
|
|
</para>
|
|
|
|
<programlisting>
|
|
#include <tr1/type_traits>
|
|
#include <type_traits>
|
|
</programlisting>
|
|
|
|
<para> Several parts of C++11 diverge quite substantially from TR1 predecessors.
|
|
</para>
|
|
</section>
|
|
|
|
<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.) 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>
|
|
|
|
<para>
|
|
Usage of C++-style headers is recommended, as then
|
|
C-linkage names can be disambiguated by explicit qualification, such
|
|
as by <code>std::abort</code>. In addition, the C++-style headers can
|
|
use function overloading to provide a simpler interface to certain
|
|
families of C-functions. For instance in <cmath>, the
|
|
function <code>std::sin</code> has overloads for all the builtin
|
|
floating-point types. This means that <code>std::sin</code> can be
|
|
used uniformly, instead of a combination
|
|
of <code>std::sinf</code>, <code>std::sin</code>,
|
|
and <code>std::sinl</code>.
|
|
</para>
|
|
</section>
|
|
|
|
<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
|
|
used to precompile the standard headers and extensions into binary
|
|
files that may the be used to speed compiles that use these headers.
|
|
</para>
|
|
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>stdc++.h</para>
|
|
<para>Includes all standard headers. Actual content varies depending on
|
|
language dialect.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>stdtr1c++.h</para>
|
|
<para>Includes all of <stdc++.h>, and adds all the TR1 headers.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem><para>extc++.h</para>
|
|
<para>Includes all of <stdtr1c++.h>, and adds all the Extension headers.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
|
|
<para>How to construct a .gch file from one of these base header files.</para>
|
|
|
|
<para>First, find the include directory for the compiler. One way to do
|
|
this is:</para>
|
|
|
|
<programlisting>
|
|
g++ -v hello.cc
|
|
|
|
#include <...> search starts here:
|
|
/mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0
|
|
...
|
|
End of search list.
|
|
</programlisting>
|
|
|
|
|
|
<para>Then, create a precompiled header file with the same flags that
|
|
will be used to compile other projects.</para>
|
|
|
|
<programlisting>
|
|
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
|
|
</programlisting>
|
|
|
|
<para>The resulting file will be quite large: the current size is around
|
|
thirty megabytes. </para>
|
|
|
|
<para>How to use the resulting file.</para>
|
|
|
|
<programlisting>
|
|
g++ -I. -include stdc++.h -H -g -O2 hello.cc
|
|
</programlisting>
|
|
|
|
<para>Verification that the PCH file is being used is easy:</para>
|
|
|
|
<programlisting>
|
|
g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe
|
|
! ./stdc++.h.gch
|
|
. /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0/iostream
|
|
. /mnt/share/bld/H-x86-gcc.20071201include/c++/4.3.0/string
|
|
</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> 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++11</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_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>
|
|
|
|
</section>
|
|
|
|
<section xml:id="manual.intro.using.namespaces" xreflabel="Namespaces"><info><title>Namespaces</title></info>
|
|
<?dbhtml filename="using_namespaces.html"?>
|
|
|
|
|
|
<section xml:id="manual.intro.using.namespaces.all" xreflabel="Available Namespaces"><info><title>Available Namespaces</title></info>
|
|
|
|
|
|
|
|
|
|
<para> There are three main namespaces.
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><para>std</para>
|
|
<para>The ISO C++ standards specify that "all library entities are defined
|
|
within namespace std." This includes namespaces nested
|
|
within <code>namespace std</code>, such as <code>namespace
|
|
std::tr1</code>.
|
|
</para>
|
|
</listitem>
|
|
<listitem><para>abi</para>
|
|
<para>Specified by the C++ ABI. This ABI specifies a number of type and
|
|
function APIs supplemental to those required by the ISO C++ Standard,
|
|
but necessary for interoperability.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem><para>__gnu_</para>
|
|
<para>Indicating one of several GNU extensions. Choices
|
|
include <code>__gnu_cxx</code>, <code>__gnu_debug</code>, <code>__gnu_parallel</code>,
|
|
and <code>__gnu_pbds</code>.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
|
|
<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>
|
|
|
|
|
|
</section>
|
|
|
|
<section xml:id="manual.intro.using.namespaces.std" xreflabel="namespace std"><info><title>namespace std</title></info>
|
|
|
|
|
|
|
|
<para>
|
|
One standard requirement is that the library components are defined
|
|
in <code>namespace std::</code>. Thus, in order to use these types or
|
|
functions, one must do one of two things:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><para>put a kind of <emphasis>using-declaration</emphasis> in your source
|
|
(either <code>using namespace std;</code> or i.e. <code>using
|
|
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
|
|
(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.)
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
</section>
|
|
|
|
<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
|
|
functionality in a sanely-named, unique namespace whenever
|
|
possible. This is considered an advantage over dumping everything in
|
|
the global namespace, as then name look-up can be explicitly enabled or
|
|
disabled as above, symbols are consistently mangled without repetitive
|
|
naming prefixes or macros, etc.
|
|
</para>
|
|
|
|
<para>For instance, consider a project that defines most of its classes in <code>namespace gtk</code>. It is possible to
|
|
adapt <code>namespace gtk</code> to <code>namespace std</code> by using a C++-feature called
|
|
<emphasis>namespace composition</emphasis>. This is what happens if
|
|
a <emphasis>using</emphasis>-declaration is put into a
|
|
namespace-definition: the imported symbol(s) gets imported into the
|
|
currently active namespace(s). For example:
|
|
</para>
|
|
<programlisting>
|
|
namespace gtk
|
|
{
|
|
using std::string;
|
|
using std::tr1::array;
|
|
|
|
class Window { ... };
|
|
}
|
|
</programlisting>
|
|
<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> 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
|
|
std::string;</code> (depending on whether the system has
|
|
libstdc++ in <code>std::</code> or not). (ideas from
|
|
Llewelly and Karl Nelson)
|
|
</para>
|
|
|
|
|
|
</section>
|
|
</section>
|
|
|
|
<section xml:id="manual.intro.using.linkage" xreflabel="Linkage"><info><title>Linking</title></info>
|
|
<?dbhtml filename="using_dynamic_or_shared.html"?>
|
|
|
|
|
|
<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>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<filename class="headerfile">cstdarg</filename>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<filename class="headerfile">cstddef</filename>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<filename class="headerfile">cstdlib</filename>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<filename class="headerfile">exception</filename>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<filename class="headerfile">limits</filename>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<filename class="headerfile">new</filename>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<filename class="headerfile">exception</filename>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<filename class="headerfile">typeinfo</filename>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
In addition, throw in
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<filename class="headerfile">cxxabi.h</filename>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
In the
|
|
C++11 <link linkend="manual.intro.using.flags">dialect</link> add
|
|
</para>
|
|
|
|
<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>
|
|
|
|
<para>
|
|
<command>gcc foo.cc -lsupc++</command>
|
|
</para>
|
|
|
|
<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>
|
|
</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 GNU/Linux):
|
|
<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 GNU/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>
|
|
|
|
|
|
<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++
|
|
library. This information is GCC-specific since the C++
|
|
standard does not address matters of multithreaded applications.
|
|
</para>
|
|
|
|
<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
|
|
compilers which report (via <code> gcc/g++ -v </code>) the same thread
|
|
model and that model is not <emphasis>single</emphasis>. As long as your
|
|
final application is actually single-threaded, then it should be
|
|
safe to mix user code built with a thread model of
|
|
<emphasis>single</emphasis> with a libstdc++ and other C++ libraries built
|
|
with another thread model useful on the platform. Other mixes
|
|
may or may not work but are not considered supported. (Thus, if
|
|
you distribute a shared C++ library in binary form only, it may
|
|
be best to compile it with a GCC configured with
|
|
--enable-threads for maximal interchangeability and usefulness
|
|
with a user population that may have built GCC with either
|
|
--enable-threads or --disable-threads.)
|
|
</para>
|
|
<para>When you link a multithreaded application, you will probably
|
|
need to add a library or flag to g++. This is a very
|
|
non-standardized area of GCC across ports. Some ports support a
|
|
special flag (the spelling isn't even standardized yet) to add
|
|
all required macros to a compilation (if any such flags are
|
|
required then you must provide the flag for all compilations not
|
|
just linking) and link-library additions and/or replacements at
|
|
link time. The documentation is weak. Here is a quick summary
|
|
to display how ad hoc this is: On Solaris, both -pthreads and
|
|
-threads (with subtly different meanings) are honored.
|
|
On GNU/Linux x86, -pthread is honored. On FreeBSD,
|
|
-pthread is honored. Some other ports use other switches.
|
|
AFAIK, none of this is properly documented anywhere other than
|
|
in ``gcc -dumpspecs'' (look at lib and cpp entries).
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section xml:id="manual.intro.using.concurrency.thread_safety" xreflabel="Thread Safety"><info><title>Thread Safety</title></info>
|
|
|
|
|
|
<para>
|
|
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:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>The system's libc is itself thread-safe,
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The compiler in use reports a thread model other than
|
|
'single'. This can be tested via output from <code>gcc
|
|
-v</code>. Multi-thread capable versions of gcc output
|
|
something like this:
|
|
</para>
|
|
<programlisting>
|
|
%gcc -v
|
|
Using built-in specs.
|
|
...
|
|
Thread model: posix
|
|
gcc version 4.1.2 20070925 (Red Hat 4.1.2-33)
|
|
</programlisting>
|
|
|
|
<para>Look for "Thread model" lines that aren't equal to "single."</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
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 <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 <link linkend="internals.thread_safety">details</link>.
|
|
</para>
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
<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;
|
|
|
|
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 does not require any
|
|
user-level locks:
|
|
</para>
|
|
<programlisting>
|
|
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 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>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>
|
|
|
|
</section>
|
|
<section xml:id="manual.intro.using.concurrency.atomics" xreflabel="Atomics"><info><title>Atomics</title></info>
|
|
|
|
<para>
|
|
</para>
|
|
</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>
|
|
|
|
<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
|
|
with actual input and output must be made in <code>__basic_file</code>.
|
|
</para>
|
|
<para>A generic locking mechanism is somewhat in place at the filebuf layer,
|
|
but is not used in the current code. Providing locking at any higher
|
|
level is akin to providing locking within containers, and is not done
|
|
for the same reasons (see the links above).
|
|
</para>
|
|
</section>
|
|
|
|
<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
|
|
implementations of the C library with varying tradeoffs of threadsafety
|
|
and efficiency. You, the programmer, are always required to take care
|
|
with multiple threads.
|
|
</para>
|
|
<para>(As an example, the POSIX standard requires that C stdio FILE*
|
|
operations are atomic. POSIX-conforming C libraries (e.g, on Solaris
|
|
and GNU/Linux) have an internal mutex to serialize operations on
|
|
FILE*s. However, you still need to not do stupid things like calling
|
|
<code>fclose(fs)</code> in one thread followed by an access of
|
|
<code>fs</code> in another.)
|
|
</para>
|
|
<para>So, if your platform's C library is threadsafe, then your
|
|
<code>fstream</code> I/O operations will be threadsafe at the lowest
|
|
level. For higher-level operations, such as manipulating the data
|
|
contained in the stream formatting classes (e.g., setting up callbacks
|
|
inside an <code>std::ofstream</code>), you need to guard such accesses
|
|
like any other critical shared resource.
|
|
</para>
|
|
</section>
|
|
|
|
<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
|
|
issues. It will be revisited, however.
|
|
</para>
|
|
<para>The libio code is a subset of the guts of the GNU libc (glibc) I/O
|
|
implementation. When libio is in use, the <code>__basic_file</code>
|
|
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
|
|
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
|
|
replaced by a jump into an internal function. Fast but frightening.
|
|
*grin*)
|
|
</para>
|
|
<para>Also, the libio internal locks are used. This requires pulling in
|
|
large chunks of glibc, such as a pthreads implementation, and is one
|
|
of the issues preventing widespread use of libio as the libstdc++
|
|
cstdio implementation.
|
|
</para>
|
|
<para>But we plan to make this work, at least as an option if not a future
|
|
default. Platforms running a copy of glibc with a recent-enough
|
|
version will see calls from libstdc++ directly into the glibc already
|
|
installed. For other platforms, a copy of the libio subsection will
|
|
be built and included in libstdc++.
|
|
</para>
|
|
</section>
|
|
|
|
<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.
|
|
</para>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<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.
|
|
All information in this section is current as of the gcc 3.0
|
|
release and all later point releases. Although earlier gcc
|
|
releases had a different approach to threading configuration and
|
|
proper compilation, the basic code design rules presented here
|
|
were similar. For information on all other aspects of
|
|
multithreading as it relates to libstdc++, including details on
|
|
the proper compilation of threaded code (and compatibility between
|
|
threaded and non-threaded code), see Chapter 17.
|
|
</para>
|
|
<para>Two excellent pages to read when working with the Standard C++
|
|
containers and threads are
|
|
<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
|
|
container-memory allocator on those pages. For the sake of this
|
|
discussion, libstdc++ configures the SGI STL implementation,
|
|
not you. This is quite different from how gcc pre-3.0 worked.
|
|
In particular, past advice was for people using g++ to
|
|
explicitly define _PTHREADS or other macros or port-specific
|
|
compilation options on the command line to get a thread-safe
|
|
STL. This is no longer required for any port and should no
|
|
longer be done unless you really know what you are doing and
|
|
assume all responsibility.</emphasis>
|
|
</para>
|
|
<para>Since the container implementation of libstdc++ uses the SGI
|
|
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
|
|
(<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
|
|
element is constructed uses an internal lock obtained and
|
|
released solely within libstdc++ code (in fact, this is the
|
|
reason STL requires any knowledge of the thread configuration).
|
|
</para>
|
|
<para>For implementing a container which does its own locking, it is
|
|
trivial to provide a wrapper class which obtains the lock (as
|
|
SGI suggests), performs the container operation, and then
|
|
releases the lock. This could be templatized <emphasis>to a certain
|
|
extent</emphasis>, on the underlying container and/or a locking
|
|
mechanism. Trying to provide a catch-all general template
|
|
solution would probably be more trouble than it's worth.
|
|
</para>
|
|
<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>
|
|
|
|
</section>
|
|
</section>
|
|
|
|
<!-- 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>
|
|
|
|
</chapter>
|