diff options
| author | upstream source tree <ports@midipix.org> | 2015-03-15 20:14:05 -0400 |
|---|---|---|
| committer | upstream source tree <ports@midipix.org> | 2015-03-15 20:14:05 -0400 |
| commit | 554fd8c5195424bdbcabf5de30fdc183aba391bd (patch) | |
| tree | 976dc5ab7fddf506dadce60ae936f43f58787092 /libstdc++-v3/doc/xml/manual/using.xml | |
| download | cbb-gcc-4.6.4-554fd8c5195424bdbcabf5de30fdc183aba391bd.tar.bz2 cbb-gcc-4.6.4-554fd8c5195424bdbcabf5de30fdc183aba391bd.tar.xz | |
obtained gcc-4.6.4.tar.bz2 from upstream website;upstream
verified gcc-4.6.4.tar.bz2.sig;
imported gcc-4.6.4 source tree from verified upstream tarball.
downloading a git-generated archive based on the 'upstream' tag
should provide you with a source tree that is binary identical
to the one extracted from the above tarball.
if you have obtained the source via the command 'git clone',
however, do note that line-endings of files in your working
directory might differ from line-endings of the respective
files in the upstream repository.
Diffstat (limited to 'libstdc++-v3/doc/xml/manual/using.xml')
| -rw-r--r-- | libstdc++-v3/doc/xml/manual/using.xml | 1543 |
1 files changed, 1543 insertions, 0 deletions
diff --git a/libstdc++-v3/doc/xml/manual/using.xml b/libstdc++-v3/doc/xml/manual/using.xml new file mode 100644 index 000000000..02498e21c --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/using.xml @@ -0,0 +1,1543 @@ +<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++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> + +</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 draft of the + upcoming 200x 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++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/> +<table frame="all"> +<title>C++ 200x 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++ 200x 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++0x mode. To use the entities in <array>, the C++0x +compilation mode must be used, which implies the C++0x 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++0x +are still only enabled when in C++0x 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++0x</code> compiler flag. (Or <code>std=c++0x</code>, of course.) +</para> + +<para>A special case of the second rule is the mixing of TR1 and C++0x +facilities. It is possible (although not especially prudent) to +include both the TR1 version and the C++0x version of header in the +same translation unit: +</para> + +<programlisting> +#include <tr1/type_traits> +#include <type_traits> +</programlisting> + +<para> Several parts of C++0x 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++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> + + </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++0x <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 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> + + + <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 OSF, + -pthread and -threads (with subtly different meanings) are + honored. On Linux/i386, -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> +We currently use 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. +</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 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> + <programlisting> + library_class_a shared_object_a; + + 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: + </para> + <programlisting> + 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> + + + </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> |