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/html/manual | |
| download | cbb-gcc-4.6.4-upstream.tar.bz2 cbb-gcc-4.6.4-upstream.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/html/manual')
92 files changed, 15700 insertions, 0 deletions
diff --git a/libstdc++-v3/doc/html/manual/abi.html b/libstdc++-v3/doc/html/manual/abi.html new file mode 100644 index 000000000..dc4bf5a75 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/abi.html @@ -0,0 +1,522 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>ABI Policy and Guidelines</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" C++ , ABI , version , dynamic , shared , compatibility "/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="appendix_porting.html" title="Appendix B. Porting and Maintenance"/><link rel="prev" href="test.html" title="Test"/><link rel="next" href="api.html" title="API Evolution and Deprecation History"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">ABI Policy and Guidelines</th></tr><tr><td align="left"><a accesskey="p" href="test.html">Prev</a> </td><th width="60%" align="center">Appendix B. + Porting and Maintenance + +</th><td align="right"> <a accesskey="n" href="api.html">Next</a></td></tr></table><hr/></div><div class="section" title="ABI Policy and Guidelines"><div class="titlepage"><div><div><h2 class="title"><a id="appendix.porting.abi"/>ABI Policy and Guidelines</h2></div></div></div><p> +</p><div class="section" title="The C++ Interface"><div class="titlepage"><div><div><h3 class="title"><a id="abi.cxx_interface"/>The C++ Interface</h3></div></div></div><p> + C++ applications often depend on specific language support + routines, say for throwing exceptions, or catching exceptions, and + perhaps also depend on features in the C++ Standard Library. +</p><p> + The C++ Standard Library has many include files, types defined in + those include files, specific named functions, and other + behavior. The text of these behaviors, as written in source include + files, is called the Application Programing Interface, or API. +</p><p> + Furthermore, C++ source that is compiled into object files is + transformed by the compiler: it arranges objects with specific + alignment and in a particular layout, mangling names according to a + well-defined algorithm, has specific arrangements for the support of + virtual functions, etc. These details are defined as the compiler + Application Binary Interface, or ABI. The GNU C++ compiler uses an + industry-standard C++ ABI starting with version 3. Details can be + found in the <a class="link" href="http://www.codesourcery.com/public/cxx-abi/abi.html">ABI + specification</a>. +</p><p> + The GNU C++ compiler, g++, has a compiler command line option to + switch between various different C++ ABIs. This explicit version + switch is the flag <code class="code">-fabi-version</code>. In addition, some + g++ command line options may change the ABI as a side-effect of + use. Such flags include <code class="code">-fpack-struct</code> and + <code class="code">-fno-exceptions</code>, but include others: see the complete + list in the GCC manual under the heading <a class="link" href="http://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html#Code%20Gen%20Options">Options + for Code Generation Conventions</a>. +</p><p> + The configure options used when building a specific libstdc++ + version may also impact the resulting library ABI. The available + configure options, and their impact on the library ABI, are + documented +<a class="link" href="configure.html" title="Configure">here</a>. +</p><p> Putting all of these ideas together results in the C++ Standard +library ABI, which is the compilation of a given library API by a +given compiler ABI. In a nutshell: +</p><p> + <span class="quote">“<span class="quote"> + library API + compiler ABI = library ABI + </span>”</span> +</p><p> + The library ABI is mostly of interest for end-users who have + unresolved symbols and are linking dynamically to the C++ Standard + library, and who thus must be careful to compile their application + with a compiler that is compatible with the available C++ Standard + library binary. In this case, compatible is defined with the equation + above: given an application compiled with a given compiler ABI and + library API, it will work correctly with a Standard C++ Library + created with the same constraints. +</p><p> + To use a specific version of the C++ ABI, one must use a + corresponding GNU C++ toolchain (i.e., g++ and libstdc++) that + implements the C++ ABI in question. +</p></div><div class="section" title="Versioning"><div class="titlepage"><div><div><h3 class="title"><a id="abi.versioning"/>Versioning</h3></div></div></div><p> The C++ interface has evolved throughout the history of the GNU +C++ toolchain. With each release, various details have been changed so +as to give distinct versions to the C++ interface. +</p><div class="section" title="Goals"><div class="titlepage"><div><div><h4 class="title"><a id="abi.versioning.goals"/>Goals</h4></div></div></div><p>Extending existing, stable ABIs. Versioning gives subsequent +releases of library binaries the ability to add new symbols and add +functionality, all the while retaining compatibility with the previous +releases in the series. Thus, program binaries linked with the initial +release of a library binary will still run correctly if the library +binary is replaced by carefully-managed subsequent library +binaries. This is called forward compatibility. +</p><p> +The reverse (backwards compatibility) is not true. It is not possible +to take program binaries linked with the latest version of a library +binary in a release series (with additional symbols added), substitute +in the initial release of the library binary, and remain link +compatible. +</p><p>Allows multiple, incompatible ABIs to coexist at the same time. +</p></div><div class="section" title="History"><div class="titlepage"><div><div><h4 class="title"><a id="abi.versioning.history"/>History</h4></div></div></div><p> + How can this complexity be managed? What does C++ versioning mean? + Because library and compiler changes often make binaries compiled + with one version of the GNU tools incompatible with binaries + compiled with other (either newer or older) versions of the same GNU + tools, specific techniques are used to make managing this complexity + easier. +</p><p> + The following techniques are used: +</p><div class="orderedlist"><ol class="orderedlist"><li class="listitem"><p>Release versioning on the libgcc_s.so binary. </p><p>This is implemented via file names and the ELF + <code class="constant">DT_SONAME</code> mechanism (at least on ELF + systems). It is versioned as follows: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>gcc-3.0.0: libgcc_s.so.1</p></li><li class="listitem"><p>gcc-3.0.1: libgcc_s.so.1</p></li><li class="listitem"><p>gcc-3.0.2: libgcc_s.so.1</p></li><li class="listitem"><p>gcc-3.0.3: libgcc_s.so.1</p></li><li class="listitem"><p>gcc-3.0.4: libgcc_s.so.1</p></li><li class="listitem"><p>gcc-3.1.0: libgcc_s.so.1</p></li><li class="listitem"><p>gcc-3.1.1: libgcc_s.so.1</p></li><li class="listitem"><p>gcc-3.2.0: libgcc_s.so.1</p></li><li class="listitem"><p>gcc-3.2.1: libgcc_s.so.1</p></li><li class="listitem"><p>gcc-3.2.2: libgcc_s.so.1</p></li><li class="listitem"><p>gcc-3.2.3: libgcc_s.so.1</p></li><li class="listitem"><p>gcc-3.3.0: libgcc_s.so.1</p></li><li class="listitem"><p>gcc-3.3.1: libgcc_s.so.1</p></li><li class="listitem"><p>gcc-3.3.2: libgcc_s.so.1</p></li><li class="listitem"><p>gcc-3.3.3: libgcc_s.so.1</p></li><li class="listitem"><p>gcc-3.4.x, gcc-4.[0-5].x: libgcc_s.so.1</p></li></ul></div><p>For m68k-linux the versions differ as follows: </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>gcc-3.4.x, gcc-4.[0-5].x: libgcc_s.so.1 + when configuring <code class="code">--with-sjlj-exceptions</code>, or + libgcc_s.so.2 </p></li></ul></div><p>For hppa-linux the versions differ as follows: </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>gcc-3.4.x, gcc-4.[0-1].x: either libgcc_s.so.1 + when configuring <code class="code">--with-sjlj-exceptions</code>, or + libgcc_s.so.2 </p></li><li class="listitem"><p>gcc-4.[2-5].x: either libgcc_s.so.3 when configuring + <code class="code">--with-sjlj-exceptions</code>) or libgcc_s.so.4 + </p></li></ul></div></li><li class="listitem"><p>Symbol versioning on the libgcc_s.so binary.</p><p>It is versioned with the following labels and version + definitions, where the version definition is the maximum for a + particular release. Labels are cumulative. If a particular release + is not listed, it has the same version labels as the preceding + release.</p><p>This corresponds to the mapfile: gcc/libgcc-std.ver</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>gcc-3.0.0: GCC_3.0</p></li><li class="listitem"><p>gcc-3.3.0: GCC_3.3</p></li><li class="listitem"><p>gcc-3.3.1: GCC_3.3.1</p></li><li class="listitem"><p>gcc-3.3.2: GCC_3.3.2</p></li><li class="listitem"><p>gcc-3.3.4: GCC_3.3.4</p></li><li class="listitem"><p>gcc-3.4.0: GCC_3.4</p></li><li class="listitem"><p>gcc-3.4.2: GCC_3.4.2</p></li><li class="listitem"><p>gcc-3.4.4: GCC_3.4.4</p></li><li class="listitem"><p>gcc-4.0.0: GCC_4.0.0</p></li><li class="listitem"><p>gcc-4.1.0: GCC_4.1.0</p></li><li class="listitem"><p>gcc-4.2.0: GCC_4.2.0</p></li><li class="listitem"><p>gcc-4.3.0: GCC_4.3.0</p></li><li class="listitem"><p>gcc-4.4.0: GCC_4.4.0</p></li></ul></div></li><li class="listitem"><p> + Release versioning on the libstdc++.so binary, implemented in + the same way as the libgcc_s.so binary above. Listed is the + filename: <code class="constant">DT_SONAME</code> can be deduced from + the filename by removing the last two period-delimited numbers. For + example, filename <code class="filename">libstdc++.so.5.0.4</code> + corresponds to a <code class="constant">DT_SONAME</code> of + <code class="constant">libstdc++.so.5</code>. Binaries with equivalent + <code class="constant">DT_SONAME</code>s are forward-compatibile: in + the table below, releases incompatible with the previous + one are explicitly noted. + </p><p>It is versioned as follows: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>gcc-3.0.0: libstdc++.so.3.0.0</p></li><li class="listitem"><p>gcc-3.0.1: libstdc++.so.3.0.1</p></li><li class="listitem"><p>gcc-3.0.2: libstdc++.so.3.0.2</p></li><li class="listitem"><p>gcc-3.0.3: libstdc++.so.3.0.2 (See Note 1)</p></li><li class="listitem"><p>gcc-3.0.4: libstdc++.so.3.0.4</p></li><li class="listitem"><p>gcc-3.1.0: libstdc++.so.4.0.0 <span class="emphasis"><em>(Incompatible with previous)</em></span></p></li><li class="listitem"><p>gcc-3.1.1: libstdc++.so.4.0.1</p></li><li class="listitem"><p>gcc-3.2.0: libstdc++.so.5.0.0 <span class="emphasis"><em>(Incompatible with previous)</em></span></p></li><li class="listitem"><p>gcc-3.2.1: libstdc++.so.5.0.1</p></li><li class="listitem"><p>gcc-3.2.2: libstdc++.so.5.0.2</p></li><li class="listitem"><p>gcc-3.2.3: libstdc++.so.5.0.3 (See Note 2)</p></li><li class="listitem"><p>gcc-3.3.0: libstdc++.so.5.0.4</p></li><li class="listitem"><p>gcc-3.3.1: libstdc++.so.5.0.5</p></li><li class="listitem"><p>gcc-3.3.2: libstdc++.so.5.0.5</p></li><li class="listitem"><p>gcc-3.3.3: libstdc++.so.5.0.5</p></li><li class="listitem"><p>gcc-3.4.0: libstdc++.so.6.0.0 <span class="emphasis"><em>(Incompatible with previous)</em></span></p></li><li class="listitem"><p>gcc-3.4.1: libstdc++.so.6.0.1</p></li><li class="listitem"><p>gcc-3.4.2: libstdc++.so.6.0.2</p></li><li class="listitem"><p>gcc-3.4.3: libstdc++.so.6.0.3</p></li><li class="listitem"><p>gcc-3.4.4: libstdc++.so.6.0.3</p></li><li class="listitem"><p>gcc-3.4.5: libstdc++.so.6.0.3</p></li><li class="listitem"><p>gcc-3.4.6: libstdc++.so.6.0.3</p></li><li class="listitem"><p>gcc-4.0.0: libstdc++.so.6.0.4</p></li><li class="listitem"><p>gcc-4.0.1: libstdc++.so.6.0.5</p></li><li class="listitem"><p>gcc-4.0.2: libstdc++.so.6.0.6</p></li><li class="listitem"><p>gcc-4.0.3: libstdc++.so.6.0.7</p></li><li class="listitem"><p>gcc-4.1.0: libstdc++.so.6.0.7</p></li><li class="listitem"><p>gcc-4.1.1: libstdc++.so.6.0.8</p></li><li class="listitem"><p>gcc-4.1.2: libstdc++.so.6.0.8</p></li><li class="listitem"><p>gcc-4.2.0: libstdc++.so.6.0.9</p></li><li class="listitem"><p>gcc-4.2.1: libstdc++.so.6.0.9 (See Note 3)</p></li><li class="listitem"><p>gcc-4.2.2: libstdc++.so.6.0.9</p></li><li class="listitem"><p>gcc-4.2.3: libstdc++.so.6.0.9</p></li><li class="listitem"><p>gcc-4.2.4: libstdc++.so.6.0.9</p></li><li class="listitem"><p>gcc-4.3.0: libstdc++.so.6.0.10</p></li><li class="listitem"><p>gcc-4.3.1: libstdc++.so.6.0.10</p></li><li class="listitem"><p>gcc-4.3.2: libstdc++.so.6.0.10</p></li><li class="listitem"><p>gcc-4.3.3: libstdc++.so.6.0.10</p></li><li class="listitem"><p>gcc-4.3.4: libstdc++.so.6.0.10</p></li><li class="listitem"><p>gcc-4.4.0: libstdc++.so.6.0.11</p></li><li class="listitem"><p>gcc-4.4.1: libstdc++.so.6.0.12</p></li><li class="listitem"><p>gcc-4.4.2: libstdc++.so.6.0.13</p></li><li class="listitem"><p>gcc-4.5.0: libstdc++.so.6.0.14</p></li></ul></div><p> + Note 1: Error should be libstdc++.so.3.0.3. + </p><p> + Note 2: Not strictly required. + </p><p> + Note 3: This release (but not previous or subsequent) has one + known incompatibility, see <a class="link" href="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=33678">33678</a> + in the GCC bug database. + </p></li><li class="listitem"><p>Symbol versioning on the libstdc++.so binary.</p><p>mapfile: libstdc++-v3/config/abi/pre/gnu.ver</p><p>It is versioned with the following labels and version + definitions, where the version definition is the maximum for a + particular release. Note, only symbols which are newly introduced + will use the maximum version definition. Thus, for release series + with the same label, but incremented version definitions, the later + release has both versions. (An example of this would be the + gcc-3.2.1 release, which has GLIBCPP_3.2.1 for new symbols and + GLIBCPP_3.2 for symbols that were introduced in the gcc-3.2.0 + release.) If a particular release is not listed, it has the same + version labels as the preceding release. + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>gcc-3.0.0: (Error, not versioned)</p></li><li class="listitem"><p>gcc-3.0.1: (Error, not versioned)</p></li><li class="listitem"><p>gcc-3.0.2: (Error, not versioned)</p></li><li class="listitem"><p>gcc-3.0.3: (Error, not versioned)</p></li><li class="listitem"><p>gcc-3.0.4: (Error, not versioned)</p></li><li class="listitem"><p>gcc-3.1.0: GLIBCPP_3.1, CXXABI_1</p></li><li class="listitem"><p>gcc-3.1.1: GLIBCPP_3.1, CXXABI_1</p></li><li class="listitem"><p>gcc-3.2.0: GLIBCPP_3.2, CXXABI_1.2</p></li><li class="listitem"><p>gcc-3.2.1: GLIBCPP_3.2.1, CXXABI_1.2</p></li><li class="listitem"><p>gcc-3.2.2: GLIBCPP_3.2.2, CXXABI_1.2</p></li><li class="listitem"><p>gcc-3.2.3: GLIBCPP_3.2.2, CXXABI_1.2</p></li><li class="listitem"><p>gcc-3.3.0: GLIBCPP_3.2.2, CXXABI_1.2.1</p></li><li class="listitem"><p>gcc-3.3.1: GLIBCPP_3.2.3, CXXABI_1.2.1</p></li><li class="listitem"><p>gcc-3.3.2: GLIBCPP_3.2.3, CXXABI_1.2.1</p></li><li class="listitem"><p>gcc-3.3.3: GLIBCPP_3.2.3, CXXABI_1.2.1</p></li><li class="listitem"><p>gcc-3.4.0: GLIBCXX_3.4, CXXABI_1.3</p></li><li class="listitem"><p>gcc-3.4.1: GLIBCXX_3.4.1, CXXABI_1.3</p></li><li class="listitem"><p>gcc-3.4.2: GLIBCXX_3.4.2</p></li><li class="listitem"><p>gcc-3.4.3: GLIBCXX_3.4.3</p></li><li class="listitem"><p>gcc-4.0.0: GLIBCXX_3.4.4, CXXABI_1.3.1</p></li><li class="listitem"><p>gcc-4.0.1: GLIBCXX_3.4.5</p></li><li class="listitem"><p>gcc-4.0.2: GLIBCXX_3.4.6</p></li><li class="listitem"><p>gcc-4.0.3: GLIBCXX_3.4.7</p></li><li class="listitem"><p>gcc-4.1.1: GLIBCXX_3.4.8</p></li><li class="listitem"><p>gcc-4.2.0: GLIBCXX_3.4.9</p></li><li class="listitem"><p>gcc-4.3.0: GLIBCXX_3.4.10, CXXABI_1.3.2</p></li><li class="listitem"><p>gcc-4.4.0: GLIBCXX_3.4.11, CXXABI_1.3.3</p></li><li class="listitem"><p>gcc-4.4.1: GLIBCXX_3.4.12, CXXABI_1.3.3</p></li><li class="listitem"><p>gcc-4.4.2: GLIBCXX_3.4.13, CXXABI_1.3.3</p></li><li class="listitem"><p>gcc-4.5.0: GLIBCXX_3.4.14, CXXABI_1.3.4</p></li></ul></div></li><li class="listitem"><p>Incremental bumping of a compiler pre-defined macro, + __GXX_ABI_VERSION. This macro is defined as the version of the + compiler v3 ABI, with g++ 3.0.x being version 100. This macro will + be automatically defined whenever g++ is used (the curious can + test this by invoking g++ with the '-v' flag.) + </p><p> + This macro was defined in the file "lang-specs.h" in the gcc/cp directory. + Later versions defined it in "c-common.c" in the gcc directory, and from + G++ 3.4 it is defined in c-cppbuiltin.c and its value determined by the + '-fabi-version' command line option. + </p><p> + It is versioned as follows, where 'n' is given by '-fabi-version=n': + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>gcc-3.0.x: 100</p></li><li class="listitem"><p>gcc-3.1.x: 100 (Error, should be 101)</p></li><li class="listitem"><p>gcc-3.2.x: 102</p></li><li class="listitem"><p>gcc-3.3.x: 102</p></li><li class="listitem"><p>gcc-3.4.x, gcc-4.[0-5].x: 102 (when n=1)</p></li><li class="listitem"><p>gcc-3.4.x, gcc-4.[0-5].x: 1000 + n (when n>1) </p></li><li class="listitem"><p>gcc-3.4.x, gcc-4.[0-5].x: 999999 (when n=0)</p></li></ul></div><p/></li><li class="listitem"><p>Changes to the default compiler option for + <code class="code">-fabi-version</code>. + </p><p> + It is versioned as follows: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>gcc-3.0.x: (Error, not versioned) </p></li><li class="listitem"><p>gcc-3.1.x: (Error, not versioned) </p></li><li class="listitem"><p>gcc-3.2.x: <code class="code">-fabi-version=1</code></p></li><li class="listitem"><p>gcc-3.3.x: <code class="code">-fabi-version=1</code></p></li><li class="listitem"><p>gcc-3.4.x, gcc-4.[0-5].x: <code class="code">-fabi-version=2</code> <span class="emphasis"><em>(Incompatible with previous)</em></span></p></li></ul></div><p/></li><li class="listitem"><p>Incremental bumping of a library pre-defined macro. For releases + before 3.4.0, the macro is __GLIBCPP__. For later releases, it's + __GLIBCXX__. (The libstdc++ project generously changed from CPP to + CXX throughout its source to allow the "C" pre-processor the CPP + macro namespace.) These macros are defined as the date the library + was released, in compressed ISO date format, as an unsigned long. + </p><p> + This macro is defined in the file "c++config" in the + "libstdc++-v3/include/bits" directory. (Up to gcc-4.1.0, it was + changed every night by an automated script. Since gcc-4.1.0, it is + the same value as gcc/DATESTAMP.) + </p><p> + It is versioned as follows: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>gcc-3.0.0: 20010615</p></li><li class="listitem"><p>gcc-3.0.1: 20010819</p></li><li class="listitem"><p>gcc-3.0.2: 20011023</p></li><li class="listitem"><p>gcc-3.0.3: 20011220</p></li><li class="listitem"><p>gcc-3.0.4: 20020220</p></li><li class="listitem"><p>gcc-3.1.0: 20020514</p></li><li class="listitem"><p>gcc-3.1.1: 20020725</p></li><li class="listitem"><p>gcc-3.2.0: 20020814</p></li><li class="listitem"><p>gcc-3.2.1: 20021119</p></li><li class="listitem"><p>gcc-3.2.2: 20030205</p></li><li class="listitem"><p>gcc-3.2.3: 20030422</p></li><li class="listitem"><p>gcc-3.3.0: 20030513</p></li><li class="listitem"><p>gcc-3.3.1: 20030804</p></li><li class="listitem"><p>gcc-3.3.2: 20031016</p></li><li class="listitem"><p>gcc-3.3.3: 20040214</p></li><li class="listitem"><p>gcc-3.4.0: 20040419</p></li><li class="listitem"><p>gcc-3.4.1: 20040701</p></li><li class="listitem"><p>gcc-3.4.2: 20040906</p></li><li class="listitem"><p>gcc-3.4.3: 20041105</p></li><li class="listitem"><p>gcc-3.4.4: 20050519</p></li><li class="listitem"><p>gcc-3.4.5: 20051201</p></li><li class="listitem"><p>gcc-3.4.6: 20060306</p></li><li class="listitem"><p>gcc-4.0.0: 20050421</p></li><li class="listitem"><p>gcc-4.0.1: 20050707</p></li><li class="listitem"><p>gcc-4.0.2: 20050921</p></li><li class="listitem"><p>gcc-4.0.3: 20060309</p></li><li class="listitem"><p>gcc-4.1.0: 20060228</p></li><li class="listitem"><p>gcc-4.1.1: 20060524</p></li><li class="listitem"><p>gcc-4.1.2: 20070214</p></li><li class="listitem"><p>gcc-4.2.0: 20070514</p></li><li class="listitem"><p>gcc-4.2.1: 20070719</p></li><li class="listitem"><p>gcc-4.2.2: 20071007</p></li><li class="listitem"><p>gcc-4.2.3: 20080201</p></li><li class="listitem"><p>gcc-4.2.4: 20080519</p></li><li class="listitem"><p>gcc-4.3.0: 20080306</p></li><li class="listitem"><p>gcc-4.3.1: 20080606</p></li><li class="listitem"><p>gcc-4.3.2: 20080827</p></li><li class="listitem"><p>gcc-4.3.3: 20090124</p></li><li class="listitem"><p>gcc-4.4.0: 20090421</p></li><li class="listitem"><p>gcc-4.4.1: 20090722</p></li><li class="listitem"><p>gcc-4.4.2: 20091015</p></li></ul></div><p/></li><li class="listitem"><p> + Incremental bumping of a library pre-defined macro, + _GLIBCPP_VERSION. This macro is defined as the released version of + the library, as a string literal. This is only implemented in + gcc-3.1.0 releases and higher, and is deprecated in 3.4 (where it + is called _GLIBCXX_VERSION). + </p><p> + This macro is defined in the file "c++config" in the + "libstdc++-v3/include/bits" directory and is generated + automatically by autoconf as part of the configure-time generation + of config.h. + </p><p> + It is versioned as follows: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>gcc-3.0.0: "3.0.0"</p></li><li class="listitem"><p>gcc-3.0.1: "3.0.0" (Error, should be "3.0.1")</p></li><li class="listitem"><p>gcc-3.0.2: "3.0.0" (Error, should be "3.0.2")</p></li><li class="listitem"><p>gcc-3.0.3: "3.0.0" (Error, should be "3.0.3")</p></li><li class="listitem"><p>gcc-3.0.4: "3.0.0" (Error, should be "3.0.4")</p></li><li class="listitem"><p>gcc-3.1.0: "3.1.0"</p></li><li class="listitem"><p>gcc-3.1.1: "3.1.1"</p></li><li class="listitem"><p>gcc-3.2.0: "3.2"</p></li><li class="listitem"><p>gcc-3.2.1: "3.2.1"</p></li><li class="listitem"><p>gcc-3.2.2: "3.2.2"</p></li><li class="listitem"><p>gcc-3.2.3: "3.2.3"</p></li><li class="listitem"><p>gcc-3.3.0: "3.3"</p></li><li class="listitem"><p>gcc-3.3.1: "3.3.1"</p></li><li class="listitem"><p>gcc-3.3.2: "3.3.2"</p></li><li class="listitem"><p>gcc-3.3.3: "3.3.3"</p></li><li class="listitem"><p>gcc-3.4.x: "version-unused"</p></li><li class="listitem"><p>gcc-4.[0-5].x: "version-unused"</p></li></ul></div><p/></li><li class="listitem"><p> + Matching each specific C++ compiler release to a specific set of + C++ include files. This is only implemented in gcc-3.1.1 releases + and higher. + </p><p> + All C++ includes are installed in include/c++, then nest in a + directory hierarchy corresponding to the C++ compiler's released + version. This version corresponds to the variable "gcc_version" in + "libstdc++-v3/acinclude.m4," and more details can be found in that + file's macro GLIBCXX_CONFIGURE (GLIBCPP_CONFIGURE before gcc-3.4.0). + </p><p> + C++ includes are versioned as follows: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>gcc-3.0.0: include/g++-v3</p></li><li class="listitem"><p>gcc-3.0.1: include/g++-v3</p></li><li class="listitem"><p>gcc-3.0.2: include/g++-v3</p></li><li class="listitem"><p>gcc-3.0.3: include/g++-v3</p></li><li class="listitem"><p>gcc-3.0.4: include/g++-v3</p></li><li class="listitem"><p>gcc-3.1.0: include/g++-v3</p></li><li class="listitem"><p>gcc-3.1.1: include/c++/3.1.1</p></li><li class="listitem"><p>gcc-3.2.0: include/c++/3.2</p></li><li class="listitem"><p>gcc-3.2.1: include/c++/3.2.1</p></li><li class="listitem"><p>gcc-3.2.2: include/c++/3.2.2</p></li><li class="listitem"><p>gcc-3.2.3: include/c++/3.2.3</p></li><li class="listitem"><p>gcc-3.3.0: include/c++/3.3</p></li><li class="listitem"><p>gcc-3.3.1: include/c++/3.3.1</p></li><li class="listitem"><p>gcc-3.3.2: include/c++/3.3.2</p></li><li class="listitem"><p>gcc-3.3.3: include/c++/3.3.3</p></li><li class="listitem"><p>gcc-3.4.0: include/c++/3.4.0</p></li><li class="listitem"><p>gcc-3.4.1: include/c++/3.4.1</p></li><li class="listitem"><p>gcc-3.4.2: include/c++/3.4.2</p></li><li class="listitem"><p>gcc-3.4.3: include/c++/3.4.3</p></li><li class="listitem"><p>gcc-3.4.4: include/c++/3.4.4</p></li><li class="listitem"><p>gcc-3.4.5: include/c++/3.4.5</p></li><li class="listitem"><p>gcc-3.4.6: include/c++/3.4.6</p></li><li class="listitem"><p>gcc-4.0.0: include/c++/4.0.0</p></li><li class="listitem"><p>gcc-4.0.1: include/c++/4.0.1</p></li><li class="listitem"><p>gcc-4.0.2: include/c++/4.0.2</p></li><li class="listitem"><p>gcc-4.0.3: include/c++/4.0.3</p></li><li class="listitem"><p>gcc-4.1.0: include/c++/4.1.0</p></li><li class="listitem"><p>gcc-4.1.1: include/c++/4.1.1</p></li><li class="listitem"><p>gcc-4.1.2: include/c++/4.1.2</p></li><li class="listitem"><p>gcc-4.2.0: include/c++/4.2.0</p></li><li class="listitem"><p>gcc-4.2.1: include/c++/4.2.1</p></li><li class="listitem"><p>gcc-4.2.2: include/c++/4.2.2</p></li><li class="listitem"><p>gcc-4.2.3: include/c++/4.2.3</p></li><li class="listitem"><p>gcc-4.2.4: include/c++/4.2.4</p></li><li class="listitem"><p>gcc-4.3.0: include/c++/4.3.0</p></li><li class="listitem"><p>gcc-4.3.1: include/c++/4.3.1</p></li><li class="listitem"><p>gcc-4.3.3: include/c++/4.3.3</p></li><li class="listitem"><p>gcc-4.3.4: include/c++/4.3.4</p></li><li class="listitem"><p>gcc-4.4.0: include/c++/4.4.0</p></li><li class="listitem"><p>gcc-4.4.1: include/c++/4.4.1</p></li><li class="listitem"><p>gcc-4.4.2: include/c++/4.4.2</p></li><li class="listitem"><p>gcc-4.5.0: include/c++/4.5.0</p></li></ul></div><p/></li></ol></div><p> + Taken together, these techniques can accurately specify interface + and implementation changes in the GNU C++ tools themselves. Used + properly, they allow both the GNU C++ tools implementation, and + programs using them, an evolving yet controlled development that + maintains backward compatibility. +</p></div><div class="section" title="Prerequisites"><div class="titlepage"><div><div><h4 class="title"><a id="abi.versioning.prereq"/>Prerequisites</h4></div></div></div><p> + Minimum environment that supports a versioned ABI: A supported + dynamic linker, a GNU linker of sufficient vintage to understand + demangled C++ name globbing (ld) or the Sun linker, a shared + executable compiled + with g++, and shared libraries (libgcc_s, libstdc++) compiled by + a compiler (g++) with a compatible ABI. Phew. + </p><p> + On top of all that, an additional constraint: libstdc++ did not + attempt to version symbols (or age gracefully, really) until + version 3.1.0. + </p><p> + Most modern Linux and BSD versions, particularly ones using + gcc-3.1.x tools and more recent vintages, will meet the + requirements above, as does Solaris 2.5 and up. + </p></div><div class="section" title="Configuring"><div class="titlepage"><div><div><h4 class="title"><a id="abi.versioning.config"/>Configuring</h4></div></div></div><p> + It turns out that most of the configure options that change + default behavior will impact the mangled names of exported + symbols, and thus impact versioning and compatibility. + </p><p> + For more information on configure options, including ABI + impacts, see: + <a class="link" href="configure.html" title="Configure">here</a> + </p><p> + There is one flag that explicitly deals with symbol versioning: + --enable-symvers. + </p><p> + In particular, libstdc++-v3/acinclude.m4 has a macro called + GLIBCXX_ENABLE_SYMVERS that defaults to yes (or the argument + passed in via --enable-symvers=foo). At that point, the macro + attempts to make sure that all the requirement for symbol + versioning are in place. For more information, please consult + acinclude.m4. + </p></div><div class="section" title="Checking Active"><div class="titlepage"><div><div><h4 class="title"><a id="abi.versioning.active"/>Checking Active</h4></div></div></div><p> + When the GNU C++ library is being built with symbol versioning + on, you should see the following at configure time for + libstdc++: + </p><pre class="screen"> +<code class="computeroutput"> + checking versioning on shared library symbols... gnu +</code> +</pre><p> + or another of the supported styles. + If you don't see this line in the configure output, or if this line + appears but the last word is 'no', then you are out of luck. +</p><p> + If the compiler is pre-installed, a quick way to test is to compile + the following (or any) simple C++ file and link it to the shared + libstdc++ library: +</p><pre class="programlisting"> +#include <iostream> + +int main() +{ std::cout << "hello" << std::endl; return 0; } + +%g++ hello.cc -o hello.out + +%ldd hello.out + libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x00764000) + libm.so.6 => /lib/tls/libm.so.6 (0x004a8000) + libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40016000) + libc.so.6 => /lib/tls/libc.so.6 (0x0036d000) + /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000) + +%nm hello.out +</pre><p> +If you see symbols in the resulting output with "GLIBCXX_3" as part +of the name, then the executable is versioned. Here's an example: +</p><p> + <code class="code">U _ZNSt8ios_base4InitC1Ev@@GLIBCXX_3.4</code> +</p><p> +On Solaris 2, you can use <code class="code">pvs -r</code> instead: +</p><pre class="programlisting"> +%g++ hello.cc -o hello.out + +%pvs -r hello.out + libstdc++.so.6 (GLIBCXX_3.4, GLIBCXX_3.4.12); + libgcc_s.so.1 (GCC_3.0); + libc.so.1 (SUNWprivate_1.1, SYSVABI_1.3); +</pre><p> +<code class="code">ldd -v</code> works too, but is very verbose. +</p></div></div><div class="section" title="Allowed Changes"><div class="titlepage"><div><div><h3 class="title"><a id="abi.changes_allowed"/>Allowed Changes</h3></div></div></div><p> +The following will cause the library minor version number to +increase, say from "libstdc++.so.3.0.4" to "libstdc++.so.3.0.5". +</p><div class="orderedlist"><ol class="orderedlist"><li class="listitem"><p>Adding an exported global or static data member</p></li><li class="listitem"><p>Adding an exported function, static or non-virtual member function</p></li><li class="listitem"><p>Adding an exported symbol or symbols by additional instantiations</p></li></ol></div><p> +Other allowed changes are possible. +</p></div><div class="section" title="Prohibited Changes"><div class="titlepage"><div><div><h3 class="title"><a id="abi.changes_no"/>Prohibited Changes</h3></div></div></div><p> +The following non-exhaustive list will cause the library major version +number to increase, say from "libstdc++.so.3.0.4" to +"libstdc++.so.4.0.0". +</p><div class="orderedlist"><ol class="orderedlist"><li class="listitem"><p>Changes in the gcc/g++ compiler ABI</p></li><li class="listitem"><p>Changing size of an exported symbol</p></li><li class="listitem"><p>Changing alignment of an exported symbol</p></li><li class="listitem"><p>Changing the layout of an exported symbol</p></li><li class="listitem"><p>Changing mangling on an exported symbol</p></li><li class="listitem"><p>Deleting an exported symbol</p></li><li class="listitem"><p>Changing the inheritance properties of a type by adding or removing + base classes</p></li><li class="listitem"><p> + Changing the size, alignment, or layout of types + specified in the C++ standard. These may not necessarily be + instantiated or otherwise exported in the library binary, and + include all the required locale facets, as well as things like + std::basic_streambuf, et al. +</p></li><li class="listitem"><p> Adding an explicit copy constructor or destructor to a +class that would otherwise have implicit versions. This will change +the way the compiler deals with this class in by-value return +statements or parameters: instead of passing instances of this +class in registers, the compiler will be forced to use memory. See the +section on <a class="link" href="http://www.codesourcery.com/public/cxx-abi/abi.html#calls">Function +Calling Conventions and APIs</a> + of the C++ ABI documentation for further details. +</p></li></ol></div></div><div class="section" title="Implementation"><div class="titlepage"><div><div><h3 class="title"><a id="abi.impl"/>Implementation</h3></div></div></div><div class="orderedlist"><ol class="orderedlist"><li class="listitem"><p> + Separation of interface and implementation + </p><p> + This is accomplished by two techniques that separate the API from + the ABI: forcing undefined references to link against a library + binary for definitions. + </p><div class="variablelist"><dl><dt><span class="term">Include files have declarations, source files have defines</span></dt><dd><p> + For non-templatized types, such as much of <code class="code">class + locale</code>, the appropriate standard C++ include, say + <code class="code">locale</code>, can contain full declarations, while + various source files (say <code class="code"> locale.cc, locale_init.cc, + localename.cc</code>) contain definitions. + </p></dd><dt><span class="term">Extern template on required types</span></dt><dd><p> + For parts of the standard that have an explicit list of + required instantiations, the GNU extension syntax <code class="code"> extern + template </code> can be used to control where template + definitions reside. By marking required instantiations as + <code class="code"> extern template </code> in include files, and providing + explicit instantiations in the appropriate instantiation files, + non-inlined template functions can be versioned. This technique + is mostly used on parts of the standard that require <code class="code"> + char</code> and <code class="code"> wchar_t</code> instantiations, and + includes <code class="code"> basic_string</code>, the locale facets, and the + types in <code class="code"> iostreams</code>. + </p></dd></dl></div><p> + In addition, these techniques have the additional benefit that they + reduce binary size, which can increase runtime performance. + </p></li><li class="listitem"><p> + Namespaces linking symbol definitions to export mapfiles + </p><p> + All symbols in the shared library binary are processed by a + linker script at build time that either allows or disallows + external linkage. Because of this, some symbols, regardless of + normal C/C++ linkage, are not visible. Symbols that are internal + have several appealing characteristics: by not exporting the + symbols, there are no relocations when the shared library is + started and thus this makes for faster runtime loading + performance by the underlying dynamic loading mechanism. In + addition, they have the possibility of changing without impacting + ABI compatibility. + </p><p>The following namespaces are transformed by the mapfile:</p><div class="variablelist"><dl><dt><span class="term"><code class="code">namespace std</code></span></dt><dd><p> Defaults to exporting all symbols in label +<code class="code">GLIBCXX</code> that do not begin with an underscore, i.e., +<code class="code">__test_func</code> would not be exported by default. Select +exceptional symbols are allowed to be visible.</p></dd><dt><span class="term"><code class="code">namespace __gnu_cxx</code></span></dt><dd><p> Defaults to not exporting any symbols in label +<code class="code">GLIBCXX</code>, select items are allowed to be visible.</p></dd><dt><span class="term"><code class="code">namespace __gnu_internal</code></span></dt><dd><p> Defaults to not exported, no items are allowed to be visible.</p></dd><dt><span class="term"><code class="code">namespace __cxxabiv1</code>, aliased to <code class="code"> namespace abi</code></span></dt><dd><p> Defaults to not exporting any symbols in label +<code class="code">CXXABI</code>, select items are allowed to be visible.</p></dd></dl></div><p> +</p></li><li class="listitem"><p>Freezing the API</p><p>Disallowed changes, as above, are not made on a stable release +branch. Enforcement tends to be less strict with GNU extensions that +standard includes.</p></li></ol></div></div><div class="section" title="Testing"><div class="titlepage"><div><div><h3 class="title"><a id="abi.testing"/>Testing</h3></div></div></div><div class="section" title="Single ABI Testing"><div class="titlepage"><div><div><h4 class="title"><a id="abi.testing.single"/>Single ABI Testing</h4></div></div></div><p> + Testing for GNU C++ ABI changes is composed of two distinct + areas: testing the C++ compiler (g++) for compiler changes, and + testing the C++ library (libstdc++) for library changes. + </p><p> + Testing the C++ compiler ABI can be done various ways. + </p><p> + One. Intel ABI checker. + </p><p> +Two. +The second is yet unreleased, but has been announced on the gcc +mailing list. It is yet unspecified if these tools will be freely +available, and able to be included in a GNU project. Please contact +Mark Mitchell (mark@codesourcery.com) for more details, and current +status. +</p><p> +Three. +Involves using the vlad.consistency test framework. This has also been +discussed on the gcc mailing lists. +</p><p> +Testing the C++ library ABI can also be done various ways. +</p><p> +One. +(Brendan Kehoe, Jeff Law suggestion to run 'make check-c++' two ways, +one with a new compiler and an old library, and the other with an old +compiler and a new library, and look for testsuite regressions) +</p><p> +Details on how to set this kind of test up can be found here: +http://gcc.gnu.org/ml/gcc/2002-08/msg00142.html +</p><p> +Two. +Use the 'make check-abi' rule in the libstdc++ Makefile. +</p><p> +This is a proactive check of the library ABI. Currently, exported symbol +names that are either weak or defined are checked against a last known +good baseline. Currently, this baseline is keyed off of 3.4.0 +binaries, as this was the last time the .so number was incremented. In +addition, all exported names are demangled, and the exported objects +are checked to make sure they are the same size as the same object in +the baseline. + +Notice that each baseline is relative to a <span class="emphasis"><em>default</em></span> +configured library and compiler: in particular, if options such as +--enable-clocale, or --with-cpu, in case of multilibs, are used at +configure time, the check may fail, either because of substantive +differences or because of limitations of the current checking +machinery. +</p><p> +This dataset is insufficient, yet a start. Also needed is a +comprehensive check for all user-visible types part of the standard +library for sizeof() and alignof() changes. +</p><p> +Verifying compatible layouts of objects is not even attempted. It +should be possible to use sizeof, alignof, and offsetof to compute +offsets for each structure and type in the standard library, saving to +another datafile. Then, compute this in a similar way for new +binaries, and look for differences. +</p><p> +Another approach might be to use the -fdump-class-hierarchy flag to +get information. However, currently this approach gives insufficient +data for use in library testing, as class data members, their offsets, +and other detailed data is not displayed with this flag. +(See PR g++/7470 on how this was used to find bugs.) +</p><p> +Perhaps there are other C++ ABI checkers. If so, please notify +us. We'd like to know about them! +</p></div><div class="section" title="Multiple ABI Testing"><div class="titlepage"><div><div><h4 class="title"><a id="abi.testing.multi"/>Multiple ABI Testing</h4></div></div></div><p> +A "C" application, dynamically linked to two shared libraries, liba, +libb. The dependent library liba is a C++ shared library compiled with +gcc-3.3.x, and uses io, exceptions, locale, etc. The dependent library +libb is a C++ shared library compiled with gcc-3.4.x, and also uses io, +exceptions, locale, etc. +</p><p> As above, libone is constructed as follows: </p><pre class="programlisting"> +%$bld/H-x86-gcc-3.4.0/bin/g++ -fPIC -DPIC -c a.cc + +%$bld/H-x86-gcc-3.4.0/bin/g++ -shared -Wl,-soname -Wl,libone.so.1 -Wl,-O1 -Wl,-z,defs a.o -o libone.so.1.0.0 + +%ln -s libone.so.1.0.0 libone.so + +%$bld/H-x86-gcc-3.4.0/bin/g++ -c a.cc + +%ar cru libone.a a.o +</pre><p> And, libtwo is constructed as follows: </p><pre class="programlisting"> +%$bld/H-x86-gcc-3.3.3/bin/g++ -fPIC -DPIC -c b.cc + +%$bld/H-x86-gcc-3.3.3/bin/g++ -shared -Wl,-soname -Wl,libtwo.so.1 -Wl,-O1 -Wl,-z,defs b.o -o libtwo.so.1.0.0 + +%ln -s libtwo.so.1.0.0 libtwo.so + +%$bld/H-x86-gcc-3.3.3/bin/g++ -c b.cc + +%ar cru libtwo.a b.o +</pre><p> ...with the resulting libraries looking like </p><pre class="screen"> +<code class="computeroutput"> +%ldd libone.so.1.0.0 + libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x40016000) + libm.so.6 => /lib/tls/libm.so.6 (0x400fa000) + libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x4011c000) + libc.so.6 => /lib/tls/libc.so.6 (0x40125000) + /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000) + +%ldd libtwo.so.1.0.0 + libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x40027000) + libm.so.6 => /lib/tls/libm.so.6 (0x400e1000) + libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40103000) + libc.so.6 => /lib/tls/libc.so.6 (0x4010c000) + /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000) +</code> +</pre><p> + Then, the "C" compiler is used to compile a source file that uses + functions from each library. +</p><pre class="programlisting"> +gcc test.c -g -O2 -L. -lone -ltwo /usr/lib/libstdc++.so.5 /usr/lib/libstdc++.so.6 +</pre><p> + Which gives the expected: +</p><pre class="screen"> +<code class="computeroutput"> +%ldd a.out + libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x00764000) + libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x40015000) + libc.so.6 => /lib/tls/libc.so.6 (0x0036d000) + libm.so.6 => /lib/tls/libm.so.6 (0x004a8000) + libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x400e5000) + /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000) +</code> +</pre><p> + This resulting binary, when executed, will be able to safely use + code from both liba, and the dependent libstdc++.so.6, and libb, + with the dependent libstdc++.so.5. +</p></div></div><div class="section" title="Outstanding Issues"><div class="titlepage"><div><div><h3 class="title"><a id="abi.issues"/>Outstanding Issues</h3></div></div></div><p> + Some features in the C++ language make versioning especially + difficult. In particular, compiler generated constructs such as + implicit instantiations for templates, typeinfo information, and + virtual tables all may cause ABI leakage across shared library + boundaries. Because of this, mixing C++ ABIs is not recommended at + this time. +</p><p> + For more background on this issue, see these bugzilla entries: +</p><p> +<a class="link" href="http://gcc.gnu.org/PR24660">24660: versioning weak symbols in libstdc++</a> +</p><p> +<a class="link" href="http://gcc.gnu.org/PR19664">19664: libstdc++ headers should have pop/push of the visibility around the declarations</a> +</p></div><div class="bibliography" title="Bibliography"><div class="titlepage"><div><div><h3 class="title"><a id="abi.biblio"/>Bibliography</h3></div></div></div><div class="biblioentry"><a id="id501388"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + ABIcheck, a vague idea of checking ABI compatibility + </em>. </span></p></div><div class="biblioentry"><a id="id501406"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + C++ ABI Reference + </em>. </span></p></div><div class="biblioentry"><a id="id501423"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + Intel Compilers for Linux Compatibility with the GNU Compilers + </em>. </span></p></div><div class="biblioentry"><a id="id501441"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + Linker and Libraries Guide (document 819-0690) + </em>. </span></p></div><div class="biblioentry"><a id="id501458"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + Sun Studio 11: C++ Migration Guide (document 819-3689) + </em>. </span></p></div><div class="biblioentry"><a id="id501476"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + How to Write Shared Libraries + </em>. </span><span class="author"><span class="firstname">Ulrich</span> <span class="surname">Drepper</span>. </span></p></div><div class="biblioentry"><a id="id501507"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + C++ ABI for the ARM Architecture + </em>. </span></p></div><div class="biblioentry"><a id="id501524"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + Dynamic Shared Objects: Survey and Issues + </em>. </span><span class="subtitle"> + ISO C++ J16/06-0046 + . </span><span class="author"><span class="firstname">Benjamin</span> <span class="surname">Kosnik</span>. </span></p></div><div class="biblioentry"><a id="id501554"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + Versioning With Namespaces + </em>. </span><span class="subtitle"> + ISO C++ J16/06-0083 + . </span><span class="author"><span class="firstname">Benjamin</span> <span class="surname">Kosnik</span>. </span></p></div><div class="biblioentry"><a id="id501584"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + Binary Compatibility of Shared Libraries Implemented in C++ + on GNU/Linux Systems + </em>. </span><span class="subtitle"> + SYRCoSE 2009 + . </span><span class="author"><span class="firstname">Pavel</span> <span class="surname">Shved</span>. </span><span class="author"><span class="firstname">Denis</span> <span class="surname">Silakov</span>. </span></p></div></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="test.html">Prev</a> </td><td align="center"><a accesskey="u" href="appendix_porting.html">Up</a></td><td align="right"> <a accesskey="n" href="api.html">Next</a></td></tr><tr><td align="left" valign="top">Test </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> API Evolution and Deprecation History</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/algorithms.html b/libstdc++-v3/doc/html/manual/algorithms.html new file mode 100644 index 000000000..ba91e4e05 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/algorithms.html @@ -0,0 +1,61 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Chapter 11. Algorithms</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library , algorithm "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="bk01pt02.html" title="Part II. Standard Contents"/><link rel="prev" href="iterators.html" title="Chapter 10. Iterators"/><link rel="next" href="numerics.html" title="Chapter 12. Numerics"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 11. + Algorithms + +</th></tr><tr><td align="left"><a accesskey="p" href="iterators.html">Prev</a> </td><th width="60%" align="center">Part II. + Standard Contents + </th><td align="right"> <a accesskey="n" href="numerics.html">Next</a></td></tr></table><hr/></div><div class="chapter" title="Chapter 11. Algorithms"><div class="titlepage"><div><div><h2 class="title"><a id="std.algorithms"/>Chapter 11. + Algorithms + <a id="id479931" class="indexterm"/> +</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="algorithms.html#std.algorithms.mutating">Mutating</a></span></dt><dd><dl><dt><span class="section"><a href="algorithms.html#algorithms.mutating.swap"><code class="function">swap</code></a></span></dt></dl></dd></dl></div><p> + The neatest accomplishment of the algorithms sect1 is that all the + work is done via iterators, not containers directly. This means two + important things: +</p><div class="orderedlist"><ol class="orderedlist"><li class="listitem"><p> + Anything that behaves like an iterator can be used in one of + these algorithms. Raw pointers make great candidates, thus + built-in arrays are fine containers, as well as your own + iterators. + </p></li><li class="listitem"><p> + The algorithms do not (and cannot) affect the container as a + whole; only the things between the two iterator endpoints. If + you pass a range of iterators only enclosing the middle third of + a container, then anything outside that range is inviolate. + </p></li></ol></div><p> + Even strings can be fed through the algorithms here, although the + string class has specialized versions of many of these functions + (for example, <code class="code">string::find()</code>). Most of the examples + on this page will use simple arrays of integers as a playground + for algorithms, just to keep things simple. The use of + <span class="emphasis"><em>N</em></span> as a size in the examples is to keep things + easy to read but probably won't be valid code. You can use wrappers + such as those described in + the <a class="link" href="containers.html" title="Chapter 9. Containers">containers sect1</a> to keep + real code readable. +</p><p> + The single thing that trips people up the most is the definition + of <span class="emphasis"><em>range</em></span> used with iterators; the famous + "past-the-end" rule that everybody loves to hate. The + <a class="link" href="iterators.html" title="Chapter 10. Iterators">iterators sect1</a> of this + document has a complete explanation of this simple rule that seems + to cause so much confusion. Once you + get <span class="emphasis"><em>range</em></span> into your head (it's not that hard, + honest!), then the algorithms are a cakewalk. +</p><div class="section" title="Mutating"><div class="titlepage"><div><div><h2 class="title"><a id="std.algorithms.mutating"/>Mutating</h2></div></div></div><div class="section" title="swap"><div class="titlepage"><div><div><h3 class="title"><a id="algorithms.mutating.swap"/><code class="function">swap</code></h3></div></div></div><div class="section" title="Specializations"><div class="titlepage"><div><div><h4 class="title"><a id="algorithms.swap.specializations"/>Specializations</h4></div></div></div><p>If you call <code class="code"> std::swap(x,y); </code> where x and y are standard + containers, then the call will automatically be replaced by a call to + <code class="code"> x.swap(y); </code> instead. + </p><p>This allows member functions of each container class to take over, and + containers' swap functions should have O(1) complexity according to + the standard. (And while "should" allows implementations to + behave otherwise and remain compliant, this implementation does in + fact use constant-time swaps.) This should not be surprising, since + for two containers of the same type to swap contents, only some + internal pointers to storage need to be exchanged. + </p></div></div></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="iterators.html">Prev</a> </td><td align="center"><a accesskey="u" href="bk01pt02.html">Up</a></td><td align="right"> <a accesskey="n" href="numerics.html">Next</a></td></tr><tr><td align="left" valign="top">Chapter 10. + Iterators + + </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Chapter 12. + Numerics + +</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/api.html b/libstdc++-v3/doc/html/manual/api.html new file mode 100644 index 000000000..2cb3500fd --- /dev/null +++ b/libstdc++-v3/doc/html/manual/api.html @@ -0,0 +1,240 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>API Evolution and Deprecation History</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content="ISO C++, api, evolution, deprecation, history"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="appendix_porting.html" title="Appendix B. Porting and Maintenance"/><link rel="prev" href="abi.html" title="ABI Policy and Guidelines"/><link rel="next" href="backwards.html" title="Backwards Compatibility"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">API Evolution and Deprecation History</th></tr><tr><td align="left"><a accesskey="p" href="abi.html">Prev</a> </td><th width="60%" align="center">Appendix B. + Porting and Maintenance + +</th><td align="right"> <a accesskey="n" href="backwards.html">Next</a></td></tr></table><hr/></div><div class="section" title="API Evolution and Deprecation History"><div class="titlepage"><div><div><h2 class="title"><a id="appendix.porting.api"/>API Evolution and Deprecation History</h2></div></div></div><p> +A list of user-visible changes, in chronological order +</p><div class="section" title="3.0"><div class="titlepage"><div><div><h3 class="title"><a id="api.rel_300"/><code class="constant">3.0</code></h3></div></div></div><p> +Extensions moved to <code class="filename">include/ext</code>. + </p><p> +Include files from the SGI/HP sources that pre-date the ISO standard +are added. These files are placed into +the <code class="filename">include/backward</code> directory and a deprecated warning +is added that notifies on inclusion (<code class="literal">-Wno-deprecated</code> +deactivates the warning.) +</p><p>Deprecated include <code class="filename">backward/strstream</code> added.</p><p>Removal of include <code class="filename">builtinbuf.h</code>, <code class="filename">indstream.h</code>, <code class="filename">parsestream.h</code>, <code class="filename">PlotFile.h</code>, <code class="filename">SFile.h</code>, <code class="filename">stdiostream.h</code>, and <code class="filename">stream.h</code>. +</p></div><div class="section" title="3.1"><div class="titlepage"><div><div><h3 class="title"><a id="api.rel_310"/><code class="constant">3.1</code></h3></div></div></div><p> + </p><p> +Extensions from SGI/HP moved from <code class="code">namespace std</code> +to <code class="code">namespace __gnu_cxx</code>. As part of this, the following +new includes are +added: <code class="filename">ext/algorithm</code>, <code class="filename">ext/functional</code>, <code class="filename">ext/iterator</code>, <code class="filename">ext/memory</code>, and <code class="filename">ext/numeric</code>. +</p><p> +Extensions to <code class="code">basic_filebuf</code> introduced: <code class="code">__gnu_cxx::enc_filebuf</code>, and <code class="code">__gnu_cxx::stdio_filebuf</code>. +</p><p> +Extensions to tree data structures added in <code class="filename">ext/rb_tree</code>. +</p><p> +Removal of <code class="filename">ext/tree</code>, moved to <code class="filename">backward/tree.h</code>. +</p></div><div class="section" title="3.2"><div class="titlepage"><div><div><h3 class="title"><a id="api.rel_320"/><code class="constant">3.2</code></h3></div></div></div><p> + </p><p>Symbol versioning introduced for shared library.</p><p>Removal of include <code class="filename">backward/strstream.h</code>.</p><p>Allocator changes. Change <code class="code">__malloc_alloc</code> to <code class="code">malloc_allocator</code> and <code class="code">__new_alloc</code> to <code class="code">new_allocator</code>. </p><p> For GCC releases from 2.95 through the 3.1 series, defining + <code class="literal">__USE_MALLOC</code> on the gcc command line would change the + default allocation strategy to instead use <code class="code"> malloc</code> and + <code class="function">free</code>. (This same functionality is now spelled <code class="literal">_GLIBCXX_FORCE_NEW</code>, see + <a class="link" href="using_macros.html" title="Macros">this page</a> + for details. + </p><p>Error handling in iostreams cleaned up, made consistent. </p></div><div class="section" title="3.3"><div class="titlepage"><div><div><h3 class="title"><a id="api.rel_330"/><code class="constant">3.3</code></h3></div></div></div><p> + </p></div><div class="section" title="3.4"><div class="titlepage"><div><div><h3 class="title"><a id="api.rel_340"/><code class="constant">3.4</code></h3></div></div></div><p> + </p><p> +Large file support. +</p><p> Extensions for generic characters and <code class="code">char_traits</code> added in <code class="filename">ext/pod_char_traits.h</code>. +</p><p> +Support for <code class="code">wchar_t</code> specializations of <code class="code">basic_filebuf</code> enhanced to support <code class="code">UTF-8</code> and <code class="code">Unicode</code>, depending on host. More hosts support basic <code class="code">wchar_t</code> functionality. +</p><p> +Support for <code class="code">char_traits</code> beyond builtin types. +</p><p> +Conformant <code class="code">allocator</code> class and usage in containers. As +part of this, the following extensions are +added: <code class="filename">ext/bitmap_allocator.h</code>, <code class="filename">ext/debug_allocator.h</code>, <code class="filename">ext/mt_allocator.h</code>, <code class="filename">ext/malloc_allocator.h</code>,<code class="filename">ext/new_allocator.h</code>, <code class="filename">ext/pool_allocator.h</code>. +</p><p> +This is a change from all previous versions, and may require +source-level changes due to allocator-related changes to structures +names and template parameters, filenames, and file locations. Some, +like <code class="code">__simple_alloc, __allocator, __alloc, </code> and <code class="code"> +_Alloc_traits</code> have been removed. +</p><p>Default behavior of <code class="code">std::allocator</code> has changed.</p><p> + Previous versions prior to 3.4 cache allocations in a memory + pool, instead of passing through to call the global allocation + operators (i.e., <code class="classname">__gnu_cxx::pool_allocator</code>). More + recent versions default to the + simpler <code class="classname">__gnu_cxx::new_allocator</code>. +</p><p> Previously, all allocators were written to the SGI + style, and all STL containers expected this interface. This + interface had a traits class called <code class="code">_Alloc_traits</code> that + attempted to provide more information for compile-time allocation + selection and optimization. This traits class had another allocator + wrapper, <code class="code">__simple_alloc<T,A></code>, which was a + wrapper around another allocator, A, which itself is an allocator + for instances of T. But wait, there's more: + <code class="code">__allocator<T,A></code> is another adapter. Many of + the provided allocator classes were SGI style: such classes can be + changed to a conforming interface with this wrapper: + <code class="code">__allocator<T, __alloc></code> is thus the same as + <code class="code">allocator<T></code>. + </p><p> The class <code class="classname">allocator</code> used the typedef + <span class="type">__alloc</span> to select an underlying allocator that + satisfied memory allocation requests. The selection of this + underlying allocator was not user-configurable. + </p><div class="table"><a id="id502145"/><p class="title"><strong>Table B.6. Extension Allocators</strong></p><div class="table-contents"><table summary="Extension Allocators" border="1"><colgroup><col style="text-align: left" class="c1"/><col style="text-align: left" class="c2"/><col style="text-align: left" class="c3"/><col style="text-align: left" class="c4"/></colgroup><thead><tr><th style="text-align: left">Allocator (3.4)</th><th style="text-align: left">Header (3.4)</th><th style="text-align: left">Allocator (3.[0-3])</th><th style="text-align: left">Header (3.[0-3])</th></tr></thead><tbody><tr><td style="text-align: left"><code class="classname">__gnu_cxx::new_allocator<T></code></td><td style="text-align: left"><code class="filename">ext/new_allocator.h</code></td><td style="text-align: left"><code class="classname">std::__new_alloc</code></td><td style="text-align: left"><code class="filename">memory</code></td></tr><tr><td style="text-align: left"><code class="classname">__gnu_cxx::malloc_allocator<T></code></td><td style="text-align: left"><code class="filename">ext/malloc_allocator.h</code></td><td style="text-align: left"><code class="classname">std::__malloc_alloc_template<int></code></td><td style="text-align: left"><code class="filename">memory</code></td></tr><tr><td style="text-align: left"><code class="classname">__gnu_cxx::debug_allocator<T></code></td><td style="text-align: left"><code class="filename">ext/debug_allocator.h</code></td><td style="text-align: left"><code class="classname">std::debug_alloc<T></code></td><td style="text-align: left"><code class="filename">memory</code></td></tr><tr><td style="text-align: left"><code class="classname">__gnu_cxx::__pool_alloc<T></code></td><td style="text-align: left"><code class="filename">ext/pool_allocator.h</code></td><td style="text-align: left"><code class="classname">std::__default_alloc_template<bool,int></code></td><td style="text-align: left"><code class="filename">memory</code></td></tr><tr><td style="text-align: left"><code class="classname">__gnu_cxx::__mt_alloc<T></code></td><td style="text-align: left"><code class="filename">ext/mt_allocator.h</code></td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left"><code class="classname">__gnu_cxx::bitmap_allocator<T></code></td><td style="text-align: left"><code class="filename">ext/bitmap_allocator.h</code></td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr></tbody></table></div></div><br class="table-break"/><p> Releases after gcc-3.4 have continued to add to the collection + of available allocators. All of these new allocators are + standard-style. The following table includes details, along with + the first released version of GCC that included the extension allocator. + </p><div class="table"><a id="id502375"/><p class="title"><strong>Table B.7. Extension Allocators Continued</strong></p><div class="table-contents"><table summary="Extension Allocators Continued" border="1"><colgroup><col style="text-align: left" class="c1"/><col style="text-align: left" class="c2"/><col style="text-align: left" class="c3"/></colgroup><thead><tr><th style="text-align: left">Allocator</th><th style="text-align: left">Include</th><th style="text-align: left">Version</th></tr></thead><tbody><tr><td style="text-align: left"><code class="classname">__gnu_cxx::array_allocator<T></code></td><td style="text-align: left"><code class="filename">ext/array_allocator.h</code></td><td style="text-align: left">4.0.0</td></tr><tr><td style="text-align: left"><code class="classname">__gnu_cxx::throw_allocator<T></code></td><td style="text-align: left"><code class="filename">ext/throw_allocator.h</code></td><td style="text-align: left">4.2.0</td></tr></tbody></table></div></div><br class="table-break"/><p> +Debug mode first appears. +</p><p> +Precompiled header support <acronym class="acronym">PCH</acronym> support. +</p><p> +Macro guard for changed, from <code class="literal">_GLIBCPP_</code> to <code class="literal">_GLIBCXX_</code>. +</p><p> +Extension <code class="filename">ext/stdio_sync_filebuf.h</code> added. +</p><p> +Extension <code class="filename">ext/demangle.h</code> added. +</p></div><div class="section" title="4.0"><div class="titlepage"><div><div><h3 class="title"><a id="api.rel_400"/><code class="constant">4.0</code></h3></div></div></div><p> + </p><p> +TR1 features first appear. +</p><p> +Extension allocator <code class="filename">ext/array_allocator.h</code> added. +</p><p> +Extension <code class="code">codecvt</code> specializations moved to <code class="filename">ext/codecvt_specializations.h</code>. +</p><p> +Removal of <code class="filename">ext/demangle.h</code>. +</p></div><div class="section" title="4.1"><div class="titlepage"><div><div><h3 class="title"><a id="api.rel_410"/><code class="constant">4.1</code></h3></div></div></div><p> + </p><p> +Removal of <code class="filename">cassert</code> from all standard headers: now has to be explicitly included for <code class="code">std::assert</code> calls. +</p><p> Extensions for policy-based data structures first added. New includes, +types, namespace <code class="code">pb_assoc</code>. +</p><p> Extensions for typelists added in <code class="filename">ext/typelist.h</code>. +</p><p> Extension for policy-based <code class="code">basic_string</code> first added: <code class="code">__gnu_cxx::__versa_string</code> in <code class="filename">ext/vstring.h</code>. +</p></div><div class="section" title="4.2"><div class="titlepage"><div><div><h3 class="title"><a id="api.rel_420"/><code class="constant">4.2</code></h3></div></div></div><p> + </p><p> Default visibility attributes applied to <code class="code">namespace std</code>. Support for <code class="code">-fvisibility</code>. +</p><p>TR1 <code class="filename">random</code>, <code class="filename">complex</code>, and C compatibility headers added.</p><p> Extensions for concurrent programming consolidated +into <code class="filename">ext/concurrence.h</code> and <code class="filename">ext/atomicity.h</code>, +including change of namespace to <code class="code">__gnu_cxx</code> in some +cases. Added types +include <code class="code">_Lock_policy</code>, <code class="code">__concurrence_lock_error</code>, <code class="code">__concurrence_unlock_error</code>, <code class="code">__mutex</code>, <code class="code">__scoped_lock</code>.</p><p> Extensions for type traits consolidated +into <code class="filename">ext/type_traits.h</code>. Additional traits are added +(<code class="code">__conditional_type</code>, <code class="code">__enable_if</code>, others.) +</p><p> Extensions for policy-based data structures revised. New includes, +types, namespace moved to <code class="code">__pb_ds</code>. +</p><p> Extensions for debug mode modified: now nested in <code class="code">namespace +std::__debug</code> and extensions in <code class="code">namespace +__gnu_cxx::__debug</code>.</p><p> Extensions added: <code class="filename">ext/typelist.h</code> +and <code class="filename">ext/throw_allocator.h</code>. +</p></div><div class="section" title="4.3"><div class="titlepage"><div><div><h3 class="title"><a id="api.rel_430"/><code class="constant">4.3</code></h3></div></div></div><p> + </p><p> +C++0X features first appear. +</p><p>TR1 <code class="filename">regex</code> and <code class="filename">cmath</code>'s mathematical special function added. +</p><p> +Backward include edit. +</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>Removed</p><p> +<code class="filename">algobase.h</code> <code class="filename">algo.h</code> <code class="filename">alloc.h</code> <code class="filename">bvector.h</code> <code class="filename">complex.h</code> +<code class="filename">defalloc.h</code> <code class="filename">deque.h</code> <code class="filename">fstream.h</code> <code class="filename">function.h</code> <code class="filename">hash_map.h</code> <code class="filename">hash_set.h</code> +<code class="filename">hashtable.h</code> <code class="filename">heap.h</code> <code class="filename">iomanip.h</code> <code class="filename">iostream.h</code> <code class="filename">istream.h</code> <code class="filename">iterator.h</code> +<code class="filename">list.h</code> <code class="filename">map.h</code> <code class="filename">multimap.h</code> <code class="filename">multiset.h</code> <code class="filename">new.h</code> <code class="filename">ostream.h</code> <code class="filename">pair.h</code> <code class="filename">queue.h</code> <code class="filename">rope.h</code> <code class="filename">set.h</code> <code class="filename">slist.h</code> <code class="filename">stack.h</code> <code class="filename">streambuf.h</code> <code class="filename">stream.h</code> <code class="filename">tempbuf.h</code> +<code class="filename">tree.h</code> <code class="filename">vector.h</code> + </p></li><li class="listitem"><p>Added</p><p> + <code class="filename">hash_map</code> and <code class="filename">hash_set</code> + </p></li><li class="listitem"><p>Added in C++0x</p><p> + <code class="filename">auto_ptr.h</code> and <code class="filename">binders.h</code> + </p></li></ul></div><p> +Header dependency streamlining. +</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><code class="filename">algorithm</code> no longer includes <code class="filename">climits</code>, <code class="filename">cstring</code>, or <code class="filename">iosfwd</code> </p></li><li class="listitem"><p><code class="filename">bitset</code> no longer includes <code class="filename">istream</code> or <code class="filename">ostream</code>, adds <code class="filename">iosfwd</code> </p></li><li class="listitem"><p><code class="filename">functional</code> no longer includes <code class="filename">cstddef</code></p></li><li class="listitem"><p><code class="filename">iomanip</code> no longer includes <code class="filename">istream</code>, <code class="filename">istream</code>, or <code class="filename">functional</code>, adds <code class="filename">ioswd</code> </p></li><li class="listitem"><p><code class="filename">numeric</code> no longer includes <code class="filename">iterator</code></p></li><li class="listitem"><p><code class="filename">string</code> no longer includes <code class="filename">algorithm</code> or <code class="filename">memory</code></p></li><li class="listitem"><p><code class="filename">valarray</code> no longer includes <code class="filename">numeric</code> or <code class="filename">cstdlib</code></p></li><li class="listitem"><p><code class="filename">tr1/hashtable</code> no longer includes <code class="filename">memory</code> or <code class="filename">functional</code></p></li><li class="listitem"><p><code class="filename">tr1/memory</code> no longer includes <code class="filename">algorithm</code></p></li><li class="listitem"><p><code class="filename">tr1/random</code> no longer includes <code class="filename">algorithm</code> or <code class="filename">fstream</code></p></li></ul></div><p> +Debug mode for <code class="filename">unordered_map</code> and <code class="filename">unordered_set</code>. +</p><p> +Parallel mode first appears. +</p><p>Variadic template implementations of items in <code class="filename">tuple</code> and + <code class="filename">functional</code>. +</p><p>Default <code class="code">what</code> implementations give more elaborate + exception strings for <code class="code">bad_cast</code>, + <code class="code">bad_typeid</code>, <code class="code">bad_exception</code>, and + <code class="code">bad_alloc</code>. +</p><p> +PCH binary files no longer installed. Instead, the source files are installed. +</p><p> +Namespace pb_ds moved to __gnu_pb_ds. +</p></div><div class="section" title="4.4"><div class="titlepage"><div><div><h3 class="title"><a id="api.rel_440"/><code class="constant">4.4</code></h3></div></div></div><p> + </p><p> +C++0X features. +</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + Added. + </p><p> + <code class="filename">atomic</code>, + <code class="filename">chrono</code>, + <code class="filename">condition_variable</code>, + <code class="filename">forward_list</code>, + <code class="filename">initializer_list</code>, + <code class="filename">mutex</code>, + <code class="filename">ratio</code>, + <code class="filename">thread</code> + </p></li><li class="listitem"><p> + Updated and improved. + </p><p> + <code class="filename">algorithm</code>, + <code class="filename">system_error</code>, + <code class="filename">type_traits</code> + </p></li><li class="listitem"><p> + Use of the GNU extension namespace association converted to inline namespaces. + </p></li><li class="listitem"><p> + Preliminary support for <code class="classname">initializer_list</code> + and defaulted and deleted constructors in container classes. + </p></li><li class="listitem"><p> + <code class="classname">unique_ptr</code>. + </p></li><li class="listitem"><p> + Support for new character types <span class="type">char16_t</span> + and <span class="type">char32_t</span> added + to <code class="classname">char_traits</code>, <code class="classname">basic_string</code>, <code class="classname">numeric_limits</code>, + and assorted compile-time type traits. + </p></li><li class="listitem"><p> + Support for string conversions <code class="function">to_string</code> + and <code class="function">to_wstring</code>. + </p></li><li class="listitem"><p> + Member functions taking string arguments were added to iostreams + including <code class="classname">basic_filebuf</code>, <code class="classname">basic_ofstream</code>, + and <code class="classname">basic_ifstream</code>. + </p></li><li class="listitem"><p> + Exception propagation support, + including <code class="classname">exception_ptr</code>, <code class="function">current_exception</code>, <code class="function">copy_exception</code>, + and <code class="function">rethrow_exception</code>. + </p></li></ul></div><p> +Uglification of <code class="literal">try</code> to <code class="literal">__try</code> +and <code class="literal">catch</code> to <code class="literal">__catch</code>. + </p><p> +Audit of internal mutex usage, conversion to functions returning static +local mutex. + </p><p> Extensions +added: <code class="filename">ext/pointer.h</code> +and <code class="filename">ext/extptr_allocator.h</code>. Support +for non-standard pointer types has been added +to <code class="classname">vector</code> +and <code class="classname">forward_list</code>. +</p></div><div class="section" title="4.5"><div class="titlepage"><div><div><h3 class="title"><a id="api.rel_450"/><code class="constant">4.5</code></h3></div></div></div><p> + </p><p> +C++0X features. +</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + Added. + </p><p> + <code class="filename">functional</code>, + <code class="filename">future</code>, + <code class="filename">random</code> + </p></li><li class="listitem"><p> + Updated and improved. + </p><p> + <code class="filename">atomic</code>, + <code class="filename">system_error</code>, + <code class="filename">type_traits</code> + </p></li><li class="listitem"><p> + Add support for explicit operators and standard layout types. + </p></li></ul></div><p> +Profile mode first appears. +</p><p> +Support for decimal floating-point arithmetic, including <code class="classname">decimal32</code>, <code class="classname">decimal64</code>, and <code class="classname">decimal128</code>. +</p><p> +Python pretty-printers are added for use with appropriately-advanced versions of <span class="command"><strong>gdb</strong></span>. +</p><p> +Audit for application of function attributes notrow, const, pure, and noreturn. +</p><p> +The default behavior for comparing typeinfo names changed, so +in <code class="filename">typeinfo</code>, <code class="literal">__GXX_MERGED_TYPEINFO_NAMES</code> +now defaults to zero. +</p><p> Extensions modified: <code class="filename">ext/throw_allocator.h</code>. +</p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="abi.html">Prev</a> </td><td align="center"><a accesskey="u" href="appendix_porting.html">Up</a></td><td align="right"> <a accesskey="n" href="backwards.html">Next</a></td></tr><tr><td align="left" valign="top">ABI Policy and Guidelines </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Backwards Compatibility</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/appendix_contributing.html b/libstdc++-v3/doc/html/manual/appendix_contributing.html new file mode 100644 index 000000000..bbaadbdc7 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/appendix_contributing.html @@ -0,0 +1,117 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Appendix A. Contributing</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="bk01pt04.html" title="Part IV. Appendices"/><link rel="prev" href="bk01pt04.html" title="Part IV. Appendices"/><link rel="next" href="source_organization.html" title="Directory Layout and Source Conventions"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Appendix A. + Contributing + +</th></tr><tr><td align="left"><a accesskey="p" href="bk01pt04.html">Prev</a> </td><th width="60%" align="center">Part IV. + Appendices +</th><td align="right"> <a accesskey="n" href="source_organization.html">Next</a></td></tr></table><hr/></div><div class="appendix" title="Appendix A. Contributing"><div class="titlepage"><div><div><h1 class="title"><a id="appendix.contrib"/> + Contributing + <a id="id492936" class="indexterm"/> +</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="appendix_contributing.html#contrib.list">Contributor Checklist</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_contributing.html#list.reading">Reading</a></span></dt><dt><span class="section"><a href="appendix_contributing.html#list.copyright">Assignment</a></span></dt><dt><span class="section"><a href="appendix_contributing.html#list.getting">Getting Sources</a></span></dt><dt><span class="section"><a href="appendix_contributing.html#list.patches">Submitting Patches</a></span></dt></dl></dd><dt><span class="section"><a href="source_organization.html">Directory Layout and Source Conventions</a></span></dt><dt><span class="section"><a href="source_code_style.html">Coding Style</a></span></dt><dd><dl><dt><span class="section"><a href="source_code_style.html#coding_style.bad_identifiers">Bad Identifiers</a></span></dt><dt><span class="section"><a href="source_code_style.html#coding_style.example">By Example</a></span></dt></dl></dd><dt><span class="section"><a href="source_design_notes.html">Design Notes</a></span></dt></dl></div><p> + The GNU C++ Library follows an open development model. Active + contributors are assigned maintainer-ship responsibility, and given + write access to the source repository. First time contributors + should follow this procedure: +</p><div class="section" title="Contributor Checklist"><div class="titlepage"><div><div><h2 class="title"><a id="contrib.list"/>Contributor Checklist</h2></div></div></div><div class="section" title="Reading"><div class="titlepage"><div><div><h3 class="title"><a id="list.reading"/>Reading</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + Get and read the relevant sections of the C++ language + specification. Copies of the full ISO 14882 standard are + available on line via the ISO mirror site for committee + members. Non-members, or those who have not paid for the + privilege of sitting on the committee and sustained their + two meeting commitment for voting rights, may get a copy of + the standard from their respective national standards + organization. In the USA, this national standards + organization is ANSI and their web-site is right + <a class="link" href="http://www.ansi.org">here.</a> + (And if you've already registered with them, clicking this link will take you to directly to the place where you can + <a class="link" href="http://webstore.ansi.org/RecordDetail.aspx?sku=ISO%2FIEC+14882:2003">buy the standard on-line</a>.) + </p></li><li class="listitem"><p> + The library working group bugs, and known defects, can + be obtained here: + <a class="link" href="http://www.open-std.org/jtc1/sc22/wg21/">http://www.open-std.org/jtc1/sc22/wg21 </a> + </p></li><li class="listitem"><p> + The newsgroup dedicated to standardization issues is + comp.std.c++: this FAQ for this group is quite useful and + can be + found <a class="link" href="http://www.comeaucomputing.com/csc/faq.html"> + here </a>. + </p></li><li class="listitem"><p> + Peruse + the <a class="link" href="http://www.gnu.org/prep/standards">GNU + Coding Standards</a>, and chuckle when you hit the part + about <span class="quote">“<span class="quote">Using Languages Other Than C</span>”</span>. + </p></li><li class="listitem"><p> + Be familiar with the extensions that preceded these + general GNU rules. These style issues for libstdc++ can be + found <a class="link" href="source_code_style.html" title="Coding Style">here</a>. + </p></li><li class="listitem"><p> + And last but certainly not least, read the + library-specific information + found <a class="link" href="appendix_porting.html" title="Appendix B. Porting and Maintenance"> here</a>. + </p></li></ul></div></div><div class="section" title="Assignment"><div class="titlepage"><div><div><h3 class="title"><a id="list.copyright"/>Assignment</h3></div></div></div><p> + Small changes can be accepted without a copyright assignment form on + file. New code and additions to the library need completed copyright + assignment form on file at the FSF. Note: your employer may be required + to fill out appropriate disclaimer forms as well. + </p><p> + Historically, the libstdc++ assignment form added the following + question: + </p><p> + <span class="quote">“<span class="quote"> + Which Belgian comic book character is better, Tintin or Asterix, and + why? + </span>”</span> + </p><p> + While not strictly necessary, humoring the maintainers and answering + this question would be appreciated. + </p><p> + For more information about getting a copyright assignment, please see + <a class="link" href="http://www.gnu.org/prep/maintain/html_node/Legal-Matters.html">Legal + Matters</a>. + </p><p> + Please contact Benjamin Kosnik at + <code class="email"><<a class="email" href="mailto:bkoz+assign@redhat.com">bkoz+assign@redhat.com</a>></code> if you are confused + about the assignment or have general licensing questions. When + requesting an assignment form from + <code class="email"><<a class="email" href="mailto:mailto:assign@gnu.org">mailto:assign@gnu.org</a>></code>, please cc the libstdc++ + maintainer above so that progress can be monitored. + </p></div><div class="section" title="Getting Sources"><div class="titlepage"><div><div><h3 class="title"><a id="list.getting"/>Getting Sources</h3></div></div></div><p> + <a class="link" href="http://gcc.gnu.org/svnwrite.html">Getting write access + (look for "Write after approval")</a> + </p></div><div class="section" title="Submitting Patches"><div class="titlepage"><div><div><h3 class="title"><a id="list.patches"/>Submitting Patches</h3></div></div></div><p> + Every patch must have several pieces of information before it can be + properly evaluated. Ideally (and to ensure the fastest possible + response from the maintainers) it would have all of these pieces: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + A description of the bug and how your patch fixes this + bug. For new features a description of the feature and your + implementation. + </p></li><li class="listitem"><p> + A ChangeLog entry as plain text; see the various + ChangeLog files for format and content. If you are + using emacs as your editor, simply position the insertion + point at the beginning of your change and hit CX-4a to bring + up the appropriate ChangeLog entry. See--magic! Similar + functionality also exists for vi. + </p></li><li class="listitem"><p> + A testsuite submission or sample program that will + easily and simply show the existing error or test new + functionality. + </p></li><li class="listitem"><p> + The patch itself. If you are accessing the SVN + repository use <span class="command"><strong>svn update; svn diff NEW</strong></span>; + else, use <span class="command"><strong>diff -cp OLD NEW</strong></span> ... If your + version of diff does not support these options, then get the + latest version of GNU + diff. The <a class="link" href="http://gcc.gnu.org/wiki/SvnTricks">SVN + Tricks</a> wiki page has information on customising the + output of <code class="code">svn diff</code>. + </p></li><li class="listitem"><p> + When you have all these pieces, bundle them up in a + mail message and send it to libstdc++@gcc.gnu.org. All + patches and related discussion should be sent to the + libstdc++ mailing list. + </p></li></ul></div></div></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="bk01pt04.html">Prev</a> </td><td align="center"><a accesskey="u" href="bk01pt04.html">Up</a></td><td align="right"> <a accesskey="n" href="source_organization.html">Next</a></td></tr><tr><td align="left" valign="top">Part IV. + Appendices + </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Directory Layout and Source Conventions</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/appendix_free.html b/libstdc++-v3/doc/html/manual/appendix_free.html new file mode 100644 index 000000000..84f44035d --- /dev/null +++ b/libstdc++-v3/doc/html/manual/appendix_free.html @@ -0,0 +1,126 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Appendix C. Free Software Needs Free Documentation</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="bk01pt04.html" title="Part IV. Appendices"/><link rel="prev" href="backwards.html" title="Backwards Compatibility"/><link rel="next" href="appendix_gpl.html" title="Appendix D. GNU General Public License version 3"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Appendix C. + Free Software Needs Free Documentation + +</th></tr><tr><td align="left"><a accesskey="p" href="backwards.html">Prev</a> </td><th width="60%" align="center">Part IV. + Appendices +</th><td align="right"> <a accesskey="n" href="appendix_gpl.html">Next</a></td></tr></table><hr/></div><div class="appendix" title="Appendix C. Free Software Needs Free Documentation"><div class="titlepage"><div><div><h1 class="title"><a id="appendix.free"/> + Free Software Needs Free Documentation + <a id="id505314" class="indexterm"/> +</h1></div></div></div><p> +The biggest deficiency in free operating systems is not in the +software--it is the lack of good free manuals that we can include in +these systems. Many of our most important programs do not come with +full manuals. Documentation is an essential part of any software +package; when an important free software package does not come with a +free manual, that is a major gap. We have many such gaps today. +</p><p> +Once upon a time, many years ago, I thought I would learn Perl. I got +a copy of a free manual, but I found it hard to read. When I asked +Perl users about alternatives, they told me that there were better +introductory manuals--but those were not free. +</p><p> +Why was this? The authors of the good manuals had written them for +O'Reilly Associates, which published them with restrictive terms--no +copying, no modification, source files not available--which exclude +them from the free software community. +</p><p> +That wasn't the first time this sort of thing has happened, and (to +our community's great loss) it was far from the last. Proprietary +manual publishers have enticed a great many authors to restrict their +manuals since then. Many times I have heard a GNU user eagerly tell +me about a manual that he is writing, with which he expects to help +the GNU project--and then had my hopes dashed, as he proceeded to +explain that he had signed a contract with a publisher that would +restrict it so that we cannot use it. +</p><p> +Given that writing good English is a rare skill among programmers, we +can ill afford to lose manuals this way. +</p><p> + Free documentation, like free software, is a matter of freedom, +not price. The problem with these manuals was not that O'Reilly +Associates charged a price for printed copies--that in itself is fine. +(The Free Software Foundation <a class="link" href="http://www.gnu.org/doc/doc.html">sells printed copies</a> of +free GNU manuals, too.) But GNU manuals are available in source code +form, while these manuals are available only on paper. GNU manuals +come with permission to copy and modify; the Perl manuals do not. +These restrictions are the problems. +</p><p> +The criterion for a free manual is pretty much the same as for free +software: it is a matter of giving all users certain freedoms. +Redistribution (including commercial redistribution) must be +permitted, so that the manual can accompany every copy of the program, +on-line or on paper. Permission for modification is crucial too. +</p><p> +As a general rule, I don't believe that it is essential for people to +have permission to modify all sorts of articles and books. The issues +for writings are not necessarily the same as those for software. For +example, I don't think you or I are obliged to give permission to +modify articles like this one, which describe our actions and our +views. +</p><p> +But there is a particular reason why the freedom to modify is crucial +for documentation for free software. When people exercise their right +to modify the software, and add or change its features, if they are +conscientious they will change the manual too--so they can provide +accurate and usable documentation with the modified program. A manual +which forbids programmers to be conscientious and finish the job, or +more precisely requires them to write a new manual from scratch if +they change the program, does not fill our community's needs. +</p><p> +While a blanket prohibition on modification is unacceptable, some +kinds of limits on the method of modification pose no problem. For +example, requirements to preserve the original author's copyright +notice, the distribution terms, or the list of authors, are ok. It is +also no problem to require modified versions to include notice that +they were modified, even to have entire sections that may not be +deleted or changed, as long as these sections deal with nontechnical +topics. (Some GNU manuals have them.) +</p><p> +These kinds of restrictions are not a problem because, as a practical +matter, they don't stop the conscientious programmer from adapting the +manual to fit the modified program. In other words, they don't block +the free software community from making full use of the manual. +</p><p> +However, it must be possible to modify all the <span class="emphasis"><em>technical</em></span> +content of the manual, and then distribute the result in all the usual +media, through all the usual channels; otherwise, the restrictions do +block the community, the manual is not free, and so we need another +manual. +</p><p> +Unfortunately, it is often hard to find someone to write another +manual when a proprietary manual exists. The obstacle is that many +users think that a proprietary manual is good enough--so they don't +see the need to write a free manual. They do not see that the free +operating system has a gap that needs filling. +</p><p> +Why do users think that proprietary manuals are good enough? Some +have not considered the issue. I hope this article will do something +to change that. +</p><p> +Other users consider proprietary manuals acceptable for the same +reason so many people consider proprietary software acceptable: they +judge in purely practical terms, not using freedom as a criterion. +These people are entitled to their opinions, but since those opinions +spring from values which do not include freedom, they are no guide for +those of us who do value freedom. +</p><p> +Please spread the word about this issue. We continue to lose manuals +to proprietary publishing. If we spread the word that proprietary +manuals are not sufficient, perhaps the next person who wants to help +GNU by writing documentation will realize, before it is too late, that +he must above all make it free. +</p><p> +We can also encourage commercial publishers to sell free, copylefted +manuals instead of proprietary ones. One way you can help this is to +check the distribution terms of a manual before you buy it, and +prefer copylefted manuals to non-copylefted ones. +</p><p> +[Note: We now maintain a <a class="link" href="http://www.fsf.org/licensing/doc/other-free-books.html">web page +that lists free books available from other publishers</a>]. +</p><p>Copyright © 2004, 2005, 2006, 2007 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA</p><p>Verbatim copying and distribution of this entire article are +permitted worldwide, without royalty, in any medium, provided this +notice is preserved.</p><p>Report any problems or suggestions to <code class="email"><<a class="email" href="mailto:webmaster@fsf.org">webmaster@fsf.org</a>></code>.</p></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="backwards.html">Prev</a> </td><td align="center"><a accesskey="u" href="bk01pt04.html">Up</a></td><td align="right"> <a accesskey="n" href="appendix_gpl.html">Next</a></td></tr><tr><td align="left" valign="top">Backwards Compatibility </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Appendix D. + <acronym class="acronym">GNU</acronym> General Public License version 3 + </td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/appendix_gfdl.html b/libstdc++-v3/doc/html/manual/appendix_gfdl.html new file mode 100644 index 000000000..9a46f18d1 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/appendix_gfdl.html @@ -0,0 +1,449 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Appendix E. GNU Free Documentation License</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="bk01pt04.html" title="Part IV. Appendices"/><link rel="prev" href="appendix_gpl.html" title="Appendix D. GNU General Public License version 3"/><link rel="next" href="../bk02.html" title=""/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Appendix E. GNU Free Documentation License</th></tr><tr><td align="left"><a accesskey="p" href="appendix_gpl.html">Prev</a> </td><th width="60%" align="center">Part IV. + Appendices +</th><td align="right"> <a accesskey="n" href="../bk02.html">Next</a></td></tr></table><hr/></div><div class="appendix" title="Appendix E. GNU Free Documentation License"><div class="titlepage"><div><div><h1 class="title"><a id="appendix.gfdl-1.3"/>GNU Free Documentation License</h1></div></div></div><p>Version 1.3, 3 November 2008</p><p> + Copyright © 2000, 2001, 2002, 2007, 2008 + <a class="link" href="http://www.fsf.org/">Free Software Foundation, Inc.</a> + </p><p> + Everyone is permitted to copy and distribute verbatim copies of this + license document, but changing it is not allowed. + </p><h3><a id="fdl-1-section0"/> + 0. PREAMBLE + </h3><p> + The purpose of this License is to make a manual, textbook, or other + functional and useful document “free” in the sense of freedom: + to assure everyone the effective freedom to copy and redistribute it, with + or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the author and + publisher a way to get credit for their work, while not being considered + responsible for modifications made by others. + </p><p> + This License is a kind of “copyleft”, which means that + derivative works of the document must themselves be free in the same + sense. It complements the GNU General Public License, which is a copyleft + license designed for free software. + </p><p> + We have designed this License in order to use it for manuals for free + software, because free software needs free documentation: a free program + should come with manuals providing the same freedoms that the software + does. But this License is not limited to software manuals; it can be used + for any textual work, regardless of subject matter or whether it is + published as a printed book. We recommend this License principally for + works whose purpose is instruction or reference. + </p><h3><a id="fdl-1-section1"/> + 1. APPLICABILITY AND DEFINITIONS + </h3><p> + This License applies to any manual or other work, in any medium, that + contains a notice placed by the copyright holder saying it can be + distributed under the terms of this License. Such a notice grants a + world-wide, royalty-free license, unlimited in duration, to use that work + under the conditions stated herein. The “Document”, below, + refers to any such manual or work. Any member of the public is a licensee, + and is addressed as “you”. You accept the license if you copy, + modify or distribute the work in a way requiring permission under + copyright law. + </p><p> + A “Modified Version” of the Document means any work containing + the Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + </p><p> + A “Secondary Section” is a named appendix or a front-matter + section of the Document that deals exclusively with the relationship of + the publishers or authors of the Document to the Document’s overall + subject (or to related matters) and contains nothing that could fall + directly within that overall subject. (Thus, if the Document is in part a + textbook of mathematics, a Secondary Section may not explain any + mathematics.) The relationship could be a matter of historical connection + with the subject or with related matters, or of legal, commercial, + philosophical, ethical or political position regarding them. + </p><p> + The “Invariant Sections” are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in the notice + that says that the Document is released under this License. If a section + does not fit the above definition of Secondary then it is not allowed to + be designated as Invariant. The Document may contain zero Invariant + Sections. If the Document does not identify any Invariant Sections then + there are none. + </p><p> + The “Cover Texts” are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says + that the Document is released under this License. A Front-Cover Text may + be at most 5 words, and a Back-Cover Text may be at most 25 words. + </p><p> + A “Transparent” copy of the Document means a machine-readable + copy, represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images composed of + pixels) generic paint programs or (for drawings) some widely available + drawing editor, and that is suitable for input to text formatters or for + automatic translation to a variety of formats suitable for input to text + formatters. A copy made in an otherwise Transparent file format whose + markup, or absence of markup, has been arranged to thwart or discourage + subsequent modification by readers is not Transparent. An image format is + not Transparent if used for any substantial amount of text. A copy that is + not “Transparent” is called “Opaque”. + </p><p> + Examples of suitable formats for Transparent copies include plain ASCII + without markup, Texinfo input format, LaTeX input format, SGML or XML + using a publicly available DTD, and standard-conforming simple HTML, + PostScript or PDF designed for human modification. Examples of transparent + image formats include PNG, XCF and JPG. Opaque formats include proprietary + formats that can be read and edited only by proprietary word processors, + SGML or XML for which the DTD and/or processing tools are not generally + available, and the machine-generated HTML, PostScript or PDF produced by + some word processors for output purposes only. + </p><p> + The “Title Page” means, for a printed book, the title page + itself, plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For works in + formats which do not have any title page as such, “Title Page” + means the text near the most prominent appearance of the work’s + title, preceding the beginning of the body of the text. + </p><p> + The “publisher” means any person or entity that distributes + copies of the Document to the public. + </p><p> + A section “Entitled XYZ” means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ stands + for a specific section name mentioned below, such as + “Acknowledgements”, “Dedications”, + “Endorsements”, or “History”.) To “Preserve + the Title” of such a section when you modify the Document means that + it remains a section “Entitled XYZ” according to this + definition. + </p><p> + The Document may include Warranty Disclaimers next to the notice which + states that this License applies to the Document. These Warranty + Disclaimers are considered to be included by reference in this License, + but only as regards disclaiming warranties: any other implication that + these Warranty Disclaimers may have is void and has no effect on the + meaning of this License. + </p><h3><a id="fdl-1-section2"/> + 2. VERBATIM COPYING + </h3><p> + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the copyright + notices, and the license notice saying this License applies to the + Document are reproduced in all copies, and that you add no other + conditions whatsoever to those of this License. You may not use technical + measures to obstruct or control the reading or further copying of the + copies you make or distribute. However, you may accept compensation in + exchange for copies. If you distribute a large enough number of copies you + must also follow the conditions in section 3. + </p><p> + You may also lend copies, under the same conditions stated above, and you + may publicly display copies. + </p><h3><a id="fdl-1-section3"/> + 3. COPYING IN QUANTITY + </h3><p> + If you publish printed copies (or copies in media that commonly have + printed covers) of the Document, numbering more than 100, and the + Document’s license notice requires Cover Texts, you must enclose + the copies in covers that carry, clearly and legibly, all these Cover + Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the + back cover. Both covers must also clearly and legibly identify you as the + publisher of these copies. The front cover must present the full title + with all words of the title equally prominent and visible. You may add + other material on the covers in addition. Copying with changes limited to + the covers, as long as they preserve the title of the Document and satisfy + these conditions, can be treated as verbatim copying in other respects. + </p><p> + If the required texts for either cover are too voluminous to fit legibly, + you should put the first ones listed (as many as fit reasonably) on the + actual cover, and continue the rest onto adjacent pages. + </p><p> + If you publish or distribute Opaque copies of the Document numbering more + than 100, you must either include a machine-readable Transparent copy + along with each Opaque copy, or state in or with each Opaque copy a + computer-network location from which the general network-using public has + access to download using public-standard network protocols a complete + Transparent copy of the Document, free of added material. If you use the + latter option, you must take reasonably prudent steps, when you begin + distribution of Opaque copies in quantity, to ensure that this Transparent + copy will remain thus accessible at the stated location until at least one + year after the last time you distribute an Opaque copy (directly or + through your agents or retailers) of that edition to the public. + </p><p> + It is requested, but not required, that you contact the authors of the + Document well before redistributing any large number of copies, to give + them a chance to provide you with an updated version of the Document. + </p><h3><a id="fdl-1-section4"/> + 4. MODIFICATIONS + </h3><p> + You may copy and distribute a Modified Version of the Document under the + conditions of sections 2 and 3 above, provided that you release the + Modified Version under precisely this License, with the Modified Version + filling the role of the Document, thus licensing distribution and + modification of the Modified Version to whoever possesses a copy of it. In + addition, you must do these things in the Modified Version: + </p><div class="orderedlist"><ol class="orderedlist"><li class="listitem"> + Use in the Title Page (and on the covers, if any) a title distinct + from that of the Document, and from those of previous versions (which + should, if there were any, be listed in the History section of the + Document). You may use the same title as a previous version if the + original publisher of that version gives permission. + </li><li class="listitem"> + List on the Title Page, as authors, one or more persons or entities + responsible for authorship of the modifications in the Modified + Version, together with at least five of the principal authors of the + Document (all of its principal authors, if it has fewer than five), + unless they release you from this requirement. + </li><li class="listitem"> + State on the Title page the name of the publisher of the Modified + Version, as the publisher. + </li><li class="listitem"> + Preserve all the copyright notices of the Document. + </li><li class="listitem"> + Add an appropriate copyright notice for your modifications adjacent to + the other copyright notices. + </li><li class="listitem"> + Include, immediately after the copyright notices, a license notice + giving the public permission to use the Modified Version under the + terms of this License, in the form shown in the Addendum below. + </li><li class="listitem"> + Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document’s license + notice. + </li><li class="listitem"> + Include an unaltered copy of this License. + </li><li class="listitem"> + Preserve the section Entitled “History”, Preserve its + Title, and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on the Title + Page. If there is no section Entitled “History” in the + Document, create one stating the title, year, authors, and publisher + of the Document as given on its Title Page, then add an item + describing the Modified Version as stated in the previous sentence. + </li><li class="listitem"> + Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise the + network locations given in the Document for previous versions it was + based on. These may be placed in the “History” + section. You may omit a network location for a work that was published + at least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. + </li><li class="listitem"> + For any section Entitled “Acknowledgements” or + “Dedications”, Preserve the Title of the section, and + preserve in the section all the substance and tone of each of the + contributor acknowledgements and/or dedications given therein. + </li><li class="listitem"> + Preserve all the Invariant Sections of the Document, unaltered in + their text and in their titles. Section numbers or the equivalent are + not considered part of the section titles. + </li><li class="listitem"> + Delete any section Entitled “Endorsements”. Such a section + may not be included in the Modified Version. + </li><li class="listitem"> + Do not retitle any existing section to be Entitled + “Endorsements” or to conflict in title with any Invariant + Section. + </li><li class="listitem"> + Preserve any Warranty Disclaimers. + </li></ol></div><p> + If the Modified Version includes new front-matter sections or appendices + that qualify as Secondary Sections and contain no material copied from the + Document, you may at your option designate some or all of these sections + as invariant. To do this, add their titles to the list of Invariant + Sections in the Modified Version’s license notice. These titles + must be distinct from any other section titles. + </p><p> + You may add a section Entitled “Endorsements”, provided it + contains nothing but endorsements of your Modified Version by various + parties — for example, statements of peer review or that the text + has been approved by an organization as the authoritative definition of a + standard. + </p><p> + You may add a passage of up to five words as a Front-Cover Text, and a + passage of up to 25 words as a Back-Cover Text, to the end of the list of + Cover Texts in the Modified Version. Only one passage of Front-Cover Text + and one of Back-Cover Text may be added by (or through arrangements made + by) any one entity. If the Document already includes a cover text for the + same cover, previously added by you or by arrangement made by the same + entity you are acting on behalf of, you may not add another; but you may + replace the old one, on explicit permission from the previous publisher + that added the old one. + </p><p> + The author(s) and publisher(s) of the Document do not by this License give + permission to use their names for publicity for or to assert or imply + endorsement of any Modified Version. + </p><h3><a id="fdl-1-section5"/> + 5. COMBINING DOCUMENTS + </h3><p> + You may combine the Document with other documents released under this + License, under the terms defined in section 4 above for modified versions, + provided that you include in the combination all of the Invariant Sections + of all of the original documents, unmodified, and list them all as + Invariant Sections of your combined work in its license notice, and that + you preserve all their Warranty Disclaimers. + </p><p> + The combined work need only contain one copy of this License, and multiple + identical Invariant Sections may be replaced with a single copy. If there + are multiple Invariant Sections with the same name but different contents, + make the title of each such section unique by adding at the end of it, in + parentheses, the name of the original author or publisher of that section + if known, or else a unique number. Make the same adjustment to the section + titles in the list of Invariant Sections in the license notice of the + combined work. + </p><p> + In the combination, you must combine any sections Entitled + “History” in the various original documents, forming one + section Entitled “History”; likewise combine any sections + Entitled “Acknowledgements”, and any sections Entitled + “Dedications”. You must delete all sections Entitled + “Endorsements”. + </p><h3><a id="fdl-1-section6"/> + 6. COLLECTIONS OF DOCUMENTS + </h3><p> + You may make a collection consisting of the Document and other documents + released under this License, and replace the individual copies of this + License in the various documents with a single copy that is included in + the collection, provided that you follow the rules of this License for + verbatim copying of each of the documents in all other respects. + </p><p> + You may extract a single document from such a collection, and distribute + it individually under this License, provided you insert a copy of this + License into the extracted document, and follow this License in all other + respects regarding verbatim copying of that document. + </p><h3><a id="fdl-1-section7"/> + 7. AGGREGATION WITH INDEPENDENT WORKS + </h3><p> + A compilation of the Document or its derivatives with other separate and + independent documents or works, in or on a volume of a storage or + distribution medium, is called an “aggregate” if the copyright + resulting from the compilation is not used to limit the legal rights of + the compilation’s users beyond what the individual works + permit. When the Document is included in an aggregate, this License does + not apply to the other works in the aggregate which are not themselves + derivative works of the Document. + </p><p> + If the Cover Text requirement of section 3 is applicable to these copies + of the Document, then if the Document is less than one half of the entire + aggregate, the Document’s Cover Texts may be placed on covers that + bracket the Document within the aggregate, or the electronic equivalent of + covers if the Document is in electronic form. Otherwise they must appear + on printed covers that bracket the whole aggregate. + </p><h3><a id="fdl-1-section8"/> + 8. TRANSLATION + </h3><p> + Translation is considered a kind of modification, so you may distribute + translations of the Document under the terms of section 4. Replacing + Invariant Sections with translations requires special permission from + their copyright holders, but you may include translations of some or all + Invariant Sections in addition to the original versions of these Invariant + Sections. You may include a translation of this License, and all the + license notices in the Document, and any Warranty Disclaimers, provided + that you also include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of this + License or a notice or disclaimer, the original version will prevail. + </p><p> + If a section in the Document is Entitled “Acknowledgements”, + “Dedications”, or “History”, the requirement + (section 4) to Preserve its Title (section 1) will typically require + changing the actual title. + </p><h3><a id="fdl-1-section9"/> + 9. TERMINATION + </h3><p> + You may not copy, modify, sublicense, or distribute the Document except as + expressly provided under this License. Any attempt otherwise to copy, + modify, sublicense, or distribute it is void, and will automatically + terminate your rights under this License. + </p><p> + However, if you cease all violation of this License, then your license + from a particular copyright holder is reinstated (a) provisionally, unless + and until the copyright holder explicitly and finally terminates your + license, and (b) permanently, if the copyright holder fails to notify you + of the violation by some reasonable means prior to 60 days after the + cessation. + </p><p> + Moreover, your license from a particular copyright holder is reinstated + permanently if the copyright holder notifies you of the violation by some + reasonable means, this is the first time you have received notice of + violation of this License (for any work) from that copyright holder, and + you cure the violation prior to 30 days after your receipt of the notice. + </p><p> + Termination of your rights under this section does not terminate the + licenses of parties who have received copies or rights from you under this + License. If your rights have been terminated and not permanently + reinstated, receipt of a copy of some or all of the same material does not + give you any rights to use it. + </p><h3><a id="fdl-1-section10"/> + 10. FUTURE REVISIONS OF THIS LICENSE + </h3><p> + The Free Software Foundation may publish new, revised versions of the GNU + Free Documentation License from time to time. Such new versions will be + similar in spirit to the present version, but may differ in detail to + address new problems or concerns. See + <a class="link" href="http://www.gnu.org/copyleft/">Copyleft</a>. + </p><p> + Each version of the License is given a distinguishing version number. If + the Document specifies that a particular numbered version of this License + “or any later version” applies to it, you have the option of + following the terms and conditions either of that specified version or of + any later version that has been published (not as a draft) by the Free + Software Foundation. If the Document does not specify a version number of + this License, you may choose any version ever published (not as a draft) + by the Free Software Foundation. If the Document specifies that a proxy + can decide which future versions of this License can be used, that + proxy’s public statement of acceptance of a version permanently + authorizes you to choose that version for the Document. + </p><h3><a id="fdl-1-section11"/> + 11. RELICENSING + </h3><p> + “Massive Multiauthor Collaboration Site” (or “MMC + Site”) means any World Wide Web server that publishes copyrightable + works and also provides prominent facilities for anybody to edit those + works. A public wiki that anybody can edit is an example of such a + server. A “Massive Multiauthor Collaboration” (or + “MMC”) contained in the site means any set of copyrightable + works thus published on the MMC site. + </p><p> + “CC-BY-SA” means the Creative Commons Attribution-Share Alike + 3.0 license published by Creative Commons Corporation, a not-for-profit + corporation with a principal place of business in San Francisco, + California, as well as future copyleft versions of that license published + by that same organization. + </p><p> + “Incorporate” means to publish or republish a Document, in + whole or in part, as part of another Document. + </p><p> + An MMC is “eligible for relicensing” if it is licensed under + this License, and if all works that were first published under this + License somewhere other than this MMC, and subsequently incorporated in + whole or in part into the MMC, (1) had no cover texts or invariant + sections, and (2) were thus incorporated prior to November 1, 2008. + </p><p> + The operator of an MMC Site may republish an MMC contained in the site + under CC-BY-SA on the same site at any time before August 1, 2009, + provided the MMC is eligible for relicensing. + </p><h3><a id="fdl-1-addendum"/> + ADDENDUM: How to use this License for your documents + </h3><p> + To use this License in a document you have written, include a copy of the + License in the document and put the following copyright and license + notices just after the title page: + </p><pre class="screen">Copyright © YEAR YOUR NAME + +Permission is granted to copy, distribute and/or modify this document under the +terms of the GNU Free Documentation License, Version 1.3 or any later version +published by the Free Software Foundation; with no Invariant Sections, no +Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in +the section entitled “GNU Free Documentation License”.</pre><p> + If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, + replace the “with… Texts.” line with this: + </p><pre class="screen">with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts +being LIST, and with the Back-Cover Texts being LIST.</pre><p> + If you have Invariant Sections without Cover Texts, or some other + combination of the three, merge those two alternatives to suit the + situation. + </p><p> + If your document contains nontrivial examples of program code, we + recommend releasing these examples in parallel under your choice of free + software license, such as the GNU General Public License, to permit their + use in free software. + </p></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="appendix_gpl.html">Prev</a> </td><td align="center"><a accesskey="u" href="bk01pt04.html">Up</a></td><td align="right"> <a accesskey="n" href="../bk02.html">Next</a></td></tr><tr><td align="left" valign="top">Appendix D. + <acronym class="acronym">GNU</acronym> General Public License version 3 + </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> </td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/appendix_gpl.html b/libstdc++-v3/doc/html/manual/appendix_gpl.html new file mode 100644 index 000000000..58d1308dc --- /dev/null +++ b/libstdc++-v3/doc/html/manual/appendix_gpl.html @@ -0,0 +1,683 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Appendix D. GNU General Public License version 3</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="bk01pt04.html" title="Part IV. Appendices"/><link rel="prev" href="appendix_free.html" title="Appendix C. Free Software Needs Free Documentation"/><link rel="next" href="appendix_gfdl.html" title="Appendix E. GNU Free Documentation License"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Appendix D. + <acronym class="acronym">GNU</acronym> General Public License version 3 + </th></tr><tr><td align="left"><a accesskey="p" href="appendix_free.html">Prev</a> </td><th width="60%" align="center">Part IV. + Appendices +</th><td align="right"> <a accesskey="n" href="appendix_gfdl.html">Next</a></td></tr></table><hr/></div><div class="appendix" title="Appendix D. GNU General Public License version 3"><div class="titlepage"><div><div><h1 class="title"><a id="appendix.gpl-3.0"/> + <acronym class="acronym">GNU</acronym> General Public License version 3 + </h1></div></div></div><p> + Version 3, 29 June 2007 + </p><p> + Copyright © 2007 Free Software Foundation, Inc. + <a class="link" href="http://www.fsf.org/">http://www.fsf.org/</a> + </p><p> + Everyone is permitted to copy and distribute verbatim copies of this license + document, but changing it is not allowed. + </p><h2><a id="gpl-3-preamble"/> + Preamble + </h2><p> + The <acronym class="acronym">GNU</acronym> General Public License is a free, copyleft + license for software and other kinds of works. + </p><p> + The licenses for most software and other practical works are designed to + take away your freedom to share and change the works. By contrast, the + <acronym class="acronym">GNU</acronym> General Public License is intended to guarantee your + freedom to share and change all versions of a program—to make sure it + remains free software for all its users. We, the Free Software Foundation, + use the <acronym class="acronym">GNU</acronym> General Public License for most of our + software; it applies also to any other work released this way by its + authors. You can apply it to your programs, too. + </p><p> + When we speak of free software, we are referring to freedom, not price. Our + General Public Licenses are designed to make sure that you have the freedom + to distribute copies of free software (and charge for them if you wish), + that you receive source code or can get it if you want it, that you can + change the software or use pieces of it in new free programs, and that you + know you can do these things. + </p><p> + To protect your rights, we need to prevent others from denying you these + rights or asking you to surrender the rights. Therefore, you have certain + responsibilities if you distribute copies of the software, or if you modify + it: responsibilities to respect the freedom of others. + </p><p> + For example, if you distribute copies of such a program, whether gratis or + for a fee, you must pass on to the recipients the same freedoms that you + received. You must make sure that they, too, receive or can get the source + code. And you must show them these terms so they know their rights. + </p><p> + Developers that use the <acronym class="acronym">GNU</acronym> <acronym class="acronym">GPL</acronym> + protect your rights with two steps: (1) assert copyright on the software, + and (2) offer you this License giving you legal permission to copy, + distribute and/or modify it. + </p><p> + For the developers’ and authors’ protection, the + <acronym class="acronym">GPL</acronym> clearly explains that there is no warranty for this + free software. For both users’ and authors’ sake, the + <acronym class="acronym">GPL</acronym> requires that modified versions be marked as changed, + so that their problems will not be attributed erroneously to authors of + previous versions. + </p><p> + Some devices are designed to deny users access to install or run modified + versions of the software inside them, although the manufacturer can do so. + This is fundamentally incompatible with the aim of protecting users’ + freedom to change the software. The systematic pattern of such abuse occurs + in the area of products for individuals to use, which is precisely where it + is most unacceptable. Therefore, we have designed this version of the + <acronym class="acronym">GPL</acronym> to prohibit the practice for those products. If such + problems arise substantially in other domains, we stand ready to extend this + provision to those domains in future versions of the <acronym class="acronym">GPL</acronym>, + as needed to protect the freedom of users. + </p><p> + Finally, every program is threatened constantly by software patents. States + should not allow patents to restrict development and use of software on + general-purpose computers, but in those that do, we wish to avoid the + special danger that patents applied to a free program could make it + effectively proprietary. To prevent this, the <acronym class="acronym">GPL</acronym> + assures that patents cannot be used to render the program non-free. + </p><p> + The precise terms and conditions for copying, distribution and modification + follow. + </p><h2><a id="id505653"/> + TERMS AND CONDITIONS + </h2><h2><a id="gpl-3-definitions"/> + 0. Definitions. + </h2><p> + “This License” refers to version 3 of the <acronym class="acronym">GNU</acronym> + General Public License. + </p><p> + “Copyright” also means copyright-like laws that apply to other + kinds of works, such as semiconductor masks. + </p><p> + “The Program” refers to any copyrightable work licensed under + this License. Each licensee is addressed as “you”. + “Licensees” and “recipients” may be individuals or + organizations. + </p><p> + To “modify” a work means to copy from or adapt all or part of + the work in a fashion requiring copyright permission, other than the making + of an exact copy. The resulting work is called a “modified + version” of the earlier work or a work “based on” the + earlier work. + </p><p> + A “covered work” means either the unmodified Program or a work + based on the Program. + </p><p> + To “propagate” a work means to do anything with it that, without + permission, would make you directly or secondarily liable for infringement + under applicable copyright law, except executing it on a computer or + modifying a private copy. Propagation includes copying, distribution (with + or without modification), making available to the public, and in some + countries other activities as well. + </p><p> + To “convey” a work means any kind of propagation that enables + other parties to make or receive copies. Mere interaction with a user + through a computer network, with no transfer of a copy, is not conveying. + </p><p> + An interactive user interface displays “Appropriate Legal + Notices” to the extent that it includes a convenient and prominently + visible feature that (1) displays an appropriate copyright notice, and (2) + tells the user that there is no warranty for the work (except to the extent + that warranties are provided), that licensees may convey the work under this + License, and how to view a copy of this License. If the interface presents + a list of user commands or options, such as a menu, a prominent item in the + list meets this criterion. + </p><h2><a id="SourceCode"/> + 1. Source Code. + </h2><p> + The “source code” for a work means the preferred form of the + work for making modifications to it. “Object code” means any + non-source form of a work. + </p><p> + A “Standard Interface” means an interface that either is an + official standard defined by a recognized standards body, or, in the case of + interfaces specified for a particular programming language, one that is + widely used among developers working in that language. + </p><p> + The “System Libraries” of an executable work include anything, + other than the work as a whole, that (a) is included in the normal form of + packaging a Major Component, but which is not part of that Major Component, + and (b) serves only to enable use of the work with that Major Component, or + to implement a Standard Interface for which an implementation is available + to the public in source code form. A “Major Component”, in this + context, means a major essential component (kernel, window system, and so + on) of the specific operating system (if any) on which the executable work + runs, or a compiler used to produce the work, or an object code interpreter + used to run it. + </p><p> + The “Corresponding Source” for a work in object code form means + all the source code needed to generate, install, and (for an executable + work) run the object code and to modify the work, including scripts to + control those activities. However, it does not include the work’s + System Libraries, or general-purpose tools or generally available free + programs which are used unmodified in performing those activities but which + are not part of the work. For example, Corresponding Source includes + interface definition files associated with source files for the work, and + the source code for shared libraries and dynamically linked subprograms that + the work is specifically designed to require, such as by intimate data + communication or control flow between those subprograms and other parts of + the work. + </p><p> + The Corresponding Source need not include anything that users can regenerate + automatically from other parts of the Corresponding Source. + </p><p> + The Corresponding Source for a work in source code form is that same work. + </p><h2><a id="BasicPermissions"/> + 2. Basic Permissions. + </h2><p> + All rights granted under this License are granted for the term of copyright + on the Program, and are irrevocable provided the stated conditions are met. + This License explicitly affirms your unlimited permission to run the + unmodified Program. The output from running a covered work is covered by + this License only if the output, given its content, constitutes a covered + work. This License acknowledges your rights of fair use or other + equivalent, as provided by copyright law. + </p><p> + You may make, run and propagate covered works that you do not convey, + without conditions so long as your license otherwise remains in force. You + may convey covered works to others for the sole purpose of having them make + modifications exclusively for you, or provide you with facilities for + running those works, provided that you comply with the terms of this License + in conveying all material for which you do not control copyright. Those + thus making or running the covered works for you must do so exclusively on + your behalf, under your direction and control, on terms that prohibit them + from making any copies of your copyrighted material outside their + relationship with you. + </p><p> + Conveying under any other circumstances is permitted solely under the + conditions stated below. Sublicensing is not allowed; section 10 makes it + unnecessary. + </p><h2><a id="Protecting"/> + 3. Protecting Users’ Legal Rights From Anti-Circumvention Law. + </h2><p> + No covered work shall be deemed part of an effective technological measure + under any applicable law fulfilling obligations under article 11 of the WIPO + copyright treaty adopted on 20 December 1996, or similar laws prohibiting or + restricting circumvention of such measures. + </p><p> + When you convey a covered work, you waive any legal power to forbid + circumvention of technological measures to the extent such circumvention is + effected by exercising rights under this License with respect to the covered + work, and you disclaim any intention to limit operation or modification of + the work as a means of enforcing, against the work’s users, your or + third parties’ legal rights to forbid circumvention of technological + measures. + </p><h2><a id="ConveyingVerbatim"/> + 4. Conveying Verbatim Copies. + </h2><p> + You may convey verbatim copies of the Program’s source code as you + receive it, in any medium, provided that you conspicuously and appropriately + publish on each copy an appropriate copyright notice; keep intact all + notices stating that this License and any non-permissive terms added in + accord with section 7 apply to the code; keep intact all notices of the + absence of any warranty; and give all recipients a copy of this License + along with the Program. + </p><p> + You may charge any price or no price for each copy that you convey, and you + may offer support or warranty protection for a fee. + </p><h2><a id="ConveyingModified"/> + 5. Conveying Modified Source Versions. + </h2><p> + You may convey a work based on the Program, or the modifications to produce + it from the Program, in the form of source code under the terms of section + 4, provided that you also meet all of these conditions: + </p><div class="orderedlist"><ol class="orderedlist"><li class="listitem"><p> + The work must carry prominent notices stating that you modified it, and + giving a relevant date. + </p></li><li class="listitem"><p> + The work must carry prominent notices stating that it is released under + this License and any conditions added under section 7. This requirement + modifies the requirement in section 4 to “keep intact all + notices”. + </p></li><li class="listitem"><p> + You must license the entire work, as a whole, under this License to + anyone who comes into possession of a copy. This License will therefore + apply, along with any applicable section 7 additional terms, to the + whole of the work, and all its parts, regardless of how they are + packaged. This License gives no permission to license the work in any + other way, but it does not invalidate such permission if you have + separately received it. + </p></li><li class="listitem"><p> + If the work has interactive user interfaces, each must display + Appropriate Legal Notices; however, if the Program has interactive + interfaces that do not display Appropriate Legal Notices, your work need + not make them do so. + </p></li></ol></div><p> + A compilation of a covered work with other separate and independent works, + which are not by their nature extensions of the covered work, and which are + not combined with it such as to form a larger program, in or on a volume of + a storage or distribution medium, is called an “aggregate” if + the compilation and its resulting copyright are not used to limit the access + or legal rights of the compilation’s users beyond what the individual works + permit. Inclusion of a covered work in an aggregate does not cause + this License to apply to the other parts of the aggregate. + </p><h2><a id="ConveyingNonSource"/> + 6. Conveying Non-Source Forms. + </h2><p> + You may convey a covered work in object code form under the terms of + sections 4 and 5, provided that you also convey the machine-readable + Corresponding Source under the terms of this License, in one of these ways: + </p><div class="orderedlist"><ol class="orderedlist"><li class="listitem"><p> + Convey the object code in, or embodied in, a physical product (including + a physical distribution medium), accompanied by the Corresponding Source + fixed on a durable physical medium customarily used for software + interchange. + </p></li><li class="listitem"><p> + Convey the object code in, or embodied in, a physical product (including + a physical distribution medium), accompanied by a written offer, valid + for at least three years and valid for as long as you offer spare parts + or customer support for that product model, to give anyone who possesses + the object code either (1) a copy of the Corresponding Source for all + the software in the product that is covered by this License, on a + durable physical medium customarily used for software interchange, for a + price no more than your reasonable cost of physically performing this + conveying of source, or (2) access to copy the Corresponding Source from + a network server at no charge. + </p></li><li class="listitem"><p> + Convey individual copies of the object code with a copy of the written + offer to provide the Corresponding Source. This alternative is allowed + only occasionally and noncommercially, and only if you received the + object code with such an offer, in accord with subsection 6b. + </p></li><li class="listitem"><p> + Convey the object code by offering access from a designated place + (gratis or for a charge), and offer equivalent access to the + Corresponding Source in the same way through the same place at no + further charge. You need not require recipients to copy the + Corresponding Source along with the object code. If the place to copy + the object code is a network server, the Corresponding Source may be on + a different server (operated by you or a third party) that supports + equivalent copying facilities, provided you maintain clear directions + next to the object code saying where to find the Corresponding Source. + Regardless of what server hosts the Corresponding Source, you remain + obligated to ensure that it is available for as long as needed to + satisfy these requirements. + </p></li><li class="listitem"><p> + Convey the object code using peer-to-peer transmission, provided you + inform other peers where the object code and Corresponding Source of the + work are being offered to the general public at no charge under + subsection 6d. + </p></li></ol></div><p> + A separable portion of the object code, whose source code is excluded from + the Corresponding Source as a System Library, need not be included in + conveying the object code work. + </p><p> + A “User Product” is either (1) a “consumer product”, + which means any tangible personal property which is normally used for + personal, family, or household purposes, or (2) anything designed or sold + for incorporation into a dwelling. In determining whether a product is a + consumer product, doubtful cases shall be resolved in favor of coverage. + For a particular product received by a particular user, “normally + used” refers to a typical or common use of that class of product, + regardless of the status of the particular user or of the way in which the + particular user actually uses, or expects or is expected to use, the + product. A product is a consumer product regardless of whether the product + has substantial commercial, industrial or non-consumer uses, unless such + uses represent the only significant mode of use of the product. + </p><p> + “Installation Information” for a User Product means any methods, + procedures, authorization keys, or other information required to install and + execute modified versions of a covered work in that User Product from a + modified version of its Corresponding Source. The information must suffice + to ensure that the continued functioning of the modified object code is in + no case prevented or interfered with solely because modification has been + made. + </p><p> + If you convey an object code work under this section in, or with, or + specifically for use in, a User Product, and the conveying occurs as part of + a transaction in which the right of possession and use of the User Product + is transferred to the recipient in perpetuity or for a fixed term + (regardless of how the transaction is characterized), the Corresponding + Source conveyed under this section must be accompanied by the Installation + Information. But this requirement does not apply if neither you nor any + third party retains the ability to install modified object code on the User + Product (for example, the work has been installed in + <acronym class="acronym">ROM</acronym>). + </p><p> + The requirement to provide Installation Information does not include a + requirement to continue to provide support service, warranty, or updates for + a work that has been modified or installed by the recipient, or for the User + Product in which it has been modified or installed. Access to a network may + be denied when the modification itself materially and adversely affects the + operation of the network or violates the rules and protocols for + communication across the network. + </p><p> + Corresponding Source conveyed, and Installation Information provided, in + accord with this section must be in a format that is publicly documented + (and with an implementation available to the public in source code form), + and must require no special password or key for unpacking, reading or + copying. + </p><h2><a id="AdditionalTerms"/> + 7. Additional Terms. + </h2><p> + “Additional permissions” are terms that supplement the terms of + this License by making exceptions from one or more of its conditions. + Additional permissions that are applicable to the entire Program shall be + treated as though they were included in this License, to the extent that + they are valid under applicable law. If additional permissions apply only + to part of the Program, that part may be used separately under those + permissions, but the entire Program remains governed by this License + without regard to the additional permissions. + </p><p> + When you convey a copy of a covered work, you may at your option remove any + additional permissions from that copy, or from any part of it. (Additional + permissions may be written to require their own removal in certain cases + when you modify the work.) You may place additional permissions on + material, added by you to a covered work, for which you have or can give + appropriate copyright permission. + </p><p> + Notwithstanding any other provision of this License, for material you add + to a covered work, you may (if authorized by the copyright holders of that + material) supplement the terms of this License with terms: + </p><div class="orderedlist"><ol class="orderedlist"><li class="listitem"><p> + Disclaiming warranty or limiting liability differently from the terms + of sections 15 and 16 of this License; or + </p></li><li class="listitem"><p> + Requiring preservation of specified reasonable legal notices or author + attributions in that material or in the Appropriate Legal Notices + displayed by works containing it; or + </p></li><li class="listitem"><p> + Prohibiting misrepresentation of the origin of that material, or + requiring that modified versions of such material be marked in + reasonable ways as different from the original version; or + </p></li><li class="listitem"><p> + Limiting the use for publicity purposes of names of licensors or + authors of the material; or + </p></li><li class="listitem"><p> + Declining to grant rights under trademark law for use of some trade + names, trademarks, or service marks; or + </p></li><li class="listitem"><p> + Requiring indemnification of licensors and authors of that material by + anyone who conveys the material (or modified versions of it) with + contractual assumptions of liability to the recipient, for any + liability that these contractual assumptions directly impose on those + licensors and authors. + </p></li></ol></div><p> + All other non-permissive additional terms are considered “further + restrictions” within the meaning of section 10. If the Program as + you received it, or any part of it, contains a notice stating that it is + governed by this License along with a term that is a further restriction, + you may remove that term. If a license document contains a further + restriction but permits relicensing or conveying under this License, you + may add to a covered work material governed by the terms of that license + document, provided that the further restriction does not survive such + relicensing or conveying. + </p><p> + If you add terms to a covered work in accord with this section, you must + place, in the relevant source files, a statement of the additional terms + that apply to those files, or a notice indicating where to find the + applicable terms. + </p><p> + Additional terms, permissive or non-permissive, may be stated in the form + of a separately written license, or stated as exceptions; the above + requirements apply either way. + </p><h2><a id="gpl-3-termination"/> + 8. Termination. + </h2><p> + You may not propagate or modify a covered work except as expressly provided + under this License. Any attempt otherwise to propagate or modify it is + void, and will automatically terminate your rights under this License + (including any patent licenses granted under the third paragraph of section + 11). + </p><p> + However, if you cease all violation of this License, then your license from + a particular copyright holder is reinstated (a) provisionally, unless and + until the copyright holder explicitly and finally terminates your license, + and (b) permanently, if the copyright holder fails to notify you of the + violation by some reasonable means prior to 60 days after the cessation. + </p><p> + Moreover, your license from a particular copyright holder is reinstated + permanently if the copyright holder notifies you of the violation by some + reasonable means, this is the first time you have received notice of + violation of this License (for any work) from that copyright holder, and + you cure the violation prior to 30 days after your receipt of the notice. + </p><p> + Termination of your rights under this section does not terminate the + licenses of parties who have received copies or rights from you under this + License. If your rights have been terminated and not permanently + reinstated, you do not qualify to receive new licenses for the same + material under section 10. + </p><h2><a id="AcceptanceNotRequired"/> + 9. Acceptance Not Required for Having Copies. + </h2><p> + You are not required to accept this License in order to receive or run a + copy of the Program. Ancillary propagation of a covered work occurring + solely as a consequence of using peer-to-peer transmission to receive a + copy likewise does not require acceptance. However, nothing other than + this License grants you permission to propagate or modify any covered work. + These actions infringe copyright if you do not accept this License. + Therefore, by modifying or propagating a covered work, you indicate your + acceptance of this License to do so. + </p><h2><a id="AutomaticDownstream"/> + 10. Automatic Licensing of Downstream Recipients. + </h2><p> + Each time you convey a covered work, the recipient automatically receives a + license from the original licensors, to run, modify and propagate that + work, subject to this License. You are not responsible for enforcing + compliance by third parties with this License. + </p><p> + An “entity transaction” is a transaction transferring control + of an organization, or substantially all assets of one, or subdividing an + organization, or merging organizations. If propagation of a covered work + results from an entity transaction, each party to that transaction who + receives a copy of the work also receives whatever licenses to the work the + party’s predecessor in interest had or could give under the previous + paragraph, plus a right to possession of the Corresponding Source of the + work from the predecessor in interest, if the predecessor has it or can get + it with reasonable efforts. + </p><p> + You may not impose any further restrictions on the exercise of the rights + granted or affirmed under this License. For example, you may not impose a + license fee, royalty, or other charge for exercise of rights granted under + this License, and you may not initiate litigation (including a cross-claim + or counterclaim in a lawsuit) alleging that any patent claim is infringed + by making, using, selling, offering for sale, or importing the Program or + any portion of it. + </p><h2><a id="Patents"/> + 11. Patents. + </h2><p> + A “contributor” is a copyright holder who authorizes use under + this License of the Program or a work on which the Program is based. The + work thus licensed is called the contributor’s “contributor + version”. + </p><p> + A contributor’s “essential patent claims” are all patent + claims owned or controlled by the contributor, whether already acquired or + hereafter acquired, that would be infringed by some manner, permitted by + this License, of making, using, or selling its contributor version, but do + not include claims that would be infringed only as a consequence of further + modification of the contributor version. For purposes of this definition, + “control” includes the right to grant patent sublicenses in a + manner consistent with the requirements of this License. + </p><p> + Each contributor grants you a non-exclusive, worldwide, royalty-free patent + license under the contributor’s essential patent claims, to make, use, + sell, offer for sale, import and otherwise run, modify and propagate the + contents of its contributor version. + </p><p> + In the following three paragraphs, a “patent license” is any + express agreement or commitment, however denominated, not to enforce a + patent (such as an express permission to practice a patent or covenant not + to sue for patent infringement). To “grant” such a patent + license to a party means to make such an agreement or commitment not to + enforce a patent against the party. + </p><p> + If you convey a covered work, knowingly relying on a patent license, and the + Corresponding Source of the work is not available for anyone to copy, free + of charge and under the terms of this License, through a publicly available + network server or other readily accessible means, then you must either (1) + cause the Corresponding Source to be so available, or (2) arrange to deprive + yourself of the benefit of the patent license for this particular work, or + (3) arrange, in a manner consistent with the requirements of this License, + to extend the patent license to downstream recipients. “Knowingly + relying” means you have actual knowledge that, but for the patent + license, your conveying the covered work in a country, or your + recipient’s use of the covered work in a country, would infringe one + or more identifiable patents in that country that you have reason to believe + are valid. + </p><p> + If, pursuant to or in connection with a single transaction or arrangement, + you convey, or propagate by procuring conveyance of, a covered work, and + grant a patent license to some of the parties receiving the covered work + authorizing them to use, propagate, modify or convey a specific copy of the + covered work, then the patent license you grant is automatically extended to + all recipients of the covered work and works based on it. + </p><p> + A patent license is “discriminatory” if it does not include + within the scope of its coverage, prohibits the exercise of, or is + conditioned on the non-exercise of one or more of the rights that are + specifically granted under this License. You may not convey a covered work + if you are a party to an arrangement with a third party that is in the + business of distributing software, under which you make payment to the third + party based on the extent of your activity of conveying the work, and under + which the third party grants, to any of the parties who would receive the + covered work from you, a discriminatory patent license (a) in connection + with copies of the covered work conveyed by you (or copies made from those + copies), or (b) primarily for and in connection with specific products or + compilations that contain the covered work, unless you entered into that + arrangement, or that patent license was granted, prior to 28 March 2007. + </p><p> + Nothing in this License shall be construed as excluding or limiting any + implied license or other defenses to infringement that may otherwise be + available to you under applicable patent law. + </p><h2><a id="NoSurrender"/> + 12. No Surrender of Others’ Freedom. + </h2><p> + If conditions are imposed on you (whether by court order, agreement or + otherwise) that contradict the conditions of this License, they do not + excuse you from the conditions of this License. If you cannot convey a + covered work so as to satisfy simultaneously your obligations under this + License and any other pertinent obligations, then as a consequence you may + not convey it at all. For example, if you agree to terms that obligate you + to collect a royalty for further conveying from those to whom you convey the + Program, the only way you could satisfy both those terms and this License + would be to refrain entirely from conveying the Program. + </p><h2><a id="UsedWithAGPL"/> + 13. Use with the <acronym class="acronym">GNU</acronym> Affero General Public License. + </h2><p> + Notwithstanding any other provision of this License, you have permission to + link or combine any covered work with a work licensed under version 3 of the + <acronym class="acronym">GNU</acronym> Affero General Public License into a single combined + work, and to convey the resulting work. The terms of this License will + continue to apply to the part which is the covered work, but the special + requirements of the <acronym class="acronym">GNU</acronym> Affero General Public License, + section 13, concerning interaction through a network will apply to the + combination as such. + </p><h2><a id="RevisedVersions"/> + 14. Revised Versions of this License. + </h2><p> + The Free Software Foundation may publish revised and/or new versions of the + <acronym class="acronym">GNU</acronym> General Public License from time to time. Such new + versions will be similar in spirit to the present version, but may differ in + detail to address new problems or concerns. + </p><p> + Each version is given a distinguishing version number. If the Program + specifies that a certain numbered version of the <acronym class="acronym">GNU</acronym> + General Public License “or any later version” applies to it, you + have the option of following the terms and conditions either of that + numbered version or of any later version published by the Free Software + Foundation. If the Program does not specify a version number of the + <acronym class="acronym">GNU</acronym> General Public License, you may choose any version + ever published by the Free Software Foundation. + </p><p> + If the Program specifies that a proxy can decide which future versions of + the <acronym class="acronym">GNU</acronym> General Public License can be used, that + proxy’s public statement of acceptance of a version permanently + authorizes you to choose that version for the Program. + </p><p> + Later license versions may give you additional or different permissions. + However, no additional obligations are imposed on any author or copyright + holder as a result of your choosing to follow a later version. + </p><h2><a id="WarrantyDisclaimer"/> + 15. Disclaimer of Warranty. + </h2><p> + THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE + LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR + OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF + ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. + THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH + YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL + NECESSARY SERVICING, REPAIR OR CORRECTION. + </p><h2><a id="LiabilityLimitation"/> + 16. Limitation of Liability. + </h2><p> + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL + ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE + PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY + GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE + OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA + OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD + PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), + EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF + SUCH DAMAGES. + </p><h2><a id="InterpretationSecs1516"/> + 17. Interpretation of Sections 15 and 16. + </h2><p> + If the disclaimer of warranty and limitation of liability provided above + cannot be given local legal effect according to their terms, reviewing + courts shall apply local law that most closely approximates an absolute + waiver of all civil liability in connection with the Program, unless a + warranty or assumption of liability accompanies a copy of the Program in + return for a fee. + </p><h2><a id="id506476"/> + END OF TERMS AND CONDITIONS + </h2><h2><a id="HowToApply"/> + How to Apply These Terms to Your New Programs + </h2><p> + If you develop a new program, and you want it to be of the greatest possible + use to the public, the best way to achieve this is to make it free software + which everyone can redistribute and change under these terms. + </p><p> + To do so, attach the following notices to the program. It is safest to + attach them to the start of each source file to most effectively state the + exclusion of warranty; and each file should have at least the + “copyright” line and a pointer to where the full notice is + found. + </p><pre class="screen"> +<em class="replaceable"><code>one line to give the program’s name and a brief idea of what it does.</code></em> +Copyright (C) <em class="replaceable"><code>year</code></em> <em class="replaceable"><code>name of author</code></em> + +This program is free software: you can redistribute it and/or modify +it under the terms of the <acronym class="acronym">GNU</acronym> General Public License as published by +the Free Software Foundation, either version 3 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +<acronym class="acronym">GNU</acronym> General Public License for more details. + +You should have received a copy of the <acronym class="acronym">GNU</acronym> General Public License +along with this program. If not, see <a class="link" href="http://www.gnu.org/licenses/">http://www.gnu.org/licenses/</a>. + </pre><p> + Also add information on how to contact you by electronic and paper mail. + </p><p> + If the program does terminal interaction, make it output a short notice like + this when it starts in an interactive mode: + </p><pre class="screen"> +<em class="replaceable"><code>program</code></em> Copyright (C) <em class="replaceable"><code>year</code></em> <em class="replaceable"><code>name of author</code></em> +This program comes with ABSOLUTELY NO WARRANTY; for details type ‘<code class="literal">show w</code>’. +This is free software, and you are welcome to redistribute it +under certain conditions; type ‘<code class="literal">show c</code>’ for details. + </pre><p> + The hypothetical commands ‘<code class="literal">show w</code>’ and + ‘<code class="literal">show c</code>’ should show the appropriate parts of + the General Public License. Of course, your program’s commands might be + different; for a GUI interface, you would use an “about box”. + </p><p> + You should also get your employer (if you work as a programmer) or school, + if any, to sign a “copyright disclaimer” for the program, if + necessary. For more information on this, and how to apply and follow the + <acronym class="acronym">GNU</acronym> <acronym class="acronym">GPL</acronym>, see + <a class="link" href="http://www.gnu.org/licenses/">http://www.gnu.org/licenses/</a>. + </p><p> + The <acronym class="acronym">GNU</acronym> General Public License does not permit + incorporating your program into proprietary programs. If your program is a + subroutine library, you may consider it more useful to permit linking + proprietary applications with the library. If this is what you want to do, + use the <acronym class="acronym">GNU</acronym> Lesser General Public License instead of this + License. But first, please read <a class="link" href="http://www.gnu.org/philosophy/why-not-lgpl.html">http://www.gnu.org/philosophy/why-not-lgpl.html</a>. + </p></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="appendix_free.html">Prev</a> </td><td align="center"><a accesskey="u" href="bk01pt04.html">Up</a></td><td align="right"> <a accesskey="n" href="appendix_gfdl.html">Next</a></td></tr><tr><td align="left" valign="top">Appendix C. + Free Software Needs Free Documentation + + </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Appendix E. GNU Free Documentation License</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/appendix_porting.html b/libstdc++-v3/doc/html/manual/appendix_porting.html new file mode 100644 index 000000000..8cb4398ff --- /dev/null +++ b/libstdc++-v3/doc/html/manual/appendix_porting.html @@ -0,0 +1,230 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Appendix B. Porting and Maintenance</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="bk01pt04.html" title="Part IV. Appendices"/><link rel="prev" href="source_design_notes.html" title="Design Notes"/><link rel="next" href="documentation_hacking.html" title="Writing and Generating Documentation"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Appendix B. + Porting and Maintenance + +</th></tr><tr><td align="left"><a accesskey="p" href="source_design_notes.html">Prev</a> </td><th width="60%" align="center">Part IV. + Appendices +</th><td align="right"> <a accesskey="n" href="documentation_hacking.html">Next</a></td></tr></table><hr/></div><div class="appendix" title="Appendix B. Porting and Maintenance"><div class="titlepage"><div><div><h1 class="title"><a id="appendix.porting"/> + Porting and Maintenance + <a id="id494054" class="indexterm"/> +</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="appendix_porting.html#appendix.porting.build_hacking">Configure and Build Hacking</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#build_hacking.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.map">Overview: What Comes from Where</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.scripts">Storing Information in non-AC files (like configure.host)</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.conventions">Coding and Commenting Conventions</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.acinclude">The acinclude.m4 layout</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.enable"><code class="constant">GLIBCXX_ENABLE</code>, the <code class="literal">--enable</code> maker</a></span></dt></dl></dd><dt><span class="section"><a href="documentation_hacking.html">Writing and Generating Documentation</a></span></dt><dd><dl><dt><span class="section"><a href="documentation_hacking.html#doc.intro">Introduction</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doc.generation">Generating Documentation</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doc.doxygen">Doxygen</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doc.docbook">Docbook</a></span></dt></dl></dd><dt><span class="section"><a href="internals.html">Porting to New Hardware or Operating Systems</a></span></dt><dd><dl><dt><span class="section"><a href="internals.html#internals.os">Operating System</a></span></dt><dt><span class="section"><a href="internals.html#internals.cpu">CPU</a></span></dt><dt><span class="section"><a href="internals.html#internals.char_types">Character Types</a></span></dt><dt><span class="section"><a href="internals.html#internals.thread_safety">Thread Safety</a></span></dt><dt><span class="section"><a href="internals.html#internals.numeric_limits">Numeric Limits</a></span></dt><dt><span class="section"><a href="internals.html#internals.libtool">Libtool</a></span></dt></dl></dd><dt><span class="section"><a href="test.html">Test</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.organization">Organization</a></span></dt><dt><span class="section"><a href="test.html#test.run">Running the Testsuite</a></span></dt><dt><span class="section"><a href="test.html#test.new_tests">Writing a new test case</a></span></dt><dt><span class="section"><a href="test.html#test.harness">Test Harness and Utilities</a></span></dt><dt><span class="section"><a href="test.html#test.special">Special Topics</a></span></dt></dl></dd><dt><span class="section"><a href="abi.html">ABI Policy and Guidelines</a></span></dt><dd><dl><dt><span class="section"><a href="abi.html#abi.cxx_interface">The C++ Interface</a></span></dt><dt><span class="section"><a href="abi.html#abi.versioning">Versioning</a></span></dt><dt><span class="section"><a href="abi.html#abi.changes_allowed">Allowed Changes</a></span></dt><dt><span class="section"><a href="abi.html#abi.changes_no">Prohibited Changes</a></span></dt><dt><span class="section"><a href="abi.html#abi.impl">Implementation</a></span></dt><dt><span class="section"><a href="abi.html#abi.testing">Testing</a></span></dt><dt><span class="section"><a href="abi.html#abi.issues">Outstanding Issues</a></span></dt></dl></dd><dt><span class="section"><a href="api.html">API Evolution and Deprecation History</a></span></dt><dd><dl><dt><span class="section"><a href="api.html#api.rel_300"><code class="constant">3.0</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_310"><code class="constant">3.1</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_320"><code class="constant">3.2</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_330"><code class="constant">3.3</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_340"><code class="constant">3.4</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_400"><code class="constant">4.0</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_410"><code class="constant">4.1</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_420"><code class="constant">4.2</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_430"><code class="constant">4.3</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_440"><code class="constant">4.4</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_450"><code class="constant">4.5</code></a></span></dt></dl></dd><dt><span class="section"><a href="backwards.html">Backwards Compatibility</a></span></dt><dd><dl><dt><span class="section"><a href="backwards.html#backwards.first">First</a></span></dt><dt><span class="section"><a href="backwards.html#backwards.second">Second</a></span></dt><dt><span class="section"><a href="backwards.html#backwards.third">Third</a></span></dt></dl></dd></dl></div><div class="section" title="Configure and Build Hacking"><div class="titlepage"><div><div><h2 class="title"><a id="appendix.porting.build_hacking"/>Configure and Build Hacking</h2></div></div></div><div class="section" title="Prerequisites"><div class="titlepage"><div><div><h3 class="title"><a id="build_hacking.prereq"/>Prerequisites</h3></div></div></div><p> + As noted <a class="link" href="http://gcc.gnu.org/install/prerequisites.html">previously</a>, + certain other tools are necessary for hacking on files that + control configure (<code class="code">configure.ac</code>, + <code class="code">acinclude.m4</code>) and make + (<code class="code">Makefile.am</code>). These additional tools + (<code class="code">automake</code>, and <code class="code">autoconf</code>) are further + described in detail in their respective manuals. All the libraries + in GCC try to stay in sync with each other in terms of versions of + the auto-tools used, so please try to play nicely with the + neighbors. + </p></div><div class="section" title="Overview: What Comes from Where"><div class="titlepage"><div><div><h3 class="title"><a id="build_hacking.map"/>Overview: What Comes from Where</h3></div></div></div><div class="figure"><a id="id494186"/><p class="title"><strong>Figure B.1. Configure and Build File Dependencies</strong></p><div class="figure-contents"><div class="mediaobject" style="text-align: center"><img src="/mnt/share/src/gcc.svn-trunk/libstdc++-v3/doc/xml/images/confdeps.png" style="text-align: middle" alt="Dependency Graph for Configure and Build Files"/></div></div></div><br class="figure-break"/><p> + Regenerate all generated files by using the command sequence + <code class="code">"autoreconf"</code> at the top level of the libstdc++ source + directory. The following will also work, but is much more complex: + <code class="code">"aclocal-1.11 && autoconf-2.64 && + autoheader-2.64 && automake-1.11"</code> The version + numbers may be absent entirely or otherwise vary depending on + <a class="link" href="http://gcc.gnu.org/install/prerequisites.html">the + current requirements</a> and your vendor's choice of + installation names. + </p></div><div class="section" title="Storing Information in non-AC files (like configure.host)"><div class="titlepage"><div><div><h3 class="title"><a id="build_hacking.scripts"/>Storing Information in non-AC files (like configure.host)</h3></div></div></div><p> + Until that glorious day when we can use AC_TRY_LINK with a + cross-compiler, we have to hardcode the results of what the tests + would have shown if they could be run. So we have an inflexible + mess like crossconfig.m4. + </p><p> + Wouldn't it be nice if we could store that information in files + like configure.host, which can be modified without needing to + regenerate anything, and can even be tweaked without really + knowing how the configury all works? Perhaps break the pieces of + crossconfig.m4 out and place them in their appropriate + config/{cpu,os} directory. + </p><p> + Alas, writing macros like + "<code class="code">AC_DEFINE(HAVE_A_NICE_DAY)</code>" can only be done inside + files which are passed through autoconf. Files which are pure + shell script can be source'd at configure time. Files which + contain autoconf macros must be processed with autoconf. We could + still try breaking the pieces out into "config/*/cross.m4" bits, + for instance, but then we would need arguments to aclocal/autoconf + to properly find them all when generating configure. I would + discourage that. +</p></div><div class="section" title="Coding and Commenting Conventions"><div class="titlepage"><div><div><h3 class="title"><a id="build_hacking.conventions"/>Coding and Commenting Conventions</h3></div></div></div><p> + Most comments should use {octothorpes, shibboleths, hash marks, + pound signs, whatever} rather than "dnl". Nearly all comments in + configure.ac should. Comments inside macros written in ancilliary + .m4 files should. About the only comments which should + <span class="emphasis"><em>not</em></span> use #, but use dnl instead, are comments + <span class="emphasis"><em>outside</em></span> our own macros in the ancilliary + files. The difference is that # comments show up in + <code class="code">configure</code> (which is most helpful for debugging), + while dnl'd lines just vanish. Since the macros in ancilliary + files generate code which appears in odd places, their "outside" + comments tend to not be useful while reading + <code class="code">configure</code>. + </p><p> + Do not use any <code class="code">$target*</code> variables, such as + <code class="code">$target_alias</code>. The single exception is in + configure.ac, for automake+dejagnu's sake. + </p></div><div class="section" title="The acinclude.m4 layout"><div class="titlepage"><div><div><h3 class="title"><a id="build_hacking.acinclude"/>The acinclude.m4 layout</h3></div></div></div><p> + The nice thing about acinclude.m4/aclocal.m4 is that macros aren't + actually performed/called/expanded/whatever here, just loaded. So + we can arrange the contents however we like. As of this writing, + acinclude.m4 is arranged as follows: + </p><pre class="programlisting"> + GLIBCXX_CHECK_HOST + GLIBCXX_TOPREL_CONFIGURE + GLIBCXX_CONFIGURE + </pre><p> + All the major variable "discovery" is done here. CXX, multilibs, + etc. + </p><pre class="programlisting"> + fragments included from elsewhere + </pre><p> + Right now, "fragments" == "the math/linkage bits". + </p><pre class="programlisting"> + GLIBCXX_CHECK_COMPILER_FEATURES + GLIBCXX_CHECK_LINKER_FEATURES + GLIBCXX_CHECK_WCHAR_T_SUPPORT +</pre><p> + Next come extra compiler/linker feature tests. Wide character + support was placed here because I couldn't think of another place + for it. It will probably get broken apart like the math tests, + because we're still disabling wchars on systems which could actually + support them. +</p><pre class="programlisting"> + GLIBCXX_CHECK_SETRLIMIT_ancilliary + GLIBCXX_CHECK_SETRLIMIT + GLIBCXX_CHECK_S_ISREG_OR_S_IFREG + GLIBCXX_CHECK_POLL + GLIBCXX_CHECK_WRITEV + + GLIBCXX_CONFIGURE_TESTSUITE +</pre><p> + Feature tests which only get used in one place. Here, things used + only in the testsuite, plus a couple bits used in the guts of I/O. +</p><pre class="programlisting"> + GLIBCXX_EXPORT_INCLUDES + GLIBCXX_EXPORT_FLAGS + GLIBCXX_EXPORT_INSTALL_INFO +</pre><p> + Installation variables, multilibs, working with the rest of the + compiler. Many of the critical variables used in the makefiles are + set here. +</p><pre class="programlisting"> + GLIBGCC_ENABLE + GLIBCXX_ENABLE_C99 + GLIBCXX_ENABLE_CHEADERS + GLIBCXX_ENABLE_CLOCALE + GLIBCXX_ENABLE_CONCEPT_CHECKS + GLIBCXX_ENABLE_CSTDIO + GLIBCXX_ENABLE_CXX_FLAGS + GLIBCXX_ENABLE_C_MBCHAR + GLIBCXX_ENABLE_DEBUG + GLIBCXX_ENABLE_DEBUG_FLAGS + GLIBCXX_ENABLE_LONG_LONG + GLIBCXX_ENABLE_PCH + GLIBCXX_ENABLE_SJLJ_EXCEPTIONS + GLIBCXX_ENABLE_SYMVERS + GLIBCXX_ENABLE_THREADS +</pre><p> + All the features which can be controlled with enable/disable + configure options. Note how they're alphabetized now? Keep them + like that. :-) +</p><pre class="programlisting"> + AC_LC_MESSAGES + libtool bits +</pre><p> + Things which we don't seem to use directly, but just has to be + present otherwise stuff magically goes wonky. +</p></div><div class="section" title="GLIBCXX_ENABLE, the --enable maker"><div class="titlepage"><div><div><h3 class="title"><a id="build_hacking.enable"/><code class="constant">GLIBCXX_ENABLE</code>, the <code class="literal">--enable</code> maker</h3></div></div></div><p> + All the GLIBCXX_ENABLE_FOO macros use a common helper, + GLIBCXX_ENABLE. (You don't have to use it, but it's easy.) The + helper does two things for us: + </p><div class="orderedlist"><ol class="orderedlist"><li class="listitem"><p> + Builds the call to the AC_ARG_ENABLE macro, with --help text + properly quoted and aligned. (Death to changequote!) + </p></li><li class="listitem"><p> + Checks the result against a list of allowed possibilities, and + signals a fatal error if there's no match. This means that the + rest of the GLIBCXX_ENABLE_FOO macro doesn't need to test for + strange arguments, nor do we need to protect against + empty/whitespace strings with the <code class="code">"x$foo" = "xbar"</code> + idiom. + </p></li></ol></div><p>Doing these things correctly takes some extra autoconf/autom4te code, + which made our macros nearly illegible. So all the ugliness is factored + out into this one helper macro. +</p><p>Many of the macros take an argument, passed from when they are expanded + in configure.ac. The argument controls the default value of the + enable/disable switch. Previously, the arguments themselves had defaults. + Now they don't, because that's extra complexity with zero gain for us. +</p><p>There are three "overloaded signatures". When reading the descriptions + below, keep in mind that the brackets are autoconf's quotation characters, + and that they will be stripped. Examples of just about everything occur + in acinclude.m4, if you want to look. +</p><pre class="programlisting"> + GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING) + GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, permit a|b|c) + GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, SHELL-CODE-HANDLER) +</pre><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + FEATURE is the string that follows --enable. The results of the + test (such as it is) will be in the variable $enable_FEATURE, + where FEATURE has been squashed. Example: + <code class="code">[extra-foo]</code>, controlled by the --enable-extra-foo + option and stored in $enable_extra_foo. + </p></li><li class="listitem"><p> + DEFAULT is the value to store in $enable_FEATURE if the user does + not pass --enable/--disable. It should be one of the permitted + values passed later. Examples: <code class="code">[yes]</code>, or + <code class="code">[bar]</code>, or <code class="code">[$1]</code> (which passes the + argument given to the GLIBCXX_ENABLE_FOO macro as the + default). + </p><p> + For cases where we need to probe for particular models of things, + it is useful to have an undocumented "auto" value here (see + GLIBCXX_ENABLE_CLOCALE for an example). + </p></li><li class="listitem"><p> + HELP-ARG is any text to append to the option string itself in the + --help output. Examples: <code class="code">[]</code> (i.e., an empty string, + which appends nothing), <code class="code">[=BAR]</code>, which produces + <code class="code">--enable-extra-foo=BAR</code>, and + <code class="code">[@<:@=BAR@:>@]</code>, which produces + <code class="code">--enable-extra-foo[=BAR]</code>. See the difference? See + what it implies to the user? + </p><p> + If you're wondering what that line noise in the last example was, + that's how you embed autoconf special characters in output text. + They're called <a class="link" href="http://www.gnu.org/software/autoconf/manual/autoconf.html#Quadrigraphs"><span class="emphasis"><em>quadrigraphs</em></span></a> + and you should use them whenever necessary. + </p></li><li class="listitem"><p>HELP-STRING is what you think it is. Do not include the + "default" text like we used to do; it will be done for you by + GLIBCXX_ENABLE. By convention, these are not full English + sentences. Example: [turn on extra foo] + </p></li></ul></div><p> + With no other arguments, only the standard autoconf patterns are + allowed: "<code class="code">--{enable,disable}-foo[={yes,no}]</code>" The + $enable_FEATURE variable is guaranteed to equal either "yes" or "no" + after the macro. If the user tries to pass something else, an + explanatory error message will be given, and configure will halt. +</p><p> + The second signature takes a fifth argument, "<code class="code">[permit + a | b | c | ...]</code>" + This allows <span class="emphasis"><em>a</em></span> or <span class="emphasis"><em>b</em></span> or + ... after the equals sign in the option, and $enable_FEATURE is + guaranteed to equal one of them after the macro. Note that if you + want to allow plain --enable/--disable with no "=whatever", you must + include "yes" and "no" in the list of permitted values. Also note + that whatever you passed as DEFAULT must be in the list. If the + user tries to pass something not on the list, a semi-explanatory + error message will be given, and configure will halt. Example: + <code class="code">[permit generic|gnu|ieee_1003.1-2001|yes|no|auto]</code> +</p><p> + The third signature takes a fifth argument. It is arbitrary shell + code to execute if the user actually passes the enable/disable + option. (If the user does not, the default is used. Duh.) No + argument checking at all is done in this signature. See + GLIBCXX_ENABLE_CXX_FLAGS for an example of handling, and an error + message. +</p></div></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="source_design_notes.html">Prev</a> </td><td align="center"><a accesskey="u" href="bk01pt04.html">Up</a></td><td align="right"> <a accesskey="n" href="documentation_hacking.html">Next</a></td></tr><tr><td align="left" valign="top">Design Notes </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Writing and Generating Documentation</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/associative.html b/libstdc++-v3/doc/html/manual/associative.html new file mode 100644 index 000000000..351ec9402 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/associative.html @@ -0,0 +1,192 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Associative</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="containers.html" title="Chapter 9. Containers"/><link rel="prev" href="containers.html" title="Chapter 9. Containers"/><link rel="next" href="containers_and_c.html" title="Interacting with C"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Associative</th></tr><tr><td align="left"><a accesskey="p" href="containers.html">Prev</a> </td><th width="60%" align="center">Chapter 9. + Containers + +</th><td align="right"> <a accesskey="n" href="containers_and_c.html">Next</a></td></tr></table><hr/></div><div class="section" title="Associative"><div class="titlepage"><div><div><h2 class="title"><a id="std.containers.associative"/>Associative</h2></div></div></div><div class="section" title="Insertion Hints"><div class="titlepage"><div><div><h3 class="title"><a id="containers.associative.insert_hints"/>Insertion Hints</h3></div></div></div><p> + Section [23.1.2], Table 69, of the C++ standard lists this + function for all of the associative containers (map, set, etc): + </p><pre class="programlisting"> + a.insert(p,t); + </pre><p> + where 'p' is an iterator into the container 'a', and 't' is the + item to insert. The standard says that <span class="quote">“<span class="quote"><code class="code">t</code> is + inserted as close as possible to the position just prior to + <code class="code">p</code>.</span>”</span> (Library DR #233 addresses this topic, + referring to <a class="link" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1780.html">N1780</a>. + Since version 4.2 GCC implements the resolution to DR 233, so + that insertions happen as close as possible to the hint. For + earlier releases the hint was only used as described below. + </p><p> + Here we'll describe how the hinting works in the libstdc++ + implementation, and what you need to do in order to take + advantage of it. (Insertions can change from logarithmic + complexity to amortized constant time, if the hint is properly + used.) Also, since the current implementation is based on the + SGI STL one, these points may hold true for other library + implementations also, since the HP/SGI code is used in a lot of + places. + </p><p> + In the following text, the phrases <span class="emphasis"><em>greater + than</em></span> and <span class="emphasis"><em>less than</em></span> refer to the + results of the strict weak ordering imposed on the container by + its comparison object, which defaults to (basically) + <span class="quote">“<span class="quote"><</span>”</span>. Using those phrases is semantically sloppy, + but I didn't want to get bogged down in syntax. I assume that if + you are intelligent enough to use your own comparison objects, + you are also intelligent enough to assign <span class="quote">“<span class="quote">greater</span>”</span> + and <span class="quote">“<span class="quote">lesser</span>”</span> their new meanings in the next + paragraph. *grin* + </p><p> + If the <code class="code">hint</code> parameter ('p' above) is equivalent to: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + <code class="code">begin()</code>, then the item being inserted should + have a key less than all the other keys in the container. + The item will be inserted at the beginning of the container, + becoming the new entry at <code class="code">begin()</code>. + </p></li><li class="listitem"><p> + <code class="code">end()</code>, then the item being inserted should have + a key greater than all the other keys in the container. The + item will be inserted at the end of the container, becoming + the new entry before <code class="code">end()</code>. + </p></li><li class="listitem"><p> + neither <code class="code">begin()</code> nor <code class="code">end()</code>, then: + Let <code class="code">h</code> be the entry in the container pointed to + by <code class="code">hint</code>, that is, <code class="code">h = *hint</code>. Then + the item being inserted should have a key less than that of + <code class="code">h</code>, and greater than that of the item preceding + <code class="code">h</code>. The new item will be inserted between + <code class="code">h</code> and <code class="code">h</code>'s predecessor. + </p></li></ul></div><p> + For <code class="code">multimap</code> and <code class="code">multiset</code>, the + restrictions are slightly looser: <span class="quote">“<span class="quote">greater than</span>”</span> + should be replaced by <span class="quote">“<span class="quote">not less than</span>”</span>and <span class="quote">“<span class="quote">less + than</span>”</span> should be replaced by <span class="quote">“<span class="quote">not greater + than.</span>”</span> (Why not replace greater with + greater-than-or-equal-to? You probably could in your head, but + the mathematicians will tell you that it isn't the same thing.) + </p><p> + If the conditions are not met, then the hint is not used, and the + insertion proceeds as if you had called <code class="code"> a.insert(t) + </code> instead. (<span class="emphasis"><em>Note </em></span> that GCC releases + prior to 3.0.2 had a bug in the case with <code class="code">hint == + begin()</code> for the <code class="code">map</code> and <code class="code">set</code> + classes. You should not use a hint argument in those releases.) + </p><p> + This behavior goes well with other containers' + <code class="code">insert()</code> functions which take an iterator: if used, + the new item will be inserted before the iterator passed as an + argument, same as the other containers. + </p><p> + <span class="emphasis"><em>Note </em></span> also that the hint in this + implementation is a one-shot. The older insertion-with-hint + routines check the immediately surrounding entries to ensure that + the new item would in fact belong there. If the hint does not + point to the correct place, then no further local searching is + done; the search begins from scratch in logarithmic time. + </p></div><div class="section" title="bitset"><div class="titlepage"><div><div><h3 class="title"><a id="containers.associative.bitset"/>bitset</h3></div></div></div><div class="section" title="Size Variable"><div class="titlepage"><div><div><h4 class="title"><a id="associative.bitset.size_variable"/>Size Variable</h4></div></div></div><p> + No, you cannot write code of the form + </p><pre class="programlisting"> + #include <bitset> + + void foo (size_t n) + { + std::bitset<n> bits; + .... + } + </pre><p> + because <code class="code">n</code> must be known at compile time. Your + compiler is correct; it is not a bug. That's the way templates + work. (Yes, it <span class="emphasis"><em>is</em></span> a feature.) + </p><p> + There are a couple of ways to handle this kind of thing. Please + consider all of them before passing judgement. They include, in + no chaptericular order: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>A very large N in <code class="code">bitset<N></code>.</p></li><li class="listitem"><p>A container<bool>.</p></li><li class="listitem"><p>Extremely weird solutions.</p></li></ul></div><p> + <span class="emphasis"><em>A very large N in + <code class="code">bitset<N></code>. </em></span> It has been + pointed out a few times in newsgroups that N bits only takes up + (N/8) bytes on most systems, and division by a factor of eight is + pretty impressive when speaking of memory. Half a megabyte given + over to a bitset (recall that there is zero space overhead for + housekeeping info; it is known at compile time exactly how large + the set is) will hold over four million bits. If you're using + those bits as status flags (e.g., + <span class="quote">“<span class="quote">changed</span>”</span>/<span class="quote">“<span class="quote">unchanged</span>”</span> flags), that's a + <span class="emphasis"><em>lot</em></span> of state. + </p><p> + You can then keep track of the <span class="quote">“<span class="quote">maximum bit used</span>”</span> + during some testing runs on representative data, make note of how + many of those bits really need to be there, and then reduce N to + a smaller number. Leave some extra space, of course. (If you + plan to write code like the incorrect example above, where the + bitset is a local variable, then you may have to talk your + compiler into allowing that much stack space; there may be zero + space overhead, but it's all allocated inside the object.) + </p><p> + <span class="emphasis"><em>A container<bool>. </em></span> The + Committee made provision for the space savings possible with that + (N/8) usage previously mentioned, so that you don't have to do + wasteful things like <code class="code">Container<char></code> or + <code class="code">Container<short int></code>. Specifically, + <code class="code">vector<bool></code> is required to be specialized for + that space savings. + </p><p> + The problem is that <code class="code">vector<bool></code> doesn't + behave like a normal vector anymore. There have been + journal articles which discuss the problems (the ones by Herb + Sutter in the May and July/August 1999 issues of C++ Report cover + it well). Future revisions of the ISO C++ Standard will change + the requirement for <code class="code">vector<bool></code> + specialization. In the meantime, <code class="code">deque<bool></code> + is recommended (although its behavior is sane, you probably will + not get the space savings, but the allocation scheme is different + than that of vector). + </p><p> + <span class="emphasis"><em>Extremely weird solutions. </em></span> If + you have access to the compiler and linker at runtime, you can do + something insane, like figuring out just how many bits you need, + then writing a temporary source code file. That file contains an + instantiation of <code class="code">bitset</code> for the required number of + bits, inside some wrapper functions with unchanging signatures. + Have your program then call the compiler on that file using + Position Independent Code, then open the newly-created object + file and load those wrapper functions. You'll have an + instantiation of <code class="code">bitset<N></code> for the exact + <code class="code">N</code> that you need at the time. Don't forget to delete + the temporary files. (Yes, this <span class="emphasis"><em>can</em></span> be, and + <span class="emphasis"><em>has been</em></span>, done.) + </p><p> + This would be the approach of either a visionary genius or a + raving lunatic, depending on your programming and management + style. Probably the latter. + </p><p> + Which of the above techniques you use, if any, are up to you and + your intended application. Some time/space profiling is + indicated if it really matters (don't just guess). And, if you + manage to do anything along the lines of the third category, the + author would love to hear from you... + </p><p> + Also note that the implementation of bitset used in libstdc++ has + <a class="link" href="bk01pt03ch21s02.html" title="HP/SGI">some extensions</a>. + </p></div><div class="section" title="Type String"><div class="titlepage"><div><div><h4 class="title"><a id="associative.bitset.type_string"/>Type String</h4></div></div></div><p> + </p><p> + Bitmasks do not take char* nor const char* arguments in their + constructors. This is something of an accident, but you can read + about the problem: follow the library's <span class="quote">“<span class="quote">Links</span>”</span> from + the homepage, and from the C++ information <span class="quote">“<span class="quote">defect + reflector</span>”</span> link, select the library issues list. Issue + number 116 describes the problem. + </p><p> + For now you can simply make a temporary string object using the + constructor expression: + </p><pre class="programlisting"> + std::bitset<5> b ( std::string(<span class="quote">“<span class="quote">10110</span>”</span>) ); + </pre><p> + instead of + </p><pre class="programlisting"> + std::bitset<5> b ( <span class="quote">“<span class="quote">10110</span>”</span> ); // invalid + </pre></div></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="containers.html">Prev</a> </td><td align="center"><a accesskey="u" href="containers.html">Up</a></td><td align="right"> <a accesskey="n" href="containers_and_c.html">Next</a></td></tr><tr><td align="left" valign="top">Chapter 9. + Containers + + </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Interacting with C</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/atomics.html b/libstdc++-v3/doc/html/manual/atomics.html new file mode 100644 index 000000000..68052a741 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/atomics.html @@ -0,0 +1,31 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Chapter 14. Atomics</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library , atomic "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="bk01pt02.html" title="Part II. Standard Contents"/><link rel="prev" href="io_and_c.html" title="Interacting with C"/><link rel="next" href="concurrency.html" title="Chapter 15. Concurrency"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 14. + Atomics + +</th></tr><tr><td align="left"><a accesskey="p" href="io_and_c.html">Prev</a> </td><th width="60%" align="center">Part II. + Standard Contents + </th><td align="right"> <a accesskey="n" href="concurrency.html">Next</a></td></tr></table><hr/></div><div class="chapter" title="Chapter 14. Atomics"><div class="titlepage"><div><div><h2 class="title"><a id="std.atomics"/>Chapter 14. + Atomics + <a id="id481583" class="indexterm"/> +</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="atomics.html#std.atomics.api">API Reference</a></span></dt></dl></div><p> + Facilities for atomic operations. +</p><div class="section" title="API Reference"><div class="titlepage"><div><div><h2 class="title"><a id="std.atomics.api"/>API Reference</h2></div></div></div><p> + All items are declared in the standard header + file <code class="filename">atomic</code>. + </p><p> + Set of typedefs that map <span class="type">int</span> to + <code class="classname">atomic_int</code>, and so on for all builtin + integral types. Global enumeration <span class="type">memory_order</span> to + control memory ordering. Also includes + <code class="classname">atomic</code>, a class template with member + functions such as <code class="function">load</code> and + <code class="function">store</code> that is instantiable such that + <code class="classname">atomic_int</code> is the base class of + <code class="classname">atomic<int></code>. + </p><p> + Full API details. + </p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="io_and_c.html">Prev</a> </td><td align="center"><a accesskey="u" href="bk01pt02.html">Up</a></td><td align="right"> <a accesskey="n" href="concurrency.html">Next</a></td></tr><tr><td align="left" valign="top">Interacting with C </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Chapter 15. + Concurrency + +</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/backwards.html b/libstdc++-v3/doc/html/manual/backwards.html new file mode 100644 index 000000000..2ac6d789e --- /dev/null +++ b/libstdc++-v3/doc/html/manual/backwards.html @@ -0,0 +1,920 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Backwards Compatibility</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , backwards "/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="appendix_porting.html" title="Appendix B. Porting and Maintenance"/><link rel="prev" href="api.html" title="API Evolution and Deprecation History"/><link rel="next" href="appendix_free.html" title="Appendix C. Free Software Needs Free Documentation"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Backwards Compatibility</th></tr><tr><td align="left"><a accesskey="p" href="api.html">Prev</a> </td><th width="60%" align="center">Appendix B. + Porting and Maintenance + +</th><td align="right"> <a accesskey="n" href="appendix_free.html">Next</a></td></tr></table><hr/></div><div class="section" title="Backwards Compatibility"><div class="titlepage"><div><div><h2 class="title"><a id="manual.appendix.porting.backwards"/>Backwards Compatibility</h2></div></div></div><div class="section" title="First"><div class="titlepage"><div><div><h3 class="title"><a id="backwards.first"/>First</h3></div></div></div><p>The first generation GNU C++ library was called libg++. It was a +separate GNU project, although reliably paired with GCC. Rumors imply +that it had a working relationship with at least two kinds of +dinosaur. +</p><p>Some background: libg++ was designed and created when there was no +ISO standard to provide guidance. Classes like linked lists are now +provided for by <code class="classname">list<T></code> and do not need to be +created by <code class="function">genclass</code>. (For that matter, templates exist +now and are well-supported, whereas genclass (mostly) predates them.) +</p><p>There are other classes in libg++ that are not specified in the +ISO Standard (e.g., statistical analysis). While there are a lot of +really useful things that are used by a lot of people, the Standards +Committee couldn't include everything, and so a lot of those +<span class="quote">“<span class="quote">obvious</span>”</span> classes didn't get included. +</p><p>Known Issues include many of the limitations of its immediate ancestor.</p><p>Portability notes and known implementation limitations are as follows.</p><div class="section" title="No ios_base"><div class="titlepage"><div><div><h4 class="title"><a id="id503868"/>No <code class="code">ios_base</code></h4></div></div></div><p> At least some older implementations don't have <code class="code">std::ios_base</code>, so you should use <code class="code">std::ios::badbit</code>, <code class="code">std::ios::failbit</code> and <code class="code">std::ios::eofbit</code> and <code class="code">std::ios::goodbit</code>. +</p></div><div class="section" title="No cout in ostream.h, no cin in istream.h"><div class="titlepage"><div><div><h4 class="title"><a id="id503900"/>No <code class="code">cout</code> in <code class="code">ostream.h</code>, no <code class="code">cin</code> in <code class="code">istream.h</code></h4></div></div></div><p> + In earlier versions of the standard, + <code class="filename">fstream.h</code>, + <code class="filename">ostream.h</code> + and <code class="filename">istream.h</code> + used to define + <code class="code">cout</code>, <code class="code">cin</code> and so on. ISO C++ specifies that one needs to include + <code class="filename">iostream</code> + explicitly to get the required definitions. + </p><p> Some include adjustment may be required.</p><p>This project is no longer maintained or supported, and the sources +archived. For the desperate, +the <a class="link" href="http://gcc.gnu.org/extensions.html">GCC extensions +page</a> describes where to find the last libg++ source. The code is +considered replaced and rewritten. +</p></div></div><div class="section" title="Second"><div class="titlepage"><div><div><h3 class="title"><a id="backwards.second"/>Second</h3></div></div></div><p> + The second generation GNU C++ library was called libstdc++, or + libstdc++-v2. It spans the time between libg++ and pre-ISO C++ + standardization and is usually associated with the following GCC + releases: egcs 1.x, gcc 2.95, and gcc 2.96. +</p><p> + The STL portions of this library are based on SGI/HP STL release 3.11. +</p><p> + This project is no longer maintained or supported, and the sources + archived. The code is considered replaced and rewritten. +</p><p> + Portability notes and known implementation limitations are as follows. +</p><div class="section" title="Namespace std:: not supported"><div class="titlepage"><div><div><h4 class="title"><a id="id504003"/>Namespace <code class="code">std::</code> not supported</h4></div></div></div><p> + Some care is required to support C++ compiler and or library + implementation that do not have the standard library in + <code class="code">namespace std</code>. + </p><p> + The following sections list some possible solutions to support compilers + that cannot ignore <code class="code">std::</code>-qualified names. + </p><p> + First, see if the compiler has a flag for this. Namespace + back-portability-issues are generally not a problem for g++ + compilers that do not have libstdc++ in <code class="code">std::</code>, as the + compilers use <code class="code">-fno-honor-std</code> (ignore + <code class="code">std::</code>, <code class="code">:: = std::</code>) by default. That is, + the responsibility for enabling or disabling <code class="code">std::</code> is + on the user; the maintainer does not have to care about it. This + probably applies to some other compilers as well. + </p><p> + Second, experiment with a variety of pre-processor tricks. + </p><p> + By defining <code class="code">std</code> as a macro, fully-qualified namespace + calls become global. Volia. + </p><pre class="programlisting"> +#ifdef WICKEDLY_OLD_COMPILER +# define std +#endif +</pre><p> + Thanks to Juergen Heinzl who posted this solution on gnu.gcc.help. + </p><p> + Another pre-processor based approach is to define a macro + <code class="code">NAMESPACE_STD</code>, which is defined to either + <span class="quote">“<span class="quote"> </span>”</span> or <span class="quote">“<span class="quote">std</span>”</span> based on a compile-type + test. On GNU systems, this can be done with autotools by means of + an autoconf test (see below) for <code class="code">HAVE_NAMESPACE_STD</code>, + then using that to set a value for the <code class="code">NAMESPACE_STD</code> + macro. At that point, one is able to use + <code class="code">NAMESPACE_STD::string</code>, which will evaluate to + <code class="code">std::string</code> or <code class="code">::string</code> (i.e., in the + global namespace on systems that do not put <code class="code">string</code> in + <code class="code">std::</code>). + </p><pre class="programlisting"> +dnl @synopsis AC_CXX_NAMESPACE_STD +dnl +dnl If the compiler supports namespace std, define +dnl HAVE_NAMESPACE_STD. +dnl +dnl @category Cxx +dnl @author Todd Veldhuizen +dnl @author Luc Maisonobe <luc@spaceroots.org> +dnl @version 2004-02-04 +dnl @license AllPermissive +AC_DEFUN([AC_CXX_NAMESPACE_STD], [ + AC_CACHE_CHECK(if g++ supports namespace std, + ac_cv_cxx_have_std_namespace, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + AC_TRY_COMPILE([#include <iostream> + std::istream& is = std::cin;],, + ac_cv_cxx_have_std_namespace=yes, ac_cv_cxx_have_std_namespace=no) + AC_LANG_RESTORE + ]) + if test "$ac_cv_cxx_have_std_namespace" = yes; then + AC_DEFINE(HAVE_NAMESPACE_STD,,[Define if g++ supports namespace std. ]) + fi +]) +</pre></div><div class="section" title="Illegal iterator usage"><div class="titlepage"><div><div><h4 class="title"><a id="id504130"/>Illegal iterator usage</h4></div></div></div><p> + The following illustrate implementation-allowed illegal iterator + use, and then correct use. +</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + you cannot do <code class="code">ostream::operator<<(iterator)</code> + to print the address of the iterator => use + <code class="code">operator<< &*iterator</code> instead + </p></li><li class="listitem"><p> + you cannot clear an iterator's reference (<code class="code">iterator = + 0</code>) => use <code class="code">iterator = iterator_type();</code> + </p></li><li class="listitem"><p> + <code class="code">if (iterator)</code> won't work any more => use + <code class="code">if (iterator != iterator_type())</code> + </p></li></ul></div></div><div class="section" title="isspace from cctype is a macro"><div class="titlepage"><div><div><h4 class="title"><a id="id504191"/><code class="code">isspace</code> from <code class="filename">cctype</code> is a macro + </h4></div></div></div><p> + Glibc 2.0.x and 2.1.x define <code class="filename">ctype.h</code> functionality as macros + (isspace, isalpha etc.). + </p><p> + This implementations of libstdc++, however, keep these functions + as macros, and so it is not back-portable to use fully qualified + names. For example: + </p><pre class="programlisting"> +#include <cctype> +int main() { std::isspace('X'); } +</pre><p> + Results in something like this: +</p><pre class="programlisting"> +std:: (__ctype_b[(int) ( ( 'X' ) )] & (unsigned short int) _ISspace ) ; +</pre><p> + A solution is to modify a header-file so that the compiler tells + <code class="filename">ctype.h</code> to define functions + instead of macros: +</p><pre class="programlisting"> +// This keeps isalnum, et al from being propagated as macros. +#if __linux__ +# define __NO_CTYPE 1 +#endif +</pre><p> + Then, include <code class="filename">ctype.h</code> +</p><p> + Another problem arises if you put a <code class="code">using namespace + std;</code> declaration at the top, and include <code class="filename">ctype.h</code>. This will result in + ambiguities between the definitions in the global namespace + (<code class="filename">ctype.h</code>) and the + definitions in namespace <code class="code">std::</code> + (<code class="code"><cctype></code>). +</p></div><div class="section" title="No vector::at, deque::at, string::at"><div class="titlepage"><div><div><h4 class="title"><a id="id504286"/>No <code class="code">vector::at</code>, <code class="code">deque::at</code>, <code class="code">string::at</code></h4></div></div></div><p> + One solution is to add an autoconf-test for this: +</p><pre class="programlisting"> +AC_MSG_CHECKING(for container::at) +AC_TRY_COMPILE( +[ +#include <vector> +#include <deque> +#include <string> + +using namespace std; +], +[ +deque<int> test_deque(3); +test_deque.at(2); +vector<int> test_vector(2); +test_vector.at(1); +string test_string(<span class="quote">“<span class="quote">test_string</span>”</span>); +test_string.at(3); +], +[AC_MSG_RESULT(yes) +AC_DEFINE(HAVE_CONTAINER_AT)], +[AC_MSG_RESULT(no)]) +</pre><p> + If you are using other (non-GNU) compilers it might be a good idea + to check for <code class="code">string::at</code> separately. +</p></div><div class="section" title="No std::char_traits<char>::eof"><div class="titlepage"><div><div><h4 class="title"><a id="id504326"/>No <code class="code">std::char_traits<char>::eof</code></h4></div></div></div><p> + Use some kind of autoconf test, plus this: +</p><pre class="programlisting"> +#ifdef HAVE_CHAR_TRAITS +#define CPP_EOF std::char_traits<char>::eof() +#else +#define CPP_EOF EOF +#endif +</pre></div><div class="section" title="No string::clear"><div class="titlepage"><div><div><h4 class="title"><a id="id504344"/>No <code class="code">string::clear</code></h4></div></div></div><p> + There are two functions for deleting the contents of a string: + <code class="code">clear</code> and <code class="code">erase</code> (the latter returns the + string). +</p><pre class="programlisting"> +void +clear() { _M_mutate(0, this->size(), 0); } +</pre><pre class="programlisting"> +basic_string& +erase(size_type __pos = 0, size_type __n = npos) +{ + return this->replace(_M_check(__pos), _M_fold(__pos, __n), + _M_data(), _M_data()); +} +</pre><p> + Unfortunately, <code class="code">clear</code> is not implemented in this + version, so you should use <code class="code">erase</code> (which is probably + faster than <code class="code">operator=(charT*)</code>). +</p></div><div class="section" title="Removal of ostream::form and istream::scan extensions"><div class="titlepage"><div><div><h4 class="title"><a id="id504390"/> + Removal of <code class="code">ostream::form</code> and <code class="code">istream::scan</code> + extensions +</h4></div></div></div><p> + These are no longer supported. Please use stringstreams instead. +</p></div><div class="section" title="No basic_stringbuf, basic_stringstream"><div class="titlepage"><div><div><h4 class="title"><a id="id504408"/>No <code class="code">basic_stringbuf</code>, <code class="code">basic_stringstream</code></h4></div></div></div><p> + Although the ISO standard <code class="code">i/ostringstream</code>-classes are + provided, (<code class="filename">sstream</code>), for + compatibility with older implementations the pre-ISO + <code class="code">i/ostrstream</code> (<code class="filename">strstream</code>) interface is also provided, + with these caveats: +</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + <code class="code">strstream</code> is considered to be deprecated + </p></li><li class="listitem"><p> + <code class="code">strstream</code> is limited to <code class="code">char</code> + </p></li><li class="listitem"><p> + with <code class="code">ostringstream</code> you don't have to take care of + terminating the string or freeing its memory + </p></li><li class="listitem"><p> + <code class="code">istringstream</code> can be re-filled (clear(); + str(input);) + </p></li></ul></div><p> + You can then use output-stringstreams like this: +</p><pre class="programlisting"> +#ifdef HAVE_SSTREAM +# include <sstream> +#else +# include <strstream> +#endif + +#ifdef HAVE_SSTREAM + std::ostringstream oss; +#else + std::ostrstream oss; +#endif + +oss << <span class="quote">“<span class="quote">Name=</span>”</span> << m_name << <span class="quote">“<span class="quote">, number=</span>”</span> << m_number << std::endl; +... +#ifndef HAVE_SSTREAM + oss << std::ends; // terminate the char*-string +#endif + +// str() returns char* for ostrstream and a string for ostringstream +// this also causes ostrstream to think that the buffer's memory +// is yours +m_label.set_text(oss.str()); +#ifndef HAVE_SSTREAM + // let the ostrstream take care of freeing the memory + oss.freeze(false); +#endif +</pre><p> + Input-stringstreams can be used similarly: +</p><pre class="programlisting"> +std::string input; +... +#ifdef HAVE_SSTREAM +std::istringstream iss(input); +#else +std::istrstream iss(input.c_str()); +#endif + +int i; +iss >> i; +</pre><p> One (the only?) restriction is that an istrstream cannot be re-filled: +</p><pre class="programlisting"> +std::istringstream iss(numerator); +iss >> m_num; +// this is not possible with istrstream +iss.clear(); +iss.str(denominator); +iss >> m_den; +</pre><p> +If you don't care about speed, you can put these conversions in + a template-function: +</p><pre class="programlisting"> +template <class X> +void fromString(const string& input, X& any) +{ +#ifdef HAVE_SSTREAM +std::istringstream iss(input); +#else +std::istrstream iss(input.c_str()); +#endif +X temp; +iss >> temp; +if (iss.fail()) +throw runtime_error(..) +any = temp; +} +</pre><p> + Another example of using stringstreams is in <a class="link" href="strings.html#strings.string.shrink" title="Shrink to Fit">this howto</a>. +</p><p> There is additional information in the libstdc++-v2 info files, in +particular <span class="quote">“<span class="quote">info iostream</span>”</span>. +</p></div><div class="section" title="Little or no wide character support"><div class="titlepage"><div><div><h4 class="title"><a id="id504564"/>Little or no wide character support</h4></div></div></div><p> + Classes <code class="classname">wstring</code> and + <code class="classname">char_traits<wchar_t></code> are + not supported. + </p></div><div class="section" title="No templatized iostreams"><div class="titlepage"><div><div><h4 class="title"><a id="id504583"/>No templatized iostreams</h4></div></div></div><p> + Classes <code class="classname">wfilebuf</code> and + <code class="classname">wstringstream</code> are not supported. + </p></div><div class="section" title="Thread safety issues"><div class="titlepage"><div><div><h4 class="title"><a id="id504602"/>Thread safety issues</h4></div></div></div><p> + Earlier GCC releases had a somewhat different approach to + threading configuration and proper compilation. Before GCC 3.0, + configuration of the threading model was dictated by compiler + command-line options and macros (both of which were somewhat + thread-implementation and port-specific). There were no + guarantees related to being able to link code compiled with one + set of options and macro setting with another set. + </p><p> + For GCC 3.0, configuration of the threading model used with + libraries and user-code is performed when GCC is configured and + built using the --enable-threads and --disable-threads options. + The ABI is stable for symbol name-mangling and limited functional + compatibility exists between code compiled under different + threading models. + </p><p> + The libstdc++ library has been designed so that it can be used in + multithreaded applications (with libstdc++-v2 this was only true + of the STL parts.) The first problem is finding a + <span class="emphasis"><em>fast</em></span> method of implementation portable to + all platforms. Due to historical reasons, some of the library is + written against per-CPU-architecture spinlocks and other parts + against the gthr.h abstraction layer which is provided by gcc. A + minor problem that pops up every so often is different + interpretations of what "thread-safe" means for a + library (not a general program). We currently use the <a class="link" href="http://www.sgi.com/tech/stl/thread_safety.html">same + definition that SGI</a> uses for their STL subset. However, + the exception for read-only containers only applies to the STL + components. This definition is widely-used and something similar + will be used in the next version of the C++ standard library. + </p><p> + Here is a small link farm to threads (no pun) in the mail + archives that discuss the threading problem. Each link is to the + first relevant message in the thread; from there you can use + "Thread Next" to move down the thread. This farm is in + latest-to-oldest order. + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + Our threading expert Loren gives a breakdown of <a class="link" href="http://gcc.gnu.org/ml/libstdc++/2001-10/msg00024.html">the + six situations involving threads</a> for the 3.0 + release series. + </p></li><li class="listitem"><p> + <a class="link" href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00384.html"> + This message</a> inspired a recent updating of issues with + threading and the SGI STL library. It also contains some + example POSIX-multithreaded STL code. + </p></li></ul></div><p> + (A large selection of links to older messages has been removed; + many of the messages from 1999 were lost in a disk crash, and the + few people with access to the backup tapes have been too swamped + with work to restore them. Many of the points have been + superseded anyhow.) + </p></div></div><div class="section" title="Third"><div class="titlepage"><div><div><h3 class="title"><a id="backwards.third"/>Third</h3></div></div></div><p> The third generation GNU C++ library is called libstdc++, or +libstdc++-v3. +</p><p>The subset commonly known as the Standard Template Library + (chapters 23 through 25, mostly) is adapted from the final release + of the SGI STL (version 3.3), with extensive changes. + </p><p>A more formal description of the V3 goals can be found in the + official <a class="link" href="source_design_notes.html" title="Design Notes">design document</a>. + </p><p>Portability notes and known implementation limitations are as follows.</p><div class="section" title="Pre-ISO headers moved to backwards or removed"><div class="titlepage"><div><div><h4 class="title"><a id="id504726"/>Pre-ISO headers moved to backwards or removed</h4></div></div></div><p> The pre-ISO C++ headers + (<code class="code">iostream.h</code>, <code class="code">defalloc.h</code> etc.) are + available, unlike previous libstdc++ versions, but inclusion + generates a warning that you are using deprecated headers. +</p><p>This compatibility layer is constructed by including the + standard C++ headers, and injecting any items in + <code class="code">std::</code> into the global namespace. + </p><p>For those of you new to ISO C++ (welcome, time travelers!), no, + that isn't a typo. Yes, the headers really have new names. + Marshall Cline's C++ FAQ Lite has a good explanation in <a class="link" href="http://www.parashift.com/c++-faq-lite/coding-standards.html#faq-27.4">item + [27.4]</a>. + </p><p> Some include adjustment may be required. What follows is an +autoconf test that defines <code class="code">PRE_STDCXX_HEADERS</code> when they +exist.</p><pre class="programlisting"> +# AC_HEADER_PRE_STDCXX +AC_DEFUN([AC_HEADER_PRE_STDCXX], [ + AC_CACHE_CHECK(for pre-ISO C++ include files, + ac_cv_cxx_pre_stdcxx, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + ac_save_CXXFLAGS="$CXXFLAGS" + CXXFLAGS="$CXXFLAGS -Wno-deprecated" + + # Omit defalloc.h, as compilation with newer compilers is problematic. + AC_TRY_COMPILE([ + #include <new.h> + #include <iterator.h> + #include <alloc.h> + #include <set.h> + #include <hashtable.h> + #include <hash_set.h> + #include <fstream.h> + #include <tempbuf.h> + #include <istream.h> + #include <bvector.h> + #include <stack.h> + #include <rope.h> + #include <complex.h> + #include <ostream.h> + #include <heap.h> + #include <iostream.h> + #include <function.h> + #include <multimap.h> + #include <pair.h> + #include <stream.h> + #include <iomanip.h> + #include <slist.h> + #include <tree.h> + #include <vector.h> + #include <deque.h> + #include <multiset.h> + #include <list.h> + #include <map.h> + #include <algobase.h> + #include <hash_map.h> + #include <algo.h> + #include <queue.h> + #include <streambuf.h> + ],, + ac_cv_cxx_pre_stdcxx=yes, ac_cv_cxx_pre_stdcxx=no) + CXXFLAGS="$ac_save_CXXFLAGS" + AC_LANG_RESTORE + ]) + if test "$ac_cv_cxx_pre_stdcxx" = yes; then + AC_DEFINE(PRE_STDCXX_HEADERS,,[Define if pre-ISO C++ header files are present. ]) + fi +]) +</pre><p>Porting between pre-ISO headers and ISO headers is simple: headers +like <code class="filename">vector.h</code> can be replaced with <code class="filename">vector</code> and a using +directive <code class="code">using namespace std;</code> can be put at the global +scope. This should be enough to get this code compiling, assuming the +other usage is correct. +</p></div><div class="section" title="Extension headers hash_map, hash_set moved to ext or backwards"><div class="titlepage"><div><div><h4 class="title"><a id="id504811"/>Extension headers hash_map, hash_set moved to ext or backwards</h4></div></div></div><p>At this time most of the features of the SGI STL extension have been + replaced by standardized libraries. + In particular, the unordered_map and unordered_set containers of TR1 + are suitable replacement for the non-standard hash_map and hash_set + containers in the SGI STL. + </p><p> Header files <code class="filename">hash_map</code> and <code class="filename">hash_set</code> moved +to <code class="filename">ext/hash_map</code> and <code class="filename">ext/hash_set</code>, +respectively. At the same time, all types in these files are enclosed +in <code class="code">namespace __gnu_cxx</code>. Later versions move deprecate +these files, and suggest using TR1's <code class="filename">unordered_map</code> +and <code class="filename">unordered_set</code> instead. +</p><p>The extensions are no longer in the global or <code class="code">std</code> + namespaces, instead they are declared in the <code class="code">__gnu_cxx</code> + namespace. For maximum portability, consider defining a namespace + alias to use to talk about extensions, e.g.: + </p><pre class="programlisting"> + #ifdef __GNUC__ + #if __GNUC__ < 3 + #include <hash_map.h> + namespace extension { using ::hash_map; }; // inherit globals + #else + #include <backward/hash_map> + #if __GNUC__ == 3 && __GNUC_MINOR__ == 0 + namespace extension = std; // GCC 3.0 + #else + namespace extension = ::__gnu_cxx; // GCC 3.1 and later + #endif + #endif + #else // ... there are other compilers, right? + namespace extension = std; + #endif + + extension::hash_map<int,int> my_map; + </pre><p>This is a bit cleaner than defining typedefs for all the + instantiations you might need. + </p><p>The following autoconf tests check for working HP/SGI hash containers. +</p><pre class="programlisting"> +# AC_HEADER_EXT_HASH_MAP +AC_DEFUN([AC_HEADER_EXT_HASH_MAP], [ + AC_CACHE_CHECK(for ext/hash_map, + ac_cv_cxx_ext_hash_map, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + ac_save_CXXFLAGS="$CXXFLAGS" + CXXFLAGS="$CXXFLAGS -Werror" + AC_TRY_COMPILE([#include <ext/hash_map>], [using __gnu_cxx::hash_map;], + ac_cv_cxx_ext_hash_map=yes, ac_cv_cxx_ext_hash_map=no) + CXXFLAGS="$ac_save_CXXFLAGS" + AC_LANG_RESTORE + ]) + if test "$ac_cv_cxx_ext_hash_map" = yes; then + AC_DEFINE(HAVE_EXT_HASH_MAP,,[Define if ext/hash_map is present. ]) + fi +]) +</pre><pre class="programlisting"> +# AC_HEADER_EXT_HASH_SET +AC_DEFUN([AC_HEADER_EXT_HASH_SET], [ + AC_CACHE_CHECK(for ext/hash_set, + ac_cv_cxx_ext_hash_set, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + ac_save_CXXFLAGS="$CXXFLAGS" + CXXFLAGS="$CXXFLAGS -Werror" + AC_TRY_COMPILE([#include <ext/hash_set>], [using __gnu_cxx::hash_set;], + ac_cv_cxx_ext_hash_set=yes, ac_cv_cxx_ext_hash_set=no) + CXXFLAGS="$ac_save_CXXFLAGS" + AC_LANG_RESTORE + ]) + if test "$ac_cv_cxx_ext_hash_set" = yes; then + AC_DEFINE(HAVE_EXT_HASH_SET,,[Define if ext/hash_set is present. ]) + fi +]) +</pre></div><div class="section" title="No ios::nocreate/ios::noreplace."><div class="titlepage"><div><div><h4 class="title"><a id="id504914"/>No <code class="code">ios::nocreate/ios::noreplace</code>. +</h4></div></div></div><p> The existence of <code class="code">ios::nocreate</code> being used for +input-streams has been confirmed, most probably because the author +thought it would be more correct to specify nocreate explicitly. So +it can be left out for input-streams. +</p><p>For output streams, <span class="quote">“<span class="quote">nocreate</span>”</span> is probably the default, +unless you specify <code class="code">std::ios::trunc</code> ? To be safe, you can +open the file for reading, check if it has been opened, and then +decide whether you want to create/replace or not. To my knowledge, +even older implementations support <code class="code">app</code>, <code class="code">ate</code> +and <code class="code">trunc</code> (except for <code class="code">app</code> ?). +</p></div><div class="section" title="No stream::attach(int fd)"><div class="titlepage"><div><div><h4 class="title"><a id="id504962"/> +No <code class="code">stream::attach(int fd)</code> +</h4></div></div></div><p> + Phil Edwards writes: It was considered and rejected for the ISO + standard. Not all environments use file descriptors. Of those + that do, not all of them use integers to represent them. + </p><p> + For a portable solution (among systems which use + file descriptors), you need to implement a subclass of + <code class="code">std::streambuf</code> (or + <code class="code">std::basic_streambuf<..></code>) which opens a file + given a descriptor, and then pass an instance of this to the + stream-constructor. + </p><p> + An extension is available that implements this. + <code class="filename">ext/stdio_filebuf.h</code> contains a derived class called + <a class="link" href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a00074.html"><code class="code">__gnu_cxx::stdio_filebuf</code></a>. + This class can be constructed from a C <code class="code">FILE*</code> or a file + descriptor, and provides the <code class="code">fd()</code> function. + </p><p> + For another example of this, refer to + <a class="link" href="http://www.josuttis.com/cppcode/fdstream.html">fdstream example</a> + by Nicolai Josuttis. +</p></div><div class="section" title="Support for C++98 dialect."><div class="titlepage"><div><div><h4 class="title"><a id="id505030"/> +Support for C++98 dialect. +</h4></div></div></div><p>Check for complete library coverage of the C++1998/2003 standard. +</p><pre class="programlisting"> +# AC_HEADER_STDCXX_98 +AC_DEFUN([AC_HEADER_STDCXX_98], [ + AC_CACHE_CHECK(for ISO C++ 98 include files, + ac_cv_cxx_stdcxx_98, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + AC_TRY_COMPILE([ + #include <cassert> + #include <cctype> + #include <cerrno> + #include <cfloat> + #include <ciso646> + #include <climits> + #include <clocale> + #include <cmath> + #include <csetjmp> + #include <csignal> + #include <cstdarg> + #include <cstddef> + #include <cstdio> + #include <cstdlib> + #include <cstring> + #include <ctime> + + #include <algorithm> + #include <bitset> + #include <complex> + #include <deque> + #include <exception> + #include <fstream> + #include <functional> + #include <iomanip> + #include <ios> + #include <iosfwd> + #include <iostream> + #include <istream> + #include <iterator> + #include <limits> + #include <list> + #include <locale> + #include <map> + #include <memory> + #include <new> + #include <numeric> + #include <ostream> + #include <queue> + #include <set> + #include <sstream> + #include <stack> + #include <stdexcept> + #include <streambuf> + #include <string> + #include <typeinfo> + #include <utility> + #include <valarray> + #include <vector> + ],, + ac_cv_cxx_stdcxx_98=yes, ac_cv_cxx_stdcxx_98=no) + AC_LANG_RESTORE + ]) + if test "$ac_cv_cxx_stdcxx_98" = yes; then + AC_DEFINE(STDCXX_98_HEADERS,,[Define if ISO C++ 1998 header files are present. ]) + fi +]) +</pre></div><div class="section" title="Support for C++TR1 dialect."><div class="titlepage"><div><div><h4 class="title"><a id="id505057"/> +Support for C++TR1 dialect. +</h4></div></div></div><p>Check for library coverage of the TR1 standard. +</p><pre class="programlisting"> +# AC_HEADER_STDCXX_TR1 +AC_DEFUN([AC_HEADER_STDCXX_TR1], [ + AC_CACHE_CHECK(for ISO C++ TR1 include files, + ac_cv_cxx_stdcxx_tr1, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + AC_TRY_COMPILE([ + #include <tr1/array> + #include <tr1/ccomplex> + #include <tr1/cctype> + #include <tr1/cfenv> + #include <tr1/cfloat> + #include <tr1/cinttypes> + #include <tr1/climits> + #include <tr1/cmath> + #include <tr1/complex> + #include <tr1/cstdarg> + #include <tr1/cstdbool> + #include <tr1/cstdint> + #include <tr1/cstdio> + #include <tr1/cstdlib> + #include <tr1/ctgmath> + #include <tr1/ctime> + #include <tr1/cwchar> + #include <tr1/cwctype> + #include <tr1/functional> + #include <tr1/memory> + #include <tr1/random> + #include <tr1/regex> + #include <tr1/tuple> + #include <tr1/type_traits> + #include <tr1/unordered_set> + #include <tr1/unordered_map> + #include <tr1/utility> + ],, + ac_cv_cxx_stdcxx_tr1=yes, ac_cv_cxx_stdcxx_tr1=no) + AC_LANG_RESTORE + ]) + if test "$ac_cv_cxx_stdcxx_tr1" = yes; then + AC_DEFINE(STDCXX_TR1_HEADERS,,[Define if ISO C++ TR1 header files are present. ]) + fi +]) +</pre><p>An alternative is to check just for specific TR1 includes, such as <unordered_map> and <unordered_set>. +</p><pre class="programlisting"> +# AC_HEADER_TR1_UNORDERED_MAP +AC_DEFUN([AC_HEADER_TR1_UNORDERED_MAP], [ + AC_CACHE_CHECK(for tr1/unordered_map, + ac_cv_cxx_tr1_unordered_map, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + AC_TRY_COMPILE([#include <tr1/unordered_map>], [using std::tr1::unordered_map;], + ac_cv_cxx_tr1_unordered_map=yes, ac_cv_cxx_tr1_unordered_map=no) + AC_LANG_RESTORE + ]) + if test "$ac_cv_cxx_tr1_unordered_map" = yes; then + AC_DEFINE(HAVE_TR1_UNORDERED_MAP,,[Define if tr1/unordered_map is present. ]) + fi +]) +</pre><pre class="programlisting"> +# AC_HEADER_TR1_UNORDERED_SET +AC_DEFUN([AC_HEADER_TR1_UNORDERED_SET], [ + AC_CACHE_CHECK(for tr1/unordered_set, + ac_cv_cxx_tr1_unordered_set, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + AC_TRY_COMPILE([#include <tr1/unordered_set>], [using std::tr1::unordered_set;], + ac_cv_cxx_tr1_unordered_set=yes, ac_cv_cxx_tr1_unordered_set=no) + AC_LANG_RESTORE + ]) + if test "$ac_cv_cxx_tr1_unordered_set" = yes; then + AC_DEFINE(HAVE_TR1_UNORDERED_SET,,[Define if tr1/unordered_set is present. ]) + fi +]) +</pre></div><div class="section" title="Support for C++0x dialect."><div class="titlepage"><div><div><h4 class="title"><a id="id505101"/> +Support for C++0x dialect. +</h4></div></div></div><p>Check for baseline language coverage in the compiler for the C++0xstandard. +</p><pre class="programlisting"> +# AC_COMPILE_STDCXX_OX +AC_DEFUN([AC_COMPILE_STDCXX_0X], [ + AC_CACHE_CHECK(if g++ supports C++0x features without additional flags, + ac_cv_cxx_compile_cxx0x_native, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + AC_TRY_COMPILE([ + template <typename T> + struct check + { + static_assert(sizeof(int) <= sizeof(T), "not big enough"); + }; + + typedef check<check<bool>> right_angle_brackets; + + int a; + decltype(a) b; + + typedef check<int> check_type; + check_type c; + check_type&& cr = c;],, + ac_cv_cxx_compile_cxx0x_native=yes, ac_cv_cxx_compile_cxx0x_native=no) + AC_LANG_RESTORE + ]) + + AC_CACHE_CHECK(if g++ supports C++0x features with -std=c++0x, + ac_cv_cxx_compile_cxx0x_cxx, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + ac_save_CXXFLAGS="$CXXFLAGS" + CXXFLAGS="$CXXFLAGS -std=c++0x" + AC_TRY_COMPILE([ + template <typename T> + struct check + { + static_assert(sizeof(int) <= sizeof(T), "not big enough"); + }; + + typedef check<check<bool>> right_angle_brackets; + + int a; + decltype(a) b; + + typedef check<int> check_type; + check_type c; + check_type&& cr = c;],, + ac_cv_cxx_compile_cxx0x_cxx=yes, ac_cv_cxx_compile_cxx0x_cxx=no) + CXXFLAGS="$ac_save_CXXFLAGS" + AC_LANG_RESTORE + ]) + + AC_CACHE_CHECK(if g++ supports C++0x features with -std=gnu++0x, + ac_cv_cxx_compile_cxx0x_gxx, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + ac_save_CXXFLAGS="$CXXFLAGS" + CXXFLAGS="$CXXFLAGS -std=gnu++0x" + AC_TRY_COMPILE([ + template <typename T> + struct check + { + static_assert(sizeof(int) <= sizeof(T), "not big enough"); + }; + + typedef check<check<bool>> right_angle_brackets; + + int a; + decltype(a) b; + + typedef check<int> check_type; + check_type c; + check_type&& cr = c;],, + ac_cv_cxx_compile_cxx0x_gxx=yes, ac_cv_cxx_compile_cxx0x_gxx=no) + CXXFLAGS="$ac_save_CXXFLAGS" + AC_LANG_RESTORE + ]) + + if test "$ac_cv_cxx_compile_cxx0x_native" = yes || + test "$ac_cv_cxx_compile_cxx0x_cxx" = yes || + test "$ac_cv_cxx_compile_cxx0x_gxx" = yes; then + AC_DEFINE(HAVE_STDCXX_0X,,[Define if g++ supports C++0x features. ]) + fi +]) +</pre><p>Check for library coverage of the C++0xstandard. +</p><pre class="programlisting"> +# AC_HEADER_STDCXX_0X +AC_DEFUN([AC_HEADER_STDCXX_0X], [ + AC_CACHE_CHECK(for ISO C++ 0x include files, + ac_cv_cxx_stdcxx_0x, + [AC_REQUIRE([AC_COMPILE_STDCXX_0X]) + AC_LANG_SAVE + AC_LANG_CPLUSPLUS + ac_save_CXXFLAGS="$CXXFLAGS" + CXXFLAGS="$CXXFLAGS -std=gnu++0x" + + AC_TRY_COMPILE([ + #include <cassert> + #include <ccomplex> + #include <cctype> + #include <cerrno> + #include <cfenv> + #include <cfloat> + #include <cinttypes> + #include <ciso646> + #include <climits> + #include <clocale> + #include <cmath> + #include <csetjmp> + #include <csignal> + #include <cstdarg> + #include <cstdbool> + #include <cstddef> + #include <cstdint> + #include <cstdio> + #include <cstdlib> + #include <cstring> + #include <ctgmath> + #include <ctime> + #include <cwchar> + #include <cwctype> + + #include <algorithm> + #include <array> + #include <bitset> + #include <complex> + #include <deque> + #include <exception> + #include <fstream> + #include <functional> + #include <iomanip> + #include <ios> + #include <iosfwd> + #include <iostream> + #include <istream> + #include <iterator> + #include <limits> + #include <list> + #include <locale> + #include <map> + #include <memory> + #include <new> + #include <numeric> + #include <ostream> + #include <queue> + #include <random> + #include <regex> + #include <set> + #include <sstream> + #include <stack> + #include <stdexcept> + #include <streambuf> + #include <string> + #include <tuple> + #include <typeinfo> + #include <type_traits> + #include <unordered_map> + #include <unordered_set> + #include <utility> + #include <valarray> + #include <vector> + ],, + ac_cv_cxx_stdcxx_0x=yes, ac_cv_cxx_stdcxx_0x=no) + AC_LANG_RESTORE + CXXFLAGS="$ac_save_CXXFLAGS" + ]) + if test "$ac_cv_cxx_stdcxx_0x" = yes; then + AC_DEFINE(STDCXX_0X_HEADERS,,[Define if ISO C++ 0x header files are present. ]) + fi +]) +</pre><p>As is the case for TR1 support, these autoconf macros can be made for a finer-grained, per-header-file check. For <unordered_map> +</p><pre class="programlisting"> +# AC_HEADER_UNORDERED_MAP +AC_DEFUN([AC_HEADER_UNORDERED_MAP], [ + AC_CACHE_CHECK(for unordered_map, + ac_cv_cxx_unordered_map, + [AC_REQUIRE([AC_COMPILE_STDCXX_0X]) + AC_LANG_SAVE + AC_LANG_CPLUSPLUS + ac_save_CXXFLAGS="$CXXFLAGS" + CXXFLAGS="$CXXFLAGS -std=gnu++0x" + AC_TRY_COMPILE([#include <unordered_map>], [using std::unordered_map;], + ac_cv_cxx_unordered_map=yes, ac_cv_cxx_unordered_map=no) + CXXFLAGS="$ac_save_CXXFLAGS" + AC_LANG_RESTORE + ]) + if test "$ac_cv_cxx_unordered_map" = yes; then + AC_DEFINE(HAVE_UNORDERED_MAP,,[Define if unordered_map is present. ]) + fi +]) +</pre><pre class="programlisting"> +# AC_HEADER_UNORDERED_SET +AC_DEFUN([AC_HEADER_UNORDERED_SET], [ + AC_CACHE_CHECK(for unordered_set, + ac_cv_cxx_unordered_set, + [AC_REQUIRE([AC_COMPILE_STDCXX_0X]) + AC_LANG_SAVE + AC_LANG_CPLUSPLUS + ac_save_CXXFLAGS="$CXXFLAGS" + CXXFLAGS="$CXXFLAGS -std=gnu++0x" + AC_TRY_COMPILE([#include <unordered_set>], [using std::unordered_set;], + ac_cv_cxx_unordered_set=yes, ac_cv_cxx_unordered_set=no) + CXXFLAGS="$ac_save_CXXFLAGS" + AC_LANG_RESTORE + ]) + if test "$ac_cv_cxx_unordered_set" = yes; then + AC_DEFINE(HAVE_UNORDERED_SET,,[Define if unordered_set is present. ]) + fi +]) +</pre></div><div class="section" title="Container::iterator_type is not necessarily Container::value_type*"><div class="titlepage"><div><div><h4 class="title"><a id="id505180"/> + Container::iterator_type is not necessarily Container::value_type* +</h4></div></div></div><p> + This is a change in behavior from the previous version. Now, most + <span class="type">iterator_type</span> typedefs in container classes are POD + objects, not <span class="type">value_type</span> pointers. +</p></div></div><div class="bibliography" title="Bibliography"><div class="titlepage"><div><div><h3 class="title"><a id="backwards.biblio"/>Bibliography</h3></div></div></div><div class="biblioentry"><a id="id505210"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + Migrating to GCC 4.1 + </em>. </span><span class="author"><span class="firstname">Dan</span> <span class="surname">Kegel</span>. </span></p></div><div class="biblioentry"><a id="id505235"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + Building the Whole Debian Archive with GCC 4.1: A Summary + </em>. </span><span class="author"><span class="firstname">Martin</span> <span class="surname">Michlmayr</span>. </span></p></div><div class="biblioentry"><a id="id505261"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + Migration guide for GCC-3.2 + </em>. </span></p></div></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="api.html">Prev</a> </td><td align="center"><a accesskey="u" href="appendix_porting.html">Up</a></td><td align="right"> <a accesskey="n" href="appendix_free.html">Next</a></td></tr><tr><td align="left" valign="top">API Evolution and Deprecation History </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Appendix C. + Free Software Needs Free Documentation + +</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/bitmap_allocator.html b/libstdc++-v3/doc/html/manual/bitmap_allocator.html new file mode 100644 index 000000000..be584e403 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bitmap_allocator.html @@ -0,0 +1,340 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>bitmap_allocator</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , allocator "/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="ext_allocators.html" title="Chapter 20. Allocators"/><link rel="prev" href="ext_allocators.html" title="Chapter 20. Allocators"/><link rel="next" href="ext_containers.html" title="Chapter 21. Containers"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">bitmap_allocator</th></tr><tr><td align="left"><a accesskey="p" href="ext_allocators.html">Prev</a> </td><th width="60%" align="center">Chapter 20. Allocators</th><td align="right"> <a accesskey="n" href="ext_containers.html">Next</a></td></tr></table><hr/></div><div class="section" title="bitmap_allocator"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.allocator.bitmap"/>bitmap_allocator</h2></div></div></div><p> +</p><div class="section" title="Design"><div class="titlepage"><div><div><h3 class="title"><a id="allocator.bitmap.design"/>Design</h3></div></div></div><p> + As this name suggests, this allocator uses a bit-map to keep track + of the used and unused memory locations for it's book-keeping + purposes. + </p><p> + This allocator will make use of 1 single bit to keep track of + whether it has been allocated or not. A bit 1 indicates free, + while 0 indicates allocated. This has been done so that you can + easily check a collection of bits for a free block. This kind of + Bitmapped strategy works best for single object allocations, and + with the STL type parameterized allocators, we do not need to + choose any size for the block which will be represented by a + single bit. This will be the size of the parameter around which + the allocator has been parameterized. Thus, close to optimal + performance will result. Hence, this should be used for node based + containers which call the allocate function with an argument of 1. + </p><p> + The bitmapped allocator's internal pool is exponentially growing. + Meaning that internally, the blocks acquired from the Free List + Store will double every time the bitmapped allocator runs out of + memory. + </p><p> + The macro <code class="literal">__GTHREADS</code> decides whether to use + Mutex Protection around every allocation/deallocation. The state + of the macro is picked up automatically from the gthr abstraction + layer. + </p></div><div class="section" title="Implementation"><div class="titlepage"><div><div><h3 class="title"><a id="allocator.bitmap.impl"/>Implementation</h3></div></div></div><div class="section" title="Free List Store"><div class="titlepage"><div><div><h4 class="title"><a id="bitmap.impl.free_list_store"/>Free List Store</h4></div></div></div><p> + The Free List Store (referred to as FLS for the remaining part of this + document) is the Global memory pool that is shared by all instances of + the bitmapped allocator instantiated for any type. This maintains a + sorted order of all free memory blocks given back to it by the + bitmapped allocator, and is also responsible for giving memory to the + bitmapped allocator when it asks for more. + </p><p> + Internally, there is a Free List threshold which indicates the + Maximum number of free lists that the FLS can hold internally + (cache). Currently, this value is set at 64. So, if there are + more than 64 free lists coming in, then some of them will be given + back to the OS using operator delete so that at any given time the + Free List's size does not exceed 64 entries. This is done because + a Binary Search is used to locate an entry in a free list when a + request for memory comes along. Thus, the run-time complexity of + the search would go up given an increasing size, for 64 entries + however, lg(64) == 6 comparisons are enough to locate the correct + free list if it exists. + </p><p> + Suppose the free list size has reached it's threshold, then the + largest block from among those in the list and the new block will + be selected and given back to the OS. This is done because it + reduces external fragmentation, and allows the OS to use the + larger blocks later in an orderly fashion, possibly merging them + later. Also, on some systems, large blocks are obtained via calls + to mmap, so giving them back to free system resources becomes most + important. + </p><p> + The function _S_should_i_give decides the policy that determines + whether the current block of memory should be given to the + allocator for the request that it has made. That's because we may + not always have exact fits for the memory size that the allocator + requests. We do this mainly to prevent external fragmentation at + the cost of a little internal fragmentation. Now, the value of + this internal fragmentation has to be decided by this function. I + can see 3 possibilities right now. Please add more as and when you + find better strategies. + </p><div class="orderedlist"><ol class="orderedlist"><li class="listitem"><p>Equal size check. Return true only when the 2 blocks are of equal +size.</p></li><li class="listitem"><p>Difference Threshold: Return true only when the _block_size is +greater than or equal to the _required_size, and if the _BS is > _RS +by a difference of less than some THRESHOLD value, then return true, +else return false. </p></li><li class="listitem"><p>Percentage Threshold. Return true only when the _block_size is +greater than or equal to the _required_size, and if the _BS is > _RS +by a percentage of less than some THRESHOLD value, then return true, +else return false.</p></li></ol></div><p> + Currently, (3) is being used with a value of 36% Maximum wastage per + Super Block. + </p></div><div class="section" title="Super Block"><div class="titlepage"><div><div><h4 class="title"><a id="bitmap.impl.super_block"/>Super Block</h4></div></div></div><p> + A super block is the block of memory acquired from the FLS from + which the bitmap allocator carves out memory for single objects + and satisfies the user's requests. These super blocks come in + sizes that are powers of 2 and multiples of 32 + (_Bits_Per_Block). Yes both at the same time! That's because the + next super block acquired will be 2 times the previous one, and + also all super blocks have to be multiples of the _Bits_Per_Block + value. + </p><p> + How does it interact with the free list store? + </p><p> + The super block is contained in the FLS, and the FLS is responsible for + getting / returning Super Bocks to and from the OS using operator new + as defined by the C++ standard. + </p></div><div class="section" title="Super Block Data Layout"><div class="titlepage"><div><div><h4 class="title"><a id="bitmap.impl.super_block_data"/>Super Block Data Layout</h4></div></div></div><p> + Each Super Block will be of some size that is a multiple of the + number of Bits Per Block. Typically, this value is chosen as + Bits_Per_Byte x sizeof(size_t). On an x86 system, this gives the + figure 8 x 4 = 32. Thus, each Super Block will be of size 32 + x Some_Value. This Some_Value is sizeof(value_type). For now, let + it be called 'K'. Thus, finally, Super Block size is 32 x K bytes. + </p><p> + This value of 32 has been chosen because each size_t has 32-bits + and Maximum use of these can be made with such a figure. + </p><p> + Consider a block of size 64 ints. In memory, it would look like this: + (assume a 32-bit system where, size_t is a 32-bit entity). + </p><div class="table"><a id="id490827"/><p class="title"><strong>Table 20.1. Bitmap Allocator Memory Map</strong></p><div class="table-contents"><table summary="Bitmap Allocator Memory Map" border="1"><colgroup><col style="text-align: left" class="c1"/><col style="text-align: left" class="c2"/><col style="text-align: left" class="c3"/><col style="text-align: left" class="c4"/><col style="text-align: left" class="c5"/></colgroup><tbody><tr><td style="text-align: left">268</td><td style="text-align: left">0</td><td style="text-align: left">4294967295</td><td style="text-align: left">4294967295</td><td style="text-align: left">Data -> Space for 64 ints</td></tr></tbody></table></div></div><br class="table-break"/><p> + The first Column(268) represents the size of the Block in bytes as + seen by the Bitmap Allocator. Internally, a global free list is + used to keep track of the free blocks used and given back by the + bitmap allocator. It is this Free List Store that is responsible + for writing and managing this information. Actually the number of + bytes allocated in this case would be: 4 + 4 + (4x2) + (64x4) = + 272 bytes, but the first 4 bytes are an addition by the Free List + Store, so the Bitmap Allocator sees only 268 bytes. These first 4 + bytes about which the bitmapped allocator is not aware hold the + value 268. + </p><p> + What do the remaining values represent?</p><p> + The 2nd 4 in the expression is the sizeof(size_t) because the + Bitmapped Allocator maintains a used count for each Super Block, + which is initially set to 0 (as indicated in the diagram). This is + incremented every time a block is removed from this super block + (allocated), and decremented whenever it is given back. So, when + the used count falls to 0, the whole super block will be given + back to the Free List Store. + </p><p> + The value 4294967295 represents the integer corresponding to the bit + representation of all bits set: 11111111111111111111111111111111. + </p><p> + The 3rd 4x2 is size of the bitmap itself, which is the size of 32-bits + x 2, + which is 8-bytes, or 2 x sizeof(size_t). + </p></div><div class="section" title="Maximum Wasted Percentage"><div class="titlepage"><div><div><h4 class="title"><a id="bitmap.impl.max_wasted"/>Maximum Wasted Percentage</h4></div></div></div><p> + This has nothing to do with the algorithm per-se, + only with some vales that must be chosen correctly to ensure that the + allocator performs well in a real word scenario, and maintains a good + balance between the memory consumption and the allocation/deallocation + speed. + </p><p> + The formula for calculating the maximum wastage as a percentage: + </p><p> +(32 x k + 1) / (2 x (32 x k + 1 + 32 x c)) x 100. + </p><p> + where k is the constant overhead per node (e.g., for list, it is + 8 bytes, and for map it is 12 bytes) and c is the size of the + base type on which the map/list is instantiated. Thus, suppose the + type1 is int and type2 is double, they are related by the relation + sizeof(double) == 2*sizeof(int). Thus, all types must have this + double size relation for this formula to work properly. + </p><p> + Plugging-in: For List: k = 8 and c = 4 (int and double), we get: + 33.376% + </p><p> +For map/multimap: k = 12, and c = 4 (int and double), we get: 37.524% + </p><p> + Thus, knowing these values, and based on the sizeof(value_type), we may + create a function that returns the Max_Wastage_Percentage for us to use. + </p></div><div class="section" title="allocate"><div class="titlepage"><div><div><h4 class="title"><a id="bitmap.impl.allocate"/><code class="function">allocate</code></h4></div></div></div><p> + The allocate function is specialized for single object allocation + ONLY. Thus, ONLY if n == 1, will the bitmap_allocator's + specialized algorithm be used. Otherwise, the request is satisfied + directly by calling operator new. + </p><p> + Suppose n == 1, then the allocator does the following: + </p><div class="orderedlist"><ol class="orderedlist"><li class="listitem"><p> + Checks to see whether a free block exists somewhere in a region + of memory close to the last satisfied request. If so, then that + block is marked as allocated in the bit map and given to the + user. If not, then (2) is executed. + </p></li><li class="listitem"><p> + Is there a free block anywhere after the current block right + up to the end of the memory that we have? If so, that block is + found, and the same procedure is applied as above, and + returned to the user. If not, then (3) is executed. + </p></li><li class="listitem"><p> + Is there any block in whatever region of memory that we own + free? This is done by checking + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + The use count for each super block, and if that fails then + </p></li><li class="listitem"><p> + The individual bit-maps for each super block. + </p></li></ul></div><p> + Note: Here we are never touching any of the memory that the + user will be given, and we are confining all memory accesses + to a small region of memory! This helps reduce cache + misses. If this succeeds then we apply the same procedure on + that bit-map as (1), and return that block of memory to the + user. However, if this process fails, then we resort to (4). + </p></li><li class="listitem"><p> + This process involves Refilling the internal exponentially + growing memory pool. The said effect is achieved by calling + _S_refill_pool which does the following: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + Gets more memory from the Global Free List of the Required + size. + </p></li><li class="listitem"><p> + Adjusts the size for the next call to itself. + </p></li><li class="listitem"><p> + Writes the appropriate headers in the bit-maps. + </p></li><li class="listitem"><p> + Sets the use count for that super-block just allocated to 0 + (zero). + </p></li><li class="listitem"><p> + All of the above accounts to maintaining the basic invariant + for the allocator. If the invariant is maintained, we are + sure that all is well. Now, the same process is applied on + the newly acquired free blocks, which are dispatched + accordingly. + </p></li></ul></div></li></ol></div><p> +Thus, you can clearly see that the allocate function is nothing but a +combination of the next-fit and first-fit algorithm optimized ONLY for +single object allocations. +</p></div><div class="section" title="deallocate"><div class="titlepage"><div><div><h4 class="title"><a id="bitmap.impl.deallocate"/><code class="function">deallocate</code></h4></div></div></div><p> + The deallocate function again is specialized for single objects ONLY. + For all n belonging to > 1, the operator delete is called without + further ado, and the deallocate function returns. + </p><p> + However for n == 1, a series of steps are performed: + </p><div class="orderedlist"><ol class="orderedlist"><li class="listitem"><p> + We first need to locate that super-block which holds the memory + location given to us by the user. For that purpose, we maintain + a static variable _S_last_dealloc_index, which holds the index + into the vector of block pairs which indicates the index of the + last super-block from which memory was freed. We use this + strategy in the hope that the user will deallocate memory in a + region close to what he/she deallocated the last time around. If + the check for belongs_to succeeds, then we determine the bit-map + for the given pointer, and locate the index into that bit-map, + and mark that bit as free by setting it. + </p></li><li class="listitem"><p> + If the _S_last_dealloc_index does not point to the memory block + that we're looking for, then we do a linear search on the block + stored in the vector of Block Pairs. This vector in code is + called _S_mem_blocks. When the corresponding super-block is + found, we apply the same procedure as we did for (1) to mark the + block as free in the bit-map. + </p></li></ol></div><p> + Now, whenever a block is freed, the use count of that particular + super block goes down by 1. When this use count hits 0, we remove + that super block from the list of all valid super blocks stored in + the vector. While doing this, we also make sure that the basic + invariant is maintained by making sure that _S_last_request and + _S_last_dealloc_index point to valid locations within the vector. + </p></div><div class="section" title="Questions"><div class="titlepage"><div><div><h4 class="title"><a id="bitmap.impl.questions"/>Questions</h4></div></div></div><div class="section" title="1"><div class="titlepage"><div><div><h5 class="title"><a id="bitmap.impl.question.1"/>1</h5></div></div></div><p> +Q1) The "Data Layout" section is +cryptic. I have no idea of what you are trying to say. Layout of what? +The free-list? Each bitmap? The Super Block? + </p><p> + The layout of a Super Block of a given +size. In the example, a super block of size 32 x 1 is taken. The +general formula for calculating the size of a super block is +32 x sizeof(value_type) x 2^n, where n ranges from 0 to 32 for 32-bit +systems. + </p></div><div class="section" title="2"><div class="titlepage"><div><div><h5 class="title"><a id="bitmap.impl.question.2"/>2</h5></div></div></div><p> + And since I just mentioned the +term `each bitmap', what in the world is meant by it? What does each +bitmap manage? How does it relate to the super block? Is the Super +Block a bitmap as well? + </p><p> + Each bitmap is part of a Super Block which is made up of 3 parts + as I have mentioned earlier. Re-iterating, 1. The use count, + 2. The bit-map for that Super Block. 3. The actual memory that + will be eventually given to the user. Each bitmap is a multiple + of 32 in size. If there are 32 x (2^3) blocks of single objects + to be given, there will be '32 x (2^3)' bits present. Each 32 + bits managing the allocated / free status for 32 blocks. Since + each size_t contains 32-bits, one size_t can manage up to 32 + blocks' status. Each bit-map is made up of a number of size_t, + whose exact number for a super-block of a given size I have just + mentioned. + </p></div><div class="section" title="3"><div class="titlepage"><div><div><h5 class="title"><a id="bitmap.impl.question.3"/>3</h5></div></div></div><p> + How do the allocate and deallocate functions work in regard to + bitmaps? + </p><p> + The allocate and deallocate functions manipulate the bitmaps and + have nothing to do with the memory that is given to the user. As + I have earlier mentioned, a 1 in the bitmap's bit field + indicates free, while a 0 indicates allocated. This lets us + check 32 bits at a time to check whether there is at lease one + free block in those 32 blocks by testing for equality with + (0). Now, the allocate function will given a memory block find + the corresponding bit in the bitmap, and will reset it (i.e., + make it re-set (0)). And when the deallocate function is called, + it will again set that bit after locating it to indicate that + that particular block corresponding to this bit in the bit-map + is not being used by anyone, and may be used to satisfy future + requests. + </p><p> + e.g.: Consider a bit-map of 64-bits as represented below: + 1111111111111111111111111111111111111111111111111111111111111111 + </p><p> + Now, when the first request for allocation of a single object + comes along, the first block in address order is returned. And + since the bit-maps in the reverse order to that of the address + order, the last bit (LSB if the bit-map is considered as a + binary word of 64-bits) is re-set to 0. + </p><p> + The bit-map now looks like this: + 1111111111111111111111111111111111111111111111111111111111111110 + </p></div></div><div class="section" title="Locality"><div class="titlepage"><div><div><h4 class="title"><a id="bitmap.impl.locality"/>Locality</h4></div></div></div><p> + Another issue would be whether to keep the all bitmaps in a + separate area in memory, or to keep them near the actual blocks + that will be given out or allocated for the client. After some + testing, I've decided to keep these bitmaps close to the actual + blocks. This will help in 2 ways. + </p><div class="orderedlist"><ol class="orderedlist"><li class="listitem"><p>Constant time access for the bitmap themselves, since no kind of +look up will be needed to find the correct bitmap list or it's +equivalent.</p></li><li class="listitem"><p>And also this would preserve the cache as far as possible.</p></li></ol></div><p> + So in effect, this kind of an allocator might prove beneficial from a + purely cache point of view. But this allocator has been made to try and + roll out the defects of the node_allocator, wherein the nodes get + skewed about in memory, if they are not returned in the exact reverse + order or in the same order in which they were allocated. Also, the + new_allocator's book keeping overhead is too much for small objects and + single object allocations, though it preserves the locality of blocks + very well when they are returned back to the allocator. + </p></div><div class="section" title="Overhead and Grow Policy"><div class="titlepage"><div><div><h4 class="title"><a id="bitmap.impl.grow_policy"/>Overhead and Grow Policy</h4></div></div></div><p> + Expected overhead per block would be 1 bit in memory. Also, once + the address of the free list has been found, the cost for + allocation/deallocation would be negligible, and is supposed to be + constant time. For these very reasons, it is very important to + minimize the linear time costs, which include finding a free list + with a free block while allocating, and finding the corresponding + free list for a block while deallocating. Therefore, I have + decided that the growth of the internal pool for this allocator + will be exponential as compared to linear for + node_allocator. There, linear time works well, because we are + mainly concerned with speed of allocation/deallocation and memory + consumption, whereas here, the allocation/deallocation part does + have some linear/logarithmic complexity components in it. Thus, to + try and minimize them would be a good thing to do at the cost of a + little bit of memory. + </p><p> + Another thing to be noted is the pool size will double every time + the internal pool gets exhausted, and all the free blocks have + been given away. The initial size of the pool would be + sizeof(size_t) x 8 which is the number of bits in an integer, + which can fit exactly in a CPU register. Hence, the term given is + exponential growth of the internal pool. + </p></div></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="ext_allocators.html">Prev</a> </td><td align="center"><a accesskey="u" href="ext_allocators.html">Up</a></td><td align="right"> <a accesskey="n" href="ext_containers.html">Next</a></td></tr><tr><td align="left" valign="top">Chapter 20. Allocators </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Chapter 21. Containers</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/bk01pt02.html b/libstdc++-v3/doc/html/manual/bk01pt02.html new file mode 100644 index 000000000..3a0751ab9 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bk01pt02.html @@ -0,0 +1,46 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Part II. Standard Contents</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="spine.html" title="The GNU C++ Library Manual"/><link rel="prev" href="debug.html" title="Debugging Support"/><link rel="next" href="support.html" title="Chapter 4. Support"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Part II. + Standard Contents + </th></tr><tr><td align="left"><a accesskey="p" href="debug.html">Prev</a> </td><th width="60%" align="center">The GNU C++ Library Manual</th><td align="right"> <a accesskey="n" href="support.html">Next</a></td></tr></table><hr/></div><div class="part" title="Part II. Standard Contents"><div class="titlepage"><div><div><h1 class="title"><a id="manual.std"/>Part II. + Standard Contents + </h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="chapter"><a href="support.html">4. + Support + +</a></span></dt><dd><dl><dt><span class="section"><a href="support.html#std.support.types">Types</a></span></dt><dd><dl><dt><span class="section"><a href="support.html#std.support.types.fundamental">Fundamental Types</a></span></dt><dt><span class="section"><a href="support.html#std.support.types.numeric_limits">Numeric Properties</a></span></dt><dt><span class="section"><a href="support.html#std.support.types.null">NULL</a></span></dt></dl></dd><dt><span class="section"><a href="dynamic_memory.html">Dynamic Memory</a></span></dt><dt><span class="section"><a href="termination.html">Termination</a></span></dt><dd><dl><dt><span class="section"><a href="termination.html#support.termination.handlers">Termination Handlers</a></span></dt><dt><span class="section"><a href="termination.html#support.termination.verbose">Verbose Terminate Handler</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="diagnostics.html">5. + Diagnostics + +</a></span></dt><dd><dl><dt><span class="section"><a href="diagnostics.html#std.diagnostics.exceptions">Exceptions</a></span></dt><dd><dl><dt><span class="section"><a href="diagnostics.html#std.diagnostics.exceptions.api">API Reference</a></span></dt><dt><span class="section"><a href="diagnostics.html#std.diagnostics.exceptions.data">Adding Data to <code class="classname">exception</code></a></span></dt></dl></dd><dt><span class="section"><a href="bk01pt02ch05s02.html">Concept Checking</a></span></dt></dl></dd><dt><span class="chapter"><a href="utilities.html">6. + Utilities + +</a></span></dt><dd><dl><dt><span class="section"><a href="utilities.html#std.util.functors">Functors</a></span></dt><dt><span class="section"><a href="pairs.html">Pairs</a></span></dt><dt><span class="section"><a href="memory.html">Memory</a></span></dt><dd><dl><dt><span class="section"><a href="memory.html#std.util.memory.allocator">Allocators</a></span></dt><dt><span class="section"><a href="memory.html#std.util.memory.auto_ptr">auto_ptr</a></span></dt><dt><span class="section"><a href="memory.html#std.util.memory.shared_ptr">shared_ptr</a></span></dt></dl></dd><dt><span class="section"><a href="traits.html">Traits</a></span></dt></dl></dd><dt><span class="chapter"><a href="strings.html">7. + Strings + +</a></span></dt><dd><dl><dt><span class="section"><a href="strings.html#std.strings.string">String Classes</a></span></dt><dd><dl><dt><span class="section"><a href="strings.html#strings.string.simple">Simple Transformations</a></span></dt><dt><span class="section"><a href="strings.html#strings.string.case">Case Sensitivity</a></span></dt><dt><span class="section"><a href="strings.html#strings.string.character_types">Arbitrary Character Types</a></span></dt><dt><span class="section"><a href="strings.html#strings.string.token">Tokenizing</a></span></dt><dt><span class="section"><a href="strings.html#strings.string.shrink">Shrink to Fit</a></span></dt><dt><span class="section"><a href="strings.html#strings.string.Cstring">CString (MFC)</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="localization.html">8. + Localization + +</a></span></dt><dd><dl><dt><span class="section"><a href="localization.html#std.localization.locales">Locales</a></span></dt><dd><dl><dt><span class="section"><a href="localization.html#std.localization.locales.locale">locale</a></span></dt></dl></dd><dt><span class="section"><a href="facets.html">Facets</a></span></dt><dd><dl><dt><span class="section"><a href="facets.html#std.localization.facet.ctype">ctype</a></span></dt><dt><span class="section"><a href="facets.html#std.localization.facet.codecvt">codecvt</a></span></dt><dt><span class="section"><a href="facets.html#manual.localization.facet.messages">messages</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="containers.html">9. + Containers + +</a></span></dt><dd><dl><dt><span class="section"><a href="containers.html#std.containers.sequences">Sequences</a></span></dt><dd><dl><dt><span class="section"><a href="containers.html#containers.sequences.list">list</a></span></dt><dt><span class="section"><a href="containers.html#containers.sequences.vector">vector</a></span></dt></dl></dd><dt><span class="section"><a href="associative.html">Associative</a></span></dt><dd><dl><dt><span class="section"><a href="associative.html#containers.associative.insert_hints">Insertion Hints</a></span></dt><dt><span class="section"><a href="associative.html#containers.associative.bitset">bitset</a></span></dt></dl></dd><dt><span class="section"><a href="containers_and_c.html">Interacting with C</a></span></dt><dd><dl><dt><span class="section"><a href="containers_and_c.html#containers.c.vs_array">Containers vs. Arrays</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="iterators.html">10. + Iterators + +</a></span></dt><dd><dl><dt><span class="section"><a href="iterators.html#std.iterators.predefined">Predefined</a></span></dt><dd><dl><dt><span class="section"><a href="iterators.html#iterators.predefined.vs_pointers">Iterators vs. Pointers</a></span></dt><dt><span class="section"><a href="iterators.html#iterators.predefined.end">One Past the End</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="algorithms.html">11. + Algorithms + +</a></span></dt><dd><dl><dt><span class="section"><a href="algorithms.html#std.algorithms.mutating">Mutating</a></span></dt><dd><dl><dt><span class="section"><a href="algorithms.html#algorithms.mutating.swap"><code class="function">swap</code></a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="numerics.html">12. + Numerics + +</a></span></dt><dd><dl><dt><span class="section"><a href="numerics.html#std.numerics.complex">Complex</a></span></dt><dd><dl><dt><span class="section"><a href="numerics.html#numerics.complex.processing">complex Processing</a></span></dt></dl></dd><dt><span class="section"><a href="generalized_numeric_operations.html">Generalized Operations</a></span></dt><dt><span class="section"><a href="numerics_and_c.html">Interacting with C</a></span></dt><dd><dl><dt><span class="section"><a href="numerics_and_c.html#numerics.c.array">Numerics vs. Arrays</a></span></dt><dt><span class="section"><a href="numerics_and_c.html#numerics.c.c99">C99</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="io.html">13. + Input and Output + +</a></span></dt><dd><dl><dt><span class="section"><a href="io.html#std.io.objects">Iostream Objects</a></span></dt><dt><span class="section"><a href="streambufs.html">Stream Buffers</a></span></dt><dd><dl><dt><span class="section"><a href="streambufs.html#io.streambuf.derived">Derived streambuf Classes</a></span></dt><dt><span class="section"><a href="streambufs.html#io.streambuf.buffering">Buffering</a></span></dt></dl></dd><dt><span class="section"><a href="stringstreams.html">Memory Based Streams</a></span></dt><dd><dl><dt><span class="section"><a href="stringstreams.html#std.io.memstreams.compat">Compatibility With strstream</a></span></dt></dl></dd><dt><span class="section"><a href="fstreams.html">File Based Streams</a></span></dt><dd><dl><dt><span class="section"><a href="fstreams.html#std.io.filestreams.copying_a_file">Copying a File</a></span></dt><dt><span class="section"><a href="fstreams.html#std.io.filestreams.binary">Binary Input and Output</a></span></dt></dl></dd><dt><span class="section"><a href="io_and_c.html">Interacting with C</a></span></dt><dd><dl><dt><span class="section"><a href="io_and_c.html#std.io.c.FILE">Using FILE* and file descriptors</a></span></dt><dt><span class="section"><a href="io_and_c.html#std.io.c.sync">Performance</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="atomics.html">14. + Atomics + +</a></span></dt><dd><dl><dt><span class="section"><a href="atomics.html#std.atomics.api">API Reference</a></span></dt></dl></dd><dt><span class="chapter"><a href="concurrency.html">15. + Concurrency + +</a></span></dt><dd><dl><dt><span class="section"><a href="concurrency.html#std.concurrency.api">API Reference</a></span></dt></dl></dd></dl></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="debug.html">Prev</a> </td><td align="center"><a accesskey="u" href="spine.html">Up</a></td><td align="right"> <a accesskey="n" href="support.html">Next</a></td></tr><tr><td align="left" valign="top">Debugging Support </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Chapter 4. + Support + +</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/bk01pt02ch05s02.html b/libstdc++-v3/doc/html/manual/bk01pt02ch05s02.html new file mode 100644 index 000000000..6a67bef7c --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bk01pt02ch05s02.html @@ -0,0 +1,50 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Concept Checking</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="diagnostics.html" title="Chapter 5. Diagnostics"/><link rel="prev" href="diagnostics.html" title="Chapter 5. Diagnostics"/><link rel="next" href="utilities.html" title="Chapter 6. Utilities"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Concept Checking</th></tr><tr><td align="left"><a accesskey="p" href="diagnostics.html">Prev</a> </td><th width="60%" align="center">Chapter 5. + Diagnostics + +</th><td align="right"> <a accesskey="n" href="utilities.html">Next</a></td></tr></table><hr/></div><div class="section" title="Concept Checking"><div class="titlepage"><div><div><h2 class="title"><a id="std.diagnostics.concept_checking"/>Concept Checking</h2></div></div></div><p> + In 1999, SGI added <span class="quote">“<span class="quote">concept checkers</span>”</span> to their + implementation of the STL: code which checked the template + parameters of instantiated pieces of the STL, in order to insure + that the parameters being used met the requirements of the + standard. For example, the Standard requires that types passed as + template parameters to <code class="classname">vector</code> be + "Assignable" (which means what you think it means). The + checking was done during compilation, and none of the code was + executed at runtime. + </p><p> + Unfortunately, the size of the compiler files grew significantly + as a result. The checking code itself was cumbersome. And bugs + were found in it on more than one occasion. + </p><p> + The primary author of the checking code, Jeremy Siek, had already + started work on a replacement implementation. The new code was + formally reviewed and accepted into + <a class="link" href="http://www.boost.org/libs/concept_check/concept_check.htm">the + Boost libraries</a>, and we are pleased to incorporate it into the + GNU C++ library. + </p><p> + The new version imposes a much smaller space overhead on the generated + object file. The checks are also cleaner and easier to read and + understand. + </p><p> + They are off by default for all versions of GCC. + They can be enabled at configure time with + <a class="link" href="configure.html" title="Configure"><code class="literal">--enable-concept-checks</code></a>. + You can enable them on a per-translation-unit basis with + <code class="literal">-D_GLIBCXX_CONCEPT_CHECKS</code>. + </p><p> + Please note that the checks are based on the requirements in the original + C++ standard, some of which have changed in the upcoming C++0x revision. + Additionally, some correct code might be rejected by the concept checks, + for example template argument types may need to be complete when used in + a template definition, rather than at the point of instantiation. + There are no plans to address these shortcomings. + </p></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="diagnostics.html">Prev</a> </td><td align="center"><a accesskey="u" href="diagnostics.html">Up</a></td><td align="right"> <a accesskey="n" href="utilities.html">Next</a></td></tr><tr><td align="left" valign="top">Chapter 5. + Diagnostics + + </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Chapter 6. + Utilities + +</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch17s02.html b/libstdc++-v3/doc/html/manual/bk01pt03ch17s02.html new file mode 100644 index 000000000..8fa7981de --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch17s02.html @@ -0,0 +1,55 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Semantics</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" C++ , library , debug "/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="debug_mode.html" title="Chapter 17. Debug Mode"/><link rel="prev" href="debug_mode.html" title="Chapter 17. Debug Mode"/><link rel="next" href="bk01pt03ch17s03.html" title="Using"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Semantics</th></tr><tr><td align="left"><a accesskey="p" href="debug_mode.html">Prev</a> </td><th width="60%" align="center">Chapter 17. Debug Mode</th><td align="right"> <a accesskey="n" href="bk01pt03ch17s03.html">Next</a></td></tr></table><hr/></div><div class="section" title="Semantics"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.debug_mode.semantics"/>Semantics</h2></div></div></div><p> + </p><p>A program that uses the C++ standard library correctly + will maintain the same semantics under debug mode as it had with + the normal (release) library. All functional and exception-handling + guarantees made by the normal library also hold for the debug mode + library, with one exception: performance guarantees made by the + normal library may not hold in the debug mode library. For + instance, erasing an element in a <code class="code">std::list</code> is a + constant-time operation in normal library, but in debug mode it is + linear in the number of iterators that reference that particular + list. So while your (correct) program won't change its results, it + is likely to execute more slowly.</p><p>libstdc++ includes many extensions to the C++ standard library. In + some cases the extensions are obvious, such as the hashed + associative containers, whereas other extensions give predictable + results to behavior that would otherwise be undefined, such as + throwing an exception when a <code class="code">std::basic_string</code> is + constructed from a NULL character pointer. This latter category also + includes implementation-defined and unspecified semantics, such as + the growth rate of a vector. Use of these extensions is not + considered incorrect, so code that relies on them will not be + rejected by debug mode. However, use of these extensions may affect + the portability of code to other implementations of the C++ standard + library, and is therefore somewhat hazardous. For this reason, the + libstdc++ debug mode offers a "pedantic" mode (similar to + GCC's <code class="code">-pedantic</code> compiler flag) that attempts to emulate + the semantics guaranteed by the C++ standard. For + instance, constructing a <code class="code">std::basic_string</code> with a NULL + character pointer would result in an exception under normal mode or + non-pedantic debug mode (this is a libstdc++ extension), whereas + under pedantic debug mode libstdc++ would signal an error. To enable + the pedantic debug mode, compile your program with + both <code class="code">-D_GLIBCXX_DEBUG</code> + and <code class="code">-D_GLIBCXX_DEBUG_PEDANTIC</code> . + (N.B. In GCC 3.4.x and 4.0.0, due to a bug, + <code class="code">-D_GLIBXX_DEBUG_PEDANTIC</code> was also needed. The problem has + been fixed in GCC 4.0.1 and later versions.) </p><p>The following library components provide extra debugging + capabilities in debug mode:</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><code class="code">std::basic_string</code> (no safe iterators and see note below)</p></li><li class="listitem"><p><code class="code">std::bitset</code></p></li><li class="listitem"><p><code class="code">std::deque</code></p></li><li class="listitem"><p><code class="code">std::list</code></p></li><li class="listitem"><p><code class="code">std::map</code></p></li><li class="listitem"><p><code class="code">std::multimap</code></p></li><li class="listitem"><p><code class="code">std::multiset</code></p></li><li class="listitem"><p><code class="code">std::set</code></p></li><li class="listitem"><p><code class="code">std::vector</code></p></li><li class="listitem"><p><code class="code">std::unordered_map</code></p></li><li class="listitem"><p><code class="code">std::unordered_multimap</code></p></li><li class="listitem"><p><code class="code">std::unordered_set</code></p></li><li class="listitem"><p><code class="code">std::unordered_multiset</code></p></li></ul></div><p>N.B. although there are precondition checks for some string operations, +e.g. <code class="code">operator[]</code>, +they will not always be run when using the <code class="code">char</code> and +<code class="code">wchar_t</code> specialisations (<code class="code">std::string</code> and +<code class="code">std::wstring</code>). This is because libstdc++ uses GCC's +<code class="code">extern template</code> extension to provide explicit instantiations +of <code class="code">std::string</code> and <code class="code">std::wstring</code>, and those +explicit instantiations don't include the debug-mode checks. If the +containing functions are inlined then the checks will run, so compiling +with <code class="code">-O1</code> might be enough to enable them. Alternatively +<code class="code">-D_GLIBCXX_EXTERN_TEMPLATE=0</code> will suppress the declarations +of the explicit instantiations and cause the functions to be instantiated +with the debug-mode checks included, but this is unsupported and not +guaranteed to work. For full debug-mode support you can use the +<code class="code">__gnu_debug::basic_string</code> debugging container directly, +which always works correctly. +</p></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="debug_mode.html">Prev</a> </td><td align="center"><a accesskey="u" href="debug_mode.html">Up</a></td><td align="right"> <a accesskey="n" href="bk01pt03ch17s03.html">Next</a></td></tr><tr><td align="left" valign="top">Chapter 17. Debug Mode </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Using</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch17s03.html b/libstdc++-v3/doc/html/manual/bk01pt03ch17s03.html new file mode 100644 index 000000000..7e017b62b --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch17s03.html @@ -0,0 +1,24 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Using</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" C++ , library , debug "/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="debug_mode.html" title="Chapter 17. Debug Mode"/><link rel="prev" href="bk01pt03ch17s02.html" title="Semantics"/><link rel="next" href="bk01pt03ch17s04.html" title="Design"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Using</th></tr><tr><td align="left"><a accesskey="p" href="bk01pt03ch17s02.html">Prev</a> </td><th width="60%" align="center">Chapter 17. Debug Mode</th><td align="right"> <a accesskey="n" href="bk01pt03ch17s04.html">Next</a></td></tr></table><hr/></div><div class="section" title="Using"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.debug_mode.using"/>Using</h2></div></div></div><p> + </p><div class="section" title="Using the Debug Mode"><div class="titlepage"><div><div><h3 class="title"><a id="debug_mode.using.mode"/>Using the Debug Mode</h3></div></div></div><p>To use the libstdc++ debug mode, compile your application with the + compiler flag <code class="code">-D_GLIBCXX_DEBUG</code>. Note that this flag + changes the sizes and behavior of standard class templates such + as <code class="code">std::vector</code>, and therefore you can only link code + compiled with debug mode and code compiled without debug mode if no + instantiation of a container is passed between the two translation + units.</p><p>By default, error messages are formatted to fit on lines of about + 78 characters. The environment variable + <code class="code">GLIBCXX_DEBUG_MESSAGE_LENGTH</code> can be used to request a + different length.</p></div><div class="section" title="Using a Specific Debug Container"><div class="titlepage"><div><div><h3 class="title"><a id="debug_mode.using.specific"/>Using a Specific Debug Container</h3></div></div></div><p>When it is not feasible to recompile your entire application, or + only specific containers need checking, debugging containers are + available as GNU extensions. These debugging containers are + functionally equivalent to the standard drop-in containers used in + debug mode, but they are available in a separate namespace as GNU + extensions and may be used in programs compiled with either release + mode or with debug mode. The + following table provides the names and headers of the debugging + containers: +</p><div class="table"><a id="id482419"/><p class="title"><strong>Table 17.1. Debugging Containers</strong></p><div class="table-contents"><table summary="Debugging Containers" border="1"><colgroup><col style="text-align: left" class="c1"/><col style="text-align: left" class="c2"/><col style="text-align: left" class="c3"/><col style="text-align: left" class="c4"/></colgroup><thead><tr><th style="text-align: left">Container</th><th style="text-align: left">Header</th><th style="text-align: left">Debug container</th><th style="text-align: left">Debug header</th></tr></thead><tbody><tr><td style="text-align: left"><code class="classname">std::bitset</code></td><td style="text-align: left"><code class="filename">bitset</code></td><td style="text-align: left"><code class="classname">__gnu_debug::bitset</code></td><td style="text-align: left"><code class="filename"><debug/bitset></code></td></tr><tr><td style="text-align: left"><code class="classname">std::deque</code></td><td style="text-align: left"><code class="filename">deque</code></td><td style="text-align: left"><code class="classname">__gnu_debug::deque</code></td><td style="text-align: left"><code class="filename"><debug/deque></code></td></tr><tr><td style="text-align: left"><code class="classname">std::list</code></td><td style="text-align: left"><code class="filename">list</code></td><td style="text-align: left"><code class="classname">__gnu_debug::list</code></td><td style="text-align: left"><code class="filename"><debug/list></code></td></tr><tr><td style="text-align: left"><code class="classname">std::map</code></td><td style="text-align: left"><code class="filename">map</code></td><td style="text-align: left"><code class="classname">__gnu_debug::map</code></td><td style="text-align: left"><code class="filename"><debug/map></code></td></tr><tr><td style="text-align: left"><code class="classname">std::multimap</code></td><td style="text-align: left"><code class="filename">map</code></td><td style="text-align: left"><code class="classname">__gnu_debug::multimap</code></td><td style="text-align: left"><code class="filename"><debug/map></code></td></tr><tr><td style="text-align: left"><code class="classname">std::multiset</code></td><td style="text-align: left"><code class="filename">set</code></td><td style="text-align: left"><code class="classname">__gnu_debug::multiset</code></td><td style="text-align: left"><code class="filename"><debug/set></code></td></tr><tr><td style="text-align: left"><code class="classname">std::set</code></td><td style="text-align: left"><code class="filename">set</code></td><td style="text-align: left"><code class="classname">__gnu_debug::set</code></td><td style="text-align: left"><code class="filename"><debug/set></code></td></tr><tr><td style="text-align: left"><code class="classname">std::string</code></td><td style="text-align: left"><code class="filename">string</code></td><td style="text-align: left"><code class="classname">__gnu_debug::string</code></td><td style="text-align: left"><code class="filename"><debug/string></code></td></tr><tr><td style="text-align: left"><code class="classname">std::wstring</code></td><td style="text-align: left"><code class="filename">string</code></td><td style="text-align: left"><code class="classname">__gnu_debug::wstring</code></td><td style="text-align: left"><code class="filename"><debug/string></code></td></tr><tr><td style="text-align: left"><code class="classname">std::basic_string</code></td><td style="text-align: left"><code class="filename">string</code></td><td style="text-align: left"><code class="classname">__gnu_debug::basic_string</code></td><td style="text-align: left"><code class="filename"><debug/string></code></td></tr><tr><td style="text-align: left"><code class="classname">std::vector</code></td><td style="text-align: left"><code class="filename">vector</code></td><td style="text-align: left"><code class="classname">__gnu_debug::vector</code></td><td style="text-align: left"><code class="filename"><debug/vector></code></td></tr></tbody></table></div></div><br class="table-break"/><p>In addition, when compiling in C++0x mode, these additional +containers have additional debug capability. +</p><div class="table"><a id="id482793"/><p class="title"><strong>Table 17.2. Debugging Containers C++0x</strong></p><div class="table-contents"><table summary="Debugging Containers C++0x" border="1"><colgroup><col style="text-align: left" class="c1"/><col style="text-align: left" class="c2"/><col style="text-align: left" class="c3"/><col style="text-align: left" class="c4"/></colgroup><thead><tr><th style="text-align: left">Container</th><th style="text-align: left">Header</th><th style="text-align: left">Debug container</th><th style="text-align: left">Debug header</th></tr></thead><tbody><tr><td style="text-align: left"><code class="classname">std::unordered_map</code></td><td style="text-align: left"><code class="filename">unordered_map</code></td><td style="text-align: left"><code class="classname">__gnu_debug::unordered_map</code></td><td style="text-align: left"><code class="filename"><debug/unordered_map></code></td></tr><tr><td style="text-align: left"><code class="classname">std::unordered_multimap</code></td><td style="text-align: left"><code class="filename">unordered_map</code></td><td style="text-align: left"><code class="classname">__gnu_debug::unordered_multimap</code></td><td style="text-align: left"><code class="filename"><debug/unordered_map></code></td></tr><tr><td style="text-align: left"><code class="classname">std::unordered_set</code></td><td style="text-align: left"><code class="filename">unordered_set</code></td><td style="text-align: left"><code class="classname">__gnu_debug::unordered_set</code></td><td style="text-align: left"><code class="filename"><debug/unordered_set></code></td></tr><tr><td style="text-align: left"><code class="classname">std::unordered_multiset</code></td><td style="text-align: left"><code class="filename">unordered_set</code></td><td style="text-align: left"><code class="classname">__gnu_debug::unordered_multiset</code></td><td style="text-align: left"><code class="filename"><debug/unordered_set></code></td></tr></tbody></table></div></div><br class="table-break"/></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="bk01pt03ch17s02.html">Prev</a> </td><td align="center"><a accesskey="u" href="debug_mode.html">Up</a></td><td align="right"> <a accesskey="n" href="bk01pt03ch17s04.html">Next</a></td></tr><tr><td align="left" valign="top">Semantics </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Design</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch17s04.html b/libstdc++-v3/doc/html/manual/bk01pt03ch17s04.html new file mode 100644 index 000000000..3e35af0fa --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch17s04.html @@ -0,0 +1,412 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Design</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" C++ , library , debug "/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="debug_mode.html" title="Chapter 17. Debug Mode"/><link rel="prev" href="bk01pt03ch17s03.html" title="Using"/><link rel="next" href="parallel_mode.html" title="Chapter 18. Parallel Mode"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Design</th></tr><tr><td align="left"><a accesskey="p" href="bk01pt03ch17s03.html">Prev</a> </td><th width="60%" align="center">Chapter 17. Debug Mode</th><td align="right"> <a accesskey="n" href="parallel_mode.html">Next</a></td></tr></table><hr/></div><div class="section" title="Design"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.debug_mode.design"/>Design</h2></div></div></div><p> + </p><div class="section" title="Goals"><div class="titlepage"><div><div><h3 class="title"><a id="debug_mode.design.goals"/>Goals</h3></div></div></div><p> + </p><p> The libstdc++ debug mode replaces unsafe (but efficient) standard + containers and iterators with semantically equivalent safe standard + containers and iterators to aid in debugging user programs. The + following goals directed the design of the libstdc++ debug mode:</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><span class="emphasis"><em>Correctness</em></span>: the libstdc++ debug mode must not change + the semantics of the standard library for all cases specified in + the ANSI/ISO C++ standard. The essence of this constraint is that + any valid C++ program should behave in the same manner regardless + of whether it is compiled with debug mode or release mode. In + particular, entities that are defined in namespace std in release + mode should remain defined in namespace std in debug mode, so that + legal specializations of namespace std entities will remain + valid. A program that is not valid C++ (e.g., invokes undefined + behavior) is not required to behave similarly, although the debug + mode will abort with a diagnostic when it detects undefined + behavior.</p></li><li class="listitem"><p><span class="emphasis"><em>Performance</em></span>: the additional of the libstdc++ debug mode + must not affect the performance of the library when it is compiled + in release mode. Performance of the libstdc++ debug mode is + secondary (and, in fact, will be worse than the release + mode).</p></li><li class="listitem"><p><span class="emphasis"><em>Usability</em></span>: the libstdc++ debug mode should be easy to + use. It should be easily incorporated into the user's development + environment (e.g., by requiring only a single new compiler switch) + and should produce reasonable diagnostics when it detects a + problem with the user program. Usability also involves detection + of errors when using the debug mode incorrectly, e.g., by linking + a release-compiled object against a debug-compiled object if in + fact the resulting program will not run correctly.</p></li><li class="listitem"><p><span class="emphasis"><em>Minimize recompilation</em></span>: While it is expected that + users recompile at least part of their program to use debug + mode, the amount of recompilation affects the + detect-compile-debug turnaround time. This indirectly affects the + usefulness of the debug mode, because debugging some applications + may require rebuilding a large amount of code, which may not be + feasible when the suspect code may be very localized. There are + several levels of conformance to this requirement, each with its + own usability and implementation characteristics. In general, the + higher-numbered conformance levels are more usable (i.e., require + less recompilation) but are more complicated to implement than + the lower-numbered conformance levels. + </p><div class="orderedlist"><ol class="orderedlist"><li class="listitem"><p><span class="emphasis"><em>Full recompilation</em></span>: The user must recompile his or + her entire application and all C++ libraries it depends on, + including the C++ standard library that ships with the + compiler. This must be done even if only a small part of the + program can use debugging features.</p></li><li class="listitem"><p><span class="emphasis"><em>Full user recompilation</em></span>: The user must recompile + his or her entire application and all C++ libraries it depends + on, but not the C++ standard library itself. This must be done + even if only a small part of the program can use debugging + features. This can be achieved given a full recompilation + system by compiling two versions of the standard library when + the compiler is installed and linking against the appropriate + one, e.g., a multilibs approach.</p></li><li class="listitem"><p><span class="emphasis"><em>Partial recompilation</em></span>: The user must recompile the + parts of his or her application and the C++ libraries it + depends on that will use the debugging facilities + directly. This means that any code that uses the debuggable + standard containers would need to be recompiled, but code + that does not use them (but may, for instance, use IOStreams) + would not have to be recompiled.</p></li><li class="listitem"><p><span class="emphasis"><em>Per-use recompilation</em></span>: The user must recompile the + parts of his or her application and the C++ libraries it + depends on where debugging should occur, and any other code + that interacts with those containers. This means that a set of + translation units that accesses a particular standard + container instance may either be compiled in release mode (no + checking) or debug mode (full checking), but must all be + compiled in the same way; a translation unit that does not see + that standard container instance need not be recompiled. This + also means that a translation unit <span class="emphasis"><em>A</em></span> that contains a + particular instantiation + (say, <code class="code">std::vector<int></code>) compiled in release + mode can be linked against a translation unit <span class="emphasis"><em>B</em></span> that + contains the same instantiation compiled in debug mode (a + feature not present with partial recompilation). While this + behavior is technically a violation of the One Definition + Rule, this ability tends to be very important in + practice. The libstdc++ debug mode supports this level of + recompilation. </p></li><li class="listitem"><p><span class="emphasis"><em>Per-unit recompilation</em></span>: The user must only + recompile the translation units where checking should occur, + regardless of where debuggable standard containers are + used. This has also been dubbed "<code class="code">-g</code> mode", + because the <code class="code">-g</code> compiler switch works in this way, + emitting debugging information at a per--translation-unit + granularity. We believe that this level of recompilation is in + fact not possible if we intend to supply safe iterators, leave + the program semantics unchanged, and not regress in + performance under release mode because we cannot associate + extra information with an iterator (to form a safe iterator) + without either reserving that space in release mode + (performance regression) or allocating extra memory associated + with each iterator with <code class="code">new</code> (changes the program + semantics).</p></li></ol></div><p> + </p></li></ul></div></div><div class="section" title="Methods"><div class="titlepage"><div><div><h3 class="title"><a id="debug_mode.design.methods"/>Methods</h3></div></div></div><p> + </p><p>This section provides an overall view of the design of the + libstdc++ debug mode and details the relationship between design + decisions and the stated design goals.</p><div class="section" title="The Wrapper Model"><div class="titlepage"><div><div><h4 class="title"><a id="debug_mode.design.methods.wrappers"/>The Wrapper Model</h4></div></div></div><p>The libstdc++ debug mode uses a wrapper model where the + debugging versions of library components (e.g., iterators and + containers) form a layer on top of the release versions of the + library components. The debugging components first verify that the + operation is correct (aborting with a diagnostic if an error is + found) and will then forward to the underlying release-mode + container that will perform the actual work. This design decision + ensures that we cannot regress release-mode performance (because the + release-mode containers are left untouched) and partially + enables <a class="link" href="bk01pt03ch17s04.html#methods.coexistence.link" title="Link- and run-time coexistence of release- and debug-mode components">mixing debug and + release code</a> at link time, although that will not be + discussed at this time.</p><p>Two types of wrappers are used in the implementation of the debug + mode: container wrappers and iterator wrappers. The two types of + wrappers interact to maintain relationships between iterators and + their associated containers, which are necessary to detect certain + types of standard library usage errors such as dereferencing + past-the-end iterators or inserting into a container using an + iterator from a different container.</p><div class="section" title="Safe Iterators"><div class="titlepage"><div><div><h5 class="title"><a id="debug_mode.design.methods.safe_iter"/>Safe Iterators</h5></div></div></div><p>Iterator wrappers provide a debugging layer over any iterator that + is attached to a particular container, and will manage the + information detailing the iterator's state (singular, + dereferenceable, etc.) and tracking the container to which the + iterator is attached. Because iterators have a well-defined, common + interface the iterator wrapper is implemented with the iterator + adaptor class template <code class="code">__gnu_debug::_Safe_iterator</code>, + which takes two template parameters:</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><code class="code">Iterator</code>: The underlying iterator type, which must + be either the <code class="code">iterator</code> or <code class="code">const_iterator</code> + typedef from the sequence type this iterator can reference.</p></li><li class="listitem"><p><code class="code">Sequence</code>: The type of sequence that this iterator + references. This sequence must be a safe sequence (discussed below) + whose <code class="code">iterator</code> or <code class="code">const_iterator</code> typedef + is the type of the safe iterator.</p></li></ul></div></div><div class="section" title="Safe Sequences (Containers)"><div class="titlepage"><div><div><h5 class="title"><a id="debug_mode.design.methods.safe_seq"/>Safe Sequences (Containers)</h5></div></div></div><p>Container wrappers provide a debugging layer over a particular + container type. Because containers vary greatly in the member + functions they support and the semantics of those member functions + (especially in the area of iterator invalidation), container + wrappers are tailored to the container they reference, e.g., the + debugging version of <code class="code">std::list</code> duplicates the entire + interface of <code class="code">std::list</code>, adding additional semantic + checks and then forwarding operations to the + real <code class="code">std::list</code> (a public base class of the debugging + version) as appropriate. However, all safe containers inherit from + the class template <code class="code">__gnu_debug::_Safe_sequence</code>, + instantiated with the type of the safe container itself (an instance + of the curiously recurring template pattern).</p><p>The iterators of a container wrapper will be + <a class="link" href="bk01pt03ch17s04.html#debug_mode.design.methods.safe_iter" title="Safe Iterators">safe + iterators</a> that reference sequences of this type and wrap the + iterators provided by the release-mode base class. The debugging + container will use only the safe iterators within its own interface + (therefore requiring the user to use safe iterators, although this + does not change correct user code) and will communicate with the + release-mode base class with only the underlying, unsafe, + release-mode iterators that the base class exports.</p><p> The debugging version of <code class="code">std::list</code> will have the + following basic structure:</p><pre class="programlisting"> +template<typename _Tp, typename _Allocator = allocator<_Tp> + class debug-list : + public release-list<_Tp, _Allocator>, + public __gnu_debug::_Safe_sequence<debug-list<_Tp, _Allocator> > + { + typedef release-list<_Tp, _Allocator> _Base; + typedef debug-list<_Tp, _Allocator> _Self; + + public: + typedef __gnu_debug::_Safe_iterator<typename _Base::iterator, _Self> iterator; + typedef __gnu_debug::_Safe_iterator<typename _Base::const_iterator, _Self> const_iterator; + + // duplicate std::list interface with debugging semantics + }; +</pre></div></div><div class="section" title="Precondition Checking"><div class="titlepage"><div><div><h4 class="title"><a id="debug_mode.design.methods.precond"/>Precondition Checking</h4></div></div></div><p>The debug mode operates primarily by checking the preconditions of + all standard library operations that it supports. Preconditions that + are always checked (regardless of whether or not we are in debug + mode) are checked via the <code class="code">__check_xxx</code> macros defined + and documented in the source + file <code class="code">include/debug/debug.h</code>. Preconditions that may or + may not be checked, depending on the debug-mode + macro <code class="code">_GLIBCXX_DEBUG</code>, are checked via + the <code class="code">__requires_xxx</code> macros defined and documented in the + same source file. Preconditions are validated using any additional + information available at run-time, e.g., the containers that are + associated with a particular iterator, the position of the iterator + within those containers, the distance between two iterators that may + form a valid range, etc. In the absence of suitable information, + e.g., an input iterator that is not a safe iterator, these + precondition checks will silently succeed.</p><p>The majority of precondition checks use the aforementioned macros, + which have the secondary benefit of having prewritten debug + messages that use information about the current status of the + objects involved (e.g., whether an iterator is singular or what + sequence it is attached to) along with some static information + (e.g., the names of the function parameters corresponding to the + objects involved). When not using these macros, the debug mode uses + either the debug-mode assertion + macro <code class="code">_GLIBCXX_DEBUG_ASSERT</code> , its pedantic + cousin <code class="code">_GLIBCXX_DEBUG_PEDASSERT</code>, or the assertion + check macro that supports more advance formulation of error + messages, <code class="code">_GLIBCXX_DEBUG_VERIFY</code>. These macros are + documented more thoroughly in the debug mode source code.</p></div><div class="section" title="Release- and debug-mode coexistence"><div class="titlepage"><div><div><h4 class="title"><a id="debug_mode.design.methods.coexistence"/>Release- and debug-mode coexistence</h4></div></div></div><p>The libstdc++ debug mode is the first debug mode we know of that + is able to provide the "Per-use recompilation" (4) guarantee, that + allows release-compiled and debug-compiled code to be linked and + executed together without causing unpredictable behavior. This + guarantee minimizes the recompilation that users are required to + perform, shortening the detect-compile-debug bug hunting cycle + and making the debug mode easier to incorporate into development + environments by minimizing dependencies.</p><p>Achieving link- and run-time coexistence is not a trivial + implementation task. To achieve this goal we required a small + extension to the GNU C++ compiler (since incorporated into the C++0x language specification, described in the GCC Manual for the C++ language as + <a class="link" href="http://gcc.gnu.org/onlinedocs/gcc/Namespace-Association.html#Namespace-Association">namespace + association</a>), and a complex organization of debug- and + release-modes. The end result is that we have achieved per-use + recompilation but have had to give up some checking of the + <code class="code">std::basic_string</code> class template (namely, safe + iterators). +</p><div class="section" title="Compile-time coexistence of release- and debug-mode components"><div class="titlepage"><div><div><h5 class="title"><a id="methods.coexistence.compile"/>Compile-time coexistence of release- and debug-mode components</h5></div></div></div><p>Both the release-mode components and the debug-mode + components need to exist within a single translation unit so that + the debug versions can wrap the release versions. However, only one + of these components should be user-visible at any particular + time with the standard name, e.g., <code class="code">std::list</code>. </p><p>In release mode, we define only the release-mode version of the + component with its standard name and do not include the debugging + component at all. The release mode version is defined within the + namespace <code class="code">std</code>. Minus the namespace associations, this + method leaves the behavior of release mode completely unchanged from + its behavior prior to the introduction of the libstdc++ debug + mode. Here's an example of what this ends up looking like, in + C++.</p><pre class="programlisting"> +namespace std +{ + template<typename _Tp, typename _Alloc = allocator<_Tp> > + class list + { + // ... + }; +} // namespace std +</pre><p>In debug mode we include the release-mode container (which is now +defined in the namespace <code class="code">__cxx1998</code>) and also the +debug-mode container. The debug-mode container is defined within the +namespace <code class="code">__debug</code>, which is associated with namespace +<code class="code">std</code> via the C++0x namespace association language feature. This +method allows the debug and release versions of the same component to +coexist at compile-time and link-time without causing an unreasonable +maintenance burden, while minimizing confusion. Again, this boils down +to C++ code as follows:</p><pre class="programlisting"> +namespace std +{ + namespace __cxx1998 + { + template<typename _Tp, typename _Alloc = allocator<_Tp> > + class list + { + // ... + }; + } // namespace __gnu_norm + + namespace __debug + { + template<typename _Tp, typename _Alloc = allocator<_Tp> > + class list + : public __cxx1998::list<_Tp, _Alloc>, + public __gnu_debug::_Safe_sequence<list<_Tp, _Alloc> > + { + // ... + }; + } // namespace __cxx1998 + + // namespace __debug __attribute__ ((strong)); + inline namespace __debug { } +} +</pre></div><div class="section" title="Link- and run-time coexistence of release- and debug-mode components"><div class="titlepage"><div><div><h5 class="title"><a id="methods.coexistence.link"/>Link- and run-time coexistence of release- and + debug-mode components</h5></div></div></div><p>Because each component has a distinct and separate release and +debug implementation, there is no issue with link-time +coexistence: the separate namespaces result in different mangled +names, and thus unique linkage.</p><p>However, components that are defined and used within the C++ +standard library itself face additional constraints. For instance, +some of the member functions of <code class="code"> std::moneypunct</code> return +<code class="code">std::basic_string</code>. Normally, this is not a problem, but +with a mixed mode standard library that could be using either +debug-mode or release-mode <code class="code"> basic_string</code> objects, things +get more complicated. As the return value of a function is not +encoded into the mangled name, there is no way to specify a +release-mode or a debug-mode string. In practice, this results in +runtime errors. A simplified example of this problem is as follows. +</p><p> Take this translation unit, compiled in debug-mode: </p><pre class="programlisting"> +// -D_GLIBCXX_DEBUG +#include <string> + +std::string test02(); + +std::string test01() +{ + return test02(); +} + +int main() +{ + test01(); + return 0; +} +</pre><p> ... and linked to this translation unit, compiled in release mode:</p><pre class="programlisting"> +#include <string> + +std::string +test02() +{ + return std::string("toast"); +} +</pre><p> For this reason we cannot easily provide safe iterators for + the <code class="code">std::basic_string</code> class template, as it is present + throughout the C++ standard library. For instance, locale facets + define typedefs that include <code class="code">basic_string</code>: in a mixed + debug/release program, should that typedef be based on the + debug-mode <code class="code">basic_string</code> or the + release-mode <code class="code">basic_string</code>? While the answer could be + "both", and the difference hidden via renaming a la the + debug/release containers, we must note two things about locale + facets:</p><div class="orderedlist"><ol class="orderedlist"><li class="listitem"><p>They exist as shared state: one can create a facet in one + translation unit and access the facet via the same type name in a + different translation unit. This means that we cannot have two + different versions of locale facets, because the types would not be + the same across debug/release-mode translation unit barriers.</p></li><li class="listitem"><p>They have virtual functions returning strings: these functions + mangle in the same way regardless of the mangling of their return + types (see above), and their precise signatures can be relied upon + by users because they may be overridden in derived classes.</p></li></ol></div><p>With the design of libstdc++ debug mode, we cannot effectively hide + the differences between debug and release-mode strings from the + user. Failure to hide the differences may result in unpredictable + behavior, and for this reason we have opted to only + perform <code class="code">basic_string</code> changes that do not require ABI + changes. The effect on users is expected to be minimal, as there are + simple alternatives (e.g., <code class="code">__gnu_debug::basic_string</code>), + and the usability benefit we gain from the ability to mix debug- and + release-compiled translation units is enormous.</p></div><div class="section" title="Alternatives for Coexistence"><div class="titlepage"><div><div><h5 class="title"><a id="methods.coexistence.alt"/>Alternatives for Coexistence</h5></div></div></div><p>The coexistence scheme above was chosen over many alternatives, + including language-only solutions and solutions that also required + extensions to the C++ front end. The following is a partial list of + solutions, with justifications for our rejection of each.</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><span class="emphasis"><em>Completely separate debug/release libraries</em></span>: This is by + far the simplest implementation option, where we do not allow any + coexistence of debug- and release-compiled translation units in a + program. This solution has an extreme negative affect on usability, + because it is quite likely that some libraries an application + depends on cannot be recompiled easily. This would not meet + our <span class="emphasis"><em>usability</em></span> or <span class="emphasis"><em>minimize recompilation</em></span> criteria + well.</p></li><li class="listitem"><p><span class="emphasis"><em>Add a <code class="code">Debug</code> boolean template parameter</em></span>: + Partial specialization could be used to select the debug + implementation when <code class="code">Debug == true</code>, and the state + of <code class="code">_GLIBCXX_DEBUG</code> could decide whether the + default <code class="code">Debug</code> argument is <code class="code">true</code> + or <code class="code">false</code>. This option would break conformance with the + C++ standard in both debug <span class="emphasis"><em>and</em></span> release modes. This would + not meet our <span class="emphasis"><em>correctness</em></span> criteria. </p></li><li class="listitem"><p><span class="emphasis"><em>Packaging a debug flag in the allocators</em></span>: We could + reuse the <code class="code">Allocator</code> template parameter of containers + by adding a sentinel wrapper <code class="code">debug<></code> that + signals the user's intention to use debugging, and pick up + the <code class="code">debug<></code> allocator wrapper in a partial + specialization. However, this has two drawbacks: first, there is a + conformance issue because the default allocator would not be the + standard-specified <code class="code">std::allocator<T></code>. Secondly + (and more importantly), users that specify allocators instead of + implicitly using the default allocator would not get debugging + containers. Thus this solution fails the <span class="emphasis"><em>correctness</em></span> + criteria.</p></li><li class="listitem"><p><span class="emphasis"><em>Define debug containers in another namespace, and employ + a <code class="code">using</code> declaration (or directive)</em></span>: This is an + enticing option, because it would eliminate the need for + the <code class="code">link_name</code> extension by aliasing the + templates. However, there is no true template aliasing mechanism + in C++, because both <code class="code">using</code> directives and using + declarations disallow specialization. This method fails + the <span class="emphasis"><em>correctness</em></span> criteria.</p></li><li class="listitem"><p><span class="emphasis"><em> Use implementation-specific properties of anonymous + namespaces. </em></span> + See <a class="link" href="http://gcc.gnu.org/ml/libstdc++/2003-08/msg00004.html"> this post + </a> + This method fails the <span class="emphasis"><em>correctness</em></span> criteria.</p></li><li class="listitem"><p><span class="emphasis"><em>Extension: allow reopening on namespaces</em></span>: This would + allow the debug mode to effectively alias the + namespace <code class="code">std</code> to an internal namespace, such + as <code class="code">__gnu_std_debug</code>, so that it is completely + separate from the release-mode <code class="code">std</code> namespace. While + this will solve some renaming problems and ensure that + debug- and release-compiled code cannot be mixed unsafely, it ensures that + debug- and release-compiled code cannot be mixed at all. For + instance, the program would have two <code class="code">std::cout</code> + objects! This solution would fails the <span class="emphasis"><em>minimize + recompilation</em></span> requirement, because we would only be able to + support option (1) or (2).</p></li><li class="listitem"><p><span class="emphasis"><em>Extension: use link name</em></span>: This option involves + complicated re-naming between debug-mode and release-mode + components at compile time, and then a g++ extension called <span class="emphasis"><em> + link name </em></span> to recover the original names at link time. There + are two drawbacks to this approach. One, it's very verbose, + relying on macro renaming at compile time and several levels of + include ordering. Two, ODR issues remained with container member + functions taking no arguments in mixed-mode settings resulting in + equivalent link names, <code class="code"> vector::push_back() </code> being + one example. + See <a class="link" href="http://gcc.gnu.org/ml/libstdc++/2003-08/msg00177.html">link + name</a> </p></li></ul></div><p>Other options may exist for implementing the debug mode, many of + which have probably been considered and others that may still be + lurking. This list may be expanded over time to include other + options that we could have implemented, but in all cases the full + ramifications of the approach (as measured against the design goals + for a libstdc++ debug mode) should be considered first. The DejaGNU + testsuite includes some testcases that check for known problems with + some solutions (e.g., the <code class="code">using</code> declaration solution + that breaks user specialization), and additional testcases will be + added as we are able to identify other typical problem cases. These + test cases will serve as a benchmark by which we can compare debug + mode implementations.</p></div></div></div><div class="section" title="Other Implementations"><div class="titlepage"><div><div><h3 class="title"><a id="debug_mode.design.other"/>Other Implementations</h3></div></div></div><p> + </p><p> There are several existing implementations of debug modes for C++ + standard library implementations, although none of them directly + supports debugging for programs using libstdc++. The existing + implementations include:</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><a class="link" href="http://www.mathcs.sjsu.edu/faculty/horstman/safestl.html">SafeSTL</a>: + SafeSTL was the original debugging version of the Standard Template + Library (STL), implemented by Cay S. Horstmann on top of the + Hewlett-Packard STL. Though it inspired much work in this area, it + has not been kept up-to-date for use with modern compilers or C++ + standard library implementations.</p></li><li class="listitem"><p><a class="link" href="http://www.stlport.org/">STLport</a>: STLport is a free + implementation of the C++ standard library derived from the <a class="link" href="http://www.sgi.com/tech/stl/">SGI implementation</a>, and + ported to many other platforms. It includes a debug mode that uses a + wrapper model (that in some ways inspired the libstdc++ debug mode + design), although at the time of this writing the debug mode is + somewhat incomplete and meets only the "Full user recompilation" (2) + recompilation guarantee by requiring the user to link against a + different library in debug mode vs. release mode.</p></li><li class="listitem"><p>Metrowerks CodeWarrior: The C++ standard library + that ships with Metrowerks CodeWarrior includes a debug mode. It is + a full debug-mode implementation (including debugging for + CodeWarrior extensions) and is easy to use, although it meets only + the "Full recompilation" (1) recompilation + guarantee.</p></li></ul></div></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="bk01pt03ch17s03.html">Prev</a> </td><td align="center"><a accesskey="u" href="debug_mode.html">Up</a></td><td align="right"> <a accesskey="n" href="parallel_mode.html">Next</a></td></tr><tr><td align="left" valign="top">Using </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Chapter 18. Parallel Mode</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch18s02.html b/libstdc++-v3/doc/html/manual/bk01pt03ch18s02.html new file mode 100644 index 000000000..7a7419ac5 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch18s02.html @@ -0,0 +1,11 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Semantics</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" C++ , library , parallel "/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="parallel_mode.html" title="Chapter 18. Parallel Mode"/><link rel="prev" href="parallel_mode.html" title="Chapter 18. Parallel Mode"/><link rel="next" href="bk01pt03ch18s03.html" title="Using"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Semantics</th></tr><tr><td align="left"><a accesskey="p" href="parallel_mode.html">Prev</a> </td><th width="60%" align="center">Chapter 18. Parallel Mode</th><td align="right"> <a accesskey="n" href="bk01pt03ch18s03.html">Next</a></td></tr></table><hr/></div><div class="section" title="Semantics"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.parallel_mode.semantics"/>Semantics</h2></div></div></div><p> The parallel mode STL algorithms are currently not exception-safe, +i.e. user-defined functors must not throw exceptions. +Also, the order of execution is not guaranteed for some functions, of course. +Therefore, user-defined functors should not have any concurrent side effects. +</p><p> Since the current GCC OpenMP implementation does not support +OpenMP parallel regions in concurrent threads, +it is not possible to call parallel STL algorithm in +concurrent threads, either. +It might work with other compilers, though.</p></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="parallel_mode.html">Prev</a> </td><td align="center"><a accesskey="u" href="parallel_mode.html">Up</a></td><td align="right"> <a accesskey="n" href="bk01pt03ch18s03.html">Next</a></td></tr><tr><td align="left" valign="top">Chapter 18. Parallel Mode </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Using</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch18s03.html b/libstdc++-v3/doc/html/manual/bk01pt03ch18s03.html new file mode 100644 index 000000000..b3a3db937 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch18s03.html @@ -0,0 +1,66 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Using</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" C++ , library , parallel "/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="parallel_mode.html" title="Chapter 18. Parallel Mode"/><link rel="prev" href="bk01pt03ch18s02.html" title="Semantics"/><link rel="next" href="bk01pt03ch18s04.html" title="Design"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Using</th></tr><tr><td align="left"><a accesskey="p" href="bk01pt03ch18s02.html">Prev</a> </td><th width="60%" align="center">Chapter 18. Parallel Mode</th><td align="right"> <a accesskey="n" href="bk01pt03ch18s04.html">Next</a></td></tr></table><hr/></div><div class="section" title="Using"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.parallel_mode.using"/>Using</h2></div></div></div><div class="section" title="Prerequisite Compiler Flags"><div class="titlepage"><div><div><h3 class="title"><a id="parallel_mode.using.prereq_flags"/>Prerequisite Compiler Flags</h3></div></div></div><p> + Any use of parallel functionality requires additional compiler + and runtime support, in particular support for OpenMP. Adding this support is + not difficult: just compile your application with the compiler + flag <code class="literal">-fopenmp</code>. This will link + in <code class="code">libgomp</code>, the GNU + OpenMP <a class="link" href="http://gcc.gnu.org/onlinedocs/libgomp">implementation</a>, + whose presence is mandatory. +</p><p> +In addition, hardware that supports atomic operations and a compiler + capable of producing atomic operations is mandatory: GCC defaults to no + support for atomic operations on some common hardware + architectures. Activating atomic operations may require explicit + compiler flags on some targets (like sparc and x86), such + as <code class="literal">-march=i686</code>, + <code class="literal">-march=native</code> or <code class="literal">-mcpu=v9</code>. See + the GCC manual for more information. +</p></div><div class="section" title="Using Parallel Mode"><div class="titlepage"><div><div><h3 class="title"><a id="parallel_mode.using.parallel_mode"/>Using Parallel Mode</h3></div></div></div><p> + To use the libstdc++ parallel mode, compile your application with + the prerequisite flags as detailed above, and in addition + add <code class="constant">-D_GLIBCXX_PARALLEL</code>. This will convert all + use of the standard (sequential) algorithms to the appropriate parallel + equivalents. Please note that this doesn't necessarily mean that + everything will end up being executed in a parallel manner, but + rather that the heuristics and settings coded into the parallel + versions will be used to determine if all, some, or no algorithms + will be executed using parallel variants. +</p><p>Note that the <code class="constant">_GLIBCXX_PARALLEL</code> define may change the + sizes and behavior of standard class templates such as + <code class="function">std::search</code>, and therefore one can only link code + compiled with parallel mode and code compiled without parallel mode + if no instantiation of a container is passed between the two + translation units. Parallel mode functionality has distinct linkage, + and cannot be confused with normal mode symbols. +</p></div><div class="section" title="Using Specific Parallel Components"><div class="titlepage"><div><div><h3 class="title"><a id="parallel_mode.using.specific"/>Using Specific Parallel Components</h3></div></div></div><p>When it is not feasible to recompile your entire application, or + only specific algorithms need to be parallel-aware, individual + parallel algorithms can be made available explicitly. These + parallel algorithms are functionally equivalent to the standard + drop-in algorithms used in parallel mode, but they are available in + a separate namespace as GNU extensions and may be used in programs + compiled with either release mode or with parallel mode. +</p><p>An example of using a parallel version +of <code class="function">std::sort</code>, but no other parallel algorithms, is: +</p><pre class="programlisting"> +#include <vector> +#include <parallel/algorithm> + +int main() +{ + std::vector<int> v(100); + + // ... + + // Explicitly force a call to parallel sort. + __gnu_parallel::sort(v.begin(), v.end()); + return 0; +} +</pre><p> +Then compile this code with the prerequisite compiler flags +(<code class="literal">-fopenmp</code> and any necessary architecture-specific +flags for atomic operations.) +</p><p> The following table provides the names and headers of all the + parallel algorithms that can be used in a similar manner: +</p><div class="table"><a id="id484380"/><p class="title"><strong>Table 18.1. Parallel Algorithms</strong></p><div class="table-contents"><table summary="Parallel Algorithms" border="1"><colgroup><col style="text-align: left" class="c1"/><col style="text-align: left" class="c2"/><col style="text-align: left" class="c3"/><col style="text-align: left" class="c4"/></colgroup><thead><tr><th style="text-align: left">Algorithm</th><th style="text-align: left">Header</th><th style="text-align: left">Parallel algorithm</th><th style="text-align: left">Parallel header</th></tr></thead><tbody><tr><td style="text-align: left"><code class="function">std::accumulate</code></td><td style="text-align: left"><code class="filename">numeric</code></td><td style="text-align: left"><code class="function">__gnu_parallel::accumulate</code></td><td style="text-align: left"><code class="filename">parallel/numeric</code></td></tr><tr><td style="text-align: left"><code class="function">std::adjacent_difference</code></td><td style="text-align: left"><code class="filename">numeric</code></td><td style="text-align: left"><code class="function">__gnu_parallel::adjacent_difference</code></td><td style="text-align: left"><code class="filename">parallel/numeric</code></td></tr><tr><td style="text-align: left"><code class="function">std::inner_product</code></td><td style="text-align: left"><code class="filename">numeric</code></td><td style="text-align: left"><code class="function">__gnu_parallel::inner_product</code></td><td style="text-align: left"><code class="filename">parallel/numeric</code></td></tr><tr><td style="text-align: left"><code class="function">std::partial_sum</code></td><td style="text-align: left"><code class="filename">numeric</code></td><td style="text-align: left"><code class="function">__gnu_parallel::partial_sum</code></td><td style="text-align: left"><code class="filename">parallel/numeric</code></td></tr><tr><td style="text-align: left"><code class="function">std::adjacent_find</code></td><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="function">__gnu_parallel::adjacent_find</code></td><td style="text-align: left"><code class="filename">parallel/algorithm</code></td></tr><tr><td style="text-align: left"><code class="function">std::count</code></td><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="function">__gnu_parallel::count</code></td><td style="text-align: left"><code class="filename">parallel/algorithm</code></td></tr><tr><td style="text-align: left"><code class="function">std::count_if</code></td><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="function">__gnu_parallel::count_if</code></td><td style="text-align: left"><code class="filename">parallel/algorithm</code></td></tr><tr><td style="text-align: left"><code class="function">std::equal</code></td><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="function">__gnu_parallel::equal</code></td><td style="text-align: left"><code class="filename">parallel/algorithm</code></td></tr><tr><td style="text-align: left"><code class="function">std::find</code></td><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="function">__gnu_parallel::find</code></td><td style="text-align: left"><code class="filename">parallel/algorithm</code></td></tr><tr><td style="text-align: left"><code class="function">std::find_if</code></td><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="function">__gnu_parallel::find_if</code></td><td style="text-align: left"><code class="filename">parallel/algorithm</code></td></tr><tr><td style="text-align: left"><code class="function">std::find_first_of</code></td><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="function">__gnu_parallel::find_first_of</code></td><td style="text-align: left"><code class="filename">parallel/algorithm</code></td></tr><tr><td style="text-align: left"><code class="function">std::for_each</code></td><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="function">__gnu_parallel::for_each</code></td><td style="text-align: left"><code class="filename">parallel/algorithm</code></td></tr><tr><td style="text-align: left"><code class="function">std::generate</code></td><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="function">__gnu_parallel::generate</code></td><td style="text-align: left"><code class="filename">parallel/algorithm</code></td></tr><tr><td style="text-align: left"><code class="function">std::generate_n</code></td><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="function">__gnu_parallel::generate_n</code></td><td style="text-align: left"><code class="filename">parallel/algorithm</code></td></tr><tr><td style="text-align: left"><code class="function">std::lexicographical_compare</code></td><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="function">__gnu_parallel::lexicographical_compare</code></td><td style="text-align: left"><code class="filename">parallel/algorithm</code></td></tr><tr><td style="text-align: left"><code class="function">std::mismatch</code></td><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="function">__gnu_parallel::mismatch</code></td><td style="text-align: left"><code class="filename">parallel/algorithm</code></td></tr><tr><td style="text-align: left"><code class="function">std::search</code></td><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="function">__gnu_parallel::search</code></td><td style="text-align: left"><code class="filename">parallel/algorithm</code></td></tr><tr><td style="text-align: left"><code class="function">std::search_n</code></td><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="function">__gnu_parallel::search_n</code></td><td style="text-align: left"><code class="filename">parallel/algorithm</code></td></tr><tr><td style="text-align: left"><code class="function">std::transform</code></td><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="function">__gnu_parallel::transform</code></td><td style="text-align: left"><code class="filename">parallel/algorithm</code></td></tr><tr><td style="text-align: left"><code class="function">std::replace</code></td><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="function">__gnu_parallel::replace</code></td><td style="text-align: left"><code class="filename">parallel/algorithm</code></td></tr><tr><td style="text-align: left"><code class="function">std::replace_if</code></td><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="function">__gnu_parallel::replace_if</code></td><td style="text-align: left"><code class="filename">parallel/algorithm</code></td></tr><tr><td style="text-align: left"><code class="function">std::max_element</code></td><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="function">__gnu_parallel::max_element</code></td><td style="text-align: left"><code class="filename">parallel/algorithm</code></td></tr><tr><td style="text-align: left"><code class="function">std::merge</code></td><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="function">__gnu_parallel::merge</code></td><td style="text-align: left"><code class="filename">parallel/algorithm</code></td></tr><tr><td style="text-align: left"><code class="function">std::min_element</code></td><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="function">__gnu_parallel::min_element</code></td><td style="text-align: left"><code class="filename">parallel/algorithm</code></td></tr><tr><td style="text-align: left"><code class="function">std::nth_element</code></td><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="function">__gnu_parallel::nth_element</code></td><td style="text-align: left"><code class="filename">parallel/algorithm</code></td></tr><tr><td style="text-align: left"><code class="function">std::partial_sort</code></td><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="function">__gnu_parallel::partial_sort</code></td><td style="text-align: left"><code class="filename">parallel/algorithm</code></td></tr><tr><td style="text-align: left"><code class="function">std::partition</code></td><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="function">__gnu_parallel::partition</code></td><td style="text-align: left"><code class="filename">parallel/algorithm</code></td></tr><tr><td style="text-align: left"><code class="function">std::random_shuffle</code></td><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="function">__gnu_parallel::random_shuffle</code></td><td style="text-align: left"><code class="filename">parallel/algorithm</code></td></tr><tr><td style="text-align: left"><code class="function">std::set_union</code></td><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="function">__gnu_parallel::set_union</code></td><td style="text-align: left"><code class="filename">parallel/algorithm</code></td></tr><tr><td style="text-align: left"><code class="function">std::set_intersection</code></td><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="function">__gnu_parallel::set_intersection</code></td><td style="text-align: left"><code class="filename">parallel/algorithm</code></td></tr><tr><td style="text-align: left"><code class="function">std::set_symmetric_difference</code></td><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="function">__gnu_parallel::set_symmetric_difference</code></td><td style="text-align: left"><code class="filename">parallel/algorithm</code></td></tr><tr><td style="text-align: left"><code class="function">std::set_difference</code></td><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="function">__gnu_parallel::set_difference</code></td><td style="text-align: left"><code class="filename">parallel/algorithm</code></td></tr><tr><td style="text-align: left"><code class="function">std::sort</code></td><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="function">__gnu_parallel::sort</code></td><td style="text-align: left"><code class="filename">parallel/algorithm</code></td></tr><tr><td style="text-align: left"><code class="function">std::stable_sort</code></td><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="function">__gnu_parallel::stable_sort</code></td><td style="text-align: left"><code class="filename">parallel/algorithm</code></td></tr><tr><td style="text-align: left"><code class="function">std::unique_copy</code></td><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="function">__gnu_parallel::unique_copy</code></td><td style="text-align: left"><code class="filename">parallel/algorithm</code></td></tr></tbody></table></div></div><br class="table-break"/></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="bk01pt03ch18s02.html">Prev</a> </td><td align="center"><a accesskey="u" href="parallel_mode.html">Up</a></td><td align="right"> <a accesskey="n" href="bk01pt03ch18s04.html">Next</a></td></tr><tr><td align="left" valign="top">Semantics </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Design</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch18s04.html b/libstdc++-v3/doc/html/manual/bk01pt03ch18s04.html new file mode 100644 index 000000000..91c951d38 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch18s04.html @@ -0,0 +1,213 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Design</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" C++ , library , parallel "/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="parallel_mode.html" title="Chapter 18. Parallel Mode"/><link rel="prev" href="bk01pt03ch18s03.html" title="Using"/><link rel="next" href="bk01pt03ch18s05.html" title="Testing"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Design</th></tr><tr><td align="left"><a accesskey="p" href="bk01pt03ch18s03.html">Prev</a> </td><th width="60%" align="center">Chapter 18. Parallel Mode</th><td align="right"> <a accesskey="n" href="bk01pt03ch18s05.html">Next</a></td></tr></table><hr/></div><div class="section" title="Design"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.parallel_mode.design"/>Design</h2></div></div></div><p> + </p><div class="section" title="Interface Basics"><div class="titlepage"><div><div><h3 class="title"><a id="parallel_mode.design.intro"/>Interface Basics</h3></div></div></div><p> +All parallel algorithms are intended to have signatures that are +equivalent to the ISO C++ algorithms replaced. For instance, the +<code class="function">std::adjacent_find</code> function is declared as: +</p><pre class="programlisting"> +namespace std +{ + template<typename _FIter> + _FIter + adjacent_find(_FIter, _FIter); +} +</pre><p> +Which means that there should be something equivalent for the parallel +version. Indeed, this is the case: +</p><pre class="programlisting"> +namespace std +{ + namespace __parallel + { + template<typename _FIter> + _FIter + adjacent_find(_FIter, _FIter); + + ... + } +} +</pre><p>But.... why the ellipses? +</p><p> The ellipses in the example above represent additional overloads +required for the parallel version of the function. These additional +overloads are used to dispatch calls from the ISO C++ function +signature to the appropriate parallel function (or sequential +function, if no parallel functions are deemed worthy), based on either +compile-time or run-time conditions. +</p><p> The available signature options are specific for the different +algorithms/algorithm classes.</p><p> The general view of overloads for the parallel algorithms look like this: +</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>ISO C++ signature</p></li><li class="listitem"><p>ISO C++ signature + sequential_tag argument</p></li><li class="listitem"><p>ISO C++ signature + algorithm-specific tag type + (several signatures)</p></li></ul></div><p> Please note that the implementation may use additional functions +(designated with the <code class="code">_switch</code> suffix) to dispatch from the +ISO C++ signature to the correct parallel version. Also, some of the +algorithms do not have support for run-time conditions, so the last +overload is therefore missing. +</p></div><div class="section" title="Configuration and Tuning"><div class="titlepage"><div><div><h3 class="title"><a id="parallel_mode.design.tuning"/>Configuration and Tuning</h3></div></div></div><div class="section" title="Setting up the OpenMP Environment"><div class="titlepage"><div><div><h4 class="title"><a id="parallel_mode.design.tuning.omp"/>Setting up the OpenMP Environment</h4></div></div></div><p> +Several aspects of the overall runtime environment can be manipulated +by standard OpenMP function calls. +</p><p> +To specify the number of threads to be used for the algorithms globally, +use the function <code class="function">omp_set_num_threads</code>. An example: +</p><pre class="programlisting"> +#include <stdlib.h> +#include <omp.h> + +int main() +{ + // Explicitly set number of threads. + const int threads_wanted = 20; + omp_set_dynamic(false); + omp_set_num_threads(threads_wanted); + + // Call parallel mode algorithms. + + return 0; +} +</pre><p> + Some algorithms allow the number of threads being set for a particular call, + by augmenting the algorithm variant. + See the next section for further information. +</p><p> +Other parts of the runtime environment able to be manipulated include +nested parallelism (<code class="function">omp_set_nested</code>), schedule kind +(<code class="function">omp_set_schedule</code>), and others. See the OpenMP +documentation for more information. +</p></div><div class="section" title="Compile Time Switches"><div class="titlepage"><div><div><h4 class="title"><a id="parallel_mode.design.tuning.compile"/>Compile Time Switches</h4></div></div></div><p> +To force an algorithm to execute sequentially, even though parallelism +is switched on in general via the macro <code class="constant">_GLIBCXX_PARALLEL</code>, +add <code class="classname">__gnu_parallel::sequential_tag()</code> to the end +of the algorithm's argument list. +</p><p> +Like so: +</p><pre class="programlisting"> +std::sort(v.begin(), v.end(), __gnu_parallel::sequential_tag()); +</pre><p> +Some parallel algorithm variants can be excluded from compilation by +preprocessor defines. See the doxygen documentation on +<code class="code">compiletime_settings.h</code> and <code class="code">features.h</code> for details. +</p><p> +For some algorithms, the desired variant can be chosen at compile-time by +appending a tag object. The available options are specific to the particular +algorithm (class). +</p><p> +For the "embarrassingly parallel" algorithms, there is only one "tag object +type", the enum _Parallelism. +It takes one of the following values, +<code class="code">__gnu_parallel::parallel_tag</code>, +<code class="code">__gnu_parallel::balanced_tag</code>, +<code class="code">__gnu_parallel::unbalanced_tag</code>, +<code class="code">__gnu_parallel::omp_loop_tag</code>, +<code class="code">__gnu_parallel::omp_loop_static_tag</code>. +This means that the actual parallelization strategy is chosen at run-time. +(Choosing the variants at compile-time will come soon.) +</p><p> +For the following algorithms in general, we have +<code class="code">__gnu_parallel::parallel_tag</code> and +<code class="code">__gnu_parallel::default_parallel_tag</code>, in addition to +<code class="code">__gnu_parallel::sequential_tag</code>. +<code class="code">__gnu_parallel::default_parallel_tag</code> chooses the default +algorithm at compiletime, as does omitting the tag. +<code class="code">__gnu_parallel::parallel_tag</code> postpones the decision to runtime +(see next section). +For all tags, the number of threads desired for this call can optionally be +passed to the respective tag's constructor. +</p><p> +The <code class="code">multiway_merge</code> algorithm comes with the additional choices, +<code class="code">__gnu_parallel::exact_tag</code> and +<code class="code">__gnu_parallel::sampling_tag</code>. +Exact and sampling are the two available splitting strategies. +</p><p> +For the <code class="code">sort</code> and <code class="code">stable_sort</code> algorithms, there are +several additional choices, namely +<code class="code">__gnu_parallel::multiway_mergesort_tag</code>, +<code class="code">__gnu_parallel::multiway_mergesort_exact_tag</code>, +<code class="code">__gnu_parallel::multiway_mergesort_sampling_tag</code>, +<code class="code">__gnu_parallel::quicksort_tag</code>, and +<code class="code">__gnu_parallel::balanced_quicksort_tag</code>. +Multiway mergesort comes with the two splitting strategies for multi-way +merging. The quicksort options cannot be used for <code class="code">stable_sort</code>. +</p></div><div class="section" title="Run Time Settings and Defaults"><div class="titlepage"><div><div><h4 class="title"><a id="parallel_mode.design.tuning.settings"/>Run Time Settings and Defaults</h4></div></div></div><p> +The default parallelization strategy, the choice of specific algorithm +strategy, the minimum threshold limits for individual parallel +algorithms, and aspects of the underlying hardware can be specified as +desired via manipulation +of <code class="classname">__gnu_parallel::_Settings</code> member data. +</p><p> +First off, the choice of parallelization strategy: serial, parallel, +or heuristically deduced. This corresponds +to <code class="code">__gnu_parallel::_Settings::algorithm_strategy</code> and is a +value of enum <span class="type">__gnu_parallel::_AlgorithmStrategy</span> +type. Choices +include: <span class="type">heuristic</span>, <span class="type">force_sequential</span>, +and <span class="type">force_parallel</span>. The default is <span class="type">heuristic</span>. +</p><p> +Next, the sub-choices for algorithm variant, if not fixed at compile-time. +Specific algorithms like <code class="function">find</code> or <code class="function">sort</code> +can be implemented in multiple ways: when this is the case, +a <code class="classname">__gnu_parallel::_Settings</code> member exists to +pick the default strategy. For +example, <code class="code">__gnu_parallel::_Settings::sort_algorithm</code> can +have any values of +enum <span class="type">__gnu_parallel::_SortAlgorithm</span>: <span class="type">MWMS</span>, <span class="type">QS</span>, +or <span class="type">QS_BALANCED</span>. +</p><p> +Likewise for setting the minimal threshold for algorithm +parallelization. Parallelism always incurs some overhead. Thus, it is +not helpful to parallelize operations on very small sets of +data. Because of this, measures are taken to avoid parallelizing below +a certain, pre-determined threshold. For each algorithm, a minimum +problem size is encoded as a variable in the +active <code class="classname">__gnu_parallel::_Settings</code> object. This +threshold variable follows the following naming scheme: +<code class="code">__gnu_parallel::_Settings::[algorithm]_minimal_n</code>. So, +for <code class="function">fill</code>, the threshold variable +is <code class="code">__gnu_parallel::_Settings::fill_minimal_n</code>, +</p><p> +Finally, hardware details like L1/L2 cache size can be hardwired +via <code class="code">__gnu_parallel::_Settings::L1_cache_size</code> and friends. +</p><p> +</p><p> +All these configuration variables can be changed by the user, if +desired. +There exists one global instance of the class <code class="classname">_Settings</code>, +i. e. it is a singleton. It can be read and written by calling +<code class="code">__gnu_parallel::_Settings::get</code> and +<code class="code">__gnu_parallel::_Settings::set</code>, respectively. +Please note that the first call return a const object, so direct manipulation +is forbidden. +See <a class="link" href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a01005.html"> + <code class="filename">settings.h</code></a> +for complete details. +</p><p> +A small example of tuning the default: +</p><pre class="programlisting"> +#include <parallel/algorithm> +#include <parallel/settings.h> + +int main() +{ + __gnu_parallel::_Settings s; + s.algorithm_strategy = __gnu_parallel::force_parallel; + __gnu_parallel::_Settings::set(s); + + // Do work... all algorithms will be parallelized, always. + + return 0; +} +</pre></div></div><div class="section" title="Implementation Namespaces"><div class="titlepage"><div><div><h3 class="title"><a id="parallel_mode.design.impl"/>Implementation Namespaces</h3></div></div></div><p> One namespace contain versions of code that are always +explicitly sequential: +<code class="code">__gnu_serial</code>. +</p><p> Two namespaces contain the parallel mode: +<code class="code">std::__parallel</code> and <code class="code">__gnu_parallel</code>. +</p><p> Parallel implementations of standard components, including +template helpers to select parallelism, are defined in <code class="code">namespace +std::__parallel</code>. For instance, <code class="function">std::transform</code> from <code class="filename">algorithm</code> has a parallel counterpart in +<code class="function">std::__parallel::transform</code> from <code class="filename">parallel/algorithm</code>. In addition, these parallel +implementations are injected into <code class="code">namespace +__gnu_parallel</code> with using declarations. +</p><p> Support and general infrastructure is in <code class="code">namespace +__gnu_parallel</code>. +</p><p> More information, and an organized index of types and functions +related to the parallel mode on a per-namespace basis, can be found in +the generated source documentation. +</p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="bk01pt03ch18s03.html">Prev</a> </td><td align="center"><a accesskey="u" href="parallel_mode.html">Up</a></td><td align="right"> <a accesskey="n" href="bk01pt03ch18s05.html">Next</a></td></tr><tr><td align="left" valign="top">Using </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Testing</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch18s05.html b/libstdc++-v3/doc/html/manual/bk01pt03ch18s05.html new file mode 100644 index 000000000..f00a4a281 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch18s05.html @@ -0,0 +1,26 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Testing</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" C++ , library , parallel "/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="parallel_mode.html" title="Chapter 18. Parallel Mode"/><link rel="prev" href="bk01pt03ch18s04.html" title="Design"/><link rel="next" href="profile_mode.html" title="Chapter 19. Profile Mode"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Testing</th></tr><tr><td align="left"><a accesskey="p" href="bk01pt03ch18s04.html">Prev</a> </td><th width="60%" align="center">Chapter 18. Parallel Mode</th><td align="right"> <a accesskey="n" href="profile_mode.html">Next</a></td></tr></table><hr/></div><div class="section" title="Testing"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.parallel_mode.test"/>Testing</h2></div></div></div><p> + Both the normal conformance and regression tests and the + supplemental performance tests work. + </p><p> + To run the conformance and regression tests with the parallel mode + active, + </p><pre class="screen"> + <strong class="userinput"><code>make check-parallel</code></strong> + </pre><p> + The log and summary files for conformance testing are in the + <code class="filename">testsuite/parallel</code> directory. + </p><p> + To run the performance tests with the parallel mode active, + </p><pre class="screen"> + <strong class="userinput"><code>make check-performance-parallel</code></strong> + </pre><p> + The result file for performance testing are in the + <code class="filename">testsuite</code> directory, in the file + <code class="filename">libstdc++_performance.sum</code>. In addition, the + policy-based containers have their own visualizations, which have + additional software dependencies than the usual bare-boned text + file, and can be generated by using the <code class="code">make + doc-performance</code> rule in the testsuite's Makefile. +</p></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="bk01pt03ch18s04.html">Prev</a> </td><td align="center"><a accesskey="u" href="parallel_mode.html">Up</a></td><td align="right"> <a accesskey="n" href="profile_mode.html">Next</a></td></tr><tr><td align="left" valign="top">Design </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Chapter 19. Profile Mode</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch19s02.html b/libstdc++-v3/doc/html/manual/bk01pt03ch19s02.html new file mode 100644 index 000000000..ce915ddb5 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch19s02.html @@ -0,0 +1,122 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Design</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" C++ , library , profile "/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="profile_mode.html" title="Chapter 19. Profile Mode"/><link rel="prev" href="profile_mode.html" title="Chapter 19. Profile Mode"/><link rel="next" href="bk01pt03ch19s03.html" title="Extensions for Custom Containers"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Design</th></tr><tr><td align="left"><a accesskey="p" href="profile_mode.html">Prev</a> </td><th width="60%" align="center">Chapter 19. Profile Mode</th><td align="right"> <a accesskey="n" href="bk01pt03ch19s03.html">Next</a></td></tr></table><hr/></div><div class="section" title="Design"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.profile_mode.design"/>Design</h2></div></div></div><p> +</p><div class="table"><a id="id486504"/><p class="title"><strong>Table 19.1. Profile Code Location</strong></p><div class="table-contents"><table summary="Profile Code Location" border="1"><colgroup><col style="text-align: left" class="c1"/><col style="text-align: left" class="c2"/></colgroup><thead><tr><th style="text-align: left">Code Location</th><th style="text-align: left">Use</th></tr></thead><tbody><tr><td style="text-align: left"><code class="code">libstdc++-v3/include/std/*</code></td><td style="text-align: left">Preprocessor code to redirect to profile extension headers.</td></tr><tr><td style="text-align: left"><code class="code">libstdc++-v3/include/profile/*</code></td><td style="text-align: left">Profile extension public headers (map, vector, ...).</td></tr><tr><td style="text-align: left"><code class="code">libstdc++-v3/include/profile/impl/*</code></td><td style="text-align: left">Profile extension internals. Implementation files are + only included from <code class="code">impl/profiler.h</code>, which is the only + file included from the public headers.</td></tr></tbody></table></div></div><br class="table-break"/><p> +</p><div class="section" title="Wrapper Model"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.design.wrapper"/>Wrapper Model</h3></div></div></div><p> + In order to get our instrumented library version included instead of the + release one, + we use the same wrapper model as the debug mode. + We subclass entities from the release version. Wherever + <code class="code">_GLIBCXX_PROFILE</code> is defined, the release namespace is + <code class="code">std::__norm</code>, whereas the profile namespace is + <code class="code">std::__profile</code>. Using plain <code class="code">std</code> translates + into <code class="code">std::__profile</code>. + </p><p> + Whenever possible, we try to wrap at the public interface level, e.g., + in <code class="code">unordered_set</code> rather than in <code class="code">hashtable</code>, + in order not to depend on implementation. + </p><p> + Mixing object files built with and without the profile mode must + not affect the program execution. However, there are no guarantees to + the accuracy of diagnostics when using even a single object not built with + <code class="code">-D_GLIBCXX_PROFILE</code>. + Currently, mixing the profile mode with debug and parallel extensions is + not allowed. Mixing them at compile time will result in preprocessor errors. + Mixing them at link time is undefined. + </p></div><div class="section" title="Instrumentation"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.design.instrumentation"/>Instrumentation</h3></div></div></div><p> + Instead of instrumenting every public entry and exit point, + we chose to add instrumentation on demand, as needed + by individual diagnostics. + The main reason is that some diagnostics require us to extract bits of + internal state that are particular only to that diagnostic. + We plan to formalize this later, after we learn more about the requirements + of several diagnostics. + </p><p> + All the instrumentation points can be switched on and off using + <code class="code">-D[_NO]_GLIBCXX_PROFILE_<diagnostic></code> options. + With all the instrumentation calls off, there should be negligible + overhead over the release version. This property is needed to support + diagnostics based on timing of internal operations. For such diagnostics, + we anticipate turning most of the instrumentation off in order to prevent + profiling overhead from polluting time measurements, and thus diagnostics. + </p><p> + All the instrumentation on/off compile time switches live in + <code class="code">include/profile/profiler.h</code>. + </p></div><div class="section" title="Run Time Behavior"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.design.rtlib"/>Run Time Behavior</h3></div></div></div><p> + For practical reasons, the instrumentation library processes the trace + partially + rather than dumping it to disk in raw form. Each event is processed when + it occurs. It is usually attached a cost and it is aggregated into + the database of a specific diagnostic class. The cost model + is based largely on the standard performance guarantees, but in some + cases we use knowledge about GCC's standard library implementation. + </p><p> + Information is indexed by (1) call stack and (2) instance id or address + to be able to understand and summarize precise creation-use-destruction + dynamic chains. Although the analysis is sensitive to dynamic instances, + the reports are only sensitive to call context. Whenever a dynamic instance + is destroyed, we accumulate its effect to the corresponding entry for the + call stack of its constructor location. + </p><p> + For details, see + <a class="link" href="http://dx.doi.org/10.1109/CGO.2009.36">paper presented at + CGO 2009</a>. + </p></div><div class="section" title="Analysis and Diagnostics"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.design.analysis"/>Analysis and Diagnostics</h3></div></div></div><p> + Final analysis takes place offline, and it is based entirely on the + generated trace and debugging info in the application binary. + See section Diagnostics for a list of analysis types that we plan to support. + </p><p> + The input to the analysis is a table indexed by profile type and call stack. + The data type for each entry depends on the profile type. + </p></div><div class="section" title="Cost Model"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.design.cost-model"/>Cost Model</h3></div></div></div><p> + While it is likely that cost models become complex as we get into + more sophisticated analysis, we will try to follow a simple set of rules + at the beginning. + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><span class="emphasis"><em>Relative benefit estimation:</em></span> + The idea is to estimate or measure the cost of all operations + in the original scenario versus the scenario we advise to switch to. + For instance, when advising to change a vector to a list, an occurrence + of the <code class="code">insert</code> method will generally count as a benefit. + Its magnitude depends on (1) the number of elements that get shifted + and (2) whether it triggers a reallocation. + </p></li><li class="listitem"><p><span class="emphasis"><em>Synthetic measurements:</em></span> + We will measure the relative difference between similar operations on + different containers. We plan to write a battery of small tests that + compare the times of the executions of similar methods on different + containers. The idea is to run these tests on the target machine. + If this training phase is very quick, we may decide to perform it at + library initialization time. The results can be cached on disk and reused + across runs. + </p></li><li class="listitem"><p><span class="emphasis"><em>Timers:</em></span> + We plan to use timers for operations of larger granularity, such as sort. + For instance, we can switch between different sort methods on the fly + and report the one that performs best for each call context. + </p></li><li class="listitem"><p><span class="emphasis"><em>Show stoppers:</em></span> + We may decide that the presence of an operation nullifies the advice. + For instance, when considering switching from <code class="code">set</code> to + <code class="code">unordered_set</code>, if we detect use of operator <code class="code">++</code>, + we will simply not issue the advice, since this could signal that the use + care require a sorted container.</p></li></ul></div></div><div class="section" title="Reports"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.design.reports"/>Reports</h3></div></div></div><p> +There are two types of reports. First, if we recognize a pattern for which +we have a substitute that is likely to give better performance, we print +the advice and estimated performance gain. The advice is usually associated +to a code position and possibly a call stack. + </p><p> +Second, we report performance characteristics for which we do not have +a clear solution for improvement. For instance, we can point to the user +the top 10 <code class="code">multimap</code> locations +which have the worst data locality in actual traversals. +Although this does not offer a solution, +it helps the user focus on the key problems and ignore the uninteresting ones. + </p></div><div class="section" title="Testing"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.design.testing"/>Testing</h3></div></div></div><p> + First, we want to make sure we preserve the behavior of the release mode. + You can just type <code class="code">"make check-profile"</code>, which + builds and runs the whole test suite in profile mode. + </p><p> + Second, we want to test the correctness of each diagnostic. + We created a <code class="code">profile</code> directory in the test suite. + Each diagnostic must come with at least two tests, one for false positives + and one for false negatives. + </p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="profile_mode.html">Prev</a> </td><td align="center"><a accesskey="u" href="profile_mode.html">Up</a></td><td align="right"> <a accesskey="n" href="bk01pt03ch19s03.html">Next</a></td></tr><tr><td align="left" valign="top">Chapter 19. Profile Mode </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Extensions for Custom Containers</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch19s03.html b/libstdc++-v3/doc/html/manual/bk01pt03ch19s03.html new file mode 100644 index 000000000..37d1ed8e4 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch19s03.html @@ -0,0 +1,10 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Extensions for Custom Containers</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" C++ , library , profile "/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="profile_mode.html" title="Chapter 19. Profile Mode"/><link rel="prev" href="bk01pt03ch19s02.html" title="Design"/><link rel="next" href="bk01pt03ch19s04.html" title="Empirical Cost Model"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Extensions for Custom Containers</th></tr><tr><td align="left"><a accesskey="p" href="bk01pt03ch19s02.html">Prev</a> </td><th width="60%" align="center">Chapter 19. Profile Mode</th><td align="right"> <a accesskey="n" href="bk01pt03ch19s04.html">Next</a></td></tr></table><hr/></div><div class="section" title="Extensions for Custom Containers"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.profile_mode.api"/>Extensions for Custom Containers</h2></div></div></div><p> + Many large projects use their own data structures instead of the ones in the + standard library. If these data structures are similar in functionality + to the standard library, they can be instrumented with the same hooks + that are used to instrument the standard library. + The instrumentation API is exposed in file + <code class="code">profiler.h</code> (look for "Instrumentation hooks"). + </p></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="bk01pt03ch19s02.html">Prev</a> </td><td align="center"><a accesskey="u" href="profile_mode.html">Up</a></td><td align="right"> <a accesskey="n" href="bk01pt03ch19s04.html">Next</a></td></tr><tr><td align="left" valign="top">Design </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Empirical Cost Model</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch19s04.html b/libstdc++-v3/doc/html/manual/bk01pt03ch19s04.html new file mode 100644 index 000000000..8fc162b7c --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch19s04.html @@ -0,0 +1,18 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Empirical Cost Model</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" C++ , library , profile "/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="profile_mode.html" title="Chapter 19. Profile Mode"/><link rel="prev" href="bk01pt03ch19s03.html" title="Extensions for Custom Containers"/><link rel="next" href="bk01pt03ch19s05.html" title="Implementation Issues"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Empirical Cost Model</th></tr><tr><td align="left"><a accesskey="p" href="bk01pt03ch19s03.html">Prev</a> </td><th width="60%" align="center">Chapter 19. Profile Mode</th><td align="right"> <a accesskey="n" href="bk01pt03ch19s05.html">Next</a></td></tr></table><hr/></div><div class="section" title="Empirical Cost Model"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.profile_mode.cost_model"/>Empirical Cost Model</h2></div></div></div><p> + Currently, the cost model uses formulas with predefined relative weights + for alternative containers or container implementations. For instance, + iterating through a vector is X times faster than iterating through a list. + </p><p> + (Under development.) + We are working on customizing this to a particular machine by providing + an automated way to compute the actual relative weights for operations + on the given machine. + </p><p> + (Under development.) + We plan to provide a performance parameter database format that can be + filled in either by hand or by an automated training mechanism. + The analysis module will then use this database instead of the built in. + generic parameters. + </p></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="bk01pt03ch19s03.html">Prev</a> </td><td align="center"><a accesskey="u" href="profile_mode.html">Up</a></td><td align="right"> <a accesskey="n" href="bk01pt03ch19s05.html">Next</a></td></tr><tr><td align="left" valign="top">Extensions for Custom Containers </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Implementation Issues</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch19s05.html b/libstdc++-v3/doc/html/manual/bk01pt03ch19s05.html new file mode 100644 index 000000000..2d072f0b4 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch19s05.html @@ -0,0 +1,51 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Implementation Issues</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" C++ , library , profile "/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="profile_mode.html" title="Chapter 19. Profile Mode"/><link rel="prev" href="bk01pt03ch19s04.html" title="Empirical Cost Model"/><link rel="next" href="bk01pt03ch19s06.html" title="Developer Information"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Implementation Issues</th></tr><tr><td align="left"><a accesskey="p" href="bk01pt03ch19s04.html">Prev</a> </td><th width="60%" align="center">Chapter 19. Profile Mode</th><td align="right"> <a accesskey="n" href="bk01pt03ch19s06.html">Next</a></td></tr></table><hr/></div><div class="section" title="Implementation Issues"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.profile_mode.implementation"/>Implementation Issues</h2></div></div></div><div class="section" title="Stack Traces"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.implementation.stack"/>Stack Traces</h3></div></div></div><p> + Accurate stack traces are needed during profiling since we group events by + call context and dynamic instance. Without accurate traces, diagnostics + may be hard to interpret. For instance, when giving advice to the user + it is imperative to reference application code, not library code. + </p><p> + Currently we are using the libc <code class="code">backtrace</code> routine to get + stack traces. + <code class="code">_GLIBCXX_PROFILE_STACK_DEPTH</code> can be set + to 0 if you are willing to give up call context information, or to a small + positive value to reduce run time overhead. + </p></div><div class="section" title="Symbolization of Instruction Addresses"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.implementation.symbols"/>Symbolization of Instruction Addresses</h3></div></div></div><p> + The profiling and analysis phases use only instruction addresses. + An external utility such as addr2line is needed to postprocess the result. + We do not plan to add symbolization support in the profile extension. + This would require access to symbol tables, debug information tables, + external programs or libraries and other system dependent information. + </p></div><div class="section" title="Concurrency"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.implementation.concurrency"/>Concurrency</h3></div></div></div><p> + Our current model is simplistic, but precise. + We cannot afford to approximate because some of our diagnostics require + precise matching of operations to container instance and call context. + During profiling, we keep a single information table per diagnostic. + There is a single lock per information table. + </p></div><div class="section" title="Using the Standard Library in the Instrumentation Implementation"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.implementation.stdlib-in-proflib"/>Using the Standard Library in the Instrumentation Implementation</h3></div></div></div><p> + As much as we would like to avoid uses of libstdc++ within our + instrumentation library, containers such as unordered_map are very + appealing. We plan to use them as long as they are named properly + to avoid ambiguity. + </p></div><div class="section" title="Malloc Hooks"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.implementation.malloc-hooks"/>Malloc Hooks</h3></div></div></div><p> + User applications/libraries can provide malloc hooks. + When the implementation of the malloc hooks uses stdlibc++, there can + be an infinite cycle between the profile mode instrumentation and the + malloc hook code. + </p><p> + We protect against reentrance to the profile mode instrumentation code, + which should avoid this problem in most cases. + The protection mechanism is thread safe and exception safe. + This mechanism does not prevent reentrance to the malloc hook itself, + which could still result in deadlock, if, for instance, the malloc hook + uses non-recursive locks. + XXX: A definitive solution to this problem would be for the profile extension + to use a custom allocator internally, and perhaps not to use libstdc++. + </p></div><div class="section" title="Construction and Destruction of Global Objects"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.implementation.construction-destruction"/>Construction and Destruction of Global Objects</h3></div></div></div><p> + The profiling library state is initialized at the first call to a profiling + method. This allows us to record the construction of all global objects. + However, we cannot do the same at destruction time. The trace is written + by a function registered by <code class="code">atexit</code>, thus invoked by + <code class="code">exit</code>. + </p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="bk01pt03ch19s04.html">Prev</a> </td><td align="center"><a accesskey="u" href="profile_mode.html">Up</a></td><td align="right"> <a accesskey="n" href="bk01pt03ch19s06.html">Next</a></td></tr><tr><td align="left" valign="top">Empirical Cost Model </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Developer Information</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch19s06.html b/libstdc++-v3/doc/html/manual/bk01pt03ch19s06.html new file mode 100644 index 000000000..ddcc7f570 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch19s06.html @@ -0,0 +1,68 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Developer Information</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" C++ , library , profile "/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="profile_mode.html" title="Chapter 19. Profile Mode"/><link rel="prev" href="bk01pt03ch19s05.html" title="Implementation Issues"/><link rel="next" href="bk01pt03ch19s07.html" title="Diagnostics"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Developer Information</th></tr><tr><td align="left"><a accesskey="p" href="bk01pt03ch19s05.html">Prev</a> </td><th width="60%" align="center">Chapter 19. Profile Mode</th><td align="right"> <a accesskey="n" href="bk01pt03ch19s07.html">Next</a></td></tr></table><hr/></div><div class="section" title="Developer Information"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.profile_mode.developer"/>Developer Information</h2></div></div></div><div class="section" title="Big Picture"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.developer.bigpic"/>Big Picture</h3></div></div></div><p>The profile mode headers are included with + <code class="code">-D_GLIBCXX_PROFILE</code> through preprocessor directives in + <code class="code">include/std/*</code>. + </p><p>Instrumented implementations are provided in + <code class="code">include/profile/*</code>. All instrumentation hooks are macros + defined in <code class="code">include/profile/profiler.h</code>. + </p><p>All the implementation of the instrumentation hooks is in + <code class="code">include/profile/impl/*</code>. Although all the code gets included, + thus is publicly visible, only a small number of functions are called from + outside this directory. All calls to hook implementations must be + done through macros defined in <code class="code">profiler.h</code>. The macro + must ensure (1) that the call is guarded against reentrance and + (2) that the call can be turned off at compile time using a + <code class="code">-D_GLIBCXX_PROFILE_...</code> compiler option. + </p></div><div class="section" title="How To Add A Diagnostic"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.developer.howto"/>How To Add A Diagnostic</h3></div></div></div><p>Let's say the diagnostic name is "magic". + </p><p>If you need to instrument a header not already under + <code class="code">include/profile/*</code>, first edit the corresponding header + under <code class="code">include/std/</code> and add a preprocessor directive such + as the one in <code class="code">include/std/vector</code>: +</p><pre class="programlisting"> +#ifdef _GLIBCXX_PROFILE +# include <profile/vector> +#endif +</pre><p> + </p><p>If the file you need to instrument is not yet under + <code class="code">include/profile/</code>, make a copy of the one in + <code class="code">include/debug</code>, or the main implementation. + You'll need to include the main implementation and inherit the classes + you want to instrument. Then define the methods you want to instrument, + define the instrumentation hooks and add calls to them. + Look at <code class="code">include/profile/vector</code> for an example. + </p><p>Add macros for the instrumentation hooks in + <code class="code">include/profile/impl/profiler.h</code>. + Hook names must start with <code class="code">__profcxx_</code>. + Make sure they transform + in no code with <code class="code">-D_NO_GLBICXX_PROFILE_MAGIC</code>. + Make sure all calls to any method in namespace <code class="code">__gnu_profile</code> + is protected against reentrance using macro + <code class="code">_GLIBCXX_PROFILE_REENTRANCE_GUARD</code>. + All names of methods in namespace <code class="code">__gnu_profile</code> called from + <code class="code">profiler.h</code> must start with <code class="code">__trace_magic_</code>. + </p><p>Add the implementation of the diagnostic. + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + Create new file <code class="code">include/profile/impl/profiler_magic.h</code>. + </p></li><li class="listitem"><p> + Define class <code class="code">__magic_info: public __object_info_base</code>. + This is the representation of a line in the object table. + The <code class="code">__merge</code> method is used to aggregate information + across all dynamic instances created at the same call context. + The <code class="code">__magnitude</code> must return the estimation of the benefit + as a number of small operations, e.g., number of words copied. + The <code class="code">__write</code> method is used to produce the raw trace. + The <code class="code">__advice</code> method is used to produce the advice string. + </p></li><li class="listitem"><p> + Define class <code class="code">__magic_stack_info: public __magic_info</code>. + This defines the content of a line in the stack table. + </p></li><li class="listitem"><p> + Define class <code class="code">__trace_magic: public __trace_base<__magic_info, + __magic_stack_info></code>. + It defines the content of the trace associated with this diagnostic. + </p></li></ul></div><p> + </p><p>Add initialization and reporting calls in + <code class="code">include/profile/impl/profiler_trace.h</code>. Use + <code class="code">__trace_vector_to_list</code> as an example. + </p><p>Add documentation in file <code class="code">doc/xml/manual/profile_mode.xml</code>. + </p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="bk01pt03ch19s05.html">Prev</a> </td><td align="center"><a accesskey="u" href="profile_mode.html">Up</a></td><td align="right"> <a accesskey="n" href="bk01pt03ch19s07.html">Next</a></td></tr><tr><td align="left" valign="top">Implementation Issues </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Diagnostics</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch19s07.html b/libstdc++-v3/doc/html/manual/bk01pt03ch19s07.html new file mode 100644 index 000000000..8c134e75f --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch19s07.html @@ -0,0 +1,558 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Diagnostics</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" C++ , library , profile "/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="profile_mode.html" title="Chapter 19. Profile Mode"/><link rel="prev" href="bk01pt03ch19s06.html" title="Developer Information"/><link rel="next" href="ext_allocators.html" title="Chapter 20. Allocators"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Diagnostics</th></tr><tr><td align="left"><a accesskey="p" href="bk01pt03ch19s06.html">Prev</a> </td><th width="60%" align="center">Chapter 19. Profile Mode</th><td align="right"> <a accesskey="n" href="ext_allocators.html">Next</a></td></tr></table><hr/></div><div class="section" title="Diagnostics"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.profile_mode.diagnostics"/>Diagnostics</h2></div></div></div><p> + The table below presents all the diagnostics we intend to implement. + Each diagnostic has a corresponding compile time switch + <code class="code">-D_GLIBCXX_PROFILE_<diagnostic></code>. + Groups of related diagnostics can be turned on with a single switch. + For instance, <code class="code">-D_GLIBCXX_PROFILE_LOCALITY</code> is equivalent to + <code class="code">-D_GLIBCXX_PROFILE_SOFTWARE_PREFETCH + -D_GLIBCXX_PROFILE_RBTREE_LOCALITY</code>. + </p><p> + The benefit, cost, expected frequency and accuracy of each diagnostic + was given a grade from 1 to 10, where 10 is highest. + A high benefit means that, if the diagnostic is accurate, the expected + performance improvement is high. + A high cost means that turning this diagnostic on leads to high slowdown. + A high frequency means that we expect this to occur relatively often. + A high accuracy means that the diagnostic is unlikely to be wrong. + These grades are not perfect. They are just meant to guide users with + specific needs or time budgets. + </p><div class="table"><a id="id487386"/><p class="title"><strong>Table 19.2. Profile Diagnostics</strong></p><div class="table-contents"><table summary="Profile Diagnostics" border="1"><colgroup><col style="text-align: left" class="c1"/><col style="text-align: left" class="c2"/><col style="text-align: left" class="c3"/><col style="text-align: left" class="c4"/><col style="text-align: left" class="c5"/><col style="text-align: left" class="c6"/><col style="text-align: left" class="c7"/></colgroup><thead><tr><th style="text-align: left">Group</th><th style="text-align: left">Flag</th><th style="text-align: left">Benefit</th><th style="text-align: left">Cost</th><th style="text-align: left">Freq.</th><th style="text-align: left">Implemented</th><td class="auto-generated"> </td></tr></thead><tbody><tr><td style="text-align: left"><a class="link" href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.containers" title="Containers"> + CONTAINERS</a></td><td style="text-align: left"><a class="link" href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.hashtable_too_small" title="Hashtable Too Small"> + HASHTABLE_TOO_SMALL</a></td><td style="text-align: left">10</td><td style="text-align: left">1</td><td style="text-align: left"> </td><td style="text-align: left">10</td><td style="text-align: left">yes</td></tr><tr><td style="text-align: left"> </td><td style="text-align: left"><a class="link" href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.hashtable_too_large" title="Hashtable Too Large"> + HASHTABLE_TOO_LARGE</a></td><td style="text-align: left">5</td><td style="text-align: left">1</td><td style="text-align: left"> </td><td style="text-align: left">10</td><td style="text-align: left">yes</td></tr><tr><td style="text-align: left"> </td><td style="text-align: left"><a class="link" href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.inefficient_hash" title="Inefficient Hash"> + INEFFICIENT_HASH</a></td><td style="text-align: left">7</td><td style="text-align: left">3</td><td style="text-align: left"> </td><td style="text-align: left">10</td><td style="text-align: left">yes</td></tr><tr><td style="text-align: left"> </td><td style="text-align: left"><a class="link" href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.vector_too_small" title="Vector Too Small"> + VECTOR_TOO_SMALL</a></td><td style="text-align: left">8</td><td style="text-align: left">1</td><td style="text-align: left"> </td><td style="text-align: left">10</td><td style="text-align: left">yes</td></tr><tr><td style="text-align: left"> </td><td style="text-align: left"><a class="link" href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.vector_too_large" title="Vector Too Large"> + VECTOR_TOO_LARGE</a></td><td style="text-align: left">5</td><td style="text-align: left">1</td><td style="text-align: left"> </td><td style="text-align: left">10</td><td style="text-align: left">yes</td></tr><tr><td style="text-align: left"> </td><td style="text-align: left"><a class="link" href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.vector_to_hashtable" title="Vector to Hashtable"> + VECTOR_TO_HASHTABLE</a></td><td style="text-align: left">7</td><td style="text-align: left">7</td><td style="text-align: left"> </td><td style="text-align: left">10</td><td style="text-align: left">no</td></tr><tr><td style="text-align: left"> </td><td style="text-align: left"><a class="link" href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.hashtable_to_vector" title="Hashtable to Vector"> + HASHTABLE_TO_VECTOR</a></td><td style="text-align: left">7</td><td style="text-align: left">7</td><td style="text-align: left"> </td><td style="text-align: left">10</td><td style="text-align: left">no</td></tr><tr><td style="text-align: left"> </td><td style="text-align: left"><a class="link" href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.vector_to_list" title="Vector to List"> + VECTOR_TO_LIST</a></td><td style="text-align: left">8</td><td style="text-align: left">5</td><td style="text-align: left"> </td><td style="text-align: left">10</td><td style="text-align: left">yes</td></tr><tr><td style="text-align: left"> </td><td style="text-align: left"><a class="link" href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.list_to_vector" title="List to Vector"> + LIST_TO_VECTOR</a></td><td style="text-align: left">10</td><td style="text-align: left">5</td><td style="text-align: left"> </td><td style="text-align: left">10</td><td style="text-align: left">no</td></tr><tr><td style="text-align: left"> </td><td style="text-align: left"><a class="link" href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.assoc_ord_to_unord" title="Ordered to Unordered Associative Container"> + ORDERED_TO_UNORDERED</a></td><td style="text-align: left">10</td><td style="text-align: left">5</td><td style="text-align: left"> </td><td style="text-align: left">10</td><td style="text-align: left">only map/unordered_map</td></tr><tr><td style="text-align: left"><a class="link" href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.algorithms" title="Algorithms"> + ALGORITHMS</a></td><td style="text-align: left"><a class="link" href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.algorithms.sort" title="Sort Algorithm Performance"> + SORT</a></td><td style="text-align: left">7</td><td style="text-align: left">8</td><td style="text-align: left"> </td><td style="text-align: left">7</td><td style="text-align: left">no</td></tr><tr><td style="text-align: left"><a class="link" href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.locality" title="Data Locality"> + LOCALITY</a></td><td style="text-align: left"><a class="link" href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.locality.sw_prefetch" title="Need Software Prefetch"> + SOFTWARE_PREFETCH</a></td><td style="text-align: left">8</td><td style="text-align: left">8</td><td style="text-align: left"> </td><td style="text-align: left">5</td><td style="text-align: left">no</td></tr><tr><td style="text-align: left"> </td><td style="text-align: left"><a class="link" href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.locality.linked" title="Linked Structure Locality"> + RBTREE_LOCALITY</a></td><td style="text-align: left">4</td><td style="text-align: left">8</td><td style="text-align: left"> </td><td style="text-align: left">5</td><td style="text-align: left">no</td></tr><tr><td style="text-align: left"> </td><td style="text-align: left"><a class="link" href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.mthread.false_share" title="False Sharing"> + FALSE_SHARING</a></td><td style="text-align: left">8</td><td style="text-align: left">10</td><td style="text-align: left"> </td><td style="text-align: left">10</td><td style="text-align: left">no</td></tr></tbody></table></div></div><br class="table-break"/><div class="section" title="Diagnostic Template"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.analysis.template"/>Diagnostic Template</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><span class="emphasis"><em>Switch:</em></span> + <code class="code">_GLIBCXX_PROFILE_<diagnostic></code>. + </p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span> What problem will it diagnose? + </p></li><li class="listitem"><p><span class="emphasis"><em>Fundamentals:</em></span>. + What is the fundamental reason why this is a problem</p></li><li class="listitem"><p><span class="emphasis"><em>Sample runtime reduction:</em></span> + Percentage reduction in execution time. When reduction is more than + a constant factor, describe the reduction rate formula. + </p></li><li class="listitem"><p><span class="emphasis"><em>Recommendation:</em></span> + What would the advise look like?</p></li><li class="listitem"><p><span class="emphasis"><em>To instrument:</em></span> + What stdlibc++ components need to be instrumented?</p></li><li class="listitem"><p><span class="emphasis"><em>Analysis:</em></span> + How do we decide when to issue the advice?</p></li><li class="listitem"><p><span class="emphasis"><em>Cost model:</em></span> + How do we measure benefits? Math goes here.</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span> +</p><pre class="programlisting"> +program code +... +advice sample +</pre><p> +</p></li></ul></div></div><div class="section" title="Containers"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.analysis.containers"/>Containers</h3></div></div></div><p> +<span class="emphasis"><em>Switch:</em></span> + <code class="code">_GLIBCXX_PROFILE_CONTAINERS</code>. +</p><div class="section" title="Hashtable Too Small"><div class="titlepage"><div><div><h4 class="title"><a id="manual.ext.profile_mode.analysis.hashtable_too_small"/>Hashtable Too Small</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><span class="emphasis"><em>Switch:</em></span> + <code class="code">_GLIBCXX_PROFILE_HASHTABLE_TOO_SMALL</code>. + </p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span> Detect hashtables with many + rehash operations, small construction size and large destruction size. + </p></li><li class="listitem"><p><span class="emphasis"><em>Fundamentals:</em></span> Rehash is very expensive. + Read content, follow chains within bucket, evaluate hash function, place at + new location in different order.</p></li><li class="listitem"><p><span class="emphasis"><em>Sample runtime reduction:</em></span> 36%. + Code similar to example below. + </p></li><li class="listitem"><p><span class="emphasis"><em>Recommendation:</em></span> + Set initial size to N at construction site S. + </p></li><li class="listitem"><p><span class="emphasis"><em>To instrument:</em></span> + <code class="code">unordered_set, unordered_map</code> constructor, destructor, rehash. + </p></li><li class="listitem"><p><span class="emphasis"><em>Analysis:</em></span> + For each dynamic instance of <code class="code">unordered_[multi]set|map</code>, + record initial size and call context of the constructor. + Record size increase, if any, after each relevant operation such as insert. + Record the estimated rehash cost.</p></li><li class="listitem"><p><span class="emphasis"><em>Cost model:</em></span> + Number of individual rehash operations * cost per rehash.</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span> +</p><pre class="programlisting"> +1 unordered_set<int> us; +2 for (int k = 0; k < 1000000; ++k) { +3 us.insert(k); +4 } + +foo.cc:1: advice: Changing initial unordered_set size from 10 to 1000000 saves 1025530 rehash operations. +</pre><p> +</p></li></ul></div></div><div class="section" title="Hashtable Too Large"><div class="titlepage"><div><div><h4 class="title"><a id="manual.ext.profile_mode.analysis.hashtable_too_large"/>Hashtable Too Large</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><span class="emphasis"><em>Switch:</em></span> + <code class="code">_GLIBCXX_PROFILE_HASHTABLE_TOO_LARGE</code>. + </p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span> Detect hashtables which are + never filled up because fewer elements than reserved are ever + inserted. + </p></li><li class="listitem"><p><span class="emphasis"><em>Fundamentals:</em></span> Save memory, which + is good in itself and may also improve memory reference performance through + fewer cache and TLB misses.</p></li><li class="listitem"><p><span class="emphasis"><em>Sample runtime reduction:</em></span> unknown. + </p></li><li class="listitem"><p><span class="emphasis"><em>Recommendation:</em></span> + Set initial size to N at construction site S. + </p></li><li class="listitem"><p><span class="emphasis"><em>To instrument:</em></span> + <code class="code">unordered_set, unordered_map</code> constructor, destructor, rehash. + </p></li><li class="listitem"><p><span class="emphasis"><em>Analysis:</em></span> + For each dynamic instance of <code class="code">unordered_[multi]set|map</code>, + record initial size and call context of the constructor, and correlate it + with its size at destruction time. + </p></li><li class="listitem"><p><span class="emphasis"><em>Cost model:</em></span> + Number of iteration operations + memory saved.</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span> +</p><pre class="programlisting"> +1 vector<unordered_set<int>> v(100000, unordered_set<int>(100)) ; +2 for (int k = 0; k < 100000; ++k) { +3 for (int j = 0; j < 10; ++j) { +4 v[k].insert(k + j); +5 } +6 } + +foo.cc:1: advice: Changing initial unordered_set size from 100 to 10 saves N +bytes of memory and M iteration steps. +</pre><p> +</p></li></ul></div></div><div class="section" title="Inefficient Hash"><div class="titlepage"><div><div><h4 class="title"><a id="manual.ext.profile_mode.analysis.inefficient_hash"/>Inefficient Hash</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><span class="emphasis"><em>Switch:</em></span> + <code class="code">_GLIBCXX_PROFILE_INEFFICIENT_HASH</code>. + </p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span> Detect hashtables with polarized + distribution. + </p></li><li class="listitem"><p><span class="emphasis"><em>Fundamentals:</em></span> A non-uniform + distribution may lead to long chains, thus possibly increasing complexity + by a factor up to the number of elements. + </p></li><li class="listitem"><p><span class="emphasis"><em>Sample runtime reduction:</em></span> factor up + to container size. + </p></li><li class="listitem"><p><span class="emphasis"><em>Recommendation:</em></span> Change hash function + for container built at site S. Distribution score = N. Access score = S. + Longest chain = C, in bucket B. + </p></li><li class="listitem"><p><span class="emphasis"><em>To instrument:</em></span> + <code class="code">unordered_set, unordered_map</code> constructor, destructor, [], + insert, iterator. + </p></li><li class="listitem"><p><span class="emphasis"><em>Analysis:</em></span> + Count the exact number of link traversals. + </p></li><li class="listitem"><p><span class="emphasis"><em>Cost model:</em></span> + Total number of links traversed.</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span> +</p><pre class="programlisting"> +class dumb_hash { + public: + size_t operator() (int i) const { return 0; } +}; +... + unordered_set<int, dumb_hash> hs; + ... + for (int i = 0; i < COUNT; ++i) { + hs.find(i); + } +</pre><p> +</p></li></ul></div></div><div class="section" title="Vector Too Small"><div class="titlepage"><div><div><h4 class="title"><a id="manual.ext.profile_mode.analysis.vector_too_small"/>Vector Too Small</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><span class="emphasis"><em>Switch:</em></span> + <code class="code">_GLIBCXX_PROFILE_VECTOR_TOO_SMALL</code>. + </p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span>Detect vectors with many + resize operations, small construction size and large destruction size.. + </p></li><li class="listitem"><p><span class="emphasis"><em>Fundamentals:</em></span>Resizing can be expensive. + Copying large amounts of data takes time. Resizing many small vectors may + have allocation overhead and affect locality.</p></li><li class="listitem"><p><span class="emphasis"><em>Sample runtime reduction:</em></span>%. + </p></li><li class="listitem"><p><span class="emphasis"><em>Recommendation:</em></span> + Set initial size to N at construction site S.</p></li><li class="listitem"><p><span class="emphasis"><em>To instrument:</em></span><code class="code">vector</code>. + </p></li><li class="listitem"><p><span class="emphasis"><em>Analysis:</em></span> + For each dynamic instance of <code class="code">vector</code>, + record initial size and call context of the constructor. + Record size increase, if any, after each relevant operation such as + <code class="code">push_back</code>. Record the estimated resize cost. + </p></li><li class="listitem"><p><span class="emphasis"><em>Cost model:</em></span> + Total number of words copied * time to copy a word.</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span> +</p><pre class="programlisting"> +1 vector<int> v; +2 for (int k = 0; k < 1000000; ++k) { +3 v.push_back(k); +4 } + +foo.cc:1: advice: Changing initial vector size from 10 to 1000000 saves +copying 4000000 bytes and 20 memory allocations and deallocations. +</pre><p> +</p></li></ul></div></div><div class="section" title="Vector Too Large"><div class="titlepage"><div><div><h4 class="title"><a id="manual.ext.profile_mode.analysis.vector_too_large"/>Vector Too Large</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><span class="emphasis"><em>Switch:</em></span> + <code class="code">_GLIBCXX_PROFILE_VECTOR_TOO_LARGE</code> + </p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span>Detect vectors which are + never filled up because fewer elements than reserved are ever + inserted. + </p></li><li class="listitem"><p><span class="emphasis"><em>Fundamentals:</em></span>Save memory, which + is good in itself and may also improve memory reference performance through + fewer cache and TLB misses.</p></li><li class="listitem"><p><span class="emphasis"><em>Sample runtime reduction:</em></span>%. + </p></li><li class="listitem"><p><span class="emphasis"><em>Recommendation:</em></span> + Set initial size to N at construction site S.</p></li><li class="listitem"><p><span class="emphasis"><em>To instrument:</em></span><code class="code">vector</code>. + </p></li><li class="listitem"><p><span class="emphasis"><em>Analysis:</em></span> + For each dynamic instance of <code class="code">vector</code>, + record initial size and call context of the constructor, and correlate it + with its size at destruction time.</p></li><li class="listitem"><p><span class="emphasis"><em>Cost model:</em></span> + Total amount of memory saved.</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span> +</p><pre class="programlisting"> +1 vector<vector<int>> v(100000, vector<int>(100)) ; +2 for (int k = 0; k < 100000; ++k) { +3 for (int j = 0; j < 10; ++j) { +4 v[k].insert(k + j); +5 } +6 } + +foo.cc:1: advice: Changing initial vector size from 100 to 10 saves N +bytes of memory and may reduce the number of cache and TLB misses. +</pre><p> +</p></li></ul></div></div><div class="section" title="Vector to Hashtable"><div class="titlepage"><div><div><h4 class="title"><a id="manual.ext.profile_mode.analysis.vector_to_hashtable"/>Vector to Hashtable</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><span class="emphasis"><em>Switch:</em></span> + <code class="code">_GLIBCXX_PROFILE_VECTOR_TO_HASHTABLE</code>. + </p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span> Detect uses of + <code class="code">vector</code> that can be substituted with <code class="code">unordered_set</code> + to reduce execution time. + </p></li><li class="listitem"><p><span class="emphasis"><em>Fundamentals:</em></span> + Linear search in a vector is very expensive, whereas searching in a hashtable + is very quick.</p></li><li class="listitem"><p><span class="emphasis"><em>Sample runtime reduction:</em></span>factor up + to container size. + </p></li><li class="listitem"><p><span class="emphasis"><em>Recommendation:</em></span>Replace + <code class="code">vector</code> with <code class="code">unordered_set</code> at site S. + </p></li><li class="listitem"><p><span class="emphasis"><em>To instrument:</em></span><code class="code">vector</code> + operations and access methods.</p></li><li class="listitem"><p><span class="emphasis"><em>Analysis:</em></span> + For each dynamic instance of <code class="code">vector</code>, + record call context of the constructor. Issue the advice only if the + only methods called on this <code class="code">vector</code> are <code class="code">push_back</code>, + <code class="code">insert</code> and <code class="code">find</code>. + </p></li><li class="listitem"><p><span class="emphasis"><em>Cost model:</em></span> + Cost(vector::push_back) + cost(vector::insert) + cost(find, vector) - + cost(unordered_set::insert) + cost(unordered_set::find). + </p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span> +</p><pre class="programlisting"> +1 vector<int> v; +... +2 for (int i = 0; i < 1000; ++i) { +3 find(v.begin(), v.end(), i); +4 } + +foo.cc:1: advice: Changing "vector" to "unordered_set" will save about 500,000 +comparisons. +</pre><p> +</p></li></ul></div></div><div class="section" title="Hashtable to Vector"><div class="titlepage"><div><div><h4 class="title"><a id="manual.ext.profile_mode.analysis.hashtable_to_vector"/>Hashtable to Vector</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><span class="emphasis"><em>Switch:</em></span> + <code class="code">_GLIBCXX_PROFILE_HASHTABLE_TO_VECTOR</code>. + </p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span> Detect uses of + <code class="code">unordered_set</code> that can be substituted with <code class="code">vector</code> + to reduce execution time. + </p></li><li class="listitem"><p><span class="emphasis"><em>Fundamentals:</em></span> + Hashtable iterator is slower than vector iterator.</p></li><li class="listitem"><p><span class="emphasis"><em>Sample runtime reduction:</em></span>95%. + </p></li><li class="listitem"><p><span class="emphasis"><em>Recommendation:</em></span>Replace + <code class="code">unordered_set</code> with <code class="code">vector</code> at site S. + </p></li><li class="listitem"><p><span class="emphasis"><em>To instrument:</em></span><code class="code">unordered_set</code> + operations and access methods.</p></li><li class="listitem"><p><span class="emphasis"><em>Analysis:</em></span> + For each dynamic instance of <code class="code">unordered_set</code>, + record call context of the constructor. Issue the advice only if the + number of <code class="code">find</code>, <code class="code">insert</code> and <code class="code">[]</code> + operations on this <code class="code">unordered_set</code> are small relative to the + number of elements, and methods <code class="code">begin</code> or <code class="code">end</code> + are invoked (suggesting iteration).</p></li><li class="listitem"><p><span class="emphasis"><em>Cost model:</em></span> + Number of .</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span> +</p><pre class="programlisting"> +1 unordered_set<int> us; +... +2 int s = 0; +3 for (unordered_set<int>::iterator it = us.begin(); it != us.end(); ++it) { +4 s += *it; +5 } + +foo.cc:1: advice: Changing "unordered_set" to "vector" will save about N +indirections and may achieve better data locality. +</pre><p> +</p></li></ul></div></div><div class="section" title="Vector to List"><div class="titlepage"><div><div><h4 class="title"><a id="manual.ext.profile_mode.analysis.vector_to_list"/>Vector to List</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><span class="emphasis"><em>Switch:</em></span> + <code class="code">_GLIBCXX_PROFILE_VECTOR_TO_LIST</code>. + </p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span> Detect cases where + <code class="code">vector</code> could be substituted with <code class="code">list</code> for + better performance. + </p></li><li class="listitem"><p><span class="emphasis"><em>Fundamentals:</em></span> + Inserting in the middle of a vector is expensive compared to inserting in a + list. + </p></li><li class="listitem"><p><span class="emphasis"><em>Sample runtime reduction:</em></span>factor up to + container size. + </p></li><li class="listitem"><p><span class="emphasis"><em>Recommendation:</em></span>Replace vector with list + at site S.</p></li><li class="listitem"><p><span class="emphasis"><em>To instrument:</em></span><code class="code">vector</code> + operations and access methods.</p></li><li class="listitem"><p><span class="emphasis"><em>Analysis:</em></span> + For each dynamic instance of <code class="code">vector</code>, + record the call context of the constructor. Record the overhead of each + <code class="code">insert</code> operation based on current size and insert position. + Report instance with high insertion overhead. + </p></li><li class="listitem"><p><span class="emphasis"><em>Cost model:</em></span> + (Sum(cost(vector::method)) - Sum(cost(list::method)), for + method in [push_back, insert, erase]) + + (Cost(iterate vector) - Cost(iterate list))</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span> +</p><pre class="programlisting"> +1 vector<int> v; +2 for (int i = 0; i < 10000; ++i) { +3 v.insert(v.begin(), i); +4 } + +foo.cc:1: advice: Changing "vector" to "list" will save about 5,000,000 +operations. +</pre><p> +</p></li></ul></div></div><div class="section" title="List to Vector"><div class="titlepage"><div><div><h4 class="title"><a id="manual.ext.profile_mode.analysis.list_to_vector"/>List to Vector</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><span class="emphasis"><em>Switch:</em></span> + <code class="code">_GLIBCXX_PROFILE_LIST_TO_VECTOR</code>. + </p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span> Detect cases where + <code class="code">list</code> could be substituted with <code class="code">vector</code> for + better performance. + </p></li><li class="listitem"><p><span class="emphasis"><em>Fundamentals:</em></span> + Iterating through a vector is faster than through a list. + </p></li><li class="listitem"><p><span class="emphasis"><em>Sample runtime reduction:</em></span>64%. + </p></li><li class="listitem"><p><span class="emphasis"><em>Recommendation:</em></span>Replace list with vector + at site S.</p></li><li class="listitem"><p><span class="emphasis"><em>To instrument:</em></span><code class="code">vector</code> + operations and access methods.</p></li><li class="listitem"><p><span class="emphasis"><em>Analysis:</em></span> + Issue the advice if there are no <code class="code">insert</code> operations. + </p></li><li class="listitem"><p><span class="emphasis"><em>Cost model:</em></span> + (Sum(cost(vector::method)) - Sum(cost(list::method)), for + method in [push_back, insert, erase]) + + (Cost(iterate vector) - Cost(iterate list))</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span> +</p><pre class="programlisting"> +1 list<int> l; +... +2 int sum = 0; +3 for (list<int>::iterator it = l.begin(); it != l.end(); ++it) { +4 sum += *it; +5 } + +foo.cc:1: advice: Changing "list" to "vector" will save about 1000000 indirect +memory references. +</pre><p> +</p></li></ul></div></div><div class="section" title="List to Forward List (Slist)"><div class="titlepage"><div><div><h4 class="title"><a id="manual.ext.profile_mode.analysis.list_to_slist"/>List to Forward List (Slist)</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><span class="emphasis"><em>Switch:</em></span> + <code class="code">_GLIBCXX_PROFILE_LIST_TO_SLIST</code>. + </p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span> Detect cases where + <code class="code">list</code> could be substituted with <code class="code">forward_list</code> for + better performance. + </p></li><li class="listitem"><p><span class="emphasis"><em>Fundamentals:</em></span> + The memory footprint of a forward_list is smaller than that of a list. + This has beneficial effects on memory subsystem, e.g., fewer cache misses. + </p></li><li class="listitem"><p><span class="emphasis"><em>Sample runtime reduction:</em></span>40%. + Note that the reduction is only noticeable if the size of the forward_list + node is in fact larger than that of the list node. For memory allocators + with size classes, you will only notice an effect when the two node sizes + belong to different allocator size classes. + </p></li><li class="listitem"><p><span class="emphasis"><em>Recommendation:</em></span>Replace list with + forward_list at site S.</p></li><li class="listitem"><p><span class="emphasis"><em>To instrument:</em></span><code class="code">list</code> + operations and iteration methods.</p></li><li class="listitem"><p><span class="emphasis"><em>Analysis:</em></span> + Issue the advice if there are no <code class="code">backwards</code> traversals + or insertion before a given node. + </p></li><li class="listitem"><p><span class="emphasis"><em>Cost model:</em></span> + Always true.</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span> +</p><pre class="programlisting"> +1 list<int> l; +... +2 int sum = 0; +3 for (list<int>::iterator it = l.begin(); it != l.end(); ++it) { +4 sum += *it; +5 } + +foo.cc:1: advice: Change "list" to "forward_list". +</pre><p> +</p></li></ul></div></div><div class="section" title="Ordered to Unordered Associative Container"><div class="titlepage"><div><div><h4 class="title"><a id="manual.ext.profile_mode.analysis.assoc_ord_to_unord"/>Ordered to Unordered Associative Container</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><span class="emphasis"><em>Switch:</em></span> + <code class="code">_GLIBCXX_PROFILE_ORDERED_TO_UNORDERED</code>. + </p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span> Detect cases where ordered + associative containers can be replaced with unordered ones. + </p></li><li class="listitem"><p><span class="emphasis"><em>Fundamentals:</em></span> + Insert and search are quicker in a hashtable than in + a red-black tree.</p></li><li class="listitem"><p><span class="emphasis"><em>Sample runtime reduction:</em></span>52%. + </p></li><li class="listitem"><p><span class="emphasis"><em>Recommendation:</em></span> + Replace set with unordered_set at site S.</p></li><li class="listitem"><p><span class="emphasis"><em>To instrument:</em></span> + <code class="code">set</code>, <code class="code">multiset</code>, <code class="code">map</code>, + <code class="code">multimap</code> methods.</p></li><li class="listitem"><p><span class="emphasis"><em>Analysis:</em></span> + Issue the advice only if we are not using operator <code class="code">++</code> on any + iterator on a particular <code class="code">[multi]set|map</code>. + </p></li><li class="listitem"><p><span class="emphasis"><em>Cost model:</em></span> + (Sum(cost(hashtable::method)) - Sum(cost(rbtree::method)), for + method in [insert, erase, find]) + + (Cost(iterate hashtable) - Cost(iterate rbtree))</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span> +</p><pre class="programlisting"> +1 set<int> s; +2 for (int i = 0; i < 100000; ++i) { +3 s.insert(i); +4 } +5 int sum = 0; +6 for (int i = 0; i < 100000; ++i) { +7 sum += *s.find(i); +8 } +</pre><p> +</p></li></ul></div></div></div><div class="section" title="Algorithms"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.analysis.algorithms"/>Algorithms</h3></div></div></div><p><span class="emphasis"><em>Switch:</em></span> + <code class="code">_GLIBCXX_PROFILE_ALGORITHMS</code>. + </p><div class="section" title="Sort Algorithm Performance"><div class="titlepage"><div><div><h4 class="title"><a id="manual.ext.profile_mode.analysis.algorithms.sort"/>Sort Algorithm Performance</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><span class="emphasis"><em>Switch:</em></span> + <code class="code">_GLIBCXX_PROFILE_SORT</code>. + </p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span> Give measure of sort algorithm + performance based on actual input. For instance, advise Radix Sort over + Quick Sort for a particular call context. + </p></li><li class="listitem"><p><span class="emphasis"><em>Fundamentals:</em></span> + See papers: + <a class="link" href="http://portal.acm.org/citation.cfm?doid=1065944.1065981"> + A framework for adaptive algorithm selection in STAPL</a> and + <a class="link" href="http://ieeexplore.ieee.org/search/wrapper.jsp?arnumber=4228227"> + Optimizing Sorting with Machine Learning Algorithms</a>. + </p></li><li class="listitem"><p><span class="emphasis"><em>Sample runtime reduction:</em></span>60%. + </p></li><li class="listitem"><p><span class="emphasis"><em>Recommendation:</em></span> Change sort algorithm + at site S from X Sort to Y Sort.</p></li><li class="listitem"><p><span class="emphasis"><em>To instrument:</em></span> <code class="code">sort</code> + algorithm.</p></li><li class="listitem"><p><span class="emphasis"><em>Analysis:</em></span> + Issue the advice if the cost model tells us that another sort algorithm + would do better on this input. Requires us to know what algorithm we + are using in our sort implementation in release mode.</p></li><li class="listitem"><p><span class="emphasis"><em>Cost model:</em></span> + Runtime(algo) for algo in [radix, quick, merge, ...]</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span> +</p><pre class="programlisting"> +</pre><p> +</p></li></ul></div></div></div><div class="section" title="Data Locality"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.analysis.locality"/>Data Locality</h3></div></div></div><p><span class="emphasis"><em>Switch:</em></span> + <code class="code">_GLIBCXX_PROFILE_LOCALITY</code>. + </p><div class="section" title="Need Software Prefetch"><div class="titlepage"><div><div><h4 class="title"><a id="manual.ext.profile_mode.analysis.locality.sw_prefetch"/>Need Software Prefetch</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><span class="emphasis"><em>Switch:</em></span> + <code class="code">_GLIBCXX_PROFILE_SOFTWARE_PREFETCH</code>. + </p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span> Discover sequences of indirect + memory accesses that are not regular, thus cannot be predicted by + hardware prefetchers. + </p></li><li class="listitem"><p><span class="emphasis"><em>Fundamentals:</em></span> + Indirect references are hard to predict and are very expensive when they + miss in caches.</p></li><li class="listitem"><p><span class="emphasis"><em>Sample runtime reduction:</em></span>25%. + </p></li><li class="listitem"><p><span class="emphasis"><em>Recommendation:</em></span> Insert prefetch + instruction.</p></li><li class="listitem"><p><span class="emphasis"><em>To instrument:</em></span> Vector iterator and + access operator []. + </p></li><li class="listitem"><p><span class="emphasis"><em>Analysis:</em></span> + First, get cache line size and page size from system. + Then record iterator dereference sequences for which the value is a pointer. + For each sequence within a container, issue a warning if successive pointer + addresses are not within cache lines and do not form a linear pattern + (otherwise they may be prefetched by hardware). + If they also step across page boundaries, make the warning stronger. + </p><p>The same analysis applies to containers other than vector. + However, we cannot give the same advice for linked structures, such as list, + as there is no random access to the n-th element. The user may still be + able to benefit from this information, for instance by employing frays (user + level light weight threads) to hide the latency of chasing pointers. + </p><p> + This analysis is a little oversimplified. A better cost model could be + created by understanding the capability of the hardware prefetcher. + This model could be trained automatically by running a set of synthetic + cases. + </p></li><li class="listitem"><p><span class="emphasis"><em>Cost model:</em></span> + Total distance between pointer values of successive elements in vectors + of pointers.</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span> +</p><pre class="programlisting"> +1 int zero = 0; +2 vector<int*> v(10000000, &zero); +3 for (int k = 0; k < 10000000; ++k) { +4 v[random() % 10000000] = new int(k); +5 } +6 for (int j = 0; j < 10000000; ++j) { +7 count += (*v[j] == 0 ? 0 : 1); +8 } + +foo.cc:7: advice: Insert prefetch instruction. +</pre><p> +</p></li></ul></div></div><div class="section" title="Linked Structure Locality"><div class="titlepage"><div><div><h4 class="title"><a id="manual.ext.profile_mode.analysis.locality.linked"/>Linked Structure Locality</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><span class="emphasis"><em>Switch:</em></span> + <code class="code">_GLIBCXX_PROFILE_RBTREE_LOCALITY</code>. + </p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span> Give measure of locality of + objects stored in linked structures (lists, red-black trees and hashtables) + with respect to their actual traversal patterns. + </p></li><li class="listitem"><p><span class="emphasis"><em>Fundamentals:</em></span>Allocation can be tuned + to a specific traversal pattern, to result in better data locality. + See paper: + <a class="link" href="http://www.springerlink.com/content/8085744l00x72662/"> + Custom Memory Allocation for Free</a>. + </p></li><li class="listitem"><p><span class="emphasis"><em>Sample runtime reduction:</em></span>30%. + </p></li><li class="listitem"><p><span class="emphasis"><em>Recommendation:</em></span> + High scatter score N for container built at site S. + Consider changing allocation sequence or choosing a structure conscious + allocator.</p></li><li class="listitem"><p><span class="emphasis"><em>To instrument:</em></span> Methods of all + containers using linked structures.</p></li><li class="listitem"><p><span class="emphasis"><em>Analysis:</em></span> + First, get cache line size and page size from system. + Then record the number of successive elements that are on different line + or page, for each traversal method such as <code class="code">find</code>. Give advice + only if the ratio between this number and the number of total node hops + is above a threshold.</p></li><li class="listitem"><p><span class="emphasis"><em>Cost model:</em></span> + Sum(same_cache_line(this,previous))</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span> +</p><pre class="programlisting"> + 1 set<int> s; + 2 for (int i = 0; i < 10000000; ++i) { + 3 s.insert(i); + 4 } + 5 set<int> s1, s2; + 6 for (int i = 0; i < 10000000; ++i) { + 7 s1.insert(i); + 8 s2.insert(i); + 9 } +... + // Fast, better locality. +10 for (set<int>::iterator it = s.begin(); it != s.end(); ++it) { +11 sum += *it; +12 } + // Slow, elements are further apart. +13 for (set<int>::iterator it = s1.begin(); it != s1.end(); ++it) { +14 sum += *it; +15 } + +foo.cc:5: advice: High scatter score NNN for set built here. Consider changing +the allocation sequence or switching to a structure conscious allocator. +</pre><p> +</p></li></ul></div></div></div><div class="section" title="Multithreaded Data Access"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.analysis.mthread"/>Multithreaded Data Access</h3></div></div></div><p> + The diagnostics in this group are not meant to be implemented short term. + They require compiler support to know when container elements are written + to. Instrumentation can only tell us when elements are referenced. + </p><p><span class="emphasis"><em>Switch:</em></span> + <code class="code">_GLIBCXX_PROFILE_MULTITHREADED</code>. + </p><div class="section" title="Data Dependence Violations at Container Level"><div class="titlepage"><div><div><h4 class="title"><a id="manual.ext.profile_mode.analysis.mthread.ddtest"/>Data Dependence Violations at Container Level</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><span class="emphasis"><em>Switch:</em></span> + <code class="code">_GLIBCXX_PROFILE_DDTEST</code>. + </p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span> Detect container elements + that are referenced from multiple threads in the parallel region or + across parallel regions. + </p></li><li class="listitem"><p><span class="emphasis"><em>Fundamentals:</em></span> + Sharing data between threads requires communication and perhaps locking, + which may be expensive. + </p></li><li class="listitem"><p><span class="emphasis"><em>Sample runtime reduction:</em></span>?%. + </p></li><li class="listitem"><p><span class="emphasis"><em>Recommendation:</em></span> Change data + distribution or parallel algorithm.</p></li><li class="listitem"><p><span class="emphasis"><em>To instrument:</em></span> Container access methods + and iterators. + </p></li><li class="listitem"><p><span class="emphasis"><em>Analysis:</em></span> + Keep a shadow for each container. Record iterator dereferences and + container member accesses. Issue advice for elements referenced by + multiple threads. + See paper: <a class="link" href="http://portal.acm.org/citation.cfm?id=207110.207148"> + The LRPD test: speculative run-time parallelization of loops with + privatization and reduction parallelization</a>. + </p></li><li class="listitem"><p><span class="emphasis"><em>Cost model:</em></span> + Number of accesses to elements referenced from multiple threads + </p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span> +</p><pre class="programlisting"> +</pre><p> +</p></li></ul></div></div><div class="section" title="False Sharing"><div class="titlepage"><div><div><h4 class="title"><a id="manual.ext.profile_mode.analysis.mthread.false_share"/>False Sharing</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><span class="emphasis"><em>Switch:</em></span> + <code class="code">_GLIBCXX_PROFILE_FALSE_SHARING</code>. + </p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span> Detect elements in the + same container which share a cache line, are written by at least one + thread, and accessed by different threads. + </p></li><li class="listitem"><p><span class="emphasis"><em>Fundamentals:</em></span> Under these assumptions, + cache protocols require + communication to invalidate lines, which may be expensive. + </p></li><li class="listitem"><p><span class="emphasis"><em>Sample runtime reduction:</em></span>68%. + </p></li><li class="listitem"><p><span class="emphasis"><em>Recommendation:</em></span> Reorganize container + or use padding to avoid false sharing.</p></li><li class="listitem"><p><span class="emphasis"><em>To instrument:</em></span> Container access methods + and iterators. + </p></li><li class="listitem"><p><span class="emphasis"><em>Analysis:</em></span> + First, get the cache line size. + For each shared container, record all the associated iterator dereferences + and member access methods with the thread id. Compare the address lists + across threads to detect references in two different threads to the same + cache line. Issue a warning only if the ratio to total references is + significant. Do the same for iterator dereference values if they are + pointers.</p></li><li class="listitem"><p><span class="emphasis"><em>Cost model:</em></span> + Number of accesses to same cache line from different threads. + </p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span> +</p><pre class="programlisting"> +1 vector<int> v(2, 0); +2 #pragma omp parallel for shared(v, SIZE) schedule(static, 1) +3 for (i = 0; i < SIZE; ++i) { +4 v[i % 2] += i; +5 } + +OMP_NUM_THREADS=2 ./a.out +foo.cc:1: advice: Change container structure or padding to avoid false +sharing in multithreaded access at foo.cc:4. Detected N shared cache lines. +</pre><p> +</p></li></ul></div></div></div><div class="section" title="Statistics"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.analysis.statistics"/>Statistics</h3></div></div></div><p> +<span class="emphasis"><em>Switch:</em></span> + <code class="code">_GLIBCXX_PROFILE_STATISTICS</code>. +</p><p> + In some cases the cost model may not tell us anything because the costs + appear to offset the benefits. Consider the choice between a vector and + a list. When there are both inserts and iteration, an automatic advice + may not be issued. However, the programmer may still be able to make use + of this information in a different way. +</p><p> + This diagnostic will not issue any advice, but it will print statistics for + each container construction site. The statistics will contain the cost + of each operation actually performed on the container. +</p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="bk01pt03ch19s06.html">Prev</a> </td><td align="center"><a accesskey="u" href="profile_mode.html">Up</a></td><td align="right"> <a accesskey="n" href="ext_allocators.html">Next</a></td></tr><tr><td align="left" valign="top">Developer Information </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Chapter 20. Allocators</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch21s02.html b/libstdc++-v3/doc/html/manual/bk01pt03ch21s02.html new file mode 100644 index 000000000..eba8cfb31 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch21s02.html @@ -0,0 +1,43 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>HP/SGI</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="ext_containers.html" title="Chapter 21. Containers"/><link rel="prev" href="ext_containers.html" title="Chapter 21. Containers"/><link rel="next" href="bk01pt03ch21s03.html" title="Deprecated HP/SGI"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">HP/SGI</th></tr><tr><td align="left"><a accesskey="p" href="ext_containers.html">Prev</a> </td><th width="60%" align="center">Chapter 21. Containers</th><td align="right"> <a accesskey="n" href="bk01pt03ch21s03.html">Next</a></td></tr></table><hr/></div><div class="section" title="HP/SGI"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.containers.sgi"/>HP/SGI</h2></div></div></div><p> + </p><p>A few extensions and nods to backwards-compatibility have been made with + containers. Those dealing with older SGI-style allocators are dealt with + elsewhere. The remaining ones all deal with bits: +</p><p>The old pre-standard <code class="code">bit_vector</code> class is present for + backwards compatibility. It is simply a typedef for the + <code class="code">vector<bool></code> specialization. +</p><p>The <code class="code">bitset</code> class has a number of extensions, described in the + rest of this item. First, we'll mention that this implementation of + <code class="code">bitset<N></code> is specialized for cases where N number of + bits will fit into a single word of storage. If your choice of N is + within that range (<=32 on i686-pc-linux-gnu, for example), then all + of the operations will be faster. +</p><p>There are + versions of single-bit test, set, reset, and flip member functions which + do no range-checking. If we call them member functions of an instantiation + of "bitset<N>," then their names and signatures are: +</p><pre class="programlisting"> + bitset<N>& _Unchecked_set (size_t pos); + bitset<N>& _Unchecked_set (size_t pos, int val); + bitset<N>& _Unchecked_reset (size_t pos); + bitset<N>& _Unchecked_flip (size_t pos); + bool _Unchecked_test (size_t pos); + </pre><p>Note that these may in fact be removed in the future, although we have + no present plans to do so (and there doesn't seem to be any immediate + reason to). +</p><p>The semantics of member function <code class="code">operator[]</code> are not specified + in the C++ standard. A long-standing defect report calls for sensible + obvious semantics, which are already implemented here: <code class="code">op[]</code> + on a const bitset returns a bool, and for a non-const bitset returns a + <code class="code">reference</code> (a nested type). However, this implementation does + no range-checking on the index argument, which is in keeping with other + containers' <code class="code">op[]</code> requirements. The defect report's proposed + resolution calls for range-checking to be done. We'll just wait and see... +</p><p>Finally, two additional searching functions have been added. They return + the index of the first "on" bit, and the index of the first + "on" bit that is after <code class="code">prev</code>, respectively: +</p><pre class="programlisting"> + size_t _Find_first() const; + size_t _Find_next (size_t prev) const;</pre><p>The same caveat given for the _Unchecked_* functions applies here also. +</p></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="ext_containers.html">Prev</a> </td><td align="center"><a accesskey="u" href="ext_containers.html">Up</a></td><td align="right"> <a accesskey="n" href="bk01pt03ch21s03.html">Next</a></td></tr><tr><td align="left" valign="top">Chapter 21. Containers </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Deprecated HP/SGI</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch21s03.html b/libstdc++-v3/doc/html/manual/bk01pt03ch21s03.html new file mode 100644 index 000000000..2f75d608b --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch21s03.html @@ -0,0 +1,50 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Deprecated HP/SGI</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="ext_containers.html" title="Chapter 21. Containers"/><link rel="prev" href="bk01pt03ch21s02.html" title="HP/SGI"/><link rel="next" href="ext_utilities.html" title="Chapter 22. Utilities"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Deprecated HP/SGI</th></tr><tr><td align="left"><a accesskey="p" href="bk01pt03ch21s02.html">Prev</a> </td><th width="60%" align="center">Chapter 21. Containers</th><td align="right"> <a accesskey="n" href="ext_utilities.html">Next</a></td></tr></table><hr/></div><div class="section" title="Deprecated HP/SGI"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.containers.deprecated_sgi"/>Deprecated HP/SGI</h2></div></div></div><p> + The SGI hashing classes <code class="classname">hash_set</code> and + <code class="classname">hash_set</code> have been deprecated by the + unordered_set, unordered_multiset, unordered_map, + unordered_multimap containers in TR1 and the upcoming C++0x, and + may be removed in future releases. + </p><p>The SGI headers</p><pre class="programlisting"> + <hash_map> + <hash_set> + <rope> + <slist> + <rb_tree> + </pre><p>are all here; + <code class="code"><hash_map></code> and <code class="code"><hash_set></code> + are deprecated but available as backwards-compatible extensions, + as discussed further below. <code class="code"><rope></code> is the + SGI specialization for large strings ("rope," + "large strings," get it? Love that geeky humor.) + <code class="code"><slist></code> is a singly-linked list, for when the + doubly-linked <code class="code">list<></code> is too much space + overhead, and <code class="code"><rb_tree></code> exposes the red-black + tree classes used in the implementation of the standard maps and + sets. + </p><p>Each of the associative containers map, multimap, set, and multiset + have a counterpart which uses a + <a class="link" href="http://www.sgi.com/tech/stl/HashFunction.html">hashing + function</a> to do the arranging, instead of a strict weak ordering + function. The classes take as one of their template parameters a + function object that will return the hash value; by default, an + instantiation of + <a class="link" href="http://www.sgi.com/tech/stl/hash.html">hash</a>. + You should specialize this functor for your class, or define your own, + before trying to use one of the hashing classes. + </p><p>The hashing classes support all the usual associative container + functions, as well as some extra constructors specifying the number + of buckets, etc. + </p><p>Why would you want to use a hashing class instead of the + <span class="quote">“<span class="quote">normal</span>”</span>implementations? Matt Austern writes: + </p><div class="blockquote"><blockquote class="blockquote"><p> + <span class="emphasis"><em>[W]ith a well chosen hash function, hash tables + generally provide much better average-case performance than + binary search trees, and much worse worst-case performance. So + if your implementation has hash_map, if you don't mind using + nonstandard components, and if you aren't scared about the + possibility of pathological cases, you'll probably get better + performance from hash_map. + </em></span> + </p></blockquote></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="bk01pt03ch21s02.html">Prev</a> </td><td align="center"><a accesskey="u" href="ext_containers.html">Up</a></td><td align="right"> <a accesskey="n" href="ext_utilities.html">Next</a></td></tr><tr><td align="left" valign="top">HP/SGI </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Chapter 22. Utilities</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch28s02.html b/libstdc++-v3/doc/html/manual/bk01pt03ch28s02.html new file mode 100644 index 000000000..4350e20b1 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch28s02.html @@ -0,0 +1,41 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Implementation</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="ext_concurrency.html" title="Chapter 28. Concurrency"/><link rel="prev" href="ext_concurrency.html" title="Chapter 28. Concurrency"/><link rel="next" href="bk01pt03ch28s03.html" title="Use"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Implementation</th></tr><tr><td align="left"><a accesskey="p" href="ext_concurrency.html">Prev</a> </td><th width="60%" align="center">Chapter 28. Concurrency</th><td align="right"> <a accesskey="n" href="bk01pt03ch28s03.html">Next</a></td></tr></table><hr/></div><div class="section" title="Implementation"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.concurrency.impl"/>Implementation</h2></div></div></div><div class="section" title="Using Builtin Atomic Functions"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.concurrency.impl.atomic_fallbacks"/>Using Builtin Atomic Functions</h3></div></div></div><p>The functions for atomic operations described above are either +implemented via compiler intrinsics (if the underlying host is +capable) or by library fallbacks.</p><p>Compiler intrinsics (builtins) are always preferred. However, as +the compiler builtins for atomics are not universally implemented, +using them directly is problematic, and can result in undefined +function calls. (An example of an undefined symbol from the use +of <code class="code">__sync_fetch_and_add</code> on an unsupported host is a +missing reference to <code class="code">__sync_fetch_and_add_4</code>.) +</p><p>In addition, on some hosts the compiler intrinsics are enabled +conditionally, via the <code class="code">-march</code> command line flag. This makes +usage vary depending on the target hardware and the flags used during +compile. +</p><p> +If builtins are possible for bool-sized integral types, +<code class="code">_GLIBCXX_ATOMIC_BUILTINS_1</code> will be defined. +If builtins are possible for int-sized integral types, +<code class="code">_GLIBCXX_ATOMIC_BUILTINS_4</code> will be defined. +</p><p>For the following hosts, intrinsics are enabled by default. +</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>alpha</p></li><li class="listitem"><p>ia64</p></li><li class="listitem"><p>powerpc</p></li><li class="listitem"><p>s390</p></li></ul></div><p>For others, some form of <code class="code">-march</code> may work. On +non-ancient x86 hardware, <code class="code">-march=native</code> usually does the +trick.</p><p> For hosts without compiler intrinsics, but with capable +hardware, hand-crafted assembly is selected. This is the case for the following hosts: +</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>cris</p></li><li class="listitem"><p>hppa</p></li><li class="listitem"><p>i386</p></li><li class="listitem"><p>i486</p></li><li class="listitem"><p>m48k</p></li><li class="listitem"><p>mips</p></li><li class="listitem"><p>sparc</p></li></ul></div><p>And for the rest, a simulated atomic lock via pthreads. +</p><p> Detailed information about compiler intrinsics for atomic operations can be found in the GCC <a class="link" href="http://gcc.gnu.org/onlinedocs/gcc/Atomic-Builtins.html"> documentation</a>. +</p><p> More details on the library fallbacks from the porting <a class="link" href="internals.html#internals.thread_safety" title="Thread Safety">section</a>. +</p></div><div class="section" title="Thread Abstraction"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.concurrency.impl.thread"/>Thread Abstraction</h3></div></div></div><p>A thin layer above IEEE 1003.1 (i.e. pthreads) is used to abstract +the thread interface for GCC. This layer is called "gthread," and is +comprised of one header file that wraps the host's default thread layer with +a POSIX-like interface. +</p><p> The file <gthr-default.h> points to the deduced wrapper for +the current host. In libstdc++ implementation files, +<bits/gthr.h> is used to select the proper gthreads file. +</p><p>Within libstdc++ sources, all calls to underlying thread functionality +use this layer. More detail as to the specific interface can be found in the source <a class="link" href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a00883_source.html">documentation</a>. +</p><p>By design, the gthread layer is interoperable with the types, +functions, and usage found in the usual <pthread.h> file, +including <code class="code">pthread_t</code>, <code class="code">pthread_once_t</code>, <code class="code">pthread_create</code>, +etc. +</p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="ext_concurrency.html">Prev</a> </td><td align="center"><a accesskey="u" href="ext_concurrency.html">Up</a></td><td align="right"> <a accesskey="n" href="bk01pt03ch28s03.html">Next</a></td></tr><tr><td align="left" valign="top">Chapter 28. Concurrency </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Use</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch28s03.html b/libstdc++-v3/doc/html/manual/bk01pt03ch28s03.html new file mode 100644 index 000000000..b70d5a621 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch28s03.html @@ -0,0 +1,36 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Use</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="ext_concurrency.html" title="Chapter 28. Concurrency"/><link rel="prev" href="bk01pt03ch28s02.html" title="Implementation"/><link rel="next" href="bk01pt04.html" title="Part IV. Appendices"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Use</th></tr><tr><td align="left"><a accesskey="p" href="bk01pt03ch28s02.html">Prev</a> </td><th width="60%" align="center">Chapter 28. Concurrency</th><td align="right"> <a accesskey="n" href="bk01pt04.html">Next</a></td></tr></table><hr/></div><div class="section" title="Use"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.concurrency.use"/>Use</h2></div></div></div><p>Typical usage of the last two constructs is demonstrated as follows: +</p><pre class="programlisting"> +#include <ext/concurrence.h> + +namespace +{ + __gnu_cxx::__mutex safe_base_mutex; +} // anonymous namespace + +namespace other +{ + void + foo() + { + __gnu_cxx::__scoped_lock sentry(safe_base_mutex); + for (int i = 0; i < max; ++i) + { + _Safe_iterator_base* __old = __iter; + __iter = __iter-<_M_next; + __old-<_M_detach_single(); + } +} +</pre><p>In this sample code, an anonymous namespace is used to keep +the <code class="code">__mutex</code> private to the compilation unit, +and <code class="code">__scoped_lock</code> is used to guard access to the critical +section within the for loop, locking the mutex on creation and freeing +the mutex as control moves out of this block. +</p><p>Several exception classes are used to keep track of +concurrence-related errors. These classes +are: <code class="code">__concurrence_lock_error</code>, <code class="code">__concurrence_unlock_error</code>, <code class="code">__concurrence_wait_error</code>, +and <code class="code">__concurrence_broadcast_error</code>. +</p></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="bk01pt03ch28s02.html">Prev</a> </td><td align="center"><a accesskey="u" href="ext_concurrency.html">Up</a></td><td align="right"> <a accesskey="n" href="bk01pt04.html">Next</a></td></tr><tr><td align="left" valign="top">Implementation </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Part IV. + Appendices +</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/bk01pt03pr01.html b/libstdc++-v3/doc/html/manual/bk01pt03pr01.html new file mode 100644 index 000000000..65348b721 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bk01pt03pr01.html @@ -0,0 +1,26 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title/><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="extensions.html" title="Part III. Extensions"/><link rel="prev" href="extensions.html" title="Part III. Extensions"/><link rel="next" href="ext_compile_checks.html" title="Chapter 16. Compile Time Checks"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center"/></tr><tr><td align="left"><a accesskey="p" href="extensions.html">Prev</a> </td><th width="60%" align="center">Part III. + Extensions + +</th><td align="right"> <a accesskey="n" href="ext_compile_checks.html">Next</a></td></tr></table><hr/></div><div class="preface"><div class="titlepage"><div><div><h1 class="title"><a id="id481886"/></h1></div></div></div><p> + Here we will make an attempt at describing the non-Standard extensions to + the library. Some of these are from SGI's STL, some of these are GNU's, + and some just seemed to appear on the doorstep. +</p><p><span class="emphasis"><em>Before</em></span> you leap in and use any of these +extensions, be aware of two things: +</p><div class="orderedlist"><ol class="orderedlist"><li class="listitem"><p> + Non-Standard means exactly that. + </p><p> + The behavior, and the very + existence, of these extensions may change with little or no + warning. (Ideally, the really good ones will appear in the next + revision of C++.) Also, other platforms, other compilers, other + versions of g++ or libstdc++ may not recognize these names, or + treat them differently, or... + </p></li><li class="listitem"><p> + You should know how to access these headers properly. + </p></li></ol></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="extensions.html">Prev</a> </td><td align="center"><a accesskey="u" href="extensions.html">Up</a></td><td align="right"> <a accesskey="n" href="ext_compile_checks.html">Next</a></td></tr><tr><td align="left" valign="top">Part III. + Extensions + + </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Chapter 16. Compile Time Checks</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/bk01pt04.html b/libstdc++-v3/doc/html/manual/bk01pt04.html new file mode 100644 index 000000000..acdf72aca --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bk01pt04.html @@ -0,0 +1,21 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Part IV. Appendices</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="spine.html" title="The GNU C++ Library Manual"/><link rel="prev" href="bk01pt03ch28s03.html" title="Use"/><link rel="next" href="appendix_contributing.html" title="Appendix A. Contributing"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Part IV. + Appendices +</th></tr><tr><td align="left"><a accesskey="p" href="bk01pt03ch28s03.html">Prev</a> </td><th width="60%" align="center">The GNU C++ Library Manual</th><td align="right"> <a accesskey="n" href="appendix_contributing.html">Next</a></td></tr></table><hr/></div><div class="part" title="Part IV. Appendices"><div class="titlepage"><div><div><h1 class="title"><a id="appendix"/>Part IV. + Appendices +</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="appendix"><a href="appendix_contributing.html">A. + Contributing + +</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_contributing.html#contrib.list">Contributor Checklist</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_contributing.html#list.reading">Reading</a></span></dt><dt><span class="section"><a href="appendix_contributing.html#list.copyright">Assignment</a></span></dt><dt><span class="section"><a href="appendix_contributing.html#list.getting">Getting Sources</a></span></dt><dt><span class="section"><a href="appendix_contributing.html#list.patches">Submitting Patches</a></span></dt></dl></dd><dt><span class="section"><a href="source_organization.html">Directory Layout and Source Conventions</a></span></dt><dt><span class="section"><a href="source_code_style.html">Coding Style</a></span></dt><dd><dl><dt><span class="section"><a href="source_code_style.html#coding_style.bad_identifiers">Bad Identifiers</a></span></dt><dt><span class="section"><a href="source_code_style.html#coding_style.example">By Example</a></span></dt></dl></dd><dt><span class="section"><a href="source_design_notes.html">Design Notes</a></span></dt></dl></dd><dt><span class="appendix"><a href="appendix_porting.html">B. + Porting and Maintenance + +</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#appendix.porting.build_hacking">Configure and Build Hacking</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#build_hacking.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.map">Overview: What Comes from Where</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.scripts">Storing Information in non-AC files (like configure.host)</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.conventions">Coding and Commenting Conventions</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.acinclude">The acinclude.m4 layout</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.enable"><code class="constant">GLIBCXX_ENABLE</code>, the <code class="literal">--enable</code> maker</a></span></dt></dl></dd><dt><span class="section"><a href="documentation_hacking.html">Writing and Generating Documentation</a></span></dt><dd><dl><dt><span class="section"><a href="documentation_hacking.html#doc.intro">Introduction</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doc.generation">Generating Documentation</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doc.doxygen">Doxygen</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doc.docbook">Docbook</a></span></dt></dl></dd><dt><span class="section"><a href="internals.html">Porting to New Hardware or Operating Systems</a></span></dt><dd><dl><dt><span class="section"><a href="internals.html#internals.os">Operating System</a></span></dt><dt><span class="section"><a href="internals.html#internals.cpu">CPU</a></span></dt><dt><span class="section"><a href="internals.html#internals.char_types">Character Types</a></span></dt><dt><span class="section"><a href="internals.html#internals.thread_safety">Thread Safety</a></span></dt><dt><span class="section"><a href="internals.html#internals.numeric_limits">Numeric Limits</a></span></dt><dt><span class="section"><a href="internals.html#internals.libtool">Libtool</a></span></dt></dl></dd><dt><span class="section"><a href="test.html">Test</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.organization">Organization</a></span></dt><dt><span class="section"><a href="test.html#test.run">Running the Testsuite</a></span></dt><dt><span class="section"><a href="test.html#test.new_tests">Writing a new test case</a></span></dt><dt><span class="section"><a href="test.html#test.harness">Test Harness and Utilities</a></span></dt><dt><span class="section"><a href="test.html#test.special">Special Topics</a></span></dt></dl></dd><dt><span class="section"><a href="abi.html">ABI Policy and Guidelines</a></span></dt><dd><dl><dt><span class="section"><a href="abi.html#abi.cxx_interface">The C++ Interface</a></span></dt><dt><span class="section"><a href="abi.html#abi.versioning">Versioning</a></span></dt><dt><span class="section"><a href="abi.html#abi.changes_allowed">Allowed Changes</a></span></dt><dt><span class="section"><a href="abi.html#abi.changes_no">Prohibited Changes</a></span></dt><dt><span class="section"><a href="abi.html#abi.impl">Implementation</a></span></dt><dt><span class="section"><a href="abi.html#abi.testing">Testing</a></span></dt><dt><span class="section"><a href="abi.html#abi.issues">Outstanding Issues</a></span></dt></dl></dd><dt><span class="section"><a href="api.html">API Evolution and Deprecation History</a></span></dt><dd><dl><dt><span class="section"><a href="api.html#api.rel_300"><code class="constant">3.0</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_310"><code class="constant">3.1</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_320"><code class="constant">3.2</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_330"><code class="constant">3.3</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_340"><code class="constant">3.4</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_400"><code class="constant">4.0</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_410"><code class="constant">4.1</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_420"><code class="constant">4.2</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_430"><code class="constant">4.3</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_440"><code class="constant">4.4</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_450"><code class="constant">4.5</code></a></span></dt></dl></dd><dt><span class="section"><a href="backwards.html">Backwards Compatibility</a></span></dt><dd><dl><dt><span class="section"><a href="backwards.html#backwards.first">First</a></span></dt><dt><span class="section"><a href="backwards.html#backwards.second">Second</a></span></dt><dt><span class="section"><a href="backwards.html#backwards.third">Third</a></span></dt></dl></dd></dl></dd><dt><span class="appendix"><a href="appendix_free.html">C. + Free Software Needs Free Documentation + +</a></span></dt><dt><span class="appendix"><a href="appendix_gpl.html">D. + <acronym class="acronym">GNU</acronym> General Public License version 3 + </a></span></dt><dt><span class="appendix"><a href="appendix_gfdl.html">E. GNU Free Documentation License</a></span></dt></dl></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="bk01pt03ch28s03.html">Prev</a> </td><td align="center"><a accesskey="u" href="spine.html">Up</a></td><td align="right"> <a accesskey="n" href="appendix_contributing.html">Next</a></td></tr><tr><td align="left" valign="top">Use </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Appendix A. + Contributing + +</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/bugs.html b/libstdc++-v3/doc/html/manual/bugs.html new file mode 100644 index 000000000..eb6efdcaf --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bugs.html @@ -0,0 +1,352 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Bugs</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="status.html" title="Chapter 1. Status"/><link rel="prev" href="license.html" title="License"/><link rel="next" href="setup.html" title="Chapter 2. Setup"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Bugs</th></tr><tr><td align="left"><a accesskey="p" href="license.html">Prev</a> </td><th width="60%" align="center">Chapter 1. Status</th><td align="right"> <a accesskey="n" href="setup.html">Next</a></td></tr></table><hr/></div><div class="section" title="Bugs"><div class="titlepage"><div><div><h2 class="title"><a id="manual.intro.status.bugs"/>Bugs</h2></div></div></div><div class="section" title="Implementation Bugs"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.status.bugs.impl"/>Implementation Bugs</h3></div></div></div><p> + Information on known bugs, details on efforts to fix them, and + fixed bugs are all available as part of the <a class="link" href="http://gcc.gnu.org/bugs/">GCC bug tracking system</a>, + with the category set to <code class="literal">libstdc++</code>. + </p></div><div class="section" title="Standard Bugs"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.status.bugs.iso"/>Standard Bugs</h3></div></div></div><p> + Everybody's got issues. Even the C++ Standard Library. + </p><p> + The Library Working Group, or LWG, is the ISO subcommittee responsible + for making changes to the library. They periodically publish an + Issues List containing problems and possible solutions. As they reach + a consensus on proposed solutions, we often incorporate the solution. + </p><p> + Here are the issues which have resulted in code changes to the library. + The links are to the specific defect reports from a <span class="emphasis"><em>partial + copy</em></span> of the Issues List. You can read the full version online + at the <a class="link" href="http://www.open-std.org/jtc1/sc22/wg21/">ISO C++ + Committee homepage</a>, linked to on the + <a class="link" href="http://gcc.gnu.org/readings.html">GCC "Readings" + page</a>. If + you spend a lot of time reading the issues, we recommend downloading + the ZIP file and reading them locally. + </p><p> + (NB: <span class="emphasis"><em>partial copy</em></span> means that not all + links within the lwg-*.html pages will work. Specifically, + links to defect reports that have not been accorded full DR + status will probably break. Rather than trying to mirror the + entire issues list on our overworked web server, we recommend + you go to the LWG homepage instead.) + </p><p> + If a DR is not listed here, we may simply not have gotten to + it yet; feel free to submit a patch. Search the include/bits + and src directories for appearances of + <code class="constant">_GLIBCXX_RESOLVE_LIB_DEFECTS</code> for examples + of style. Note that we usually do not make changes to the + code until an issue has reached <a class="link" href="../ext/lwg-active.html#DR">DR</a> status. + </p><div class="variablelist"><dl><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#5">5</a>: + <span class="emphasis"><em>string::compare specification questionable</em></span> + </span></dt><dd><p>This should be two overloaded functions rather than a single function. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#17">17</a>: + <span class="emphasis"><em>Bad bool parsing</em></span> + </span></dt><dd><p>Apparently extracting Boolean values was messed up... + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#19">19</a>: + <span class="emphasis"><em>"Noconv" definition too vague</em></span> + </span></dt><dd><p>If <code class="code">codecvt::do_in</code> returns <code class="code">noconv</code> there are + no changes to the values in <code class="code">[to, to_limit)</code>. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#22">22</a>: + <span class="emphasis"><em>Member open vs flags</em></span> + </span></dt><dd><p>Re-opening a file stream does <span class="emphasis"><em>not</em></span> clear the state flags. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#23">23</a>: + <span class="emphasis"><em>Num_get overflow result</em></span> + </span></dt><dd><p>Implement the proposed resolution. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#25">25</a>: + <span class="emphasis"><em>String operator<< uses width() value wrong</em></span> + </span></dt><dd><p>Padding issues. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#48">48</a>: + <span class="emphasis"><em>Use of non-existent exception constructor</em></span> + </span></dt><dd><p>An instance of <code class="code">ios_base::failure</code> is constructed instead. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#49">49</a>: + <span class="emphasis"><em>Underspecification of ios_base::sync_with_stdio</em></span> + </span></dt><dd><p>The return type is the <span class="emphasis"><em>previous</em></span> state of synchronization. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#50">50</a>: + <span class="emphasis"><em>Copy constructor and assignment operator of ios_base</em></span> + </span></dt><dd><p>These members functions are declared <code class="code">private</code> and are + thus inaccessible. Specifying the correct semantics of + "copying stream state" was deemed too complicated. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#60">60</a>: + <span class="emphasis"><em>What is a formatted input function?</em></span> + </span></dt><dd><p>This DR made many widespread changes to <code class="code">basic_istream</code> + and <code class="code">basic_ostream</code> all of which have been implemented. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#63">63</a>: + <span class="emphasis"><em>Exception-handling policy for unformatted output</em></span> + </span></dt><dd><p>Make the policy consistent with that of formatted input, unformatted + input, and formatted output. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#68">68</a>: + <span class="emphasis"><em>Extractors for char* should store null at end</em></span> + </span></dt><dd><p>And they do now. An editing glitch in the last item in the list of + [27.6.1.2.3]/7. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#74">74</a>: + <span class="emphasis"><em>Garbled text for codecvt::do_max_length</em></span> + </span></dt><dd><p>The text of the standard was gibberish. Typos gone rampant. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#75">75</a>: + <span class="emphasis"><em>Contradiction in codecvt::length's argument types</em></span> + </span></dt><dd><p>Change the first parameter to <code class="code">stateT&</code> and implement + the new effects paragraph. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#83">83</a>: + <span class="emphasis"><em>string::npos vs. string::max_size()</em></span> + </span></dt><dd><p>Safety checks on the size of the string should test against + <code class="code">max_size()</code> rather than <code class="code">npos</code>. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#90">90</a>: + <span class="emphasis"><em>Incorrect description of operator>> for strings</em></span> + </span></dt><dd><p>The effect contain <code class="code">isspace(c,getloc())</code> which must be + replaced by <code class="code">isspace(c,is.getloc())</code>. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#91">91</a>: + <span class="emphasis"><em>Description of operator>> and getline() for string<> + might cause endless loop</em></span> + </span></dt><dd><p>They behave as a formatted input function and as an unformatted + input function, respectively (except that <code class="code">getline</code> is + not required to set <code class="code">gcount</code>). + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#103">103</a>: + <span class="emphasis"><em>set::iterator is required to be modifiable, but this allows + modification of keys.</em></span> + </span></dt><dd><p>For associative containers where the value type is the same as + the key type, both <code class="code">iterator</code> and <code class="code">const_iterator + </code> are constant iterators. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#109">109</a>: + <span class="emphasis"><em>Missing binders for non-const sequence elements</em></span> + </span></dt><dd><p>The <code class="code">binder1st</code> and <code class="code">binder2nd</code> didn't have an + <code class="code">operator()</code> taking a non-const parameter. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#110">110</a>: + <span class="emphasis"><em>istreambuf_iterator::equal not const</em></span> + </span></dt><dd><p>This was not a const member function. Note that the DR says to + replace the function with a const one; we have instead provided an + overloaded version with identical contents. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#117">117</a>: + <span class="emphasis"><em>basic_ostream uses nonexistent num_put member functions</em></span> + </span></dt><dd><p><code class="code">num_put::put()</code> was overloaded on the wrong types. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#118">118</a>: + <span class="emphasis"><em>basic_istream uses nonexistent num_get member functions</em></span> + </span></dt><dd><p>Same as 117, but for <code class="code">num_get::get()</code>. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#129">129</a>: + <span class="emphasis"><em>Need error indication from seekp() and seekg()</em></span> + </span></dt><dd><p>These functions set <code class="code">failbit</code> on error now. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#130">130</a>: + <span class="emphasis"><em>Return type of container::erase(iterator) differs for associative containers</em></span> + </span></dt><dd><p>Make member <code class="code">erase</code> return iterator for <code class="code">set</code>, <code class="code">multiset</code>, <code class="code">map</code>, <code class="code">multimap</code>. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#136">136</a>: + <span class="emphasis"><em>seekp, seekg setting wrong streams?</em></span> + </span></dt><dd><p><code class="code">seekp</code> should only set the output stream, and + <code class="code">seekg</code> should only set the input stream. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#167">167</a>: + <span class="emphasis"><em>Improper use of traits_type::length()</em></span> + </span></dt><dd><p><code class="code">op<<</code> with a <code class="code">const char*</code> was + calculating an incorrect number of characters to write. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#169">169</a>: + <span class="emphasis"><em>Bad efficiency of overflow() mandated</em></span> + </span></dt><dd><p>Grow efficiently the internal array object. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#171">171</a>: + <span class="emphasis"><em>Strange seekpos() semantics due to joint position</em></span> + </span></dt><dd><p>Quite complex to summarize... + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#181">181</a>: + <span class="emphasis"><em>make_pair() unintended behavior</em></span> + </span></dt><dd><p>This function used to take its arguments as reference-to-const, now + it copies them (pass by value). + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#195">195</a>: + <span class="emphasis"><em>Should basic_istream::sentry's constructor ever set eofbit?</em></span> + </span></dt><dd><p>Yes, it can, specifically if EOF is reached while skipping whitespace. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#211">211</a>: + <span class="emphasis"><em>operator>>(istream&, string&) doesn't set failbit</em></span> + </span></dt><dd><p>If nothing is extracted into the string, <code class="code">op>></code> now + sets <code class="code">failbit</code> (which can cause an exception, etc., etc.). + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#214">214</a>: + <span class="emphasis"><em>set::find() missing const overload</em></span> + </span></dt><dd><p>Both <code class="code">set</code> and <code class="code">multiset</code> were missing + overloaded find, lower_bound, upper_bound, and equal_range functions + for const instances. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#231">231</a>: + <span class="emphasis"><em>Precision in iostream?</em></span> + </span></dt><dd><p>For conversion from a floating-point type, <code class="code">str.precision()</code> + is specified in the conversion specification. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#233">233</a>: + <span class="emphasis"><em>Insertion hints in associative containers</em></span> + </span></dt><dd><p>Implement N1780, first check before then check after, insert as close + to hint as possible. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#235">235</a>: + <span class="emphasis"><em>No specification of default ctor for reverse_iterator</em></span> + </span></dt><dd><p>The declaration of <code class="code">reverse_iterator</code> lists a default constructor. + However, no specification is given what this constructor should do. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#241">241</a>: + <span class="emphasis"><em>Does unique_copy() require CopyConstructible and Assignable?</em></span> + </span></dt><dd><p>Add a helper for forward_iterator/output_iterator, fix the existing + one for input_iterator/output_iterator to not rely on Assignability. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#243">243</a>: + <span class="emphasis"><em>get and getline when sentry reports failure</em></span> + </span></dt><dd><p>Store a null character only if the character array has a non-zero size. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#251">251</a>: + <span class="emphasis"><em>basic_stringbuf missing allocator_type</em></span> + </span></dt><dd><p>This nested typedef was originally not specified. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#253">253</a>: + <span class="emphasis"><em>valarray helper functions are almost entirely useless</em></span> + </span></dt><dd><p>Make the copy constructor and copy-assignment operator declarations + public in gslice_array, indirect_array, mask_array, slice_array; provide + definitions. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#265">265</a>: + <span class="emphasis"><em>std::pair::pair() effects overly restrictive</em></span> + </span></dt><dd><p>The default ctor would build its members from copies of temporaries; + now it simply uses their respective default ctors. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#266">266</a>: + <span class="emphasis"><em>bad_exception::~bad_exception() missing Effects clause</em></span> + </span></dt><dd><p>The <code class="code">bad_</code>* classes no longer have destructors (they + are trivial), since no description of them was ever given. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#271">271</a>: + <span class="emphasis"><em>basic_iostream missing typedefs</em></span> + </span></dt><dd><p>The typedefs it inherits from its base classes can't be used, since + (for example) <code class="code">basic_iostream<T>::traits_type</code> is ambiguous. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#275">275</a>: + <span class="emphasis"><em>Wrong type in num_get::get() overloads</em></span> + </span></dt><dd><p>Similar to 118. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#280">280</a>: + <span class="emphasis"><em>Comparison of reverse_iterator to const reverse_iterator</em></span> + </span></dt><dd><p>Add global functions with two template parameters. + (NB: not added for now a templated assignment operator) + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#292">292</a>: + <span class="emphasis"><em>Effects of a.copyfmt (a)</em></span> + </span></dt><dd><p>If <code class="code">(this == &rhs)</code> do nothing. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#300">300</a>: + <span class="emphasis"><em>List::merge() specification incomplete</em></span> + </span></dt><dd><p>If <code class="code">(this == &x)</code> do nothing. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#303">303</a>: + <span class="emphasis"><em>Bitset input operator underspecified</em></span> + </span></dt><dd><p>Basically, compare the input character to + <code class="code">is.widen(0)</code> and <code class="code">is.widen(1)</code>. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#305">305</a>: + <span class="emphasis"><em>Default behavior of codecvt<wchar_t, char, + mbstate_t>::length()</em></span> + </span></dt><dd><p>Do not specify what <code class="code">codecvt<wchar_t, char, + mbstate_t>::do_length</code> must return. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#328">328</a>: + <span class="emphasis"><em>Bad sprintf format modifier in + money_put<>::do_put()</em></span> + </span></dt><dd><p>Change the format string to "%.0Lf". + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#365">365</a>: + <span class="emphasis"><em>Lack of const-qualification in clause 27</em></span> + </span></dt><dd><p>Add const overloads of <code class="code">is_open</code>. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#387">387</a>: + <span class="emphasis"><em>std::complex over-encapsulated</em></span> + </span></dt><dd><p>Add the <code class="code">real(T)</code> and <code class="code">imag(T)</code> + members; in C++0x mode, also adjust the existing + <code class="code">real()</code> and <code class="code">imag()</code> members and + free functions. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#389">389</a>: + <span class="emphasis"><em>Const overload of valarray::operator[] returns + by value</em></span> + </span></dt><dd><p>Change it to return a <code class="code">const T&</code>. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#396">396</a>: + <span class="emphasis"><em>what are characters zero and one</em></span> + </span></dt><dd><p>Implement the proposed resolution. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#402">402</a>: + <span class="emphasis"><em>Wrong new expression in [some_]allocator::construct</em></span> + </span></dt><dd><p>Replace "new" with "::new". + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-closed.html#408">408</a>: + <span class="emphasis"><em> + Is vector<reverse_iterator<char*> > forbidden? + </em></span> + </span></dt><dd><p>Tweak the debug-mode checks in _Safe_iterator. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#409">409</a>: + <span class="emphasis"><em>Closing an fstream should clear the error state</em></span> + </span></dt><dd><p>Have <code class="code">open</code> clear the error flags. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-closed.html#431">431</a>: + <span class="emphasis"><em>Swapping containers with unequal allocators</em></span> + </span></dt><dd><p>Implement Option 3, as per N1599. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#432">432</a>: + <span class="emphasis"><em>stringbuf::overflow() makes only one write position + available</em></span> + </span></dt><dd><p>Implement the resolution, beyond DR 169. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#434">434</a>: + <span class="emphasis"><em>bitset::to_string() hard to use</em></span> + </span></dt><dd><p>Add three overloads, taking fewer template arguments. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#438">438</a>: + <span class="emphasis"><em>Ambiguity in the "do the right thing" clause</em></span> + </span></dt><dd><p>Implement the resolution, basically cast less. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#453">453</a>: + <span class="emphasis"><em>basic_stringbuf::seekoff need not always fail for an empty stream</em></span> + </span></dt><dd><p>Don't fail if the next pointer is null and newoff is zero. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#455">455</a>: + <span class="emphasis"><em>cerr::tie() and wcerr::tie() are overspecified</em></span> + </span></dt><dd><p>Initialize cerr tied to cout and wcerr tied to wcout. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#464">464</a>: + <span class="emphasis"><em>Suggestion for new member functions in standard containers</em></span> + </span></dt><dd><p>Add <code class="code">data()</code> to <code class="code">std::vector</code> and + <code class="code">at(const key_type&)</code> to <code class="code">std::map</code>. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#508">508</a>: + <span class="emphasis"><em>Bad parameters for ranlux64_base_01</em></span> + </span></dt><dd><p>Fix the parameters. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-closed.html#512">512</a>: + <span class="emphasis"><em>Seeding subtract_with_carry_01 from a single unsigned long</em></span> + </span></dt><dd><p>Construct a <code class="code">linear_congruential</code> engine and seed with it. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-closed.html#526">526</a>: + <span class="emphasis"><em>Is it undefined if a function in the standard changes in + parameters?</em></span> + </span></dt><dd><p>Use &value. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#538">538</a>: + <span class="emphasis"><em>241 again: Does unique_copy() require CopyConstructible + and Assignable?</em></span> + </span></dt><dd><p>In case of input_iterator/output_iterator rely on Assignability of + input_iterator' value_type. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#539">539</a>: + <span class="emphasis"><em>partial_sum and adjacent_difference should mention + requirements</em></span> + </span></dt><dd><p>We were almost doing the right thing, just use std::move + in adjacent_difference. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#541">541</a>: + <span class="emphasis"><em>shared_ptr template assignment and void</em></span> + </span></dt><dd><p>Add an auto_ptr<void> specialization. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#543">543</a>: + <span class="emphasis"><em>valarray slice default constructor</em></span> + </span></dt><dd><p>Follow the straightforward proposed resolution. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#550">550</a>: + <span class="emphasis"><em>What should the return type of pow(float,int) be?</em></span> + </span></dt><dd><p>In C++0x mode, remove the pow(float,int), etc., signatures. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#586">586</a>: + <span class="emphasis"><em>string inserter not a formatted function</em></span> + </span></dt><dd><p>Change it to be a formatted output function (i.e. catch exceptions). + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#596">596</a>: + <span class="emphasis"><em>27.8.1.3 Table 112 omits "a+" and "a+b" modes</em></span> + </span></dt><dd><p>Add the missing modes to fopen_mode. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#630">630</a>: + <span class="emphasis"><em>arrays of valarray</em></span> + </span></dt><dd><p>Implement the simple resolution. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#660">660</a>: + <span class="emphasis"><em>Missing bitwise operations</em></span> + </span></dt><dd><p>Add the missing operations. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#691">691</a>: + <span class="emphasis"><em>const_local_iterator cbegin, cend missing from TR1</em></span> + </span></dt><dd><p>In C++0x mode add cbegin(size_type) and cend(size_type) + to the unordered containers. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#693">693</a>: + <span class="emphasis"><em>std::bitset::all() missing</em></span> + </span></dt><dd><p>Add it, consistently with the discussion. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#695">695</a>: + <span class="emphasis"><em>ctype<char>::classic_table() not accessible</em></span> + </span></dt><dd><p>Make the member functions table and classic_table public. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#696">696</a>: + <span class="emphasis"><em>istream::operator>>(int&) broken</em></span> + </span></dt><dd><p>Implement the straightforward resolution. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#761">761</a>: + <span class="emphasis"><em>unordered_map needs an at() member function</em></span> + </span></dt><dd><p>In C++0x mode, add at() and at() const. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#775">775</a>: + <span class="emphasis"><em>Tuple indexing should be unsigned?</em></span> + </span></dt><dd><p>Implement the int -> size_t replacements. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#776">776</a>: + <span class="emphasis"><em>Undescribed assign function of std::array</em></span> + </span></dt><dd><p>In C++0x mode, remove assign, add fill. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#781">781</a>: + <span class="emphasis"><em>std::complex should add missing C99 functions</em></span> + </span></dt><dd><p>In C++0x mode, add std::proj. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#809">809</a>: + <span class="emphasis"><em>std::swap should be overloaded for array types</em></span> + </span></dt><dd><p>Add the overload. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#844">844</a>: + <span class="emphasis"><em>complex pow return type is ambiguous</em></span> + </span></dt><dd><p>In C++0x mode, remove the pow(complex<T>, int) signature. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#853">853</a>: + <span class="emphasis"><em>to_string needs updating with zero and one</em></span> + </span></dt><dd><p>Update / add the signatures. + </p></dd><dt><span class="term"><a class="link" href="../ext/lwg-defects.html#865">865</a>: + <span class="emphasis"><em>More algorithms that throw away information</em></span> + </span></dt><dd><p>The traditional HP / SGI return type and value is blessed + by the resolution of the DR. + </p></dd></dl></div></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="license.html">Prev</a> </td><td align="center"><a accesskey="u" href="status.html">Up</a></td><td align="right"> <a accesskey="n" href="setup.html">Next</a></td></tr><tr><td align="left" valign="top">License </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Chapter 2. Setup</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/concurrency.html b/libstdc++-v3/doc/html/manual/concurrency.html new file mode 100644 index 000000000..bc1b78792 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/concurrency.html @@ -0,0 +1,42 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Chapter 15. Concurrency</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library , mutex , thread , future , condition_variable "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="bk01pt02.html" title="Part II. Standard Contents"/><link rel="prev" href="atomics.html" title="Chapter 14. Atomics"/><link rel="next" href="extensions.html" title="Part III. Extensions"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 15. + Concurrency + +</th></tr><tr><td align="left"><a accesskey="p" href="atomics.html">Prev</a> </td><th width="60%" align="center">Part II. + Standard Contents + </th><td align="right"> <a accesskey="n" href="extensions.html">Next</a></td></tr></table><hr/></div><div class="chapter" title="Chapter 15. Concurrency"><div class="titlepage"><div><div><h2 class="title"><a id="std.concurrency"/>Chapter 15. + Concurrency + <a id="id481702" class="indexterm"/> +</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="concurrency.html#std.concurrency.api">API Reference</a></span></dt></dl></div><p> + Facilities for concurrent operation, and control thereof. +</p><div class="section" title="API Reference"><div class="titlepage"><div><div><h2 class="title"><a id="std.concurrency.api"/>API Reference</h2></div></div></div><p> + All items are declared in one of four standard header files. + </p><p> + In header <code class="filename">mutex</code>, class + template <code class="classname">mutex</code> and variants, + class <code class="classname">once_flag</code>, and class + template <code class="classname">unique_lock</code>. + </p><p> + In header <code class="filename">condition_variable</code>, + classes <code class="classname">condition_variable</code> + and <code class="classname">condition_variable_any</code>. + </p><p> + In header <code class="filename">thread</code>, + class <code class="classname">thread</code> and + namespace <code class="code">this_thread</code>. + </p><p> + In header <code class="filename">future</code>, class + template <code class="classname">future</code> and class + template <code class="classname">shared_future</code>, class + template <code class="classname">promise</code>, + and <code class="classname">packaged_task</code>. + </p><p> + Full API details. + </p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="atomics.html">Prev</a> </td><td align="center"><a accesskey="u" href="bk01pt02.html">Up</a></td><td align="right"> <a accesskey="n" href="extensions.html">Next</a></td></tr><tr><td align="left" valign="top">Chapter 14. + Atomics + + </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Part III. + Extensions + +</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/configure.html b/libstdc++-v3/doc/html/manual/configure.html new file mode 100644 index 000000000..70409d0c4 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/configure.html @@ -0,0 +1,211 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Configure</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , configure , options "/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="setup.html" title="Chapter 2. Setup"/><link rel="prev" href="setup.html" title="Chapter 2. Setup"/><link rel="next" href="make.html" title="Make"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Configure</th></tr><tr><td align="left"><a accesskey="p" href="setup.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Setup</th><td align="right"> <a accesskey="n" href="make.html">Next</a></td></tr></table><hr/></div><div class="section" title="Configure"><div class="titlepage"><div><div><h2 class="title"><a id="manual.intro.setup.configure"/>Configure</h2></div></div></div><p> + When configuring libstdc++, you'll have to configure the entire + <span class="emphasis"><em>gccsrcdir</em></span> directory. Consider using the + toplevel gcc configuration option + <code class="literal">--enable-languages=c++</code>, which saves time by only + building the C++ toolchain. +</p><p> + Here are all of the configure options specific to libstdc++. Keep + in mind that + + <a class="link" href="http://sourceware.org/autobook/autobook/autobook_14.html">they + all have opposite forms as well</a> (enable/disable and + with/without). The defaults are for the <span class="emphasis"><em>current + development sources</em></span>, which may be different than those + for released versions. +</p><p>The canonical way to find out the configure options that are + available for a given set of libstdc++ sources is to go to the + source directory and then type:<span class="command"><strong>./configure --help</strong></span>. +</p><div class="variablelist"><dl><dt><span class="term"><code class="code">--enable-multilib</code>[default]</span></dt><dd><p>This is part of the generic multilib support for building cross + compilers. As such, targets like "powerpc-elf" will have + libstdc++ built many different ways: "-msoft-float" + and not, etc. A different libstdc++ will be built for each of + the different multilib versions. This option is on by default. + </p></dd><dt><span class="term"><code class="code">--enable-sjlj-exceptions</code></span></dt><dd><p>Forces old, set-jump/long-jump exception handling model. If + at all possible, the new, frame unwinding exception handling routines + should be used instead, as they significantly reduce both + runtime memory usage and executable size. This option can + change the library ABI. + </p></dd><dt><span class="term"><code class="code">--enable-version-specific-runtime-libs</code></span></dt><dd><p>Specify that run-time libraries should be installed in the + compiler-specific subdirectory (i.e., + <code class="code">${libdir}/gcc-lib/${target_alias}/${gcc_version}</code>) + instead of <code class="code">${libdir}</code>. This option is useful if you + intend to use several versions of gcc in parallel. In addition, + libstdc++'s include files will be installed in + <code class="code">${libdir}/gcc-lib/${target_alias}/${gcc_version}/include/g++</code>, + unless you also specify + <code class="literal">--with-gxx-include-dir=</code><code class="filename">dirname</code> during configuration. + </p></dd><dt><span class="term"><code class="code">--with-gxx-include-dir=<include-files dir></code></span></dt><dd><p>Adds support for named libstdc++ include directory. For instance, + the following puts all the libstdc++ headers into a directory + called "4.4-20090404" instead of the usual + "c++/(version)". + </p><pre class="programlisting"> + --with-gxx-include-dir=/foo/H-x86-gcc-3-c-gxx-inc/include/4.4-20090404</pre></dd><dt><span class="term"><code class="code">--enable-cstdio</code></span></dt><dd><p>This is an abbreviated form of <code class="code">'--enable-cstdio=stdio'</code> + (described next). + </p></dd><dt><span class="term"><code class="code">--enable-cstdio=OPTION</code></span></dt><dd><p>Select a target-specific I/O package. At the moment, the only + choice is to use 'stdio', a generic "C" abstraction. + The default is 'stdio'. This option can change the library ABI. + </p></dd><dt><span class="term"><code class="code">--enable-clocale</code></span></dt><dd><p>This is an abbreviated form of <code class="code">'--enable-clocale=generic'</code> + (described next). + </p></dd><dt><span class="term"><code class="code">--enable-clocale=OPTION</code></span></dt><dd><p>Select a target-specific underlying locale package. The + choices are 'ieee_1003.1-2001' to specify an X/Open, Standard Unix + (IEEE Std. 1003.1-2001) model based on langinfo/iconv/catgets, + 'gnu' to specify a model based on functionality from the GNU C + library (langinfo/iconv/gettext) (from <a class="link" href="http://sources.redhat.com/glibc/">glibc</a>, the GNU C + library), or 'generic' to use a generic "C" + abstraction which consists of "C" locale info. + </p><p>If not explicitly specified, the configure proccess tries + to guess the most suitable package from the choices above. The + default is 'generic'. On glibc-based systems of sufficient + vintage (2.3 and newer), 'gnu' is automatically selected. This option + can change the library ABI. + </p></dd><dt><span class="term"><code class="code">--enable-libstdcxx-allocator</code></span></dt><dd><p>This is an abbreviated form of + <code class="code">'--enable-libstdcxx-allocator=auto'</code> (described + next). + </p></dd><dt><span class="term"><code class="code">--enable-libstdcxx-allocator=OPTION </code></span></dt><dd><p>Select a target-specific underlying std::allocator. The + choices are 'new' to specify a wrapper for new, 'malloc' to + specify a wrapper for malloc, 'mt' for a fixed power of two allocator, + 'pool' for the SGI pooled allocator or 'bitmap' for a bitmap allocator. + See this page for more information on allocator + <a class="link" href="memory.html#allocator.ext" title="Extension Allocators">extensions</a>. This option + can change the library ABI. + </p></dd><dt><span class="term"><code class="code">--enable-cheaders=OPTION</code></span></dt><dd><p>This allows the user to define the approach taken for C header + compatibility with C++. Options are c, c_std, and c_global. + These correspond to the source directory's include/c, + include/c_std, and include/c_global, and may also include + include/c_compatibility. The default is 'c_global'. + </p></dd><dt><span class="term"><code class="code">--enable-threads</code></span></dt><dd><p>This is an abbreviated form of <code class="code">'--enable-threads=yes'</code> + (described next). + </p></dd><dt><span class="term"><code class="code">--enable-threads=OPTION</code></span></dt><dd><p>Select a threading library. A full description is + given in the + general <a class="link" href="http://gcc.gnu.org/install/configure.html">compiler + configuration instructions</a>. This option can change the + library ABI. + </p></dd><dt><span class="term"><code class="code">--enable-libstdcxx-time</code></span></dt><dd><p>This is an abbreviated form of + <code class="code">'--enable-libstdcxx-time=yes'</code>(described next). + </p></dd><dt><span class="term"><code class="code">--enable-libstdcxx-time=OPTION</code></span></dt><dd><p>Enables link-type checks for the availability of the + clock_gettime clocks, used in the implementation of [time.clock], + and of the nanosleep and sched_yield functions, used in the + implementation of [thread.thread.this] of the current C++0x draft. + The choice OPTION=yes checks for the availability of the facilities + in libc and libposix4. In case of need the latter is also linked + to libstdc++ as part of the build process. OPTION=rt also searches + (and, in case, links) librt. Note that the latter is not always + desirable because, in glibc, for example, in turn it triggers the + linking of libpthread too, which activates locking, a large overhead + for single-thread programs. OPTION=no skips the tests completely. + The default is OPTION=no. + </p></dd><dt><span class="term"><code class="code">--enable-libstdcxx-debug</code></span></dt><dd><p>Build separate debug libraries in addition to what is normally built. + By default, the debug libraries are compiled with + <code class="code"> CXXFLAGS='-g3 -O0 -fno-inline'</code> + , are installed in <code class="code">${libdir}/debug</code>, and have the + same names and versioning information as the non-debug + libraries. This option is off by default. + </p><p>Note this make command, executed in + the build directory, will do much the same thing, without the + configuration difference and without building everything twice: + <code class="code">make CXXFLAGS='-g3 -O0 -fno-inline' all</code> + </p></dd><dt><span class="term"><code class="code">--enable-libstdcxx-debug-flags=FLAGS</code></span></dt><dd><p>This option is only valid when <code class="code"> --enable-debug </code> + is also specified, and applies to the debug builds only. With + this option, you can pass a specific string of flags to the + compiler to use when building the debug versions of libstdc++. + FLAGS is a quoted string of options, like + </p><pre class="programlisting"> + --enable-libstdcxx-debug-flags='-g3 -O1 -fno-inline'</pre></dd><dt><span class="term"><code class="code">--enable-cxx-flags=FLAGS</code></span></dt><dd><p>With this option, you can pass a string of -f (functionality) + flags to the compiler to use when building libstdc++. This + option can change the library ABI. FLAGS is a quoted string of + options, like + </p><pre class="programlisting"> + --enable-cxx-flags='-fvtable-gc -fomit-frame-pointer -ansi'</pre><p> + Note that the flags don't necessarily have to all be -f flags, + as shown, but usually those are the ones that will make sense + for experimentation and configure-time overriding. + </p><p>The advantage of --enable-cxx-flags over setting CXXFLAGS in + the 'make' environment is that, if files are automatically + rebuilt, the same flags will be used when compiling those files + as well, so that everything matches. + </p><p>Fun flags to try might include combinations of + </p><pre class="programlisting"> + -fstrict-aliasing + -fno-exceptions + -ffunction-sections + -fvtable-gc</pre><p>and opposite forms (-fno-) of the same. Tell us (the libstdc++ + mailing list) if you discover more! + </p></dd><dt><span class="term"><code class="code">--enable-c99</code></span></dt><dd><p>The "long long" type was introduced in C99, along + with many other functions for wide characters, and math + classification macros, etc. If enabled, all C99 functions not + specified by the C++ standard will be put into <code class="code">namespace + __gnu_cxx</code>, and then all these names will + be injected into namespace std, so that C99 functions can be + used "as if" they were in the C++ standard (as they + will eventually be in some future revision of the standard, + without a doubt). By default, C99 support is on, assuming the + configure probes find all the necessary functions and bits + necessary. This option can change the library ABI. + </p></dd><dt><span class="term"><code class="code">--enable-wchar_t</code>[default]</span></dt><dd><p>Template specializations for the "wchar_t" type are + required for wide character conversion support. Disabling + wide character specializations may be expedient for initial + porting efforts, but builds only a subset of what is required by + ISO, and is not recommended. By default, this option is on. + This option can change the library ABI. + </p></dd><dt><span class="term"><code class="code">--enable-long-long </code></span></dt><dd><p>The "long long" type was introduced in C99. It is + provided as a GNU extension to C++98 in g++. This flag builds + support for "long long" into the library (specialized + templates and the like for iostreams). This option is on by default: + if enabled, users will have to either use the new-style "C" + headers by default (i.e., <cmath> not <math.h>) + or add appropriate compile-time flags to all compile lines to + allow "C" visibility of this feature (on GNU/Linux, + the flag is -D_ISOC99_SOURCE, which is added automatically via + CPLUSPLUS_CPP_SPEC's addition of _GNU_SOURCE). + This option can change the library ABI. + </p></dd><dt><span class="term"><code class="code">--enable-fully-dynamic-string</code></span></dt><dd><p>This option enables a special version of basic_string avoiding + the optimization that allocates empty objects in static memory. + Mostly useful together with shared memory allocators, see PR + libstdc++/16612 for details. + </p></dd><dt><span class="term"><code class="code">--enable-concept-checks</code></span></dt><dd><p>This turns on additional compile-time checks for instantiated + library templates, in the form of specialized templates, + <a class="link" href="bk01pt02ch05s02.html" title="Concept Checking">described here</a>. They + can help users discover when they break the rules of the STL, before + their programs run. + </p></dd><dt><span class="term"><code class="code">--enable-symvers[=style]</code></span></dt><dd><p>In 3.1 and later, tries to turn on symbol versioning in the + shared library (if a shared library has been + requested). Values for 'style' that are currently supported + are 'gnu', 'gnu-versioned-namespace', 'darwin', + 'darwin-export', and 'sun'. Both gnu- options require that a recent + version of the GNU linker be in use. Both darwin options are + equivalent. With no style given, the configure script will try + to guess correct defaults for the host system, probe to see if + additional requirements are necessary and present for + activation, and if so, will turn symbol versioning on. This + option can change the library ABI. + </p></dd><dt><span class="term"><code class="code">--enable-visibility</code></span></dt><dd><p> In 4.2 and later, enables or disables visibility attributes. + If enabled (as by default), and the compiler seems capable of + passing the simple sanity checks thrown at it, adjusts items + in namespace std, namespace std::tr1, and namespace __gnu_cxx + so that -fvisibility options work. + </p></dd><dt><span class="term"><code class="code">--enable-libstdcxx-pch</code></span></dt><dd><p>In 3.4 and later, tries to turn on the generation of + stdc++.h.gch, a pre-compiled file including all the standard + C++ includes. If enabled (as by default), and the compiler + seems capable of passing the simple sanity checks thrown at + it, try to build stdc++.h.gch as part of the make process. + In addition, this generated file is used later on (by appending <code class="code"> + --include bits/stdc++.h </code> to CXXFLAGS) when running the + testsuite. + </p></dd><dt><span class="term"><code class="code">--enable-extern-template</code>[default]</span></dt><dd><p>Use extern template to pre-instantiate all required + specializations for certain types defined in the standard libraries. + These types include <code class="classname">string</code> and dependents like + <code class="classname">char_traits</code>, the templateized io classes, + <code class="classname">allocator</code>, and others. + Disabling means that implicit + template generation will be used when compiling these types. By + default, this option is on. This option can change the library ABI. + </p></dd><dt><span class="term"><code class="code">--disable-hosted-libstdcxx</code></span></dt><dd><p> + By default, a complete <span class="emphasis"><em>hosted</em></span> C++ library is + built. The C++ Standard also describes a + <span class="emphasis"><em>freestanding</em></span> environment, in which only a + minimal set of headers are provided. This option builds such an + environment. + </p></dd></dl></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="setup.html">Prev</a> </td><td align="center"><a accesskey="u" href="setup.html">Up</a></td><td align="right"> <a accesskey="n" href="make.html">Next</a></td></tr><tr><td align="left" valign="top">Chapter 2. Setup </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Make</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/containers.html b/libstdc++-v3/doc/html/manual/containers.html new file mode 100644 index 000000000..1185af6a1 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/containers.html @@ -0,0 +1,55 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Chapter 9. Containers</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="bk01pt02.html" title="Part II. Standard Contents"/><link rel="prev" href="facets.html" title="Facets"/><link rel="next" href="associative.html" title="Associative"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 9. + Containers + +</th></tr><tr><td align="left"><a accesskey="p" href="facets.html">Prev</a> </td><th width="60%" align="center">Part II. + Standard Contents + </th><td align="right"> <a accesskey="n" href="associative.html">Next</a></td></tr></table><hr/></div><div class="chapter" title="Chapter 9. Containers"><div class="titlepage"><div><div><h2 class="title"><a id="std.containers"/>Chapter 9. + Containers + <a id="id478750" class="indexterm"/> +</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="containers.html#std.containers.sequences">Sequences</a></span></dt><dd><dl><dt><span class="section"><a href="containers.html#containers.sequences.list">list</a></span></dt><dt><span class="section"><a href="containers.html#containers.sequences.vector">vector</a></span></dt></dl></dd><dt><span class="section"><a href="associative.html">Associative</a></span></dt><dd><dl><dt><span class="section"><a href="associative.html#containers.associative.insert_hints">Insertion Hints</a></span></dt><dt><span class="section"><a href="associative.html#containers.associative.bitset">bitset</a></span></dt></dl></dd><dt><span class="section"><a href="containers_and_c.html">Interacting with C</a></span></dt><dd><dl><dt><span class="section"><a href="containers_and_c.html#containers.c.vs_array">Containers vs. Arrays</a></span></dt></dl></dd></dl></div><div class="section" title="Sequences"><div class="titlepage"><div><div><h2 class="title"><a id="std.containers.sequences"/>Sequences</h2></div></div></div><div class="section" title="list"><div class="titlepage"><div><div><h3 class="title"><a id="containers.sequences.list"/>list</h3></div></div></div><div class="section" title="list::size() is O(n)"><div class="titlepage"><div><div><h4 class="title"><a id="sequences.list.size"/>list::size() is O(n)</h4></div></div></div><p> + Yes it is, and that's okay. This is a decision that we preserved + when we imported SGI's STL implementation. The following is + quoted from <a class="link" href="http://www.sgi.com/tech/stl/FAQ.html">their FAQ</a>: + </p><div class="blockquote"><blockquote class="blockquote"><p> + The size() member function, for list and slist, takes time + proportional to the number of elements in the list. This was a + deliberate tradeoff. The only way to get a constant-time + size() for linked lists would be to maintain an extra member + variable containing the list's size. This would require taking + extra time to update that variable (it would make splice() a + linear time operation, for example), and it would also make the + list larger. Many list algorithms don't require that extra + word (algorithms that do require it might do better with + vectors than with lists), and, when it is necessary to maintain + an explicit size count, it's something that users can do + themselves. + </p><p> + This choice is permitted by the C++ standard. The standard says + that size() <span class="quote">“<span class="quote">should</span>”</span> be constant time, and + <span class="quote">“<span class="quote">should</span>”</span> does not mean the same thing as + <span class="quote">“<span class="quote">shall</span>”</span>. This is the officially recommended ISO + wording for saying that an implementation is supposed to do + something unless there is a good reason not to. + </p><p> + One implication of linear time size(): you should never write + </p><pre class="programlisting"> + if (L.size() == 0) + ... + </pre><p> + Instead, you should write + </p><pre class="programlisting"> + if (L.empty()) + ... + </pre></blockquote></div></div></div><div class="section" title="vector"><div class="titlepage"><div><div><h3 class="title"><a id="containers.sequences.vector"/>vector</h3></div></div></div><p> + </p><div class="section" title="Space Overhead Management"><div class="titlepage"><div><div><h4 class="title"><a id="sequences.vector.management"/>Space Overhead Management</h4></div></div></div><p> + In <a class="link" href="http://gcc.gnu.org/ml/libstdc++/2002-04/msg00105.html">this + message to the list</a>, Daniel Kostecky announced work on an + alternate form of <code class="code">std::vector</code> that would support + hints on the number of elements to be over-allocated. The design + was also described, along with possible implementation choices. + </p><p> + The first two alpha releases were announced <a class="link" href="http://gcc.gnu.org/ml/libstdc++/2002-07/msg00048.html">here</a> + and <a class="link" href="http://gcc.gnu.org/ml/libstdc++/2002-07/msg00111.html">here</a>. + </p></div></div></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="facets.html">Prev</a> </td><td align="center"><a accesskey="u" href="bk01pt02.html">Up</a></td><td align="right"> <a accesskey="n" href="associative.html">Next</a></td></tr><tr><td align="left" valign="top">Facets </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Associative</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/containers_and_c.html b/libstdc++-v3/doc/html/manual/containers_and_c.html new file mode 100644 index 000000000..3e612aa5a --- /dev/null +++ b/libstdc++-v3/doc/html/manual/containers_and_c.html @@ -0,0 +1,90 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Interacting with C</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="containers.html" title="Chapter 9. Containers"/><link rel="prev" href="associative.html" title="Associative"/><link rel="next" href="iterators.html" title="Chapter 10. Iterators"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Interacting with C</th></tr><tr><td align="left"><a accesskey="p" href="associative.html">Prev</a> </td><th width="60%" align="center">Chapter 9. + Containers + +</th><td align="right"> <a accesskey="n" href="iterators.html">Next</a></td></tr></table><hr/></div><div class="section" title="Interacting with C"><div class="titlepage"><div><div><h2 class="title"><a id="std.containers.c"/>Interacting with C</h2></div></div></div><div class="section" title="Containers vs. Arrays"><div class="titlepage"><div><div><h3 class="title"><a id="containers.c.vs_array"/>Containers vs. Arrays</h3></div></div></div><p> + You're writing some code and can't decide whether to use builtin + arrays or some kind of container. There are compelling reasons + to use one of the container classes, but you're afraid that + you'll eventually run into difficulties, change everything back + to arrays, and then have to change all the code that uses those + data types to keep up with the change. + </p><p> + If your code makes use of the standard algorithms, this isn't as + scary as it sounds. The algorithms don't know, nor care, about + the kind of <span class="quote">“<span class="quote">container</span>”</span> on which they work, since + the algorithms are only given endpoints to work with. For the + container classes, these are iterators (usually + <code class="code">begin()</code> and <code class="code">end()</code>, but not always). + For builtin arrays, these are the address of the first element + and the <a class="link" href="iterators.html#iterators.predefined.end" title="One Past the End">past-the-end</a> element. + </p><p> + Some very simple wrapper functions can hide all of that from the + rest of the code. For example, a pair of functions called + <code class="code">beginof</code> can be written, one that takes an array, + another that takes a vector. The first returns a pointer to the + first element, and the second returns the vector's + <code class="code">begin()</code> iterator. + </p><p> + The functions should be made template functions, and should also + be declared inline. As pointed out in the comments in the code + below, this can lead to <code class="code">beginof</code> being optimized out + of existence, so you pay absolutely nothing in terms of increased + code size or execution time. + </p><p> + The result is that if all your algorithm calls look like + </p><pre class="programlisting"> + std::transform(beginof(foo), endof(foo), beginof(foo), SomeFunction); + </pre><p> + then the type of foo can change from an array of ints to a vector + of ints to a deque of ints and back again, without ever changing + any client code. + </p><pre class="programlisting"> +// beginof +template<typename T> + inline typename vector<T>::iterator + beginof(vector<T> &v) + { return v.begin(); } + +template<typename T, unsigned int sz> + inline T* + beginof(T (&array)[sz]) { return array; } + +// endof +template<typename T> + inline typename vector<T>::iterator + endof(vector<T> &v) + { return v.end(); } + +template<typename T, unsigned int sz> + inline T* + endof(T (&array)[sz]) { return array + sz; } + +// lengthof +template<typename T> + inline typename vector<T>::size_type + lengthof(vector<T> &v) + { return v.size(); } + +template<typename T, unsigned int sz> + inline unsigned int + lengthof(T (&)[sz]) { return sz; } +</pre><p> + Astute readers will notice two things at once: first, that the + container class is still a <code class="code">vector<T></code> instead + of a more general <code class="code">Container<T></code>. This would + mean that three functions for <code class="code">deque</code> would have to be + added, another three for <code class="code">list</code>, and so on. This is + due to problems with getting template resolution correct; I find + it easier just to give the extra three lines and avoid confusion. + </p><p> + Second, the line + </p><pre class="programlisting"> + inline unsigned int lengthof (T (&)[sz]) { return sz; } + </pre><p> + looks just weird! Hint: unused parameters can be left nameless. + </p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="associative.html">Prev</a> </td><td align="center"><a accesskey="u" href="containers.html">Up</a></td><td align="right"> <a accesskey="n" href="iterators.html">Next</a></td></tr><tr><td align="left" valign="top">Associative </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Chapter 10. + Iterators + +</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/debug.html b/libstdc++-v3/doc/html/manual/debug.html new file mode 100644 index 000000000..55b5abf76 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/debug.html @@ -0,0 +1,231 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Debugging Support</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" C++ , debug "/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="using.html" title="Chapter 3. Using"/><link rel="prev" href="using_exceptions.html" title="Exceptions"/><link rel="next" href="bk01pt02.html" title="Part II. Standard Contents"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Debugging Support</th></tr><tr><td align="left"><a accesskey="p" href="using_exceptions.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td align="right"> <a accesskey="n" href="bk01pt02.html">Next</a></td></tr></table><hr/></div><div class="section" title="Debugging Support"><div class="titlepage"><div><div><h2 class="title"><a id="manual.intro.using.debug"/>Debugging Support</h2></div></div></div><p> + There are numerous things that can be done to improve the ease with + which C++ binaries are debugged when using the GNU tool chain. Here + are some of them. +</p><div class="section" title="Using g++"><div class="titlepage"><div><div><h3 class="title"><a id="debug.compiler"/>Using <span class="command"><strong>g++</strong></span></h3></div></div></div><p> + Compiler flags determine how debug information is transmitted + between compilation and debug or analysis tools. + </p><p> + The default optimizations and debug flags for a libstdc++ build + are <code class="code">-g -O2</code>. However, both debug and optimization + flags can be varied to change debugging characteristics. For + instance, turning off all optimization via the <code class="code">-g -O0 + -fno-inline</code> flags will disable inlining and optimizations, + and add debugging information, so that stepping through all functions, + (including inlined constructors and destructors) is possible. In + addition, <code class="code">-fno-eliminate-unused-debug-types</code> can be + used when additional debug information, such as nested class info, + is desired. +</p><p> + Or, the debug format that the compiler and debugger use to + communicate information about source constructs can be changed via + <code class="code">-gdwarf-2</code> or <code class="code">-gstabs</code> flags: some debugging + formats permit more expressive type and scope information to be + shown in GDB. Expressiveness can be enhanced by flags like + <code class="code">-g3</code>. The default debug information for a particular + platform can be identified via the value set by the + PREFERRED_DEBUGGING_TYPE macro in the gcc sources. +</p><p> + Many other options are available: please see <a class="link" href="http://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html#Debugging%20Options">"Options + for Debugging Your Program"</a> in Using the GNU Compiler + Collection (GCC) for a complete list. +</p></div><div class="section" title="Debug Versions of Library Binary Files"><div class="titlepage"><div><div><h3 class="title"><a id="debug.req"/>Debug Versions of Library Binary Files</h3></div></div></div><p> + If you would like debug symbols in libstdc++, there are two ways to + build libstdc++ with debug flags. The first is to run make from the + toplevel in a freshly-configured tree with +</p><pre class="programlisting"> + --enable-libstdcxx-debug +</pre><p>and perhaps</p><pre class="programlisting"> + --enable-libstdcxx-debug-flags='...' +</pre><p> + to create a separate debug build. Both the normal build and the + debug build will persist, without having to specify + <code class="code">CXXFLAGS</code>, and the debug library will be installed in a + separate directory tree, in <code class="code">(prefix)/lib/debug</code>. For + more information, look at the <a class="link" href="configure.html" title="Configure">configuration</a> section. +</p><p> + A second approach is to use the configuration flags +</p><pre class="programlisting"> + make CXXFLAGS='-g3 -fno-inline -O0' all +</pre><p> + This quick and dirty approach is often sufficient for quick + debugging tasks, when you cannot or don't want to recompile your + application to use the <a class="link" href="debug_mode.html" title="Chapter 17. Debug Mode">debug mode</a>.</p></div><div class="section" title="Memory Leak Hunting"><div class="titlepage"><div><div><h3 class="title"><a id="debug.memory"/>Memory Leak Hunting</h3></div></div></div><p> + There are various third party memory tracing and debug utilities + that can be used to provide detailed memory allocation information + about C++ code. An exhaustive list of tools is not going to be + attempted, but includes <code class="code">mtrace</code>, <code class="code">valgrind</code>, + <code class="code">mudflap</code>, and the non-free commercial product + <code class="code">purify</code>. In addition, <code class="code">libcwd</code> has a + replacement for the global new and delete operators that can track + memory allocation and deallocation and provide useful memory + statistics. +</p><p> + Regardless of the memory debugging tool being used, there is one + thing of great importance to keep in mind when debugging C++ code + that uses <code class="code">new</code> and <code class="code">delete</code>: there are + different kinds of allocation schemes that can be used by <code class="code"> + std::allocator </code>. For implementation details, see the <a class="link" href="ext_allocators.html#manual.ext.allocator.mt" title="mt_allocator">mt allocator</a> documentation and + look specifically for <code class="code">GLIBCXX_FORCE_NEW</code>. +</p><p> + In a nutshell, the default allocator used by <code class="code"> + std::allocator</code> is a high-performance pool allocator, and can + give the mistaken impression that in a suspect executable, memory is + being leaked, when in reality the memory "leak" is a pool being used + by the library's allocator and is reclaimed after program + termination. +</p><p> + For valgrind, there are some specific items to keep in mind. First + of all, use a version of valgrind that will work with current GNU + C++ tools: the first that can do this is valgrind 1.0.4, but later + versions should work at least as well. Second of all, use a + completely unoptimized build to avoid confusing valgrind. Third, use + GLIBCXX_FORCE_NEW to keep extraneous pool allocation noise from + cluttering debug information. +</p><p> + Fourth, it may be necessary to force deallocation in other libraries + as well, namely the "C" library. On linux, this can be accomplished + with the appropriate use of the <code class="code">__cxa_atexit</code> or + <code class="code">atexit</code> functions. +</p><pre class="programlisting"> + #include <cstdlib> + + extern "C" void __libc_freeres(void); + + void do_something() { } + + int main() + { + atexit(__libc_freeres); + do_something(); + return 0; + } +</pre><p>or, using <code class="code">__cxa_atexit</code>:</p><pre class="programlisting"> + extern "C" void __libc_freeres(void); + extern "C" int __cxa_atexit(void (*func) (void *), void *arg, void *d); + + void do_something() { } + + int main() + { + extern void* __dso_handle __attribute__ ((__weak__)); + __cxa_atexit((void (*) (void *)) __libc_freeres, NULL, + &__dso_handle ? __dso_handle : NULL); + do_test(); + return 0; + } +</pre><p> + Suggested valgrind flags, given the suggestions above about setting + up the runtime environment, library, and test file, might be: +</p><pre class="programlisting"> + valgrind -v --num-callers=20 --leak-check=yes --leak-resolution=high --show-reachable=yes a.out +</pre></div><div class="section" title="Data Race Hunting"><div class="titlepage"><div><div><h3 class="title"><a id="debug.races"/>Data Race Hunting</h3></div></div></div><p> + All synchronization primitives used in the library internals need to be + understood by race detectors so that they do not produce false reports. +</p><p> + Two annotation macros are used to explain low-level synchronization + to race detectors: + <code class="code">_GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE()</code> and + <code class="code"> _GLIBCXX_SYNCHRONIZATION_HAPPENS_AFTER()</code>. + By default, these macros are defined empty -- anyone who wants + to use a race detector needs to redefine them to call an + appropriate API. + Since these macros are empty by default when the library is built, + redefining them will only affect inline functions and template + instantiations which are compiled in user code. This allows annotation + of templates such as <code class="code">shared_ptr</code>, but not code which is + only instantiated in the library. + In order to annotate <code class="code">basic_string</code> reference counting it + is necessary to disable extern templates (by defining + <code class="code">_GLIBCXX_EXTERN_TEMPLATE=-1</code>) or to rebuild the + <code class="code">.so</code> file. + Annotating the remaining atomic operations (at the time of writing these + are in <code class="code">ios_base::Init::~Init</code>, <code class="code">locale::_Impl</code> and + <code class="code">locale::facet</code>) requires rebuilding the <code class="code">.so</code> file. +</p><p> + The approach described above is known to work with the following race + detection tools: + <a class="link" href="http://valgrind.org/docs/manual/drd-manual.html"> + DRD</a>, + <a class="link" href="http://valgrind.org/docs/manual/hg-manual.html"> + Helgrind</a>, and + <a class="link" href="http://code.google.com/p/data-race-test"> + ThreadSanitizer</a>. +</p><p> + With DRD, Helgrind and ThreadSanitizer you will need to define + the macros like this: +</p><pre class="programlisting"> + #define _GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE(A) ANNOTATE_HAPPENS_BEFORE(A) + #define _GLIBCXX_SYNCHRONIZATION_HAPPENS_AFTER(A) ANNOTATE_HAPPENS_AFTER(A) +</pre><p> + Refer to the documentation of each particular tool for details. +</p></div><div class="section" title="Using gdb"><div class="titlepage"><div><div><h3 class="title"><a id="debug.gdb"/>Using <span class="command"><strong>gdb</strong></span></h3></div></div></div><p> + </p><p> + Many options are available for GDB itself: please see <a class="link" href="http://sources.redhat.com/gdb/current/onlinedocs/gdb/"> + "GDB features for C++" </a> in the GDB documentation. Also + recommended: the other parts of this manual. +</p><p> + These settings can either be switched on in at the GDB command line, + or put into a .gdbint file to establish default debugging + characteristics, like so: +</p><pre class="programlisting"> + set print pretty on + set print object on + set print static-members on + set print vtbl on + set print demangle on + set demangle-style gnu-v3 +</pre><p> + Starting with version 7.0, GDB includes support for writing + pretty-printers in Python. Pretty printers for STL classes are + distributed with GCC from version 4.5.0. The most recent version of + these printers are always found in libstdc++ svn repository. + To enable these printers, check-out the latest printers to a local + directory: +</p><pre class="programlisting"> + svn co svn://gcc.gnu.org/svn/gcc/trunk/libstdc++-v3/python +</pre><p> + Next, add the following section to your ~/.gdbinit The path must + match the location where the Python module above was checked-out. + So if checked out to: /home/maude/gdb_printers/, the path would be as + written in the example below. +</p><pre class="programlisting"> + python + import sys + sys.path.insert(0, '/home/maude/gdb_printers/python') + from libstdcxx.v6.printers import register_libstdcxx_printers + register_libstdcxx_printers (None) + end +</pre><p> + The path should be the only element that needs to be adjusted in the + example. Once loaded, STL classes that the printers support + should print in a more human-readable format. To print the classes + in the old style, use the /r (raw) switch in the print command + (i.e., print /r foo). This will print the classes as if the Python + pretty-printers were not loaded. +</p><p> + For additional information on STL support and GDB please visit: + <a class="link" href="http://sourceware.org/gdb/wiki/STLSupport"> "GDB Support + for STL" </a> in the GDB wiki. Additionally, in-depth + documentation and discussion of the pretty printing feature can be + found in "Pretty Printing" node in the GDB manual. You can find + on-line versions of the GDB user manual in GDB's homepage, at + <a class="link" href="http://sourceware.org/gdb/"> "GDB: The GNU Project + Debugger" </a>. +</p></div><div class="section" title="Tracking uncaught exceptions"><div class="titlepage"><div><div><h3 class="title"><a id="debug.exceptions"/>Tracking uncaught exceptions</h3></div></div></div><p> + The <a class="link" href="termination.html#support.termination.verbose" title="Verbose Terminate Handler">verbose + termination handler</a> gives information about uncaught + exceptions which are killing the program. It is described in the + linked-to page. +</p></div><div class="section" title="Debug Mode"><div class="titlepage"><div><div><h3 class="title"><a id="debug.debug_mode"/>Debug Mode</h3></div></div></div><p> The <a class="link" href="debug_mode.html" title="Chapter 17. Debug Mode">Debug Mode</a> + has compile and run-time checks for many containers. + </p></div><div class="section" title="Compile Time Checking"><div class="titlepage"><div><div><h3 class="title"><a id="debug.compile_time_checks"/>Compile Time Checking</h3></div></div></div><p> The <a class="link" href="ext_compile_checks.html" title="Chapter 16. Compile Time Checks">Compile-Time + Checks</a> Extension has compile-time checks for many algorithms. + </p></div><div class="section" title="Profile-based Performance Analysis"><div class="titlepage"><div><div><h3 class="title"><a id="debug.profile_mode"/>Profile-based Performance Analysis</h3></div></div></div><p> The <a class="link" href="profile_mode.html" title="Chapter 19. Profile Mode">Profile-based + Performance Analysis</a> Extension has performance checks for many + algorithms. + </p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="using_exceptions.html">Prev</a> </td><td align="center"><a accesskey="u" href="using.html">Up</a></td><td align="right"> <a accesskey="n" href="bk01pt02.html">Next</a></td></tr><tr><td align="left" valign="top">Exceptions </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Part II. + Standard Contents + </td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/debug_mode.html b/libstdc++-v3/doc/html/manual/debug_mode.html new file mode 100644 index 000000000..f35960b53 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/debug_mode.html @@ -0,0 +1,37 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Chapter 17. Debug Mode</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" C++ , library , debug "/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="extensions.html" title="Part III. Extensions"/><link rel="prev" href="ext_compile_checks.html" title="Chapter 16. Compile Time Checks"/><link rel="next" href="bk01pt03ch17s02.html" title="Semantics"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 17. Debug Mode</th></tr><tr><td align="left"><a accesskey="p" href="ext_compile_checks.html">Prev</a> </td><th width="60%" align="center">Part III. + Extensions + +</th><td align="right"> <a accesskey="n" href="bk01pt03ch17s02.html">Next</a></td></tr></table><hr/></div><div class="chapter" title="Chapter 17. Debug Mode"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.debug_mode"/>Chapter 17. Debug Mode</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="debug_mode.html#manual.ext.debug_mode.intro">Intro</a></span></dt><dt><span class="section"><a href="bk01pt03ch17s02.html">Semantics</a></span></dt><dt><span class="section"><a href="bk01pt03ch17s03.html">Using</a></span></dt><dd><dl><dt><span class="section"><a href="bk01pt03ch17s03.html#debug_mode.using.mode">Using the Debug Mode</a></span></dt><dt><span class="section"><a href="bk01pt03ch17s03.html#debug_mode.using.specific">Using a Specific Debug Container</a></span></dt></dl></dd><dt><span class="section"><a href="bk01pt03ch17s04.html">Design</a></span></dt><dd><dl><dt><span class="section"><a href="bk01pt03ch17s04.html#debug_mode.design.goals">Goals</a></span></dt><dt><span class="section"><a href="bk01pt03ch17s04.html#debug_mode.design.methods">Methods</a></span></dt><dt><span class="section"><a href="bk01pt03ch17s04.html#debug_mode.design.other">Other Implementations</a></span></dt></dl></dd></dl></div><div class="section" title="Intro"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.debug_mode.intro"/>Intro</h2></div></div></div><p> + By default, libstdc++ is built with efficiency in mind, and + therefore performs little or no error checking that is not + required by the C++ standard. This means that programs that + incorrectly use the C++ standard library will exhibit behavior + that is not portable and may not even be predictable, because they + tread into implementation-specific or undefined behavior. To + detect some of these errors before they can become problematic, + libstdc++ offers a debug mode that provides additional checking of + library facilities, and will report errors in the use of libstdc++ + as soon as they can be detected by emitting a description of the + problem to standard error and aborting the program. This debug + mode is available with GCC 3.4.0 and later versions. + </p><p> + The libstdc++ debug mode performs checking for many areas of the + C++ standard, but the focus is on checking interactions among + standard iterators, containers, and algorithms, including: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><span class="emphasis"><em>Safe iterators</em></span>: Iterators keep track of the + container whose elements they reference, so errors such as + incrementing a past-the-end iterator or dereferencing an iterator + that points to a container that has been destructed are diagnosed + immediately.</p></li><li class="listitem"><p><span class="emphasis"><em>Algorithm preconditions</em></span>: Algorithms attempt to + validate their input parameters to detect errors as early as + possible. For instance, the <code class="code">set_intersection</code> + algorithm requires that its iterator + parameters <code class="code">first1</code> and <code class="code">last1</code> form a valid + iterator range, and that the sequence + [<code class="code">first1</code>, <code class="code">last1</code>) is sorted according to + the same predicate that was passed + to <code class="code">set_intersection</code>; the libstdc++ debug mode will + detect an error if the sequence is not sorted or was sorted by a + different predicate.</p></li></ul></div></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="ext_compile_checks.html">Prev</a> </td><td align="center"><a accesskey="u" href="extensions.html">Up</a></td><td align="right"> <a accesskey="n" href="bk01pt03ch17s02.html">Next</a></td></tr><tr><td align="left" valign="top">Chapter 16. Compile Time Checks </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Semantics</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/diagnostics.html b/libstdc++-v3/doc/html/manual/diagnostics.html new file mode 100644 index 000000000..9c9abdfc2 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/diagnostics.html @@ -0,0 +1,43 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Chapter 5. Diagnostics</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="bk01pt02.html" title="Part II. Standard Contents"/><link rel="prev" href="termination.html" title="Termination"/><link rel="next" href="bk01pt02ch05s02.html" title="Concept Checking"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 5. + Diagnostics + +</th></tr><tr><td align="left"><a accesskey="p" href="termination.html">Prev</a> </td><th width="60%" align="center">Part II. + Standard Contents + </th><td align="right"> <a accesskey="n" href="bk01pt02ch05s02.html">Next</a></td></tr></table><hr/></div><div class="chapter" title="Chapter 5. Diagnostics"><div class="titlepage"><div><div><h2 class="title"><a id="std.diagnostics"/>Chapter 5. + Diagnostics + <a id="id472366" class="indexterm"/> +</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="diagnostics.html#std.diagnostics.exceptions">Exceptions</a></span></dt><dd><dl><dt><span class="section"><a href="diagnostics.html#std.diagnostics.exceptions.api">API Reference</a></span></dt><dt><span class="section"><a href="diagnostics.html#std.diagnostics.exceptions.data">Adding Data to <code class="classname">exception</code></a></span></dt></dl></dd><dt><span class="section"><a href="bk01pt02ch05s02.html">Concept Checking</a></span></dt></dl></div><div class="section" title="Exceptions"><div class="titlepage"><div><div><h2 class="title"><a id="std.diagnostics.exceptions"/>Exceptions</h2></div></div></div><div class="section" title="API Reference"><div class="titlepage"><div><div><h3 class="title"><a id="std.diagnostics.exceptions.api"/>API Reference</h3></div></div></div><p> + All exception objects are defined in one of the standard header + files: <code class="filename">exception</code>, + <code class="filename">stdexcept</code>, <code class="filename">new</code>, and + <code class="filename">typeinfo</code>. + </p><p> + The base exception object is <code class="classname">exception</code>, + located in <code class="filename">exception</code>. This object has no + <code class="classname">string</code> member. + </p><p> + Derived from this are several classes that may have a + <code class="classname">string</code> member: a full hierarchy can be + found in the source documentation. + </p><p> + Full API details. + </p></div><div class="section" title="Adding Data to exception"><div class="titlepage"><div><div><h3 class="title"><a id="std.diagnostics.exceptions.data"/>Adding Data to <code class="classname">exception</code></h3></div></div></div><p> + The standard exception classes carry with them a single string as + data (usually describing what went wrong or where the 'throw' took + place). It's good to remember that you can add your own data to + these exceptions when extending the hierarchy: + </p><pre class="programlisting"> + struct My_Exception : public std::runtime_error + { + public: + My_Exception (const string& whatarg) + : std::runtime_error(whatarg), e(errno), id(GetDataBaseID()) { } + int errno_at_time_of_throw() const { return e; } + DBID id_of_thing_that_threw() const { return id; } + protected: + int e; + DBID id; // some user-defined type + }; + </pre></div></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="termination.html">Prev</a> </td><td align="center"><a accesskey="u" href="bk01pt02.html">Up</a></td><td align="right"> <a accesskey="n" href="bk01pt02ch05s02.html">Next</a></td></tr><tr><td align="left" valign="top">Termination </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Concept Checking</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/documentation_hacking.html b/libstdc++-v3/doc/html/manual/documentation_hacking.html new file mode 100644 index 000000000..fbb85b150 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/documentation_hacking.html @@ -0,0 +1,442 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Writing and Generating Documentation</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content="ISO C++, documentation, style, docbook, doxygen"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="appendix_porting.html" title="Appendix B. Porting and Maintenance"/><link rel="prev" href="appendix_porting.html" title="Appendix B. Porting and Maintenance"/><link rel="next" href="internals.html" title="Porting to New Hardware or Operating Systems"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Writing and Generating Documentation</th></tr><tr><td align="left"><a accesskey="p" href="appendix_porting.html">Prev</a> </td><th width="60%" align="center">Appendix B. + Porting and Maintenance + +</th><td align="right"> <a accesskey="n" href="internals.html">Next</a></td></tr></table><hr/></div><div class="section" title="Writing and Generating Documentation"><div class="titlepage"><div><div><h2 class="title"><a id="appendix.porting.doc"/>Writing and Generating Documentation</h2></div></div></div><div class="section" title="Introduction"><div class="titlepage"><div><div><h3 class="title"><a id="doc.intro"/>Introduction</h3></div></div></div><p> + Documentation for the GNU C++ Library is created from three + independent sources: a manual, a FAQ, and an API reference. + </p><p> + The sub-directory <code class="filename">doc</code> + within the main source directory contains + <code class="filename">Makefile.am</code> and + <code class="filename">Makefile.in</code>, which provide rules for + generating documentation, described in excruciating detail + below. The <code class="filename">doc</code> + sub-directory also contains three directories: <code class="filename">doxygen</code>, which contains scripts and + fragments for <span class="command"><strong>doxygen</strong></span>, <code class="filename">html</code>, which contains an html + version of the manual, and <code class="filename">xml</code>, which contains an xml version + of the manual. + </p><p> + Diverging from established documentation conventions in the rest + of the GCC project, libstdc++ does not use Texinfo as a markup + language. Instead, Docbook is used to create the manual and the + FAQ, and Doxygen is used to construct the API + reference. Although divergent, this conforms to the GNU Project + recommendations as long as the output is of sufficient quality, + as per + <a class="link" href="http://www.gnu.org/prep/standards/standards.html#Documentation"> + GNU Manuals</a>. + </p></div><div class="section" title="Generating Documentation"><div class="titlepage"><div><div><h3 class="title"><a id="doc.generation"/>Generating Documentation</h3></div></div></div><p> + Certain Makefile rules are required by the GNU Coding + Standards. These standard rules generate HTML, PDF, XML, or man + files. For each of the generative rules, there is an additional + install rule that is used to install any generated documentation + files into the prescribed installation directory. Files are + installed into <code class="filename">share/doc</code> + or <code class="filename">share/man</code> directories. + </p><p> + The standard Makefile rules are conditionally supported, based + on the results of examining the host environment for + prerequisites at configuration time. If requirements are not + found, the rule is aliased to a dummy rule that does nothing, + and produces no documentation. If the requirements are found, + the rule forwards to a private rule that produces the requested + documentation. + </p><p> + For more details on what prerequisites were found and where, + please consult the file <code class="filename">config.log</code> in the + libstdc++ build directory. Compare this log to what is expected + for the relevant Makefile conditionals: + <code class="literal">BUILD_INFO</code>, <code class="literal">BUILD_XML</code>, + <code class="literal">BUILD_HTML</code>, <code class="literal">BUILD_MAN</code>, + <code class="literal">BUILD_PDF</code>, and <code class="literal">BUILD_EPUB</code>. + </p><p> + Supported Makefile rules: + </p><div class="variablelist"><dl><dt><span class="term"> + <span class="emphasis"><em>make html</em></span> + , </span><span class="term"> + <span class="emphasis"><em>make install-html</em></span> + </span></dt><dd><p> + Generates multi-page HTML documentation, and installs it + in the following directories: + </p><p> + <code class="filename"> + doc/libstdc++/libstdc++-api.html + </code> + </p><p> + <code class="filename"> + doc/libstdc++/libstdc++-manual.html + </code> + </p></dd><dt><span class="term"> + <span class="emphasis"><em>make pdf</em></span> + , </span><span class="term"> + <span class="emphasis"><em>make install-pdf</em></span> + </span></dt><dd><p> + Generates indexed PDF documentation, and installs it as + the following files: + </p><p> + <code class="filename">doc/libstdc++/libstdc++-api.pdf</code> + </p><p> + <code class="filename">doc/libstdc++/libstdc++-manual.pdf</code> + </p></dd><dt><span class="term"> + <span class="emphasis"><em>make man</em></span> + , </span><span class="term"> + <span class="emphasis"><em>make install-man</em></span> + </span></dt><dd><p> + Generates man pages, and installs it in the following directory: + </p><p> + <code class="filename">man/man3/</code> + </p><p> + The generated man pages are namespace-qualified, so to look at + the man page for <code class="classname">vector</code>, one would use + <span class="command"><strong>man std::vector</strong></span>. + </p></dd><dt><span class="term"> + <span class="emphasis"><em>make epub</em></span> + , </span><span class="term"> + <span class="emphasis"><em>make install-epub</em></span> + </span></dt><dd><p> + Generates documentation in the ebook/portable electronic + reader format called Epub, and installs it as the + following file. + </p><p> + <code class="filename">doc/libstdc++/libstdc++-manual.epub</code> + </p></dd><dt><span class="term"> + <span class="emphasis"><em>make xml</em></span> + , </span><span class="term"> + <span class="emphasis"><em>make install-xml</em></span> + </span></dt><dd><p> + Generates single-file XML documentation, and installs it + as the following files: + </p><p> + <code class="filename">doc/libstdc++/libstdc++-api-single.xml</code> + </p><p> + <code class="filename">doc/libstdc++/libstdc++-manual-single.xml</code> + </p></dd></dl></div><p> + Makefile rules for several other formats are explicitly not + supported, and are always aliased to dummy rules. These + unsupported formats are: <span class="emphasis"><em>info</em></span>, + <span class="emphasis"><em>ps</em></span>, and <span class="emphasis"><em>dvi</em></span>. + </p></div><div class="section" title="Doxygen"><div class="titlepage"><div><div><h3 class="title"><a id="doc.doxygen"/>Doxygen</h3></div></div></div><div class="section" title="Prerequisites"><div class="titlepage"><div><div><h4 class="title"><a id="doxygen.prereq"/>Prerequisites</h4></div></div></div><div class="table"><a id="id495087"/><p class="title"><strong>Table B.1. Doxygen Prerequisites</strong></p><div class="table-contents"><table summary="Doxygen Prerequisites" border="1"><colgroup><col style="text-align: center" class="c1"/><col style="text-align: center" class="c2"/><col style="text-align: center" class="c3"/></colgroup><thead><tr><th style="text-align: center">Tool</th><th style="text-align: center">Version</th><th style="text-align: center">Required By</th></tr></thead><tbody><tr><td style="text-align: center">coreutils</td><td style="text-align: center">8.5</td><td style="text-align: center">all</td></tr><tr><td style="text-align: center">bash</td><td style="text-align: center">4.1</td><td style="text-align: center">all</td></tr><tr><td style="text-align: center">doxygen</td><td style="text-align: center">1.7.0</td><td style="text-align: center">all</td></tr><tr><td style="text-align: center">graphviz</td><td style="text-align: center">2.26</td><td style="text-align: center">graphical hierarchies</td></tr><tr><td style="text-align: center">pdflatex</td><td style="text-align: center">2007-59</td><td style="text-align: center">pdf output</td></tr></tbody></table></div></div><br class="table-break"/><p> + Prerequisite tools are Bash 2.0 or later, + <a class="link" href="http://www.doxygen.org/">Doxygen</a>, and + the <a class="link" href="http://www.gnu.org/software/coreutils/">GNU + coreutils</a>. (GNU versions of find, xargs, and possibly + sed and grep are used, just because the GNU versions make + things very easy.) + </p><p> + To generate the pretty pictures and hierarchy + graphs, the + <a class="link" href="http://www.graphviz.org">Graphviz</a> package + will need to be installed. For PDF + output, <a class="link" href="http://www.tug.org/applications/pdftex/"> + pdflatex</a> is required. + </p></div><div class="section" title="Generating the Doxygen Files"><div class="titlepage"><div><div><h4 class="title"><a id="doxygen.rules"/>Generating the Doxygen Files</h4></div></div></div><p> + The following Makefile rules run Doxygen to generate HTML + docs, XML docs, XML docs as a single file, PDF docs, and the + man pages. These rules are not conditional! If the required + tools are not found, or are the wrong versions, the rule may + end in an error. + </p><p> + </p><pre class="screen"><strong class="userinput"><code>make doc-html-doxygen</code></strong></pre><p> + </p><p> + </p><pre class="screen"><strong class="userinput"><code>make doc-xml-doxygen</code></strong></pre><p> + </p><p> + </p><pre class="screen"><strong class="userinput"><code>make doc-xml-single-doxygen</code></strong></pre><p> + </p><p> + </p><pre class="screen"><strong class="userinput"><code>make doc-pdf-doxygen</code></strong></pre><p> + </p><p> + </p><pre class="screen"><strong class="userinput"><code>make doc-man-doxygen</code></strong></pre><p> + </p><p> + Generated files are output into separate sub directories of + <code class="filename">doc/doxygen/</code> in the + build directory, based on the output format. For instance, the + HTML docs will be in <code class="filename">doc/doxygen/html</code>. + </p><p> + Careful observers will see that the Makefile rules simply call + a script from the source tree, <code class="filename">run_doxygen</code>, which + does the actual work of running Doxygen and then (most + importantly) massaging the output files. If for some reason + you prefer to not go through the Makefile, you can call this + script directly. (Start by passing <code class="literal">--help</code>.) + </p><p> + If you wish to tweak the Doxygen settings, do so by editing + <code class="filename">doc/doxygen/user.cfg.in</code>. Notes to fellow + library hackers are written in triple-# comments. + </p></div><div class="section" title="Markup"><div class="titlepage"><div><div><h4 class="title"><a id="doxygen.markup"/>Markup</h4></div></div></div><p> + In general, libstdc++ files should be formatted according to + the rules found in the + <a class="link" href="source_code_style.html" title="Coding Style">Coding Standard</a>. Before + any doxygen-specific formatting tweaks are made, please try to + make sure that the initial formatting is sound. + </p><p> + Adding Doxygen markup to a file (informally called + <span class="quote">“<span class="quote">doxygenating</span>”</span>) is very simple. The Doxygen manual can be + found + <a class="link" href="http://www.stack.nl/~dimitri/doxygen/download.html#latestman">here</a>. + We try to use a very-recent version of Doxygen. + </p><p> + For classes, use + <code class="classname">deque</code>/<code class="classname">vector</code>/<code class="classname">list</code> + and <code class="classname">std::pair</code> as examples. For + functions, see their member functions, and the free functions + in <code class="filename">stl_algobase.h</code>. Member functions of + other container-like types should read similarly to these + member functions. + </p><p> + Some commentary to accompany + the first list in the <a class="link" href="http://www.stack.nl/~dimitri/doxygen/docblocks.html">Special + Documentation Blocks</a> section of + the Doxygen manual: + </p><div class="orderedlist"><ol class="orderedlist"><li class="listitem"><p>For longer comments, use the Javadoc style...</p></li><li class="listitem"><p> + ...not the Qt style. The intermediate *'s are preferred. + </p></li><li class="listitem"><p> + Use the triple-slash style only for one-line comments (the + <span class="quote">“<span class="quote">brief</span>”</span> mode). + </p></li><li class="listitem"><p> + This is disgusting. Don't do this. + </p></li></ol></div><p> + Some specific guidelines: + </p><p> + Use the @-style of commands, not the !-style. Please be + careful about whitespace in your markup comments. Most of the + time it doesn't matter; doxygen absorbs most whitespace, and + both HTML and *roff are agnostic about whitespace. However, + in <pre> blocks and @code/@endcode sections, spacing can + have <span class="quote">“<span class="quote">interesting</span>”</span> effects. + </p><p> + Use either kind of grouping, as + appropriate. <code class="filename">doxygroups.cc</code> exists for this + purpose. See <code class="filename">stl_iterator.h</code> for a good example + of the <span class="quote">“<span class="quote">other</span>”</span> kind of grouping. + </p><p> + Please use markup tags like @p and @a when referring to things + such as the names of function parameters. Use @e for emphasis + when necessary. Use @c to refer to other standard names. + (Examples of all these abound in the present code.) + </p><p> + Complicated math functions should use the multi-line + format. An example from <code class="filename">random.h</code>: + </p><p> +</p><div class="literallayout"><p><br/> +/**<br/> + * @brief A model of a linear congruential random number generator.<br/> + *<br/> + * @f[<br/> + * x_{i+1}\leftarrow(ax_{i} + c) \bmod m<br/> + * @f]<br/> + */<br/> +</p></div><p> + </p><p> + One area of note is the markup required for + <code class="literal">@file</code> markup in header files. Two details + are important: for filenames that have the same name in + multiple directories, include part of the installed path to + disambiguate. For example: + </p><p> +</p><div class="literallayout"><p><br/> +/** @file debug/vector<br/> + * This file is a GNU debug extension to the Standard C++ Library.<br/> + */<br/> +</p></div><p> + </p><p> + The other relevant detail for header files is the use of a + libstdc++-specific doxygen alias that helps distinguish + between public header files (like <code class="filename">random</code>) + from implementation or private header files (like + <code class="filename">bits/c++config.h</code>.) This alias is spelled + <code class="literal">@headername</code> and can take one or two + arguments that detail the public header file or files that + should be included to use the contents of the file. All header + files that are not intended for direct inclusion must use + <code class="literal">headername</code> in the <code class="literal">file</code> + block. An example: + </p><p> +</p><div class="literallayout"><p><br/> +/** @file bits/basic_string.h<br/> + * This is an internal header file, included by other library headers.<br/> + * Do not attempt to use it directly. @headername{string}<br/> + */<br/> +</p></div><p> + </p><p> + Be careful about using certain, special characters when + writing Doxygen comments. Single and double quotes, and + separators in filenames are two common trouble spots. When in + doubt, consult the following table. + </p><div class="table"><a id="id495589"/><p class="title"><strong>Table B.2. HTML to Doxygen Markup Comparison</strong></p><div class="table-contents"><table summary="HTML to Doxygen Markup Comparison" border="1"><colgroup><col style="text-align: left" class="c1"/><col style="text-align: left" class="c2"/></colgroup><thead><tr><th style="text-align: left">HTML</th><th style="text-align: left">Doxygen</th></tr></thead><tbody><tr><td style="text-align: left">\</td><td style="text-align: left">\\</td></tr><tr><td style="text-align: left">"</td><td style="text-align: left">\"</td></tr><tr><td style="text-align: left">'</td><td style="text-align: left">\'</td></tr><tr><td style="text-align: left"><i></td><td style="text-align: left">@a word</td></tr><tr><td style="text-align: left"><b></td><td style="text-align: left">@b word</td></tr><tr><td style="text-align: left"><code></td><td style="text-align: left">@c word</td></tr><tr><td style="text-align: left"><em></td><td style="text-align: left">@a word</td></tr><tr><td style="text-align: left"><em></td><td style="text-align: left"><em>two words or more</em></td></tr></tbody></table></div></div><br class="table-break"/></div></div><div class="section" title="Docbook"><div class="titlepage"><div><div><h3 class="title"><a id="doc.docbook"/>Docbook</h3></div></div></div><div class="section" title="Prerequisites"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.prereq"/>Prerequisites</h4></div></div></div><div class="table"><a id="id495751"/><p class="title"><strong>Table B.3. Docbook Prerequisites</strong></p><div class="table-contents"><table summary="Docbook Prerequisites" border="1"><colgroup><col style="text-align: center" class="c1"/><col style="text-align: center" class="c2"/><col style="text-align: center" class="c3"/></colgroup><thead><tr><th style="text-align: center">Tool</th><th style="text-align: center">Version</th><th style="text-align: center">Required By</th></tr></thead><tbody><tr><td style="text-align: center">docbook5-style-xsl</td><td style="text-align: center">1.76.1</td><td style="text-align: center">all</td></tr><tr><td style="text-align: center">xsltproc</td><td style="text-align: center">1.1.26</td><td style="text-align: center">all</td></tr><tr><td style="text-align: center">xmllint</td><td style="text-align: center">2.7.7</td><td style="text-align: center">validation</td></tr><tr><td style="text-align: center">dblatex</td><td style="text-align: center">0.3</td><td style="text-align: center">pdf output</td></tr><tr><td style="text-align: center">pdflatex</td><td style="text-align: center">2007-59</td><td style="text-align: center">pdf output</td></tr><tr><td style="text-align: center">docbook2X</td><td style="text-align: center">0.8.8</td><td style="text-align: center">info output</td></tr></tbody></table></div></div><br class="table-break"/><p> + Editing the DocBook sources requires an XML editor. Many + exist: some notable options + include <span class="command"><strong>emacs</strong></span>, <span class="application">Kate</span>, + or <span class="application">Conglomerate</span>. + </p><p> + Some editors support special <span class="quote">“<span class="quote">XML Validation</span>”</span> + modes that can validate the file as it is + produced. Recommended is the <span class="command"><strong>nXML Mode</strong></span> + for <span class="command"><strong>emacs</strong></span>. + </p><p> + Besides an editor, additional DocBook files and XML tools are + also required. + </p><p> + Access to the DocBook 5.0 stylesheets and schema is required. The + stylesheets are usually packaged by vendor, in something + like <code class="filename">docbook5-style-xsl</code>. To exactly match + generated output, please use a version of the stylesheets + equivalent + to <code class="filename">docbook5-style-xsl-1.75.2-3</code>. The + installation directory for this package corresponds to + the <code class="literal">XSL_STYLE_DIR</code> + in <code class="filename">doc/Makefile.am</code> and defaults + to <code class="filename">/usr/share/sgml/docbook/xsl-ns-stylesheets</code>. + </p><p> + For processing XML, an XML processor and some style + sheets are necessary. Defaults are <span class="command"><strong>xsltproc</strong></span> + provided by <code class="filename">libxslt</code>. + </p><p> + For validating the XML document, you'll need + something like <span class="command"><strong>xmllint</strong></span> and access to the + relevant DocBook schema. These are provided + by a vendor package like <code class="filename">libxml2</code> and <code class="filename">docbook5-schemas-5.0-4</code> + </p><p> + For PDF output, something that transforms valid Docbook XML to PDF is + required. Possible solutions include <a class="link" href="http://dblatex.sourceforge.net">dblatex</a>, + <span class="command"><strong>xmlto</strong></span>, or <span class="command"><strong>prince</strong></span>. Of + these, <span class="command"><strong>dblatex</strong></span> is the default. Other + options are listed on the DocBook web <a class="link" href="http://wiki.docbook.org/topic/DocBookPublishingTools">pages</a>. Please + consult the <code class="email"><<a class="email" href="mailto:libstdc++@gcc.gnu.org">libstdc++@gcc.gnu.org</a>></code> list when + preparing printed manuals for current best practice and + suggestions. + </p><p> + For Texinfo output, something that transforms valid Docbook + XML to Texinfo is required. The default choice is <a class="link" href="http://docbook2x.sourceforge.net/">docbook2X</a>. + </p></div><div class="section" title="Generating the DocBook Files"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.rules"/>Generating the DocBook Files</h4></div></div></div><p> + The following Makefile rules generate (in order): an HTML + version of all the DocBook documentation, a PDF version of the + same, and a single XML document. These rules are not + conditional! If the required tools are not found, or are the + wrong versions, the rule may end in an error. + </p><p> + </p><pre class="screen"><strong class="userinput"><code>make doc-html-docbook</code></strong></pre><p> + </p><p> + </p><pre class="screen"><strong class="userinput"><code>make doc-pdf-docbook</code></strong></pre><p> + </p><p> + </p><pre class="screen"><strong class="userinput"><code>make doc-xml-single-docbook</code></strong></pre><p> + </p><p> + Generated files are output into separate sub directores of + <code class="filename">doc/docbook/</code> in the + build directory, based on the output format. For instance, the + HTML docs will be in <code class="filename">doc/docbook/html</code>. + </p><p> + If the Docbook stylesheets are installed in a custom location, + one can use the variable <code class="literal">XSL_STYLE_DIR</code> to + over-ride the Makefile defaults. As so: + </p><pre class="screen"> + <strong class="userinput"><code> +make <code class="literal">XSL_STYLE_DIR="/usr/share/xml/docbook/stylesheet/nwalsh"</code> doc-html-docbook + </code></strong> + </pre></div><div class="section" title="Editing and Validation"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.validation"/>Editing and Validation</h4></div></div></div><p> + After editing the xml sources, please make sure that the XML + documentation and markup is still valid. This can be + done easily, with the following validation rule: + </p><pre class="screen"> + <strong class="userinput"><code>make doc-xml-validate-docbook</code></strong> + </pre><p> + This is equivalent to doing: + </p><pre class="screen"> + <strong class="userinput"><code> + xmllint --noout --valid <code class="filename">xml/index.xml</code> + </code></strong> + </pre><p> + Please note that individual sections and chapters of the + manual can be validated by substituting the file desired for + <code class="filename">xml/index.xml</code> in the command + above. Reducing scope in this manner can be helpful when + validation on the entire manual fails. + </p><p> + All Docbook xml sources should always validate. No excuses! + </p></div><div class="section" title="File Organization and Basics"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.examples"/>File Organization and Basics</h4></div></div></div><div class="literallayout"><p><br/> + <span class="emphasis"><em>Which files are important</em></span><br/> +<br/> + All Docbook files are in the directory<br/> + libstdc++-v3/doc/xml<br/> +<br/> + Inside this directory, the files of importance:<br/> + spine.xml - index to documentation set<br/> + manual/spine.xml - index to manual<br/> + manual/*.xml - individual chapters and sections of the manual<br/> + faq.xml - index to FAQ<br/> + api.xml - index to source level / API<br/> +<br/> + All *.txml files are template xml files, i.e., otherwise empty files with<br/> + the correct structure, suitable for filling in with new information.<br/> +<br/> + <span class="emphasis"><em>Canonical Writing Style</em></span><br/> +<br/> + class template<br/> + function template<br/> + member function template<br/> + (via C++ Templates, Vandevoorde)<br/> +<br/> + class in namespace std: allocator, not std::allocator<br/> +<br/> + header file: iostream, not <iostream><br/> +<br/> +<br/> + <span class="emphasis"><em>General structure</em></span><br/> +<br/> + <set><br/> + <book><br/> + </book><br/> +<br/> + <book><br/> + <chapter><br/> + </chapter><br/> + </book><br/> +<br/> + <book><br/> + <part><br/> + <chapter><br/> + <section><br/> + </section><br/> +<br/> + <sect1><br/> + </sect1><br/> +<br/> + <sect1><br/> + <sect2><br/> + </sect2><br/> + </sect1><br/> + </chapter><br/> +<br/> + <chapter><br/> + </chapter><br/> + </part><br/> + </book><br/> +<br/> + </set><br/> + </p></div></div><div class="section" title="Markup By Example"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.markup"/>Markup By Example</h4></div></div></div><p> + Complete details on Docbook markup can be found in the DocBook + Element Reference, + <a class="link" href="http://www.docbook.org/tdg/en/html/part2.html">online</a>. + An incomplete reference for HTML to Docbook conversion is + detailed in the table below. + </p><div class="table"><a id="id496228"/><p class="title"><strong>Table B.4. HTML to Docbook XML Markup Comparison</strong></p><div class="table-contents"><table summary="HTML to Docbook XML Markup Comparison" border="1"><colgroup><col style="text-align: left" class="c1"/><col style="text-align: left" class="c2"/></colgroup><thead><tr><th style="text-align: left">HTML</th><th style="text-align: left">Docbook</th></tr></thead><tbody><tr><td style="text-align: left"><p></td><td style="text-align: left"><para></td></tr><tr><td style="text-align: left"><pre></td><td style="text-align: left"><computeroutput>, <programlisting>, + <literallayout></td></tr><tr><td style="text-align: left"><ul></td><td style="text-align: left"><itemizedlist></td></tr><tr><td style="text-align: left"><ol></td><td style="text-align: left"><orderedlist></td></tr><tr><td style="text-align: left"><il></td><td style="text-align: left"><listitem></td></tr><tr><td style="text-align: left"><dl></td><td style="text-align: left"><variablelist></td></tr><tr><td style="text-align: left"><dt></td><td style="text-align: left"><term></td></tr><tr><td style="text-align: left"><dd></td><td style="text-align: left"><listitem></td></tr><tr><td style="text-align: left"><a href=""></td><td style="text-align: left"><ulink url=""></td></tr><tr><td style="text-align: left"><code></td><td style="text-align: left"><literal>, <programlisting></td></tr><tr><td style="text-align: left"><strong></td><td style="text-align: left"><emphasis></td></tr><tr><td style="text-align: left"><em></td><td style="text-align: left"><emphasis></td></tr><tr><td style="text-align: left">"</td><td style="text-align: left"><quote></td></tr></tbody></table></div></div><br class="table-break"/><p> + And examples of detailed markup for which there are no real HTML + equivalents are listed in the table below. +</p><div class="table"><a id="id496429"/><p class="title"><strong>Table B.5. Docbook XML Element Use</strong></p><div class="table-contents"><table summary="Docbook XML Element Use" border="1"><colgroup><col style="text-align: left" class="c1"/><col style="text-align: left" class="c2"/></colgroup><thead><tr><th style="text-align: left">Element</th><th style="text-align: left">Use</th></tr></thead><tbody><tr><td style="text-align: left"><structname></td><td style="text-align: left"><structname>char_traits</structname></td></tr><tr><td style="text-align: left"><classname></td><td style="text-align: left"><classname>string</classname></td></tr><tr><td style="text-align: left"><function></td><td style="text-align: left"> + <p><function>clear()</function></p> + <p><function>fs.clear()</function></p> + </td></tr><tr><td style="text-align: left"><type></td><td style="text-align: left"><type>long long</type></td></tr><tr><td style="text-align: left"><varname></td><td style="text-align: left"><varname>fs</varname></td></tr><tr><td style="text-align: left"><literal></td><td style="text-align: left"> + <p><literal>-Weffc++</literal></p> + <p><literal>rel_ops</literal></p> + </td></tr><tr><td style="text-align: left"><constant></td><td style="text-align: left"> + <p><constant>_GNU_SOURCE</constant></p> + <p><constant>3.0</constant></p> + </td></tr><tr><td style="text-align: left"><command></td><td style="text-align: left"><command>g++</command></td></tr><tr><td style="text-align: left"><errortext></td><td style="text-align: left"><errortext>In instantiation of</errortext></td></tr><tr><td style="text-align: left"><filename></td><td style="text-align: left"> + <p><filename class="headerfile">ctype.h</filename></p> + <p><filename class="directory">/home/gcc/build</filename></p> + <p><filename class="libraryfile">libstdc++.so</filename></p> + </td></tr></tbody></table></div></div><br class="table-break"/></div></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="appendix_porting.html">Prev</a> </td><td align="center"><a accesskey="u" href="appendix_porting.html">Up</a></td><td align="right"> <a accesskey="n" href="internals.html">Next</a></td></tr><tr><td align="left" valign="top">Appendix B. + Porting and Maintenance + + </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Porting to New Hardware or Operating Systems</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/dynamic_memory.html b/libstdc++-v3/doc/html/manual/dynamic_memory.html new file mode 100644 index 000000000..481347bef --- /dev/null +++ b/libstdc++-v3/doc/html/manual/dynamic_memory.html @@ -0,0 +1,72 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Dynamic Memory</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="support.html" title="Chapter 4. Support"/><link rel="prev" href="support.html" title="Chapter 4. Support"/><link rel="next" href="termination.html" title="Termination"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Dynamic Memory</th></tr><tr><td align="left"><a accesskey="p" href="support.html">Prev</a> </td><th width="60%" align="center">Chapter 4. + Support + +</th><td align="right"> <a accesskey="n" href="termination.html">Next</a></td></tr></table><hr/></div><div class="section" title="Dynamic Memory"><div class="titlepage"><div><div><h2 class="title"><a id="std.support.memory"/>Dynamic Memory</h2></div></div></div><p> + There are six flavors each of <code class="function">new</code> and + <code class="function">delete</code>, so make certain that you're using the right + ones. Here are quickie descriptions of <code class="function">new</code>: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + single object form, throwing a + <code class="classname">bad_alloc</code> on errors; this is what most + people are used to using + </p></li><li class="listitem"><p> + Single object "nothrow" form, returning NULL on errors + </p></li><li class="listitem"><p> + Array <code class="function">new</code>, throwing + <code class="classname">bad_alloc</code> on errors + </p></li><li class="listitem"><p> + Array nothrow <code class="function">new</code>, returning + <code class="constant">NULL</code> on errors + </p></li><li class="listitem"><p> + Placement <code class="function">new</code>, which does nothing (like + it's supposed to) + </p></li><li class="listitem"><p> + Placement array <code class="function">new</code>, which also does + nothing + </p></li></ul></div><p> + They are distinguished by the parameters that you pass to them, like + any other overloaded function. The six flavors of <code class="function">delete</code> + are distinguished the same way, but none of them are allowed to throw + an exception under any circumstances anyhow. (They match up for + completeness' sake.) + </p><p> + Remember that it is perfectly okay to call <code class="function">delete</code> on a + NULL pointer! Nothing happens, by definition. That is not the + same thing as deleting a pointer twice. + </p><p> + By default, if one of the <span class="quote">“<span class="quote">throwing <code class="function">new</code>s</span>”</span> can't + allocate the memory requested, it tosses an instance of a + <code class="classname">bad_alloc</code> exception (or, technically, some class derived + from it). You can change this by writing your own function (called a + new-handler) and then registering it with <code class="function">set_new_handler()</code>: + </p><pre class="programlisting"> + typedef void (*PFV)(void); + + static char* safety; + static PFV old_handler; + + void my_new_handler () + { + delete[] safety; + popup_window ("Dude, you are running low on heap memory. You + should, like, close some windows, or something. + The next time you run out, we're gonna burn!"); + set_new_handler (old_handler); + return; + } + + int main () + { + safety = new char[500000]; + old_handler = set_new_handler (&my_new_handler); + ... + } + </pre><p> + <code class="classname">bad_alloc</code> is derived from the base <code class="classname">exception</code> + class defined in Sect1 19. + </p></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="support.html">Prev</a> </td><td align="center"><a accesskey="u" href="support.html">Up</a></td><td align="right"> <a accesskey="n" href="termination.html">Next</a></td></tr><tr><td align="left" valign="top">Chapter 4. + Support + + </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Termination</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/ext_algorithms.html b/libstdc++-v3/doc/html/manual/ext_algorithms.html new file mode 100644 index 000000000..354dd9bbc --- /dev/null +++ b/libstdc++-v3/doc/html/manual/ext_algorithms.html @@ -0,0 +1,23 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Chapter 23. Algorithms</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="extensions.html" title="Part III. Extensions"/><link rel="prev" href="ext_utilities.html" title="Chapter 22. Utilities"/><link rel="next" href="ext_numerics.html" title="Chapter 24. Numerics"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 23. Algorithms</th></tr><tr><td align="left"><a accesskey="p" href="ext_utilities.html">Prev</a> </td><th width="60%" align="center">Part III. + Extensions + +</th><td align="right"> <a accesskey="n" href="ext_numerics.html">Next</a></td></tr></table><hr/></div><div class="chapter" title="Chapter 23. Algorithms"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.algorithms"/>Chapter 23. Algorithms</h2></div></div></div><p>25.1.6 (count, count_if) is extended with two more versions of count + and count_if. The standard versions return their results. The + additional signatures return void, but take a final parameter by + reference to which they assign their results, e.g., +</p><pre class="programlisting"> + void count (first, last, value, n);</pre><p>25.2 (mutating algorithms) is extended with two families of signatures, + random_sample and random_sample_n. +</p><p>25.2.1 (copy) is extended with +</p><pre class="programlisting"> + copy_n (_InputIter first, _Size count, _OutputIter result);</pre><p>which copies the first 'count' elements at 'first' into 'result'. +</p><p>25.3 (sorting 'n' heaps 'n' stuff) is extended with some helper + predicates. Look in the doxygen-generated pages for notes on these. +</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><code class="code">is_heap</code> tests whether or not a range is a heap.</p></li><li class="listitem"><p><code class="code">is_sorted</code> tests whether or not a range is sorted in + nondescending order.</p></li></ul></div><p>25.3.8 (lexicographical_compare) is extended with +</p><pre class="programlisting"> + lexicographical_compare_3way(_InputIter1 first1, _InputIter1 last1, + _InputIter2 first2, _InputIter2 last2)</pre><p>which does... what? +</p></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="ext_utilities.html">Prev</a> </td><td align="center"><a accesskey="u" href="extensions.html">Up</a></td><td align="right"> <a accesskey="n" href="ext_numerics.html">Next</a></td></tr><tr><td align="left" valign="top">Chapter 22. Utilities </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Chapter 24. Numerics</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/ext_allocators.html b/libstdc++-v3/doc/html/manual/ext_allocators.html new file mode 100644 index 000000000..bd283b75c --- /dev/null +++ b/libstdc++-v3/doc/html/manual/ext_allocators.html @@ -0,0 +1,397 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Chapter 20. Allocators</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="extensions.html" title="Part III. Extensions"/><link rel="prev" href="bk01pt03ch19s07.html" title="Diagnostics"/><link rel="next" href="bitmap_allocator.html" title="bitmap_allocator"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 20. Allocators</th></tr><tr><td align="left"><a accesskey="p" href="bk01pt03ch19s07.html">Prev</a> </td><th width="60%" align="center">Part III. + Extensions + +</th><td align="right"> <a accesskey="n" href="bitmap_allocator.html">Next</a></td></tr></table><hr/></div><div class="chapter" title="Chapter 20. Allocators"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.allocator"/>Chapter 20. Allocators</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="ext_allocators.html#manual.ext.allocator.mt">mt_allocator</a></span></dt><dd><dl><dt><span class="section"><a href="ext_allocators.html#allocator.mt.intro">Intro</a></span></dt><dt><span class="section"><a href="ext_allocators.html#allocator.mt.design_issues">Design Issues</a></span></dt><dt><span class="section"><a href="ext_allocators.html#allocator.mt.impl">Implementation</a></span></dt><dt><span class="section"><a href="ext_allocators.html#allocator.mt.example_single">Single Thread Example</a></span></dt><dt><span class="section"><a href="ext_allocators.html#allocator.mt.example_multi">Multiple Thread Example</a></span></dt></dl></dd><dt><span class="section"><a href="bitmap_allocator.html">bitmap_allocator</a></span></dt><dd><dl><dt><span class="section"><a href="bitmap_allocator.html#allocator.bitmap.design">Design</a></span></dt><dt><span class="section"><a href="bitmap_allocator.html#allocator.bitmap.impl">Implementation</a></span></dt></dl></dd></dl></div><div class="section" title="mt_allocator"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.allocator.mt"/>mt_allocator</h2></div></div></div><p> +</p><div class="section" title="Intro"><div class="titlepage"><div><div><h3 class="title"><a id="allocator.mt.intro"/>Intro</h3></div></div></div><p> + The mt allocator [hereinafter referred to simply as "the allocator"] + is a fixed size (power of two) allocator that was initially + developed specifically to suit the needs of multi threaded + applications [hereinafter referred to as an MT application]. Over + time the allocator has evolved and been improved in many ways, in + particular it now also does a good job in single threaded + applications [hereinafter referred to as a ST application]. (Note: + In this document, when referring to single threaded applications + this also includes applications that are compiled with gcc without + thread support enabled. This is accomplished using ifdef's on + __GTHREADS). This allocator is tunable, very flexible, and capable + of high-performance. +</p><p> + The aim of this document is to describe - from an application point of + view - the "inner workings" of the allocator. +</p></div><div class="section" title="Design Issues"><div class="titlepage"><div><div><h3 class="title"><a id="allocator.mt.design_issues"/>Design Issues</h3></div></div></div><div class="section" title="Overview"><div class="titlepage"><div><div><h4 class="title"><a id="allocator.mt.overview"/>Overview</h4></div></div></div><p> There are three general components to the allocator: a datum +describing the characteristics of the memory pool, a policy class +containing this pool that links instantiation types to common or +individual pools, and a class inheriting from the policy class that is +the actual allocator. +</p><p>The datum describing pools characteristics is +</p><pre class="programlisting"> + template<bool _Thread> + class __pool +</pre><p> This class is parametrized on thread support, and is explicitly +specialized for both multiple threads (with <code class="code">bool==true</code>) +and single threads (via <code class="code">bool==false</code>.) It is possible to +use a custom pool datum instead of the default class that is provided. +</p><p> There are two distinct policy classes, each of which can be used +with either type of underlying pool datum. +</p><pre class="programlisting"> + template<bool _Thread> + struct __common_pool_policy + + template<typename _Tp, bool _Thread> + struct __per_type_pool_policy +</pre><p> The first policy, <code class="code">__common_pool_policy</code>, implements a +common pool. This means that allocators that are instantiated with +different types, say <code class="code">char</code> and <code class="code">long</code> will both +use the same pool. This is the default policy. +</p><p> The second policy, <code class="code">__per_type_pool_policy</code>, implements +a separate pool for each instantiating type. Thus, <code class="code">char</code> +and <code class="code">long</code> will use separate pools. This allows per-type +tuning, for instance. +</p><p> Putting this all together, the actual allocator class is +</p><pre class="programlisting"> + template<typename _Tp, typename _Poolp = __default_policy> + class __mt_alloc : public __mt_alloc_base<_Tp>, _Poolp +</pre><p> This class has the interface required for standard library allocator +classes, namely member functions <code class="code">allocate</code> and +<code class="code">deallocate</code>, plus others. +</p></div></div><div class="section" title="Implementation"><div class="titlepage"><div><div><h3 class="title"><a id="allocator.mt.impl"/>Implementation</h3></div></div></div><div class="section" title="Tunable Parameters"><div class="titlepage"><div><div><h4 class="title"><a id="allocator.mt.tune"/>Tunable Parameters</h4></div></div></div><p>Certain allocation parameters can be modified, or tuned. There +exists a nested <code class="code">struct __pool_base::_Tune</code> that contains all +these parameters, which include settings for +</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>Alignment</p></li><li class="listitem"><p>Maximum bytes before calling <code class="code">::operator new</code> directly</p></li><li class="listitem"><p>Minimum bytes</p></li><li class="listitem"><p>Size of underlying global allocations</p></li><li class="listitem"><p>Maximum number of supported threads</p></li><li class="listitem"><p>Migration of deallocations to the global free list</p></li><li class="listitem"><p>Shunt for global <code class="code">new</code> and <code class="code">delete</code></p></li></ul></div><p>Adjusting parameters for a given instance of an allocator can only +happen before any allocations take place, when the allocator itself is +initialized. For instance: +</p><pre class="programlisting"> +#include <ext/mt_allocator.h> + +struct pod +{ + int i; + int j; +}; + +int main() +{ + typedef pod value_type; + typedef __gnu_cxx::__mt_alloc<value_type> allocator_type; + typedef __gnu_cxx::__pool_base::_Tune tune_type; + + tune_type t_default; + tune_type t_opt(16, 5120, 32, 5120, 20, 10, false); + tune_type t_single(16, 5120, 32, 5120, 1, 10, false); + + tune_type t; + t = allocator_type::_M_get_options(); + allocator_type::_M_set_options(t_opt); + t = allocator_type::_M_get_options(); + + allocator_type a; + allocator_type::pointer p1 = a.allocate(128); + allocator_type::pointer p2 = a.allocate(5128); + + a.deallocate(p1, 128); + a.deallocate(p2, 5128); + + return 0; +} +</pre></div><div class="section" title="Initialization"><div class="titlepage"><div><div><h4 class="title"><a id="allocator.mt.init"/>Initialization</h4></div></div></div><p> +The static variables (pointers to freelists, tuning parameters etc) +are initialized as above, or are set to the global defaults. +</p><p> +The very first allocate() call will always call the +_S_initialize_once() function. In order to make sure that this +function is called exactly once we make use of a __gthread_once call +in MT applications and check a static bool (_S_init) in ST +applications. +</p><p> +The _S_initialize() function: +- If the GLIBCXX_FORCE_NEW environment variable is set, it sets the bool + _S_force_new to true and then returns. This will cause subsequent calls to + allocate() to return memory directly from a new() call, and deallocate will + only do a delete() call. +</p><p> +- If the GLIBCXX_FORCE_NEW environment variable is not set, both ST and MT + applications will: + - Calculate the number of bins needed. A bin is a specific power of two size + of bytes. I.e., by default the allocator will deal with requests of up to + 128 bytes (or whatever the value of _S_max_bytes is when _S_init() is + called). This means that there will be bins of the following sizes + (in bytes): 1, 2, 4, 8, 16, 32, 64, 128. + + - Create the _S_binmap array. All requests are rounded up to the next + "large enough" bin. I.e., a request for 29 bytes will cause a block from + the "32 byte bin" to be returned to the application. The purpose of + _S_binmap is to speed up the process of finding out which bin to use. + I.e., the value of _S_binmap[ 29 ] is initialized to 5 (bin 5 = 32 bytes). +</p><p> + - Create the _S_bin array. This array consists of bin_records. There will be + as many bin_records in this array as the number of bins that we calculated + earlier. I.e., if _S_max_bytes = 128 there will be 8 entries. + Each bin_record is then initialized: + - bin_record->first = An array of pointers to block_records. There will be + as many block_records pointers as there are maximum number of threads + (in a ST application there is only 1 thread, in a MT application there + are _S_max_threads). + This holds the pointer to the first free block for each thread in this + bin. I.e., if we would like to know where the first free block of size 32 + for thread number 3 is we would look this up by: _S_bin[ 5 ].first[ 3 ] + + The above created block_record pointers members are now initialized to + their initial values. I.e. _S_bin[ n ].first[ n ] = NULL; +</p><p> +- Additionally a MT application will: + - Create a list of free thread id's. The pointer to the first entry + is stored in _S_thread_freelist_first. The reason for this approach is + that the __gthread_self() call will not return a value that corresponds to + the maximum number of threads allowed but rather a process id number or + something else. So what we do is that we create a list of thread_records. + This list is _S_max_threads long and each entry holds a size_t thread_id + which is initialized to 1, 2, 3, 4, 5 and so on up to _S_max_threads. + Each time a thread calls allocate() or deallocate() we call + _S_get_thread_id() which looks at the value of _S_thread_key which is a + thread local storage pointer. If this is NULL we know that this is a newly + created thread and we pop the first entry from this list and saves the + pointer to this record in the _S_thread_key variable. The next time + we will get the pointer to the thread_record back and we use the + thread_record->thread_id as identification. I.e., the first thread that + calls allocate will get the first record in this list and thus be thread + number 1 and will then find the pointer to its first free 32 byte block + in _S_bin[ 5 ].first[ 1 ] + When we create the _S_thread_key we also define a destructor + (_S_thread_key_destr) which means that when the thread dies, this + thread_record is returned to the front of this list and the thread id + can then be reused if a new thread is created. + This list is protected by a mutex (_S_thread_freelist_mutex) which is only + locked when records are removed or added to the list. +</p><p> + - Initialize the free and used counters of each bin_record: + - bin_record->free = An array of size_t. This keeps track of the number + of blocks on a specific thread's freelist in each bin. I.e., if a thread + has 12 32-byte blocks on it's freelists and allocates one of these, this + counter would be decreased to 11. + + - bin_record->used = An array of size_t. This keeps track of the number + of blocks currently in use of this size by this thread. I.e., if a thread + has made 678 requests (and no deallocations...) of 32-byte blocks this + counter will read 678. + + The above created arrays are now initialized with their initial values. + I.e. _S_bin[ n ].free[ n ] = 0; +</p><p> + - Initialize the mutex of each bin_record: The bin_record->mutex + is used to protect the global freelist. This concept of a global + freelist is explained in more detail in the section "A multi + threaded example", but basically this mutex is locked whenever a + block of memory is retrieved or returned to the global freelist + for this specific bin. This only occurs when a number of blocks + are grabbed from the global list to a thread specific list or when + a thread decides to return some blocks to the global freelist. +</p></div><div class="section" title="Deallocation Notes"><div class="titlepage"><div><div><h4 class="title"><a id="allocator.mt.deallocation"/>Deallocation Notes</h4></div></div></div><p> Notes about deallocation. This allocator does not explicitly +release memory. Because of this, memory debugging programs like +valgrind or purify may notice leaks: sorry about this +inconvenience. Operating systems will reclaim allocated memory at +program termination anyway. If sidestepping this kind of noise is +desired, there are three options: use an allocator, like +<code class="code">new_allocator</code> that releases memory while debugging, use +GLIBCXX_FORCE_NEW to bypass the allocator's internal pools, or use a +custom pool datum that releases resources on destruction. +</p><p> + On systems with the function <code class="code">__cxa_atexit</code>, the +allocator can be forced to free all memory allocated before program +termination with the member function +<code class="code">__pool_type::_M_destroy</code>. However, because this member +function relies on the precise and exactly-conforming ordering of +static destructors, including those of a static local +<code class="code">__pool</code> object, it should not be used, ever, on systems +that don't have the necessary underlying support. In addition, in +practice, forcing deallocation can be tricky, as it requires the +<code class="code">__pool</code> object to be fully-constructed before the object +that uses it is fully constructed. For most (but not all) STL +containers, this works, as an instance of the allocator is constructed +as part of a container's constructor. However, this assumption is +implementation-specific, and subject to change. For an example of a +pool that frees memory, see the following + <a class="link" href="http://gcc.gnu.org/viewcvs/trunk/libstdc++-v3/testsuite/ext/mt_allocator/deallocate_local-6.cc?view=markup"> + example.</a> +</p></div></div><div class="section" title="Single Thread Example"><div class="titlepage"><div><div><h3 class="title"><a id="allocator.mt.example_single"/>Single Thread Example</h3></div></div></div><p> +Let's start by describing how the data on a freelist is laid out in memory. +This is the first two blocks in freelist for thread id 3 in bin 3 (8 bytes): +</p><pre class="programlisting"> ++----------------+ +| next* ---------|--+ (_S_bin[ 3 ].first[ 3 ] points here) +| | | +| | | +| | | ++----------------+ | +| thread_id = 3 | | +| | | +| | | +| | | ++----------------+ | +| DATA | | (A pointer to here is what is returned to the +| | | the application when needed) +| | | +| | | +| | | +| | | +| | | +| | | ++----------------+ | ++----------------+ | +| next* |<-+ (If next == NULL it's the last one on the list) +| | +| | +| | ++----------------+ +| thread_id = 3 | +| | +| | +| | ++----------------+ +| DATA | +| | +| | +| | +| | +| | +| | +| | ++----------------+ +</pre><p> +With this in mind we simplify things a bit for a while and say that there is +only one thread (a ST application). In this case all operations are made to +what is referred to as the global pool - thread id 0 (No thread may be +assigned this id since they span from 1 to _S_max_threads in a MT application). +</p><p> +When the application requests memory (calling allocate()) we first look at the +requested size and if this is > _S_max_bytes we call new() directly and return. +</p><p> +If the requested size is within limits we start by finding out from which +bin we should serve this request by looking in _S_binmap. +</p><p> +A quick look at _S_bin[ bin ].first[ 0 ] tells us if there are any blocks of +this size on the freelist (0). If this is not NULL - fine, just remove the +block that _S_bin[ bin ].first[ 0 ] points to from the list, +update _S_bin[ bin ].first[ 0 ] and return a pointer to that blocks data. +</p><p> +If the freelist is empty (the pointer is NULL) we must get memory from the +system and build us a freelist within this memory. All requests for new memory +is made in chunks of _S_chunk_size. Knowing the size of a block_record and +the bytes that this bin stores we then calculate how many blocks we can create +within this chunk, build the list, remove the first block, update the pointer +(_S_bin[ bin ].first[ 0 ]) and return a pointer to that blocks data. +</p><p> +Deallocation is equally simple; the pointer is casted back to a block_record +pointer, lookup which bin to use based on the size, add the block to the front +of the global freelist and update the pointer as needed +(_S_bin[ bin ].first[ 0 ]). +</p><p> +The decision to add deallocated blocks to the front of the freelist was made +after a set of performance measurements that showed that this is roughly 10% +faster than maintaining a set of "last pointers" as well. +</p></div><div class="section" title="Multiple Thread Example"><div class="titlepage"><div><div><h3 class="title"><a id="allocator.mt.example_multi"/>Multiple Thread Example</h3></div></div></div><p> +In the ST example we never used the thread_id variable present in each block. +Let's start by explaining the purpose of this in a MT application. +</p><p> +The concept of "ownership" was introduced since many MT applications +allocate and deallocate memory to shared containers from different +threads (such as a cache shared amongst all threads). This introduces +a problem if the allocator only returns memory to the current threads +freelist (I.e., there might be one thread doing all the allocation and +thus obtaining ever more memory from the system and another thread +that is getting a longer and longer freelist - this will in the end +consume all available memory). +</p><p> +Each time a block is moved from the global list (where ownership is +irrelevant), to a threads freelist (or when a new freelist is built +from a chunk directly onto a threads freelist or when a deallocation +occurs on a block which was not allocated by the same thread id as the +one doing the deallocation) the thread id is set to the current one. +</p><p> +What's the use? Well, when a deallocation occurs we can now look at +the thread id and find out if it was allocated by another thread id +and decrease the used counter of that thread instead, thus keeping the +free and used counters correct. And keeping the free and used counters +corrects is very important since the relationship between these two +variables decides if memory should be returned to the global pool or +not when a deallocation occurs. +</p><p> +When the application requests memory (calling allocate()) we first +look at the requested size and if this is >_S_max_bytes we call new() +directly and return. +</p><p> +If the requested size is within limits we start by finding out from which +bin we should serve this request by looking in _S_binmap. +</p><p> +A call to _S_get_thread_id() returns the thread id for the calling thread +(and if no value has been set in _S_thread_key, a new id is assigned and +returned). +</p><p> +A quick look at _S_bin[ bin ].first[ thread_id ] tells us if there are +any blocks of this size on the current threads freelist. If this is +not NULL - fine, just remove the block that _S_bin[ bin ].first[ +thread_id ] points to from the list, update _S_bin[ bin ].first[ +thread_id ], update the free and used counters and return a pointer to +that blocks data. +</p><p> +If the freelist is empty (the pointer is NULL) we start by looking at +the global freelist (0). If there are blocks available on the global +freelist we lock this bins mutex and move up to block_count (the +number of blocks of this bins size that will fit into a _S_chunk_size) +or until end of list - whatever comes first - to the current threads +freelist and at the same time change the thread_id ownership and +update the counters and pointers. When the bins mutex has been +unlocked, we remove the block that _S_bin[ bin ].first[ thread_id ] +points to from the list, update _S_bin[ bin ].first[ thread_id ], +update the free and used counters, and return a pointer to that blocks +data. +</p><p> +The reason that the number of blocks moved to the current threads +freelist is limited to block_count is to minimize the chance that a +subsequent deallocate() call will return the excess blocks to the +global freelist (based on the _S_freelist_headroom calculation, see +below). +</p><p> +However if there isn't any memory on the global pool we need to get +memory from the system - this is done in exactly the same way as in a +single threaded application with one major difference; the list built +in the newly allocated memory (of _S_chunk_size size) is added to the +current threads freelist instead of to the global. +</p><p> +The basic process of a deallocation call is simple: always add the +block to the front of the current threads freelist and update the +counters and pointers (as described earlier with the specific check of +ownership that causes the used counter of the thread that originally +allocated the block to be decreased instead of the current threads +counter). +</p><p> +And here comes the free and used counters to service. Each time a +deallocation() call is made, the length of the current threads +freelist is compared to the amount memory in use by this thread. +</p><p> +Let's go back to the example of an application that has one thread +that does all the allocations and one that deallocates. Both these +threads use say 516 32-byte blocks that was allocated during thread +creation for example. Their used counters will both say 516 at this +point. The allocation thread now grabs 1000 32-byte blocks and puts +them in a shared container. The used counter for this thread is now +1516. +</p><p> +The deallocation thread now deallocates 500 of these blocks. For each +deallocation made the used counter of the allocating thread is +decreased and the freelist of the deallocation thread gets longer and +longer. But the calculation made in deallocate() will limit the length +of the freelist in the deallocation thread to _S_freelist_headroom % +of it's used counter. In this case, when the freelist (given that the +_S_freelist_headroom is at it's default value of 10%) exceeds 52 +(516/10) blocks will be returned to the global pool where the +allocating thread may pick them up and reuse them. +</p><p> +In order to reduce lock contention (since this requires this bins +mutex to be locked) this operation is also made in chunks of blocks +(just like when chunks of blocks are moved from the global freelist to +a threads freelist mentioned above). The "formula" used can probably +be improved to further reduce the risk of blocks being "bounced back +and forth" between freelists. +</p></div></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="bk01pt03ch19s07.html">Prev</a> </td><td align="center"><a accesskey="u" href="extensions.html">Up</a></td><td align="right"> <a accesskey="n" href="bitmap_allocator.html">Next</a></td></tr><tr><td align="left" valign="top">Diagnostics </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> bitmap_allocator</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/ext_compile_checks.html b/libstdc++-v3/doc/html/manual/ext_compile_checks.html new file mode 100644 index 000000000..c648797c1 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/ext_compile_checks.html @@ -0,0 +1,40 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Chapter 16. Compile Time Checks</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="extensions.html" title="Part III. Extensions"/><link rel="prev" href="bk01pt03pr01.html" title=""/><link rel="next" href="debug_mode.html" title="Chapter 17. Debug Mode"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 16. Compile Time Checks</th></tr><tr><td align="left"><a accesskey="p" href="bk01pt03pr01.html">Prev</a> </td><th width="60%" align="center">Part III. + Extensions + +</th><td align="right"> <a accesskey="n" href="debug_mode.html">Next</a></td></tr></table><hr/></div><div class="chapter" title="Chapter 16. Compile Time Checks"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.compile_checks"/>Chapter 16. Compile Time Checks</h2></div></div></div><p> + Also known as concept checking. + </p><p>In 1999, SGI added <span class="emphasis"><em>concept checkers</em></span> to their implementation + of the STL: code which checked the template parameters of + instantiated pieces of the STL, in order to insure that the parameters + being used met the requirements of the standard. For example, + the Standard requires that types passed as template parameters to + <code class="code">vector</code> be <span class="quote">“<span class="quote">Assignable</span>”</span> (which means what you think + it means). The checking was done during compilation, and none of + the code was executed at runtime. + </p><p>Unfortunately, the size of the compiler files grew significantly + as a result. The checking code itself was cumbersome. And bugs + were found in it on more than one occasion. + </p><p>The primary author of the checking code, Jeremy Siek, had already + started work on a replacement implementation. The new code has been + formally reviewed and accepted into + <a class="link" href="http://www.boost.org/libs/concept_check/concept_check.htm">the + Boost libraries</a>, and we are pleased to incorporate it into the + GNU C++ library. + </p><p>The new version imposes a much smaller space overhead on the generated + object file. The checks are also cleaner and easier to read and + understand. + </p><p>They are off by default for all versions of GCC from 3.0 to 3.4 (the + latest release at the time of writing). + They can be enabled at configure time with + <a class="link" href="configure.html" title="Configure"><code class="literal">--enable-concept-checks</code></a>. + You can enable them on a per-translation-unit basis with + <code class="code">#define _GLIBCXX_CONCEPT_CHECKS</code> for GCC 3.4 and higher + (or with <code class="code">#define _GLIBCPP_CONCEPT_CHECKS</code> for versions + 3.1, 3.2 and 3.3). + </p><p>Please note that the upcoming C++ standard has first-class + support for template parameter constraints based on concepts in the core + language. This will obviate the need for the library-simulated concept + checking described above. + </p></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="bk01pt03pr01.html">Prev</a> </td><td align="center"><a accesskey="u" href="extensions.html">Up</a></td><td align="right"> <a accesskey="n" href="debug_mode.html">Next</a></td></tr><tr><td align="left" valign="top"> </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Chapter 17. Debug Mode</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/ext_concurrency.html b/libstdc++-v3/doc/html/manual/ext_concurrency.html new file mode 100644 index 000000000..99718e04f --- /dev/null +++ b/libstdc++-v3/doc/html/manual/ext_concurrency.html @@ -0,0 +1,91 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Chapter 28. Concurrency</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="extensions.html" title="Part III. Extensions"/><link rel="prev" href="ext_demangling.html" title="Chapter 27. Demangling"/><link rel="next" href="bk01pt03ch28s02.html" title="Implementation"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 28. Concurrency</th></tr><tr><td align="left"><a accesskey="p" href="ext_demangling.html">Prev</a> </td><th width="60%" align="center">Part III. + Extensions + +</th><td align="right"> <a accesskey="n" href="bk01pt03ch28s02.html">Next</a></td></tr></table><hr/></div><div class="chapter" title="Chapter 28. Concurrency"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.concurrency"/>Chapter 28. Concurrency</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="ext_concurrency.html#manual.ext.concurrency.design">Design</a></span></dt><dd><dl><dt><span class="section"><a href="ext_concurrency.html#manual.ext.concurrency.design.threads">Interface to Locks and Mutexes</a></span></dt><dt><span class="section"><a href="ext_concurrency.html#manual.ext.concurrency.design.atomics">Interface to Atomic Functions</a></span></dt></dl></dd><dt><span class="section"><a href="bk01pt03ch28s02.html">Implementation</a></span></dt><dd><dl><dt><span class="section"><a href="bk01pt03ch28s02.html#manual.ext.concurrency.impl.atomic_fallbacks">Using Builtin Atomic Functions</a></span></dt><dt><span class="section"><a href="bk01pt03ch28s02.html#manual.ext.concurrency.impl.thread">Thread Abstraction</a></span></dt></dl></dd><dt><span class="section"><a href="bk01pt03ch28s03.html">Use</a></span></dt></dl></div><div class="section" title="Design"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.concurrency.design"/>Design</h2></div></div></div><div class="section" title="Interface to Locks and Mutexes"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.concurrency.design.threads"/>Interface to Locks and Mutexes</h3></div></div></div><p>The file <ext/concurrence.h> contains all the higher-level +constructs for playing with threads. In contrast to the atomics layer, +the concurrence layer consists largely of types. All types are defined within <code class="code">namespace __gnu_cxx</code>. +</p><p> +These types can be used in a portable manner, regardless of the +specific environment. They are carefully designed to provide optimum +efficiency and speed, abstracting out underlying thread calls and +accesses when compiling for single-threaded situations (even on hosts +that support multiple threads.) +</p><p>The enumerated type <code class="code">_Lock_policy</code> details the set of +available locking +policies: <code class="code">_S_single</code>, <code class="code">_S_mutex</code>, +and <code class="code">_S_atomic</code>. +</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><code class="code">_S_single</code></p><p>Indicates single-threaded code that does not need locking. +</p></li><li class="listitem"><p><code class="code">_S_mutex</code></p><p>Indicates multi-threaded code using thread-layer abstractions. +</p></li><li class="listitem"><p><code class="code">_S_atomic</code></p><p>Indicates multi-threaded code using atomic operations. +</p></li></ul></div><p>The compile-time constant <code class="code">__default_lock_policy</code> is set +to one of the three values above, depending on characteristics of the +host environment and the current compilation flags. +</p><p>Two more datatypes make up the rest of the +interface: <code class="code">__mutex</code>, and <code class="code">__scoped_lock</code>. +</p><p> +</p><p>The scoped lock idiom is well-discussed within the C++ +community. This version takes a <code class="code">__mutex</code> reference, and +locks it during construction of <code class="code">__scoped_locke</code> and +unlocks it during destruction. This is an efficient way of locking +critical sections, while retaining exception-safety. +</p></div><div class="section" title="Interface to Atomic Functions"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.concurrency.design.atomics"/>Interface to Atomic Functions</h3></div></div></div><p> +Two functions and one type form the base of atomic support. +</p><p>The type <code class="code">_Atomic_word</code> is a signed integral type +supporting atomic operations. +</p><p> +The two functions functions are: +</p><pre class="programlisting"> +_Atomic_word +__exchange_and_add_dispatch(volatile _Atomic_word*, int); + +void +__atomic_add_dispatch(volatile _Atomic_word*, int); +</pre><p>Both of these functions are declared in the header file +<ext/atomicity.h>, and are in <code class="code">namespace __gnu_cxx</code>. +</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> +<code class="code"> +__exchange_and_add_dispatch +</code> +</p><p>Adds the second argument's value to the first argument. Returns the old value. +</p></li><li class="listitem"><p> +<code class="code"> +__atomic_add_dispatch +</code> +</p><p>Adds the second argument's value to the first argument. Has no return value. +</p></li></ul></div><p> +These functions forward to one of several specialized helper +functions, depending on the circumstances. For instance, +</p><p> +<code class="code"> +__exchange_and_add_dispatch +</code> +</p><p> +Calls through to either of: +</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><code class="code">__exchange_and_add</code> +</p><p>Multi-thread version. Inlined if compiler-generated builtin atomics +can be used, otherwise resolved at link time to a non-builtin code +sequence. +</p></li><li class="listitem"><p><code class="code">__exchange_and_add_single</code> +</p><p>Single threaded version. Inlined.</p></li></ul></div><p>However, only <code class="code">__exchange_and_add_dispatch</code> +and <code class="code">__atomic_add_dispatch</code> should be used. These functions +can be used in a portable manner, regardless of the specific +environment. They are carefully designed to provide optimum efficiency +and speed, abstracting out atomic accesses when they are not required +(even on hosts that support compiler intrinsics for atomic +operations.) +</p><p> +In addition, there are two macros +</p><p> +<code class="code"> +_GLIBCXX_READ_MEM_BARRIER +</code> +</p><p> +<code class="code"> +_GLIBCXX_WRITE_MEM_BARRIER +</code> +</p><p> +Which expand to the appropriate write and read barrier required by the +host hardware and operating system. +</p></div></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="ext_demangling.html">Prev</a> </td><td align="center"><a accesskey="u" href="extensions.html">Up</a></td><td align="right"> <a accesskey="n" href="bk01pt03ch28s02.html">Next</a></td></tr><tr><td align="left" valign="top">Chapter 27. Demangling </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Implementation</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/ext_containers.html b/libstdc++-v3/doc/html/manual/ext_containers.html new file mode 100644 index 000000000..d07860bbd --- /dev/null +++ b/libstdc++-v3/doc/html/manual/ext_containers.html @@ -0,0 +1,9 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Chapter 21. Containers</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="extensions.html" title="Part III. Extensions"/><link rel="prev" href="bitmap_allocator.html" title="bitmap_allocator"/><link rel="next" href="bk01pt03ch21s02.html" title="HP/SGI"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 21. Containers</th></tr><tr><td align="left"><a accesskey="p" href="bitmap_allocator.html">Prev</a> </td><th width="60%" align="center">Part III. + Extensions + +</th><td align="right"> <a accesskey="n" href="bk01pt03ch21s02.html">Next</a></td></tr></table><hr/></div><div class="chapter" title="Chapter 21. Containers"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.containers"/>Chapter 21. Containers</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="ext_containers.html#manual.ext.containers.pbds">Policy Based Data Structures</a></span></dt><dt><span class="section"><a href="bk01pt03ch21s02.html">HP/SGI</a></span></dt><dt><span class="section"><a href="bk01pt03ch21s03.html">Deprecated HP/SGI</a></span></dt></dl></div><p> + </p><div class="section" title="Policy Based Data Structures"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.containers.pbds"/>Policy Based Data Structures</h2></div></div></div><p> + <a class="link" href="http://gcc.gnu.org/onlinedocs/libstdc++/ext/pb_ds/index.html">More details here</a>. + </p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="bitmap_allocator.html">Prev</a> </td><td align="center"><a accesskey="u" href="extensions.html">Up</a></td><td align="right"> <a accesskey="n" href="bk01pt03ch21s02.html">Next</a></td></tr><tr><td align="left" valign="top">bitmap_allocator </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> HP/SGI</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/ext_demangling.html b/libstdc++-v3/doc/html/manual/ext_demangling.html new file mode 100644 index 000000000..0120bc2b0 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/ext_demangling.html @@ -0,0 +1,74 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Chapter 27. Demangling</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="extensions.html" title="Part III. Extensions"/><link rel="prev" href="ext_io.html" title="Chapter 26. Input and Output"/><link rel="next" href="ext_concurrency.html" title="Chapter 28. Concurrency"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 27. Demangling</th></tr><tr><td align="left"><a accesskey="p" href="ext_io.html">Prev</a> </td><th width="60%" align="center">Part III. + Extensions + +</th><td align="right"> <a accesskey="n" href="ext_concurrency.html">Next</a></td></tr></table><hr/></div><div class="chapter" title="Chapter 27. Demangling"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.demangle"/>Chapter 27. Demangling</h2></div></div></div><p> + Transforming C++ ABI identifiers (like RTTI symbols) into the + original C++ source identifiers is called + <span class="quote">“<span class="quote">demangling.</span>”</span> + </p><p> + If you have read the <a class="link" href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a01115.html">source + documentation for <code class="code">namespace abi</code></a> then you are + aware of the cross-vendor C++ ABI in use by GCC. One of the + exposed functions is used for demangling, + <code class="code">abi::__cxa_demangle</code>. + </p><p> + In programs like <span class="command"><strong>c++filt</strong></span>, the linker, and other tools + have the ability to decode C++ ABI names, and now so can you. + </p><p> + (The function itself might use different demanglers, but that's the + whole point of abstract interfaces. If we change the implementation, + you won't notice.) + </p><p> + Probably the only times you'll be interested in demangling at runtime + are when you're seeing <code class="code">typeid</code> strings in RTTI, or when + you're handling the runtime-support exception classes. For example: + </p><pre class="programlisting"> +#include <exception> +#include <iostream> +#include <cxxabi.h> + +struct empty { }; + +template <typename T, int N> + struct bar { }; + + +int main() +{ + int status; + char *realname; + + // exception classes not in <stdexcept>, thrown by the implementation + // instead of the user + std::bad_exception e; + realname = abi::__cxa_demangle(e.what(), 0, 0, &status); + std::cout << e.what() << "\t=> " << realname << "\t: " << status << '\n'; + free(realname); + + + // typeid + bar<empty,17> u; + const std::type_info &ti = typeid(u); + + realname = abi::__cxa_demangle(ti.name(), 0, 0, &status); + std::cout << ti.name() << "\t=> " << realname << "\t: " << status << '\n'; + free(realname); + + return 0; +} + </pre><p> + This prints + </p><pre class="screen"> + <code class="computeroutput"> + St13bad_exception => std::bad_exception : 0 + 3barI5emptyLi17EE => bar<empty, 17> : 0 + </code> + </pre><p> + The demangler interface is described in the source documentation + linked to above. It is actually written in C, so you don't need to + be writing C++ in order to demangle C++. (That also means we have to + use crummy memory management facilities, so don't forget to free() + the returned char array.) + </p></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="ext_io.html">Prev</a> </td><td align="center"><a accesskey="u" href="extensions.html">Up</a></td><td align="right"> <a accesskey="n" href="ext_concurrency.html">Next</a></td></tr><tr><td align="left" valign="top">Chapter 26. Input and Output </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Chapter 28. Concurrency</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/ext_io.html b/libstdc++-v3/doc/html/manual/ext_io.html new file mode 100644 index 000000000..aba0fe1d6 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/ext_io.html @@ -0,0 +1,50 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Chapter 26. Input and Output</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="extensions.html" title="Part III. Extensions"/><link rel="prev" href="ext_iterators.html" title="Chapter 25. Iterators"/><link rel="next" href="ext_demangling.html" title="Chapter 27. Demangling"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 26. Input and Output</th></tr><tr><td align="left"><a accesskey="p" href="ext_iterators.html">Prev</a> </td><th width="60%" align="center">Part III. + Extensions + +</th><td align="right"> <a accesskey="n" href="ext_demangling.html">Next</a></td></tr></table><hr/></div><div class="chapter" title="Chapter 26. Input and Output"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.io"/>Chapter 26. Input and Output</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="ext_io.html#manual.ext.io.filebuf_derived">Derived filebufs</a></span></dt></dl></div><p> + Extensions allowing <code class="code">filebuf</code>s to be constructed from + "C" types like FILE*s and file descriptors. + </p><div class="section" title="Derived filebufs"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.io.filebuf_derived"/>Derived filebufs</h2></div></div></div><p>The v2 library included non-standard extensions to construct + <code class="code">std::filebuf</code>s from C stdio types such as + <code class="code">FILE*</code>s and POSIX file descriptors. + Today the recommended way to use stdio types with libstdc++ + IOStreams is via the <code class="code">stdio_filebuf</code> class (see below), + but earlier releases provided slightly different mechanisms. + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>3.0.x <code class="code">filebuf</code>s have another ctor with this signature: + <code class="code">basic_filebuf(__c_file_type*, ios_base::openmode, int_type); + </code> + This comes in very handy in a number of places, such as + attaching Unix sockets, pipes, and anything else which uses file + descriptors, into the IOStream buffering classes. The three + arguments are as follows: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><code class="code">__c_file_type* F </code> + // the __c_file_type typedef usually boils down to stdio's FILE + </p></li><li class="listitem"><p><code class="code">ios_base::openmode M </code> + // same as all the other uses of openmode + </p></li><li class="listitem"><p><code class="code">int_type B </code> + // buffer size, defaults to BUFSIZ if not specified + </p></li></ul></div><p> + For those wanting to use file descriptors instead of FILE*'s, I + invite you to contemplate the mysteries of C's <code class="code">fdopen()</code>. + </p></li><li class="listitem"><p>In library snapshot 3.0.95 and later, <code class="code">filebuf</code>s bring + back an old extension: the <code class="code">fd()</code> member function. The + integer returned from this function can be used for whatever file + descriptors can be used for on your platform. Naturally, the + library cannot track what you do on your own with a file descriptor, + so if you perform any I/O directly, don't expect the library to be + aware of it. + </p></li><li class="listitem"><p>Beginning with 3.1, the extra <code class="code">filebuf</code> constructor and + the <code class="code">fd()</code> function were removed from the standard + filebuf. Instead, <code class="code"><ext/stdio_filebuf.h></code> contains + a derived class called + <a class="link" href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a00074.html"><code class="code">__gnu_cxx::stdio_filebuf</code></a>. + This class can be constructed from a C <code class="code">FILE*</code> or a file + descriptor, and provides the <code class="code">fd()</code> function. + </p></li></ul></div><p>If you want to access a <code class="code">filebuf</code>'s file descriptor to + implement file locking (e.g. using the <code class="code">fcntl()</code> system + call) then you might be interested in Henry Suter's RWLock class. + + </p><p> + </p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="ext_iterators.html">Prev</a> </td><td align="center"><a accesskey="u" href="extensions.html">Up</a></td><td align="right"> <a accesskey="n" href="ext_demangling.html">Next</a></td></tr><tr><td align="left" valign="top">Chapter 25. Iterators </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Chapter 27. Demangling</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/ext_iterators.html b/libstdc++-v3/doc/html/manual/ext_iterators.html new file mode 100644 index 000000000..8c00985c4 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/ext_iterators.html @@ -0,0 +1,14 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Chapter 25. Iterators</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="extensions.html" title="Part III. Extensions"/><link rel="prev" href="ext_numerics.html" title="Chapter 24. Numerics"/><link rel="next" href="ext_io.html" title="Chapter 26. Input and Output"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 25. Iterators</th></tr><tr><td align="left"><a accesskey="p" href="ext_numerics.html">Prev</a> </td><th width="60%" align="center">Part III. + Extensions + +</th><td align="right"> <a accesskey="n" href="ext_io.html">Next</a></td></tr></table><hr/></div><div class="chapter" title="Chapter 25. Iterators"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.iterators"/>Chapter 25. Iterators</h2></div></div></div><p>24.3.2 describes <code class="code">struct iterator</code>, which didn't exist in the + original HP STL implementation (the language wasn't rich enough at the + time). For backwards compatibility, base classes are provided which + declare the same nested typedefs: +</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>input_iterator</p></li><li class="listitem"><p>output_iterator</p></li><li class="listitem"><p>forward_iterator</p></li><li class="listitem"><p>bidirectional_iterator</p></li><li class="listitem"><p>random_access_iterator</p></li></ul></div><p>24.3.4 describes iterator operation <code class="code">distance</code>, which takes + two iterators and returns a result. It is extended by another signature + which takes two iterators and a reference to a result. The result is + modified, and the function returns nothing. +</p></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="ext_numerics.html">Prev</a> </td><td align="center"><a accesskey="u" href="extensions.html">Up</a></td><td align="right"> <a accesskey="n" href="ext_io.html">Next</a></td></tr><tr><td align="left" valign="top">Chapter 24. Numerics </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Chapter 26. Input and Output</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/ext_numerics.html b/libstdc++-v3/doc/html/manual/ext_numerics.html new file mode 100644 index 000000000..71d417c3a --- /dev/null +++ b/libstdc++-v3/doc/html/manual/ext_numerics.html @@ -0,0 +1,20 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Chapter 24. Numerics</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="extensions.html" title="Part III. Extensions"/><link rel="prev" href="ext_algorithms.html" title="Chapter 23. Algorithms"/><link rel="next" href="ext_iterators.html" title="Chapter 25. Iterators"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 24. Numerics</th></tr><tr><td align="left"><a accesskey="p" href="ext_algorithms.html">Prev</a> </td><th width="60%" align="center">Part III. + Extensions + +</th><td align="right"> <a accesskey="n" href="ext_iterators.html">Next</a></td></tr></table><hr/></div><div class="chapter" title="Chapter 24. Numerics"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.numerics"/>Chapter 24. Numerics</h2></div></div></div><p>26.4, the generalized numeric operations such as accumulate, are extended + with the following functions: +</p><pre class="programlisting"> + power (x, n); + power (x, n, moniod_operation);</pre><p>Returns, in FORTRAN syntax, "x ** n" where n>=0. In the + case of n == 0, returns the identity element for the + monoid operation. The two-argument signature uses multiplication (for + a true "power" implementation), but addition is supported as well. + The operation functor must be associative. +</p><p>The <code class="code">iota</code> function wins the award for Extension With the + Coolest Name. It "assigns sequentially increasing values to a range. + That is, it assigns value to *first, value + 1 to *(first + 1) and so + on." Quoted from SGI documentation. +</p><pre class="programlisting"> + void iota(_ForwardIter first, _ForwardIter last, _Tp value);</pre></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="ext_algorithms.html">Prev</a> </td><td align="center"><a accesskey="u" href="extensions.html">Up</a></td><td align="right"> <a accesskey="n" href="ext_iterators.html">Next</a></td></tr><tr><td align="left" valign="top">Chapter 23. Algorithms </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Chapter 25. Iterators</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/ext_utilities.html b/libstdc++-v3/doc/html/manual/ext_utilities.html new file mode 100644 index 000000000..d15057c27 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/ext_utilities.html @@ -0,0 +1,41 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Chapter 22. Utilities</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="extensions.html" title="Part III. Extensions"/><link rel="prev" href="bk01pt03ch21s03.html" title="Deprecated HP/SGI"/><link rel="next" href="ext_algorithms.html" title="Chapter 23. Algorithms"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 22. Utilities</th></tr><tr><td align="left"><a accesskey="p" href="bk01pt03ch21s03.html">Prev</a> </td><th width="60%" align="center">Part III. + Extensions + +</th><td align="right"> <a accesskey="n" href="ext_algorithms.html">Next</a></td></tr></table><hr/></div><div class="chapter" title="Chapter 22. Utilities"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.util"/>Chapter 22. Utilities</h2></div></div></div><p> + The <functional> header contains many additional functors + and helper functions, extending section 20.3. They are + implemented in the file stl_function.h: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><code class="code">identity_element</code> for addition and multiplication. * + </p></li><li class="listitem"><p>The functor <code class="code">identity</code>, whose <code class="code">operator()</code> + returns the argument unchanged. * + </p></li><li class="listitem"><p>Composition functors <code class="code">unary_function</code> and + <code class="code">binary_function</code>, and their helpers <code class="code">compose1</code> + and <code class="code">compose2</code>. * + </p></li><li class="listitem"><p><code class="code">select1st</code> and <code class="code">select2nd</code>, to strip pairs. * + </p></li><li class="listitem"><p><code class="code">project1st</code> and <code class="code">project2nd</code>. * </p></li><li class="listitem"><p>A set of functors/functions which always return the same result. They + are <code class="code">constant_void_fun</code>, <code class="code">constant_binary_fun</code>, + <code class="code">constant_unary_fun</code>, <code class="code">constant0</code>, + <code class="code">constant1</code>, and <code class="code">constant2</code>. * </p></li><li class="listitem"><p>The class <code class="code">subtractive_rng</code>. * </p></li><li class="listitem"><p>mem_fun adaptor helpers <code class="code">mem_fun1</code> and + <code class="code">mem_fun1_ref</code> are provided for backwards compatibility. </p></li></ul></div><p> + 20.4.1 can use several different allocators; they are described on the + main extensions page. +</p><p> + 20.4.3 is extended with a special version of + <code class="code">get_temporary_buffer</code> taking a second argument. The + argument is a pointer, which is ignored, but can be used to specify + the template type (instead of using explicit function template + arguments like the standard version does). That is, in addition to +</p><pre class="programlisting"> +get_temporary_buffer<int>(5); +</pre><p> +you can also use +</p><pre class="programlisting"> +get_temporary_buffer(5, (int*)0); +</pre><p> + A class <code class="code">temporary_buffer</code> is given in stl_tempbuf.h. * +</p><p> + The specialized algorithms of section 20.4.4 are extended with + <code class="code">uninitialized_copy_n</code>. * +</p></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="bk01pt03ch21s03.html">Prev</a> </td><td align="center"><a accesskey="u" href="extensions.html">Up</a></td><td align="right"> <a accesskey="n" href="ext_algorithms.html">Next</a></td></tr><tr><td align="left" valign="top">Deprecated HP/SGI </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Chapter 23. Algorithms</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/extensions.html b/libstdc++-v3/doc/html/manual/extensions.html new file mode 100644 index 000000000..7fae9078a --- /dev/null +++ b/libstdc++-v3/doc/html/manual/extensions.html @@ -0,0 +1,9 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Part III. Extensions</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="spine.html" title="The GNU C++ Library Manual"/><link rel="prev" href="io_and_c.html" title="Interacting with C"/><link rel="next" href="bk01pt03pr01.html" title=""/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Part III. + Extensions + +</th></tr><tr><td align="left"><a accesskey="p" href="io_and_c.html">Prev</a> </td><th width="60%" align="center">The GNU C++ Library Manual</th><td align="right"> <a accesskey="n" href="bk01pt03pr01.html">Next</a></td></tr></table><hr/></div><div class="part" title="Part III. Extensions"><div class="titlepage"><div><div><h1 class="title"><a id="manual.ext"/>Part III. + Extensions + <a id="id481867" class="indexterm"/> +</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="preface"><a href="bk01pt03pr01.html"/></span></dt><dt><span class="chapter"><a href="ext_compile_checks.html">16. Compile Time Checks</a></span></dt><dt><span class="chapter"><a href="debug_mode.html">17. Debug Mode</a></span></dt><dd><dl><dt><span class="section"><a href="debug_mode.html#manual.ext.debug_mode.intro">Intro</a></span></dt><dt><span class="section"><a href="bk01pt03ch17s02.html">Semantics</a></span></dt><dt><span class="section"><a href="bk01pt03ch17s03.html">Using</a></span></dt><dd><dl><dt><span class="section"><a href="bk01pt03ch17s03.html#debug_mode.using.mode">Using the Debug Mode</a></span></dt><dt><span class="section"><a href="bk01pt03ch17s03.html#debug_mode.using.specific">Using a Specific Debug Container</a></span></dt></dl></dd><dt><span class="section"><a href="bk01pt03ch17s04.html">Design</a></span></dt><dd><dl><dt><span class="section"><a href="bk01pt03ch17s04.html#debug_mode.design.goals">Goals</a></span></dt><dt><span class="section"><a href="bk01pt03ch17s04.html#debug_mode.design.methods">Methods</a></span></dt><dt><span class="section"><a href="bk01pt03ch17s04.html#debug_mode.design.other">Other Implementations</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="parallel_mode.html">18. Parallel Mode</a></span></dt><dd><dl><dt><span class="section"><a href="parallel_mode.html#manual.ext.parallel_mode.intro">Intro</a></span></dt><dt><span class="section"><a href="bk01pt03ch18s02.html">Semantics</a></span></dt><dt><span class="section"><a href="bk01pt03ch18s03.html">Using</a></span></dt><dd><dl><dt><span class="section"><a href="bk01pt03ch18s03.html#parallel_mode.using.prereq_flags">Prerequisite Compiler Flags</a></span></dt><dt><span class="section"><a href="bk01pt03ch18s03.html#parallel_mode.using.parallel_mode">Using Parallel Mode</a></span></dt><dt><span class="section"><a href="bk01pt03ch18s03.html#parallel_mode.using.specific">Using Specific Parallel Components</a></span></dt></dl></dd><dt><span class="section"><a href="bk01pt03ch18s04.html">Design</a></span></dt><dd><dl><dt><span class="section"><a href="bk01pt03ch18s04.html#parallel_mode.design.intro">Interface Basics</a></span></dt><dt><span class="section"><a href="bk01pt03ch18s04.html#parallel_mode.design.tuning">Configuration and Tuning</a></span></dt><dt><span class="section"><a href="bk01pt03ch18s04.html#parallel_mode.design.impl">Implementation Namespaces</a></span></dt></dl></dd><dt><span class="section"><a href="bk01pt03ch18s05.html">Testing</a></span></dt><dt><span class="bibliography"><a href="parallel_mode.html#parallel_mode.biblio">Bibliography</a></span></dt></dl></dd><dt><span class="chapter"><a href="profile_mode.html">19. Profile Mode</a></span></dt><dd><dl><dt><span class="section"><a href="profile_mode.html#manual.ext.profile_mode.intro">Intro</a></span></dt><dd><dl><dt><span class="section"><a href="profile_mode.html#manual.ext.profile_mode.using">Using the Profile Mode</a></span></dt><dt><span class="section"><a href="profile_mode.html#manual.ext.profile_mode.tuning">Tuning the Profile Mode</a></span></dt></dl></dd><dt><span class="section"><a href="bk01pt03ch19s02.html">Design</a></span></dt><dd><dl><dt><span class="section"><a href="bk01pt03ch19s02.html#manual.ext.profile_mode.design.wrapper">Wrapper Model</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s02.html#manual.ext.profile_mode.design.instrumentation">Instrumentation</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s02.html#manual.ext.profile_mode.design.rtlib">Run Time Behavior</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s02.html#manual.ext.profile_mode.design.analysis">Analysis and Diagnostics</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s02.html#manual.ext.profile_mode.design.cost-model">Cost Model</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s02.html#manual.ext.profile_mode.design.reports">Reports</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s02.html#manual.ext.profile_mode.design.testing">Testing</a></span></dt></dl></dd><dt><span class="section"><a href="bk01pt03ch19s03.html">Extensions for Custom Containers</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s04.html">Empirical Cost Model</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s05.html">Implementation Issues</a></span></dt><dd><dl><dt><span class="section"><a href="bk01pt03ch19s05.html#manual.ext.profile_mode.implementation.stack">Stack Traces</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s05.html#manual.ext.profile_mode.implementation.symbols">Symbolization of Instruction Addresses</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s05.html#manual.ext.profile_mode.implementation.concurrency">Concurrency</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s05.html#manual.ext.profile_mode.implementation.stdlib-in-proflib">Using the Standard Library in the Instrumentation Implementation</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s05.html#manual.ext.profile_mode.implementation.malloc-hooks">Malloc Hooks</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s05.html#manual.ext.profile_mode.implementation.construction-destruction">Construction and Destruction of Global Objects</a></span></dt></dl></dd><dt><span class="section"><a href="bk01pt03ch19s06.html">Developer Information</a></span></dt><dd><dl><dt><span class="section"><a href="bk01pt03ch19s06.html#manual.ext.profile_mode.developer.bigpic">Big Picture</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s06.html#manual.ext.profile_mode.developer.howto">How To Add A Diagnostic</a></span></dt></dl></dd><dt><span class="section"><a href="bk01pt03ch19s07.html">Diagnostics</a></span></dt><dd><dl><dt><span class="section"><a href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.template">Diagnostic Template</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.containers">Containers</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.algorithms">Algorithms</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.locality">Data Locality</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.mthread">Multithreaded Data Access</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.statistics">Statistics</a></span></dt></dl></dd><dt><span class="bibliography"><a href="profile_mode.html#profile_mode.biblio">Bibliography</a></span></dt></dl></dd><dt><span class="chapter"><a href="ext_allocators.html">20. Allocators</a></span></dt><dd><dl><dt><span class="section"><a href="ext_allocators.html#manual.ext.allocator.mt">mt_allocator</a></span></dt><dd><dl><dt><span class="section"><a href="ext_allocators.html#allocator.mt.intro">Intro</a></span></dt><dt><span class="section"><a href="ext_allocators.html#allocator.mt.design_issues">Design Issues</a></span></dt><dt><span class="section"><a href="ext_allocators.html#allocator.mt.impl">Implementation</a></span></dt><dt><span class="section"><a href="ext_allocators.html#allocator.mt.example_single">Single Thread Example</a></span></dt><dt><span class="section"><a href="ext_allocators.html#allocator.mt.example_multi">Multiple Thread Example</a></span></dt></dl></dd><dt><span class="section"><a href="bitmap_allocator.html">bitmap_allocator</a></span></dt><dd><dl><dt><span class="section"><a href="bitmap_allocator.html#allocator.bitmap.design">Design</a></span></dt><dt><span class="section"><a href="bitmap_allocator.html#allocator.bitmap.impl">Implementation</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="ext_containers.html">21. Containers</a></span></dt><dd><dl><dt><span class="section"><a href="ext_containers.html#manual.ext.containers.pbds">Policy Based Data Structures</a></span></dt><dt><span class="section"><a href="bk01pt03ch21s02.html">HP/SGI</a></span></dt><dt><span class="section"><a href="bk01pt03ch21s03.html">Deprecated HP/SGI</a></span></dt></dl></dd><dt><span class="chapter"><a href="ext_utilities.html">22. Utilities</a></span></dt><dt><span class="chapter"><a href="ext_algorithms.html">23. Algorithms</a></span></dt><dt><span class="chapter"><a href="ext_numerics.html">24. Numerics</a></span></dt><dt><span class="chapter"><a href="ext_iterators.html">25. Iterators</a></span></dt><dt><span class="chapter"><a href="ext_io.html">26. Input and Output</a></span></dt><dd><dl><dt><span class="section"><a href="ext_io.html#manual.ext.io.filebuf_derived">Derived filebufs</a></span></dt></dl></dd><dt><span class="chapter"><a href="ext_demangling.html">27. Demangling</a></span></dt><dt><span class="chapter"><a href="ext_concurrency.html">28. Concurrency</a></span></dt><dd><dl><dt><span class="section"><a href="ext_concurrency.html#manual.ext.concurrency.design">Design</a></span></dt><dd><dl><dt><span class="section"><a href="ext_concurrency.html#manual.ext.concurrency.design.threads">Interface to Locks and Mutexes</a></span></dt><dt><span class="section"><a href="ext_concurrency.html#manual.ext.concurrency.design.atomics">Interface to Atomic Functions</a></span></dt></dl></dd><dt><span class="section"><a href="bk01pt03ch28s02.html">Implementation</a></span></dt><dd><dl><dt><span class="section"><a href="bk01pt03ch28s02.html#manual.ext.concurrency.impl.atomic_fallbacks">Using Builtin Atomic Functions</a></span></dt><dt><span class="section"><a href="bk01pt03ch28s02.html#manual.ext.concurrency.impl.thread">Thread Abstraction</a></span></dt></dl></dd><dt><span class="section"><a href="bk01pt03ch28s03.html">Use</a></span></dt></dl></dd></dl></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="io_and_c.html">Prev</a> </td><td align="center"><a accesskey="u" href="spine.html">Up</a></td><td align="right"> <a accesskey="n" href="bk01pt03pr01.html">Next</a></td></tr><tr><td align="left" valign="top">Interacting with C </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> </td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/facets.html b/libstdc++-v3/doc/html/manual/facets.html new file mode 100644 index 000000000..cfe89bc0d --- /dev/null +++ b/libstdc++-v3/doc/html/manual/facets.html @@ -0,0 +1,728 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Facets</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="localization.html" title="Chapter 8. Localization"/><link rel="prev" href="localization.html" title="Chapter 8. Localization"/><link rel="next" href="containers.html" title="Chapter 9. Containers"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Facets</th></tr><tr><td align="left"><a accesskey="p" href="localization.html">Prev</a> </td><th width="60%" align="center">Chapter 8. + Localization + +</th><td align="right"> <a accesskey="n" href="containers.html">Next</a></td></tr></table><hr/></div><div class="section" title="Facets"><div class="titlepage"><div><div><h2 class="title"><a id="std.localization.facet"/>Facets</h2></div></div></div><div class="section" title="ctype"><div class="titlepage"><div><div><h3 class="title"><a id="std.localization.facet.ctype"/>ctype</h3></div></div></div><div class="section" title="Implementation"><div class="titlepage"><div><div><h4 class="title"><a id="facet.ctype.impl"/>Implementation</h4></div></div></div><div class="section" title="Specializations"><div class="titlepage"><div><div><h5 class="title"><a id="id476560"/>Specializations</h5></div></div></div><p> +For the required specialization codecvt<wchar_t, char, mbstate_t> , +conversions are made between the internal character set (always UCS4 +on GNU/Linux) and whatever the currently selected locale for the +LC_CTYPE category implements. +</p><p> +The two required specializations are implemented as follows: +</p><p> +<code class="code"> +ctype<char> +</code> +</p><p> +This is simple specialization. Implementing this was a piece of cake. +</p><p> +<code class="code"> +ctype<wchar_t> +</code> +</p><p> +This specialization, by specifying all the template parameters, pretty +much ties the hands of implementors. As such, the implementation is +straightforward, involving mcsrtombs for the conversions between char +to wchar_t and wcsrtombs for conversions between wchar_t and char. +</p><p> +Neither of these two required specializations deals with Unicode +characters. +</p></div></div><div class="section" title="Future"><div class="titlepage"><div><div><h4 class="title"><a id="facet.ctype.future"/>Future</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + How to deal with the global locale issue? + </p></li><li class="listitem"><p> + How to deal with different types than char, wchar_t? </p></li><li class="listitem"><p> + Overlap between codecvt/ctype: narrow/widen + </p></li><li class="listitem"><p> + Mask typedef in codecvt_base, argument types in codecvt. what + is know about this type? + </p></li><li class="listitem"><p> + Why mask* argument in codecvt? + </p></li><li class="listitem"><p> + Can this be made (more) generic? is there a simple way to + straighten out the configure-time mess that is a by-product of + this class? + </p></li><li class="listitem"><p> + Get the ctype<wchar_t>::mask stuff under control. Need to + make some kind of static table, and not do lookup every time + somebody hits the do_is... functions. Too bad we can't just + redefine mask for ctype<wchar_t> + </p></li><li class="listitem"><p> + Rename abstract base class. See if just smash-overriding is a + better approach. Clarify, add sanity to naming. + </p></li></ul></div></div><div class="bibliography" title="Bibliography"><div class="titlepage"><div><div><h4 class="title"><a id="facet.ctype.biblio"/>Bibliography</h4></div></div></div><div class="biblioentry"><a id="id476684"/><p><span class="citetitle"><em class="citetitle"> + The GNU C Library + </em>. </span><span class="author"><span class="firstname">Roland</span> <span class="surname">McGrath</span>. </span><span class="author"><span class="firstname">Ulrich</span> <span class="surname">Drepper</span>. </span><span class="copyright">Copyright © 2007 FSF. </span><span class="pagenums">Chapters 6 Character Set Handling and 7 Locales and Internationalization. </span></p></div><div class="biblioentry"><a id="id476724"/><p><span class="citetitle"><em class="citetitle"> + Correspondence + </em>. </span><span class="author"><span class="firstname">Ulrich</span> <span class="surname">Drepper</span>. </span><span class="copyright">Copyright © 2002 . </span></p></div><div class="biblioentry"><a id="id476750"/><p><span class="citetitle"><em class="citetitle"> + ISO/IEC 14882:1998 Programming languages - C++ + </em>. </span><span class="copyright">Copyright © 1998 ISO. </span></p></div><div class="biblioentry"><a id="id476769"/><p><span class="citetitle"><em class="citetitle"> + ISO/IEC 9899:1999 Programming languages - C + </em>. </span><span class="copyright">Copyright © 1999 ISO. </span></p></div><div class="biblioentry"><a id="id476788"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + The Open Group Base Specifications, Issue 6 (IEEE Std. 1003.1-2004) + </em>. </span><span class="copyright">Copyright © 1999 + The Open Group/The Institute of Electrical and Electronics Engineers, Inc.. </span></p></div><div class="biblioentry"><a id="id476817"/><p><span class="citetitle"><em class="citetitle"> + The C++ Programming Language, Special Edition + </em>. </span><span class="author"><span class="firstname">Bjarne</span> <span class="surname">Stroustrup</span>. </span><span class="copyright">Copyright © 2000 Addison Wesley, Inc.. </span><span class="pagenums">Appendix D. </span><span class="publisher"><span class="publishername"> + Addison Wesley + . </span></span></p></div><div class="biblioentry"><a id="id476856"/><p><span class="citetitle"><em class="citetitle"> + Standard C++ IOStreams and Locales + </em>. </span><span class="subtitle"> + Advanced Programmer's Guide and Reference + . </span><span class="author"><span class="firstname">Angelika</span> <span class="surname">Langer</span>. </span><span class="author"><span class="firstname">Klaus</span> <span class="surname">Kreft</span>. </span><span class="copyright">Copyright © 2000 Addison Wesley Longman, Inc.. </span><span class="publisher"><span class="publishername"> + Addison Wesley Longman + . </span></span></p></div></div></div><div class="section" title="codecvt"><div class="titlepage"><div><div><h3 class="title"><a id="std.localization.facet.codecvt"/>codecvt</h3></div></div></div><p> +The standard class codecvt attempts to address conversions between +different character encoding schemes. In particular, the standard +attempts to detail conversions between the implementation-defined wide +characters (hereafter referred to as wchar_t) and the standard type +char that is so beloved in classic <span class="quote">“<span class="quote">C</span>”</span> (which can now be +referred to as narrow characters.) This document attempts to describe +how the GNU libstdc++ implementation deals with the conversion between +wide and narrow characters, and also presents a framework for dealing +with the huge number of other encodings that iconv can convert, +including Unicode and UTF8. Design issues and requirements are +addressed, and examples of correct usage for both the required +specializations for wide and narrow characters and the +implementation-provided extended functionality are given. +</p><div class="section" title="Requirements"><div class="titlepage"><div><div><h4 class="title"><a id="facet.codecvt.req"/>Requirements</h4></div></div></div><p> +Around page 425 of the C++ Standard, this charming heading comes into view: +</p><div class="blockquote"><blockquote class="blockquote"><p> +22.2.1.5 - Template class codecvt +</p></blockquote></div><p> +The text around the codecvt definition gives some clues: +</p><div class="blockquote"><blockquote class="blockquote"><p> +<span class="emphasis"><em> +-1- The class codecvt<internT,externT,stateT> is for use when +converting from one codeset to another, such as from wide characters +to multibyte characters, between wide character encodings such as +Unicode and EUC. +</em></span> +</p></blockquote></div><p> +Hmm. So, in some unspecified way, Unicode encodings and +translations between other character sets should be handled by this +class. +</p><div class="blockquote"><blockquote class="blockquote"><p> +<span class="emphasis"><em> +-2- The stateT argument selects the pair of codesets being mapped between. +</em></span> +</p></blockquote></div><p> +Ah ha! Another clue... +</p><div class="blockquote"><blockquote class="blockquote"><p> +<span class="emphasis"><em> +-3- The instantiations required in the Table ?? +(lib.locale.category), namely codecvt<wchar_t,char,mbstate_t> and +codecvt<char,char,mbstate_t>, convert the implementation-defined +native character set. codecvt<char,char,mbstate_t> implements a +degenerate conversion; it does not convert at +all. codecvt<wchar_t,char,mbstate_t> converts between the native +character sets for tiny and wide characters. Instantiations on +mbstate_t perform conversion between encodings known to the library +implementor. Other encodings can be converted by specializing on a +user-defined stateT type. The stateT object can contain any state that +is useful to communicate to or from the specialized do_convert member. +</em></span> +</p></blockquote></div><p> +At this point, a couple points become clear: +</p><p> +One: The standard clearly implies that attempts to add non-required +(yet useful and widely used) conversions need to do so through the +third template parameter, stateT.</p><p> +Two: The required conversions, by specifying mbstate_t as the third +template parameter, imply an implementation strategy that is mostly +(or wholly) based on the underlying C library, and the functions +mcsrtombs and wcsrtombs in particular.</p></div><div class="section" title="Design"><div class="titlepage"><div><div><h4 class="title"><a id="facet.codecvt.design"/>Design</h4></div></div></div><div class="section" title="wchar_t Size"><div class="titlepage"><div><div><h5 class="title"><a id="codecvt.design.wchar_t_size"/><span class="type">wchar_t</span> Size</h5></div></div></div><p> + The simple implementation detail of wchar_t's size seems to + repeatedly confound people. Many systems use a two byte, + unsigned integral type to represent wide characters, and use an + internal encoding of Unicode or UCS2. (See AIX, Microsoft NT, + Java, others.) Other systems, use a four byte, unsigned integral + type to represent wide characters, and use an internal encoding + of UCS4. (GNU/Linux systems using glibc, in particular.) The C + programming language (and thus C++) does not specify a specific + size for the type wchar_t. + </p><p> + Thus, portable C++ code cannot assume a byte size (or endianness) either. + </p></div><div class="section" title="Support for Unicode"><div class="titlepage"><div><div><h5 class="title"><a id="codecvt.design.unicode"/>Support for Unicode</h5></div></div></div><p> + Probably the most frequently asked question about code conversion + is: "So dudes, what's the deal with Unicode strings?" + The dude part is optional, but apparently the usefulness of + Unicode strings is pretty widely appreciated. Sadly, this specific + encoding (And other useful encodings like UTF8, UCS4, ISO 8859-10, + etc etc etc) are not mentioned in the C++ standard. + </p><p> + A couple of comments: + </p><p> + The thought that all one needs to convert between two arbitrary + codesets is two types and some kind of state argument is + unfortunate. In particular, encodings may be stateless. The naming + of the third parameter as stateT is unfortunate, as what is really + needed is some kind of generalized type that accounts for the + issues that abstract encodings will need. The minimum information + that is required includes: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + Identifiers for each of the codesets involved in the + conversion. For example, using the iconv family of functions + from the Single Unix Specification (what used to be called + X/Open) hosted on the GNU/Linux operating system allows + bi-directional mapping between far more than the following + tantalizing possibilities: + </p><p> + (An edited list taken from <code class="code">`iconv --list`</code> on a + Red Hat 6.2/Intel system: + </p><div class="blockquote"><blockquote class="blockquote"><pre class="programlisting"> +8859_1, 8859_9, 10646-1:1993, 10646-1:1993/UCS4, ARABIC, ARABIC7, +ASCII, EUC-CN, EUC-JP, EUC-KR, EUC-TW, GREEK-CCIcode, GREEK, GREEK7-OLD, +GREEK7, GREEK8, HEBREW, ISO-8859-1, ISO-8859-2, ISO-8859-3, +ISO-8859-4, ISO-8859-5, ISO-8859-6, ISO-8859-7, ISO-8859-8, +ISO-8859-9, ISO-8859-10, ISO-8859-11, ISO-8859-13, ISO-8859-14, +ISO-8859-15, ISO-10646, ISO-10646/UCS2, ISO-10646/UCS4, +ISO-10646/UTF-8, ISO-10646/UTF8, SHIFT-JIS, SHIFT_JIS, UCS-2, UCS-4, +UCS2, UCS4, UNICODE, UNICODEBIG, UNICODELIcodeLE, US-ASCII, US, UTF-8, +UTF-16, UTF8, UTF16). +</pre></blockquote></div><p> +For iconv-based implementations, string literals for each of the +encodings (i.e. "UCS-2" and "UTF-8") are necessary, +although for other, +non-iconv implementations a table of enumerated values or some other +mechanism may be required. +</p></li><li class="listitem"><p> + Maximum length of the identifying string literal. +</p></li><li class="listitem"><p> + Some encodings require explicit endian-ness. As such, some kind + of endian marker or other byte-order marker will be necessary. See + "Footnotes for C/C++ developers" in Haible for more information on + UCS-2/Unicode endian issues. (Summary: big endian seems most likely, + however implementations, most notably Microsoft, vary.) +</p></li><li class="listitem"><p> + Types representing the conversion state, for conversions involving + the machinery in the "C" library, or the conversion descriptor, for + conversions using iconv (such as the type iconv_t.) Note that the + conversion descriptor encodes more information than a simple encoding + state type. +</p></li><li class="listitem"><p> + Conversion descriptors for both directions of encoding. (i.e., both + UCS-2 to UTF-8 and UTF-8 to UCS-2.) +</p></li><li class="listitem"><p> + Something to indicate if the conversion requested if valid. +</p></li><li class="listitem"><p> + Something to represent if the conversion descriptors are valid. +</p></li><li class="listitem"><p> + Some way to enforce strict type checking on the internal and + external types. As part of this, the size of the internal and + external types will need to be known. +</p></li></ul></div></div><div class="section" title="Other Issues"><div class="titlepage"><div><div><h5 class="title"><a id="codecvt.design.issues"/>Other Issues</h5></div></div></div><p> +In addition, multi-threaded and multi-locale environments also impact +the design and requirements for code conversions. In particular, they +affect the required specialization codecvt<wchar_t, char, mbstate_t> +when implemented using standard "C" functions. +</p><p> +Three problems arise, one big, one of medium importance, and one small. +</p><p> +First, the small: mcsrtombs and wcsrtombs may not be multithread-safe +on all systems required by the GNU tools. For GNU/Linux and glibc, +this is not an issue. +</p><p> +Of medium concern, in the grand scope of things, is that the functions +used to implement this specialization work on null-terminated +strings. Buffers, especially file buffers, may not be null-terminated, +thus giving conversions that end prematurely or are otherwise +incorrect. Yikes! +</p><p> +The last, and fundamental problem, is the assumption of a global +locale for all the "C" functions referenced above. For something like +C++ iostreams (where codecvt is explicitly used) the notion of +multiple locales is fundamental. In practice, most users may not run +into this limitation. However, as a quality of implementation issue, +the GNU C++ library would like to offer a solution that allows +multiple locales and or simultaneous usage with computationally +correct results. In short, libstdc++ is trying to offer, as an +option, a high-quality implementation, damn the additional complexity! +</p><p> +For the required specialization codecvt<wchar_t, char, mbstate_t> , +conversions are made between the internal character set (always UCS4 +on GNU/Linux) and whatever the currently selected locale for the +LC_CTYPE category implements. +</p></div></div><div class="section" title="Implementation"><div class="titlepage"><div><div><h4 class="title"><a id="facet.codecvt.impl"/>Implementation</h4></div></div></div><p> +The two required specializations are implemented as follows: +</p><p> +<code class="code"> +codecvt<char, char, mbstate_t> +</code> +</p><p> +This is a degenerate (i.e., does nothing) specialization. Implementing +this was a piece of cake. +</p><p> +<code class="code"> +codecvt<char, wchar_t, mbstate_t> +</code> +</p><p> +This specialization, by specifying all the template parameters, pretty +much ties the hands of implementors. As such, the implementation is +straightforward, involving mcsrtombs for the conversions between char +to wchar_t and wcsrtombs for conversions between wchar_t and char. +</p><p> +Neither of these two required specializations deals with Unicode +characters. As such, libstdc++ implements a partial specialization +of the codecvt class with and iconv wrapper class, encoding_state as the +third template parameter. +</p><p> +This implementation should be standards conformant. First of all, the +standard explicitly points out that instantiations on the third +template parameter, stateT, are the proper way to implement +non-required conversions. Second of all, the standard says (in Chapter +17) that partial specializations of required classes are a-ok. Third +of all, the requirements for the stateT type elsewhere in the standard +(see 21.1.2 traits typedefs) only indicate that this type be copy +constructible. +</p><p> +As such, the type encoding_state is defined as a non-templatized, POD +type to be used as the third type of a codecvt instantiation. This +type is just a wrapper class for iconv, and provides an easy interface +to iconv functionality. +</p><p> +There are two constructors for encoding_state: +</p><p> +<code class="code"> +encoding_state() : __in_desc(0), __out_desc(0) +</code> +</p><p> +This default constructor sets the internal encoding to some default +(currently UCS4) and the external encoding to whatever is returned by +nl_langinfo(CODESET). +</p><p> +<code class="code"> +encoding_state(const char* __int, const char* __ext) +</code> +</p><p> +This constructor takes as parameters string literals that indicate the +desired internal and external encoding. There are no defaults for +either argument. +</p><p> +One of the issues with iconv is that the string literals identifying +conversions are not standardized. Because of this, the thought of +mandating and or enforcing some set of pre-determined valid +identifiers seems iffy: thus, a more practical (and non-migraine +inducing) strategy was implemented: end-users can specify any string +(subject to a pre-determined length qualifier, currently 32 bytes) for +encodings. It is up to the user to make sure that these strings are +valid on the target system. +</p><p> +<code class="code"> +void +_M_init() +</code> +</p><p> +Strangely enough, this member function attempts to open conversion +descriptors for a given encoding_state object. If the conversion +descriptors are not valid, the conversion descriptors returned will +not be valid and the resulting calls to the codecvt conversion +functions will return error. +</p><p> +<code class="code"> +bool +_M_good() +</code> +</p><p> +Provides a way to see if the given encoding_state object has been +properly initialized. If the string literals describing the desired +internal and external encoding are not valid, initialization will +fail, and this will return false. If the internal and external +encodings are valid, but iconv_open could not allocate conversion +descriptors, this will also return false. Otherwise, the object is +ready to convert and will return true. +</p><p> +<code class="code"> +encoding_state(const encoding_state&) +</code> +</p><p> +As iconv allocates memory and sets up conversion descriptors, the copy +constructor can only copy the member data pertaining to the internal +and external code conversions, and not the conversion descriptors +themselves. +</p><p> +Definitions for all the required codecvt member functions are provided +for this specialization, and usage of codecvt<internal character type, +external character type, encoding_state> is consistent with other +codecvt usage. +</p></div><div class="section" title="Use"><div class="titlepage"><div><div><h4 class="title"><a id="facet.codecvt.use"/>Use</h4></div></div></div><p>A conversions involving string literal.</p><pre class="programlisting"> + typedef codecvt_base::result result; + typedef unsigned short unicode_t; + typedef unicode_t int_type; + typedef char ext_type; + typedef encoding_state state_type; + typedef codecvt<int_type, ext_type, state_type> unicode_codecvt; + + const ext_type* e_lit = "black pearl jasmine tea"; + int size = strlen(e_lit); + int_type i_lit_base[24] = + { 25088, 27648, 24832, 25344, 27392, 8192, 28672, 25856, 24832, 29184, + 27648, 8192, 27136, 24832, 29440, 27904, 26880, 28160, 25856, 8192, 29696, + 25856, 24832, 2560 + }; + const int_type* i_lit = i_lit_base; + const ext_type* efrom_next; + const int_type* ifrom_next; + ext_type* e_arr = new ext_type[size + 1]; + ext_type* eto_next; + int_type* i_arr = new int_type[size + 1]; + int_type* ito_next; + + // construct a locale object with the specialized facet. + locale loc(locale::classic(), new unicode_codecvt); + // sanity check the constructed locale has the specialized facet. + VERIFY( has_facet<unicode_codecvt>(loc) ); + const unicode_codecvt& cvt = use_facet<unicode_codecvt>(loc); + // convert between const char* and unicode strings + unicode_codecvt::state_type state01("UNICODE", "ISO_8859-1"); + initialize_state(state01); + result r1 = cvt.in(state01, e_lit, e_lit + size, efrom_next, + i_arr, i_arr + size, ito_next); + VERIFY( r1 == codecvt_base::ok ); + VERIFY( !int_traits::compare(i_arr, i_lit, size) ); + VERIFY( efrom_next == e_lit + size ); + VERIFY( ito_next == i_arr + size ); +</pre></div><div class="section" title="Future"><div class="titlepage"><div><div><h4 class="title"><a id="facet.codecvt.future"/>Future</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + a. things that are sketchy, or remain unimplemented: + do_encoding, max_length and length member functions + are only weakly implemented. I have no idea how to do + this correctly, and in a generic manner. Nathan? +</p></li><li class="listitem"><p> + b. conversions involving std::string + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + how should operators != and == work for string of + different/same encoding? + </p></li><li class="listitem"><p> + what is equal? A byte by byte comparison or an + encoding then byte comparison? + </p></li><li class="listitem"><p> + conversions between narrow, wide, and unicode strings + </p></li></ul></div></li><li class="listitem"><p> + c. conversions involving std::filebuf and std::ostream +</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + how to initialize the state object in a + standards-conformant manner? + </p></li><li class="listitem"><p> + how to synchronize the "C" and "C++" + conversion information? + </p></li><li class="listitem"><p> + wchar_t/char internal buffers and conversions between + internal/external buffers? + </p></li></ul></div></li></ul></div></div><div class="bibliography" title="Bibliography"><div class="titlepage"><div><div><h4 class="title"><a id="facet.codecvt.biblio"/>Bibliography</h4></div></div></div><div class="biblioentry"><a id="id477506"/><p><span class="citetitle"><em class="citetitle"> + The GNU C Library + </em>. </span><span class="author"><span class="firstname">Roland</span> <span class="surname">McGrath</span>. </span><span class="author"><span class="firstname">Ulrich</span> <span class="surname">Drepper</span>. </span><span class="copyright">Copyright © 2007 FSF. </span><span class="pagenums"> + Chapters 6 Character Set Handling and 7 Locales and Internationalization + . </span></p></div><div class="biblioentry"><a id="id477546"/><p><span class="citetitle"><em class="citetitle"> + Correspondence + </em>. </span><span class="author"><span class="firstname">Ulrich</span> <span class="surname">Drepper</span>. </span><span class="copyright">Copyright © 2002 . </span></p></div><div class="biblioentry"><a id="id477571"/><p><span class="citetitle"><em class="citetitle"> + ISO/IEC 14882:1998 Programming languages - C++ + </em>. </span><span class="copyright">Copyright © 1998 ISO. </span></p></div><div class="biblioentry"><a id="id477590"/><p><span class="citetitle"><em class="citetitle"> + ISO/IEC 9899:1999 Programming languages - C + </em>. </span><span class="copyright">Copyright © 1999 ISO. </span></p></div><div class="biblioentry"><a id="id477609"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + System Interface Definitions, Issue 7 (IEEE Std. 1003.1-2008) + </em>. </span><span class="copyright">Copyright © 2008 + The Open Group/The Institute of Electrical and Electronics + Engineers, Inc. + . </span></p></div><div class="biblioentry"><a id="id477639"/><p><span class="citetitle"><em class="citetitle"> + The C++ Programming Language, Special Edition + </em>. </span><span class="author"><span class="firstname">Bjarne</span> <span class="surname">Stroustrup</span>. </span><span class="copyright">Copyright © 2000 Addison Wesley, Inc.. </span><span class="pagenums">Appendix D. </span><span class="publisher"><span class="publishername"> + Addison Wesley + . </span></span></p></div><div class="biblioentry"><a id="id477677"/><p><span class="citetitle"><em class="citetitle"> + Standard C++ IOStreams and Locales + </em>. </span><span class="subtitle"> + Advanced Programmer's Guide and Reference + . </span><span class="author"><span class="firstname">Angelika</span> <span class="surname">Langer</span>. </span><span class="author"><span class="firstname">Klaus</span> <span class="surname">Kreft</span>. </span><span class="copyright">Copyright © 2000 Addison Wesley Longman, Inc.. </span><span class="publisher"><span class="publishername"> + Addison Wesley Longman + . </span></span></p></div><div class="biblioentry"><a id="id477724"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + A brief description of Normative Addendum 1 + </em>. </span><span class="author"><span class="firstname">Clive</span> <span class="surname">Feather</span>. </span><span class="pagenums">Extended Character Sets. </span></p></div><div class="biblioentry"><a id="id477754"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + The Unicode HOWTO + </em>. </span><span class="author"><span class="firstname">Bruno</span> <span class="surname">Haible</span>. </span></p></div><div class="biblioentry"><a id="id477779"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + UTF-8 and Unicode FAQ for Unix/Linux + </em>. </span><span class="author"><span class="firstname">Markus</span> <span class="surname">Khun</span>. </span></p></div></div></div><div class="section" title="messages"><div class="titlepage"><div><div><h3 class="title"><a id="manual.localization.facet.messages"/>messages</h3></div></div></div><p> +The std::messages facet implements message retrieval functionality +equivalent to Java's java.text.MessageFormat .using either GNU gettext +or IEEE 1003.1-200 functions. +</p><div class="section" title="Requirements"><div class="titlepage"><div><div><h4 class="title"><a id="facet.messages.req"/>Requirements</h4></div></div></div><p> +The std::messages facet is probably the most vaguely defined facet in +the standard library. It's assumed that this facility was built into +the standard library in order to convert string literals from one +locale to the other. For instance, converting the "C" locale's +<code class="code">const char* c = "please"</code> to a German-localized <code class="code">"bitte"</code> +during program execution. +</p><div class="blockquote"><blockquote class="blockquote"><p> +22.2.7.1 - Template class messages [lib.locale.messages] +</p></blockquote></div><p> +This class has three public member functions, which directly +correspond to three protected virtual member functions. +</p><p> +The public member functions are: +</p><p> +<code class="code">catalog open(const string&, const locale&) const</code> +</p><p> +<code class="code">string_type get(catalog, int, int, const string_type&) const</code> +</p><p> +<code class="code">void close(catalog) const</code> +</p><p> +While the virtual functions are: +</p><p> +<code class="code">catalog do_open(const string&, const locale&) const</code> +</p><div class="blockquote"><blockquote class="blockquote"><p> +<span class="emphasis"><em> +-1- Returns: A value that may be passed to get() to retrieve a +message, from the message catalog identified by the string name +according to an implementation-defined mapping. The result can be used +until it is passed to close(). Returns a value less than 0 if no such +catalog can be opened. +</em></span> +</p></blockquote></div><p> +<code class="code">string_type do_get(catalog, int, int, const string_type&) const</code> +</p><div class="blockquote"><blockquote class="blockquote"><p> +<span class="emphasis"><em> +-3- Requires: A catalog cat obtained from open() and not yet closed. +-4- Returns: A message identified by arguments set, msgid, and dfault, +according to an implementation-defined mapping. If no such message can +be found, returns dfault. +</em></span> +</p></blockquote></div><p> +<code class="code">void do_close(catalog) const</code> +</p><div class="blockquote"><blockquote class="blockquote"><p> +<span class="emphasis"><em> +-5- Requires: A catalog cat obtained from open() and not yet closed. +-6- Effects: Releases unspecified resources associated with cat. +-7- Notes: The limit on such resources, if any, is implementation-defined. +</em></span> +</p></blockquote></div></div><div class="section" title="Design"><div class="titlepage"><div><div><h4 class="title"><a id="facet.messages.design"/>Design</h4></div></div></div><p> +A couple of notes on the standard. +</p><p> +First, why is <code class="code">messages_base::catalog</code> specified as a typedef +to int? This makes sense for implementations that use +<code class="code">catopen</code>, but not for others. Fortunately, it's not heavily +used and so only a minor irritant. +</p><p> +Second, by making the member functions <code class="code">const</code>, it is +impossible to save state in them. Thus, storing away information used +in the 'open' member function for use in 'get' is impossible. This is +unfortunate. +</p><p> +The 'open' member function in particular seems to be oddly +designed. The signature seems quite peculiar. Why specify a <code class="code">const +string& </code> argument, for instance, instead of just <code class="code">const +char*</code>? Or, why specify a <code class="code">const locale&</code> argument that is +to be used in the 'get' member function? How, exactly, is this locale +argument useful? What was the intent? It might make sense if a locale +argument was associated with a given default message string in the +'open' member function, for instance. Quite murky and unclear, on +reflection. +</p><p> +Lastly, it seems odd that messages, which explicitly require code +conversion, don't use the codecvt facet. Because the messages facet +has only one template parameter, it is assumed that ctype, and not +codecvt, is to be used to convert between character sets. +</p><p> +It is implicitly assumed that the locale for the default message +string in 'get' is in the "C" locale. Thus, all source code is assumed +to be written in English, so translations are always from "en_US" to +other, explicitly named locales. +</p></div><div class="section" title="Implementation"><div class="titlepage"><div><div><h4 class="title"><a id="facet.messages.impl"/>Implementation</h4></div></div></div><div class="section" title="Models"><div class="titlepage"><div><div><h5 class="title"><a id="messages.impl.models"/>Models</h5></div></div></div><p> + This is a relatively simple class, on the face of it. The standard + specifies very little in concrete terms, so generic + implementations that are conforming yet do very little are the + norm. Adding functionality that would be useful to programmers and + comparable to Java's java.text.MessageFormat takes a bit of work, + and is highly dependent on the capabilities of the underlying + operating system. + </p><p> + Three different mechanisms have been provided, selectable via + configure flags: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + generic + </p><p> + This model does very little, and is what is used by default. + </p></li><li class="listitem"><p> + gnu + </p><p> + The gnu model is complete and fully tested. It's based on the + GNU gettext package, which is part of glibc. It uses the + functions <code class="code">textdomain, bindtextdomain, gettext</code> to + implement full functionality. Creating message catalogs is a + relatively straight-forward process and is lightly documented + below, and fully documented in gettext's distributed + documentation. + </p></li><li class="listitem"><p> + ieee_1003.1-200x + </p><p> + This is a complete, though untested, implementation based on + the IEEE standard. The functions <code class="code">catopen, catgets, + catclose</code> are used to retrieve locale-specific messages + given the appropriate message catalogs that have been + constructed for their use. Note, the script <code class="code"> + po2msg.sed</code> that is part of the gettext distribution can + convert gettext catalogs into catalogs that + <code class="code">catopen</code> can use. + </p></li></ul></div><p> +A new, standards-conformant non-virtual member function signature was +added for 'open' so that a directory could be specified with a given +message catalog. This simplifies calling conventions for the gnu +model. +</p></div><div class="section" title="The GNU Model"><div class="titlepage"><div><div><h5 class="title"><a id="messages.impl.gnu"/>The GNU Model</h5></div></div></div><p> + The messages facet, because it is retrieving and converting + between characters sets, depends on the ctype and perhaps the + codecvt facet in a given locale. In addition, underlying "C" + library locale support is necessary for more than just the + <code class="code">LC_MESSAGES</code> mask: <code class="code">LC_CTYPE</code> is also + necessary. To avoid any unpleasantness, all bits of the "C" mask + (i.e. <code class="code">LC_ALL</code>) are set before retrieving messages. + </p><p> + Making the message catalogs can be initially tricky, but become + quite simple with practice. For complete info, see the gettext + documentation. Here's an idea of what is required: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + Make a source file with the required string literals that need + to be translated. See <code class="code">intl/string_literals.cc</code> for + an example. + </p></li><li class="listitem"><p> + Make initial catalog (see "4 Making the PO Template File" from + the gettext docs).</p><p> + <code class="code"> xgettext --c++ --debug string_literals.cc -o libstdc++.pot </code> + </p></li><li class="listitem"><p>Make language and country-specific locale catalogs.</p><p> + <code class="code">cp libstdc++.pot fr_FR.po</code> + </p><p> + <code class="code">cp libstdc++.pot de_DE.po</code> + </p></li><li class="listitem"><p> + Edit localized catalogs in emacs so that strings are + translated. + </p><p> + <code class="code">emacs fr_FR.po</code> + </p></li><li class="listitem"><p>Make the binary mo files.</p><p> + <code class="code">msgfmt fr_FR.po -o fr_FR.mo</code> + </p><p> + <code class="code">msgfmt de_DE.po -o de_DE.mo</code> + </p></li><li class="listitem"><p>Copy the binary files into the correct directory structure.</p><p> + <code class="code">cp fr_FR.mo (dir)/fr_FR/LC_MESSAGES/libstdc++.mo</code> + </p><p> + <code class="code">cp de_DE.mo (dir)/de_DE/LC_MESSAGES/libstdc++.mo</code> + </p></li><li class="listitem"><p>Use the new message catalogs.</p><p> + <code class="code">locale loc_de("de_DE");</code> + </p><p> + <code class="code"> + use_facet<messages<char> >(loc_de).open("libstdc++", locale(), dir); + </code> + </p></li></ul></div></div></div><div class="section" title="Use"><div class="titlepage"><div><div><h4 class="title"><a id="facet.messages.use"/>Use</h4></div></div></div><p> + A simple example using the GNU model of message conversion. + </p><pre class="programlisting"> +#include <iostream> +#include <locale> +using namespace std; + +void test01() +{ + typedef messages<char>::catalog catalog; + const char* dir = + "/mnt/egcs/build/i686-pc-linux-gnu/libstdc++/po/share/locale"; + const locale loc_de("de_DE"); + const messages<char>& mssg_de = use_facet<messages<char> >(loc_de); + + catalog cat_de = mssg_de.open("libstdc++", loc_de, dir); + string s01 = mssg_de.get(cat_de, 0, 0, "please"); + string s02 = mssg_de.get(cat_de, 0, 0, "thank you"); + cout << "please in german:" << s01 << '\n'; + cout << "thank you in german:" << s02 << '\n'; + mssg_de.close(cat_de); +} +</pre></div><div class="section" title="Future"><div class="titlepage"><div><div><h4 class="title"><a id="facet.messages.future"/>Future</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + Things that are sketchy, or remain unimplemented: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + _M_convert_from_char, _M_convert_to_char are in flux, + depending on how the library ends up doing character set + conversions. It might not be possible to do a real character + set based conversion, due to the fact that the template + parameter for messages is not enough to instantiate the + codecvt facet (1 supplied, need at least 2 but would prefer + 3). + </p></li><li class="listitem"><p> + There are issues with gettext needing the global locale set + to extract a message. This dependence on the global locale + makes the current "gnu" model non MT-safe. Future versions + of glibc, i.e. glibc 2.3.x will fix this, and the C++ library + bits are already in place. + </p></li></ul></div></li><li class="listitem"><p> + Development versions of the GNU "C" library, glibc 2.3 will allow + a more efficient, MT implementation of std::messages, and will + allow the removal of the _M_name_messages data member. If this is + done, it will change the library ABI. The C++ parts to support + glibc 2.3 have already been coded, but are not in use: once this + version of the "C" library is released, the marked parts of the + messages implementation can be switched over to the new "C" + library functionality. + </p></li><li class="listitem"><p> + At some point in the near future, std::numpunct will probably use + std::messages facilities to implement truename/falsename + correctly. This is currently not done, but entries in + libstdc++.pot have already been made for "true" and "false" string + literals, so all that remains is the std::numpunct coding and the + configure/make hassles to make the installed library search its + own catalog. Currently the libstdc++.mo catalog is only searched + for the testsuite cases involving messages members. + </p></li><li class="listitem"><p> The following member functions:</p><p> + <code class="code"> + catalog + open(const basic_string<char>& __s, const locale& __loc) const + </code> + </p><p> + <code class="code"> + catalog + open(const basic_string<char>&, const locale&, const char*) const; + </code> + </p><p> + Don't actually return a "value less than 0 if no such catalog + can be opened" as required by the standard in the "gnu" + model. As of this writing, it is unknown how to query to see + if a specified message catalog exists using the gettext + package. + </p></li></ul></div></div><div class="bibliography" title="Bibliography"><div class="titlepage"><div><div><h4 class="title"><a id="facet.messages.biblio"/>Bibliography</h4></div></div></div><div class="biblioentry"><a id="id478453"/><p><span class="citetitle"><em class="citetitle"> + The GNU C Library + </em>. </span><span class="author"><span class="firstname">Roland</span> <span class="surname">McGrath</span>. </span><span class="author"><span class="firstname">Ulrich</span> <span class="surname">Drepper</span>. </span><span class="copyright">Copyright © 2007 FSF. </span><span class="pagenums">Chapters 6 Character Set Handling, and 7 Locales and Internationalization + . </span></p></div><div class="biblioentry"><a id="id478493"/><p><span class="citetitle"><em class="citetitle"> + Correspondence + </em>. </span><span class="author"><span class="firstname">Ulrich</span> <span class="surname">Drepper</span>. </span><span class="copyright">Copyright © 2002 . </span></p></div><div class="biblioentry"><a id="id478519"/><p><span class="citetitle"><em class="citetitle"> + ISO/IEC 14882:1998 Programming languages - C++ + </em>. </span><span class="copyright">Copyright © 1998 ISO. </span></p></div><div class="biblioentry"><a id="id478538"/><p><span class="citetitle"><em class="citetitle"> + ISO/IEC 9899:1999 Programming languages - C + </em>. </span><span class="copyright">Copyright © 1999 ISO. </span></p></div><div class="biblioentry"><a id="id478557"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + System Interface Definitions, Issue 7 (IEEE Std. 1003.1-2008) + </em>. </span><span class="copyright">Copyright © 2008 + The Open Group/The Institute of Electrical and Electronics + Engineers, Inc. + . </span></p></div><div class="biblioentry"><a id="id478586"/><p><span class="citetitle"><em class="citetitle"> + The C++ Programming Language, Special Edition + </em>. </span><span class="author"><span class="firstname">Bjarne</span> <span class="surname">Stroustrup</span>. </span><span class="copyright">Copyright © 2000 Addison Wesley, Inc.. </span><span class="pagenums">Appendix D. </span><span class="publisher"><span class="publishername"> + Addison Wesley + . </span></span></p></div><div class="biblioentry"><a id="id478624"/><p><span class="citetitle"><em class="citetitle"> + Standard C++ IOStreams and Locales + </em>. </span><span class="subtitle"> + Advanced Programmer's Guide and Reference + . </span><span class="author"><span class="firstname">Angelika</span> <span class="surname">Langer</span>. </span><span class="author"><span class="firstname">Klaus</span> <span class="surname">Kreft</span>. </span><span class="copyright">Copyright © 2000 Addison Wesley Longman, Inc.. </span><span class="publisher"><span class="publishername"> + Addison Wesley Longman + . </span></span></p></div><div class="biblioentry"><a id="id478672"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + API Specifications, Java Platform + </em>. </span><span class="pagenums">java.util.Properties, java.text.MessageFormat, +java.util.Locale, java.util.ResourceBundle + . </span></p></div><div class="biblioentry"><a id="id478694"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + GNU gettext tools, version 0.10.38, Native Language Support + Library and Tools. + </em>. </span></p></div></div></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="localization.html">Prev</a> </td><td align="center"><a accesskey="u" href="localization.html">Up</a></td><td align="right"> <a accesskey="n" href="containers.html">Next</a></td></tr><tr><td align="left" valign="top">Chapter 8. + Localization + + </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Chapter 9. + Containers + +</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/fstreams.html b/libstdc++-v3/doc/html/manual/fstreams.html new file mode 100644 index 000000000..6c03a2bb6 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/fstreams.html @@ -0,0 +1,150 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>File Based Streams</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="io.html" title="Chapter 13. Input and Output"/><link rel="prev" href="stringstreams.html" title="Memory Based Streams"/><link rel="next" href="io_and_c.html" title="Interacting with C"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">File Based Streams</th></tr><tr><td align="left"><a accesskey="p" href="stringstreams.html">Prev</a> </td><th width="60%" align="center">Chapter 13. + Input and Output + +</th><td align="right"> <a accesskey="n" href="io_and_c.html">Next</a></td></tr></table><hr/></div><div class="section" title="File Based Streams"><div class="titlepage"><div><div><h2 class="title"><a id="std.io.filestreams"/>File Based Streams</h2></div></div></div><div class="section" title="Copying a File"><div class="titlepage"><div><div><h3 class="title"><a id="std.io.filestreams.copying_a_file"/>Copying a File</h3></div></div></div><p> + </p><p>So you want to copy a file quickly and easily, and most important, + completely portably. And since this is C++, you have an open + ifstream (call it IN) and an open ofstream (call it OUT): + </p><pre class="programlisting"> + #include <fstream> + + std::ifstream IN ("input_file"); + std::ofstream OUT ("output_file"); </pre><p>Here's the easiest way to get it completely wrong: + </p><pre class="programlisting"> + OUT << IN;</pre><p>For those of you who don't already know why this doesn't work + (probably from having done it before), I invite you to quickly + create a simple text file called "input_file" containing + the sentence + </p><pre class="programlisting"> + The quick brown fox jumped over the lazy dog.</pre><p>surrounded by blank lines. Code it up and try it. The contents + of "output_file" may surprise you. + </p><p>Seriously, go do it. Get surprised, then come back. It's worth it. + </p><p>The thing to remember is that the <code class="code">basic_[io]stream</code> classes + handle formatting, nothing else. In chaptericular, they break up on + whitespace. The actual reading, writing, and storing of data is + handled by the <code class="code">basic_streambuf</code> family. Fortunately, the + <code class="code">operator<<</code> is overloaded to take an ostream and + a pointer-to-streambuf, in order to help with just this kind of + "dump the data verbatim" situation. + </p><p>Why a <span class="emphasis"><em>pointer</em></span> to streambuf and not just a streambuf? Well, + the [io]streams hold pointers (or references, depending on the + implementation) to their buffers, not the actual + buffers. This allows polymorphic behavior on the chapter of the buffers + as well as the streams themselves. The pointer is easily retrieved + using the <code class="code">rdbuf()</code> member function. Therefore, the easiest + way to copy the file is: + </p><pre class="programlisting"> + OUT << IN.rdbuf();</pre><p>So what <span class="emphasis"><em>was</em></span> happening with OUT<<IN? Undefined + behavior, since that chaptericular << isn't defined by the Standard. + I have seen instances where it is implemented, but the character + extraction process removes all the whitespace, leaving you with no + blank lines and only "Thequickbrownfox...". With + libraries that do not define that operator, IN (or one of IN's + member pointers) sometimes gets converted to a void*, and the output + file then contains a perfect text representation of a hexadecimal + address (quite a big surprise). Others don't compile at all. + </p><p>Also note that none of this is specific to o<span class="emphasis"><em>*f*</em></span>streams. + The operators shown above are all defined in the parent + basic_ostream class and are therefore available with all possible + descendants. + </p></div><div class="section" title="Binary Input and Output"><div class="titlepage"><div><div><h3 class="title"><a id="std.io.filestreams.binary"/>Binary Input and Output</h3></div></div></div><p> + </p><p>The first and most important thing to remember about binary I/O is + that opening a file with <code class="code">ios::binary</code> is not, repeat + <span class="emphasis"><em>not</em></span>, the only thing you have to do. It is not a silver + bullet, and will not allow you to use the <code class="code"><</>></code> + operators of the normal fstreams to do binary I/O. + </p><p>Sorry. Them's the breaks. + </p><p>This isn't going to try and be a complete tutorial on reading and + writing binary files (because "binary" + covers a lot of ground), but we will try and clear + up a couple of misconceptions and common errors. + </p><p>First, <code class="code">ios::binary</code> has exactly one defined effect, no more + and no less. Normal text mode has to be concerned with the newline + characters, and the runtime system will translate between (for + example) '\n' and the appropriate end-of-line sequence (LF on Unix, + CRLF on DOS, CR on Macintosh, etc). (There are other things that + normal mode does, but that's the most obvious.) Opening a file in + binary mode disables this conversion, so reading a CRLF sequence + under Windows won't accidentally get mapped to a '\n' character, etc. + Binary mode is not supposed to suddenly give you a bitstream, and + if it is doing so in your program then you've discovered a bug in + your vendor's compiler (or some other chapter of the C++ implementation, + possibly the runtime system). + </p><p>Second, using <code class="code"><<</code> to write and <code class="code">>></code> to + read isn't going to work with the standard file stream classes, even + if you use <code class="code">skipws</code> during reading. Why not? Because + ifstream and ofstream exist for the purpose of <span class="emphasis"><em>formatting</em></span>, + not reading and writing. Their job is to interpret the data into + text characters, and that's exactly what you don't want to happen + during binary I/O. + </p><p>Third, using the <code class="code">get()</code> and <code class="code">put()/write()</code> member + functions still aren't guaranteed to help you. These are + "unformatted" I/O functions, but still character-based. + (This may or may not be what you want, see below.) + </p><p>Notice how all the problems here are due to the inappropriate use + of <span class="emphasis"><em>formatting</em></span> functions and classes to perform something + which <span class="emphasis"><em>requires</em></span> that formatting not be done? There are a + seemingly infinite number of solutions, and a few are listed here: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><span class="quote">“<span class="quote">Derive your own fstream-type classes and write your own + <</>> operators to do binary I/O on whatever data + types you're using.</span>”</span> + </p><p> + This is a Bad Thing, because while + the compiler would probably be just fine with it, other humans + are going to be confused. The overloaded bitshift operators + have a well-defined meaning (formatting), and this breaks it. + </p></li><li class="listitem"><p> + <span class="quote">“<span class="quote">Build the file structure in memory, then + <code class="code">mmap()</code> the file and copy the + structure. + </span>”</span> + </p><p> + Well, this is easy to make work, and easy to break, and is + pretty equivalent to using <code class="code">::read()</code> and + <code class="code">::write()</code> directly, and makes no use of the + iostream library at all... + </p></li><li class="listitem"><p> + <span class="quote">“<span class="quote">Use streambufs, that's what they're there for.</span>”</span> + </p><p> + While not trivial for the beginner, this is the best of all + solutions. The streambuf/filebuf layer is the layer that is + responsible for actual I/O. If you want to use the C++ + library for binary I/O, this is where you start. + </p></li></ul></div><p>How to go about using streambufs is a bit beyond the scope of this + document (at least for now), but while streambufs go a long way, + they still leave a couple of things up to you, the programmer. + As an example, byte ordering is completely between you and the + operating system, and you have to handle it yourself. + </p><p>Deriving a streambuf or filebuf + class from the standard ones, one that is specific to your data + types (or an abstraction thereof) is probably a good idea, and + lots of examples exist in journals and on Usenet. Using the + standard filebufs directly (either by declaring your own or by + using the pointer returned from an fstream's <code class="code">rdbuf()</code>) + is certainly feasible as well. + </p><p>One area that causes problems is trying to do bit-by-bit operations + with filebufs. C++ is no different from C in this respect: I/O + must be done at the byte level. If you're trying to read or write + a few bits at a time, you're going about it the wrong way. You + must read/write an integral number of bytes and then process the + bytes. (For example, the streambuf functions take and return + variables of type <code class="code">int_type</code>.) + </p><p>Another area of problems is opening text files in binary mode. + Generally, binary mode is intended for binary files, and opening + text files in binary mode means that you now have to deal with all of + those end-of-line and end-of-file problems that we mentioned before. + </p><p> + An instructive thread from comp.lang.c++.moderated delved off into + this topic starting more or less at + <a class="link" href="http://groups.google.com/group/comp.std.c++/browse_thread/thread/f87b4abd7954a87/946a3eb9921e382d?q=comp.std.c%2B%2B+binary+iostream#946a3eb9921e382d">this</a> + post and continuing to the end of the thread. (The subject heading is "binary iostreams" on both comp.std.c++ + and comp.lang.c++.moderated.) Take special note of the replies by James Kanze and Dietmar Kühl. + </p><p>Briefly, the problems of byte ordering and type sizes mean that + the unformatted functions like <code class="code">ostream::put()</code> and + <code class="code">istream::get()</code> cannot safely be used to communicate + between arbitrary programs, or across a network, or from one + invocation of a program to another invocation of the same program + on a different platform, etc. + </p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="stringstreams.html">Prev</a> </td><td align="center"><a accesskey="u" href="io.html">Up</a></td><td align="right"> <a accesskey="n" href="io_and_c.html">Next</a></td></tr><tr><td align="left" valign="top">Memory Based Streams </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Interacting with C</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/generalized_numeric_operations.html b/libstdc++-v3/doc/html/manual/generalized_numeric_operations.html new file mode 100644 index 000000000..043cbeb36 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/generalized_numeric_operations.html @@ -0,0 +1,32 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Generalized Operations</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="numerics.html" title="Chapter 12. Numerics"/><link rel="prev" href="numerics.html" title="Chapter 12. Numerics"/><link rel="next" href="numerics_and_c.html" title="Interacting with C"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Generalized Operations</th></tr><tr><td align="left"><a accesskey="p" href="numerics.html">Prev</a> </td><th width="60%" align="center">Chapter 12. + Numerics + +</th><td align="right"> <a accesskey="n" href="numerics_and_c.html">Next</a></td></tr></table><hr/></div><div class="section" title="Generalized Operations"><div class="titlepage"><div><div><h2 class="title"><a id="std.numerics.generalized_ops"/>Generalized Operations</h2></div></div></div><p> + </p><p>There are four generalized functions in the <numeric> header + that follow the same conventions as those in <algorithm>. Each + of them is overloaded: one signature for common default operations, + and a second for fully general operations. Their names are + self-explanatory to anyone who works with numerics on a regular basis: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><code class="code">accumulate</code></p></li><li class="listitem"><p><code class="code">inner_product</code></p></li><li class="listitem"><p><code class="code">chapterial_sum</code></p></li><li class="listitem"><p><code class="code">adjacent_difference</code></p></li></ul></div><p>Here is a simple example of the two forms of <code class="code">accumulate</code>. + </p><pre class="programlisting"> + int ar[50]; + int someval = somefunction(); + + // ...initialize members of ar to something... + + int sum = std::accumulate(ar,ar+50,0); + int sum_stuff = std::accumulate(ar,ar+50,someval); + int product = std::accumulate(ar,ar+50,1,std::multiplies<int>()); + </pre><p>The first call adds all the members of the array, using zero as an + initial value for <code class="code">sum</code>. The second does the same, but uses + <code class="code">someval</code> as the starting value (thus, <code class="code">sum_stuff == sum + + someval</code>). The final call uses the second of the two signatures, + and multiplies all the members of the array; here we must obviously + use 1 as a starting value instead of 0. + </p><p>The other three functions have similar dual-signature forms. + </p></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="numerics.html">Prev</a> </td><td align="center"><a accesskey="u" href="numerics.html">Up</a></td><td align="right"> <a accesskey="n" href="numerics_and_c.html">Next</a></td></tr><tr><td align="left" valign="top">Chapter 12. + Numerics + + </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Interacting with C</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/internals.html b/libstdc++-v3/doc/html/manual/internals.html new file mode 100644 index 000000000..c6531fb55 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/internals.html @@ -0,0 +1,371 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Porting to New Hardware or Operating Systems</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , internals "/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="appendix_porting.html" title="Appendix B. Porting and Maintenance"/><link rel="prev" href="documentation_hacking.html" title="Writing and Generating Documentation"/><link rel="next" href="test.html" title="Test"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Porting to New Hardware or Operating Systems</th></tr><tr><td align="left"><a accesskey="p" href="documentation_hacking.html">Prev</a> </td><th width="60%" align="center">Appendix B. + Porting and Maintenance + +</th><td align="right"> <a accesskey="n" href="test.html">Next</a></td></tr></table><hr/></div><div class="section" title="Porting to New Hardware or Operating Systems"><div class="titlepage"><div><div><h2 class="title"><a id="appendix.porting.internals"/>Porting to New Hardware or Operating Systems</h2></div></div></div><p> +</p><p>This document explains how to port libstdc++ (the GNU C++ library) to +a new target. +</p><p>In order to make the GNU C++ library (libstdc++) work with a new +target, you must edit some configuration files and provide some new +header files. Unless this is done, libstdc++ will use generic +settings which may not be correct for your target; even if they are +correct, they will likely be inefficient. + </p><p>Before you get started, make sure that you have a working C library on +your target. The C library need not precisely comply with any +particular standard, but should generally conform to the requirements +imposed by the ANSI/ISO standard. + </p><p>In addition, you should try to verify that the C++ compiler generally +works. It is difficult to test the C++ compiler without a working +library, but you should at least try some minimal test cases. + </p><p>(Note that what we think of as a "target," the library refers to as +a "host." The comment at the top of <code class="code">configure.ac</code> explains why.) + </p><div class="section" title="Operating System"><div class="titlepage"><div><div><h3 class="title"><a id="internals.os"/>Operating System</h3></div></div></div><p>If you are porting to a new operating system (as opposed to a new chip +using an existing operating system), you will need to create a new +directory in the <code class="code">config/os</code> hierarchy. For example, the IRIX +configuration files are all in <code class="code">config/os/irix</code>. There is no set +way to organize the OS configuration directory. For example, +<code class="code">config/os/solaris/solaris-2.6</code> and +<code class="code">config/os/solaris/solaris-2.7</code> are used as configuration +directories for these two versions of Solaris. On the other hand, both +Solaris 2.7 and Solaris 2.8 use the <code class="code">config/os/solaris/solaris-2.7</code> +directory. The important information is that there needs to be a +directory under <code class="code">config/os</code> to store the files for your operating +system. +</p><p>You might have to change the <code class="code">configure.host</code> file to ensure that +your new directory is activated. Look for the switch statement that sets +<code class="code">os_include_dir</code>, and add a pattern to handle your operating system +if the default will not suffice. The switch statement switches on only +the OS portion of the standard target triplet; e.g., the <code class="code">solaris2.8</code> +in <code class="code">sparc-sun-solaris2.8</code>. If the new directory is named after the +OS portion of the triplet (the default), then nothing needs to be changed. + </p><p>The first file to create in this directory, should be called +<code class="code">os_defines.h</code>. This file contains basic macro definitions +that are required to allow the C++ library to work with your C library. + </p><p>Several libstdc++ source files unconditionally define the macro +<code class="code">_POSIX_SOURCE</code>. On many systems, defining this macro causes +large portions of the C library header files to be eliminated +at preprocessing time. Therefore, you may have to <code class="code">#undef</code> this +macro, or define other macros (like <code class="code">_LARGEFILE_SOURCE</code> or +<code class="code">__EXTENSIONS__</code>). You won't know what macros to define or +undefine at this point; you'll have to try compiling the library and +seeing what goes wrong. If you see errors about calling functions +that have not been declared, look in your C library headers to see if +the functions are declared there, and then figure out what macros you +need to define. You will need to add them to the +<code class="code">CPLUSPLUS_CPP_SPEC</code> macro in the GCC configuration file for your +target. It will not work to simply define these macros in +<code class="code">os_defines.h</code>. + </p><p>At this time, there are a few libstdc++-specific macros which may be +defined: + </p><p><code class="code">_GLIBCXX_USE_C99_CHECK</code> may be defined to 1 to check C99 +function declarations (which are not covered by specialization below) +found in system headers against versions found in the library headers +derived from the standard. + </p><p><code class="code">_GLIBCXX_USE_C99_DYNAMIC</code> may be defined to an expression that +yields 0 if and only if the system headers are exposing proper support +for C99 functions (which are not covered by specialization below). If +defined, it must be 0 while bootstrapping the compiler/rebuilding the +library. + </p><p><code class="code">_GLIBCXX_USE_C99_LONG_LONG_CHECK</code> may be defined to 1 to check +the set of C99 long long function declarations found in system headers +against versions found in the library headers derived from the +standard. + + </p><p><code class="code">_GLIBCXX_USE_C99_LONG_LONG_DYNAMIC</code> may be defined to an +expression that yields 0 if and only if the system headers are +exposing proper support for the set of C99 long long functions. If +defined, it must be 0 while bootstrapping the compiler/rebuilding the +library. + </p><p><code class="code">_GLIBCXX_USE_C99_FP_MACROS_DYNAMIC</code> may be defined to an +expression that yields 0 if and only if the system headers +are exposing proper support for the related set of macros. If defined, +it must be 0 while bootstrapping the compiler/rebuilding the library. + </p><p><code class="code">_GLIBCXX_USE_C99_FLOAT_TRANSCENDENTALS_CHECK</code> may be defined +to 1 to check the related set of function declarations found in system +headers against versions found in the library headers derived from +the standard. + </p><p><code class="code">_GLIBCXX_USE_C99_FLOAT_TRANSCENDENTALS_DYNAMIC</code> may be defined +to an expression that yields 0 if and only if the system headers +are exposing proper support for the related set of functions. If defined, +it must be 0 while bootstrapping the compiler/rebuilding the library. + </p><p>Finally, you should bracket the entire file in an include-guard, like +this: + </p><pre class="programlisting"> + +#ifndef _GLIBCXX_OS_DEFINES +#define _GLIBCXX_OS_DEFINES +... +#endif +</pre><p>We recommend copying an existing <code class="code">os_defines.h</code> to use as a +starting point. + </p></div><div class="section" title="CPU"><div class="titlepage"><div><div><h3 class="title"><a id="internals.cpu"/>CPU</h3></div></div></div><p>If you are porting to a new chip (as opposed to a new operating system +running on an existing chip), you will need to create a new directory in the +<code class="code">config/cpu</code> hierarchy. Much like the <a class="link" href="internals.html#internals.os" title="Operating System">Operating system</a> setup, +there are no strict rules on how to organize the CPU configuration +directory, but careful naming choices will allow the configury to find your +setup files without explicit help. +</p><p>We recommend that for a target triplet <code class="code"><CPU>-<vendor>-<OS></code>, you +name your configuration directory <code class="code">config/cpu/<CPU></code>. If you do this, +the configury will find the directory by itself. Otherwise you will need to +edit the <code class="code">configure.host</code> file and, in the switch statement that sets +<code class="code">cpu_include_dir</code>, add a pattern to handle your chip. + </p><p>Note that some chip families share a single configuration directory, for +example, <code class="code">alpha</code>, <code class="code">alphaev5</code>, and <code class="code">alphaev6</code> all use the +<code class="code">config/cpu/alpha</code> directory, and there is an entry in the +<code class="code">configure.host</code> switch statement to handle this. + </p><p>The <code class="code">cpu_include_dir</code> sets default locations for the files controlling +<a class="link" href="internals.html#internals.thread_safety" title="Thread Safety">Thread safety</a> and <a class="link" href="internals.html#internals.numeric_limits" title="Numeric Limits">Numeric limits</a>, if the defaults are not +appropriate for your chip. + </p></div><div class="section" title="Character Types"><div class="titlepage"><div><div><h3 class="title"><a id="internals.char_types"/>Character Types</h3></div></div></div><p>The library requires that you provide three header files to implement +character classification, analogous to that provided by the C libraries +<code class="code"><ctype.h></code> header. You can model these on the files provided in +<code class="code">config/os/generic</code>. However, these files will almost +certainly need some modification. +</p><p>The first file to write is <code class="code">ctype_base.h</code>. This file provides +some very basic information about character classification. The libstdc++ +library assumes that your C library implements <code class="code"><ctype.h></code> by using +a table (indexed by character code) containing integers, where each of +these integers is a bit-mask indicating whether the character is +upper-case, lower-case, alphabetic, etc. The <code class="code">ctype_base.h</code> +file gives the type of the integer, and the values of the various bit +masks. You will have to peer at your own <code class="code"><ctype.h></code> to figure out +how to define the values required by this file. + </p><p>The <code class="code">ctype_base.h</code> header file does not need include guards. +It should contain a single <code class="code">struct</code> definition called +<code class="code">ctype_base</code>. This <code class="code">struct</code> should contain two type +declarations, and one enumeration declaration, like this example, taken +from the IRIX configuration: + </p><pre class="programlisting"> + struct ctype_base + { + typedef unsigned int mask; + typedef int* __to_type; + + enum + { + space = _ISspace, + print = _ISprint, + cntrl = _IScntrl, + upper = _ISupper, + lower = _ISlower, + alpha = _ISalpha, + digit = _ISdigit, + punct = _ISpunct, + xdigit = _ISxdigit, + alnum = _ISalnum, + graph = _ISgraph + }; + }; +</pre><p>The <code class="code">mask</code> type is the type of the elements in the table. If your +C library uses a table to map lower-case numbers to upper-case numbers, +and vice versa, you should define <code class="code">__to_type</code> to be the type of the +elements in that table. If you don't mind taking a minor performance +penalty, or if your library doesn't implement <code class="code">toupper</code> and +<code class="code">tolower</code> in this way, you can pick any pointer-to-integer type, +but you must still define the type. +</p><p>The enumeration should give definitions for all the values in the above +example, using the values from your native <code class="code"><ctype.h></code>. They can +be given symbolically (as above), or numerically, if you prefer. You do +not have to include <code class="code"><ctype.h></code> in this header; it will always be +included before <code class="code">ctype_base.h</code> is included. + </p><p>The next file to write is <code class="code">ctype_noninline.h</code>, which also does +not require include guards. This file defines a few member functions +that will be included in <code class="code">include/bits/locale_facets.h</code>. The first +function that must be written is the <code class="code">ctype<char>::ctype</code> +constructor. Here is the IRIX example: + </p><pre class="programlisting"> +ctype<char>::ctype(const mask* __table = 0, bool __del = false, + size_t __refs = 0) + : _Ctype_nois<char>(__refs), _M_del(__table != 0 && __del), + _M_toupper(NULL), + _M_tolower(NULL), + _M_ctable(NULL), + _M_table(!__table + ? (const mask*) (__libc_attr._ctype_tbl->_class + 1) + : __table) + { } +</pre><p>There are two parts of this that you might choose to alter. The first, +and most important, is the line involving <code class="code">__libc_attr</code>. That is +IRIX system-dependent code that gets the base of the table mapping +character codes to attributes. You need to substitute code that obtains +the address of this table on your system. If you want to use your +operating system's tables to map upper-case letters to lower-case, and +vice versa, you should initialize <code class="code">_M_toupper</code> and +<code class="code">_M_tolower</code> with those tables, in similar fashion. +</p><p>Now, you have to write two functions to convert from upper-case to +lower-case, and vice versa. Here are the IRIX versions: + </p><pre class="programlisting"> + char + ctype<char>::do_toupper(char __c) const + { return _toupper(__c); } + + char + ctype<char>::do_tolower(char __c) const + { return _tolower(__c); } +</pre><p>Your C library provides equivalents to IRIX's <code class="code">_toupper</code> and +<code class="code">_tolower</code>. If you initialized <code class="code">_M_toupper</code> and +<code class="code">_M_tolower</code> above, then you could use those tables instead. +</p><p>Finally, you have to provide two utility functions that convert strings +of characters. The versions provided here will always work - but you +could use specialized routines for greater performance if you have +machinery to do that on your system: + </p><pre class="programlisting"> + const char* + ctype<char>::do_toupper(char* __low, const char* __high) const + { + while (__low < __high) + { + *__low = do_toupper(*__low); + ++__low; + } + return __high; + } + + const char* + ctype<char>::do_tolower(char* __low, const char* __high) const + { + while (__low < __high) + { + *__low = do_tolower(*__low); + ++__low; + } + return __high; + } +</pre><p>You must also provide the <code class="code">ctype_inline.h</code> file, which +contains a few more functions. On most systems, you can just copy +<code class="code">config/os/generic/ctype_inline.h</code> and use it on your system. + </p><p>In detail, the functions provided test characters for particular +properties; they are analogous to the functions like <code class="code">isalpha</code> and +<code class="code">islower</code> provided by the C library. + </p><p>The first function is implemented like this on IRIX: + </p><pre class="programlisting"> + bool + ctype<char>:: + is(mask __m, char __c) const throw() + { return (_M_table)[(unsigned char)(__c)] & __m; } +</pre><p>The <code class="code">_M_table</code> is the table passed in above, in the constructor. +This is the table that contains the bitmasks for each character. The +implementation here should work on all systems. +</p><p>The next function is: + </p><pre class="programlisting"> + const char* + ctype<char>:: + is(const char* __low, const char* __high, mask* __vec) const throw() + { + while (__low < __high) + *__vec++ = (_M_table)[(unsigned char)(*__low++)]; + return __high; + } +</pre><p>This function is similar; it copies the masks for all the characters +from <code class="code">__low</code> up until <code class="code">__high</code> into the vector given by +<code class="code">__vec</code>. +</p><p>The last two functions again are entirely generic: + </p><pre class="programlisting"> + const char* + ctype<char>:: + scan_is(mask __m, const char* __low, const char* __high) const throw() + { + while (__low < __high && !this->is(__m, *__low)) + ++__low; + return __low; + } + + const char* + ctype<char>:: + scan_not(mask __m, const char* __low, const char* __high) const throw() + { + while (__low < __high && this->is(__m, *__low)) + ++__low; + return __low; + } +</pre></div><div class="section" title="Thread Safety"><div class="titlepage"><div><div><h3 class="title"><a id="internals.thread_safety"/>Thread Safety</h3></div></div></div><p>The C++ library string functionality requires a couple of atomic +operations to provide thread-safety. If you don't take any special +action, the library will use stub versions of these functions that are +not thread-safe. They will work fine, unless your applications are +multi-threaded. +</p><p>If you want to provide custom, safe, versions of these functions, there +are two distinct approaches. One is to provide a version for your CPU, +using assembly language constructs. The other is to use the +thread-safety primitives in your operating system. In either case, you +make a file called <code class="code">atomicity.h</code>, and the variable +<code class="code">ATOMICITYH</code> must point to this file. + </p><p>If you are using the assembly-language approach, put this code in +<code class="code">config/cpu/<chip>/atomicity.h</code>, where chip is the name of +your processor (see <a class="link" href="internals.html#internals.cpu" title="CPU">CPU</a>). No additional changes are necessary to +locate the file in this case; <code class="code">ATOMICITYH</code> will be set by default. + </p><p>If you are using the operating system thread-safety primitives approach, +you can also put this code in the same CPU directory, in which case no more +work is needed to locate the file. For examples of this approach, +see the <code class="code">atomicity.h</code> file for IRIX or IA64. + </p><p>Alternatively, if the primitives are more closely related to the OS +than they are to the CPU, you can put the <code class="code">atomicity.h</code> file in +the <a class="link" href="internals.html#internals.os" title="Operating System">Operating system</a> directory instead. In this case, you must +edit <code class="code">configure.host</code>, and in the switch statement that handles +operating systems, override the <code class="code">ATOMICITYH</code> variable to point to +the appropriate <code class="code">os_include_dir</code>. For examples of this approach, +see the <code class="code">atomicity.h</code> file for AIX. + </p><p>With those bits out of the way, you have to actually write +<code class="code">atomicity.h</code> itself. This file should be wrapped in an +include guard named <code class="code">_GLIBCXX_ATOMICITY_H</code>. It should define one +type, and two functions. + </p><p>The type is <code class="code">_Atomic_word</code>. Here is the version used on IRIX: + </p><pre class="programlisting"> +typedef long _Atomic_word; +</pre><p>This type must be a signed integral type supporting atomic operations. +If you're using the OS approach, use the same type used by your system's +primitives. Otherwise, use the type for which your CPU provides atomic +primitives. +</p><p>Then, you must provide two functions. The bodies of these functions +must be equivalent to those provided here, but using atomic operations: + </p><pre class="programlisting"> + static inline _Atomic_word + __attribute__ ((__unused__)) + __exchange_and_add (_Atomic_word* __mem, int __val) + { + _Atomic_word __result = *__mem; + *__mem += __val; + return __result; + } + + static inline void + __attribute__ ((__unused__)) + __atomic_add (_Atomic_word* __mem, int __val) + { + *__mem += __val; + } +</pre></div><div class="section" title="Numeric Limits"><div class="titlepage"><div><div><h3 class="title"><a id="internals.numeric_limits"/>Numeric Limits</h3></div></div></div><p>The C++ library requires information about the fundamental data types, +such as the minimum and maximum representable values of each type. +You can define each of these values individually, but it is usually +easiest just to indicate how many bits are used in each of the data +types and let the library do the rest. For information about the +macros to define, see the top of <code class="code">include/bits/std_limits.h</code>. +</p><p>If you need to define any macros, you can do so in <code class="code">os_defines.h</code>. +However, if all operating systems for your CPU are likely to use the +same values, you can provide a CPU-specific file instead so that you +do not have to provide the same definitions for each operating system. +To take that approach, create a new file called <code class="code">cpu_limits.h</code> in +your CPU configuration directory (see <a class="link" href="internals.html#internals.cpu" title="CPU">CPU</a>). + </p></div><div class="section" title="Libtool"><div class="titlepage"><div><div><h3 class="title"><a id="internals.libtool"/>Libtool</h3></div></div></div><p>The C++ library is compiled, archived and linked with libtool. +Explaining the full workings of libtool is beyond the scope of this +document, but there are a few, particular bits that are necessary for +porting. +</p><p>Some parts of the libstdc++ library are compiled with the libtool +<code class="code">--tags CXX</code> option (the C++ definitions for libtool). Therefore, +<code class="code">ltcf-cxx.sh</code> in the top-level directory needs to have the correct +logic to compile and archive objects equivalent to the C version of libtool, +<code class="code">ltcf-c.sh</code>. Some libtool targets have definitions for C but not +for C++, or C++ definitions which have not been kept up to date. + </p><p>The C++ run-time library contains initialization code that needs to be +run as the library is loaded. Often, that requires linking in special +object files when the C++ library is built as a shared library, or +taking other system-specific actions. + </p><p>The libstdc++ library is linked with the C version of libtool, even +though it is a C++ library. Therefore, the C version of libtool needs to +ensure that the run-time library initializers are run. The usual way to +do this is to build the library using <code class="code">gcc -shared</code>. + </p><p>If you need to change how the library is linked, look at +<code class="code">ltcf-c.sh</code> in the top-level directory. Find the switch statement +that sets <code class="code">archive_cmds</code>. Here, adjust the setting for your +operating system. + </p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="documentation_hacking.html">Prev</a> </td><td align="center"><a accesskey="u" href="appendix_porting.html">Up</a></td><td align="right"> <a accesskey="n" href="test.html">Next</a></td></tr><tr><td align="left" valign="top">Writing and Generating Documentation </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Test</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/intro.html b/libstdc++-v3/doc/html/manual/intro.html new file mode 100644 index 000000000..d283df00a --- /dev/null +++ b/libstdc++-v3/doc/html/manual/intro.html @@ -0,0 +1,9 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Part I. Introduction</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="spine.html" title="The GNU C++ Library Manual"/><link rel="prev" href="spine.html" title="The GNU C++ Library Manual"/><link rel="next" href="status.html" title="Chapter 1. Status"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Part I. + Introduction + +</th></tr><tr><td align="left"><a accesskey="p" href="spine.html">Prev</a> </td><th width="60%" align="center">The GNU C++ Library Manual</th><td align="right"> <a accesskey="n" href="status.html">Next</a></td></tr></table><hr/></div><div class="part" title="Part I. Introduction"><div class="titlepage"><div><div><h1 class="title"><a id="manual.intro"/>Part I. + Introduction + <a id="id400676" class="indexterm"/> +</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="chapter"><a href="status.html">1. Status</a></span></dt><dd><dl><dt><span class="section"><a href="status.html#manual.intro.status.iso">Implementation Status</a></span></dt><dd><dl><dt><span class="section"><a href="status.html#status.iso.1998">C++ 1998/2003</a></span></dt><dt><span class="section"><a href="status.html#status.iso.200x">C++ 200x</a></span></dt><dt><span class="section"><a href="status.html#status.iso.tr1">C++ TR1</a></span></dt><dt><span class="section"><a href="status.html#status.iso.tr24733">C++ TR 24733</a></span></dt></dl></dd><dt><span class="section"><a href="license.html">License</a></span></dt><dd><dl><dt><span class="section"><a href="license.html#manual.intro.status.license.gpl">The Code: GPL</a></span></dt><dt><span class="section"><a href="license.html#manual.intro.status.license.fdl">The Documentation: GPL, FDL</a></span></dt></dl></dd><dt><span class="section"><a href="bugs.html">Bugs</a></span></dt><dd><dl><dt><span class="section"><a href="bugs.html#manual.intro.status.bugs.impl">Implementation Bugs</a></span></dt><dt><span class="section"><a href="bugs.html#manual.intro.status.bugs.iso">Standard Bugs</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="setup.html">2. Setup</a></span></dt><dd><dl><dt><span class="section"><a href="setup.html#manual.intro.setup.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="configure.html">Configure</a></span></dt><dt><span class="section"><a href="make.html">Make</a></span></dt></dl></dd><dt><span class="chapter"><a href="using.html">3. Using</a></span></dt><dd><dl><dt><span class="section"><a href="using.html#manual.intro.using.flags">Command Options</a></span></dt><dt><span class="section"><a href="using_headers.html">Headers</a></span></dt><dd><dl><dt><span class="section"><a href="using_headers.html#manual.intro.using.headers.all">Header Files</a></span></dt><dt><span class="section"><a href="using_headers.html#manual.intro.using.headers.mixing">Mixing Headers</a></span></dt><dt><span class="section"><a href="using_headers.html#manual.intro.using.headers.cheaders">The C Headers and <code class="code">namespace std</code></a></span></dt><dt><span class="section"><a href="using_headers.html#manual.intro.using.headers.pre">Precompiled Headers</a></span></dt></dl></dd><dt><span class="section"><a href="using_macros.html">Macros</a></span></dt><dt><span class="section"><a href="using_namespaces.html">Namespaces</a></span></dt><dd><dl><dt><span class="section"><a href="using_namespaces.html#manual.intro.using.namespaces.all">Available Namespaces</a></span></dt><dt><span class="section"><a href="using_namespaces.html#manual.intro.using.namespaces.std">namespace std</a></span></dt><dt><span class="section"><a href="using_namespaces.html#manual.intro.using.namespaces.comp">Using Namespace Composition</a></span></dt></dl></dd><dt><span class="section"><a href="using_dynamic_or_shared.html">Linking</a></span></dt><dd><dl><dt><span class="section"><a href="using_dynamic_or_shared.html#manual.intro.using.linkage.freestanding">Almost Nothing</a></span></dt><dt><span class="section"><a href="using_dynamic_or_shared.html#manual.intro.using.linkage.dynamic">Finding Dynamic or Shared Libraries</a></span></dt></dl></dd><dt><span class="section"><a href="using_concurrency.html">Concurrency</a></span></dt><dd><dl><dt><span class="section"><a href="using_concurrency.html#manual.intro.using.concurrency.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="using_concurrency.html#manual.intro.using.concurrency.thread_safety">Thread Safety</a></span></dt><dt><span class="section"><a href="using_concurrency.html#manual.intro.using.concurrency.atomics">Atomics</a></span></dt><dt><span class="section"><a href="using_concurrency.html#manual.intro.using.concurrency.io">IO</a></span></dt><dt><span class="section"><a href="using_concurrency.html#manual.intro.using.concurrency.containers">Containers</a></span></dt></dl></dd><dt><span class="section"><a href="using_exceptions.html">Exceptions</a></span></dt><dd><dl><dt><span class="section"><a href="using_exceptions.html#intro.using.exception.safety">Exception Safety</a></span></dt><dt><span class="section"><a href="using_exceptions.html#intro.using.exception.propagating">Exception Neutrality</a></span></dt><dt><span class="section"><a href="using_exceptions.html#intro.using.exception.no">Doing without</a></span></dt><dt><span class="section"><a href="using_exceptions.html#intro.using.exception.compat">Compatibility</a></span></dt></dl></dd><dt><span class="section"><a href="debug.html">Debugging Support</a></span></dt><dd><dl><dt><span class="section"><a href="debug.html#debug.compiler">Using <span class="command"><strong>g++</strong></span></a></span></dt><dt><span class="section"><a href="debug.html#debug.req">Debug Versions of Library Binary Files</a></span></dt><dt><span class="section"><a href="debug.html#debug.memory">Memory Leak Hunting</a></span></dt><dt><span class="section"><a href="debug.html#debug.races">Data Race Hunting</a></span></dt><dt><span class="section"><a href="debug.html#debug.gdb">Using <span class="command"><strong>gdb</strong></span></a></span></dt><dt><span class="section"><a href="debug.html#debug.exceptions">Tracking uncaught exceptions</a></span></dt><dt><span class="section"><a href="debug.html#debug.debug_mode">Debug Mode</a></span></dt><dt><span class="section"><a href="debug.html#debug.compile_time_checks">Compile Time Checking</a></span></dt><dt><span class="section"><a href="debug.html#debug.profile_mode">Profile-based Performance Analysis</a></span></dt></dl></dd></dl></dd></dl></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="spine.html">Prev</a> </td><td align="center"><a accesskey="u" href="spine.html">Up</a></td><td align="right"> <a accesskey="n" href="status.html">Next</a></td></tr><tr><td align="left" valign="top">The GNU C++ Library Manual </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Chapter 1. Status</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/io.html b/libstdc++-v3/doc/html/manual/io.html new file mode 100644 index 000000000..01ef0ff23 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/io.html @@ -0,0 +1,121 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Chapter 13. Input and Output</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="bk01pt02.html" title="Part II. Standard Contents"/><link rel="prev" href="numerics_and_c.html" title="Interacting with C"/><link rel="next" href="streambufs.html" title="Stream Buffers"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 13. + Input and Output + +</th></tr><tr><td align="left"><a accesskey="p" href="numerics_and_c.html">Prev</a> </td><th width="60%" align="center">Part II. + Standard Contents + </th><td align="right"> <a accesskey="n" href="streambufs.html">Next</a></td></tr></table><hr/></div><div class="chapter" title="Chapter 13. Input and Output"><div class="titlepage"><div><div><h2 class="title"><a id="std.io"/>Chapter 13. + Input and Output + <a id="id480471" class="indexterm"/> +</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="io.html#std.io.objects">Iostream Objects</a></span></dt><dt><span class="section"><a href="streambufs.html">Stream Buffers</a></span></dt><dd><dl><dt><span class="section"><a href="streambufs.html#io.streambuf.derived">Derived streambuf Classes</a></span></dt><dt><span class="section"><a href="streambufs.html#io.streambuf.buffering">Buffering</a></span></dt></dl></dd><dt><span class="section"><a href="stringstreams.html">Memory Based Streams</a></span></dt><dd><dl><dt><span class="section"><a href="stringstreams.html#std.io.memstreams.compat">Compatibility With strstream</a></span></dt></dl></dd><dt><span class="section"><a href="fstreams.html">File Based Streams</a></span></dt><dd><dl><dt><span class="section"><a href="fstreams.html#std.io.filestreams.copying_a_file">Copying a File</a></span></dt><dt><span class="section"><a href="fstreams.html#std.io.filestreams.binary">Binary Input and Output</a></span></dt></dl></dd><dt><span class="section"><a href="io_and_c.html">Interacting with C</a></span></dt><dd><dl><dt><span class="section"><a href="io_and_c.html#std.io.c.FILE">Using FILE* and file descriptors</a></span></dt><dt><span class="section"><a href="io_and_c.html#std.io.c.sync">Performance</a></span></dt></dl></dd></dl></div><div class="section" title="Iostream Objects"><div class="titlepage"><div><div><h2 class="title"><a id="std.io.objects"/>Iostream Objects</h2></div></div></div><p>To minimize the time you have to wait on the compiler, it's good to + only include the headers you really need. Many people simply include + <iostream> when they don't need to -- and that can <span class="emphasis"><em>penalize + your runtime as well.</em></span> Here are some tips on which header to use + for which situations, starting with the simplest. + </p><p><span class="emphasis"><em><iosfwd></em></span> should be included whenever you simply + need the <span class="emphasis"><em>name</em></span> of an I/O-related class, such as + "ofstream" or "basic_streambuf". Like the name + implies, these are forward declarations. (A word to all you fellow + old school programmers: trying to forward declare classes like + "class istream;" won't work. Look in the iosfwd header if + you'd like to know why.) For example, + </p><pre class="programlisting"> + #include <iosfwd> + + class MyClass + { + .... + std::ifstream& input_file; + }; + + extern std::ostream& operator<< (std::ostream&, MyClass&); + </pre><p><span class="emphasis"><em><ios></em></span> declares the base classes for the entire + I/O stream hierarchy, std::ios_base and std::basic_ios<charT>, the + counting types std::streamoff and std::streamsize, the file + positioning type std::fpos, and the various manipulators like + std::hex, std::fixed, std::noshowbase, and so forth. + </p><p>The ios_base class is what holds the format flags, the state flags, + and the functions which change them (setf(), width(), precision(), + etc). You can also store extra data and register callback functions + through ios_base, but that has been historically underused. Anything + which doesn't depend on the type of characters stored is consolidated + here. + </p><p>The template class basic_ios is the highest template class in the + hierarchy; it is the first one depending on the character type, and + holds all general state associated with that type: the pointer to the + polymorphic stream buffer, the facet information, etc. + </p><p><span class="emphasis"><em><streambuf></em></span> declares the template class + basic_streambuf, and two standard instantiations, streambuf and + wstreambuf. If you need to work with the vastly useful and capable + stream buffer classes, e.g., to create a new form of storage + transport, this header is the one to include. + </p><p><span class="emphasis"><em><istream></em></span>/<span class="emphasis"><em><ostream></em></span> are + the headers to include when you are using the >>/<< + interface, or any of the other abstract stream formatting functions. + For example, + </p><pre class="programlisting"> + #include <istream> + + std::ostream& operator<< (std::ostream& os, MyClass& c) + { + return os << c.data1() << c.data2(); + } + </pre><p>The std::istream and std::ostream classes are the abstract parents of + the various concrete implementations. If you are only using the + interfaces, then you only need to use the appropriate interface header. + </p><p><span class="emphasis"><em><iomanip></em></span> provides "extractors and inserters + that alter information maintained by class ios_base and its derived + classes," such as std::setprecision and std::setw. If you need + to write expressions like <code class="code">os << setw(3);</code> or + <code class="code">is >> setbase(8);</code>, you must include <iomanip>. + </p><p><span class="emphasis"><em><sstream></em></span>/<span class="emphasis"><em><fstream></em></span> + declare the six stringstream and fstream classes. As they are the + standard concrete descendants of istream and ostream, you will already + know about them. + </p><p>Finally, <span class="emphasis"><em><iostream></em></span> provides the eight standard + global objects (cin, cout, etc). To do this correctly, this header + also provides the contents of the <istream> and <ostream> + headers, but nothing else. The contents of this header look like + </p><pre class="programlisting"> + #include <ostream> + #include <istream> + + namespace std + { + extern istream cin; + extern ostream cout; + .... + + // this is explained below + <span class="emphasis"><em>static ios_base::Init __foo;</em></span> // not its real name + } + </pre><p>Now, the runtime penalty mentioned previously: the global objects + must be initialized before any of your own code uses them; this is + guaranteed by the standard. Like any other global object, they must + be initialized once and only once. This is typically done with a + construct like the one above, and the nested class ios_base::Init is + specified in the standard for just this reason. + </p><p>How does it work? Because the header is included before any of your + code, the <span class="emphasis"><em>__foo</em></span> object is constructed before any of + your objects. (Global objects are built in the order in which they + are declared, and destroyed in reverse order.) The first time the + constructor runs, the eight stream objects are set up. + </p><p>The <code class="code">static</code> keyword means that each object file compiled + from a source file containing <iostream> will have its own + private copy of <span class="emphasis"><em>__foo</em></span>. There is no specified order + of construction across object files (it's one of those pesky NP + problems that make life so interesting), so one copy in each object + file means that the stream objects are guaranteed to be set up before + any of your code which uses them could run, thereby meeting the + requirements of the standard. + </p><p>The penalty, of course, is that after the first copy of + <span class="emphasis"><em>__foo</em></span> is constructed, all the others are just wasted + processor time. The time spent is merely for an increment-and-test + inside a function call, but over several dozen or hundreds of object + files, that time can add up. (It's not in a tight loop, either.) + </p><p>The lesson? Only include <iostream> when you need to use one of + the standard objects in that source file; you'll pay less startup + time. Only include the header files you need to in general; your + compile times will go down when there's less parsing work to do. + </p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="numerics_and_c.html">Prev</a> </td><td align="center"><a accesskey="u" href="bk01pt02.html">Up</a></td><td align="right"> <a accesskey="n" href="streambufs.html">Next</a></td></tr><tr><td align="left" valign="top">Interacting with C </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Stream Buffers</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/io_and_c.html b/libstdc++-v3/doc/html/manual/io_and_c.html new file mode 100644 index 000000000..6b4066154 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/io_and_c.html @@ -0,0 +1,57 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Interacting with C</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="io.html" title="Chapter 13. Input and Output"/><link rel="prev" href="fstreams.html" title="File Based Streams"/><link rel="next" href="atomics.html" title="Chapter 14. Atomics"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Interacting with C</th></tr><tr><td align="left"><a accesskey="p" href="fstreams.html">Prev</a> </td><th width="60%" align="center">Chapter 13. + Input and Output + +</th><td align="right"> <a accesskey="n" href="atomics.html">Next</a></td></tr></table><hr/></div><div class="section" title="Interacting with C"><div class="titlepage"><div><div><h2 class="title"><a id="std.io.c"/>Interacting with C</h2></div></div></div><div class="section" title="Using FILE* and file descriptors"><div class="titlepage"><div><div><h3 class="title"><a id="std.io.c.FILE"/>Using FILE* and file descriptors</h3></div></div></div><p> + See the <a class="link" href="ext_io.html" title="Chapter 26. Input and Output">extensions</a> for using + <span class="type">FILE</span> and <span class="type">file descriptors</span> with + <code class="classname">ofstream</code> and + <code class="classname">ifstream</code>. + </p></div><div class="section" title="Performance"><div class="titlepage"><div><div><h3 class="title"><a id="std.io.c.sync"/>Performance</h3></div></div></div><p> + Pathetic Performance? Ditch C. + </p><p>It sounds like a flame on C, but it isn't. Really. Calm down. + I'm just saying it to get your attention. + </p><p>Because the C++ library includes the C library, both C-style and + C++-style I/O have to work at the same time. For example: + </p><pre class="programlisting"> + #include <iostream> + #include <cstdio> + + std::cout << "Hel"; + std::printf ("lo, worl"); + std::cout << "d!\n"; + </pre><p>This must do what you think it does. + </p><p>Alert members of the audience will immediately notice that buffering + is going to make a hash of the output unless special steps are taken. + </p><p>The special steps taken by libstdc++, at least for version 3.0, + involve doing very little buffering for the standard streams, leaving + most of the buffering to the underlying C library. (This kind of + thing is tricky to get right.) + The upside is that correctness is ensured. The downside is that + writing through <code class="code">cout</code> can quite easily lead to awful + performance when the C++ I/O library is layered on top of the C I/O + library (as it is for 3.0 by default). Some patches have been applied + which improve the situation for 3.1. + </p><p>However, the C and C++ standard streams only need to be kept in sync + when both libraries' facilities are in use. If your program only uses + C++ I/O, then there's no need to sync with the C streams. The right + thing to do in this case is to call + </p><pre class="programlisting"> + #include <span class="emphasis"><em>any of the I/O headers such as ios, iostream, etc</em></span> + + std::ios::sync_with_stdio(false); + </pre><p>You must do this before performing any I/O via the C++ stream objects. + Once you call this, the C++ streams will operate independently of the + (unused) C streams. For GCC 3.x, this means that <code class="code">cout</code> and + company will become fully buffered on their own. + </p><p>Note, by the way, that the synchronization requirement only applies to + the standard streams (<code class="code">cin</code>, <code class="code">cout</code>, + <code class="code">cerr</code>, + <code class="code">clog</code>, and their wide-character counterchapters). File stream + objects that you declare yourself have no such requirement and are fully + buffered. + </p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="fstreams.html">Prev</a> </td><td align="center"><a accesskey="u" href="io.html">Up</a></td><td align="right"> <a accesskey="n" href="atomics.html">Next</a></td></tr><tr><td align="left" valign="top">File Based Streams </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Chapter 14. + Atomics + +</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/iterators.html b/libstdc++-v3/doc/html/manual/iterators.html new file mode 100644 index 000000000..8a44178b7 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/iterators.html @@ -0,0 +1,130 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Chapter 10. Iterators</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="bk01pt02.html" title="Part II. Standard Contents"/><link rel="prev" href="containers_and_c.html" title="Interacting with C"/><link rel="next" href="algorithms.html" title="Chapter 11. Algorithms"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 10. + Iterators + +</th></tr><tr><td align="left"><a accesskey="p" href="containers_and_c.html">Prev</a> </td><th width="60%" align="center">Part II. + Standard Contents + </th><td align="right"> <a accesskey="n" href="algorithms.html">Next</a></td></tr></table><hr/></div><div class="chapter" title="Chapter 10. Iterators"><div class="titlepage"><div><div><h2 class="title"><a id="std.iterators"/>Chapter 10. + Iterators + <a id="id479637" class="indexterm"/> +</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="iterators.html#std.iterators.predefined">Predefined</a></span></dt><dd><dl><dt><span class="section"><a href="iterators.html#iterators.predefined.vs_pointers">Iterators vs. Pointers</a></span></dt><dt><span class="section"><a href="iterators.html#iterators.predefined.end">One Past the End</a></span></dt></dl></dd></dl></div><div class="section" title="Predefined"><div class="titlepage"><div><div><h2 class="title"><a id="std.iterators.predefined"/>Predefined</h2></div></div></div><div class="section" title="Iterators vs. Pointers"><div class="titlepage"><div><div><h3 class="title"><a id="iterators.predefined.vs_pointers"/>Iterators vs. Pointers</h3></div></div></div><p> + The following +FAQ <a class="link" href="../faq.html#faq.iterator_as_pod" title="7.1.">entry</a> points out that +iterators are not implemented as pointers. They are a generalization +of pointers, but they are implemented in libstdc++ as separate +classes. + </p><p> + Keeping that simple fact in mind as you design your code will + prevent a whole lot of difficult-to-understand bugs. + </p><p> + You can think of it the other way 'round, even. Since iterators + are a generalization, that means + that <span class="emphasis"><em>pointers</em></span> are + <span class="emphasis"><em>iterators</em></span>, and that pointers can be used + whenever an iterator would be. All those functions in the + Algorithms sect1 of the Standard will work just as well on plain + arrays and their pointers. + </p><p> + That doesn't mean that when you pass in a pointer, it gets + wrapped into some special delegating iterator-to-pointer class + with a layer of overhead. (If you think that's the case + anywhere, you don't understand templates to begin with...) Oh, + no; if you pass in a pointer, then the compiler will instantiate + that template using T* as a type, and good old high-speed + pointer arithmetic as its operations, so the resulting code will + be doing exactly the same things as it would be doing if you had + hand-coded it yourself (for the 273rd time). + </p><p> + How much overhead <span class="emphasis"><em>is</em></span> there when using an + iterator class? Very little. Most of the layering classes + contain nothing but typedefs, and typedefs are + "meta-information" that simply tell the compiler some + nicknames; they don't create code. That information gets passed + down through inheritance, so while the compiler has to do work + looking up all the names, your runtime code does not. (This has + been a prime concern from the beginning.) + </p></div><div class="section" title="One Past the End"><div class="titlepage"><div><div><h3 class="title"><a id="iterators.predefined.end"/>One Past the End</h3></div></div></div><p>This starts off sounding complicated, but is actually very easy, + especially towards the end. Trust me. + </p><p>Beginners usually have a little trouble understand the whole + 'past-the-end' thing, until they remember their early algebra classes + (see, they <span class="emphasis"><em>told</em></span> you that stuff would come in handy!) and + the concept of half-open ranges. + </p><p>First, some history, and a reminder of some of the funkier rules in + C and C++ for builtin arrays. The following rules have always been + true for both languages: + </p><div class="orderedlist"><ol class="orderedlist"><li class="listitem"><p>You can point anywhere in the array, <span class="emphasis"><em>or to the first element + past the end of the array</em></span>. A pointer that points to one + past the end of the array is guaranteed to be as unique as a + pointer to somewhere inside the array, so that you can compare + such pointers safely. + </p></li><li class="listitem"><p>You can only dereference a pointer that points into an array. + If your array pointer points outside the array -- even to just + one past the end -- and you dereference it, Bad Things happen. + </p></li><li class="listitem"><p>Strictly speaking, simply pointing anywhere else invokes + undefined behavior. Most programs won't puke until such a + pointer is actually dereferenced, but the standards leave that + up to the platform. + </p></li></ol></div><p>The reason this past-the-end addressing was allowed is to make it + easy to write a loop to go over an entire array, e.g., + while (*d++ = *s++);. + </p><p>So, when you think of two pointers delimiting an array, don't think + of them as indexing 0 through n-1. Think of them as <span class="emphasis"><em>boundary + markers</em></span>: + </p><pre class="programlisting"> + + beginning end + | | + | | This is bad. Always having to + | | remember to add or subtract one. + | | Off-by-one bugs very common here. + V V + array of N elements + |---|---|--...--|---|---| + | 0 | 1 | ... |N-2|N-1| + |---|---|--...--|---|---| + + ^ ^ + | | + | | This is good. This is safe. This + | | is guaranteed to work. Just don't + | | dereference 'end'. + beginning end + + </pre><p>See? Everything between the boundary markers is chapter of the array. + Simple. + </p><p>Now think back to your junior-high school algebra course, when you + were learning how to draw graphs. Remember that a graph terminating + with a solid dot meant, "Everything up through this point," + and a graph terminating with an open dot meant, "Everything up + to, but not including, this point," respectively called closed + and open ranges? Remember how closed ranges were written with + brackets, <span class="emphasis"><em>[a,b]</em></span>, and open ranges were written with parentheses, + <span class="emphasis"><em>(a,b)</em></span>? + </p><p>The boundary markers for arrays describe a <span class="emphasis"><em>half-open range</em></span>, + starting with (and including) the first element, and ending with (but + not including) the last element: <span class="emphasis"><em>[beginning,end)</em></span>. See, I + told you it would be simple in the end. + </p><p>Iterators, and everything working with iterators, follows this same + time-honored tradition. A container's <code class="code">begin()</code> method returns + an iterator referring to the first element, and its <code class="code">end()</code> + method returns a past-the-end iterator, which is guaranteed to be + unique and comparable against any other iterator pointing into the + middle of the container. + </p><p>Container constructors, container methods, and algorithms, all take + pairs of iterators describing a range of values on which to operate. + All of these ranges are half-open ranges, so you pass the beginning + iterator as the starting parameter, and the one-past-the-end iterator + as the finishing parameter. + </p><p>This generalizes very well. You can operate on sub-ranges quite + easily this way; functions accepting a <span class="emphasis"><em>[first,last)</em></span> range + don't know or care whether they are the boundaries of an entire {array, + sequence, container, whatever}, or whether they only enclose a few + elements from the center. This approach also makes zero-length + sequences very simple to recognize: if the two endpoints compare + equal, then the {array, sequence, container, whatever} is empty. + </p><p>Just don't dereference <code class="code">end()</code>. + </p></div></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="containers_and_c.html">Prev</a> </td><td align="center"><a accesskey="u" href="bk01pt02.html">Up</a></td><td align="right"> <a accesskey="n" href="algorithms.html">Next</a></td></tr><tr><td align="left" valign="top">Interacting with C </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Chapter 11. + Algorithms + +</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/license.html b/libstdc++-v3/doc/html/manual/license.html new file mode 100644 index 000000000..da021a9fe --- /dev/null +++ b/libstdc++-v3/doc/html/manual/license.html @@ -0,0 +1,105 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>License</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="status.html" title="Chapter 1. Status"/><link rel="prev" href="status.html" title="Chapter 1. Status"/><link rel="next" href="bugs.html" title="Bugs"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">License</th></tr><tr><td align="left"><a accesskey="p" href="status.html">Prev</a> </td><th width="60%" align="center">Chapter 1. Status</th><td align="right"> <a accesskey="n" href="bugs.html">Next</a></td></tr></table><hr/></div><div class="section" title="License"><div class="titlepage"><div><div><h2 class="title"><a id="manual.intro.status.license"/>License</h2></div></div></div><p> + There are two licenses affecting GNU libstdc++: one for the code, + and one for the documentation. + </p><p> + There is a license section in the FAQ regarding common <a class="link" href="../faq.html#faq.license">questions</a>. If you have more + questions, ask the FSF or the <a class="link" href="http://gcc.gnu.org/lists.html">gcc mailing list</a>. + </p><div class="section" title="The Code: GPL"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.status.license.gpl"/>The Code: GPL</h3></div></div></div><p> + The source code is distributed under the <a class="link" href="appendix_gpl.html" title="Appendix D. GNU General Public License version 3">GNU General Public License version 3</a>, + with the addition under section 7 of an exception described in + the <span class="quote">“<span class="quote">GCC Runtime Library Exception, version 3.1</span>”</span> + as follows (or see the file COPYING.RUNTIME): + </p><div class="literallayout"><p><br/> +GCC RUNTIME LIBRARY EXCEPTION<br/> +<br/> +Version 3.1, 31 March 2009<br/> +<br/> +Copyright (C) 2009 <a class="link" href="http://www.fsf.org">Free Software Foundation, Inc.</a><br/> +<br/> +Everyone is permitted to copy and distribute verbatim copies of this<br/> +license document, but changing it is not allowed.<br/> +<br/> +This GCC Runtime Library Exception ("Exception") is an additional<br/> +permission under section 7 of the GNU General Public License, version<br/> +3 ("GPLv3"). It applies to a given file (the "Runtime Library") that<br/> +bears a notice placed by the copyright holder of the file stating that<br/> +the file is governed by GPLv3 along with this Exception.<br/> +<br/> +When you use GCC to compile a program, GCC may combine portions of<br/> +certain GCC header files and runtime libraries with the compiled<br/> +program. The purpose of this Exception is to allow compilation of<br/> +non-GPL (including proprietary) programs to use, in this way, the<br/> +header files and runtime libraries covered by this Exception.<br/> +<br/> +0. Definitions.<br/> +<br/> +A file is an "Independent Module" if it either requires the Runtime<br/> +Library for execution after a Compilation Process, or makes use of an<br/> +interface provided by the Runtime Library, but is not otherwise based<br/> +on the Runtime Library.<br/> +<br/> +"GCC" means a version of the GNU Compiler Collection, with or without<br/> +modifications, governed by version 3 (or a specified later version) of<br/> +the GNU General Public License (GPL) with the option of using any<br/> +subsequent versions published by the FSF.<br/> +<br/> +"GPL-compatible Software" is software whose conditions of propagation,<br/> +modification and use would permit combination with GCC in accord with<br/> +the license of GCC.<br/> +<br/> +"Target Code" refers to output from any compiler for a real or virtual<br/> +target processor architecture, in executable form or suitable for<br/> +input to an assembler, loader, linker and/or execution<br/> +phase. Notwithstanding that, Target Code does not include data in any<br/> +format that is used as a compiler intermediate representation, or used<br/> +for producing a compiler intermediate representation.<br/> +<br/> +The "Compilation Process" transforms code entirely represented in<br/> +non-intermediate languages designed for human-written code, and/or in<br/> +Java Virtual Machine byte code, into Target Code. Thus, for example,<br/> +use of source code generators and preprocessors need not be considered<br/> +part of the Compilation Process, since the Compilation Process can be<br/> +understood as starting with the output of the generators or<br/> +preprocessors.<br/> +<br/> +A Compilation Process is "Eligible" if it is done using GCC, alone or<br/> +with other GPL-compatible software, or if it is done without using any<br/> +work based on GCC. For example, using non-GPL-compatible Software to<br/> +optimize any GCC intermediate representations would not qualify as an<br/> +Eligible Compilation Process.<br/> +<br/> +1. Grant of Additional Permission.<br/> +<br/> +You have permission to propagate a work of Target Code formed by<br/> +combining the Runtime Library with Independent Modules, even if such<br/> +propagation would otherwise violate the terms of GPLv3, provided that<br/> +all Target Code was generated by Eligible Compilation Processes. You<br/> +may then convey such a combination under terms of your choice,<br/> +consistent with the licensing of the Independent Modules.<br/> +<br/> +2. No Weakening of GCC Copyleft.<br/> +<br/> +The availability of this Exception does not imply any general<br/> +presumption that third-party software is unaffected by the copyleft<br/> +requirements of the license of GCC.<br/> + </p></div><p> + Hopefully that text is self-explanatory. If it isn't, you need to speak + to your lawyer, or the Free Software Foundation. + </p></div><div class="section" title="The Documentation: GPL, FDL"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.status.license.fdl"/>The Documentation: GPL, FDL</h3></div></div></div><p> + The documentation shipped with the library and made available over + the web, excluding the pages generated from source comments, are + copyrighted by the Free Software Foundation, and placed under the + <a class="link" href="appendix_gfdl.html" title="Appendix E. GNU Free Documentation License"> GNU Free Documentation + License version 1.3</a>. There are no Front-Cover Texts, no + Back-Cover Texts, and no Invariant Sections. + </p><p> + For documentation generated by doxygen or other automated tools + via processing source code comments and markup, the original source + code license applies to the generated files. Thus, the doxygen + documents are licensed <a class="link" href="appendix_gpl.html" title="Appendix D. GNU General Public License version 3">GPL</a>. + </p><p> + If you plan on making copies of the documentation, please let us know. + We can probably offer suggestions. + </p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="status.html">Prev</a> </td><td align="center"><a accesskey="u" href="status.html">Up</a></td><td align="right"> <a accesskey="n" href="bugs.html">Next</a></td></tr><tr><td align="left" valign="top">Chapter 1. Status </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Bugs</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/localization.html b/libstdc++-v3/doc/html/manual/localization.html new file mode 100644 index 000000000..6947a018e --- /dev/null +++ b/libstdc++-v3/doc/html/manual/localization.html @@ -0,0 +1,436 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Chapter 8. Localization</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="bk01pt02.html" title="Part II. Standard Contents"/><link rel="prev" href="strings.html" title="Chapter 7. Strings"/><link rel="next" href="facets.html" title="Facets"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 8. + Localization + +</th></tr><tr><td align="left"><a accesskey="p" href="strings.html">Prev</a> </td><th width="60%" align="center">Part II. + Standard Contents + </th><td align="right"> <a accesskey="n" href="facets.html">Next</a></td></tr></table><hr/></div><div class="chapter" title="Chapter 8. Localization"><div class="titlepage"><div><div><h2 class="title"><a id="std.localization"/>Chapter 8. + Localization + <a id="id475905" class="indexterm"/> +</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="localization.html#std.localization.locales">Locales</a></span></dt><dd><dl><dt><span class="section"><a href="localization.html#std.localization.locales.locale">locale</a></span></dt></dl></dd><dt><span class="section"><a href="facets.html">Facets</a></span></dt><dd><dl><dt><span class="section"><a href="facets.html#std.localization.facet.ctype">ctype</a></span></dt><dt><span class="section"><a href="facets.html#std.localization.facet.codecvt">codecvt</a></span></dt><dt><span class="section"><a href="facets.html#manual.localization.facet.messages">messages</a></span></dt></dl></dd></dl></div><div class="section" title="Locales"><div class="titlepage"><div><div><h2 class="title"><a id="std.localization.locales"/>Locales</h2></div></div></div><div class="section" title="locale"><div class="titlepage"><div><div><h3 class="title"><a id="std.localization.locales.locale"/>locale</h3></div></div></div><p> +Describes the basic locale object, including nested +classes id, facet, and the reference-counted implementation object, +class _Impl. +</p><div class="section" title="Requirements"><div class="titlepage"><div><div><h4 class="title"><a id="locales.locale.req"/>Requirements</h4></div></div></div><p> +Class locale is non-templatized and has two distinct types nested +inside of it: +</p><div class="blockquote"><blockquote class="blockquote"><p> +<span class="emphasis"><em> +class facet +22.1.1.1.2 Class locale::facet +</em></span> +</p></blockquote></div><p> +Facets actually implement locale functionality. For instance, a facet +called numpunct is the data object that can be used to query for the +thousands separator in the locale. +</p><p> +Literally, a facet is strictly defined: +</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + Containing the following public data member: + </p><p> + <code class="code">static locale::id id;</code> + </p></li><li class="listitem"><p> + Derived from another facet: + </p><p> + <code class="code">class gnu_codecvt: public std::ctype<user-defined-type></code> + </p></li></ul></div><p> +Of interest in this class are the memory management options explicitly +specified as an argument to facet's constructor. Each constructor of a +facet class takes a std::size_t __refs argument: if __refs == 0, the +facet is deleted when the locale containing it is destroyed. If __refs +== 1, the facet is not destroyed, even when it is no longer +referenced. +</p><div class="blockquote"><blockquote class="blockquote"><p> +<span class="emphasis"><em> +class id +22.1.1.1.3 - Class locale::id +</em></span> +</p></blockquote></div><p> +Provides an index for looking up specific facets. +</p></div><div class="section" title="Design"><div class="titlepage"><div><div><h4 class="title"><a id="locales.locale.design"/>Design</h4></div></div></div><p> +The major design challenge is fitting an object-orientated and +non-global locale design on top of POSIX and other relevant standards, +which include the Single Unix (nee X/Open.) +</p><p> +Because C and earlier versions of POSIX fall down so completely, +portability is an issue. +</p></div><div class="section" title="Implementation"><div class="titlepage"><div><div><h4 class="title"><a id="locales.locale.impl"/>Implementation</h4></div></div></div><div class="section" title="Interacting with "C" locales"><div class="titlepage"><div><div><h5 class="title"><a id="locale.impl.c"/>Interacting with "C" locales</h5></div></div></div><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + <code class="code">`locale -a`</code> displays available locales. + </p><div class="blockquote"><blockquote class="blockquote"><pre class="programlisting"> +af_ZA +ar_AE +ar_AE.utf8 +ar_BH +ar_BH.utf8 +ar_DZ +ar_DZ.utf8 +ar_EG +ar_EG.utf8 +ar_IN +ar_IQ +ar_IQ.utf8 +ar_JO +ar_JO.utf8 +ar_KW +ar_KW.utf8 +ar_LB +ar_LB.utf8 +ar_LY +ar_LY.utf8 +ar_MA +ar_MA.utf8 +ar_OM +ar_OM.utf8 +ar_QA +ar_QA.utf8 +ar_SA +ar_SA.utf8 +ar_SD +ar_SD.utf8 +ar_SY +ar_SY.utf8 +ar_TN +ar_TN.utf8 +ar_YE +ar_YE.utf8 +be_BY +be_BY.utf8 +bg_BG +bg_BG.utf8 +br_FR +bs_BA +C +ca_ES +ca_ES@euro +ca_ES.utf8 +ca_ES.utf8@euro +cs_CZ +cs_CZ.utf8 +cy_GB +da_DK +da_DK.iso885915 +da_DK.utf8 +de_AT +de_AT@euro +de_AT.utf8 +de_AT.utf8@euro +de_BE +de_BE@euro +de_BE.utf8 +de_BE.utf8@euro +de_CH +de_CH.utf8 +de_DE +de_DE@euro +de_DE.utf8 +de_DE.utf8@euro +de_LU +de_LU@euro +de_LU.utf8 +de_LU.utf8@euro +el_GR +el_GR.utf8 +en_AU +en_AU.utf8 +en_BW +en_BW.utf8 +en_CA +en_CA.utf8 +en_DK +en_DK.utf8 +en_GB +en_GB.iso885915 +en_GB.utf8 +en_HK +en_HK.utf8 +en_IE +en_IE@euro +en_IE.utf8 +en_IE.utf8@euro +en_IN +en_NZ +en_NZ.utf8 +en_PH +en_PH.utf8 +en_SG +en_SG.utf8 +en_US +en_US.iso885915 +en_US.utf8 +en_ZA +en_ZA.utf8 +en_ZW +en_ZW.utf8 +es_AR +es_AR.utf8 +es_BO +es_BO.utf8 +es_CL +es_CL.utf8 +es_CO +es_CO.utf8 +es_CR +es_CR.utf8 +es_DO +es_DO.utf8 +es_EC +es_EC.utf8 +es_ES +es_ES@euro +es_ES.utf8 +es_ES.utf8@euro +es_GT +es_GT.utf8 +es_HN +es_HN.utf8 +es_MX +es_MX.utf8 +es_NI +es_NI.utf8 +es_PA +es_PA.utf8 +es_PE +es_PE.utf8 +es_PR +es_PR.utf8 +es_PY +es_PY.utf8 +es_SV +es_SV.utf8 +es_US +es_US.utf8 +es_UY +es_UY.utf8 +es_VE +es_VE.utf8 +et_EE +et_EE.utf8 +eu_ES +eu_ES@euro +eu_ES.utf8 +eu_ES.utf8@euro +fa_IR +fi_FI +fi_FI@euro +fi_FI.utf8 +fi_FI.utf8@euro +fo_FO +fo_FO.utf8 +fr_BE +fr_BE@euro +fr_BE.utf8 +fr_BE.utf8@euro +fr_CA +fr_CA.utf8 +fr_CH +fr_CH.utf8 +fr_FR +fr_FR@euro +fr_FR.utf8 +fr_FR.utf8@euro +fr_LU +fr_LU@euro +fr_LU.utf8 +fr_LU.utf8@euro +ga_IE +ga_IE@euro +ga_IE.utf8 +ga_IE.utf8@euro +gl_ES +gl_ES@euro +gl_ES.utf8 +gl_ES.utf8@euro +gv_GB +gv_GB.utf8 +he_IL +he_IL.utf8 +hi_IN +hr_HR +hr_HR.utf8 +hu_HU +hu_HU.utf8 +id_ID +id_ID.utf8 +is_IS +is_IS.utf8 +it_CH +it_CH.utf8 +it_IT +it_IT@euro +it_IT.utf8 +it_IT.utf8@euro +iw_IL +iw_IL.utf8 +ja_JP.eucjp +ja_JP.utf8 +ka_GE +kl_GL +kl_GL.utf8 +ko_KR.euckr +ko_KR.utf8 +kw_GB +kw_GB.utf8 +lt_LT +lt_LT.utf8 +lv_LV +lv_LV.utf8 +mi_NZ +mk_MK +mk_MK.utf8 +mr_IN +ms_MY +ms_MY.utf8 +mt_MT +mt_MT.utf8 +nl_BE +nl_BE@euro +nl_BE.utf8 +nl_BE.utf8@euro +nl_NL +nl_NL@euro +nl_NL.utf8 +nl_NL.utf8@euro +nn_NO +nn_NO.utf8 +no_NO +no_NO.utf8 +oc_FR +pl_PL +pl_PL.utf8 +POSIX +pt_BR +pt_BR.utf8 +pt_PT +pt_PT@euro +pt_PT.utf8 +pt_PT.utf8@euro +ro_RO +ro_RO.utf8 +ru_RU +ru_RU.koi8r +ru_RU.utf8 +ru_UA +ru_UA.utf8 +se_NO +sk_SK +sk_SK.utf8 +sl_SI +sl_SI.utf8 +sq_AL +sq_AL.utf8 +sr_YU +sr_YU@cyrillic +sr_YU.utf8 +sr_YU.utf8@cyrillic +sv_FI +sv_FI@euro +sv_FI.utf8 +sv_FI.utf8@euro +sv_SE +sv_SE.iso885915 +sv_SE.utf8 +ta_IN +te_IN +tg_TJ +th_TH +th_TH.utf8 +tl_PH +tr_TR +tr_TR.utf8 +uk_UA +uk_UA.utf8 +ur_PK +uz_UZ +vi_VN +vi_VN.tcvn +wa_BE +wa_BE@euro +yi_US +zh_CN +zh_CN.gb18030 +zh_CN.gbk +zh_CN.utf8 +zh_HK +zh_HK.utf8 +zh_TW +zh_TW.euctw +zh_TW.utf8 +</pre></blockquote></div></li><li class="listitem"><p> + <code class="code">`locale`</code> displays environmental variables that + impact how locale("") will be deduced. + </p><div class="blockquote"><blockquote class="blockquote"><pre class="programlisting"> +LANG=en_US +LC_CTYPE="en_US" +LC_NUMERIC="en_US" +LC_TIME="en_US" +LC_COLLATE="en_US" +LC_MONETARY="en_US" +LC_MESSAGES="en_US" +LC_PAPER="en_US" +LC_NAME="en_US" +LC_ADDRESS="en_US" +LC_TELEPHONE="en_US" +LC_MEASUREMENT="en_US" +LC_IDENTIFICATION="en_US" +LC_ALL= +</pre></blockquote></div></li></ul></div><p> +From Josuttis, p. 697-698, which says, that "there is only *one* +relation (of the C++ locale mechanism) to the C locale mechanism: the +global C locale is modified if a named C++ locale object is set as the +global locale" (emphasis Paolo), that is: +</p><pre class="programlisting">std::locale::global(std::locale(""));</pre><p>affects the C functions as if the following call was made:</p><pre class="programlisting">std::setlocale(LC_ALL, "");</pre><p> + On the other hand, there is *no* vice versa, that is, calling + setlocale has *no* whatsoever on the C++ locale mechanism, in + particular on the working of locale(""), which constructs the locale + object from the environment of the running program, that is, in + practice, the set of LC_ALL, LANG, etc. variable of the shell. +</p></div></div><div class="section" title="Future"><div class="titlepage"><div><div><h4 class="title"><a id="locales.locale.future"/>Future</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + Locale initialization: at what point does _S_classic, _S_global + get initialized? Can named locales assume this initialization + has already taken place? + </p></li><li class="listitem"><p> + Document how named locales error check when filling data + members. I.e., a fr_FR locale that doesn't have + numpunct::truename(): does it use "true"? Or is it a blank + string? What's the convention? + </p></li><li class="listitem"><p> + Explain how locale aliasing happens. When does "de_DE" use "de" + information? What is the rule for locales composed of just an + ISO language code (say, "de") and locales with both an ISO + language code and ISO country code (say, "de_DE"). + </p></li><li class="listitem"><p> + What should non-required facet instantiations do? If the + generic implementation is provided, then how to end-users + provide specializations? + </p></li></ul></div></div><div class="bibliography" title="Bibliography"><div class="titlepage"><div><div><h4 class="title"><a id="locales.locale.biblio"/>Bibliography</h4></div></div></div><div class="biblioentry"><a id="id476268"/><p><span class="citetitle"><em class="citetitle"> + The GNU C Library + </em>. </span><span class="author"><span class="firstname">Roland</span> <span class="surname">McGrath</span>. </span><span class="author"><span class="firstname">Ulrich</span> <span class="surname">Drepper</span>. </span><span class="copyright">Copyright © 2007 FSF. </span><span class="pagenums"> + Chapters 6 Character Set Handling and 7 Locales and + Internationalization + . </span></p></div><div class="biblioentry"><a id="id476307"/><p><span class="citetitle"><em class="citetitle"> + Correspondence + </em>. </span><span class="author"><span class="firstname">Ulrich</span> <span class="surname">Drepper</span>. </span><span class="copyright">Copyright © 2002 . </span></p></div><div class="biblioentry"><a id="id476333"/><p><span class="citetitle"><em class="citetitle"> + ISO/IEC 14882:1998 Programming languages - C++ + </em>. </span><span class="copyright">Copyright © 1998 ISO. </span></p></div><div class="biblioentry"><a id="id476352"/><p><span class="citetitle"><em class="citetitle"> + ISO/IEC 9899:1999 Programming languages - C + </em>. </span><span class="copyright">Copyright © 1999 ISO. </span></p></div><div class="biblioentry"><a id="id476371"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + System Interface Definitions, Issue 7 (IEEE Std. 1003.1-2008) + </em>. </span><span class="copyright">Copyright © 2008 + The Open Group/The Institute of Electrical and Electronics + Engineers, Inc. + . </span></p></div><div class="biblioentry"><a id="id476400"/><p><span class="citetitle"><em class="citetitle"> + The C++ Programming Language, Special Edition + </em>. </span><span class="author"><span class="firstname">Bjarne</span> <span class="surname">Stroustrup</span>. </span><span class="copyright">Copyright © 2000 Addison Wesley, Inc.. </span><span class="pagenums">Appendix D. </span><span class="publisher"><span class="publishername"> + Addison Wesley + . </span></span></p></div><div class="biblioentry"><a id="id476439"/><p><span class="citetitle"><em class="citetitle"> + Standard C++ IOStreams and Locales + </em>. </span><span class="subtitle"> + Advanced Programmer's Guide and Reference + . </span><span class="author"><span class="firstname">Angelika</span> <span class="surname">Langer</span>. </span><span class="author"><span class="firstname">Klaus</span> <span class="surname">Kreft</span>. </span><span class="copyright">Copyright © 2000 Addison Wesley Longman, Inc.. </span><span class="publisher"><span class="publishername"> + Addison Wesley Longman + . </span></span></p></div></div></div></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="strings.html">Prev</a> </td><td align="center"><a accesskey="u" href="bk01pt02.html">Up</a></td><td align="right"> <a accesskey="n" href="facets.html">Next</a></td></tr><tr><td align="left" valign="top">Chapter 7. + Strings + + </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Facets</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/make.html b/libstdc++-v3/doc/html/manual/make.html new file mode 100644 index 000000000..62b149924 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/make.html @@ -0,0 +1,9 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Make</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="setup.html" title="Chapter 2. Setup"/><link rel="prev" href="configure.html" title="Configure"/><link rel="next" href="using.html" title="Chapter 3. Using"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Make</th></tr><tr><td align="left"><a accesskey="p" href="configure.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Setup</th><td align="right"> <a accesskey="n" href="using.html">Next</a></td></tr></table><hr/></div><div class="section" title="Make"><div class="titlepage"><div><div><h2 class="title"><a id="manual.intro.setup.make"/>Make</h2></div></div></div><p>If you have never done this before, you should read the basic + <a class="link" href="http://gcc.gnu.org/install/">GCC Installation + Instructions</a> first. Read <span class="emphasis"><em>all of them</em></span>. + <span class="emphasis"><em>Twice.</em></span> + </p><p>Then type: <span class="command"><strong>make</strong></span>, and congratulations, you've +started to build. +</p></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="configure.html">Prev</a> </td><td align="center"><a accesskey="u" href="setup.html">Up</a></td><td align="right"> <a accesskey="n" href="using.html">Next</a></td></tr><tr><td align="left" valign="top">Configure </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Chapter 3. Using</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/memory.html b/libstdc++-v3/doc/html/manual/memory.html new file mode 100644 index 000000000..5953539dc --- /dev/null +++ b/libstdc++-v3/doc/html/manual/memory.html @@ -0,0 +1,699 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Memory</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="utilities.html" title="Chapter 6. Utilities"/><link rel="prev" href="pairs.html" title="Pairs"/><link rel="next" href="traits.html" title="Traits"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Memory</th></tr><tr><td align="left"><a accesskey="p" href="pairs.html">Prev</a> </td><th width="60%" align="center">Chapter 6. + Utilities + +</th><td align="right"> <a accesskey="n" href="traits.html">Next</a></td></tr></table><hr/></div><div class="section" title="Memory"><div class="titlepage"><div><div><h2 class="title"><a id="std.util.memory"/>Memory</h2></div></div></div><p> + Memory contains three general areas. First, function and operator + calls via <code class="function">new</code> and <code class="function">delete</code> + operator or member function calls. Second, allocation via + <code class="classname">allocator</code>. And finally, smart pointer and + intelligent pointer abstractions. + </p><div class="section" title="Allocators"><div class="titlepage"><div><div><h3 class="title"><a id="std.util.memory.allocator"/>Allocators</h3></div></div></div><p> + Memory management for Standard Library entities is encapsulated in a + class template called <code class="classname">allocator</code>. The + <code class="classname">allocator</code> abstraction is used throughout the + library in <code class="classname">string</code>, container classes, + algorithms, and parts of iostreams. This class, and base classes of + it, are the superset of available free store (<span class="quote">“<span class="quote">heap</span>”</span>) + management classes. +</p><div class="section" title="Requirements"><div class="titlepage"><div><div><h4 class="title"><a id="allocator.req"/>Requirements</h4></div></div></div><p> + The C++ standard only gives a few directives in this area: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + When you add elements to a container, and the container must + allocate more memory to hold them, the container makes the + request via its <span class="type">Allocator</span> template + parameter, which is usually aliased to + <span class="type">allocator_type</span>. This includes adding chars + to the string class, which acts as a regular STL container in + this respect. + </p></li><li class="listitem"><p> + The default <span class="type">Allocator</span> argument of every + container-of-T is <code class="classname">allocator<T></code>. + </p></li><li class="listitem"><p> + The interface of the <code class="classname">allocator<T></code> class is + extremely simple. It has about 20 public declarations (nested + typedefs, member functions, etc), but the two which concern us most + are: + </p><pre class="programlisting"> + T* allocate (size_type n, const void* hint = 0); + void deallocate (T* p, size_type n); + </pre><p> + The <code class="varname">n</code> arguments in both those + functions is a <span class="emphasis"><em>count</em></span> of the number of + <span class="type">T</span>'s to allocate space for, <span class="emphasis"><em>not their + total size</em></span>. + (This is a simplification; the real signatures use nested typedefs.) + </p></li><li class="listitem"><p> + The storage is obtained by calling <code class="function">::operator + new</code>, but it is unspecified when or how + often this function is called. The use of the + <code class="varname">hint</code> is unspecified, but intended as an + aid to locality if an implementation so + desires. <code class="constant">[20.4.1.1]/6</code> + </p></li></ul></div><p> + Complete details can be found in the C++ standard, look in + <code class="constant">[20.4 Memory]</code>. + </p></div><div class="section" title="Design Issues"><div class="titlepage"><div><div><h4 class="title"><a id="allocator.design_issues"/>Design Issues</h4></div></div></div><p> + The easiest way of fulfilling the requirements is to call + <code class="function">operator new</code> each time a container needs + memory, and to call <code class="function">operator delete</code> each time + the container releases memory. This method may be <a class="link" href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00105.html">slower</a> + than caching the allocations and re-using previously-allocated + memory, but has the advantage of working correctly across a wide + variety of hardware and operating systems, including large + clusters. The <code class="classname">__gnu_cxx::new_allocator</code> + implements the simple operator new and operator delete semantics, + while <code class="classname">__gnu_cxx::malloc_allocator</code> + implements much the same thing, only with the C language functions + <code class="function">std::malloc</code> and <code class="function">free</code>. + </p><p> + Another approach is to use intelligence within the allocator + class to cache allocations. This extra machinery can take a variety + of forms: a bitmap index, an index into an exponentially increasing + power-of-two-sized buckets, or simpler fixed-size pooling cache. + The cache is shared among all the containers in the program: when + your program's <code class="classname">std::vector<int></code> gets + cut in half and frees a bunch of its storage, that memory can be + reused by the private + <code class="classname">std::list<WonkyWidget></code> brought in from + a KDE library that you linked against. And operators + <code class="function">new</code> and <code class="function">delete</code> are not + always called to pass the memory on, either, which is a speed + bonus. Examples of allocators that use these techniques are + <code class="classname">__gnu_cxx::bitmap_allocator</code>, + <code class="classname">__gnu_cxx::pool_allocator</code>, and + <code class="classname">__gnu_cxx::__mt_alloc</code>. + </p><p> + Depending on the implementation techniques used, the underlying + operating system, and compilation environment, scaling caching + allocators can be tricky. In particular, order-of-destruction and + order-of-creation for memory pools may be difficult to pin down + with certainty, which may create problems when used with plugins + or loading and unloading shared objects in memory. As such, using + caching allocators on systems that do not support + <code class="function">abi::__cxa_atexit</code> is not recommended. + </p></div><div class="section" title="Implementation"><div class="titlepage"><div><div><h4 class="title"><a id="allocator.impl"/>Implementation</h4></div></div></div><div class="section" title="Interface Design"><div class="titlepage"><div><div><h5 class="title"><a id="id473085"/>Interface Design</h5></div></div></div><p> + The only allocator interface that + is supported is the standard C++ interface. As such, all STL + containers have been adjusted, and all external allocators have + been modified to support this change. + </p><p> + The class <code class="classname">allocator</code> just has typedef, + constructor, and rebind members. It inherits from one of the + high-speed extension allocators, covered below. Thus, all + allocation and deallocation depends on the base class. + </p><p> + The base class that <code class="classname">allocator</code> is derived from + may not be user-configurable. +</p></div><div class="section" title="Selecting Default Allocation Policy"><div class="titlepage"><div><div><h5 class="title"><a id="id473115"/>Selecting Default Allocation Policy</h5></div></div></div><p> + It's difficult to pick an allocation strategy that will provide + maximum utility, without excessively penalizing some behavior. In + fact, it's difficult just deciding which typical actions to measure + for speed. + </p><p> + Three synthetic benchmarks have been created that provide data + that is used to compare different C++ allocators. These tests are: + </p><div class="orderedlist"><ol class="orderedlist"><li class="listitem"><p> + Insertion. + </p><p> + Over multiple iterations, various STL container + objects have elements inserted to some maximum amount. A variety + of allocators are tested. + Test source for <a class="link" href="http://gcc.gnu.org/viewcvs/trunk/libstdc%2B%2B-v3/testsuite/performance/23_containers/insert/sequence.cc?view=markup">sequence</a> + and <a class="link" href="http://gcc.gnu.org/viewcvs/trunk/libstdc%2B%2B-v3/testsuite/performance/23_containers/insert/associative.cc?view=markup">associative</a> + containers. + </p></li><li class="listitem"><p> + Insertion and erasure in a multi-threaded environment. + </p><p> + This test shows the ability of the allocator to reclaim memory + on a per-thread basis, as well as measuring thread contention + for memory resources. + Test source + <a class="link" href="http://gcc.gnu.org/viewcvs/trunk/libstdc%2B%2B-v3/testsuite/performance/23_containers/insert_erase/associative.cc?view=markup">here</a>. + </p></li><li class="listitem"><p> + A threaded producer/consumer model. + </p><p> + Test source for + <a class="link" href="http://gcc.gnu.org/viewcvs/trunk/libstdc++-v3/testsuite/performance/23_containers/producer_consumer/sequence.cc?view=markup">sequence</a> + and + <a class="link" href="http://gcc.gnu.org/viewcvs/trunk/libstdc++-v3/testsuite/performance/23_containers/producer_consumer/associative.cc?view=markup">associative</a> + containers. + </p></li></ol></div><p> + The current default choice for + <code class="classname">allocator</code> is + <code class="classname">__gnu_cxx::new_allocator</code>. + </p></div><div class="section" title="Disabling Memory Caching"><div class="titlepage"><div><div><h5 class="title"><a id="id473225"/>Disabling Memory Caching</h5></div></div></div><p> + In use, <code class="classname">allocator</code> may allocate and + deallocate using implementation-specified strategies and + heuristics. Because of this, every call to an allocator object's + <code class="function">allocate</code> member function may not actually + call the global operator new. This situation is also duplicated + for calls to the <code class="function">deallocate</code> member + function. + </p><p> + This can be confusing. + </p><p> + In particular, this can make debugging memory errors more + difficult, especially when using third party tools like valgrind or + debug versions of <code class="function">new</code>. + </p><p> + There are various ways to solve this problem. One would be to use + a custom allocator that just called operators + <code class="function">new</code> and <code class="function">delete</code> + directly, for every allocation. (See + <code class="filename">include/ext/new_allocator.h</code>, for instance.) + However, that option would involve changing source code to use + a non-default allocator. Another option is to force the + default allocator to remove caching and pools, and to directly + allocate with every call of <code class="function">allocate</code> and + directly deallocate with every call of + <code class="function">deallocate</code>, regardless of efficiency. As it + turns out, this last option is also available. + </p><p> + To globally disable memory caching within the library for the + default allocator, merely set + <code class="constant">GLIBCXX_FORCE_NEW</code> (with any value) in the + system's environment before running the program. If your program + crashes with <code class="constant">GLIBCXX_FORCE_NEW</code> in the + environment, it likely means that you linked against objects + built against the older library (objects which might still using the + cached allocations...). + </p></div></div><div class="section" title="Using a Specific Allocator"><div class="titlepage"><div><div><h4 class="title"><a id="allocator.using"/>Using a Specific Allocator</h4></div></div></div><p> + You can specify different memory management schemes on a + per-container basis, by overriding the default + <span class="type">Allocator</span> template parameter. For example, an easy + (but non-portable) method of specifying that only <code class="function">malloc</code> or <code class="function">free</code> + should be used instead of the default node allocator is: + </p><pre class="programlisting"> + std::list <int, __gnu_cxx::malloc_allocator<int> > malloc_list;</pre><p> + Likewise, a debugging form of whichever allocator is currently in use: + </p><pre class="programlisting"> + std::deque <int, __gnu_cxx::debug_allocator<std::allocator<int> > > debug_deque; + </pre></div><div class="section" title="Custom Allocators"><div class="titlepage"><div><div><h4 class="title"><a id="allocator.custom"/>Custom Allocators</h4></div></div></div><p> + Writing a portable C++ allocator would dictate that the interface + would look much like the one specified for + <code class="classname">allocator</code>. Additional member functions, but + not subtractions, would be permissible. + </p><p> + Probably the best place to start would be to copy one of the + extension allocators: say a simple one like + <code class="classname">new_allocator</code>. + </p></div><div class="section" title="Extension Allocators"><div class="titlepage"><div><div><h4 class="title"><a id="allocator.ext"/>Extension Allocators</h4></div></div></div><p> + Several other allocators are provided as part of this + implementation. The location of the extension allocators and their + names have changed, but in all cases, functionality is + equivalent. Starting with gcc-3.4, all extension allocators are + standard style. Before this point, SGI style was the norm. Because of + this, the number of template arguments also changed. Here's a simple + chart to track the changes. + </p><p> + More details on each of these extension allocators follows. + </p><div class="orderedlist"><ol class="orderedlist"><li class="listitem"><p> + <code class="classname">new_allocator</code> + </p><p> + Simply wraps <code class="function">::operator new</code> + and <code class="function">::operator delete</code>. + </p></li><li class="listitem"><p> + <code class="classname">malloc_allocator</code> + </p><p> + Simply wraps <code class="function">malloc</code> and + <code class="function">free</code>. There is also a hook for an + out-of-memory handler (for + <code class="function">new</code>/<code class="function">delete</code> this is + taken care of elsewhere). + </p></li><li class="listitem"><p> + <code class="classname">array_allocator</code> + </p><p> + Allows allocations of known and fixed sizes using existing + global or external storage allocated via construction of + <code class="classname">std::tr1::array</code> objects. By using this + allocator, fixed size containers (including + <code class="classname">std::string</code>) can be used without + instances calling <code class="function">::operator new</code> and + <code class="function">::operator delete</code>. This capability + allows the use of STL abstractions without runtime + complications or overhead, even in situations such as program + startup. For usage examples, please consult the testsuite. + </p></li><li class="listitem"><p> + <code class="classname">debug_allocator</code> + </p><p> + A wrapper around an arbitrary allocator A. It passes on + slightly increased size requests to A, and uses the extra + memory to store size information. When a pointer is passed + to <code class="function">deallocate()</code>, the stored size is + checked, and <code class="function">assert()</code> is used to + guarantee they match. + </p></li><li class="listitem"><p> + <code class="classname">throw_allocator</code> + </p><p> + Includes memory tracking and marking abilities as well as hooks for + throwing exceptions at configurable intervals (including random, + all, none). + </p></li><li class="listitem"><p> + <code class="classname">__pool_alloc</code> + </p><p> + A high-performance, single pool allocator. The reusable + memory is shared among identical instantiations of this type. + It calls through <code class="function">::operator new</code> to + obtain new memory when its lists run out. If a client + container requests a block larger than a certain threshold + size, then the pool is bypassed, and the allocate/deallocate + request is passed to <code class="function">::operator new</code> + directly. + </p><p> + Older versions of this class take a boolean template + parameter, called <code class="varname">thr</code>, and an integer template + parameter, called <code class="varname">inst</code>. + </p><p> + The <code class="varname">inst</code> number is used to track additional memory + pools. The point of the number is to allow multiple + instantiations of the classes without changing the semantics at + all. All three of + </p><pre class="programlisting"> + typedef __pool_alloc<true,0> normal; + typedef __pool_alloc<true,1> private; + typedef __pool_alloc<true,42> also_private; + </pre><p> + behave exactly the same way. However, the memory pool for each type + (and remember that different instantiations result in different types) + remains separate. + </p><p> + The library uses <span class="emphasis"><em>0</em></span> in all its instantiations. If you + wish to keep separate free lists for a particular purpose, use a + different number. + </p><p>The <code class="varname">thr</code> boolean determines whether the + pool should be manipulated atomically or not. When + <code class="varname">thr</code> = <code class="constant">true</code>, the allocator + is thread-safe, while <code class="varname">thr</code> = + <code class="constant">false</code>, is slightly faster but unsafe for + multiple threads. + </p><p> + For thread-enabled configurations, the pool is locked with a + single big lock. In some situations, this implementation detail + may result in severe performance degradation. + </p><p> + (Note that the GCC thread abstraction layer allows us to provide + safe zero-overhead stubs for the threading routines, if threads + were disabled at configuration time.) + </p></li><li class="listitem"><p> + <code class="classname">__mt_alloc</code> + </p><p> + A high-performance fixed-size allocator with + exponentially-increasing allocations. It has its own + documentation, found <a class="link" href="ext_allocators.html#manual.ext.allocator.mt" title="mt_allocator">here</a>. + </p></li><li class="listitem"><p> + <code class="classname">bitmap_allocator</code> + </p><p> + A high-performance allocator that uses a bit-map to keep track + of the used and unused memory locations. It has its own + documentation, found <a class="link" href="bitmap_allocator.html" title="bitmap_allocator">here</a>. + </p></li></ol></div></div><div class="bibliography" title="Bibliography"><div class="titlepage"><div><div><h4 class="title"><a id="allocator.biblio"/>Bibliography</h4></div></div></div><div class="biblioentry"><a id="id473676"/><p><span class="citetitle"><em class="citetitle"> + ISO/IEC 14882:1998 Programming languages - C++ + </em>. </span> + isoc++_1998 + <span class="pagenums">20.4 Memory. </span></p></div><div class="biblioentry"><a id="id473691"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + The Standard Librarian: What Are Allocators Good For? + </em>. </span><span class="author"><span class="firstname">Matt</span> <span class="surname">Austern</span>. </span><span class="publisher"><span class="publishername"> + C/C++ Users Journal + . </span></span></p></div><div class="biblioentry"><a id="id473725"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + The Hoard Memory Allocator + </em>. </span><span class="author"><span class="firstname">Emery</span> <span class="surname">Berger</span>. </span></p></div><div class="biblioentry"><a id="id473750"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + Reconsidering Custom Memory Allocation + </em>. </span><span class="author"><span class="firstname">Emery</span> <span class="surname">Berger</span>. </span><span class="author"><span class="firstname">Ben</span> <span class="surname">Zorn</span>. </span><span class="author"><span class="firstname">Kathryn</span> <span class="surname">McKinley</span>. </span><span class="copyright">Copyright © 2002 OOPSLA. </span></p></div><div class="biblioentry"><a id="id473804"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + Allocator Types + </em>. </span><span class="author"><span class="firstname">Klaus</span> <span class="surname">Kreft</span>. </span><span class="author"><span class="firstname">Angelika</span> <span class="surname">Langer</span>. </span><span class="publisher"><span class="publishername"> + C/C++ Users Journal + . </span></span></p></div><div class="biblioentry"><a id="id473845"/><p><span class="citetitle"><em class="citetitle">The C++ Programming Language</em>. </span><span class="author"><span class="firstname">Bjarne</span> <span class="surname">Stroustrup</span>. </span><span class="copyright">Copyright © 2000 . </span><span class="pagenums">19.4 Allocators. </span><span class="publisher"><span class="publishername"> + Addison Wesley + . </span></span></p></div><div class="biblioentry"><a id="id473882"/><p><span class="citetitle"><em class="citetitle">Yalloc: A Recycling C++ Allocator</em>. </span><span class="author"><span class="firstname">Felix</span> <span class="surname">Yen</span>. </span></p></div></div></div><div class="section" title="auto_ptr"><div class="titlepage"><div><div><h3 class="title"><a id="std.util.memory.auto_ptr"/>auto_ptr</h3></div></div></div><div class="section" title="Limitations"><div class="titlepage"><div><div><h4 class="title"><a id="auto_ptr.limitations"/>Limitations</h4></div></div></div><p>Explaining all of the fun and delicious things that can + happen with misuse of the <code class="classname">auto_ptr</code> class + template (called <acronym class="acronym">AP</acronym> here) would take some + time. Suffice it to say that the use of <acronym class="acronym">AP</acronym> + safely in the presence of copying has some subtleties. + </p><p> + The AP class is a really + nifty idea for a smart pointer, but it is one of the dumbest of + all the smart pointers -- and that's fine. + </p><p> + AP is not meant to be a supersmart solution to all resource + leaks everywhere. Neither is it meant to be an effective form + of garbage collection (although it can help, a little bit). + And it can <span class="emphasis"><em>not</em></span>be used for arrays! + </p><p> + <acronym class="acronym">AP</acronym> is meant to prevent nasty leaks in the + presence of exceptions. That's <span class="emphasis"><em>all</em></span>. This + code is AP-friendly: + </p><pre class="programlisting"> + // Not a recommend naming scheme, but good for web-based FAQs. + typedef std::auto_ptr<MyClass> APMC; + + extern function_taking_MyClass_pointer (MyClass*); + extern some_throwable_function (); + + void func (int data) + { + APMC ap (new MyClass(data)); + + some_throwable_function(); // this will throw an exception + + function_taking_MyClass_pointer (ap.get()); + } + </pre><p>When an exception gets thrown, the instance of MyClass that's + been created on the heap will be <code class="function">delete</code>'d as the stack is + unwound past <code class="function">func()</code>. + </p><p>Changing that code as follows is not <acronym class="acronym">AP</acronym>-friendly: + </p><pre class="programlisting"> + APMC ap (new MyClass[22]); + </pre><p>You will get the same problems as you would without the use + of <acronym class="acronym">AP</acronym>: + </p><pre class="programlisting"> + char* array = new char[10]; // array new... + ... + delete array; // ...but single-object delete + </pre><p> + AP cannot tell whether the pointer you've passed at creation points + to one or many things. If it points to many things, you are about + to die. AP is trivial to write, however, so you could write your + own <code class="code">auto_array_ptr</code> for that situation (in fact, this has + been done many times; check the mailing lists, Usenet, Boost, etc). + </p></div><div class="section" title="Use in Containers"><div class="titlepage"><div><div><h4 class="title"><a id="auto_ptr.using"/>Use in Containers</h4></div></div></div><p> + </p><p>All of the <a class="link" href="containers.html" title="Chapter 9. Containers">containers</a> + described in the standard library require their contained types + to have, among other things, a copy constructor like this: + </p><pre class="programlisting"> + struct My_Type + { + My_Type (My_Type const&); + }; + </pre><p> + Note the const keyword; the object being copied shouldn't change. + The template class <code class="code">auto_ptr</code> (called AP here) does not + meet this requirement. Creating a new AP by copying an existing + one transfers ownership of the pointed-to object, which means that + the AP being copied must change, which in turn means that the + copy ctors of AP do not take const objects. + </p><p> + The resulting rule is simple: <span class="emphasis"><em>Never ever use a + container of auto_ptr objects</em></span>. The standard says that + <span class="quote">“<span class="quote">undefined</span>”</span> behavior is the result, but it is + guaranteed to be messy. + </p><p> + To prevent you from doing this to yourself, the + <a class="link" href="ext_compile_checks.html" title="Chapter 16. Compile Time Checks">concept checks</a> built + in to this implementation will issue an error if you try to + compile code like this: + </p><pre class="programlisting"> + #include <vector> + #include <memory> + + void f() + { + std::vector< std::auto_ptr<int> > vec_ap_int; + } + </pre><p> +Should you try this with the checks enabled, you will see an error. + </p></div></div><div class="section" title="shared_ptr"><div class="titlepage"><div><div><h3 class="title"><a id="std.util.memory.shared_ptr"/>shared_ptr</h3></div></div></div><p> +The shared_ptr class template stores a pointer, usually obtained via new, +and implements shared ownership semantics. +</p><div class="section" title="Requirements"><div class="titlepage"><div><div><h4 class="title"><a id="shared_ptr.req"/>Requirements</h4></div></div></div><p> + </p><p> + The standard deliberately doesn't require a reference-counted + implementation, allowing other techniques such as a + circular-linked-list. + </p><p> + At the time of writing the C++0x working paper doesn't mention how + threads affect shared_ptr, but it is likely to follow the existing + practice set by <code class="classname">boost::shared_ptr</code>. The + shared_ptr in libstdc++ is derived from Boost's, so the same rules + apply. + </p><p> + </p></div><div class="section" title="Design Issues"><div class="titlepage"><div><div><h4 class="title"><a id="shared_ptr.design_issues"/>Design Issues</h4></div></div></div><p> +The <code class="classname">shared_ptr</code> code is kindly donated to GCC by the Boost +project and the original authors of the code. The basic design and +algorithms are from Boost, the notes below describe details specific to +the GCC implementation. Names have been uglified in this implementation, +but the design should be recognisable to anyone familiar with the Boost +1.32 shared_ptr. + </p><p> +The basic design is an abstract base class, <code class="code">_Sp_counted_base</code> that +does the reference-counting and calls virtual functions when the count +drops to zero. +Derived classes override those functions to destroy resources in a context +where the correct dynamic type is known. This is an application of the +technique known as type erasure. + </p></div><div class="section" title="Implementation"><div class="titlepage"><div><div><h4 class="title"><a id="shared_ptr.impl"/>Implementation</h4></div></div></div><div class="section" title="Class Hierarchy"><div class="titlepage"><div><div><h5 class="title"><a id="id474243"/>Class Hierarchy</h5></div></div></div><p> +A <code class="classname">shared_ptr<T></code> contains a pointer of +type <span class="type">T*</span> and an object of type +<code class="classname">__shared_count</code>. The shared_count contains a +pointer of type <span class="type">_Sp_counted_base*</span> which points to the +object that maintains the reference-counts and destroys the managed +resource. + </p><div class="variablelist"><dl><dt><span class="term"><code class="classname">_Sp_counted_base<Lp></code></span></dt><dd><p> +The base of the hierarchy is parameterized on the lock policy (see below.) +_Sp_counted_base doesn't depend on the type of pointer being managed, +it only maintains the reference counts and calls virtual functions when +the counts drop to zero. The managed object is destroyed when the last +strong reference is dropped, but the _Sp_counted_base itself must exist +until the last weak reference is dropped. + </p></dd><dt><span class="term"><code class="classname">_Sp_counted_base_impl<Ptr, Deleter, Lp></code></span></dt><dd><p> +Inherits from _Sp_counted_base and stores a pointer of type <span class="type">Ptr</span> +and a deleter of type <code class="code">Deleter</code>. <code class="code">_Sp_deleter</code> is +used when the user doesn't supply a custom deleter. Unlike Boost's, this +default deleter is not "checked" because GCC already issues a warning if +<code class="function">delete</code> is used with an incomplete type. +This is the only derived type used by <code class="classname">shared_ptr<Ptr></code> +and it is never used by <code class="classname">shared_ptr</code>, which uses one of +the following types, depending on how the shared_ptr is constructed. + </p></dd><dt><span class="term"><code class="classname">_Sp_counted_ptr<Ptr, Lp></code></span></dt><dd><p> +Inherits from _Sp_counted_base and stores a pointer of type <span class="type">Ptr</span>, +which is passed to <code class="function">delete</code> when the last reference is dropped. +This is the simplest form and is used when there is no custom deleter or +allocator. + </p></dd><dt><span class="term"><code class="classname">_Sp_counted_deleter<Ptr, Deleter, Alloc></code></span></dt><dd><p> +Inherits from _Sp_counted_ptr and adds support for custom deleter and +allocator. Empty Base Optimization is used for the allocator. This class +is used even when the user only provides a custom deleter, in which case +<code class="classname">allocator</code> is used as the allocator. + </p></dd><dt><span class="term"><code class="classname">_Sp_counted_ptr_inplace<Tp, Alloc, Lp></code></span></dt><dd><p> +Used by <code class="code">allocate_shared</code> and <code class="code">make_shared</code>. +Contains aligned storage to hold an object of type <span class="type">Tp</span>, +which is constructed in-place with placement <code class="function">new</code>. +Has a variadic template constructor allowing any number of arguments to +be forwarded to <span class="type">Tp</span>'s constructor. +Unlike the other <code class="classname">_Sp_counted_*</code> classes, this one is parameterized on the +type of object, not the type of pointer; this is purely a convenience +that simplifies the implementation slightly. + </p></dd></dl></div></div><div class="section" title="Thread Safety"><div class="titlepage"><div><div><h5 class="title"><a id="id474421"/>Thread Safety</h5></div></div></div><p> +C++0x-only features are: rvalue-ref/move support, allocator support, +aliasing constructor, make_shared & allocate_shared. Additionally, +the constructors taking <code class="classname">auto_ptr</code> parameters are +deprecated in C++0x mode. + </p><p> +The +<a class="link" href="http://boost.org/libs/smart_ptr/shared_ptr.htm#ThreadSafety">Thread +Safety</a> section of the Boost shared_ptr documentation says "shared_ptr +objects offer the same level of thread safety as built-in types." +The implementation must ensure that concurrent updates to separate shared_ptr +instances are correct even when those instances share a reference count e.g. +</p><pre class="programlisting"> +shared_ptr<A> a(new A); +shared_ptr<A> b(a); + +// Thread 1 // Thread 2 + a.reset(); b.reset(); +</pre><p> +The dynamically-allocated object must be destroyed by exactly one of the +threads. Weak references make things even more interesting. +The shared state used to implement shared_ptr must be transparent to the +user and invariants must be preserved at all times. +The key pieces of shared state are the strong and weak reference counts. +Updates to these need to be atomic and visible to all threads to ensure +correct cleanup of the managed resource (which is, after all, shared_ptr's +job!) +On multi-processor systems memory synchronisation may be needed so that +reference-count updates and the destruction of the managed resource are +race-free. +</p><p> +The function <code class="function">_Sp_counted_base::_M_add_ref_lock()</code>, called when +obtaining a shared_ptr from a weak_ptr, has to test if the managed +resource still exists and either increment the reference count or throw +<code class="classname">bad_weak_ptr</code>. +In a multi-threaded program there is a potential race condition if the last +reference is dropped (and the managed resource destroyed) between testing +the reference count and incrementing it, which could result in a shared_ptr +pointing to invalid memory. +</p><p> +The Boost shared_ptr (as used in GCC) features a clever lock-free +algorithm to avoid the race condition, but this relies on the +processor supporting an atomic <span class="emphasis"><em>Compare-And-Swap</em></span> +instruction. For other platforms there are fall-backs using mutex +locks. Boost (as of version 1.35) includes several different +implementations and the preprocessor selects one based on the +compiler, standard library, platform etc. For the version of +shared_ptr in libstdc++ the compiler and library are fixed, which +makes things much simpler: we have an atomic CAS or we don't, see Lock +Policy below for details. +</p></div><div class="section" title="Selecting Lock Policy"><div class="titlepage"><div><div><h5 class="title"><a id="id474491"/>Selecting Lock Policy</h5></div></div></div><p> + </p><p> +There is a single <code class="classname">_Sp_counted_base</code> class, +which is a template parameterized on the enum +<span class="type">__gnu_cxx::_Lock_policy</span>. The entire family of classes is +parameterized on the lock policy, right up to +<code class="classname">__shared_ptr</code>, <code class="classname">__weak_ptr</code> and +<code class="classname">__enable_shared_from_this</code>. The actual +<code class="classname">std::shared_ptr</code> class inherits from +<code class="classname">__shared_ptr</code> with the lock policy parameter +selected automatically based on the thread model and platform that +libstdc++ is configured for, so that the best available template +specialization will be used. This design is necessary because it would +not be conforming for <code class="classname">shared_ptr</code> to have an +extra template parameter, even if it had a default value. The +available policies are: + </p><div class="orderedlist"><ol class="orderedlist"><li class="listitem"><p> + <span class="type">_S_Atomic</span> + </p><p> +Selected when GCC supports a builtin atomic compare-and-swap operation +on the target processor (see <a class="link" href="http://gcc.gnu.org/onlinedocs/gcc/Atomic-Builtins.html">Atomic +Builtins</a>.) The reference counts are maintained using a lock-free +algorithm and GCC's atomic builtins, which provide the required memory +synchronisation. + </p></li><li class="listitem"><p> + <span class="type">_S_Mutex</span> + </p><p> +The _Sp_counted_base specialization for this policy contains a mutex, +which is locked in add_ref_lock(). This policy is used when GCC's atomic +builtins aren't available so explicit memory barriers are needed in places. + </p></li><li class="listitem"><p> + <span class="type">_S_Single</span> + </p><p> +This policy uses a non-reentrant add_ref_lock() with no locking. It is +used when libstdc++ is built without <code class="literal">--enable-threads</code>. + </p></li></ol></div><p> + For all three policies, reference count increments and + decrements are done via the functions in + <code class="filename">ext/atomicity.h</code>, which detect if the program + is multi-threaded. If only one thread of execution exists in + the program then less expensive non-atomic operations are used. + </p></div><div class="section" title="Dual C++0x and TR1 Implementation"><div class="titlepage"><div><div><h5 class="title"><a id="id474613"/>Dual C++0x and TR1 Implementation</h5></div></div></div><p> +The interface of <code class="classname">tr1::shared_ptr</code> was extended for C++0x +with support for rvalue-references and the other features from N2351. +The <code class="classname">_Sp_counted_base</code> base class is implemented in +<code class="filename">tr1/boost_sp_shared_count.h</code> and is common to the TR1 +and C++0x versions of <code class="classname">shared_ptr</code>. +</p><p> +The classes derived from <code class="classname">_Sp_counted_base</code> (see Class Hierarchy +above) and <code class="classname">__shared_count</code> are implemented separately for C++0x +and TR1, in <code class="filename">bits/shared_ptr.h</code> and +<code class="filename">tr1/shared_ptr.h</code> respectively. +</p><p> +The TR1 implementation is considered relatively stable, so is unlikely to +change unless bug fixes require it. If the code that is common to both +C++0x and TR1 modes needs to diverge further then it might be necessary to +duplicate <code class="classname">_Sp_counted_base</code> and only make changes to +the C++0x version. +</p></div><div class="section" title="Related functions and classes"><div class="titlepage"><div><div><h5 class="title"><a id="id474669"/>Related functions and classes</h5></div></div></div><div class="variablelist"><dl><dt><span class="term"><code class="code">dynamic_pointer_cast</code>, <code class="code">static_pointer_cast</code>, +<code class="code">const_pointer_cast</code></span></dt><dd><p> +As noted in N2351, these functions can be implemented non-intrusively using +the alias constructor. However the aliasing constructor is only available +in C++0x mode, so in TR1 mode these casts rely on three non-standard +constructors in shared_ptr and __shared_ptr. +In C++0x mode these constructors and the related tag types are not needed. + </p></dd><dt><span class="term"><code class="code">enable_shared_from_this</code></span></dt><dd><p> +The clever overload to detect a base class of type +<code class="code">enable_shared_from_this</code> comes straight from Boost. +There is an extra overload for <code class="code">__enable_shared_from_this</code> to +work smoothly with <code class="code">__shared_ptr<Tp, Lp></code> using any lock +policy. + </p></dd><dt><span class="term"><code class="code">make_shared</code>, <code class="code">allocate_shared</code></span></dt><dd><p> +<code class="code">make_shared</code> simply forwards to <code class="code">allocate_shared</code> +with <code class="code">std::allocator</code> as the allocator. +Although these functions can be implemented non-intrusively using the +alias constructor, if they have access to the implementation then it is +possible to save storage and reduce the number of heap allocations. The +newly constructed object and the _Sp_counted_* can be allocated in a single +block and the standard says implementations are "encouraged, but not required," +to do so. This implementation provides additional non-standard constructors +(selected with the type <code class="code">_Sp_make_shared_tag</code>) which create an +object of type <code class="code">_Sp_counted_ptr_inplace</code> to hold the new object. +The returned <code class="code">shared_ptr<A></code> needs to know the address of the +new <code class="code">A</code> object embedded in the <code class="code">_Sp_counted_ptr_inplace</code>, +but it has no way to access it. +This implementation uses a "covert channel" to return the address of the +embedded object when <code class="code">get_deleter<_Sp_make_shared_tag>()</code> +is called. Users should not try to use this. +As well as the extra constructors, this implementation also needs some +members of _Sp_counted_deleter to be protected where they could otherwise +be private. + </p></dd></dl></div></div></div><div class="section" title="Use"><div class="titlepage"><div><div><h4 class="title"><a id="shared_ptr.using"/>Use</h4></div></div></div><div class="section" title="Examples"><div class="titlepage"><div><div><h5 class="title"><a id="id474818"/>Examples</h5></div></div></div><p> + Examples of use can be found in the testsuite, under + <code class="filename">testsuite/tr1/2_general_utilities/shared_ptr</code>, + <code class="filename">testsuite/20_util/shared_ptr</code> + and + <code class="filename">testsuite/20_util/weak_ptr</code>. + </p></div><div class="section" title="Unresolved Issues"><div class="titlepage"><div><div><h5 class="title"><a id="id474848"/>Unresolved Issues</h5></div></div></div><p> + The <span class="emphasis"><em><code class="classname">shared_ptr</code> atomic access</em></span> + clause in the C++0x working draft is not implemented in GCC. + </p><p> + The <span class="type">_S_single</span> policy uses atomics when used in MT + code, because it uses the same dispatcher functions that check + <code class="function">__gthread_active_p()</code>. This could be + addressed by providing template specialisations for some members + of <code class="classname">_Sp_counted_base<_S_single></code>. + </p><p> + Unlike Boost, this implementation does not use separate classes + for the pointer+deleter and pointer+deleter+allocator cases in + C++0x mode, combining both into _Sp_counted_deleter and using + <code class="classname">allocator</code> when the user doesn't specify + an allocator. If it was found to be beneficial an additional + class could easily be added. With the current implementation, + the _Sp_counted_deleter and __shared_count constructors taking a + custom deleter but no allocator are technically redundant and + could be removed, changing callers to always specify an + allocator. If a separate pointer+deleter class was added the + __shared_count constructor would be needed, so it has been kept + for now. + </p><p> + The hack used to get the address of the managed object from + <code class="function">_Sp_counted_ptr_inplace::_M_get_deleter()</code> + is accessible to users. This could be prevented if + <code class="function">get_deleter<_Sp_make_shared_tag>()</code> + always returned NULL, since the hack only needs to work at a + lower level, not in the public API. This wouldn't be difficult, + but hasn't been done since there is no danger of accidental + misuse: users already know they are relying on unsupported + features if they refer to implementation details such as + _Sp_make_shared_tag. + </p><p> + tr1::_Sp_deleter could be a private member of tr1::__shared_count but it + would alter the ABI. + </p></div></div><div class="section" title="Acknowledgments"><div class="titlepage"><div><div><h4 class="title"><a id="shared_ptr.ack"/>Acknowledgments</h4></div></div></div><p> + The original authors of the Boost shared_ptr, which is really nice + code to work with, Peter Dimov in particular for his help and + invaluable advice on thread safety. Phillip Jordan and Paolo + Carlini for the lock policy implementation. + </p></div><div class="bibliography" title="Bibliography"><div class="titlepage"><div><div><h4 class="title"><a id="shared_ptr.biblio"/>Bibliography</h4></div></div></div><div class="biblioentry"><a id="id474942"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + Improving shared_ptr for C++0x, Revision 2 + </em>. </span><span class="subtitle"> + N2351 + . </span></p></div><div class="biblioentry"><a id="id474963"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + C++ Standard Library Active Issues List + </em>. </span><span class="subtitle"> + N2456 + . </span></p></div><div class="biblioentry"><a id="id474984"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + Working Draft, Standard for Programming Language C++ + </em>. </span><span class="subtitle"> + N2461 + . </span></p></div><div class="biblioentry"><a id="id475006"/><p><span class="biblioid">shared_ptr + . </span><span class="citetitle"><em class="citetitle"> + Boost C++ Libraries documentation, shared_ptr + </em>. </span><span class="subtitle"> + N2461 + . </span></p></div></div></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="pairs.html">Prev</a> </td><td align="center"><a accesskey="u" href="utilities.html">Up</a></td><td align="right"> <a accesskey="n" href="traits.html">Next</a></td></tr><tr><td align="left" valign="top">Pairs </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Traits</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/numerics.html b/libstdc++-v3/doc/html/manual/numerics.html new file mode 100644 index 000000000..ccf1f26e1 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/numerics.html @@ -0,0 +1,30 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Chapter 12. Numerics</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="bk01pt02.html" title="Part II. Standard Contents"/><link rel="prev" href="algorithms.html" title="Chapter 11. Algorithms"/><link rel="next" href="generalized_numeric_operations.html" title="Generalized Operations"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 12. + Numerics + +</th></tr><tr><td align="left"><a accesskey="p" href="algorithms.html">Prev</a> </td><th width="60%" align="center">Part II. + Standard Contents + </th><td align="right"> <a accesskey="n" href="generalized_numeric_operations.html">Next</a></td></tr></table><hr/></div><div class="chapter" title="Chapter 12. Numerics"><div class="titlepage"><div><div><h2 class="title"><a id="std.numerics"/>Chapter 12. + Numerics + <a id="id480125" class="indexterm"/> +</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="numerics.html#std.numerics.complex">Complex</a></span></dt><dd><dl><dt><span class="section"><a href="numerics.html#numerics.complex.processing">complex Processing</a></span></dt></dl></dd><dt><span class="section"><a href="generalized_numeric_operations.html">Generalized Operations</a></span></dt><dt><span class="section"><a href="numerics_and_c.html">Interacting with C</a></span></dt><dd><dl><dt><span class="section"><a href="numerics_and_c.html#numerics.c.array">Numerics vs. Arrays</a></span></dt><dt><span class="section"><a href="numerics_and_c.html#numerics.c.c99">C99</a></span></dt></dl></dd></dl></div><div class="section" title="Complex"><div class="titlepage"><div><div><h2 class="title"><a id="std.numerics.complex"/>Complex</h2></div></div></div><p> + </p><div class="section" title="complex Processing"><div class="titlepage"><div><div><h3 class="title"><a id="numerics.complex.processing"/>complex Processing</h3></div></div></div><p> + </p><p>Using <code class="code">complex<></code> becomes even more comple- er, sorry, + <span class="emphasis"><em>complicated</em></span>, with the not-quite-gratuitously-incompatible + addition of complex types to the C language. David Tribble has + compiled a list of C++98 and C99 conflict points; his description of + C's new type versus those of C++ and how to get them playing together + nicely is +<a class="link" href="http://david.tribble.com/text/cdiffs.htm#C99-complex">here</a>. + </p><p><code class="code">complex<></code> is intended to be instantiated with a + floating-point type. As long as you meet that and some other basic + requirements, then the resulting instantiation has all of the usual + math operators defined, as well as definitions of <code class="code">op<<</code> + and <code class="code">op>></code> that work with iostreams: <code class="code">op<<</code> + prints <code class="code">(u,v)</code> and <code class="code">op>></code> can read <code class="code">u</code>, + <code class="code">(u)</code>, and <code class="code">(u,v)</code>. + </p></div></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="algorithms.html">Prev</a> </td><td align="center"><a accesskey="u" href="bk01pt02.html">Up</a></td><td align="right"> <a accesskey="n" href="generalized_numeric_operations.html">Next</a></td></tr><tr><td align="left" valign="top">Chapter 11. + Algorithms + + </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Generalized Operations</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/numerics_and_c.html b/libstdc++-v3/doc/html/manual/numerics_and_c.html new file mode 100644 index 000000000..3a2fb499e --- /dev/null +++ b/libstdc++-v3/doc/html/manual/numerics_and_c.html @@ -0,0 +1,37 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Interacting with C</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="numerics.html" title="Chapter 12. Numerics"/><link rel="prev" href="generalized_numeric_operations.html" title="Generalized Operations"/><link rel="next" href="io.html" title="Chapter 13. Input and Output"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Interacting with C</th></tr><tr><td align="left"><a accesskey="p" href="generalized_numeric_operations.html">Prev</a> </td><th width="60%" align="center">Chapter 12. + Numerics + +</th><td align="right"> <a accesskey="n" href="io.html">Next</a></td></tr></table><hr/></div><div class="section" title="Interacting with C"><div class="titlepage"><div><div><h2 class="title"><a id="std.numerics.c"/>Interacting with C</h2></div></div></div><div class="section" title="Numerics vs. Arrays"><div class="titlepage"><div><div><h3 class="title"><a id="numerics.c.array"/>Numerics vs. Arrays</h3></div></div></div><p>One of the major reasons why FORTRAN can chew through numbers so well + is that it is defined to be free of pointer aliasing, an assumption + that C89 is not allowed to make, and neither is C++98. C99 adds a new + keyword, <code class="code">restrict</code>, to apply to individual pointers. The + C++ solution is contained in the library rather than the language + (although many vendors can be expected to add this to their compilers + as an extension). + </p><p>That library solution is a set of two classes, five template classes, + and "a whole bunch" of functions. The classes are required + to be free of pointer aliasing, so compilers can optimize the + daylights out of them the same way that they have been for FORTRAN. + They are collectively called <code class="code">valarray</code>, although strictly + speaking this is only one of the five template classes, and they are + designed to be familiar to people who have worked with the BLAS + libraries before. + </p></div><div class="section" title="C99"><div class="titlepage"><div><div><h3 class="title"><a id="numerics.c.c99"/>C99</h3></div></div></div><p>In addition to the other topics on this page, we'll note here some + of the C99 features that appear in libstdc++. + </p><p>The C99 features depend on the <code class="code">--enable-c99</code> configure flag. + This flag is already on by default, but it can be disabled by the + user. Also, the configuration machinery will disable it if the + necessary support for C99 (e.g., header files) cannot be found. + </p><p>As of GCC 3.0, C99 support includes classification functions + such as <code class="code">isnormal</code>, <code class="code">isgreater</code>, + <code class="code">isnan</code>, etc. + The functions used for 'long long' support such as <code class="code">strtoll</code> + are supported, as is the <code class="code">lldiv_t</code> typedef. Also supported + are the wide character functions using 'long long', like + <code class="code">wcstoll</code>. + </p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="generalized_numeric_operations.html">Prev</a> </td><td align="center"><a accesskey="u" href="numerics.html">Up</a></td><td align="right"> <a accesskey="n" href="io.html">Next</a></td></tr><tr><td align="left" valign="top">Generalized Operations </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Chapter 13. + Input and Output + +</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/pairs.html b/libstdc++-v3/doc/html/manual/pairs.html new file mode 100644 index 000000000..8c4dbb763 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/pairs.html @@ -0,0 +1,45 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Pairs</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="utilities.html" title="Chapter 6. Utilities"/><link rel="prev" href="utilities.html" title="Chapter 6. Utilities"/><link rel="next" href="memory.html" title="Memory"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Pairs</th></tr><tr><td align="left"><a accesskey="p" href="utilities.html">Prev</a> </td><th width="60%" align="center">Chapter 6. + Utilities + +</th><td align="right"> <a accesskey="n" href="memory.html">Next</a></td></tr></table><hr/></div><div class="section" title="Pairs"><div class="titlepage"><div><div><h2 class="title"><a id="std.util.pairs"/>Pairs</h2></div></div></div><p>The <code class="code">pair<T1,T2></code> is a simple and handy way to + carry around a pair of objects. One is of type T1, and another of + type T2; they may be the same type, but you don't get anything + extra if they are. The two members can be accessed directly, as + <code class="code">.first</code> and <code class="code">.second</code>. + </p><p>Construction is simple. The default ctor initializes each member + with its respective default ctor. The other simple ctor, + </p><pre class="programlisting"> + pair (const T1& x, const T2& y); + </pre><p>does what you think it does, <code class="code">first</code> getting <code class="code">x</code> + and <code class="code">second</code> getting <code class="code">y</code>. + </p><p>There is a copy constructor, but it requires that your compiler + handle member function templates: + </p><pre class="programlisting"> + template <class U, class V> pair (const pair<U,V>& p); + </pre><p>The compiler will convert as necessary from U to T1 and from + V to T2 in order to perform the respective initializations. + </p><p>The comparison operators are done for you. Equality + of two <code class="code">pair<T1,T2></code>s is defined as both <code class="code">first</code> + members comparing equal and both <code class="code">second</code> members comparing + equal; this simply delegates responsibility to the respective + <code class="code">operator==</code> functions (for types like MyClass) or builtin + comparisons (for types like int, char, etc). + </p><p> + The less-than operator is a bit odd the first time you see it. It + is defined as evaluating to: + </p><pre class="programlisting"> + x.first < y.first || + ( !(y.first < x.first) && x.second < y.second ) + </pre><p>The other operators are not defined using the <code class="code">rel_ops</code> + functions above, but their semantics are the same. + </p><p>Finally, there is a template function called <code class="function">make_pair</code> + that takes two references-to-const objects and returns an + instance of a pair instantiated on their respective types: + </p><pre class="programlisting"> + pair<int,MyClass> p = make_pair(4,myobject); + </pre></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="utilities.html">Prev</a> </td><td align="center"><a accesskey="u" href="utilities.html">Up</a></td><td align="right"> <a accesskey="n" href="memory.html">Next</a></td></tr><tr><td align="left" valign="top">Chapter 6. + Utilities + + </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Memory</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/parallel_mode.html b/libstdc++-v3/doc/html/manual/parallel_mode.html new file mode 100644 index 000000000..9c94e266f --- /dev/null +++ b/libstdc++-v3/doc/html/manual/parallel_mode.html @@ -0,0 +1,24 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Chapter 18. Parallel Mode</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" C++ , library , parallel "/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="extensions.html" title="Part III. Extensions"/><link rel="prev" href="bk01pt03ch17s04.html" title="Design"/><link rel="next" href="bk01pt03ch18s02.html" title="Semantics"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 18. Parallel Mode</th></tr><tr><td align="left"><a accesskey="p" href="bk01pt03ch17s04.html">Prev</a> </td><th width="60%" align="center">Part III. + Extensions + +</th><td align="right"> <a accesskey="n" href="bk01pt03ch18s02.html">Next</a></td></tr></table><hr/></div><div class="chapter" title="Chapter 18. Parallel Mode"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.parallel_mode"/>Chapter 18. Parallel Mode</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="parallel_mode.html#manual.ext.parallel_mode.intro">Intro</a></span></dt><dt><span class="section"><a href="bk01pt03ch18s02.html">Semantics</a></span></dt><dt><span class="section"><a href="bk01pt03ch18s03.html">Using</a></span></dt><dd><dl><dt><span class="section"><a href="bk01pt03ch18s03.html#parallel_mode.using.prereq_flags">Prerequisite Compiler Flags</a></span></dt><dt><span class="section"><a href="bk01pt03ch18s03.html#parallel_mode.using.parallel_mode">Using Parallel Mode</a></span></dt><dt><span class="section"><a href="bk01pt03ch18s03.html#parallel_mode.using.specific">Using Specific Parallel Components</a></span></dt></dl></dd><dt><span class="section"><a href="bk01pt03ch18s04.html">Design</a></span></dt><dd><dl><dt><span class="section"><a href="bk01pt03ch18s04.html#parallel_mode.design.intro">Interface Basics</a></span></dt><dt><span class="section"><a href="bk01pt03ch18s04.html#parallel_mode.design.tuning">Configuration and Tuning</a></span></dt><dt><span class="section"><a href="bk01pt03ch18s04.html#parallel_mode.design.impl">Implementation Namespaces</a></span></dt></dl></dd><dt><span class="section"><a href="bk01pt03ch18s05.html">Testing</a></span></dt><dt><span class="bibliography"><a href="parallel_mode.html#parallel_mode.biblio">Bibliography</a></span></dt></dl></div><p> The libstdc++ parallel mode is an experimental parallel +implementation of many algorithms the C++ Standard Library. +</p><p> +Several of the standard algorithms, for instance +<code class="function">std::sort</code>, are made parallel using OpenMP +annotations. These parallel mode constructs and can be invoked by +explicit source declaration or by compiling existing sources with a +specific compiler flag. +</p><div class="section" title="Intro"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.parallel_mode.intro"/>Intro</h2></div></div></div><p>The following library components in the include +<code class="filename">numeric</code> are included in the parallel mode:</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><code class="function">std::accumulate</code></p></li><li class="listitem"><p><code class="function">std::adjacent_difference</code></p></li><li class="listitem"><p><code class="function">std::inner_product</code></p></li><li class="listitem"><p><code class="function">std::partial_sum</code></p></li></ul></div><p>The following library components in the include +<code class="filename">algorithm</code> are included in the parallel mode:</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><code class="function">std::adjacent_find</code></p></li><li class="listitem"><p><code class="function">std::count</code></p></li><li class="listitem"><p><code class="function">std::count_if</code></p></li><li class="listitem"><p><code class="function">std::equal</code></p></li><li class="listitem"><p><code class="function">std::find</code></p></li><li class="listitem"><p><code class="function">std::find_if</code></p></li><li class="listitem"><p><code class="function">std::find_first_of</code></p></li><li class="listitem"><p><code class="function">std::for_each</code></p></li><li class="listitem"><p><code class="function">std::generate</code></p></li><li class="listitem"><p><code class="function">std::generate_n</code></p></li><li class="listitem"><p><code class="function">std::lexicographical_compare</code></p></li><li class="listitem"><p><code class="function">std::mismatch</code></p></li><li class="listitem"><p><code class="function">std::search</code></p></li><li class="listitem"><p><code class="function">std::search_n</code></p></li><li class="listitem"><p><code class="function">std::transform</code></p></li><li class="listitem"><p><code class="function">std::replace</code></p></li><li class="listitem"><p><code class="function">std::replace_if</code></p></li><li class="listitem"><p><code class="function">std::max_element</code></p></li><li class="listitem"><p><code class="function">std::merge</code></p></li><li class="listitem"><p><code class="function">std::min_element</code></p></li><li class="listitem"><p><code class="function">std::nth_element</code></p></li><li class="listitem"><p><code class="function">std::partial_sort</code></p></li><li class="listitem"><p><code class="function">std::partition</code></p></li><li class="listitem"><p><code class="function">std::random_shuffle</code></p></li><li class="listitem"><p><code class="function">std::set_union</code></p></li><li class="listitem"><p><code class="function">std::set_intersection</code></p></li><li class="listitem"><p><code class="function">std::set_symmetric_difference</code></p></li><li class="listitem"><p><code class="function">std::set_difference</code></p></li><li class="listitem"><p><code class="function">std::sort</code></p></li><li class="listitem"><p><code class="function">std::stable_sort</code></p></li><li class="listitem"><p><code class="function">std::unique_copy</code></p></li></ul></div></div><div class="bibliography" title="Bibliography"><div class="titlepage"><div><div><h2 class="title"><a id="parallel_mode.biblio"/>Bibliography</h2></div></div></div><div class="biblioentry"><a id="id486049"/><p><span class="citetitle"><em class="citetitle"> + Parallelization of Bulk Operations for STL Dictionaries + </em>. </span><span class="author"><span class="firstname">Johannes</span> <span class="surname">Singler</span>. </span><span class="author"><span class="firstname">Leonor</span> <span class="surname">Frias</span>. </span><span class="copyright">Copyright © 2007 . </span><span class="publisher"><span class="publishername"> + Workshop on Highly Parallel Processing on a Chip (HPPC) 2007. (LNCS) + . </span></span></p></div><div class="biblioentry"><a id="id486091"/><p><span class="citetitle"><em class="citetitle"> + The Multi-Core Standard Template Library + </em>. </span><span class="author"><span class="firstname">Johannes</span> <span class="surname">Singler</span>. </span><span class="author"><span class="firstname">Peter</span> <span class="surname">Sanders</span>. </span><span class="author"><span class="firstname">Felix</span> <span class="surname">Putze</span>. </span><span class="copyright">Copyright © 2007 . </span><span class="publisher"><span class="publishername"> + Euro-Par 2007: Parallel Processing. (LNCS 4641) + . </span></span></p></div></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="bk01pt03ch17s04.html">Prev</a> </td><td align="center"><a accesskey="u" href="extensions.html">Up</a></td><td align="right"> <a accesskey="n" href="bk01pt03ch18s02.html">Next</a></td></tr><tr><td align="left" valign="top">Design </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Semantics</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/profile_mode.html b/libstdc++-v3/doc/html/manual/profile_mode.html new file mode 100644 index 000000000..3c1b2d3b5 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/profile_mode.html @@ -0,0 +1,146 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Chapter 19. Profile Mode</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" C++ , library , profile "/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="extensions.html" title="Part III. Extensions"/><link rel="prev" href="bk01pt03ch18s05.html" title="Testing"/><link rel="next" href="bk01pt03ch19s02.html" title="Design"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 19. Profile Mode</th></tr><tr><td align="left"><a accesskey="p" href="bk01pt03ch18s05.html">Prev</a> </td><th width="60%" align="center">Part III. + Extensions + +</th><td align="right"> <a accesskey="n" href="bk01pt03ch19s02.html">Next</a></td></tr></table><hr/></div><div class="chapter" title="Chapter 19. Profile Mode"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.profile_mode"/>Chapter 19. Profile Mode</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="profile_mode.html#manual.ext.profile_mode.intro">Intro</a></span></dt><dd><dl><dt><span class="section"><a href="profile_mode.html#manual.ext.profile_mode.using">Using the Profile Mode</a></span></dt><dt><span class="section"><a href="profile_mode.html#manual.ext.profile_mode.tuning">Tuning the Profile Mode</a></span></dt></dl></dd><dt><span class="section"><a href="bk01pt03ch19s02.html">Design</a></span></dt><dd><dl><dt><span class="section"><a href="bk01pt03ch19s02.html#manual.ext.profile_mode.design.wrapper">Wrapper Model</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s02.html#manual.ext.profile_mode.design.instrumentation">Instrumentation</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s02.html#manual.ext.profile_mode.design.rtlib">Run Time Behavior</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s02.html#manual.ext.profile_mode.design.analysis">Analysis and Diagnostics</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s02.html#manual.ext.profile_mode.design.cost-model">Cost Model</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s02.html#manual.ext.profile_mode.design.reports">Reports</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s02.html#manual.ext.profile_mode.design.testing">Testing</a></span></dt></dl></dd><dt><span class="section"><a href="bk01pt03ch19s03.html">Extensions for Custom Containers</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s04.html">Empirical Cost Model</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s05.html">Implementation Issues</a></span></dt><dd><dl><dt><span class="section"><a href="bk01pt03ch19s05.html#manual.ext.profile_mode.implementation.stack">Stack Traces</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s05.html#manual.ext.profile_mode.implementation.symbols">Symbolization of Instruction Addresses</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s05.html#manual.ext.profile_mode.implementation.concurrency">Concurrency</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s05.html#manual.ext.profile_mode.implementation.stdlib-in-proflib">Using the Standard Library in the Instrumentation Implementation</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s05.html#manual.ext.profile_mode.implementation.malloc-hooks">Malloc Hooks</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s05.html#manual.ext.profile_mode.implementation.construction-destruction">Construction and Destruction of Global Objects</a></span></dt></dl></dd><dt><span class="section"><a href="bk01pt03ch19s06.html">Developer Information</a></span></dt><dd><dl><dt><span class="section"><a href="bk01pt03ch19s06.html#manual.ext.profile_mode.developer.bigpic">Big Picture</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s06.html#manual.ext.profile_mode.developer.howto">How To Add A Diagnostic</a></span></dt></dl></dd><dt><span class="section"><a href="bk01pt03ch19s07.html">Diagnostics</a></span></dt><dd><dl><dt><span class="section"><a href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.template">Diagnostic Template</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.containers">Containers</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.algorithms">Algorithms</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.locality">Data Locality</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.mthread">Multithreaded Data Access</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.statistics">Statistics</a></span></dt></dl></dd><dt><span class="bibliography"><a href="profile_mode.html#profile_mode.biblio">Bibliography</a></span></dt></dl></div><div class="section" title="Intro"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.profile_mode.intro"/>Intro</h2></div></div></div><p> + <span class="emphasis"><em>Goal: </em></span>Give performance improvement advice based on + recognition of suboptimal usage patterns of the standard library. + </p><p> + <span class="emphasis"><em>Method: </em></span>Wrap the standard library code. Insert + calls to an instrumentation library to record the internal state of + various components at interesting entry/exit points to/from the standard + library. Process trace, recognize suboptimal patterns, give advice. + For details, see + <a class="link" href="http://dx.doi.org/10.1109/CGO.2009.36">paper presented at + CGO 2009</a>. + </p><p> + <span class="emphasis"><em>Strengths: </em></span> +</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + Unintrusive solution. The application code does not require any + modification. + </p></li><li class="listitem"><p> The advice is call context sensitive, thus capable of + identifying precisely interesting dynamic performance behavior. + </p></li><li class="listitem"><p> + The overhead model is pay-per-view. When you turn off a diagnostic class + at compile time, its overhead disappears. + </p></li></ul></div><p> + </p><p> + <span class="emphasis"><em>Drawbacks: </em></span> +</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + You must recompile the application code with custom options. + </p></li><li class="listitem"><p>You must run the application on representative input. + The advice is input dependent. + </p></li><li class="listitem"><p> + The execution time will increase, in some cases by factors. + </p></li></ul></div><p> + </p><div class="section" title="Using the Profile Mode"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.using"/>Using the Profile Mode</h3></div></div></div><p> + This is the anticipated common workflow for program <code class="code">foo.cc</code>: +</p><pre class="programlisting"> +$ cat foo.cc +#include <vector> +int main() { + vector<int> v; + for (int k = 0; k < 1024; ++k) v.insert(v.begin(), k); +} + +$ g++ -D_GLIBCXX_PROFILE foo.cc +$ ./a.out +$ cat libstdcxx-profile.txt +vector-to-list: improvement = 5: call stack = 0x804842c ... + : advice = change std::vector to std::list +vector-size: improvement = 3: call stack = 0x804842c ... + : advice = change initial container size from 0 to 1024 +</pre><p> + </p><p> + Anatomy of a warning: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + Warning id. This is a short descriptive string for the class + that this warning belongs to. E.g., "vector-to-list". + </p></li><li class="listitem"><p> + Estimated improvement. This is an approximation of the benefit expected + from implementing the change suggested by the warning. It is given on + a log10 scale. Negative values mean that the alternative would actually + do worse than the current choice. + In the example above, 5 comes from the fact that the overhead of + inserting at the beginning of a vector vs. a list is around 1024 * 1024 / 2, + which is around 10e5. The improvement from setting the initial size to + 1024 is in the range of 10e3, since the overhead of dynamic resizing is + linear in this case. + </p></li><li class="listitem"><p> + Call stack. Currently, the addresses are printed without + symbol name or code location attribution. + Users are expected to postprocess the output using, for instance, addr2line. + </p></li><li class="listitem"><p> + The warning message. For some warnings, this is static text, e.g., + "change vector to list". For other warnings, such as the one above, + the message contains numeric advice, e.g., the suggested initial size + of the vector. + </p></li></ul></div><p> + </p><p>Three files are generated. <code class="code">libstdcxx-profile.txt</code> + contains human readable advice. <code class="code">libstdcxx-profile.raw</code> + contains implementation specific data about each diagnostic. + Their format is not documented. They are sufficient to generate + all the advice given in <code class="code">libstdcxx-profile.txt</code>. The advantage + of keeping this raw format is that traces from multiple executions can + be aggregated simply by concatenating the raw traces. We intend to + offer an external utility program that can issue advice from a trace. + <code class="code">libstdcxx-profile.conf.out</code> lists the actual diagnostic + parameters used. To alter parameters, edit this file and rename it to + <code class="code">libstdcxx-profile.conf</code>. + </p><p>Advice is given regardless whether the transformation is valid. + For instance, we advise changing a map to an unordered_map even if the + application semantics require that data be ordered. + We believe such warnings can help users understand the performance + behavior of their application better, which can lead to changes + at a higher abstraction level. + </p></div><div class="section" title="Tuning the Profile Mode"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.tuning"/>Tuning the Profile Mode</h3></div></div></div><p>Compile time switches and environment variables (see also file + profiler.h). Unless specified otherwise, they can be set at compile time + using -D_<name> or by setting variable <name> + in the environment where the program is run, before starting execution. + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + <code class="code">_GLIBCXX_PROFILE_NO_<diagnostic></code>: + disable specific diagnostics. + See section Diagnostics for possible values. + (Environment variables not supported.) + </p></li><li class="listitem"><p> + <code class="code">_GLIBCXX_PROFILE_TRACE_PATH_ROOT</code>: set an alternative root + path for the output files. + </p></li><li class="listitem"><p>_GLIBCXX_PROFILE_MAX_WARN_COUNT: set it to the maximum + number of warnings desired. The default value is 10.</p></li><li class="listitem"><p> + <code class="code">_GLIBCXX_PROFILE_MAX_STACK_DEPTH</code>: if set to 0, + the advice will + be collected and reported for the program as a whole, and not for each + call context. + This could also be used in continuous regression tests, where you + just need to know whether there is a regression or not. + The default value is 32. + </p></li><li class="listitem"><p> + <code class="code">_GLIBCXX_PROFILE_MEM_PER_DIAGNOSTIC</code>: + set a limit on how much memory to use for the accounting tables for each + diagnostic type. When this limit is reached, new events are ignored + until the memory usage decreases under the limit. Generally, this means + that newly created containers will not be instrumented until some + live containers are deleted. The default is 128 MB. + </p></li><li class="listitem"><p> + <code class="code">_GLIBCXX_PROFILE_NO_THREADS</code>: + Make the library not use threads. If thread local storage (TLS) is not + available, you will get a preprocessor error asking you to set + -D_GLIBCXX_PROFILE_NO_THREADS if your program is single-threaded. + Multithreaded execution without TLS is not supported. + (Environment variable not supported.) + </p></li><li class="listitem"><p> + <code class="code">_GLIBCXX_HAVE_EXECINFO_H</code>: + This name should be defined automatically at library configuration time. + If your library was configured without <code class="code">execinfo.h</code>, but + you have it in your include path, you can define it explicitly. Without + it, advice is collected for the program as a whole, and not for each + call context. + (Environment variable not supported.) + </p></li></ul></div><p> + </p></div></div><div class="bibliography" title="Bibliography"><div class="titlepage"><div><div><h2 class="title"><a id="profile_mode.biblio"/>Bibliography</h2></div></div></div><div class="biblioentry"><a id="id489940"/><p><span class="citetitle"><em class="citetitle"> + Perflint: A Context Sensitive Performance Advisor for C++ Programs + </em>. </span><span class="author"><span class="firstname">Lixia</span> <span class="surname">Liu</span>. </span><span class="author"><span class="firstname">Silvius</span> <span class="surname">Rus</span>. </span><span class="copyright">Copyright © 2009 . </span><span class="publisher"><span class="publishername"> + Proceedings of the 2009 International Symposium on Code Generation + and Optimization + . </span></span></p></div></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="bk01pt03ch18s05.html">Prev</a> </td><td align="center"><a accesskey="u" href="extensions.html">Up</a></td><td align="right"> <a accesskey="n" href="bk01pt03ch19s02.html">Next</a></td></tr><tr><td align="left" valign="top">Testing </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Design</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/setup.html b/libstdc++-v3/doc/html/manual/setup.html new file mode 100644 index 000000000..e0b5caee6 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/setup.html @@ -0,0 +1,102 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Chapter 2. Setup</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="intro.html" title="Part I. Introduction"/><link rel="prev" href="bugs.html" title="Bugs"/><link rel="next" href="configure.html" title="Configure"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 2. Setup</th></tr><tr><td align="left"><a accesskey="p" href="bugs.html">Prev</a> </td><th width="60%" align="center">Part I. + Introduction + +</th><td align="right"> <a accesskey="n" href="configure.html">Next</a></td></tr></table><hr/></div><div class="chapter" title="Chapter 2. Setup"><div class="titlepage"><div><div><h2 class="title"><a id="manual.intro.setup"/>Chapter 2. Setup</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="setup.html#manual.intro.setup.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="configure.html">Configure</a></span></dt><dt><span class="section"><a href="make.html">Make</a></span></dt></dl></div><p>To transform libstdc++ sources into installed include files + and properly built binaries useful for linking to other software is + a multi-step process. Steps include getting the sources, + configuring and building the sources, testing, and installation. + </p><p>The general outline of commands is something like: + </p><pre class="programlisting"> + <span class="emphasis"><em>get gcc sources</em></span> + <span class="emphasis"><em>extract into gccsrcdir</em></span> + mkdir <span class="emphasis"><em>gccbuilddir</em></span> + cd <span class="emphasis"><em>gccbuilddir</em></span> + <span class="emphasis"><em>gccsrcdir</em></span>/configure --prefix=<span class="emphasis"><em>destdir</em></span> --other-opts... + make + make check + make install + </pre><p> + Each step is described in more detail in the following sections. + </p><div class="section" title="Prerequisites"><div class="titlepage"><div><div><h2 class="title"><a id="manual.intro.setup.prereq"/>Prerequisites</h2></div></div></div><p> + Because libstdc++ is part of GCC, the primary source for + installation instructions is + <a class="link" href="http://gcc.gnu.org/install/">the GCC install page</a>. + In particular, list of prerequisite software needed to build the library + <a class="link" href="http://gcc.gnu.org/install/prerequisites.html"> + starts with those requirements.</a> The same pages also list + the tools you will need if you wish to modify the source. +</p><p> + Additional data is given here only where it applies to libstdc++. + </p><p>As of GCC 4.0.1 the minimum version of binutils required to build + libstdc++ is <code class="code">2.15.90.0.1.1</code>. You can get snapshots + (as well as releases) of binutils from + <a class="link" href="ftp://sources.redhat.com/pub/binutils/"> + ftp://sources.redhat.com/pub/binutils</a>. + Older releases of libstdc++ do not require such a recent version, + but to take full advantage of useful space-saving features and + bug-fixes you should use a recent binutils whenever possible. + The configure process will automatically detect and use these + features if the underlying support is present. + </p><p> + To generate the API documentation from the sources you will need + Doxygen, see <a class="link" href="documentation_hacking.html" title="Writing and Generating Documentation">Documentation + Hacking</a> in the appendix for full details. + </p><p> + Finally, a few system-specific requirements: + </p><div class="variablelist"><dl><dt><span class="term">linux</span></dt><dd><p> + If gcc 3.1.0 or later on is being used on linux, an attempt + will be made to use "C" library functionality necessary for + C++ named locale support. For gcc 4.6.0 and later, this + means that glibc 2.3 or later is required. + </p><p> + If the 'gnu' locale model is being used, the following + locales are used and tested in the libstdc++ testsuites. + The first column is the name of the locale, the second is + the character set it is expected to use. + </p><pre class="programlisting"> +de_DE ISO-8859-1 +de_DE@euro ISO-8859-15 +en_GB ISO-8859-1 +en_HK ISO-8859-1 +en_PH ISO-8859-1 +en_US ISO-8859-1 +en_US.ISO-8859-1 ISO-8859-1 +en_US.ISO-8859-15 ISO-8859-15 +en_US.UTF-8 UTF-8 +es_ES ISO-8859-1 +es_MX ISO-8859-1 +fr_FR ISO-8859-1 +fr_FR@euro ISO-8859-15 +is_IS UTF-8 +it_IT ISO-8859-1 +ja_JP.eucjp EUC-JP +ru_RU.ISO-8859-5 ISO-8859-5 +ru_RU.UTF-8 UTF-8 +se_NO.UTF-8 UTF-8 +ta_IN UTF-8 +zh_TW BIG5 +</pre><p>Failure to have installed the underlying "C" library + locale information for any of the above regions means that + the corresponding C++ named locale will not work: because of + this, the libstdc++ testsuite will skip named locale tests + which need missing information. If this isn't an issue, don't + worry about it. If a named locale is needed, the underlying + locale information must be installed. Note that rebuilding + libstdc++ after "C" locales are installed is not necessary. + </p><p> + To install support for locales, do only one of the following: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>install all locales</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>with RedHat Linux: + </p><p> <code class="code"> export LC_ALL=C </code> + </p><p> <code class="code"> rpm -e glibc-common --nodeps </code> + </p><p> + <code class="code"> rpm -i --define "_install_langs all" + glibc-common-2.2.5-34.i386.rpm + </code> + </p></li><li class="listitem"><p> + Instructions for other operating systems solicited. + </p></li></ul></div></li><li class="listitem"><p>install just the necessary locales</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>with Debian Linux:</p><p> Add the above list, as shown, to the file + <code class="code">/etc/locale.gen</code> </p><p> run <code class="code">/usr/sbin/locale-gen</code> </p></li><li class="listitem"><p>on most Unix-like operating systems:</p><p><code class="code"> localedef -i de_DE -f ISO-8859-1 de_DE </code></p><p>(repeat for each entry in the above list) </p></li><li class="listitem"><p> + Instructions for other operating systems solicited. + </p></li></ul></div></li></ul></div></dd></dl></div></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="bugs.html">Prev</a> </td><td align="center"><a accesskey="u" href="intro.html">Up</a></td><td align="right"> <a accesskey="n" href="configure.html">Next</a></td></tr><tr><td align="left" valign="top">Bugs </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Configure</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/source_code_style.html b/libstdc++-v3/doc/html/manual/source_code_style.html new file mode 100644 index 000000000..ff4b4db2f --- /dev/null +++ b/libstdc++-v3/doc/html/manual/source_code_style.html @@ -0,0 +1,620 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Coding Style</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="appendix_contributing.html" title="Appendix A. Contributing"/><link rel="prev" href="source_organization.html" title="Directory Layout and Source Conventions"/><link rel="next" href="source_design_notes.html" title="Design Notes"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Coding Style</th></tr><tr><td align="left"><a accesskey="p" href="source_organization.html">Prev</a> </td><th width="60%" align="center">Appendix A. + Contributing + +</th><td align="right"> <a accesskey="n" href="source_design_notes.html">Next</a></td></tr></table><hr/></div><div class="section" title="Coding Style"><div class="titlepage"><div><div><h2 class="title"><a id="contrib.coding_style"/>Coding Style</h2></div></div></div><p> + </p><div class="section" title="Bad Identifiers"><div class="titlepage"><div><div><h3 class="title"><a id="coding_style.bad_identifiers"/>Bad Identifiers</h3></div></div></div><p> + Identifiers that conflict and should be avoided. + </p><div class="literallayout"><p><br/> + This is the list of names <span class="quote">“<span class="quote">reserved to the<br/> + implementation</span>”</span> that have been claimed by certain<br/> + compilers and system headers of interest, and should not be used<br/> + in the library. It will grow, of course. We generally are<br/> + interested in names that are not all-caps, except for those like<br/> + "_T"<br/> +<br/> + For Solaris:<br/> + _B<br/> + _C<br/> + _L<br/> + _N<br/> + _P<br/> + _S<br/> + _U<br/> + _X<br/> + _E1<br/> + ..<br/> + _E24<br/> +<br/> + Irix adds:<br/> + _A<br/> + _G<br/> +<br/> + MS adds:<br/> + _T<br/> +<br/> + BSD adds:<br/> + __used<br/> + __unused<br/> + __inline<br/> + _Complex<br/> + __istype<br/> + __maskrune<br/> + __tolower<br/> + __toupper<br/> + __wchar_t<br/> + __wint_t<br/> + _res<br/> + _res_ext<br/> + __tg_*<br/> +<br/> + SPU adds:<br/> + __ea<br/> +<br/> + For GCC:<br/> +<br/> + [Note that this list is out of date. It applies to the old<br/> + name-mangling; in G++ 3.0 and higher a different name-mangling is<br/> + used. In addition, many of the bugs relating to G++ interpreting<br/> + these names as operators have been fixed.]<br/> +<br/> + The full set of __* identifiers (combined from gcc/cp/lex.c and<br/> + gcc/cplus-dem.c) that are either old or new, but are definitely<br/> + recognized by the demangler, is:<br/> +<br/> + __aa<br/> + __aad<br/> + __ad<br/> + __addr<br/> + __adv<br/> + __aer<br/> + __als<br/> + __alshift<br/> + __amd<br/> + __ami<br/> + __aml<br/> + __amu<br/> + __aor<br/> + __apl<br/> + __array<br/> + __ars<br/> + __arshift<br/> + __as<br/> + __bit_and<br/> + __bit_ior<br/> + __bit_not<br/> + __bit_xor<br/> + __call<br/> + __cl<br/> + __cm<br/> + __cn<br/> + __co<br/> + __component<br/> + __compound<br/> + __cond<br/> + __convert<br/> + __delete<br/> + __dl<br/> + __dv<br/> + __eq<br/> + __er<br/> + __ge<br/> + __gt<br/> + __indirect<br/> + __le<br/> + __ls<br/> + __lt<br/> + __max<br/> + __md<br/> + __method_call<br/> + __mi<br/> + __min<br/> + __minus<br/> + __ml<br/> + __mm<br/> + __mn<br/> + __mult<br/> + __mx<br/> + __ne<br/> + __negate<br/> + __new<br/> + __nop<br/> + __nt<br/> + __nw<br/> + __oo<br/> + __op<br/> + __or<br/> + __pl<br/> + __plus<br/> + __postdecrement<br/> + __postincrement<br/> + __pp<br/> + __pt<br/> + __rf<br/> + __rm<br/> + __rs<br/> + __sz<br/> + __trunc_div<br/> + __trunc_mod<br/> + __truth_andif<br/> + __truth_not<br/> + __truth_orif<br/> + __vc<br/> + __vd<br/> + __vn<br/> +<br/> + SGI badnames:<br/> + __builtin_alloca<br/> + __builtin_fsqrt<br/> + __builtin_sqrt<br/> + __builtin_fabs<br/> + __builtin_dabs<br/> + __builtin_cast_f2i<br/> + __builtin_cast_i2f<br/> + __builtin_cast_d2ll<br/> + __builtin_cast_ll2d<br/> + __builtin_copy_dhi2i<br/> + __builtin_copy_i2dhi<br/> + __builtin_copy_dlo2i<br/> + __builtin_copy_i2dlo<br/> + __add_and_fetch<br/> + __sub_and_fetch<br/> + __or_and_fetch<br/> + __xor_and_fetch<br/> + __and_and_fetch<br/> + __nand_and_fetch<br/> + __mpy_and_fetch<br/> + __min_and_fetch<br/> + __max_and_fetch<br/> + __fetch_and_add<br/> + __fetch_and_sub<br/> + __fetch_and_or<br/> + __fetch_and_xor<br/> + __fetch_and_and<br/> + __fetch_and_nand<br/> + __fetch_and_mpy<br/> + __fetch_and_min<br/> + __fetch_and_max<br/> + __lock_test_and_set<br/> + __lock_release<br/> + __lock_acquire<br/> + __compare_and_swap<br/> + __synchronize<br/> + __high_multiply<br/> + __unix<br/> + __sgi<br/> + __linux__<br/> + __i386__<br/> + __i486__<br/> + __cplusplus<br/> + __embedded_cplusplus<br/> + // long double conversion members mangled as __opr<br/> + // http://gcc.gnu.org/ml/libstdc++/1999-q4/msg00060.html<br/> + __opr<br/> + </p></div></div><div class="section" title="By Example"><div class="titlepage"><div><div><h3 class="title"><a id="coding_style.example"/>By Example</h3></div></div></div><div class="literallayout"><p><br/> + This library is written to appropriate C++ coding standards. As such,<br/> + it is intended to precede the recommendations of the GNU Coding<br/> + Standard, which can be referenced in full here:<br/> +<br/> + <a class="link" href="http://www.gnu.org/prep/standards/standards.html#Formatting">http://www.gnu.org/prep/standards/standards.html#Formatting</a><br/> +<br/> + The rest of this is also interesting reading, but skip the "Design<br/> + Advice" part.<br/> +<br/> + The GCC coding conventions are here, and are also useful:<br/> + <a class="link" href="http://gcc.gnu.org/codingconventions.html">http://gcc.gnu.org/codingconventions.html</a><br/> +<br/> + In addition, because it doesn't seem to be stated explicitly anywhere<br/> + else, there is an 80 column source limit.<br/> +<br/> + <code class="filename">ChangeLog</code> entries for member functions should use the<br/> + classname::member function name syntax as follows:<br/> +<br/> +<code class="code"><br/> +1999-04-15 Dennis Ritchie <dr@att.com><br/> +<br/> + * src/basic_file.cc (__basic_file::open): Fix thinko in<br/> + _G_HAVE_IO_FILE_OPEN bits.<br/> +</code><br/> +<br/> + Notable areas of divergence from what may be previous local practice<br/> + (particularly for GNU C) include:<br/> +<br/> + 01. Pointers and references<br/> + <code class="code"><br/> + char* p = "flop";<br/> + char& c = *p;<br/> + -NOT-<br/> + char *p = "flop"; // wrong<br/> + char &c = *p; // wrong<br/> + </code><br/> +<br/> + Reason: In C++, definitions are mixed with executable code. Here,<br/> + <code class="code">p</code> is being initialized, not <code class="code">*p</code>. This is near-universal<br/> + practice among C++ programmers; it is normal for C hackers<br/> + to switch spontaneously as they gain experience.<br/> +<br/> + 02. Operator names and parentheses<br/> + <code class="code"><br/> + operator==(type)<br/> + -NOT-<br/> + operator == (type) // wrong<br/> + </code><br/> +<br/> + Reason: The <code class="code">==</code> is part of the function name. Separating<br/> + it makes the declaration look like an expression.<br/> +<br/> + 03. Function names and parentheses<br/> + <code class="code"><br/> + void mangle()<br/> + -NOT-<br/> + void mangle () // wrong<br/> + </code><br/> +<br/> + Reason: no space before parentheses (except after a control-flow<br/> + keyword) is near-universal practice for C++. It identifies the<br/> + parentheses as the function-call operator or declarator, as<br/> + opposed to an expression or other overloaded use of parentheses.<br/> +<br/> + 04. Template function indentation<br/> + <code class="code"><br/> + template<typename T><br/> + void<br/> + template_function(args)<br/> + { }<br/> + -NOT-<br/> + template<class T><br/> + void template_function(args) {};<br/> + </code><br/> +<br/> + Reason: In class definitions, without indentation whitespace is<br/> + needed both above and below the declaration to distinguish<br/> + it visually from other members. (Also, re: "typename"<br/> + rather than "class".) <code class="code">T</code> often could be <code class="code">int</code>, which is<br/> + not a class. ("class", here, is an anachronism.)<br/> +<br/> + 05. Template class indentation<br/> + <code class="code"><br/> + template<typename _CharT, typename _Traits><br/> + class basic_ios : public ios_base<br/> + {<br/> + public:<br/> + // Types:<br/> + };<br/> + -NOT-<br/> + template<class _CharT, class _Traits><br/> + class basic_ios : public ios_base<br/> + {<br/> + public:<br/> + // Types:<br/> + };<br/> + -NOT-<br/> + template<class _CharT, class _Traits><br/> + class basic_ios : public ios_base<br/> + {<br/> + public:<br/> + // Types:<br/> + };<br/> + </code><br/> +<br/> + 06. Enumerators<br/> + <code class="code"><br/> + enum<br/> + {<br/> + space = _ISspace,<br/> + print = _ISprint,<br/> + cntrl = _IScntrl<br/> + };<br/> + -NOT-<br/> + enum { space = _ISspace, print = _ISprint, cntrl = _IScntrl };<br/> + </code><br/> +<br/> + 07. Member initialization lists<br/> + All one line, separate from class name.<br/> +<br/> + <code class="code"><br/> + gribble::gribble()<br/> + : _M_private_data(0), _M_more_stuff(0), _M_helper(0)<br/> + { }<br/> + -NOT-<br/> + gribble::gribble() : _M_private_data(0), _M_more_stuff(0), _M_helper(0)<br/> + { }<br/> + </code><br/> +<br/> + 08. Try/Catch blocks<br/> + <code class="code"><br/> + try<br/> + {<br/> + //<br/> + }<br/> + catch (...)<br/> + {<br/> + //<br/> + }<br/> + -NOT-<br/> + try {<br/> + //<br/> + } catch(...) {<br/> + //<br/> + }<br/> + </code><br/> +<br/> + 09. Member functions declarations and definitions<br/> + Keywords such as extern, static, export, explicit, inline, etc<br/> + go on the line above the function name. Thus<br/> +<br/> + <code class="code"><br/> + virtual int<br/> + foo()<br/> + -NOT-<br/> + virtual int foo()<br/> + </code><br/> +<br/> + Reason: GNU coding conventions dictate return types for functions<br/> + are on a separate line than the function name and parameter list<br/> + for definitions. For C++, where we have member functions that can<br/> + be either inline definitions or declarations, keeping to this<br/> + standard allows all member function names for a given class to be<br/> + aligned to the same margin, increasing readability.<br/> +<br/> +<br/> + 10. Invocation of member functions with "this->"<br/> + For non-uglified names, use <code class="code">this->name</code> to call the function.<br/> +<br/> + <code class="code"><br/> + this->sync()<br/> + -NOT-<br/> + sync()<br/> + </code><br/> +<br/> + Reason: Koenig lookup.<br/> +<br/> + 11. Namespaces<br/> + <code class="code"><br/> + namespace std<br/> + {<br/> + blah blah blah;<br/> + } // namespace std<br/> +<br/> + -NOT-<br/> +<br/> + namespace std {<br/> + blah blah blah;<br/> + } // namespace std<br/> + </code><br/> +<br/> + 12. Spacing under protected and private in class declarations:<br/> + space above, none below<br/> + i.e.<br/> +<br/> + <code class="code"><br/> + public:<br/> + int foo;<br/> +<br/> + -NOT-<br/> + public:<br/> +<br/> + int foo;<br/> + </code><br/> +<br/> + 13. Spacing WRT return statements.<br/> + no extra spacing before returns, no parenthesis<br/> + i.e.<br/> +<br/> + <code class="code"><br/> + }<br/> + return __ret;<br/> +<br/> + -NOT-<br/> + }<br/> +<br/> + return __ret;<br/> +<br/> + -NOT-<br/> +<br/> + }<br/> + return (__ret);<br/> + </code><br/> +<br/> +<br/> + 14. Location of global variables.<br/> + All global variables of class type, whether in the "user visible"<br/> + space (e.g., <code class="code">cin</code>) or the implementation namespace, must be defined<br/> + as a character array with the appropriate alignment and then later<br/> + re-initialized to the correct value.<br/> +<br/> + This is due to startup issues on certain platforms, such as AIX.<br/> + For more explanation and examples, see <code class="filename">src/globals.cc</code>. All such<br/> + variables should be contained in that file, for simplicity.<br/> +<br/> + 15. Exception abstractions<br/> + Use the exception abstractions found in <code class="filename">functexcept.h</code>, which allow<br/> + C++ programmers to use this library with <code class="literal">-fno-exceptions</code>. (Even if<br/> + that is rarely advisable, it's a necessary evil for backwards<br/> + compatibility.)<br/> +<br/> + 16. Exception error messages<br/> + All start with the name of the function where the exception is<br/> + thrown, and then (optional) descriptive text is added. Example:<br/> +<br/> + <code class="code"><br/> + __throw_logic_error(__N("basic_string::_S_construct NULL not valid"));<br/> + </code><br/> +<br/> + Reason: The verbose terminate handler prints out <code class="code">exception::what()</code>,<br/> + as well as the typeinfo for the thrown exception. As this is the<br/> + default terminate handler, by putting location info into the<br/> + exception string, a very useful error message is printed out for<br/> + uncaught exceptions. So useful, in fact, that non-programmers can<br/> + give useful error messages, and programmers can intelligently<br/> + speculate what went wrong without even using a debugger.<br/> +<br/> + 17. The doxygen style guide to comments is a separate document,<br/> + see index.<br/> +<br/> + The library currently has a mixture of GNU-C and modern C++ coding<br/> + styles. The GNU C usages will be combed out gradually.<br/> +<br/> + Name patterns:<br/> +<br/> + For nonstandard names appearing in Standard headers, we are constrained<br/> + to use names that begin with underscores. This is called "uglification".<br/> + The convention is:<br/> +<br/> + Local and argument names: <code class="literal">__[a-z].*</code><br/> +<br/> + Examples: <code class="code">__count __ix __s1</code><br/> +<br/> + Type names and template formal-argument names: <code class="literal">_[A-Z][^_].*</code><br/> +<br/> + Examples: <code class="code">_Helper _CharT _N</code><br/> +<br/> + Member data and function names: <code class="literal">_M_.*</code><br/> +<br/> + Examples: <code class="code">_M_num_elements _M_initialize ()</code><br/> +<br/> + Static data members, constants, and enumerations: <code class="literal">_S_.*</code><br/> +<br/> + Examples: <code class="code">_S_max_elements _S_default_value</code><br/> +<br/> + Don't use names in the same scope that differ only in the prefix,<br/> + e.g. _S_top and _M_top. See BADNAMES for a list of forbidden names.<br/> + (The most tempting of these seem to be and "_T" and "__sz".)<br/> +<br/> + Names must never have "__" internally; it would confuse name<br/> + unmanglers on some targets. Also, never use "__[0-9]", same reason.<br/> +<br/> + --------------------------<br/> +<br/> + [BY EXAMPLE]<br/> + <code class="code"><br/> +<br/> + #ifndef _HEADER_<br/> + #define _HEADER_ 1<br/> +<br/> + namespace std<br/> + {<br/> + class gribble<br/> + {<br/> + public:<br/> + gribble() throw();<br/> +<br/> + gribble(const gribble&);<br/> +<br/> + explicit<br/> + gribble(int __howmany);<br/> +<br/> + gribble&<br/> + operator=(const gribble&);<br/> +<br/> + virtual<br/> + ~gribble() throw ();<br/> +<br/> + // Start with a capital letter, end with a period.<br/> + inline void<br/> + public_member(const char* __arg) const;<br/> +<br/> + // In-class function definitions should be restricted to one-liners.<br/> + int<br/> + one_line() { return 0 }<br/> +<br/> + int<br/> + two_lines(const char* arg)<br/> + { return strchr(arg, 'a'); }<br/> +<br/> + inline int<br/> + three_lines(); // inline, but defined below.<br/> +<br/> + // Note indentation.<br/> + template<typename _Formal_argument><br/> + void<br/> + public_template() const throw();<br/> +<br/> + template<typename _Iterator><br/> + void<br/> + other_template();<br/> +<br/> + private:<br/> + class _Helper;<br/> +<br/> + int _M_private_data;<br/> + int _M_more_stuff;<br/> + _Helper* _M_helper;<br/> + int _M_private_function();<br/> +<br/> + enum _Enum<br/> + {<br/> + _S_one,<br/> + _S_two<br/> + };<br/> +<br/> + static void<br/> + _S_initialize_library();<br/> + };<br/> +<br/> + // More-or-less-standard language features described by lack, not presence.<br/> + # ifndef _G_NO_LONGLONG<br/> + extern long long _G_global_with_a_good_long_name; // avoid globals!<br/> + # endif<br/> +<br/> + // Avoid in-class inline definitions, define separately;<br/> + // likewise for member class definitions:<br/> + inline int<br/> + gribble::public_member() const<br/> + { int __local = 0; return __local; }<br/> +<br/> + class gribble::_Helper<br/> + {<br/> + int _M_stuff;<br/> +<br/> + friend class gribble;<br/> + };<br/> + }<br/> +<br/> + // Names beginning with "__": only for arguments and<br/> + // local variables; never use "__" in a type name, or<br/> + // within any name; never use "__[0-9]".<br/> +<br/> + #endif /* _HEADER_ */<br/> +<br/> +<br/> + namespace std<br/> + {<br/> + template<typename T> // notice: "typename", not "class", no space<br/> + long_return_value_type<with_many, args><br/> + function_name(char* pointer, // "char *pointer" is wrong.<br/> + char* argument,<br/> + const Reference& ref)<br/> + {<br/> + // int a_local; /* wrong; see below. */<br/> + if (test)<br/> + {<br/> + nested code<br/> + }<br/> +<br/> + int a_local = 0; // declare variable at first use.<br/> +<br/> + // char a, b, *p; /* wrong */<br/> + char a = 'a';<br/> + char b = a + 1;<br/> + char* c = "abc"; // each variable goes on its own line, always.<br/> +<br/> + // except maybe here...<br/> + for (unsigned i = 0, mask = 1; mask; ++i, mask <<= 1) {<br/> + // ...<br/> + }<br/> + }<br/> +<br/> + gribble::gribble()<br/> + : _M_private_data(0), _M_more_stuff(0), _M_helper(0)<br/> + { }<br/> +<br/> + int<br/> + gribble::three_lines()<br/> + {<br/> + // doesn't fit in one line.<br/> + }<br/> + } // namespace std<br/> + </code><br/> + </p></div></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="source_organization.html">Prev</a> </td><td align="center"><a accesskey="u" href="appendix_contributing.html">Up</a></td><td align="right"> <a accesskey="n" href="source_design_notes.html">Next</a></td></tr><tr><td align="left" valign="top">Directory Layout and Source Conventions </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Design Notes</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/source_design_notes.html b/libstdc++-v3/doc/html/manual/source_design_notes.html new file mode 100644 index 000000000..fab57a647 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/source_design_notes.html @@ -0,0 +1,863 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Design Notes</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="appendix_contributing.html" title="Appendix A. Contributing"/><link rel="prev" href="source_code_style.html" title="Coding Style"/><link rel="next" href="appendix_porting.html" title="Appendix B. Porting and Maintenance"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Design Notes</th></tr><tr><td align="left"><a accesskey="p" href="source_code_style.html">Prev</a> </td><th width="60%" align="center">Appendix A. + Contributing + +</th><td align="right"> <a accesskey="n" href="appendix_porting.html">Next</a></td></tr></table><hr/></div><div class="section" title="Design Notes"><div class="titlepage"><div><div><h2 class="title"><a id="contrib.design_notes"/>Design Notes</h2></div></div></div><p> + </p><div class="literallayout"><p><br/> +<br/> + The Library<br/> + -----------<br/> +<br/> + This paper is covers two major areas:<br/> +<br/> + - Features and policies not mentioned in the standard that<br/> + the quality of the library implementation depends on, including<br/> + extensions and "implementation-defined" features;<br/> +<br/> + - Plans for required but unimplemented library features and<br/> + optimizations to them.<br/> +<br/> + Overhead<br/> + --------<br/> +<br/> + The standard defines a large library, much larger than the standard<br/> + C library. A naive implementation would suffer substantial overhead<br/> + in compile time, executable size, and speed, rendering it unusable<br/> + in many (particularly embedded) applications. The alternative demands<br/> + care in construction, and some compiler support, but there is no<br/> + need for library subsets.<br/> +<br/> + What are the sources of this overhead? There are four main causes:<br/> +<br/> + - The library is specified almost entirely as templates, which<br/> + with current compilers must be included in-line, resulting in<br/> + very slow builds as tens or hundreds of thousands of lines<br/> + of function definitions are read for each user source file.<br/> + Indeed, the entire SGI STL, as well as the dos Reis valarray,<br/> + are provided purely as header files, largely for simplicity in<br/> + porting. Iostream/locale is (or will be) as large again.<br/> +<br/> + - The library is very flexible, specifying a multitude of hooks<br/> + where users can insert their own code in place of defaults.<br/> + When these hooks are not used, any time and code expended to<br/> + support that flexibility is wasted.<br/> +<br/> + - Templates are often described as causing to "code bloat". In<br/> + practice, this refers (when it refers to anything real) to several<br/> + independent processes. First, when a class template is manually<br/> + instantiated in its entirely, current compilers place the definitions<br/> + for all members in a single object file, so that a program linking<br/> + to one member gets definitions of all. Second, template functions<br/> + which do not actually depend on the template argument are, under<br/> + current compilers, generated anew for each instantiation, rather<br/> + than being shared with other instantiations. Third, some of the<br/> + flexibility mentioned above comes from virtual functions (both in<br/> + regular classes and template classes) which current linkers add<br/> + to the executable file even when they manifestly cannot be called.<br/> +<br/> + - The library is specified to use a language feature, exceptions,<br/> + which in the current gcc compiler ABI imposes a run time and<br/> + code space cost to handle the possibility of exceptions even when<br/> + they are not used. Under the new ABI (accessed with -fnew-abi),<br/> + there is a space overhead and a small reduction in code efficiency<br/> + resulting from lost optimization opportunities associated with<br/> + non-local branches associated with exceptions.<br/> +<br/> + What can be done to eliminate this overhead? A variety of coding<br/> + techniques, and compiler, linker and library improvements and<br/> + extensions may be used, as covered below. Most are not difficult,<br/> + and some are already implemented in varying degrees.<br/> +<br/> + Overhead: Compilation Time<br/> + --------------------------<br/> +<br/> + Providing "ready-instantiated" template code in object code archives<br/> + allows us to avoid generating and optimizing template instantiations<br/> + in each compilation unit which uses them. However, the number of such<br/> + instantiations that are useful to provide is limited, and anyway this<br/> + is not enough, by itself, to minimize compilation time. In particular,<br/> + it does not reduce time spent parsing conforming headers.<br/> +<br/> + Quicker header parsing will depend on library extensions and compiler<br/> + improvements. One approach is some variation on the techniques<br/> + previously marketed as "pre-compiled headers", now standardized as<br/> + support for the "export" keyword. "Exported" template definitions<br/> + can be placed (once) in a "repository" -- really just a library, but<br/> + of template definitions rather than object code -- to be drawn upon<br/> + at link time when an instantiation is needed, rather than placed in<br/> + header files to be parsed along with every compilation unit.<br/> +<br/> + Until "export" is implemented we can put some of the lengthy template<br/> + definitions in #if guards or alternative headers so that users can skip<br/> + over the full definitions when they need only the ready-instantiated<br/> + specializations.<br/> +<br/> + To be precise, this means that certain headers which define<br/> + templates which users normally use only for certain arguments<br/> + can be instrumented to avoid exposing the template definitions<br/> + to the compiler unless a macro is defined. For example, in<br/> + <string>, we might have:<br/> +<br/> + template <class _CharT, ... > class basic_string {<br/> + ... // member declarations<br/> + };<br/> + ... // operator declarations<br/> +<br/> + #ifdef _STRICT_ISO_<br/> + # if _G_NO_TEMPLATE_EXPORT<br/> + # include <bits/std_locale.h> // headers needed by definitions<br/> + # ...<br/> + # include <bits/string.tcc> // member and global template definitions.<br/> + # endif<br/> + #endif<br/> +<br/> + Users who compile without specifying a strict-ISO-conforming flag<br/> + would not see many of the template definitions they now see, and rely<br/> + instead on ready-instantiated specializations in the library. This<br/> + technique would be useful for the following substantial components:<br/> + string, locale/iostreams, valarray. It would *not* be useful or<br/> + usable with the following: containers, algorithms, iterators,<br/> + allocator. Since these constitute a large (though decreasing)<br/> + fraction of the library, the benefit the technique offers is<br/> + limited.<br/> +<br/> + The language specifies the semantics of the "export" keyword, but<br/> + the gcc compiler does not yet support it. When it does, problems<br/> + with large template inclusions can largely disappear, given some<br/> + minor library reorganization, along with the need for the apparatus<br/> + described above.<br/> +<br/> + Overhead: Flexibility Cost<br/> + --------------------------<br/> +<br/> + The library offers many places where users can specify operations<br/> + to be performed by the library in place of defaults. Sometimes<br/> + this seems to require that the library use a more-roundabout, and<br/> + possibly slower, way to accomplish the default requirements than<br/> + would be used otherwise.<br/> +<br/> + The primary protection against this overhead is thorough compiler<br/> + optimization, to crush out layers of inline function interfaces.<br/> + Kuck & Associates has demonstrated the practicality of this kind<br/> + of optimization.<br/> +<br/> + The second line of defense against this overhead is explicit<br/> + specialization. By defining helper function templates, and writing<br/> + specialized code for the default case, overhead can be eliminated<br/> + for that case without sacrificing flexibility. This takes full<br/> + advantage of any ability of the optimizer to crush out degenerate<br/> + code.<br/> +<br/> + The library specifies many virtual functions which current linkers<br/> + load even when they cannot be called. Some minor improvements to the<br/> + compiler and to ld would eliminate any such overhead by simply<br/> + omitting virtual functions that the complete program does not call.<br/> + A prototype of this work has already been done. For targets where<br/> + GNU ld is not used, a "pre-linker" could do the same job.<br/> +<br/> + The main areas in the standard interface where user flexibility<br/> + can result in overhead are:<br/> +<br/> + - Allocators: Containers are specified to use user-definable<br/> + allocator types and objects, making tuning for the container<br/> + characteristics tricky.<br/> +<br/> + - Locales: the standard specifies locale objects used to implement<br/> + iostream operations, involving many virtual functions which use<br/> + streambuf iterators.<br/> +<br/> + - Algorithms and containers: these may be instantiated on any type,<br/> + frequently duplicating code for identical operations.<br/> +<br/> + - Iostreams and strings: users are permitted to use these on their<br/> + own types, and specify the operations the stream must use on these<br/> + types.<br/> +<br/> + Note that these sources of overhead are _avoidable_. The techniques<br/> + to avoid them are covered below.<br/> +<br/> + Code Bloat<br/> + ----------<br/> +<br/> + In the SGI STL, and in some other headers, many of the templates<br/> + are defined "inline" -- either explicitly or by their placement<br/> + in class definitions -- which should not be inline. This is a<br/> + source of code bloat. Matt had remarked that he was relying on<br/> + the compiler to recognize what was too big to benefit from inlining,<br/> + and generate it out-of-line automatically. However, this also can<br/> + result in code bloat except where the linker can eliminate the extra<br/> + copies.<br/> +<br/> + Fixing these cases will require an audit of all inline functions<br/> + defined in the library to determine which merit inlining, and moving<br/> + the rest out of line. This is an issue mainly in chapters 23, 25, and<br/> + 27. Of course it can be done incrementally, and we should generally<br/> + accept patches that move large functions out of line and into ".tcc"<br/> + files, which can later be pulled into a repository. Compiler/linker<br/> + improvements to recognize very large inline functions and move them<br/> + out-of-line, but shared among compilation units, could make this<br/> + work unnecessary.<br/> +<br/> + Pre-instantiating template specializations currently produces large<br/> + amounts of dead code which bloats statically linked programs. The<br/> + current state of the static library, libstdc++.a, is intolerable on<br/> + this account, and will fuel further confused speculation about a need<br/> + for a library "subset". A compiler improvement that treats each<br/> + instantiated function as a separate object file, for linking purposes,<br/> + would be one solution to this problem. An alternative would be to<br/> + split up the manual instantiation files into dozens upon dozens of<br/> + little files, each compiled separately, but an abortive attempt at<br/> + this was done for <string> and, though it is far from complete, it<br/> + is already a nuisance. A better interim solution (just until we have<br/> + "export") is badly needed.<br/> +<br/> + When building a shared library, the current compiler/linker cannot<br/> + automatically generate the instantiations needed. This creates a<br/> + miserable situation; it means any time something is changed in the<br/> + library, before a shared library can be built someone must manually<br/> + copy the declarations of all templates that are needed by other parts<br/> + of the library to an "instantiation" file, and add it to the build<br/> + system to be compiled and linked to the library. This process is<br/> + readily automated, and should be automated as soon as possible.<br/> + Users building their own shared libraries experience identical<br/> + frustrations.<br/> +<br/> + Sharing common aspects of template definitions among instantiations<br/> + can radically reduce code bloat. The compiler could help a great<br/> + deal here by recognizing when a function depends on nothing about<br/> + a template parameter, or only on its size, and giving the resulting<br/> + function a link-name "equate" that allows it to be shared with other<br/> + instantiations. Implementation code could take advantage of the<br/> + capability by factoring out code that does not depend on the template<br/> + argument into separate functions to be merged by the compiler.<br/> +<br/> + Until such a compiler optimization is implemented, much can be done<br/> + manually (if tediously) in this direction. One such optimization is<br/> + to derive class templates from non-template classes, and move as much<br/> + implementation as possible into the base class. Another is to partial-<br/> + specialize certain common instantiations, such as vector<T*>, to share<br/> + code for instantiations on all types T. While these techniques work,<br/> + they are far from the complete solution that a compiler improvement<br/> + would afford.<br/> +<br/> + Overhead: Expensive Language Features<br/> + -------------------------------------<br/> +<br/> + The main "expensive" language feature used in the standard library<br/> + is exception support, which requires compiling in cleanup code with<br/> + static table data to locate it, and linking in library code to use<br/> + the table. For small embedded programs the amount of such library<br/> + code and table data is assumed by some to be excessive. Under the<br/> + "new" ABI this perception is generally exaggerated, although in some<br/> + cases it may actually be excessive.<br/> +<br/> + To implement a library which does not use exceptions directly is<br/> + not difficult given minor compiler support (to "turn off" exceptions<br/> + and ignore exception constructs), and results in no great library<br/> + maintenance difficulties. To be precise, given "-fno-exceptions",<br/> + the compiler should treat "try" blocks as ordinary blocks, and<br/> + "catch" blocks as dead code to ignore or eliminate. Compiler<br/> + support is not strictly necessary, except in the case of "function<br/> + try blocks"; otherwise the following macros almost suffice:<br/> +<br/> + #define throw(X)<br/> + #define try if (true)<br/> + #define catch(X) else if (false)<br/> +<br/> + However, there may be a need to use function try blocks in the<br/> + library implementation, and use of macros in this way can make<br/> + correct diagnostics impossible. Furthermore, use of this scheme<br/> + would require the library to call a function to re-throw exceptions<br/> + from a try block. Implementing the above semantics in the compiler<br/> + is preferable.<br/> +<br/> + Given the support above (however implemented) it only remains to<br/> + replace code that "throws" with a call to a well-documented "handler"<br/> + function in a separate compilation unit which may be replaced by<br/> + the user. The main source of exceptions that would be difficult<br/> + for users to avoid is memory allocation failures, but users can<br/> + define their own memory allocation primitives that never throw.<br/> + Otherwise, the complete list of such handlers, and which library<br/> + functions may call them, would be needed for users to be able to<br/> + implement the necessary substitutes. (Fortunately, they have the<br/> + source code.)<br/> +<br/> + Opportunities<br/> + -------------<br/> +<br/> + The template capabilities of C++ offer enormous opportunities for<br/> + optimizing common library operations, well beyond what would be<br/> + considered "eliminating overhead". In particular, many operations<br/> + done in Glibc with macros that depend on proprietary language<br/> + extensions can be implemented in pristine Standard C++. For example,<br/> + the chapter 25 algorithms, and even C library functions such as strchr,<br/> + can be specialized for the case of static arrays of known (small) size.<br/> +<br/> + Detailed optimization opportunities are identified below where<br/> + the component where they would appear is discussed. Of course new<br/> + opportunities will be identified during implementation.<br/> +<br/> + Unimplemented Required Library Features<br/> + ---------------------------------------<br/> +<br/> + The standard specifies hundreds of components, grouped broadly by<br/> + chapter. These are listed in excruciating detail in the CHECKLIST<br/> + file.<br/> +<br/> + 17 general<br/> + 18 support<br/> + 19 diagnostics<br/> + 20 utilities<br/> + 21 string<br/> + 22 locale<br/> + 23 containers<br/> + 24 iterators<br/> + 25 algorithms<br/> + 26 numerics<br/> + 27 iostreams<br/> + Annex D backward compatibility<br/> +<br/> + Anyone participating in implementation of the library should obtain<br/> + a copy of the standard, ISO 14882. People in the U.S. can obtain an<br/> + electronic copy for US$18 from ANSI's web site. Those from other<br/> + countries should visit http://www.iso.org/ to find out the location<br/> + of their country's representation in ISO, in order to know who can<br/> + sell them a copy.<br/> +<br/> + The emphasis in the following sections is on unimplemented features<br/> + and optimization opportunities.<br/> +<br/> + Chapter 17 General<br/> + -------------------<br/> +<br/> + Chapter 17 concerns overall library requirements.<br/> +<br/> + The standard doesn't mention threads. A multi-thread (MT) extension<br/> + primarily affects operators new and delete (18), allocator (20),<br/> + string (21), locale (22), and iostreams (27). The common underlying<br/> + support needed for this is discussed under chapter 20.<br/> +<br/> + The standard requirements on names from the C headers create a<br/> + lot of work, mostly done. Names in the C headers must be visible<br/> + in the std:: and sometimes the global namespace; the names in the<br/> + two scopes must refer to the same object. More stringent is that<br/> + Koenig lookup implies that any types specified as defined in std::<br/> + really are defined in std::. Names optionally implemented as<br/> + macros in C cannot be macros in C++. (An overview may be read at<br/> + <http://www.cantrip.org/cheaders.html>). The scripts "inclosure"<br/> + and "mkcshadow", and the directories shadow/ and cshadow/, are the<br/> + beginning of an effort to conform in this area.<br/> +<br/> + A correct conforming definition of C header names based on underlying<br/> + C library headers, and practical linking of conforming namespaced<br/> + customer code with third-party C libraries depends ultimately on<br/> + an ABI change, allowing namespaced C type names to be mangled into<br/> + type names as if they were global, somewhat as C function names in a<br/> + namespace, or C++ global variable names, are left unmangled. Perhaps<br/> + another "extern" mode, such as 'extern "C-global"' would be an<br/> + appropriate place for such type definitions. Such a type would<br/> + affect mangling as follows:<br/> +<br/> + namespace A {<br/> + struct X {};<br/> + extern "C-global" { // or maybe just 'extern "C"'<br/> + struct Y {};<br/> + };<br/> + }<br/> + void f(A::X*); // mangles to f__FPQ21A1X<br/> + void f(A::Y*); // mangles to f__FP1Y<br/> +<br/> + (It may be that this is really the appropriate semantics for regular<br/> + 'extern "C"', and 'extern "C-global"', as an extension, would not be<br/> + necessary.) This would allow functions declared in non-standard C headers<br/> + (and thus fixable by neither us nor users) to link properly with functions<br/> + declared using C types defined in properly-namespaced headers. The<br/> + problem this solves is that C headers (which C++ programmers do persist<br/> + in using) frequently forward-declare C struct tags without including<br/> + the header where the type is defined, as in<br/> +<br/> + struct tm;<br/> + void munge(tm*);<br/> +<br/> + Without some compiler accommodation, munge cannot be called by correct<br/> + C++ code using a pointer to a correctly-scoped tm* value.<br/> +<br/> + The current C headers use the preprocessor extension "#include_next",<br/> + which the compiler complains about when run "-pedantic".<br/> + (Incidentally, it appears that "-fpedantic" is currently ignored,<br/> + probably a bug.) The solution in the C compiler is to use<br/> + "-isystem" rather than "-I", but unfortunately in g++ this seems<br/> + also to wrap the whole header in an 'extern "C"' block, so it's<br/> + unusable for C++ headers. The correct solution appears to be to<br/> + allow the various special include-directory options, if not given<br/> + an argument, to affect subsequent include-directory options additively,<br/> + so that if one said<br/> +<br/> + -pedantic -iprefix $(prefix) \<br/> + -idirafter -ino-pedantic -ino-extern-c -iwithprefix -I g++-v3 \<br/> + -iwithprefix -I g++-v3/ext<br/> +<br/> + the compiler would search $(prefix)/g++-v3 and not report<br/> + pedantic warnings for files found there, but treat files in<br/> + $(prefix)/g++-v3/ext pedantically. (The undocumented semantics<br/> + of "-isystem" in g++ stink. Can they be rescinded? If not it<br/> + must be replaced with something more rationally behaved.)<br/> +<br/> + All the C headers need the treatment above; in the standard these<br/> + headers are mentioned in various chapters. Below, I have only<br/> + mentioned those that present interesting implementation issues.<br/> +<br/> + The components identified as "mostly complete", below, have not been<br/> + audited for conformance. In many cases where the library passes<br/> + conformance tests we have non-conforming extensions that must be<br/> + wrapped in #if guards for "pedantic" use, and in some cases renamed<br/> + in a conforming way for continued use in the implementation regardless<br/> + of conformance flags.<br/> +<br/> + The STL portion of the library still depends on a header<br/> + stl/bits/stl_config.h full of #ifdef clauses. This apparatus<br/> + should be replaced with autoconf/automake machinery.<br/> +<br/> + The SGI STL defines a type_traits<> template, specialized for<br/> + many types in their code including the built-in numeric and<br/> + pointer types and some library types, to direct optimizations of<br/> + standard functions. The SGI compiler has been extended to generate<br/> + specializations of this template automatically for user types,<br/> + so that use of STL templates on user types can take advantage of<br/> + these optimizations. Specializations for other, non-STL, types<br/> + would make more optimizations possible, but extending the gcc<br/> + compiler in the same way would be much better. Probably the next<br/> + round of standardization will ratify this, but probably with<br/> + changes, so it probably should be renamed to place it in the<br/> + implementation namespace.<br/> +<br/> + The SGI STL also defines a large number of extensions visible in<br/> + standard headers. (Other extensions that appear in separate headers<br/> + have been sequestered in subdirectories ext/ and backward/.) All<br/> + these extensions should be moved to other headers where possible,<br/> + and in any case wrapped in a namespace (not std!), and (where kept<br/> + in a standard header) girded about with macro guards. Some cannot be<br/> + moved out of standard headers because they are used to implement<br/> + standard features. The canonical method for accommodating these<br/> + is to use a protected name, aliased in macro guards to a user-space<br/> + name. Unfortunately C++ offers no satisfactory template typedef<br/> + mechanism, so very ad-hoc and unsatisfactory aliasing must be used<br/> + instead.<br/> +<br/> + Implementation of a template typedef mechanism should have the highest<br/> + priority among possible extensions, on the same level as implementation<br/> + of the template "export" feature.<br/> +<br/> + Chapter 18 Language support<br/> + ----------------------------<br/> +<br/> + Headers: <limits> <new> <typeinfo> <exception><br/> + C headers: <cstddef> <climits> <cfloat> <cstdarg> <csetjmp><br/> + <ctime> <csignal> <cstdlib> (also 21, 25, 26)<br/> +<br/> + This defines the built-in exceptions, rtti, numeric_limits<>,<br/> + operator new and delete. Much of this is provided by the<br/> + compiler in its static runtime library.<br/> +<br/> + Work to do includes defining numeric_limits<> specializations in<br/> + separate files for all target architectures. Values for integer types<br/> + except for bool and wchar_t are readily obtained from the C header<br/> + <limits.h>, but values for the remaining numeric types (bool, wchar_t,<br/> + float, double, long double) must be entered manually. This is<br/> + largely dog work except for those members whose values are not<br/> + easily deduced from available documentation. Also, this involves<br/> + some work in target configuration to identify the correct choice of<br/> + file to build against and to install.<br/> +<br/> + The definitions of the various operators new and delete must be<br/> + made thread-safe, which depends on a portable exclusion mechanism,<br/> + discussed under chapter 20. Of course there is always plenty of<br/> + room for improvements to the speed of operators new and delete.<br/> +<br/> + <cstdarg>, in Glibc, defines some macros that gcc does not allow to<br/> + be wrapped into an inline function. Probably this header will demand<br/> + attention whenever a new target is chosen. The functions atexit(),<br/> + exit(), and abort() in cstdlib have different semantics in C++, so<br/> + must be re-implemented for C++.<br/> +<br/> + Chapter 19 Diagnostics<br/> + -----------------------<br/> +<br/> + Headers: <stdexcept><br/> + C headers: <cassert> <cerrno><br/> +<br/> + This defines the standard exception objects, which are "mostly complete".<br/> + Cygnus has a version, and now SGI provides a slightly different one.<br/> + It makes little difference which we use.<br/> +<br/> + The C global name "errno", which C allows to be a variable or a macro,<br/> + is required in C++ to be a macro. For MT it must typically result in<br/> + a function call.<br/> +<br/> + Chapter 20 Utilities<br/> + ---------------------<br/> + Headers: <utility> <functional> <memory><br/> + C header: <ctime> (also in 18)<br/> +<br/> + SGI STL provides "mostly complete" versions of all the components<br/> + defined in this chapter. However, the auto_ptr<> implementation<br/> + is known to be wrong. Furthermore, the standard definition of it<br/> + is known to be unimplementable as written. A minor change to the<br/> + standard would fix it, and auto_ptr<> should be adjusted to match.<br/> +<br/> + Multi-threading affects the allocator implementation, and there must<br/> + be configuration/installation choices for different users' MT<br/> + requirements. Anyway, users will want to tune allocator options<br/> + to support different target conditions, MT or no.<br/> +<br/> + The primitives used for MT implementation should be exposed, as an<br/> + extension, for users' own work. We need cross-CPU "mutex" support,<br/> + multi-processor shared-memory atomic integer operations, and single-<br/> + processor uninterruptible integer operations, and all three configurable<br/> + to be stubbed out for non-MT use, or to use an appropriately-loaded<br/> + dynamic library for the actual runtime environment, or statically<br/> + compiled in for cases where the target architecture is known.<br/> +<br/> + Chapter 21 String<br/> + ------------------<br/> + Headers: <string><br/> + C headers: <cctype> <cwctype> <cstring> <cwchar> (also in 27)<br/> + <cstdlib> (also in 18, 25, 26)<br/> +<br/> + We have "mostly-complete" char_traits<> implementations. Many of the<br/> + char_traits<char> operations might be optimized further using existing<br/> + proprietary language extensions.<br/> +<br/> + We have a "mostly-complete" basic_string<> implementation. The work<br/> + to manually instantiate char and wchar_t specializations in object<br/> + files to improve link-time behavior is extremely unsatisfactory,<br/> + literally tripling library-build time with no commensurate improvement<br/> + in static program link sizes. It must be redone. (Similar work is<br/> + needed for some components in chapters 22 and 27.)<br/> +<br/> + Other work needed for strings is MT-safety, as discussed under the<br/> + chapter 20 heading.<br/> +<br/> + The standard C type mbstate_t from <cwchar> and used in char_traits<><br/> + must be different in C++ than in C, because in C++ the default constructor<br/> + value mbstate_t() must be the "base" or "ground" sequence state.<br/> + (According to the likely resolution of a recently raised Core issue,<br/> + this may become unnecessary. However, there are other reasons to<br/> + use a state type not as limited as whatever the C library provides.)<br/> + If we might want to provide conversions from (e.g.) internally-<br/> + represented EUC-wide to externally-represented Unicode, or vice-<br/> + versa, the mbstate_t we choose will need to be more accommodating<br/> + than what might be provided by an underlying C library.<br/> +<br/> + There remain some basic_string template-member functions which do<br/> + not overload properly with their non-template brethren. The infamous<br/> + hack akin to what was done in vector<> is needed, to conform to<br/> + 23.1.1 para 10. The CHECKLIST items for basic_string marked 'X',<br/> + or incomplete, are so marked for this reason.<br/> +<br/> + Replacing the string iterators, which currently are simple character<br/> + pointers, with class objects would greatly increase the safety of the<br/> + client interface, and also permit a "debug" mode in which range,<br/> + ownership, and validity are rigorously checked. The current use of<br/> + raw pointers as string iterators is evil. vector<> iterators need the<br/> + same treatment. Note that the current implementation freely mixes<br/> + pointers and iterators, and that must be fixed before safer iterators<br/> + can be introduced.<br/> +<br/> + Some of the functions in <cstring> are different from the C version.<br/> + generally overloaded on const and non-const argument pointers. For<br/> + example, in <cstring> strchr is overloaded. The functions isupper<br/> + etc. in <cctype> typically implemented as macros in C are functions<br/> + in C++, because they are overloaded with others of the same name<br/> + defined in <locale>.<br/> +<br/> + Many of the functions required in <cwctype> and <cwchar> cannot be<br/> + implemented using underlying C facilities on intended targets because<br/> + such facilities only partly exist.<br/> +<br/> + Chapter 22 Locale<br/> + ------------------<br/> + Headers: <locale><br/> + C headers: <clocale><br/> +<br/> + We have a "mostly complete" class locale, with the exception of<br/> + code for constructing, and handling the names of, named locales.<br/> + The ways that locales are named (particularly when categories<br/> + (e.g. LC_TIME, LC_COLLATE) are different) varies among all target<br/> + environments. This code must be written in various versions and<br/> + chosen by configuration parameters.<br/> +<br/> + Members of many of the facets defined in <locale> are stubs. Generally,<br/> + there are two sets of facets: the base class facets (which are supposed<br/> + to implement the "C" locale) and the "byname" facets, which are supposed<br/> + to read files to determine their behavior. The base ctype<>, collate<>,<br/> + and numpunct<> facets are "mostly complete", except that the table of<br/> + bitmask values used for "is" operations, and corresponding mask values,<br/> + are still defined in libio and just included/linked. (We will need to<br/> + implement these tables independently, soon, but should take advantage<br/> + of libio where possible.) The num_put<>::put members for integer types<br/> + are "mostly complete".<br/> +<br/> + A complete list of what has and has not been implemented may be<br/> + found in CHECKLIST. However, note that the current definition of<br/> + codecvt<wchar_t,char,mbstate_t> is wrong. It should simply write<br/> + out the raw bytes representing the wide characters, rather than<br/> + trying to convert each to a corresponding single "char" value.<br/> +<br/> + Some of the facets are more important than others. Specifically,<br/> + the members of ctype<>, numpunct<>, num_put<>, and num_get<> facets<br/> + are used by other library facilities defined in <string>, <istream>,<br/> + and <ostream>, and the codecvt<> facet is used by basic_filebuf<><br/> + in <fstream>, so a conforming iostream implementation depends on<br/> + these.<br/> +<br/> + The "long long" type eventually must be supported, but code mentioning<br/> + it should be wrapped in #if guards to allow pedantic-mode compiling.<br/> +<br/> + Performance of num_put<> and num_get<> depend critically on<br/> + caching computed values in ios_base objects, and on extensions<br/> + to the interface with streambufs.<br/> +<br/> + Specifically: retrieving a copy of the locale object, extracting<br/> + the needed facets, and gathering data from them, for each call to<br/> + (e.g.) operator<< would be prohibitively slow. To cache format<br/> + data for use by num_put<> and num_get<> we have a _Format_cache<><br/> + object stored in the ios_base::pword() array. This is constructed<br/> + and initialized lazily, and is organized purely for utility. It<br/> + is discarded when a new locale with different facets is imbued.<br/> +<br/> + Using only the public interfaces of the iterator arguments to the<br/> + facet functions would limit performance by forbidding "vector-style"<br/> + character operations. The streambuf iterator optimizations are<br/> + described under chapter 24, but facets can also bypass the streambuf<br/> + iterators via explicit specializations and operate directly on the<br/> + streambufs, and use extended interfaces to get direct access to the<br/> + streambuf internal buffer arrays. These extensions are mentioned<br/> + under chapter 27. These optimizations are particularly important<br/> + for input parsing.<br/> +<br/> + Unused virtual members of locale facets can be omitted, as mentioned<br/> + above, by a smart linker.<br/> +<br/> + Chapter 23 Containers<br/> + ----------------------<br/> + Headers: <deque> <list> <queue> <stack> <vector> <map> <set> <bitset><br/> +<br/> + All the components in chapter 23 are implemented in the SGI STL.<br/> + They are "mostly complete"; they include a large number of<br/> + nonconforming extensions which must be wrapped. Some of these<br/> + are used internally and must be renamed or duplicated.<br/> +<br/> + The SGI components are optimized for large-memory environments. For<br/> + embedded targets, different criteria might be more appropriate. Users<br/> + will want to be able to tune this behavior. We should provide<br/> + ways for users to compile the library with different memory usage<br/> + characteristics.<br/> +<br/> + A lot more work is needed on factoring out common code from different<br/> + specializations to reduce code size here and in chapter 25. The<br/> + easiest fix for this would be a compiler/ABI improvement that allows<br/> + the compiler to recognize when a specialization depends only on the<br/> + size (or other gross quality) of a template argument, and allow the<br/> + linker to share the code with similar specializations. In its<br/> + absence, many of the algorithms and containers can be partial-<br/> + specialized, at least for the case of pointers, but this only solves<br/> + a small part of the problem. Use of a type_traits-style template<br/> + allows a few more optimization opportunities, more if the compiler<br/> + can generate the specializations automatically.<br/> +<br/> + As an optimization, containers can specialize on the default allocator<br/> + and bypass it, or take advantage of details of its implementation<br/> + after it has been improved upon.<br/> +<br/> + Replacing the vector iterators, which currently are simple element<br/> + pointers, with class objects would greatly increase the safety of the<br/> + client interface, and also permit a "debug" mode in which range,<br/> + ownership, and validity are rigorously checked. The current use of<br/> + pointers for iterators is evil.<br/> +<br/> + As mentioned for chapter 24, the deque iterator is a good example of<br/> + an opportunity to implement a "staged" iterator that would benefit<br/> + from specializations of some algorithms.<br/> +<br/> + Chapter 24 Iterators<br/> + ---------------------<br/> + Headers: <iterator><br/> +<br/> + Standard iterators are "mostly complete", with the exception of<br/> + the stream iterators, which are not yet templatized on the<br/> + stream type. Also, the base class template iterator<> appears<br/> + to be wrong, so everything derived from it must also be wrong,<br/> + currently.<br/> +<br/> + The streambuf iterators (currently located in stl/bits/std_iterator.h,<br/> + but should be under bits/) can be rewritten to take advantage of<br/> + friendship with the streambuf implementation.<br/> +<br/> + Matt Austern has identified opportunities where certain iterator<br/> + types, particularly including streambuf iterators and deque<br/> + iterators, have a "two-stage" quality, such that an intermediate<br/> + limit can be checked much more quickly than the true limit on<br/> + range operations. If identified with a member of iterator_traits,<br/> + algorithms may be specialized for this case. Of course the<br/> + iterators that have this quality can be identified by specializing<br/> + a traits class.<br/> +<br/> + Many of the algorithms must be specialized for the streambuf<br/> + iterators, to take advantage of block-mode operations, in order<br/> + to allow iostream/locale operations' performance not to suffer.<br/> + It may be that they could be treated as staged iterators and<br/> + take advantage of those optimizations.<br/> +<br/> + Chapter 25 Algorithms<br/> + ----------------------<br/> + Headers: <algorithm><br/> + C headers: <cstdlib> (also in 18, 21, 26))<br/> +<br/> + The algorithms are "mostly complete". As mentioned above, they<br/> + are optimized for speed at the expense of code and data size.<br/> +<br/> + Specializations of many of the algorithms for non-STL types would<br/> + give performance improvements, but we must use great care not to<br/> + interfere with fragile template overloading semantics for the<br/> + standard interfaces. Conventionally the standard function template<br/> + interface is an inline which delegates to a non-standard function<br/> + which is then overloaded (this is already done in many places in<br/> + the library). Particularly appealing opportunities for the sake of<br/> + iostream performance are for copy and find applied to streambuf<br/> + iterators or (as noted elsewhere) for staged iterators, of which<br/> + the streambuf iterators are a good example.<br/> +<br/> + The bsearch and qsort functions cannot be overloaded properly as<br/> + required by the standard because gcc does not yet allow overloading<br/> + on the extern-"C"-ness of a function pointer.<br/> +<br/> + Chapter 26 Numerics<br/> + --------------------<br/> + Headers: <complex> <valarray> <numeric><br/> + C headers: <cmath>, <cstdlib> (also 18, 21, 25)<br/> +<br/> + Numeric components: Gabriel dos Reis's valarray, Drepper's complex,<br/> + and the few algorithms from the STL are "mostly done". Of course<br/> + optimization opportunities abound for the numerically literate. It<br/> + is not clear whether the valarray implementation really conforms<br/> + fully, in the assumptions it makes about aliasing (and lack thereof)<br/> + in its arguments.<br/> +<br/> + The C div() and ldiv() functions are interesting, because they are the<br/> + only case where a C library function returns a class object by value.<br/> + Since the C++ type div_t must be different from the underlying C type<br/> + (which is in the wrong namespace) the underlying functions div() and<br/> + ldiv() cannot be re-used efficiently. Fortunately they are trivial to<br/> + re-implement.<br/> +<br/> + Chapter 27 Iostreams<br/> + ---------------------<br/> + Headers: <iosfwd> <streambuf> <ios> <ostream> <istream> <iostream><br/> + <iomanip> <sstream> <fstream><br/> + C headers: <cstdio> <cwchar> (also in 21)<br/> +<br/> + Iostream is currently in a very incomplete state. <iosfwd>, <iomanip>,<br/> + ios_base, and basic_ios<> are "mostly complete". basic_streambuf<> and<br/> + basic_ostream<> are well along, but basic_istream<> has had little work<br/> + done. The standard stream objects, <sstream> and <fstream> have been<br/> + started; basic_filebuf<> "write" functions have been implemented just<br/> + enough to do "hello, world".<br/> +<br/> + Most of the istream and ostream operators << and >> (with the exception<br/> + of the op<<(integer) ones) have not been changed to use locale primitives,<br/> + sentry objects, or char_traits members.<br/> +<br/> + All these templates should be manually instantiated for char and<br/> + wchar_t in a way that links only used members into user programs.<br/> +<br/> + Streambuf is fertile ground for optimization extensions. An extended<br/> + interface giving iterator access to its internal buffer would be very<br/> + useful for other library components.<br/> +<br/> + Iostream operations (primarily operators << and >>) can take advantage<br/> + of the case where user code has not specified a locale, and bypass locale<br/> + operations entirely. The current implementation of op<</num_put<>::put,<br/> + for the integer types, demonstrates how they can cache encoding details<br/> + from the locale on each operation. There is lots more room for<br/> + optimization in this area.<br/> +<br/> + The definition of the relationship between the standard streams<br/> + cout et al. and stdout et al. requires something like a "stdiobuf".<br/> + The SGI solution of using double-indirection to actually use a<br/> + stdio FILE object for buffering is unsatisfactory, because it<br/> + interferes with peephole loop optimizations.<br/> +<br/> + The <sstream> header work has begun. stringbuf can benefit from<br/> + friendship with basic_string<> and basic_string<>::_Rep to use<br/> + those objects directly as buffers, and avoid allocating and making<br/> + copies.<br/> +<br/> + The basic_filebuf<> template is a complex beast. It is specified to<br/> + use the locale facet codecvt<> to translate characters between native<br/> + files and the locale character encoding. In general this involves<br/> + two buffers, one of "char" representing the file and another of<br/> + "char_type", for the stream, with codecvt<> translating. The process<br/> + is complicated by the variable-length nature of the translation, and<br/> + the need to seek to corresponding places in the two representations.<br/> + For the case of basic_filebuf<char>, when no translation is needed,<br/> + a single buffer suffices. A specialized filebuf can be used to reduce<br/> + code space overhead when no locale has been imbued. Matt Austern's<br/> + work at SGI will be useful, perhaps directly as a source of code, or<br/> + at least as an example to draw on.<br/> +<br/> + Filebuf, almost uniquely (cf. operator new), depends heavily on<br/> + underlying environmental facilities. In current releases iostream<br/> + depends fairly heavily on libio constant definitions, but it should<br/> + be made independent. It also depends on operating system primitives<br/> + for file operations. There is immense room for optimizations using<br/> + (e.g.) mmap for reading. The shadow/ directory wraps, besides the<br/> + standard C headers, the libio.h and unistd.h headers, for use mainly<br/> + by filebuf. These wrappings have not been completed, though there<br/> + is scaffolding in place.<br/> +<br/> + The encapsulation of certain C header <cstdio> names presents an<br/> + interesting problem. It is possible to define an inline std::fprintf()<br/> + implemented in terms of the 'extern "C"' vfprintf(), but there is no<br/> + standard vfscanf() to use to implement std::fscanf(). It appears that<br/> + vfscanf but be re-implemented in C++ for targets where no vfscanf<br/> + extension has been defined. This is interesting in that it seems<br/> + to be the only significant case in the C library where this kind of<br/> + rewriting is necessary. (Of course Glibc provides the vfscanf()<br/> + extension.) (The functions related to exit() must be rewritten<br/> + for other reasons.)<br/> +<br/> +<br/> + Annex D<br/> + -------<br/> + Headers: <strstream><br/> +<br/> + Annex D defines many non-library features, and many minor<br/> + modifications to various headers, and a complete header.<br/> + It is "mostly done", except that the libstdc++-2 <strstream><br/> + header has not been adopted into the library, or checked to<br/> + verify that it matches the draft in those details that were<br/> + clarified by the committee. Certainly it must at least be<br/> + moved into the std namespace.<br/> +<br/> + We still need to wrap all the deprecated features in #if guards<br/> + so that pedantic compile modes can detect their use.<br/> +<br/> + Nonstandard Extensions<br/> + ----------------------<br/> + Headers: <iostream.h> <strstream.h> <hash> <rbtree><br/> + <pthread_alloc> <stdiobuf> (etc.)<br/> +<br/> + User code has come to depend on a variety of nonstandard components<br/> + that we must not omit. Much of this code can be adopted from<br/> + libstdc++-v2 or from the SGI STL. This particularly includes<br/> + <iostream.h>, <strstream.h>, and various SGI extensions such<br/> + as <hash_map.h>. Many of these are already placed in the<br/> + subdirectories ext/ and backward/. (Note that it is better to<br/> + include them via "<backward/hash_map.h>" or "<ext/hash_map>" than<br/> + to search the subdirectory itself via a "-I" directive.<br/> + </p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="source_code_style.html">Prev</a> </td><td align="center"><a accesskey="u" href="appendix_contributing.html">Up</a></td><td align="right"> <a accesskey="n" href="appendix_porting.html">Next</a></td></tr><tr><td align="left" valign="top">Coding Style </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Appendix B. + Porting and Maintenance + +</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/source_organization.html b/libstdc++-v3/doc/html/manual/source_organization.html new file mode 100644 index 000000000..3e17c8b48 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/source_organization.html @@ -0,0 +1,97 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Directory Layout and Source Conventions</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="appendix_contributing.html" title="Appendix A. Contributing"/><link rel="prev" href="appendix_contributing.html" title="Appendix A. Contributing"/><link rel="next" href="source_code_style.html" title="Coding Style"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Directory Layout and Source Conventions</th></tr><tr><td align="left"><a accesskey="p" href="appendix_contributing.html">Prev</a> </td><th width="60%" align="center">Appendix A. + Contributing + +</th><td align="right"> <a accesskey="n" href="source_code_style.html">Next</a></td></tr></table><hr/></div><div class="section" title="Directory Layout and Source Conventions"><div class="titlepage"><div><div><h2 class="title"><a id="contrib.organization"/>Directory Layout and Source Conventions</h2></div></div></div><p> + The unpacked source directory of libstdc++ contains the files + needed to create the GNU C++ Library. + </p><div class="literallayout"><p><br/> +It has subdirectories:<br/> +<br/> + doc<br/> + Files in HTML and text format that document usage, quirks of the<br/> + implementation, and contributor checklists.<br/> +<br/> + include<br/> + All header files for the C++ library are within this directory,<br/> + modulo specific runtime-related files that are in the libsupc++<br/> + directory.<br/> +<br/> + include/std<br/> + Files meant to be found by #include <name> directives in<br/> + standard-conforming user programs.<br/> +<br/> + include/c<br/> + Headers intended to directly include standard C headers.<br/> + [NB: this can be enabled via --enable-cheaders=c]<br/> +<br/> + include/c_global<br/> + Headers intended to include standard C headers in<br/> + the global namespace, and put select names into the std::<br/> + namespace. [NB: this is the default, and is the same as<br/> + --enable-cheaders=c_global]<br/> +<br/> + include/c_std<br/> + Headers intended to include standard C headers<br/> + already in namespace std, and put select names into the std::<br/> + namespace. [NB: this is the same as --enable-cheaders=c_std]<br/> +<br/> + include/bits<br/> + Files included by standard headers and by other files in<br/> + the bits directory.<br/> +<br/> + include/backward<br/> + Headers provided for backward compatibility, such as <iostream.h>.<br/> + They are not used in this library.<br/> +<br/> + include/ext<br/> + Headers that define extensions to the standard library. No<br/> + standard header refers to any of them.<br/> +<br/> + scripts<br/> + Scripts that are used during the configure, build, make, or test<br/> + process.<br/> +<br/> + src<br/> + Files that are used in constructing the library, but are not<br/> + installed.<br/> +<br/> + testsuites/[backward, demangle, ext, performance, thread, 17_* to 27_*]<br/> + Test programs are here, and may be used to begin to exercise the<br/> + library. Support for "make check" and "make check-install" is<br/> + complete, and runs through all the subdirectories here when this<br/> + command is issued from the build directory. Please note that<br/> + "make check" requires DejaGNU 1.4 or later to be installed. Please<br/> + note that "make check-script" calls the script mkcheck, which<br/> + requires bash, and which may need the paths to bash adjusted to<br/> + work properly, as /bin/bash is assumed.<br/> +<br/> +Other subdirectories contain variant versions of certain files<br/> +that are meant to be copied or linked by the configure script.<br/> +Currently these are:<br/> +<br/> + config/abi<br/> + config/cpu<br/> + config/io<br/> + config/locale<br/> + config/os<br/> +<br/> +In addition, a subdirectory holds the convenience library libsupc++.<br/> +<br/> + libsupc++<br/> + Contains the runtime library for C++, including exception<br/> + handling and memory allocation and deallocation, RTTI, terminate<br/> + handlers, etc.<br/> +<br/> +Note that glibc also has a bits/ subdirectory. We will either<br/> +need to be careful not to collide with names in its bits/<br/> +directory; or rename bits to (e.g.) cppbits/.<br/> +<br/> +In files throughout the system, lines marked with an "XXX" indicate<br/> +a bug or incompletely-implemented feature. Lines marked "XXX MT"<br/> +indicate a place that may require attention for multi-thread safety.<br/> + </p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="appendix_contributing.html">Prev</a> </td><td align="center"><a accesskey="u" href="appendix_contributing.html">Up</a></td><td align="right"> <a accesskey="n" href="source_code_style.html">Next</a></td></tr><tr><td align="left" valign="top">Appendix A. + Contributing + + </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Coding Style</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/spine.html b/libstdc++-v3/doc/html/manual/spine.html new file mode 100644 index 000000000..36225c1c7 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/spine.html @@ -0,0 +1,67 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>The GNU C++ Library Manual</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="../spine.html" title="The GNU C++ Library"/><link rel="prev" href="../spine.html" title="The GNU C++ Library"/><link rel="next" href="intro.html" title="Part I. Introduction"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">The GNU C++ Library Manual</th></tr><tr><td align="left"><a accesskey="p" href="../spine.html">Prev</a> </td><th width="60%" align="center"> </th><td align="right"> <a accesskey="n" href="intro.html">Next</a></td></tr></table><hr/></div><div class="book" title="The GNU C++ Library Manual"><div class="titlepage"><div><div><h1 class="title"><a id="manual-index"/>The GNU C++ Library Manual</h1></div><div><p class="copyright">Copyright © 2009, 2010 + <a class="link" href="http://www.fsf.org">FSF</a> + </p></div><div><div class="legalnotice" title="Legal Notice"><a id="id399399"/><p> + <a class="link" href="license.html" title="License">License</a> + </p></div></div></div><hr/></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="part"><a href="intro.html">I. + Introduction + +</a></span></dt><dd><dl><dt><span class="chapter"><a href="status.html">1. Status</a></span></dt><dd><dl><dt><span class="section"><a href="status.html#manual.intro.status.iso">Implementation Status</a></span></dt><dd><dl><dt><span class="section"><a href="status.html#status.iso.1998">C++ 1998/2003</a></span></dt><dt><span class="section"><a href="status.html#status.iso.200x">C++ 200x</a></span></dt><dt><span class="section"><a href="status.html#status.iso.tr1">C++ TR1</a></span></dt><dt><span class="section"><a href="status.html#status.iso.tr24733">C++ TR 24733</a></span></dt></dl></dd><dt><span class="section"><a href="license.html">License</a></span></dt><dd><dl><dt><span class="section"><a href="license.html#manual.intro.status.license.gpl">The Code: GPL</a></span></dt><dt><span class="section"><a href="license.html#manual.intro.status.license.fdl">The Documentation: GPL, FDL</a></span></dt></dl></dd><dt><span class="section"><a href="bugs.html">Bugs</a></span></dt><dd><dl><dt><span class="section"><a href="bugs.html#manual.intro.status.bugs.impl">Implementation Bugs</a></span></dt><dt><span class="section"><a href="bugs.html#manual.intro.status.bugs.iso">Standard Bugs</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="setup.html">2. Setup</a></span></dt><dd><dl><dt><span class="section"><a href="setup.html#manual.intro.setup.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="configure.html">Configure</a></span></dt><dt><span class="section"><a href="make.html">Make</a></span></dt></dl></dd><dt><span class="chapter"><a href="using.html">3. Using</a></span></dt><dd><dl><dt><span class="section"><a href="using.html#manual.intro.using.flags">Command Options</a></span></dt><dt><span class="section"><a href="using_headers.html">Headers</a></span></dt><dd><dl><dt><span class="section"><a href="using_headers.html#manual.intro.using.headers.all">Header Files</a></span></dt><dt><span class="section"><a href="using_headers.html#manual.intro.using.headers.mixing">Mixing Headers</a></span></dt><dt><span class="section"><a href="using_headers.html#manual.intro.using.headers.cheaders">The C Headers and <code class="code">namespace std</code></a></span></dt><dt><span class="section"><a href="using_headers.html#manual.intro.using.headers.pre">Precompiled Headers</a></span></dt></dl></dd><dt><span class="section"><a href="using_macros.html">Macros</a></span></dt><dt><span class="section"><a href="using_namespaces.html">Namespaces</a></span></dt><dd><dl><dt><span class="section"><a href="using_namespaces.html#manual.intro.using.namespaces.all">Available Namespaces</a></span></dt><dt><span class="section"><a href="using_namespaces.html#manual.intro.using.namespaces.std">namespace std</a></span></dt><dt><span class="section"><a href="using_namespaces.html#manual.intro.using.namespaces.comp">Using Namespace Composition</a></span></dt></dl></dd><dt><span class="section"><a href="using_dynamic_or_shared.html">Linking</a></span></dt><dd><dl><dt><span class="section"><a href="using_dynamic_or_shared.html#manual.intro.using.linkage.freestanding">Almost Nothing</a></span></dt><dt><span class="section"><a href="using_dynamic_or_shared.html#manual.intro.using.linkage.dynamic">Finding Dynamic or Shared Libraries</a></span></dt></dl></dd><dt><span class="section"><a href="using_concurrency.html">Concurrency</a></span></dt><dd><dl><dt><span class="section"><a href="using_concurrency.html#manual.intro.using.concurrency.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="using_concurrency.html#manual.intro.using.concurrency.thread_safety">Thread Safety</a></span></dt><dt><span class="section"><a href="using_concurrency.html#manual.intro.using.concurrency.atomics">Atomics</a></span></dt><dt><span class="section"><a href="using_concurrency.html#manual.intro.using.concurrency.io">IO</a></span></dt><dt><span class="section"><a href="using_concurrency.html#manual.intro.using.concurrency.containers">Containers</a></span></dt></dl></dd><dt><span class="section"><a href="using_exceptions.html">Exceptions</a></span></dt><dd><dl><dt><span class="section"><a href="using_exceptions.html#intro.using.exception.safety">Exception Safety</a></span></dt><dt><span class="section"><a href="using_exceptions.html#intro.using.exception.propagating">Exception Neutrality</a></span></dt><dt><span class="section"><a href="using_exceptions.html#intro.using.exception.no">Doing without</a></span></dt><dt><span class="section"><a href="using_exceptions.html#intro.using.exception.compat">Compatibility</a></span></dt></dl></dd><dt><span class="section"><a href="debug.html">Debugging Support</a></span></dt><dd><dl><dt><span class="section"><a href="debug.html#debug.compiler">Using <span class="command"><strong>g++</strong></span></a></span></dt><dt><span class="section"><a href="debug.html#debug.req">Debug Versions of Library Binary Files</a></span></dt><dt><span class="section"><a href="debug.html#debug.memory">Memory Leak Hunting</a></span></dt><dt><span class="section"><a href="debug.html#debug.races">Data Race Hunting</a></span></dt><dt><span class="section"><a href="debug.html#debug.gdb">Using <span class="command"><strong>gdb</strong></span></a></span></dt><dt><span class="section"><a href="debug.html#debug.exceptions">Tracking uncaught exceptions</a></span></dt><dt><span class="section"><a href="debug.html#debug.debug_mode">Debug Mode</a></span></dt><dt><span class="section"><a href="debug.html#debug.compile_time_checks">Compile Time Checking</a></span></dt><dt><span class="section"><a href="debug.html#debug.profile_mode">Profile-based Performance Analysis</a></span></dt></dl></dd></dl></dd></dl></dd><dt><span class="part"><a href="bk01pt02.html">II. + Standard Contents + </a></span></dt><dd><dl><dt><span class="chapter"><a href="support.html">4. + Support + +</a></span></dt><dd><dl><dt><span class="section"><a href="support.html#std.support.types">Types</a></span></dt><dd><dl><dt><span class="section"><a href="support.html#std.support.types.fundamental">Fundamental Types</a></span></dt><dt><span class="section"><a href="support.html#std.support.types.numeric_limits">Numeric Properties</a></span></dt><dt><span class="section"><a href="support.html#std.support.types.null">NULL</a></span></dt></dl></dd><dt><span class="section"><a href="dynamic_memory.html">Dynamic Memory</a></span></dt><dt><span class="section"><a href="termination.html">Termination</a></span></dt><dd><dl><dt><span class="section"><a href="termination.html#support.termination.handlers">Termination Handlers</a></span></dt><dt><span class="section"><a href="termination.html#support.termination.verbose">Verbose Terminate Handler</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="diagnostics.html">5. + Diagnostics + +</a></span></dt><dd><dl><dt><span class="section"><a href="diagnostics.html#std.diagnostics.exceptions">Exceptions</a></span></dt><dd><dl><dt><span class="section"><a href="diagnostics.html#std.diagnostics.exceptions.api">API Reference</a></span></dt><dt><span class="section"><a href="diagnostics.html#std.diagnostics.exceptions.data">Adding Data to <code class="classname">exception</code></a></span></dt></dl></dd><dt><span class="section"><a href="bk01pt02ch05s02.html">Concept Checking</a></span></dt></dl></dd><dt><span class="chapter"><a href="utilities.html">6. + Utilities + +</a></span></dt><dd><dl><dt><span class="section"><a href="utilities.html#std.util.functors">Functors</a></span></dt><dt><span class="section"><a href="pairs.html">Pairs</a></span></dt><dt><span class="section"><a href="memory.html">Memory</a></span></dt><dd><dl><dt><span class="section"><a href="memory.html#std.util.memory.allocator">Allocators</a></span></dt><dt><span class="section"><a href="memory.html#std.util.memory.auto_ptr">auto_ptr</a></span></dt><dt><span class="section"><a href="memory.html#std.util.memory.shared_ptr">shared_ptr</a></span></dt></dl></dd><dt><span class="section"><a href="traits.html">Traits</a></span></dt></dl></dd><dt><span class="chapter"><a href="strings.html">7. + Strings + +</a></span></dt><dd><dl><dt><span class="section"><a href="strings.html#std.strings.string">String Classes</a></span></dt><dd><dl><dt><span class="section"><a href="strings.html#strings.string.simple">Simple Transformations</a></span></dt><dt><span class="section"><a href="strings.html#strings.string.case">Case Sensitivity</a></span></dt><dt><span class="section"><a href="strings.html#strings.string.character_types">Arbitrary Character Types</a></span></dt><dt><span class="section"><a href="strings.html#strings.string.token">Tokenizing</a></span></dt><dt><span class="section"><a href="strings.html#strings.string.shrink">Shrink to Fit</a></span></dt><dt><span class="section"><a href="strings.html#strings.string.Cstring">CString (MFC)</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="localization.html">8. + Localization + +</a></span></dt><dd><dl><dt><span class="section"><a href="localization.html#std.localization.locales">Locales</a></span></dt><dd><dl><dt><span class="section"><a href="localization.html#std.localization.locales.locale">locale</a></span></dt></dl></dd><dt><span class="section"><a href="facets.html">Facets</a></span></dt><dd><dl><dt><span class="section"><a href="facets.html#std.localization.facet.ctype">ctype</a></span></dt><dt><span class="section"><a href="facets.html#std.localization.facet.codecvt">codecvt</a></span></dt><dt><span class="section"><a href="facets.html#manual.localization.facet.messages">messages</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="containers.html">9. + Containers + +</a></span></dt><dd><dl><dt><span class="section"><a href="containers.html#std.containers.sequences">Sequences</a></span></dt><dd><dl><dt><span class="section"><a href="containers.html#containers.sequences.list">list</a></span></dt><dt><span class="section"><a href="containers.html#containers.sequences.vector">vector</a></span></dt></dl></dd><dt><span class="section"><a href="associative.html">Associative</a></span></dt><dd><dl><dt><span class="section"><a href="associative.html#containers.associative.insert_hints">Insertion Hints</a></span></dt><dt><span class="section"><a href="associative.html#containers.associative.bitset">bitset</a></span></dt></dl></dd><dt><span class="section"><a href="containers_and_c.html">Interacting with C</a></span></dt><dd><dl><dt><span class="section"><a href="containers_and_c.html#containers.c.vs_array">Containers vs. Arrays</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="iterators.html">10. + Iterators + +</a></span></dt><dd><dl><dt><span class="section"><a href="iterators.html#std.iterators.predefined">Predefined</a></span></dt><dd><dl><dt><span class="section"><a href="iterators.html#iterators.predefined.vs_pointers">Iterators vs. Pointers</a></span></dt><dt><span class="section"><a href="iterators.html#iterators.predefined.end">One Past the End</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="algorithms.html">11. + Algorithms + +</a></span></dt><dd><dl><dt><span class="section"><a href="algorithms.html#std.algorithms.mutating">Mutating</a></span></dt><dd><dl><dt><span class="section"><a href="algorithms.html#algorithms.mutating.swap"><code class="function">swap</code></a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="numerics.html">12. + Numerics + +</a></span></dt><dd><dl><dt><span class="section"><a href="numerics.html#std.numerics.complex">Complex</a></span></dt><dd><dl><dt><span class="section"><a href="numerics.html#numerics.complex.processing">complex Processing</a></span></dt></dl></dd><dt><span class="section"><a href="generalized_numeric_operations.html">Generalized Operations</a></span></dt><dt><span class="section"><a href="numerics_and_c.html">Interacting with C</a></span></dt><dd><dl><dt><span class="section"><a href="numerics_and_c.html#numerics.c.array">Numerics vs. Arrays</a></span></dt><dt><span class="section"><a href="numerics_and_c.html#numerics.c.c99">C99</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="io.html">13. + Input and Output + +</a></span></dt><dd><dl><dt><span class="section"><a href="io.html#std.io.objects">Iostream Objects</a></span></dt><dt><span class="section"><a href="streambufs.html">Stream Buffers</a></span></dt><dd><dl><dt><span class="section"><a href="streambufs.html#io.streambuf.derived">Derived streambuf Classes</a></span></dt><dt><span class="section"><a href="streambufs.html#io.streambuf.buffering">Buffering</a></span></dt></dl></dd><dt><span class="section"><a href="stringstreams.html">Memory Based Streams</a></span></dt><dd><dl><dt><span class="section"><a href="stringstreams.html#std.io.memstreams.compat">Compatibility With strstream</a></span></dt></dl></dd><dt><span class="section"><a href="fstreams.html">File Based Streams</a></span></dt><dd><dl><dt><span class="section"><a href="fstreams.html#std.io.filestreams.copying_a_file">Copying a File</a></span></dt><dt><span class="section"><a href="fstreams.html#std.io.filestreams.binary">Binary Input and Output</a></span></dt></dl></dd><dt><span class="section"><a href="io_and_c.html">Interacting with C</a></span></dt><dd><dl><dt><span class="section"><a href="io_and_c.html#std.io.c.FILE">Using FILE* and file descriptors</a></span></dt><dt><span class="section"><a href="io_and_c.html#std.io.c.sync">Performance</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="atomics.html">14. + Atomics + +</a></span></dt><dd><dl><dt><span class="section"><a href="atomics.html#std.atomics.api">API Reference</a></span></dt></dl></dd><dt><span class="chapter"><a href="concurrency.html">15. + Concurrency + +</a></span></dt><dd><dl><dt><span class="section"><a href="concurrency.html#std.concurrency.api">API Reference</a></span></dt></dl></dd></dl></dd><dt><span class="part"><a href="extensions.html">III. + Extensions + +</a></span></dt><dd><dl><dt><span class="preface"><a href="bk01pt03pr01.html"/></span></dt><dt><span class="chapter"><a href="ext_compile_checks.html">16. Compile Time Checks</a></span></dt><dt><span class="chapter"><a href="debug_mode.html">17. Debug Mode</a></span></dt><dd><dl><dt><span class="section"><a href="debug_mode.html#manual.ext.debug_mode.intro">Intro</a></span></dt><dt><span class="section"><a href="bk01pt03ch17s02.html">Semantics</a></span></dt><dt><span class="section"><a href="bk01pt03ch17s03.html">Using</a></span></dt><dd><dl><dt><span class="section"><a href="bk01pt03ch17s03.html#debug_mode.using.mode">Using the Debug Mode</a></span></dt><dt><span class="section"><a href="bk01pt03ch17s03.html#debug_mode.using.specific">Using a Specific Debug Container</a></span></dt></dl></dd><dt><span class="section"><a href="bk01pt03ch17s04.html">Design</a></span></dt><dd><dl><dt><span class="section"><a href="bk01pt03ch17s04.html#debug_mode.design.goals">Goals</a></span></dt><dt><span class="section"><a href="bk01pt03ch17s04.html#debug_mode.design.methods">Methods</a></span></dt><dt><span class="section"><a href="bk01pt03ch17s04.html#debug_mode.design.other">Other Implementations</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="parallel_mode.html">18. Parallel Mode</a></span></dt><dd><dl><dt><span class="section"><a href="parallel_mode.html#manual.ext.parallel_mode.intro">Intro</a></span></dt><dt><span class="section"><a href="bk01pt03ch18s02.html">Semantics</a></span></dt><dt><span class="section"><a href="bk01pt03ch18s03.html">Using</a></span></dt><dd><dl><dt><span class="section"><a href="bk01pt03ch18s03.html#parallel_mode.using.prereq_flags">Prerequisite Compiler Flags</a></span></dt><dt><span class="section"><a href="bk01pt03ch18s03.html#parallel_mode.using.parallel_mode">Using Parallel Mode</a></span></dt><dt><span class="section"><a href="bk01pt03ch18s03.html#parallel_mode.using.specific">Using Specific Parallel Components</a></span></dt></dl></dd><dt><span class="section"><a href="bk01pt03ch18s04.html">Design</a></span></dt><dd><dl><dt><span class="section"><a href="bk01pt03ch18s04.html#parallel_mode.design.intro">Interface Basics</a></span></dt><dt><span class="section"><a href="bk01pt03ch18s04.html#parallel_mode.design.tuning">Configuration and Tuning</a></span></dt><dt><span class="section"><a href="bk01pt03ch18s04.html#parallel_mode.design.impl">Implementation Namespaces</a></span></dt></dl></dd><dt><span class="section"><a href="bk01pt03ch18s05.html">Testing</a></span></dt><dt><span class="bibliography"><a href="parallel_mode.html#parallel_mode.biblio">Bibliography</a></span></dt></dl></dd><dt><span class="chapter"><a href="profile_mode.html">19. Profile Mode</a></span></dt><dd><dl><dt><span class="section"><a href="profile_mode.html#manual.ext.profile_mode.intro">Intro</a></span></dt><dd><dl><dt><span class="section"><a href="profile_mode.html#manual.ext.profile_mode.using">Using the Profile Mode</a></span></dt><dt><span class="section"><a href="profile_mode.html#manual.ext.profile_mode.tuning">Tuning the Profile Mode</a></span></dt></dl></dd><dt><span class="section"><a href="bk01pt03ch19s02.html">Design</a></span></dt><dd><dl><dt><span class="section"><a href="bk01pt03ch19s02.html#manual.ext.profile_mode.design.wrapper">Wrapper Model</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s02.html#manual.ext.profile_mode.design.instrumentation">Instrumentation</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s02.html#manual.ext.profile_mode.design.rtlib">Run Time Behavior</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s02.html#manual.ext.profile_mode.design.analysis">Analysis and Diagnostics</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s02.html#manual.ext.profile_mode.design.cost-model">Cost Model</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s02.html#manual.ext.profile_mode.design.reports">Reports</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s02.html#manual.ext.profile_mode.design.testing">Testing</a></span></dt></dl></dd><dt><span class="section"><a href="bk01pt03ch19s03.html">Extensions for Custom Containers</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s04.html">Empirical Cost Model</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s05.html">Implementation Issues</a></span></dt><dd><dl><dt><span class="section"><a href="bk01pt03ch19s05.html#manual.ext.profile_mode.implementation.stack">Stack Traces</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s05.html#manual.ext.profile_mode.implementation.symbols">Symbolization of Instruction Addresses</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s05.html#manual.ext.profile_mode.implementation.concurrency">Concurrency</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s05.html#manual.ext.profile_mode.implementation.stdlib-in-proflib">Using the Standard Library in the Instrumentation Implementation</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s05.html#manual.ext.profile_mode.implementation.malloc-hooks">Malloc Hooks</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s05.html#manual.ext.profile_mode.implementation.construction-destruction">Construction and Destruction of Global Objects</a></span></dt></dl></dd><dt><span class="section"><a href="bk01pt03ch19s06.html">Developer Information</a></span></dt><dd><dl><dt><span class="section"><a href="bk01pt03ch19s06.html#manual.ext.profile_mode.developer.bigpic">Big Picture</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s06.html#manual.ext.profile_mode.developer.howto">How To Add A Diagnostic</a></span></dt></dl></dd><dt><span class="section"><a href="bk01pt03ch19s07.html">Diagnostics</a></span></dt><dd><dl><dt><span class="section"><a href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.template">Diagnostic Template</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.containers">Containers</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.algorithms">Algorithms</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.locality">Data Locality</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.mthread">Multithreaded Data Access</a></span></dt><dt><span class="section"><a href="bk01pt03ch19s07.html#manual.ext.profile_mode.analysis.statistics">Statistics</a></span></dt></dl></dd><dt><span class="bibliography"><a href="profile_mode.html#profile_mode.biblio">Bibliography</a></span></dt></dl></dd><dt><span class="chapter"><a href="ext_allocators.html">20. Allocators</a></span></dt><dd><dl><dt><span class="section"><a href="ext_allocators.html#manual.ext.allocator.mt">mt_allocator</a></span></dt><dd><dl><dt><span class="section"><a href="ext_allocators.html#allocator.mt.intro">Intro</a></span></dt><dt><span class="section"><a href="ext_allocators.html#allocator.mt.design_issues">Design Issues</a></span></dt><dt><span class="section"><a href="ext_allocators.html#allocator.mt.impl">Implementation</a></span></dt><dt><span class="section"><a href="ext_allocators.html#allocator.mt.example_single">Single Thread Example</a></span></dt><dt><span class="section"><a href="ext_allocators.html#allocator.mt.example_multi">Multiple Thread Example</a></span></dt></dl></dd><dt><span class="section"><a href="bitmap_allocator.html">bitmap_allocator</a></span></dt><dd><dl><dt><span class="section"><a href="bitmap_allocator.html#allocator.bitmap.design">Design</a></span></dt><dt><span class="section"><a href="bitmap_allocator.html#allocator.bitmap.impl">Implementation</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="ext_containers.html">21. Containers</a></span></dt><dd><dl><dt><span class="section"><a href="ext_containers.html#manual.ext.containers.pbds">Policy Based Data Structures</a></span></dt><dt><span class="section"><a href="bk01pt03ch21s02.html">HP/SGI</a></span></dt><dt><span class="section"><a href="bk01pt03ch21s03.html">Deprecated HP/SGI</a></span></dt></dl></dd><dt><span class="chapter"><a href="ext_utilities.html">22. Utilities</a></span></dt><dt><span class="chapter"><a href="ext_algorithms.html">23. Algorithms</a></span></dt><dt><span class="chapter"><a href="ext_numerics.html">24. Numerics</a></span></dt><dt><span class="chapter"><a href="ext_iterators.html">25. Iterators</a></span></dt><dt><span class="chapter"><a href="ext_io.html">26. Input and Output</a></span></dt><dd><dl><dt><span class="section"><a href="ext_io.html#manual.ext.io.filebuf_derived">Derived filebufs</a></span></dt></dl></dd><dt><span class="chapter"><a href="ext_demangling.html">27. Demangling</a></span></dt><dt><span class="chapter"><a href="ext_concurrency.html">28. Concurrency</a></span></dt><dd><dl><dt><span class="section"><a href="ext_concurrency.html#manual.ext.concurrency.design">Design</a></span></dt><dd><dl><dt><span class="section"><a href="ext_concurrency.html#manual.ext.concurrency.design.threads">Interface to Locks and Mutexes</a></span></dt><dt><span class="section"><a href="ext_concurrency.html#manual.ext.concurrency.design.atomics">Interface to Atomic Functions</a></span></dt></dl></dd><dt><span class="section"><a href="bk01pt03ch28s02.html">Implementation</a></span></dt><dd><dl><dt><span class="section"><a href="bk01pt03ch28s02.html#manual.ext.concurrency.impl.atomic_fallbacks">Using Builtin Atomic Functions</a></span></dt><dt><span class="section"><a href="bk01pt03ch28s02.html#manual.ext.concurrency.impl.thread">Thread Abstraction</a></span></dt></dl></dd><dt><span class="section"><a href="bk01pt03ch28s03.html">Use</a></span></dt></dl></dd></dl></dd><dt><span class="part"><a href="bk01pt04.html">IV. + Appendices +</a></span></dt><dd><dl><dt><span class="appendix"><a href="appendix_contributing.html">A. + Contributing + +</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_contributing.html#contrib.list">Contributor Checklist</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_contributing.html#list.reading">Reading</a></span></dt><dt><span class="section"><a href="appendix_contributing.html#list.copyright">Assignment</a></span></dt><dt><span class="section"><a href="appendix_contributing.html#list.getting">Getting Sources</a></span></dt><dt><span class="section"><a href="appendix_contributing.html#list.patches">Submitting Patches</a></span></dt></dl></dd><dt><span class="section"><a href="source_organization.html">Directory Layout and Source Conventions</a></span></dt><dt><span class="section"><a href="source_code_style.html">Coding Style</a></span></dt><dd><dl><dt><span class="section"><a href="source_code_style.html#coding_style.bad_identifiers">Bad Identifiers</a></span></dt><dt><span class="section"><a href="source_code_style.html#coding_style.example">By Example</a></span></dt></dl></dd><dt><span class="section"><a href="source_design_notes.html">Design Notes</a></span></dt></dl></dd><dt><span class="appendix"><a href="appendix_porting.html">B. + Porting and Maintenance + +</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#appendix.porting.build_hacking">Configure and Build Hacking</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#build_hacking.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.map">Overview: What Comes from Where</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.scripts">Storing Information in non-AC files (like configure.host)</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.conventions">Coding and Commenting Conventions</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.acinclude">The acinclude.m4 layout</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.enable"><code class="constant">GLIBCXX_ENABLE</code>, the <code class="literal">--enable</code> maker</a></span></dt></dl></dd><dt><span class="section"><a href="documentation_hacking.html">Writing and Generating Documentation</a></span></dt><dd><dl><dt><span class="section"><a href="documentation_hacking.html#doc.intro">Introduction</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doc.generation">Generating Documentation</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doc.doxygen">Doxygen</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doc.docbook">Docbook</a></span></dt></dl></dd><dt><span class="section"><a href="internals.html">Porting to New Hardware or Operating Systems</a></span></dt><dd><dl><dt><span class="section"><a href="internals.html#internals.os">Operating System</a></span></dt><dt><span class="section"><a href="internals.html#internals.cpu">CPU</a></span></dt><dt><span class="section"><a href="internals.html#internals.char_types">Character Types</a></span></dt><dt><span class="section"><a href="internals.html#internals.thread_safety">Thread Safety</a></span></dt><dt><span class="section"><a href="internals.html#internals.numeric_limits">Numeric Limits</a></span></dt><dt><span class="section"><a href="internals.html#internals.libtool">Libtool</a></span></dt></dl></dd><dt><span class="section"><a href="test.html">Test</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.organization">Organization</a></span></dt><dt><span class="section"><a href="test.html#test.run">Running the Testsuite</a></span></dt><dt><span class="section"><a href="test.html#test.new_tests">Writing a new test case</a></span></dt><dt><span class="section"><a href="test.html#test.harness">Test Harness and Utilities</a></span></dt><dt><span class="section"><a href="test.html#test.special">Special Topics</a></span></dt></dl></dd><dt><span class="section"><a href="abi.html">ABI Policy and Guidelines</a></span></dt><dd><dl><dt><span class="section"><a href="abi.html#abi.cxx_interface">The C++ Interface</a></span></dt><dt><span class="section"><a href="abi.html#abi.versioning">Versioning</a></span></dt><dt><span class="section"><a href="abi.html#abi.changes_allowed">Allowed Changes</a></span></dt><dt><span class="section"><a href="abi.html#abi.changes_no">Prohibited Changes</a></span></dt><dt><span class="section"><a href="abi.html#abi.impl">Implementation</a></span></dt><dt><span class="section"><a href="abi.html#abi.testing">Testing</a></span></dt><dt><span class="section"><a href="abi.html#abi.issues">Outstanding Issues</a></span></dt></dl></dd><dt><span class="section"><a href="api.html">API Evolution and Deprecation History</a></span></dt><dd><dl><dt><span class="section"><a href="api.html#api.rel_300"><code class="constant">3.0</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_310"><code class="constant">3.1</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_320"><code class="constant">3.2</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_330"><code class="constant">3.3</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_340"><code class="constant">3.4</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_400"><code class="constant">4.0</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_410"><code class="constant">4.1</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_420"><code class="constant">4.2</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_430"><code class="constant">4.3</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_440"><code class="constant">4.4</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_450"><code class="constant">4.5</code></a></span></dt></dl></dd><dt><span class="section"><a href="backwards.html">Backwards Compatibility</a></span></dt><dd><dl><dt><span class="section"><a href="backwards.html#backwards.first">First</a></span></dt><dt><span class="section"><a href="backwards.html#backwards.second">Second</a></span></dt><dt><span class="section"><a href="backwards.html#backwards.third">Third</a></span></dt></dl></dd></dl></dd><dt><span class="appendix"><a href="appendix_free.html">C. + Free Software Needs Free Documentation + +</a></span></dt><dt><span class="appendix"><a href="appendix_gpl.html">D. + <acronym class="acronym">GNU</acronym> General Public License version 3 + </a></span></dt><dt><span class="appendix"><a href="appendix_gfdl.html">E. GNU Free Documentation License</a></span></dt></dl></dd></dl></div><div class="list-of-figures"><p><strong>List of Figures</strong></p><dl><dt>B.1. <a href="appendix_porting.html#id494186">Configure and Build File Dependencies</a></dt></dl></div><div class="list-of-tables"><p><strong>List of Tables</strong></p><dl><dt>1.1. <a href="status.html#id410184">C++ 1998/2003 Implementation Status</a></dt><dt>1.2. <a href="status.html#id414053">C++ 200x Implementation Status</a></dt><dt>1.3. <a href="status.html#id456195">C++ TR1 Implementation Status</a></dt><dt>1.4. <a href="status.html#id461766">C++ TR 24733 Implementation Status</a></dt><dt>3.1. <a href="using.html#id465910">C++ Command Options</a></dt><dt>3.2. <a href="using_headers.html#id466139">C++ 1998 Library Headers</a></dt><dt>3.3. <a href="using_headers.html#id466443">C++ 1998 Library Headers for C Library Facilities</a></dt><dt>3.4. <a href="using_headers.html#id466649">C++ 200x Library Headers</a></dt><dt>3.5. <a href="using_headers.html#id467078">C++ 200x Library Headers for C Library Facilities</a></dt><dt>3.6. <a href="using_headers.html#id467327">C++ TR 1 Library Headers</a></dt><dt>3.7. <a href="using_headers.html#id467468">C++ TR 1 Library Headers for C Library Facilities</a></dt><dt>3.8. <a href="using_headers.html#id467644">C++ TR 24733 Decimal Floating-Point Header</a></dt><dt>3.9. <a href="using_headers.html#id467690">C++ ABI Headers</a></dt><dt>3.10. <a href="using_headers.html#id467743">Extension Headers</a></dt><dt>3.11. <a href="using_headers.html#id468041">Extension Debug Headers</a></dt><dt>3.12. <a href="using_headers.html#id468164">Extension Profile Headers</a></dt><dt>3.13. <a href="using_headers.html#id468275">Extension Parallel Headers</a></dt><dt>17.1. <a href="bk01pt03ch17s03.html#id482419">Debugging Containers</a></dt><dt>17.2. <a href="bk01pt03ch17s03.html#id482793">Debugging Containers C++0x</a></dt><dt>18.1. <a href="bk01pt03ch18s03.html#id484380">Parallel Algorithms</a></dt><dt>19.1. <a href="bk01pt03ch19s02.html#id486504">Profile Code Location</a></dt><dt>19.2. <a href="bk01pt03ch19s07.html#id487386">Profile Diagnostics</a></dt><dt>20.1. <a href="bitmap_allocator.html#id490827">Bitmap Allocator Memory Map</a></dt><dt>B.1. <a href="documentation_hacking.html#id495087">Doxygen Prerequisites</a></dt><dt>B.2. <a href="documentation_hacking.html#id495589">HTML to Doxygen Markup Comparison</a></dt><dt>B.3. <a href="documentation_hacking.html#id495751">Docbook Prerequisites</a></dt><dt>B.4. <a href="documentation_hacking.html#id496228">HTML to Docbook XML Markup Comparison</a></dt><dt>B.5. <a href="documentation_hacking.html#id496429">Docbook XML Element Use</a></dt><dt>B.6. <a href="api.html#id502145">Extension Allocators</a></dt><dt>B.7. <a href="api.html#id502375">Extension Allocators Continued</a></dt></dl></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="../spine.html">Prev</a> </td><td align="center"> </td><td align="right"> <a accesskey="n" href="intro.html">Next</a></td></tr><tr><td align="left" valign="top">The GNU C++ Library </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Part I. + Introduction + +</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/status.html b/libstdc++-v3/doc/html/manual/status.html new file mode 100644 index 000000000..438c1bf15 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/status.html @@ -0,0 +1,283 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Chapter 1. Status</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="intro.html" title="Part I. Introduction"/><link rel="prev" href="intro.html" title="Part I. Introduction"/><link rel="next" href="license.html" title="License"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 1. Status</th></tr><tr><td align="left"><a accesskey="p" href="intro.html">Prev</a> </td><th width="60%" align="center">Part I. + Introduction + +</th><td align="right"> <a accesskey="n" href="license.html">Next</a></td></tr></table><hr/></div><div class="chapter" title="Chapter 1. Status"><div class="titlepage"><div><div><h2 class="title"><a id="manual.intro.status"/>Chapter 1. Status</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="status.html#manual.intro.status.iso">Implementation Status</a></span></dt><dd><dl><dt><span class="section"><a href="status.html#status.iso.1998">C++ 1998/2003</a></span></dt><dt><span class="section"><a href="status.html#status.iso.200x">C++ 200x</a></span></dt><dt><span class="section"><a href="status.html#status.iso.tr1">C++ TR1</a></span></dt><dt><span class="section"><a href="status.html#status.iso.tr24733">C++ TR 24733</a></span></dt></dl></dd><dt><span class="section"><a href="license.html">License</a></span></dt><dd><dl><dt><span class="section"><a href="license.html#manual.intro.status.license.gpl">The Code: GPL</a></span></dt><dt><span class="section"><a href="license.html#manual.intro.status.license.fdl">The Documentation: GPL, FDL</a></span></dt></dl></dd><dt><span class="section"><a href="bugs.html">Bugs</a></span></dt><dd><dl><dt><span class="section"><a href="bugs.html#manual.intro.status.bugs.impl">Implementation Bugs</a></span></dt><dt><span class="section"><a href="bugs.html#manual.intro.status.bugs.iso">Standard Bugs</a></span></dt></dl></dd></dl></div><div class="section" title="Implementation Status"><div class="titlepage"><div><div><h2 class="title"><a id="manual.intro.status.iso"/>Implementation Status</h2></div></div></div><div class="section" title="C++ 1998/2003"><div class="titlepage"><div><div><h3 class="title"><a id="status.iso.1998"/>C++ 1998/2003</h3></div></div></div><div class="section" title="Implementation Status"><div class="titlepage"><div><div><h4 class="title"><a id="iso.1998.status"/>Implementation Status</h4></div></div></div><p> +This status table is based on the table of contents of ISO/IEC 14882:2003. +</p><p> +This page describes the C++ support in mainline GCC SVN, not in any +particular release. +</p><div class="table"><a id="id410184"/><p class="title"><strong>Table 1.1. C++ 1998/2003 Implementation Status</strong></p><div class="table-contents"><table summary="C++ 1998/2003 Implementation Status" border="1"><colgroup><col style="text-align: left" class="c1"/><col style="text-align: left" class="c2"/><col style="text-align: left" class="c3"/><col style="text-align: left" class="c4"/></colgroup><thead><tr><th style="text-align: left">Section</th><th style="text-align: left">Description</th><th style="text-align: left">Status</th><th style="text-align: left">Comments</th></tr></thead><tbody><tr><td style="text-align: left"> + <span class="emphasis"><em>18</em></span> + </td><td colspan="3" style="text-align: left"> + <span class="emphasis"><em>Language support</em></span> + </td></tr><tr><td style="text-align: left">18.1</td><td style="text-align: left">Types</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.2</td><td style="text-align: left">Implementation properties</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.2.1</td><td style="text-align: left">Numeric Limits</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.2.1.1</td><td style="text-align: left">Class template <code class="code">numeric_limits</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.2.1.2</td><td style="text-align: left"><code class="code">numeric_limits</code> members</td><td style="text-align: left">Y</td><td class="auto-generated"> </td></tr><tr><td style="text-align: left">18.2.1.3</td><td style="text-align: left"><code class="code">float_round_style</code></td><td style="text-align: left">Y</td><td class="auto-generated"> </td></tr><tr><td style="text-align: left">18.2.1.4</td><td style="text-align: left"><code class="code">float_denorm_style</code></td><td style="text-align: left">Y</td><td class="auto-generated"> </td></tr><tr><td style="text-align: left">18.2.1.5</td><td style="text-align: left"><code class="code">numeric_limits</code> specializations</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.2.2</td><td style="text-align: left">C Library</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.3</td><td style="text-align: left">Start and termination</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.4</td><td style="text-align: left">Dynamic memory management</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.5</td><td style="text-align: left">Type identification</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.5.1</td><td style="text-align: left">Class type_info</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.5.2</td><td style="text-align: left">Class bad_cast</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.5.3</td><td style="text-align: left">Class bad_typeid</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.6</td><td style="text-align: left">Exception handling</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.6.1</td><td style="text-align: left">Class exception</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.6.2</td><td style="text-align: left">Violation exception-specifications</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.6.3</td><td style="text-align: left">Abnormal termination</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.6.4</td><td style="text-align: left"><code class="code">uncaught_exception</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.7</td><td style="text-align: left">Other runtime support</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left"> + <span class="emphasis"><em>19</em></span> + </td><td colspan="3" style="text-align: left"> + <span class="emphasis"><em>Diagnostics</em></span> + </td></tr><tr><td style="text-align: left">19.1</td><td style="text-align: left">Exception classes</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">19.2</td><td style="text-align: left">Assertions</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">19.3</td><td style="text-align: left">Error numbers</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left"> + <span class="emphasis"><em>20</em></span> + </td><td colspan="3" style="text-align: left"> + <span class="emphasis"><em>General utilities</em></span> + </td></tr><tr><td style="text-align: left">20.1</td><td style="text-align: left">Requirements</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.2</td><td style="text-align: left">Utility components</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.2.1</td><td style="text-align: left">Operators</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.2.2</td><td style="text-align: left"><code class="code">pair</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.3</td><td style="text-align: left">Function objects</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.3.1</td><td style="text-align: left">Base</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.3.2</td><td style="text-align: left">Arithmetic operation</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.3.3</td><td style="text-align: left">Comparisons</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.3.4</td><td style="text-align: left">Logical operations</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.3.5</td><td style="text-align: left">Negators</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.3.6</td><td style="text-align: left">Binders</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.3.7</td><td style="text-align: left">Adaptors for pointers to functions</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.3.8</td><td style="text-align: left">Adaptors for pointers to members</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.4</td><td style="text-align: left">Memory</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.4.1</td><td style="text-align: left">The default allocator</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.4.2</td><td style="text-align: left">Raw storage iterator</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.4.3</td><td style="text-align: left">Temporary buffers</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.4.4</td><td style="text-align: left">Specialized algorithms</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.4.4.1</td><td style="text-align: left"><code class="code">uninitialized_copy</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.4.4.2</td><td style="text-align: left"><code class="code">uninitialized_fill</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.4.4.3</td><td style="text-align: left"><code class="code">uninitialized_fill_n</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.4.5</td><td style="text-align: left">Class template <code class="code">auto_ptr</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.4.6</td><td style="text-align: left">C library</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left"> + <span class="emphasis"><em>21</em></span> + </td><td colspan="3" style="text-align: left"> + <span class="emphasis"><em>Strings</em></span> + </td></tr><tr><td style="text-align: left">21.1</td><td style="text-align: left">Character traits</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">21.1.1</td><td style="text-align: left">Character traits requirements</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">21.1.2</td><td style="text-align: left">traits typedef</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">21.1.3</td><td style="text-align: left"><code class="code">char_traits</code> specializations</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">21.1.3.1</td><td style="text-align: left">struct <code class="code">char_traits<char></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">21.1.3.2</td><td style="text-align: left">struct <code class="code">char_traits<wchar_t></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">21.2</td><td style="text-align: left">String classes</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">21.3</td><td style="text-align: left">Class template <code class="code">basic_string</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">21.4</td><td style="text-align: left">Null-terminated sequence utilities</td><td style="text-align: left">Y</td><td style="text-align: left">C library dependency</td></tr><tr><td style="text-align: left"> + <span class="emphasis"><em>22</em></span> + </td><td colspan="3" style="text-align: left"> + <span class="emphasis"><em>Localization</em></span> + </td></tr><tr><td style="text-align: left">22.1</td><td style="text-align: left">Locales</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.1.1</td><td style="text-align: left">Class <code class="code">locale</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.1.2</td><td style="text-align: left"><code class="code">locale</code> globals</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.1.3</td><td style="text-align: left">Convenience interfaces</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.1.3.1</td><td style="text-align: left">Character classification</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.1.3.2</td><td style="text-align: left">Character conversions</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.2</td><td style="text-align: left">Standard locale categories</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.2.1</td><td style="text-align: left"><code class="code">ctype</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.2.2</td><td style="text-align: left">Numeric</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.2.2.1</td><td style="text-align: left"><code class="code">num_get</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.2.2.2</td><td style="text-align: left"><code class="code">num_put</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.2.3</td><td style="text-align: left"><code class="code">num_punct</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.2.4</td><td style="text-align: left"><code class="code">collate</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.2.5</td><td style="text-align: left">Time</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.2.5.1</td><td style="text-align: left"><code class="code">time_get</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.2.5.2</td><td style="text-align: left"><code class="code">time_get_byname</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.2.5.3</td><td style="text-align: left"><code class="code">time_put</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.2.5.3</td><td style="text-align: left"><code class="code">time_put_byname</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.2.6</td><td style="text-align: left">Monetary</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.2.6.1</td><td style="text-align: left"><code class="code">money_get</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.2.6.2</td><td style="text-align: left"><code class="code">money_put</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.2.6.3</td><td style="text-align: left"><code class="code">money_punct</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.2.6.4</td><td style="text-align: left"><code class="code">money_punct_byname</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.2.7</td><td style="text-align: left"><code class="code">messages</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.2.8</td><td style="text-align: left">Program-defined facets</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.3</td><td style="text-align: left">C Library Locales</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left"> + <span class="emphasis"><em>23</em></span> + </td><td colspan="3" style="text-align: left"> + <span class="emphasis"><em>Containers</em></span> + </td></tr><tr><td style="text-align: left">23.1</td><td style="text-align: left">Container requirements</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.2</td><td style="text-align: left">Sequence containers</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.2.1</td><td style="text-align: left">Class template <code class="code">deque</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.2.2</td><td style="text-align: left">Class template <code class="code">list</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.2.3</td><td style="text-align: left">Adaptors</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.2.3.1</td><td style="text-align: left">Class template <code class="code">queue</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.2.3.2</td><td style="text-align: left">Class template <code class="code">priority_queue</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.2.3.3</td><td style="text-align: left">Class template <code class="code">stack</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.2.4</td><td style="text-align: left">Class template <code class="code">vector</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.2.5</td><td style="text-align: left">Class <code class="code">vector<bool></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.3</td><td style="text-align: left">Associative containers</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.3.1</td><td style="text-align: left">Class template <code class="code">map</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.3.2</td><td style="text-align: left">Class template <code class="code">multimap</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.3.3</td><td style="text-align: left">Class template <code class="code">set</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.3.4</td><td style="text-align: left">Class template <code class="code">multiset</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left"> + <span class="emphasis"><em>24</em></span> + </td><td colspan="3" style="text-align: left"> + <span class="emphasis"><em>Iterators</em></span> + </td></tr><tr><td style="text-align: left">24.1</td><td style="text-align: left">Requirements</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">24.2</td><td style="text-align: left">Header <code class="code"><iterator></code> synopsis</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">24.3</td><td style="text-align: left">Iterator primitives</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">24.4</td><td style="text-align: left">Predefined iterators and Iterator adaptors</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">24.4.1</td><td style="text-align: left">Reverse iterators</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">24.4.2</td><td style="text-align: left">Insert iterators</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">24.5</td><td style="text-align: left">Stream iterators</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">24.5.1</td><td style="text-align: left">Class template <code class="code">istream_iterator</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">24.5.2</td><td style="text-align: left">Class template <code class="code">ostream_iterator</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">24.5.3</td><td style="text-align: left">Class template <code class="code">istreambuf_iterator</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">24.5.4</td><td style="text-align: left">Class template <code class="code">ostreambuf_iterator</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left"> + <span class="emphasis"><em>25</em></span> + </td><td colspan="3" style="text-align: left"> + <span class="emphasis"><em>Algorithms</em></span> + </td></tr><tr><td style="text-align: left">25.1</td><td style="text-align: left">Non-modifying sequence operations</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">25.2</td><td style="text-align: left">Mutating sequence operations</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">25.3</td><td style="text-align: left">Sorting and related operations</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">25.4</td><td style="text-align: left">C library algorithms</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left"> + <span class="emphasis"><em>26</em></span> + </td><td colspan="3" style="text-align: left"> + <span class="emphasis"><em>Numerics</em></span> + </td></tr><tr><td style="text-align: left">26.1</td><td style="text-align: left">Numeric type requirements</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.2</td><td style="text-align: left">Complex numbers</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.3</td><td style="text-align: left">Numeric arrays</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.3.1</td><td style="text-align: left">Header <code class="code"><valarray></code> synopsis</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.3.2</td><td style="text-align: left">Class template <code class="code">valarray</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.3.3</td><td style="text-align: left"><code class="code">valarray</code> non-member operations</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.3.4</td><td style="text-align: left">Class <code class="code">slice</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.3.5</td><td style="text-align: left">Class template <code class="code">slice_array</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.3.6</td><td style="text-align: left">Class <code class="code">gslice</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.3.7</td><td style="text-align: left">Class template <code class="code">gslice_array</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.3.8</td><td style="text-align: left">Class template <code class="code">mask_array</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.3.9</td><td style="text-align: left">Class template <code class="code">indirect_array</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.4</td><td style="text-align: left">Generalized numeric operations</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.4.1</td><td style="text-align: left"><code class="code">accumulate</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.4.2</td><td style="text-align: left"><code class="code">inner_product</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.4.3</td><td style="text-align: left"><code class="code">partial_sum</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.4.4</td><td style="text-align: left"><code class="code">adjacent_difference</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.4.5</td><td style="text-align: left">iota</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5</td><td style="text-align: left">C Library</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left"> + <span class="emphasis"><em>27</em></span> + </td><td colspan="3" style="text-align: left"> + <span class="emphasis"><em>Input/output</em></span> + </td></tr><tr><td style="text-align: left">27.1</td><td style="text-align: left">Requirements</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">27.2</td><td style="text-align: left">Forward declarations</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">27.3</td><td style="text-align: left">Standard iostream objects</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">27.3.1</td><td style="text-align: left">Narrow stream objects</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">27.3.2</td><td style="text-align: left">Wide stream objects</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">27.4</td><td style="text-align: left">Iostreams base classes</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">27.5</td><td style="text-align: left">Stream buffers</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">27.6</td><td style="text-align: left">Formatting and manipulators</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">27.7</td><td style="text-align: left">String-based streams</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">27.8</td><td style="text-align: left">File-based streams</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left"> + <span class="emphasis"><em>Appendix D</em></span> + </td><td colspan="3" style="text-align: left"> + <span class="emphasis"><em>Compatibility features</em></span> + </td></tr><tr><td style="text-align: left">D.1</td><td style="text-align: left">Increment operator with bool operand</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">D.2</td><td style="text-align: left"><code class="code">static</code> keyword</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">D.3</td><td style="text-align: left">Access declarations</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">D.4</td><td style="text-align: left">Implicit conversion from const strings</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">D.5</td><td style="text-align: left">C standard library headers</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">D.6</td><td style="text-align: left">Old iostreams members</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">D.7</td><td style="text-align: left">char* streams</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr></tbody></table></div></div><br class="table-break"/></div><div class="section" title="Implementation Specific Behavior"><div class="titlepage"><div><div><h4 class="title"><a id="iso.1998.specific"/>Implementation Specific Behavior</h4></div></div></div><p> + The ISO standard defines the following phrase: + </p><div class="blockquote"><blockquote class="blockquote"><div class="variablelist"><dl><dt><span class="term"> + <code class="code">[1.3.5] implementation-defined behavior</code> + </span></dt><dd><p> + Behavior, for a well-formed program construct and correct data, that + depends on the implementation <span class="emphasis"><em>and that each implementation + shall document</em></span>. + </p></dd></dl></div></blockquote></div><p> + We do so here, for the C++ library only. Behavior of the + compiler, linker, runtime loader, and other elements of "the + implementation" are documented elsewhere. Everything listed + in Annex B, Implementation Qualities, are also part of the + compiler, not the library. + </p><p> + For each entry, we give the section number of the standard, when + applicable. This list is probably incomplet and inkorrekt. + </p><p> + <span class="emphasis"><em>[1.9]/11 #3</em></span> If <code class="code">isatty(3)</code> is true, then + interactive stream support is implied. + </p><p> + <span class="emphasis"><em>[17.4.4.5]</em></span> Non-reentrant functions are probably best + discussed in the various sections on multithreading (see above). + </p><p><span class="emphasis"><em>[18.1]/4</em></span> The type of <code class="code">NULL</code> is described + <a class="link" href="support.html#std.support.types.null" title="NULL">here</a>. + </p><p><span class="emphasis"><em>[18.3]/8</em></span> Even though it's listed in the library + sections, libstdc++ has zero control over what the cleanup code hands + back to the runtime loader. Talk to the compiler people. :-) + </p><p><span class="emphasis"><em>[18.4.2.1]/5</em></span> (bad_alloc), + <span class="emphasis"><em>[18.5.2]/5</em></span> (bad_cast), + <span class="emphasis"><em>[18.5.3]/5</em></span> (bad_typeid), + <span class="emphasis"><em>[18.6.1]/8</em></span> (exception), + <span class="emphasis"><em>[18.6.2.1]/5</em></span> (bad_exception): The <code class="code">what()</code> + member function of class <code class="code">std::exception</code>, and these other + classes publicly derived from it, simply returns the name of the + class. But they are the <span class="emphasis"><em>mangled</em></span> names; you will need to call + <code class="code">c++filt</code> and pass the names as command-line parameters to + demangle them, or call a + <a class="link" href="ext_demangling.html" title="Chapter 27. Demangling">runtime demangler function</a>. + (The classes in <code class="code"><stdexcept></code> have constructors which + require an argument to use later for <code class="code">what()</code> calls, so the + problem of <code class="code">what()</code>'s value does not arise in most + user-defined exceptions.) + </p><p><span class="emphasis"><em>[18.5.1]/7</em></span> The return value of + <code class="code">std::type_info::name()</code> is the mangled type name (see the + previous entry for more). + </p><p><span class="emphasis"><em>[20.1.5]/5</em></span> <span class="emphasis"><em>"Implementors are encouraged to + supply libraries that can accept allocators that encapsulate more + general memory models and that support non-equal instances. In such + implementations, any requirements imposed on allocators by containers + beyond those requirements that appear in Table 32, and the semantics + of containers and algorithms when allocator instances compare + non-equal, are implementation-defined."</em></span> As yet we don't + have any allocators which compare non-equal, so we can't describe how + they behave. + </p><p><span class="emphasis"><em>[21.1.3.1]/3,4</em></span>, + <span class="emphasis"><em>[21.1.3.2]/2</em></span>, + <span class="emphasis"><em>[23.*]'s foo::iterator</em></span>, + <span class="emphasis"><em>[27.*]'s foo::*_type</em></span>, + <span class="emphasis"><em>others...</em></span> + Nope, these types are called implementation-defined because you + shouldn't be taking advantage of their underlying types. Listing them + here would defeat the purpose. :-) + </p><p><span class="emphasis"><em>[21.1.3.1]/5</em></span> I don't really know about + the mbstate_t stuff... see + the <a class="link" href="facets.html#std.localization.facet.codecvt" title="codecvt">chapter 22 + notes</a> for what does exist. + </p><p><span class="emphasis"><em>[22.*]</em></span> Anything and everything we have on locale + implementation will be described + <a class="link" href="localization.html#std.localization.locales.locale" title="locale">over here</a>. + </p><p><span class="emphasis"><em>[26.2.8]/9</em></span> I have no idea what + <code class="code">complex<T></code>'s pow(0,0) returns. + </p><p><span class="emphasis"><em>[27.4.2.4]/2</em></span> Calling + <code class="code">std::ios_base::sync_with_stdio</code> after I/O has already been + performed on the standard stream objects will + flush the buffers, and + destroy and recreate the underlying buffer instances. Whether or not + the previously-written I/O is destroyed in this process depends mostly + on the --enable-libio choice: for stdio, if the written data is + already in the stdio buffer, the data may be completely safe! + </p><p><span class="emphasis"><em>[27.6.1.1.2]</em></span>, + <span class="emphasis"><em>[27.6.2.3]</em></span> The I/O sentry ctor and dtor can perform + additional work than the minimum required. We are not currently taking + advantage of this yet. + </p><p><span class="emphasis"><em>[27.7.1.3]/16</em></span>, + <span class="emphasis"><em>[27.8.1.4]/10</em></span> + The effects of <code class="code">pubsetbuf/setbuf</code> are described + <a class="link" href="io.html" title="Chapter 13. Input and Output">in this chapter</a>. + </p><p><span class="emphasis"><em>[27.8.1.4]/16</em></span> Calling <code class="code">fstream::sync</code> when + a get area exists will... whatever <code class="code">fflush()</code> does, I think. + </p></div></div><div class="section" title="C++ 200x"><div class="titlepage"><div><div><h3 class="title"><a id="status.iso.200x"/>C++ 200x</h3></div></div></div><p> +This table is based on the table of contents of ISO/IEC +JTC1 SC22 WG21 Doc No: N3290 Date: 2011-04-11 +Final Draft International Standard, Standard for Programming Language C++ +</p><p> +In this implementation <code class="literal">-std=gnu++0x</code> or +<code class="literal">-std=c++0x</code> flags must be used to enable language +and library +features. See <a class="link" href="using.html#manual.intro.using.flags" title="Command Options">dialect</a> +options. The pre-defined symbol +<code class="constant">__GXX_EXPERIMENTAL_CXX0X__</code> is used to check for the +presence of the required flag. +</p><p> +This page describes the C++0x support in the GCC 4.6 release series. +</p><div class="table"><a id="id414053"/><p class="title"><strong>Table 1.2. C++ 200x Implementation Status</strong></p><div class="table-contents"><table summary="C++ 200x Implementation Status" border="1"><colgroup><col style="text-align: left" class="c1"/><col style="text-align: left" class="c2"/><col style="text-align: left" class="c3"/><col style="text-align: left" class="c4"/></colgroup><thead><tr><th style="text-align: left">Section</th><th style="text-align: left">Description</th><th style="text-align: left">Status</th><th style="text-align: left">Comments</th></tr></thead><tbody><tr><td style="text-align: left"> + <span class="emphasis"><em>18</em></span> + </td><td colspan="3" style="text-align: left"> + <span class="emphasis"><em>Language support</em></span> + </td></tr><tr><td style="text-align: left">18.1</td><td style="text-align: left">General</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">18.2</td><td style="text-align: left">Types</td><td style="text-align: left">Partial</td><td style="text-align: left">Missing offsetof, max_align_t</td></tr><tr><td style="text-align: left">18.3</td><td style="text-align: left">Implementation properties</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.3.2</td><td style="text-align: left">Numeric Limits</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.3.2.3</td><td style="text-align: left">Class template <code class="code">numeric_limits</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.3.2.4</td><td style="text-align: left"><code class="code">numeric_limits</code> members</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">18.3.2.5</td><td style="text-align: left"><code class="code">float_round_style</code></td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">18.3.2.6</td><td style="text-align: left"><code class="code">float_denorm_style</code></td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.3.2.7</td><td style="text-align: left"><code class="code">numeric_limits</code> specializations</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.3.3</td><td style="text-align: left">C Library</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.4</td><td style="text-align: left">Integer types</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.4.1</td><td style="text-align: left">Header <code class="code"><cstdint></code> synopsis</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">18.5</td><td style="text-align: left">Start and termination</td><td style="text-align: left">Partial</td><td style="text-align: left">C library dependency for quick_exit, at_quick_exit</td></tr><tr><td style="text-align: left">18.6</td><td style="text-align: left">Dynamic memory management</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.7</td><td style="text-align: left">Type identification</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.7.1</td><td style="text-align: left">Class type_info</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.7.2</td><td style="text-align: left">Class bad_cast</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.7.3</td><td style="text-align: left">Class bad_typeid</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.8</td><td style="text-align: left">Exception handling</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.8.1</td><td style="text-align: left">Class exception</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.8.2</td><td style="text-align: left">Class bad_exception</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.8.3</td><td style="text-align: left">Abnormal termination</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.8.4</td><td style="text-align: left"><code class="code">uncaught_exception</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.8.5</td><td style="text-align: left">Exception Propagation</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.8.6</td><td style="text-align: left"><code class="code">nested_exception</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.9</td><td style="text-align: left">Initializer lists</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.9.1</td><td style="text-align: left">Initializer list constructors</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.9.2</td><td style="text-align: left">Initializer list access</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">18.9.3</td><td style="text-align: left">Initializer list range access</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">18.10</td><td style="text-align: left">Other runtime support</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left"> + <span class="emphasis"><em>19</em></span> + </td><td colspan="3" style="text-align: left"> + <span class="emphasis"><em>Diagnostics</em></span> + </td></tr><tr><td style="text-align: left">19.1</td><td style="text-align: left">General</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">19.2</td><td style="text-align: left">Exception classes</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">19.3</td><td style="text-align: left">Assertions</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">19.4</td><td style="text-align: left">Error numbers</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">19.5</td><td style="text-align: left">System error support</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">19.5.1</td><td style="text-align: left">Class <code class="code">error_category</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">19.5.2</td><td style="text-align: left">Class <code class="code">error_code</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">19.5.3</td><td style="text-align: left">Class <code class="code">error_condition</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">19.5.4</td><td style="text-align: left">Comparison operators</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">19.5.5</td><td style="text-align: left">Class <code class="code">system_error</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left"> + <span class="emphasis"><em>20</em></span> + </td><td colspan="3" style="text-align: left"> + <span class="emphasis"><em>General utilities</em></span> + </td></tr><tr><td style="text-align: left">20.1</td><td style="text-align: left">General</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.2</td><td style="text-align: left">Utility components</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.2.1</td><td style="text-align: left">Operators</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.2.2</td><td style="text-align: left">Swap</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.2.3</td><td style="text-align: left"><code class="code">forward</code> and <code class="code">move</code> helpers</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.2.4</td><td style="text-align: left">Function template <code class="code">declval</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.3</td><td style="text-align: left">Pairs</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.3.1</td><td style="text-align: left">In general</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.3.2</td><td style="text-align: left">Class template <code class="code">pair</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.3.3</td><td style="text-align: left">Specialized algorithms</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.3.4</td><td style="text-align: left">Tuple-like access to <code class="code">pair</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.3.5</td><td style="text-align: left">Piecewise construction</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.4</td><td style="text-align: left">Tuples</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.4.1</td><td style="text-align: left">In general</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.4.2</td><td style="text-align: left">Class template <code class="code">tuple</code></td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.4.2.1</td><td style="text-align: left">Construction</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.4.2.2</td><td style="text-align: left">Assignment</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.4.2.3</td><td style="text-align: left">Swap</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">20.4.2.4</td><td style="text-align: left">Tuple creation functions</td><td style="text-align: left">Partial</td><td style="text-align: left"><code class="code">tuple_cat</code> should be a single variadic signature (DR 1385)</td></tr><tr><td style="text-align: left">20.4.2.5</td><td style="text-align: left">Tuple helper classes</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.4.2.6</td><td style="text-align: left">Element access</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.4.2.7</td><td style="text-align: left">Relational operators</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">20.4.2.8</td><td style="text-align: left">Tuple traits</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.4.2.9</td><td style="text-align: left">Tuple specialized algorithms</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.5</td><td style="text-align: left">Class template <code class="code">bitset</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.5.1</td><td style="text-align: left"><code class="code">bitset</code> constructors</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.5.2</td><td style="text-align: left"><code class="code">bitset</code> members</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.5.3</td><td style="text-align: left"><code class="code">bitset</code> hash support</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.5.4</td><td style="text-align: left"><code class="code">bitset</code> operators</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.6</td><td style="text-align: left">Memory</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.6.1</td><td style="text-align: left">In general</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.6.2</td><td style="text-align: left">Header <code class="code"><memory></code> synopsis</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">20.6.3</td><td style="text-align: left">Pointer traits</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">20.6.4</td><td style="text-align: left">Pointer safety</td><td style="text-align: left">Partial</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">20.6.5</td><td style="text-align: left">Align</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.6.6</td><td style="text-align: left">Allocator argument tag</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.6.7</td><td style="text-align: left"><code class="code">uses_allocator</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">20.6.8</td><td style="text-align: left">Allocator traits</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.6.9</td><td style="text-align: left">The default allocator</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.6.10</td><td style="text-align: left">Raw storage iterator</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.6.11</td><td style="text-align: left">Temporary buffers</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.6.12</td><td style="text-align: left">Specialized algorithms</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.6.12.1</td><td style="text-align: left"><code class="code">addressof</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.6.12.2</td><td style="text-align: left"><code class="code">uninitialized_copy</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.6.12.3</td><td style="text-align: left"><code class="code">uninitialized_fill</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.6.12.4</td><td style="text-align: left"><code class="code">uninitialized_fill_n</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.6.13</td><td style="text-align: left">C library</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.7</td><td style="text-align: left">Smart pointers</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.7.1</td><td style="text-align: left">Class template <code class="code">unique_ptr</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.7.2</td><td style="text-align: left">Shared-ownership pointers</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.7.2.1</td><td style="text-align: left">Class <code class="code">bad_weak_ptr</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.7.2.2</td><td style="text-align: left">Class template <code class="code">shared_ptr</code></td><td style="text-align: left">Y</td><td style="text-align: left"> + <p> + Uses code from + <a class="link" href="http://www.boost.org/libs/smart_ptr/shared_ptr.htm">boost::shared_ptr</a>. + </p> + </td></tr><tr><td style="text-align: left">20.7.2.3</td><td style="text-align: left">Class template <code class="code">weak_ptr</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.7.2.4</td><td style="text-align: left">Class template <code class="code">emable_shared_from_this</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">20.7.2.5</td><td style="text-align: left"><code class="code">shared_ptr</code> atomic access</td><td style="text-align: left">Partial</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.7.2.6</td><td style="text-align: left">Smart pointer hash support</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.8</td><td style="text-align: left">Function objects</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.8.1</td><td style="text-align: left">Definitions</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.8.2</td><td style="text-align: left">Requirements</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.8.3</td><td style="text-align: left">Class template <code class="code">reference_wrapper</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.8.4</td><td style="text-align: left">Arithmetic operation</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.8.5</td><td style="text-align: left">Comparisons</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.8.6</td><td style="text-align: left">Logical operations</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.8.7</td><td style="text-align: left">Bitwise operations</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.8.8</td><td style="text-align: left">Negators</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.8.9</td><td style="text-align: left">Function template <code class="code">bind</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">20.8.10</td><td style="text-align: left">Function template <code class="code">mem_fn</code></td><td style="text-align: left">Partial</td><td style="text-align: left">Missing overloads for reference-qualified member functions</td></tr><tr><td style="text-align: left">20.8.11</td><td style="text-align: left">Polymorphic function wrappers</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.8.11.1</td><td style="text-align: left">Class <code class="code">bad_function_call</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">20.8.11.2</td><td style="text-align: left">Class template <code class="code">function</code></td><td style="text-align: left">Partial</td><td style="text-align: left">Missing allocator support</td></tr><tr><td style="text-align: left">20.8.12</td><td style="text-align: left">Class template <code class="code">hash</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.9</td><td style="text-align: left">Metaprogramming and type traits</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.9.1</td><td style="text-align: left">Requirements</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.9.2</td><td style="text-align: left">Header <code class="code"><type_traits></code> synopsis</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.9.3</td><td style="text-align: left">Helper classes</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.9.4</td><td style="text-align: left">Unary Type Traits</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.9.4.1</td><td style="text-align: left">Primary type categories</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.9.4.2</td><td style="text-align: left">Composite type traits</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">20.9.4.3</td><td style="text-align: left">Type properties</td><td style="text-align: left">Partial</td><td style="text-align: left">Missing is_trivially_copyable, + is_assignable, is_copy_assignable, is_move_assignable, + is_trivially_constructible, is_trivially_default_constructible, + is_trivially_copy_constructible, is_trivially_move_constructible, + is_trivially_assignable, is_trivially_default_assignable, + is_trivially_copy_assignable, is_trivially_move_assignable, + is_trivially_destructible, + is_nothrow_assignable, + is_nothrow_copy_assignable, is_nothrow_move_assignable, + is_nothrow_destructible + </td></tr><tr><td style="text-align: left">20.9.5</td><td style="text-align: left">Type property queries</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.9.6</td><td style="text-align: left">Relationships between types</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.9.7</td><td style="text-align: left">Transformations between types</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.9.7.1</td><td style="text-align: left">Const-volatile modifications</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.9.7.2</td><td style="text-align: left">Reference modifications</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.9.7.3</td><td style="text-align: left">Sign modifications</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.9.7.4</td><td style="text-align: left">Array modifications</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.9.7.5</td><td style="text-align: left">Pointer modifications</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.9.7.6</td><td style="text-align: left">Other transformations</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.10</td><td style="text-align: left">Compile-time rational arithmetic</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.10.1</td><td style="text-align: left">In general</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.10.2</td><td style="text-align: left">Header <code class="code"><ratio></code> synopsis</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.10.3</td><td style="text-align: left">Class template <code class="code">ratio</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.10.4</td><td style="text-align: left">Arithmetic on <code class="code">ratio</code>s</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.10.5</td><td style="text-align: left">Comparison of <code class="code">ratio</code>s</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.10.6</td><td style="text-align: left">SI types for <code class="code">ratio</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.11</td><td style="text-align: left">Time utilities</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.11.3</td><td style="text-align: left">Clock requirements</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.11.4</td><td style="text-align: left">Time-related traits</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.11.4.1</td><td style="text-align: left"><code class="code">treat_as_floating_point</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.11.4.2</td><td style="text-align: left"><code class="code">duration_values</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.11.4.3</td><td style="text-align: left">Specializations of <code class="code">common_type</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">20.11.5</td><td style="text-align: left">Class template <code class="code">duration</code></td><td style="text-align: left">Partial</td><td style="text-align: left">Missing constexpr for non-member arithmetic operations</td></tr><tr><td style="text-align: left">20.11.6</td><td style="text-align: left">Class template <code class="code">time_point</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.11.7</td><td style="text-align: left">Clocks</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.11.7.1</td><td style="text-align: left">Class <code class="code">system_clock</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">20.11.7.2</td><td style="text-align: left">Class <code class="code">steady_clock</code></td><td style="text-align: left">N</td><td style="text-align: left">Support old <code class="code">monotonic_clock</code> spec instead</td></tr><tr><td style="text-align: left">20.11.7.3</td><td style="text-align: left">Class <code class="code">high_resolution_clock</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">20.11.8</td><td style="text-align: left">Date and time functions</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">20.12</td><td style="text-align: left">Scoped allocator adaptor</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">20.12.1</td><td style="text-align: left">Header <code class="code"><scoped_allocator></code> synopsis</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">20.12.2</td><td style="text-align: left">Scoped allocator adaptor member types</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">20.12.3</td><td style="text-align: left">Scoped allocator adaptor constructors</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">20.12.4</td><td style="text-align: left">Scoped allocator adaptor members</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">20.12.5</td><td style="text-align: left">Scoped allocator operators</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">20.13</td><td style="text-align: left">Class <code class="code">type_index</code></td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left"> + <span class="emphasis"><em>21</em></span> + </td><td colspan="3" style="text-align: left"> + <span class="emphasis"><em>Strings</em></span> + </td></tr><tr><td style="text-align: left">21.1</td><td style="text-align: left">General</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">21.2</td><td style="text-align: left">Character traits</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">21.2.1</td><td style="text-align: left">Character traits requirements</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">21.2.2</td><td style="text-align: left">traits typedefs</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">21.2.3</td><td style="text-align: left"><code class="code">char_traits</code> specializations</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">21.2.3.1</td><td style="text-align: left">struct <code class="code">char_traits<char></code></td><td style="text-align: left">Partial</td><td style="text-align: left">Missing constexpr</td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">21.2.3.2</td><td style="text-align: left">struct <code class="code">char_traits<char16_t></code></td><td style="text-align: left">Partial</td><td style="text-align: left">Missing constexpr</td></tr><tr><td style="text-align: left">21.2.3.3</td><td style="text-align: left">struct <code class="code">char_traits<char32_t></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">21.2.3.4</td><td style="text-align: left">struct <code class="code">char_traits<wchar_t></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">21.3</td><td style="text-align: left">String classes</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">21.4</td><td style="text-align: left">Class template <code class="code">basic_string</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">21.5</td><td style="text-align: left">Numeric Conversions</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">21.6</td><td style="text-align: left">Hash support</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">21.7</td><td style="text-align: left">Null-terminated sequence utilities</td><td style="text-align: left">Y</td><td style="text-align: left">C library dependency</td></tr><tr><td style="text-align: left"> + <span class="emphasis"><em>22</em></span> + </td><td colspan="3" style="text-align: left"> + <span class="emphasis"><em>Localization</em></span> + </td></tr><tr><td style="text-align: left">22.1</td><td style="text-align: left">General</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.2</td><td style="text-align: left">Header <code class="code"><locale></code> synopsis</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.3</td><td style="text-align: left">Locales</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.3.1</td><td style="text-align: left">Class <code class="code">locale</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.3.2</td><td style="text-align: left"><code class="code">locale</code> globals</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.3.3</td><td style="text-align: left">Convenience interfaces</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.3.3.1</td><td style="text-align: left">Character classification</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.3.3.2</td><td style="text-align: left">Conversions</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.3.3.2.1</td><td style="text-align: left">Character conversions</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">22.3.3.2.2</td><td style="text-align: left"><code class="code">string</code> conversions</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">22.3.3.2.3</td><td style="text-align: left">Buffer conversions</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.4</td><td style="text-align: left">Standard <code class="code">locale</code> categories</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.4.1</td><td style="text-align: left">The <code class="code">ctype</code> category</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.4.2</td><td style="text-align: left">The numeric category</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.4.2.1</td><td style="text-align: left"><code class="code">num_get</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.4.2.2</td><td style="text-align: left"><code class="code">num_put</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.4.3</td><td style="text-align: left">The numeric punctuation facet</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.4.4</td><td style="text-align: left">The collate category</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.4.5</td><td style="text-align: left">The time category</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.4.5.1</td><td style="text-align: left">Class template <code class="code">time_get</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.4.5.2</td><td style="text-align: left">Class template <code class="code">time_get_byname</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.4.5.3</td><td style="text-align: left">Class template <code class="code">time_put</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.4.5.3</td><td style="text-align: left">Class template <code class="code">time_put_byname</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.4.6</td><td style="text-align: left">The monetary category</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.4.6.1</td><td style="text-align: left">Class template <code class="code">money_get</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.4.6.2</td><td style="text-align: left">Class template <code class="code">money_put</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.4.6.3</td><td style="text-align: left">Class template <code class="code">money_punct</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.4.6.4</td><td style="text-align: left">Class template <code class="code">money_punct_byname</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.4.7</td><td style="text-align: left">The message retrieval category</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.4.8</td><td style="text-align: left">Program-defined facets</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">22.5</td><td style="text-align: left">Standard code conversion facets</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">22.6</td><td style="text-align: left">C Library Locales</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left"> + <span class="emphasis"><em>23</em></span> + </td><td colspan="3" style="text-align: left"> + <span class="emphasis"><em>Containers</em></span> + </td></tr><tr><td style="text-align: left">23.1</td><td style="text-align: left">General</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.2</td><td style="text-align: left">Container requirements</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.2.1</td><td style="text-align: left">General container requirements</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.2.2</td><td style="text-align: left">Container data races</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.2.3</td><td style="text-align: left">Sequence containers</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.2.4</td><td style="text-align: left">Associative containers</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.2.5</td><td style="text-align: left">Unordered associative containers</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.3</td><td style="text-align: left">Sequence containers</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.3.2</td><td style="text-align: left">Class template <code class="code">array</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.3.3</td><td style="text-align: left">Class template <code class="code">deque</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.3.4</td><td style="text-align: left">Class template <code class="code">forward_list</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.3.5</td><td style="text-align: left">Class template <code class="code">list</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.3.6</td><td style="text-align: left">Class template <code class="code">vector</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.3.7</td><td style="text-align: left">Class <code class="code">vector<bool></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.4</td><td style="text-align: left">Associative containers</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.4.4</td><td style="text-align: left">Class template <code class="code">map</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.4.5</td><td style="text-align: left">Class template <code class="code">multimap</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.4.6</td><td style="text-align: left">Class template <code class="code">set</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.4.7</td><td style="text-align: left">Class template <code class="code">multiset</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.5</td><td style="text-align: left">Unordered associative containers</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.5.4</td><td style="text-align: left">Class template <code class="code">unordered_map</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.5.5</td><td style="text-align: left">Class template <code class="code">unordered_multimap</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.5.6</td><td style="text-align: left">Class template <code class="code">unordered_set</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.5.7</td><td style="text-align: left">Class template <code class="code">unordered_multiset</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.6</td><td style="text-align: left">Container adaptors</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.6.1</td><td style="text-align: left">Class template <code class="code">queue</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.6.2</td><td style="text-align: left">Class template <code class="code">priority_queue</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">23.6.3</td><td style="text-align: left">Class template <code class="code">stack</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left"> + <span class="emphasis"><em>24</em></span> + </td><td colspan="3" style="text-align: left"> + <span class="emphasis"><em>Iterators</em></span> + </td></tr><tr><td style="text-align: left">24.1</td><td style="text-align: left">General</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">24.2</td><td style="text-align: left">Iterator requirements</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">24.3</td><td style="text-align: left">Header <code class="code"><iterator></code> synopsis</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">24.4</td><td style="text-align: left">Iterator primitives</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">24.5</td><td style="text-align: left">Iterator adaptors</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">24.5.1</td><td style="text-align: left">Reverse iterators</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">24.5.2</td><td style="text-align: left">Insert iterators</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">24.5.3</td><td style="text-align: left">Move iterators</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">24.6</td><td style="text-align: left">Stream iterators</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">24.6.1</td><td style="text-align: left">Class template <code class="code">istream_iterator</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">24.6.2</td><td style="text-align: left">Class template <code class="code">ostream_iterator</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">24.6.3</td><td style="text-align: left">Class template <code class="code">istreambuf_iterator</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">24.6.4</td><td style="text-align: left">Class template <code class="code">ostreambuf_iterator</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">24.6.5</td><td style="text-align: left">range access</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left"> + <span class="emphasis"><em>25</em></span> + </td><td colspan="3" style="text-align: left"> + <span class="emphasis"><em>Algorithms</em></span> + </td></tr><tr><td style="text-align: left">25.1</td><td style="text-align: left">General</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">25.2</td><td style="text-align: left">Non-modifying sequence operations</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">25.3</td><td style="text-align: left">Mutating sequence operations</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">25.4</td><td style="text-align: left">Sorting and related operations</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">25.5</td><td style="text-align: left">C library algorithms</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left"> + <span class="emphasis"><em>26</em></span> + </td><td colspan="3" style="text-align: left"> + <span class="emphasis"><em>Numerics</em></span> + </td></tr><tr><td style="text-align: left">26.1</td><td style="text-align: left">General</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.2</td><td style="text-align: left">Numeric type requirements</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.3</td><td style="text-align: left">The floating-point environment</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.4</td><td style="text-align: left">Complex numbers</td><td style="text-align: left">Partial</td><td style="text-align: left">Missing constexpr</td></tr><tr><td style="text-align: left">26.5</td><td style="text-align: left">Random number generation</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.1</td><td style="text-align: left">Requirements</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.2</td><td style="text-align: left">Header <code class="code"><random></code> synopsis</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.3</td><td style="text-align: left">Random number engine class templates</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.3.1</td><td style="text-align: left">Class template <code class="code">linear_congruential_engine</code></td><td style="text-align: left">Y</td><td style="text-align: left">Missing constexpr</td></tr><tr><td style="text-align: left">26.5.3.2</td><td style="text-align: left">Class template <code class="code">mersenne_twister_engine</code></td><td style="text-align: left">Y</td><td style="text-align: left">Missing constexpr</td></tr><tr><td style="text-align: left">26.5.3.3</td><td style="text-align: left">Class template <code class="code">subtract_with_carry_engine</code></td><td style="text-align: left">Y</td><td style="text-align: left">Missing constexpr</td></tr><tr><td style="text-align: left">26.5.4</td><td style="text-align: left">Random number engine adaptor class templates</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.4.2</td><td style="text-align: left">Class template <code class="code">discard_block_engine</code></td><td style="text-align: left">Y</td><td style="text-align: left">Missing constexpr</td></tr><tr><td style="text-align: left">26.5.4.3</td><td style="text-align: left">Class template <code class="code">independent_bits_engine</code></td><td style="text-align: left">Y</td><td style="text-align: left">Missing constexpr</td></tr><tr><td style="text-align: left">26.5.4.4</td><td style="text-align: left">Class template <code class="code">shuffle_order_engine</code></td><td style="text-align: left">Y</td><td style="text-align: left">Missing constexpr</td></tr><tr><td style="text-align: left">26.5.5</td><td style="text-align: left">Engines and engine adaptors with predefined parameters</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.6</td><td style="text-align: left">Class <code class="code">random_device</code></td><td style="text-align: left">Y</td><td style="text-align: left">Missing constexpr</td></tr><tr><td style="text-align: left">26.5.7</td><td style="text-align: left">Utilities</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.7.1</td><td style="text-align: left">Class <code class="code">seed_seq</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.7.2</td><td style="text-align: left">Function template <code class="code">generate_canonical</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.8</td><td style="text-align: left">Random number distribution class templates</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.8.2</td><td style="text-align: left">Uniform distributions</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.8.2.1</td><td style="text-align: left">Class template <code class="code">uniform_int_distribution</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.8.2.2</td><td style="text-align: left">Class template <code class="code">uniform_real_distribution</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.8.3</td><td style="text-align: left">Bernoulli distributions</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.8.3.1</td><td style="text-align: left">Class <code class="code">bernoulli_distribution</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.8.3.2</td><td style="text-align: left">Class template <code class="code">binomial_distribution</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.8.3.3</td><td style="text-align: left">Class template <code class="code">geometric_distribution</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.8.3.4</td><td style="text-align: left">Class template <code class="code">negative_binomial_distribution</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.8.4</td><td style="text-align: left">Poisson distributions</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.8.4.1</td><td style="text-align: left">Class template <code class="code">poisson_distribution</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.8.4.2</td><td style="text-align: left">Class template <code class="code">exponential_distribution</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.8.4.3</td><td style="text-align: left">Class template <code class="code">gamma_distribution</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.8.4.4</td><td style="text-align: left">Class template <code class="code">weibull_distribution</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.8.4.5</td><td style="text-align: left">Class template <code class="code">extreme_value_distribution</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.8.5</td><td style="text-align: left">Normal distributions</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.8.5.1</td><td style="text-align: left">Class template <code class="code">normal_distribution</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.8.5.2</td><td style="text-align: left">Class template <code class="code">lognormal_distribution</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.8.5.3</td><td style="text-align: left">Class template <code class="code">chi_squared_distribution</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.8.5.4</td><td style="text-align: left">Class template <code class="code">cauchy_distribution</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.8.5.5</td><td style="text-align: left">Class template <code class="code">fisher_f_distribution</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.8.5.6</td><td style="text-align: left">Class template <code class="code">student_t_distribution</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.8.6</td><td style="text-align: left">Sampling distributions</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.8.6.1</td><td style="text-align: left">Class template <code class="code">discrete_distribution</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.8.6.2</td><td style="text-align: left">Class template <code class="code">piecewise_constant_distribution</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.5.8.6.3</td><td style="text-align: left">Class template <code class="code">piecewise_linear_distribution</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.6</td><td style="text-align: left">Numeric arrays</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.6.1</td><td style="text-align: left">Header <code class="code"><valarray></code> synopsis</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">26.6.2</td><td style="text-align: left">Class template <code class="code">valarray</code></td><td style="text-align: left">Partial</td><td style="text-align: left">Missing move and swap operations</td></tr><tr><td style="text-align: left">26.6.3</td><td style="text-align: left"><code class="code">valarray</code> non-member operations</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.6.4</td><td style="text-align: left">Class <code class="code">slice</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.6.5</td><td style="text-align: left">Class template <code class="code">slice_array</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.6.6</td><td style="text-align: left">The <code class="code">gslice</code> class</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.6.7</td><td style="text-align: left">Class template <code class="code">gslice_array</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.6.8</td><td style="text-align: left">Class template <code class="code">mask_array</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.6.9</td><td style="text-align: left">Class template <code class="code">indirect_array</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.6.10</td><td style="text-align: left"><code class="code">valarray</code> range access</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.7</td><td style="text-align: left">Generalized numeric operations</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.7.1</td><td style="text-align: left">Header <code class="code"><numeric></code> synopsis</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.7.2</td><td style="text-align: left"><code class="code">accumulate</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.7.3</td><td style="text-align: left"><code class="code">inner_product</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.7.4</td><td style="text-align: left"><code class="code">partial_sum</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.7.5</td><td style="text-align: left"><code class="code">adjacent_difference</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.7.6</td><td style="text-align: left">iota</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">26.8</td><td style="text-align: left">C Library</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left"> + <span class="emphasis"><em>27</em></span> + </td><td colspan="3" style="text-align: left"> + <span class="emphasis"><em>Input/output library</em></span> + </td></tr><tr><td style="text-align: left">27.1</td><td style="text-align: left">General</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">27.2</td><td style="text-align: left">Iostreams requirements</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">27.2.1</td><td style="text-align: left">Imbue Limitations</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">27.2.2</td><td style="text-align: left">Positioning Type Limitations</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">27.2.3</td><td style="text-align: left">Thread safety</td><td style="text-align: left">Partial</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">27.3</td><td style="text-align: left">Forward declarations</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">27.4</td><td style="text-align: left">Standard iostream objects</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">27.4.1</td><td style="text-align: left">Overview</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">27.4.2</td><td style="text-align: left">Narrow stream objects</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">27.4.3</td><td style="text-align: left">Wide stream objects</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">27.5</td><td style="text-align: left">Iostreams base classes</td><td style="text-align: left">Partial</td><td style="text-align: left"> + Missing move and swap operations on <code class="code">basic_ios</code>. Missing + <code class="code">make_error_code</code> and <code class="code">make_error_condition</code>. + </td></tr><tr><td style="text-align: left">27.6</td><td style="text-align: left">Stream buffers</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">27.7</td><td style="text-align: left">Formatting and manipulators</td><td style="text-align: left">Partial</td><td style="text-align: left">Missing move and swap operations</td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">27.8</td><td style="text-align: left">String-based streams</td><td style="text-align: left">Partial</td><td style="text-align: left">Missing move and swap operations</td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">27.9</td><td style="text-align: left">File-based streams</td><td style="text-align: left">Partial</td><td style="text-align: left">Missing move and swap operations</td></tr><tr><td style="text-align: left"> + <span class="emphasis"><em>28</em></span> + </td><td colspan="3" style="text-align: left"> + <span class="emphasis"><em>Regular expressions</em></span> + </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">28.1</td><td style="text-align: left">General</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">28.2</td><td style="text-align: left">Definitions</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">28.3</td><td style="text-align: left">Requirements</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">28.4</td><td style="text-align: left">Header <code class="code"><regex></code> synopsis</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">28.5</td><td style="text-align: left">Namespace <code class="code">std::regex_constants</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">28.6</td><td style="text-align: left">Class <code class="code">regex_error</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">28.7</td><td style="text-align: left">Class template <code class="code">regex_traits</code></td><td style="text-align: left">Partial</td><td style="text-align: left"> </td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">28.8</td><td style="text-align: left">Class template <code class="code">basic_regex</code></td><td style="text-align: left">Partial</td><td style="text-align: left"> </td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">28.9</td><td style="text-align: left">Class template <code class="code">sub_match</code></td><td style="text-align: left">Partial</td><td style="text-align: left"> </td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">28.10</td><td style="text-align: left">Class template <code class="code">match_results</code></td><td style="text-align: left">Partial</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">28.11</td><td style="text-align: left">Regular expression algorithms</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">28.12</td><td style="text-align: left">Regular expression Iterators</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">28.13</td><td style="text-align: left">Modified ECMAScript regular expression grammar</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left"> + <span class="emphasis"><em>29</em></span> + </td><td colspan="3" style="text-align: left"> + <span class="emphasis"><em>Atomic operations</em></span> + </td></tr><tr><td style="text-align: left">29.1</td><td style="text-align: left">General</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">29.2</td><td style="text-align: left">Header <code class="code"><atomic></code> synopsis</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">29.3</td><td style="text-align: left">Order and consistency</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">29.4</td><td style="text-align: left">Lock-free property</td><td style="text-align: left">Partial</td><td style="text-align: left">Missing <code class="code">ATOMIC_BOOL_LOCK_FREE</code> and + <code class="code">ATOMIC_POINTER_LOCK_FREE</code>. + Based on _GLIBCXX_ATOMIC_PROPERTY + </td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">29.5</td><td style="text-align: left">Atomic types</td><td style="text-align: left">Partial</td><td style="text-align: left">Missing constexpr</td></tr><tr><td style="text-align: left">29.6</td><td style="text-align: left">Operations on atomic types</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">29.7</td><td style="text-align: left">Flag Type and operations</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">29.8</td><td style="text-align: left">Fences</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left"> + <span class="emphasis"><em>30</em></span> + </td><td colspan="3" style="text-align: left"> + <span class="emphasis"><em>Thread support</em></span> + </td></tr><tr><td style="text-align: left">30.1</td><td style="text-align: left">General</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">30.2</td><td style="text-align: left">Requirements</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">30.3</td><td style="text-align: left">Threads</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">30.3.1</td><td style="text-align: left">Class <code class="code">thread</code></td><td style="text-align: left">Partial</td><td style="text-align: left"><code class="code">thread::id</code> comparisons not well-defined</td></tr><tr><td style="text-align: left">30.3.2</td><td style="text-align: left">Namespace <code class="code">this_thread</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">30.4</td><td style="text-align: left">Mutual exclusion</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">30.4.1</td><td style="text-align: left">Mutex requirements</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">30.4.1.1</td><td style="text-align: left">In general</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">30.4.1.2</td><td style="text-align: left">Mutex types</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">30.4.1.2.1</td><td style="text-align: left">Class <code class="code">mutex</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">30.4.1.2.2</td><td style="text-align: left">Class <code class="code">recursive_mutex</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">30.4.1.3</td><td style="text-align: left">Timed mutex types</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">30.4.1.3.1</td><td style="text-align: left">Class <code class="code">timed_mutex</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">30.4.1.3.2</td><td style="text-align: left">Class <code class="code">recursive_timed_mutex</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">30.4.2</td><td style="text-align: left">Locks</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">30.4.2.1</td><td style="text-align: left">Class template <code class="code">lock_guard</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">30.4.2.2</td><td style="text-align: left">Class template <code class="code">unique_lock</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">30.4.3</td><td style="text-align: left">Generic locking algorithms</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">30.4.4</td><td style="text-align: left">Call once</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">30.4.4.1</td><td style="text-align: left">Struct <code class="code">once_flag</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">30.4.4.2</td><td style="text-align: left">Function <code class="code">call_once</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">30.5</td><td style="text-align: left">Condition variables</td><td style="text-align: left">Partial</td><td style="text-align: left">Missing notify_all_at_thread_exit</td></tr><tr><td style="text-align: left">30.5.1</td><td style="text-align: left">Class <code class="code">condition_variable</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">30.5.2</td><td style="text-align: left">Class <code class="code">condition_variable_any</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">30.6</td><td style="text-align: left">Futures</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">30.6.1</td><td style="text-align: left">Overview</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">30.6.2</td><td style="text-align: left">Error handling</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">30.6.3</td><td style="text-align: left">Class <code class="code">future_error</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">30.6.4</td><td style="text-align: left">Shared state</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">30.6.5</td><td style="text-align: left">Class template <code class="code">promise</code></td><td style="text-align: left">Partial</td><td style="text-align: left">Missing set_*_at_thread_exit</td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">30.6.6</td><td style="text-align: left">Class template <code class="code">future</code></td><td style="text-align: left">Partial</td><td style="text-align: left">Missing future_status and future::share()</td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">30.6.7</td><td style="text-align: left">Class template <code class="code">shared_future</code></td><td style="text-align: left">Partial</td><td style="text-align: left">Missing future_status</td></tr><tr><td style="text-align: left">30.6.8</td><td style="text-align: left">Function template <code class="code">async</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">30.6.9</td><td style="text-align: left">Class template <code class="code">packaged_task</code></td><td style="text-align: left">Partial</td><td style="text-align: left">Missing make_ready_at_thread_exit</td></tr><tr><td style="text-align: left"> + <span class="emphasis"><em>Appendix D</em></span> + </td><td colspan="3" style="text-align: left"> + <span class="emphasis"><em>Compatibility features</em></span> + </td></tr><tr><td style="text-align: left">D.1</td><td style="text-align: left">Increment operator with <code class="code">bool</code> operand</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">D.2</td><td style="text-align: left"><code class="code">register</code> keyword</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">D.3</td><td style="text-align: left">Implicit declaration of copy functions</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">D.4</td><td style="text-align: left">Dynamic exception specifications</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">D.5</td><td style="text-align: left">C standard library headers</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">D.6</td><td style="text-align: left">Old iostreams members</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">D.7</td><td style="text-align: left"><code class="code">char*</code> streams</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">D.8</td><td style="text-align: left">Function objects</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">D.9</td><td style="text-align: left">Binders</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">D.10</td><td style="text-align: left"><code class="code">auto_ptr</code></td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">D.11</td><td style="text-align: left">Violating exception-specifications</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr></tbody></table></div></div><br class="table-break"/></div><div class="section" title="C++ TR1"><div class="titlepage"><div><div><h3 class="title"><a id="status.iso.tr1"/>C++ TR1</h3></div></div></div><p> +This table is based on the table of contents of ISO/IEC DTR 19768 +Doc No: N1836=05-0096 Date: 2005-06-24 +Draft Technical Report on C++ Library Extensions +</p><p> +In this implementation the header names are prefixed by +<code class="code">tr1/</code>, for instance <code class="code"><tr1/functional></code>, +<code class="code"><tr1/memory></code>, and so on. +</p><p> +This page describes the TR1 support in mainline GCC SVN, not in any particular +release. +</p><div class="table"><a id="id456195"/><p class="title"><strong>Table 1.3. C++ TR1 Implementation Status</strong></p><div class="table-contents"><table summary="C++ TR1 Implementation Status" border="1"><colgroup><col style="text-align: left" class="c1"/><col style="text-align: left" class="c2"/><col style="text-align: left" class="c3"/><col style="text-align: left" class="c4"/></colgroup><thead><tr><th style="text-align: left">Section</th><th style="text-align: left">Description</th><th style="text-align: left">Status</th><th style="text-align: left">Comments</th></tr></thead><tbody><tr><td style="text-align: left"><span class="emphasis"><em>2</em></span></td><td colspan="3" style="text-align: left"><span class="emphasis"><em>General Utilities</em></span></td></tr><tr><td style="text-align: left">2.1</td><td style="text-align: left">Reference wrappers</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">2.1.1</td><td style="text-align: left">Additions to header <code class="code"><functional></code> synopsis</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">2.1.2</td><td style="text-align: left">Class template <code class="code">reference_wrapper</code></td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">2.1.2.1</td><td style="text-align: left"><code class="code">reference_wrapper</code> construct/copy/destroy</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">2.1.2.2</td><td style="text-align: left"><code class="code">reference_wrapper</code> assignment</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">2.1.2.3</td><td style="text-align: left"><code class="code">reference_wrapper</code> access</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">2.1.2.4</td><td style="text-align: left"><code class="code">reference_wrapper</code> invocation</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">2.1.2.5</td><td style="text-align: left"><code class="code">reference_wrapper</code> helper functions</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">2.2</td><td style="text-align: left">Smart pointers</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">2.2.1</td><td style="text-align: left">Additions to header <code class="code"><memory></code> synopsis</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">2.2.2</td><td style="text-align: left">Class <code class="code">bad_weak_ptr</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">2.2.3</td><td style="text-align: left">Class template <code class="code">shared_ptr</code></td><td style="text-align: left"> </td><td style="text-align: left"> + <p> + Uses code from + <a class="link" href="http://www.boost.org/libs/smart_ptr/shared_ptr.htm">boost::shared_ptr</a>. + </p> + </td></tr><tr><td style="text-align: left">2.2.3.1</td><td style="text-align: left"><code class="code">shared_ptr</code> constructors</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">2.2.3.2</td><td style="text-align: left"><code class="code">shared_ptr</code> destructor</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">2.2.3.3</td><td style="text-align: left"><code class="code">shared_ptr</code> assignment</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">2.2.3.4</td><td style="text-align: left"><code class="code">shared_ptr</code> modifiers</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">2.2.3.5</td><td style="text-align: left"><code class="code">shared_ptr</code> observers</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">2.2.3.6</td><td style="text-align: left"><code class="code">shared_ptr</code> comparison</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">2.2.3.7</td><td style="text-align: left"><code class="code">shared_ptr</code> I/O</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">2.2.3.8</td><td style="text-align: left"><code class="code">shared_ptr</code> specialized algorithms</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">2.2.3.9</td><td style="text-align: left"><code class="code">shared_ptr</code> casts</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">2.2.3.10</td><td style="text-align: left"><code class="code">get_deleter</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">2.2.4</td><td style="text-align: left">Class template <code class="code">weak_ptr</code></td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">2.2.4.1</td><td style="text-align: left"><code class="code">weak_ptr</code> constructors</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">2.2.4.2</td><td style="text-align: left"><code class="code">weak_ptr</code> destructor</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">2.2.4.3</td><td style="text-align: left"><code class="code">weak_ptr</code> assignment</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">2.2.4.4</td><td style="text-align: left"><code class="code">weak_ptr</code> modifiers</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">2.2.4.5</td><td style="text-align: left"><code class="code">weak_ptr</code> observers</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">2.2.4.6</td><td style="text-align: left"><code class="code">weak_ptr</code> comparison</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">2.2.4.7</td><td style="text-align: left"><code class="code">weak_ptr</code> specialized algorithms</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">2.2.5</td><td style="text-align: left">Class template <code class="code">enable_shared_from_this</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left"><span class="emphasis"><em>3</em></span></td><td colspan="3" style="text-align: left"><span class="emphasis"><em>Function Objects</em></span></td></tr><tr><td style="text-align: left">3.1</td><td style="text-align: left">Definitions</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.2</td><td style="text-align: left">Additions to <code class="code"><functional> synopsis</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.3</td><td style="text-align: left">Requirements</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.4</td><td style="text-align: left">Function return types</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.5</td><td style="text-align: left">Function template <code class="code">mem_fn</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.6</td><td style="text-align: left">Function object binders</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.6.1</td><td style="text-align: left">Class template <code class="code">is_bind_expression</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.6.2</td><td style="text-align: left">Class template <code class="code">is_placeholder</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.6.3</td><td style="text-align: left">Function template <code class="code">bind</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.6.4</td><td style="text-align: left">Placeholders</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.7</td><td style="text-align: left">Polymorphic function wrappers</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.7.1</td><td style="text-align: left">Class <code class="code">bad_function_call</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.7.1.1</td><td style="text-align: left"><code class="code">bad_function_call</code> constructor</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.7.2</td><td style="text-align: left">Class template <code class="code">function</code></td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.7.2.1</td><td style="text-align: left"><code class="code">function</code> construct/copy/destroy</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.7.2.2</td><td style="text-align: left"><code class="code">function</code> modifiers</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.7.2.3</td><td style="text-align: left"><code class="code">function</code> capacity</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.7.2.4</td><td style="text-align: left"><code class="code">function</code> invocation</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.7.2.5</td><td style="text-align: left"><code class="code">function</code> target access</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.7.2.6</td><td style="text-align: left">undefined operators</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.7.2.7</td><td style="text-align: left">null pointer comparison operators</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.7.2.8</td><td style="text-align: left">specialized algorithms</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left"><span class="emphasis"><em>4</em></span></td><td colspan="3" style="text-align: left"><span class="emphasis"><em>Metaprogramming and type traits</em></span></td></tr><tr><td style="text-align: left">4.1</td><td style="text-align: left">Requirements</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">4.2</td><td style="text-align: left">Header <code class="code"><type_traits></code> synopsis</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">4.3</td><td style="text-align: left">Helper classes</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">4.4</td><td style="text-align: left">General Requirements</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">4.5</td><td style="text-align: left">Unary Type Traits</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">4.5.1</td><td style="text-align: left">Primary Type Categories</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">4.5.2</td><td style="text-align: left">Composite type traits</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">4.5.3</td><td style="text-align: left">Type properties</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">4.6</td><td style="text-align: left">Relationships between types</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">4.7</td><td style="text-align: left">Transformations between types</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">4.7.1</td><td style="text-align: left">Const-volatile modifications</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">4.7.2</td><td style="text-align: left">Reference modifications</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">4.7.3</td><td style="text-align: left">Array modifications</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">4.7.4</td><td style="text-align: left">Pointer modifications</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">4.8</td><td style="text-align: left">Other transformations</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">4.9</td><td style="text-align: left">Implementation requirements</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left"><span class="emphasis"><em>5</em></span></td><td colspan="3" style="text-align: left"><span class="emphasis"><em>Numerical Facilities</em></span></td></tr><tr><td style="text-align: left">5.1</td><td style="text-align: left">Random number generation</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.1.1</td><td style="text-align: left">Requirements</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.1.2</td><td style="text-align: left">Header <code class="code"><random></code> synopsis</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.1.3</td><td style="text-align: left">Class template <code class="code">variate_generator</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.1.4</td><td style="text-align: left">Random number engine class templates</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.1.4.1</td><td style="text-align: left">Class template <code class="code">linear_congruential</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.1.4.2</td><td style="text-align: left">Class template <code class="code">mersenne_twister</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.1.4.3</td><td style="text-align: left">Class template <code class="code">subtract_with_carry</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.1.4.4</td><td style="text-align: left">Class template <code class="code">subtract_with_carry_01</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.1.4.5</td><td style="text-align: left">Class template <code class="code">discard_block</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.1.4.6</td><td style="text-align: left">Class template <code class="code">xor_combine</code></td><td style="text-align: left">Y</td><td style="text-align: left">operator()() per N2079</td></tr><tr><td style="text-align: left">5.1.5</td><td style="text-align: left">Engines with predefined parameters</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.1.6</td><td style="text-align: left">Class <code class="code">random_device</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.1.7</td><td style="text-align: left">Random distribution class templates</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.1.7.1</td><td style="text-align: left">Class template <code class="code">uniform_int</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.1.7.2</td><td style="text-align: left">Class <code class="code">bernoulli_distribution</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.1.7.3</td><td style="text-align: left">Class template <code class="code">geometric_distribution</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.1.7.4</td><td style="text-align: left">Class template <code class="code">poisson_distribution</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.1.7.5</td><td style="text-align: left">Class template <code class="code">binomial_distribution</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.1.7.6</td><td style="text-align: left">Class template <code class="code">uniform_real</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.1.7.7</td><td style="text-align: left">Class template <code class="code">exponential_distribution</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.1.7.8</td><td style="text-align: left">Class template <code class="code">normal_distribution</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.1.7.9</td><td style="text-align: left">Class template <code class="code">gamma_distribution</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.2</td><td style="text-align: left">Mathematical special functions</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.2.1</td><td style="text-align: left">Additions to header <code class="code"><cmath></code> synopsis</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.2.1.1</td><td style="text-align: left">associated Laguerre polynomials</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.2.1.2</td><td style="text-align: left">associated Legendre functions</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.2.1.3</td><td style="text-align: left">beta function</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.2.1.4</td><td style="text-align: left">(complete) elliptic integral of the first kind</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.2.1.5</td><td style="text-align: left">(complete) elliptic integral of the second kind</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.2.1.6</td><td style="text-align: left">(complete) elliptic integral of the third kind</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.2.1.7</td><td style="text-align: left">confluent hypergeometric functions</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.2.1.8</td><td style="text-align: left">regular modified cylindrical Bessel functions</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.2.1.9</td><td style="text-align: left">cylindrical Bessel functions (of the first kind)</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.2.1.10</td><td style="text-align: left">irregular modified cylindrical Bessel functions</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.2.1.11</td><td style="text-align: left">cylindrical Neumann functions</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.2.1.12</td><td style="text-align: left">(incomplete) elliptic integral of the first kind</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.2.1.13</td><td style="text-align: left">(incomplete) elliptic integral of the second kind</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.2.1.14</td><td style="text-align: left">(incomplete) elliptic integral of the third kind</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.2.1.15</td><td style="text-align: left">exponential integral</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.2.1.16</td><td style="text-align: left">Hermite polynomials</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.2.1.17</td><td style="text-align: left">hypergeometric functions</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.2.1.18</td><td style="text-align: left">Laguerre polynomials</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.2.1.19</td><td style="text-align: left">Legendre polynomials</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.2.1.20</td><td style="text-align: left">Riemann zeta function</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.2.1.21</td><td style="text-align: left">spherical Bessel functions (of the first kind)</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.2.1.22</td><td style="text-align: left">spherical associated Legendre functions</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.2.1.23</td><td style="text-align: left">spherical Neumann functions</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">5.2.2</td><td style="text-align: left">Additions to header <code class="code"><math.h></code> synopsis</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left"><span class="emphasis"><em>6</em></span></td><td colspan="3" style="text-align: left"><span class="emphasis"><em>Containers</em></span></td></tr><tr><td style="text-align: left">6.1</td><td style="text-align: left">Tuple types</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.1.1</td><td style="text-align: left">Header <code class="code"><tuple></code> synopsis</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.1.2</td><td style="text-align: left">Additions to header <code class="code"><utility></code> synopsis</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.1.3</td><td style="text-align: left">Class template <code class="code">tuple</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.1.3.1</td><td style="text-align: left">Construction</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.1.3.2</td><td style="text-align: left">Tuple creation functions</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.1.3.3</td><td style="text-align: left">Tuple helper classes</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.1.3.4</td><td style="text-align: left">Element access</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.1.3.5</td><td style="text-align: left">Relational operators</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.1.4</td><td style="text-align: left">Pairs</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.2</td><td style="text-align: left">Fixed size array</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.2.1</td><td style="text-align: left">Header <code class="code"><array></code> synopsis</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.2.2</td><td style="text-align: left">Class template <code class="code">array</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.2.2.1</td><td style="text-align: left"><code class="code">array</code> constructors, copy, and assignment</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.2.2.2</td><td style="text-align: left"><code class="code">array</code> specialized algorithms</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.2.2.3</td><td style="text-align: left"><code class="code">array</code> size</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.2.2.4</td><td style="text-align: left">Zero sized <code class="code">array</code>s</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.2.2.5</td><td style="text-align: left">Tuple interface to class template <code class="code">array</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.3</td><td style="text-align: left">Unordered associative containers</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.3.1</td><td style="text-align: left">Unordered associative container requirements</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.3.1.1</td><td style="text-align: left">Exception safety guarantees</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.3.2</td><td style="text-align: left">Additions to header <code class="code"><functional></code> synopsis</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.3.3</td><td style="text-align: left">Class template <code class="code">hash</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.3.4</td><td style="text-align: left">Unordered associative container classes</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.3.4.1</td><td style="text-align: left">Header <code class="code"><unordered_set></code> synopsis</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.3.4.2</td><td style="text-align: left">Header <code class="code"><unordered_map></code> synopsis</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.3.4.3</td><td style="text-align: left">Class template <code class="code">unordered_set</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.3.4.3.1</td><td style="text-align: left"><code class="code">unordered_set</code> constructors</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.3.4.3.2</td><td style="text-align: left"><code class="code">unordered_set</code> swap</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.3.4.4</td><td style="text-align: left">Class template <code class="code">unordered_map</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.3.4.4.1</td><td style="text-align: left"><code class="code">unordered_map</code> constructors</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.3.4.4.2</td><td style="text-align: left"><code class="code">unordered_map</code> element access</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.3.4.4.3</td><td style="text-align: left"><code class="code">unordered_map</code> swap</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.3.4.5</td><td style="text-align: left">Class template <code class="code">unordered_multiset</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.3.4.5.1</td><td style="text-align: left"><code class="code">unordered_multiset</code> constructors</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.3.4.5.2</td><td style="text-align: left"><code class="code">unordered_multiset</code> swap</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.3.4.6</td><td style="text-align: left">Class template <code class="code">unordered_multimap</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.3.4.6.1</td><td style="text-align: left"><code class="code">unordered_multimap</code> constructors</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">6.3.4.6.2</td><td style="text-align: left"><code class="code">unordered_multimap</code> swap</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left"><span class="emphasis"><em>7</em></span></td><td colspan="3" style="text-align: left"><span class="emphasis"><em>Regular Expressions</em></span></td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.1</td><td style="text-align: left">Definitions</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.2</td><td style="text-align: left">Requirements</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.3</td><td style="text-align: left">Regular expressions summary</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.4</td><td style="text-align: left">Header <code class="code"><regex></code> synopsis</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.5</td><td style="text-align: left">Namespace <code class="code">tr1::regex_constants</code></td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.5.1</td><td style="text-align: left">Bitmask Type <code class="code">syntax_option_type</code></td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.5.2</td><td style="text-align: left">Bitmask Type <code class="code">regex_constants::match_flag_type</code></td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.5.3</td><td style="text-align: left">Implementation defined <code class="code">error_type</code></td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.6</td><td style="text-align: left">Class <code class="code">regex_error</code></td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.7</td><td style="text-align: left">Class template <code class="code">regex_traits</code></td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.8</td><td style="text-align: left">Class template <code class="code">basic_regex</code></td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.8.1</td><td style="text-align: left"><code class="code">basic_regex</code> constants</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.8.2</td><td style="text-align: left"><code class="code">basic_regex</code> constructors</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.8.3</td><td style="text-align: left"><code class="code">basic_regex</code> assign</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.8.4</td><td style="text-align: left"><code class="code">basic_regex</code> constant operations</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.8.5</td><td style="text-align: left"><code class="code">basic_regex</code> locale</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.8.6</td><td style="text-align: left"><code class="code">basic_regex</code> swap</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.8.7</td><td style="text-align: left"><code class="code">basic_regex</code> non-member functions</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.8.7.1</td><td style="text-align: left"><code class="code">basic_regex</code> non-member swap</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.9</td><td style="text-align: left">Class template <code class="code">sub_match</code></td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.9.1</td><td style="text-align: left"><code class="code">sub_match</code> members</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.9.2</td><td style="text-align: left"><code class="code">sub_match</code> non-member operators</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.10</td><td style="text-align: left">Class template <code class="code">match_results</code></td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.10.1</td><td style="text-align: left"><code class="code">match_results</code> constructors</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.10.2</td><td style="text-align: left"><code class="code">match_results</code> size</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.10.3</td><td style="text-align: left"><code class="code">match_results</code> element access</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.10.4</td><td style="text-align: left"><code class="code">match_results</code> formatting</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.10.5</td><td style="text-align: left"><code class="code">match_results</code> allocator</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.10.6</td><td style="text-align: left"><code class="code">match_results</code> swap</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.11</td><td style="text-align: left">Regular expression algorithms</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.11.1</td><td style="text-align: left">exceptions</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.11.2</td><td style="text-align: left"><code class="code">regex_match</code></td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.11.3</td><td style="text-align: left"><code class="code">regex_search</code></td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.11.4</td><td style="text-align: left"><code class="code">regex_replace</code></td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.12</td><td style="text-align: left">Regular expression Iterators</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.12.1</td><td style="text-align: left">Class template <code class="code">regex_iterator</code></td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.12.1.1</td><td style="text-align: left"><code class="code">regex_iterator</code> constructors</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.12.1.2</td><td style="text-align: left"><code class="code">regex_iterator</code> comparisons</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.12.1.3</td><td style="text-align: left"><code class="code">regex_iterator</code> dereference</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.12.1.4</td><td style="text-align: left"><code class="code">regex_iterator</code> increment</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.12.2</td><td style="text-align: left">Class template <code class="code">regex_token_iterator</code></td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.12.2.1</td><td style="text-align: left"><code class="code">regex_token_iterator</code> constructors</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.12.2.2</td><td style="text-align: left"><code class="code">regex_token_iterator</code> comparisons</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.12.2.3</td><td style="text-align: left"><code class="code">regex_token_iterator</code> dereference</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.12.2.4</td><td style="text-align: left"><code class="code">regex_token_iterator</code> increment</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">7.13</td><td style="text-align: left">Modified ECMAScript regular expression grammar</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left"><span class="emphasis"><em>8</em></span></td><td colspan="3" style="text-align: left"><span class="emphasis"><em>C Compatibility</em></span></td></tr><tr><td style="text-align: left">8.1</td><td style="text-align: left">Additions to header <code class="code"><complex></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.1.1</td><td style="text-align: left">Synopsis</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.1.2</td><td style="text-align: left">Function <code class="code">acos</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.1.3</td><td style="text-align: left">Function <code class="code">asin</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.1.4</td><td style="text-align: left">Function <code class="code">atan</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.1.5</td><td style="text-align: left">Function <code class="code">acosh</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.1.6</td><td style="text-align: left">Function <code class="code">asinh</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.1.7</td><td style="text-align: left">Function <code class="code">atanh</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.1.8</td><td style="text-align: left">Function <code class="code">fabs</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.1.9</td><td style="text-align: left">Additional Overloads</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">8.2</td><td style="text-align: left">Header <code class="code"><ccomplex></code></td><td style="text-align: left">N</td><td style="text-align: left">DR 551</td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">8.3</td><td style="text-align: left">Header <code class="code"><complex.h></code></td><td style="text-align: left">N</td><td style="text-align: left">DR 551</td></tr><tr><td style="text-align: left">8.4</td><td style="text-align: left">Additions to header <code class="code"><cctype></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.4.1</td><td style="text-align: left">Synopsis</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.4.2</td><td style="text-align: left">Function <code class="code">isblank</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.5</td><td style="text-align: left">Additions to header <code class="code"><ctype.h></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.6</td><td style="text-align: left">Header <code class="code"><cfenv></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.6.1</td><td style="text-align: left">Synopsis</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.6.2</td><td style="text-align: left">Definitions</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.7</td><td style="text-align: left">Header <code class="code"><fenv.h></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.8</td><td style="text-align: left">Additions to header <code class="code"><cfloat></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.9</td><td style="text-align: left">Additions to header <code class="code"><float.h></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">8.10</td><td style="text-align: left">Additions to header <code class="code"><ios></code></td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">8.10.1</td><td style="text-align: left">Synopsis</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">8.10.2</td><td style="text-align: left">Function <code class="code">hexfloat</code></td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.11</td><td style="text-align: left">Header <code class="code"><cinttypes></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.11.1</td><td style="text-align: left">Synopsis</td><td style="text-align: left">Y</td><td style="text-align: left">DR 557</td></tr><tr><td style="text-align: left">8.11.2</td><td style="text-align: left">Definitions</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.12</td><td style="text-align: left">Header <code class="code"><inttypes.h></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.13</td><td style="text-align: left">Additions to header <code class="code"><climits></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.14</td><td style="text-align: left">Additions to header <code class="code"><limits.h></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">8.15</td><td style="text-align: left">Additions to header <code class="code"><locale></code></td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.16</td><td style="text-align: left">Additions to header <code class="code"><cmath></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.16.1</td><td style="text-align: left">Synopsis</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.16.2</td><td style="text-align: left">Definitions</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.16.3</td><td style="text-align: left">Function template definitions</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.16.4</td><td style="text-align: left">Additional overloads</td><td style="text-align: left">Y</td><td style="text-align: left">DR 568; DR 550</td></tr><tr><td style="text-align: left">8.17</td><td style="text-align: left">Additions to header <code class="code"><math.h></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.18</td><td style="text-align: left">Additions to header <code class="code"><cstdarg></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.19</td><td style="text-align: left">Additions to header <code class="code"><stdarg.h></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.20</td><td style="text-align: left">The header <code class="code"><cstdbool></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.21</td><td style="text-align: left">The header <code class="code"><stdbool.h></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.22</td><td style="text-align: left">The header <code class="code"><cstdint></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.22.1</td><td style="text-align: left">Synopsis</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.22.2</td><td style="text-align: left">Definitions</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.23</td><td style="text-align: left">The header <code class="code"><stdint.h></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.24</td><td style="text-align: left">Additions to header <code class="code"><cstdio></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.24.1</td><td style="text-align: left">Synopsis</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.24.2</td><td style="text-align: left">Definitions</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.24.3</td><td style="text-align: left">Additional format specifiers</td><td style="text-align: left">Y</td><td style="text-align: left">C library dependency</td></tr><tr><td style="text-align: left">8.24.4</td><td style="text-align: left">Additions to header <code class="code"><stdio.h></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.25</td><td style="text-align: left">Additions to header <code class="code"><cstdlib></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.25.1</td><td style="text-align: left">Synopsis</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.25.2</td><td style="text-align: left">Definitions</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.25.3</td><td style="text-align: left">Function <code class="code">abs</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.25.4</td><td style="text-align: left">Function <code class="code">div</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.26</td><td style="text-align: left">Additions to header <code class="code"><stdlib.h></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.27</td><td style="text-align: left">Header <code class="code"><ctgmath></code></td><td style="text-align: left">Y</td><td style="text-align: left">DR 551</td></tr><tr><td style="text-align: left">8.28</td><td style="text-align: left">Header <code class="code"><tgmath.h></code></td><td style="text-align: left">Y</td><td style="text-align: left">DR 551</td></tr><tr><td style="text-align: left">8.29</td><td style="text-align: left">Additions to header <code class="code"><ctime></code></td><td style="text-align: left">Y</td><td style="text-align: left">C library dependency</td></tr><tr><td style="text-align: left">8.30</td><td style="text-align: left">Additions to header <code class="code"><cwchar></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.30.1</td><td style="text-align: left">Synopsis</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.30.2</td><td style="text-align: left">Definitions</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.30.3</td><td style="text-align: left">Additional wide format specifiers</td><td style="text-align: left">Y</td><td style="text-align: left">C library dependency</td></tr><tr><td style="text-align: left">8.31</td><td style="text-align: left">Additions to header <code class="code"><wchar.h></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.32</td><td style="text-align: left">Additions to header <code class="code"><cwctype></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.32.1</td><td style="text-align: left">Synopsis</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.32.2</td><td style="text-align: left">Function <code class="code">iswblank</code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">8.33</td><td style="text-align: left">Additions to header <code class="code"><wctype.h></code></td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr></tbody></table></div></div><br class="table-break"/></div><div class="section" title="C++ TR 24733"><div class="titlepage"><div><div><h3 class="title"><a id="status.iso.tr24733"/>C++ TR 24733</h3></div></div></div><p> +This table is based on the table of contents of +ISO/IEC TR 24733 Date: 2009-08-28 +Extension for the programming language C++ to support +decimal floating-point arithmetic +</p><p> +This page describes the TR 24733 support in mainline GCC SVN, not in any +particular release. +</p><div class="table"><a id="id461766"/><p class="title"><strong>Table 1.4. C++ TR 24733 Implementation Status</strong></p><div class="table-contents"><table summary="C++ TR 24733 Implementation Status" border="1"><colgroup><col style="text-align: left" class="c1"/><col style="text-align: left" class="c2"/><col style="text-align: left" class="c3"/><col style="text-align: left" class="c4"/></colgroup><thead><tr><th style="text-align: left">Section</th><th style="text-align: left">Description</th><th style="text-align: left">Status</th><th style="text-align: left">Comments</th></tr></thead><tbody><tr><td style="text-align: left"> + <span class="emphasis"><em>0</em></span> + </td><td colspan="3" style="text-align: left"> + <span class="emphasis"><em>Introduction</em></span> + </td></tr><tr><td style="text-align: left"> + <span class="emphasis"><em>1</em></span> + </td><td colspan="3" style="text-align: left"> + <span class="emphasis"><em>Normative references</em></span> + </td></tr><tr><td style="text-align: left"> + <span class="emphasis"><em>2</em></span> + </td><td colspan="3" style="text-align: left"> + <span class="emphasis"><em>Conventions</em></span> + </td></tr><tr><td style="text-align: left"> + <span class="emphasis"><em>3</em></span> + </td><td colspan="3" style="text-align: left"> + <span class="emphasis"><em>Decimal floating-point types</em></span> + </td></tr><tr><td style="text-align: left">3.1</td><td style="text-align: left">Characteristics of decimal floating-point types</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.2</td><td style="text-align: left">Decimal Types</td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">3.2.1</td><td style="text-align: left">Class <code class="code">decimal</code> synopsis</td><td style="text-align: left">Partial</td><td style="text-align: left">Missing declarations for formatted input/output; non-conforming extension for functions converting to integral type</td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">3.2.2</td><td style="text-align: left">Class <code class="code">decimal32</code></td><td style="text-align: left">Partial</td><td style="text-align: left">Missing 3.2.2.5 conversion to integral type; conforming extension for conversion from scalar decimal floating-point</td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">3.2.3</td><td style="text-align: left">Class <code class="code">decimal64</code></td><td style="text-align: left">Partial</td><td style="text-align: left">Missing 3.2.3.5 conversion to integral type; conforming extension for conversion from scalar decimal floating-point</td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">3.2.4</td><td style="text-align: left">Class <code class="code">decimal128</code></td><td style="text-align: left">Partial</td><td style="text-align: left">Missing 3.2.4.5 conversion to integral type; conforming extension for conversion from scalar decimal floating-point</td></tr><tr><td style="text-align: left">3.2.5</td><td style="text-align: left">Initialization from coefficient and exponent</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.2.6</td><td style="text-align: left">Conversion to generic floating-point type</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.2.7</td><td style="text-align: left">Unary arithmetic operators</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.2.8</td><td style="text-align: left">Binary arithmetic operators</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.2.9</td><td style="text-align: left">Comparison operators</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">3.2.10</td><td style="text-align: left">Formatted input</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">3.2.11</td><td style="text-align: left">Formatted output</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">3.3</td><td style="text-align: left">Additions to header <code class="code">limits</code></td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.4</td><td style="text-align: left">Headers <code class="code">cfloat</code> and <code class="code">float.h</code></td><td style="text-align: left"> </td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.4.2</td><td style="text-align: left">Additions to header <code class="code">cfloat</code> synopsis</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #B0B0B0"><td style="text-align: left">3.4.3</td><td style="text-align: left">Additions to header <code class="code">float.h</code> synopsis</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.4.4</td><td style="text-align: left">Maximum finite value</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.4.5</td><td style="text-align: left">Epsilon</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.4.6</td><td style="text-align: left">Minimum positive normal value</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.4.7</td><td style="text-align: left">Minimum positive subnormal value</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left">3.4.8</td><td style="text-align: left">Evaluation format</td><td style="text-align: left">Y</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">3.5</td><td style="text-align: left">Additions to <code class="code">cfenv</code> and <code class="code">fenv.h</code></td><td style="text-align: left">Outside the scope of GCC</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">3.6</td><td style="text-align: left">Additions to <code class="code">cmath</code> and <code class="code">math.h</code></td><td style="text-align: left">Outside the scope of GCC</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">3.7</td><td style="text-align: left">Additions to <code class="code">cstdio</code> and <code class="code">stdio.h</code></td><td style="text-align: left">Outside the scope of GCC</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">3.8</td><td style="text-align: left">Additions to <code class="code">cstdlib</code> and <code class="code">stdlib.h</code></td><td style="text-align: left">Outside the scope of GCC</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">3.9</td><td style="text-align: left">Additions to <code class="code">cwchar</code> and <code class="code">wchar.h</code></td><td style="text-align: left">Outside the scope of GCC</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">3.10</td><td style="text-align: left">Facets</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">3.11</td><td style="text-align: left">Type traits</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr style="background-color: #C8B0B0"><td style="text-align: left">3.12</td><td style="text-align: left">Hash functions</td><td style="text-align: left">N</td><td style="text-align: left"> </td></tr><tr><td style="text-align: left"> + <span class="emphasis"><em>4</em></span> + </td><td colspan="3" style="text-align: left"> + <span class="emphasis"><em>Notes on C compatibility</em></span> + </td></tr></tbody></table></div></div><br class="table-break"/></div></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="intro.html">Prev</a> </td><td align="center"><a accesskey="u" href="intro.html">Up</a></td><td align="right"> <a accesskey="n" href="license.html">Next</a></td></tr><tr><td align="left" valign="top">Part I. + Introduction + + </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> License</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/streambufs.html b/libstdc++-v3/doc/html/manual/streambufs.html new file mode 100644 index 000000000..92c148dfc --- /dev/null +++ b/libstdc++-v3/doc/html/manual/streambufs.html @@ -0,0 +1,137 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Stream Buffers</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="io.html" title="Chapter 13. Input and Output"/><link rel="prev" href="io.html" title="Chapter 13. Input and Output"/><link rel="next" href="stringstreams.html" title="Memory Based Streams"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Stream Buffers</th></tr><tr><td align="left"><a accesskey="p" href="io.html">Prev</a> </td><th width="60%" align="center">Chapter 13. + Input and Output + +</th><td align="right"> <a accesskey="n" href="stringstreams.html">Next</a></td></tr></table><hr/></div><div class="section" title="Stream Buffers"><div class="titlepage"><div><div><h2 class="title"><a id="std.io.streambufs"/>Stream Buffers</h2></div></div></div><div class="section" title="Derived streambuf Classes"><div class="titlepage"><div><div><h3 class="title"><a id="io.streambuf.derived"/>Derived streambuf Classes</h3></div></div></div><p> + </p><p>Creating your own stream buffers for I/O can be remarkably easy. + If you are interested in doing so, we highly recommend two very + excellent books: + <a class="link" href="http://www.angelikalanger.com/iostreams.html">Standard C++ + IOStreams and Locales</a> by Langer and Kreft, ISBN 0-201-18395-1, and + <a class="link" href="http://www.josuttis.com/libbook/">The C++ Standard Library</a> + by Nicolai Josuttis, ISBN 0-201-37926-0. Both are published by + Addison-Wesley, who isn't paying us a cent for saying that, honest. + </p><p>Here is a simple example, io/outbuf1, from the Josuttis text. It + transforms everything sent through it to uppercase. This version + assumes many things about the nature of the character type being + used (for more information, read the books or the newsgroups): + </p><pre class="programlisting"> + #include <iostream> + #include <streambuf> + #include <locale> + #include <cstdio> + + class outbuf : public std::streambuf + { + protected: + /* central output function + * - print characters in uppercase mode + */ + virtual int_type overflow (int_type c) { + if (c != EOF) { + // convert lowercase to uppercase + c = std::toupper(static_cast<char>(c),getloc()); + + // and write the character to the standard output + if (putchar(c) == EOF) { + return EOF; + } + } + return c; + } + }; + + int main() + { + // create special output buffer + outbuf ob; + // initialize output stream with that output buffer + std::ostream out(&ob); + + out << "31 hexadecimal: " + << std::hex << 31 << std::endl; + return 0; + } + </pre><p>Try it yourself! More examples can be found in 3.1.x code, in + <code class="code">include/ext/*_filebuf.h</code>, and in this article by James Kanze: + <a class="link" href="http://kanze.james.neuf.fr/articles/fltrsbf1.html">Filtering + Streambufs</a>. + </p></div><div class="section" title="Buffering"><div class="titlepage"><div><div><h3 class="title"><a id="io.streambuf.buffering"/>Buffering</h3></div></div></div><p>First, are you sure that you understand buffering? Particularly + the fact that C++ may not, in fact, have anything to do with it? + </p><p>The rules for buffering can be a little odd, but they aren't any + different from those of C. (Maybe that's why they can be a bit + odd.) Many people think that writing a newline to an output + stream automatically flushes the output buffer. This is true only + when the output stream is, in fact, a terminal and not a file + or some other device -- and <span class="emphasis"><em>that</em></span> may not even be true + since C++ says nothing about files nor terminals. All of that is + system-dependent. (The "newline-buffer-flushing only occurring + on terminals" thing is mostly true on Unix systems, though.) + </p><p>Some people also believe that sending <code class="code">endl</code> down an + output stream only writes a newline. This is incorrect; after a + newline is written, the buffer is also flushed. Perhaps this + is the effect you want when writing to a screen -- get the text + out as soon as possible, etc -- but the buffering is largely + wasted when doing this to a file: + </p><pre class="programlisting"> + output << "a line of text" << endl; + output << some_data_variable << endl; + output << "another line of text" << endl; </pre><p>The proper thing to do in this case to just write the data out + and let the libraries and the system worry about the buffering. + If you need a newline, just write a newline: + </p><pre class="programlisting"> + output << "a line of text\n" + << some_data_variable << '\n' + << "another line of text\n"; </pre><p>I have also joined the output statements into a single statement. + You could make the code prettier by moving the single newline to + the start of the quoted text on the last line, for example. + </p><p>If you do need to flush the buffer above, you can send an + <code class="code">endl</code> if you also need a newline, or just flush the buffer + yourself: + </p><pre class="programlisting"> + output << ...... << flush; // can use std::flush manipulator + output.flush(); // or call a member fn </pre><p>On the other hand, there are times when writing to a file should + be like writing to standard error; no buffering should be done + because the data needs to appear quickly (a prime example is a + log file for security-related information). The way to do this is + just to turn off the buffering <span class="emphasis"><em>before any I/O operations at + all</em></span> have been done (note that opening counts as an I/O operation): + </p><pre class="programlisting"> + std::ofstream os; + std::ifstream is; + int i; + + os.rdbuf()->pubsetbuf(0,0); + is.rdbuf()->pubsetbuf(0,0); + + os.open("/foo/bar/baz"); + is.open("/qux/quux/quuux"); + ... + os << "this data is written immediately\n"; + is >> i; // and this will probably cause a disk read </pre><p>Since all aspects of buffering are handled by a streambuf-derived + member, it is necessary to get at that member with <code class="code">rdbuf()</code>. + Then the public version of <code class="code">setbuf</code> can be called. The + arguments are the same as those for the Standard C I/O Library + function (a buffer area followed by its size). + </p><p>A great deal of this is implementation-dependent. For example, + <code class="code">streambuf</code> does not specify any actions for its own + <code class="code">setbuf()</code>-ish functions; the classes derived from + <code class="code">streambuf</code> each define behavior that "makes + sense" for that class: an argument of (0,0) turns off buffering + for <code class="code">filebuf</code> but does nothing at all for its siblings + <code class="code">stringbuf</code> and <code class="code">strstreambuf</code>, and specifying + anything other than (0,0) has varying effects. + User-defined classes derived from <code class="code">streambuf</code> can + do whatever they want. (For <code class="code">filebuf</code> and arguments for + <code class="code">(p,s)</code> other than zeros, libstdc++ does what you'd expect: + the first <code class="code">s</code> bytes of <code class="code">p</code> are used as a buffer, + which you must allocate and deallocate.) + </p><p>A last reminder: there are usually more buffers involved than + just those at the language/library level. Kernel buffers, disk + buffers, and the like will also have an effect. Inspecting and + changing those are system-dependent. + </p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="io.html">Prev</a> </td><td align="center"><a accesskey="u" href="io.html">Up</a></td><td align="right"> <a accesskey="n" href="stringstreams.html">Next</a></td></tr><tr><td align="left" valign="top">Chapter 13. + Input and Output + + </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Memory Based Streams</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/strings.html b/libstdc++-v3/doc/html/manual/strings.html new file mode 100644 index 000000000..a70edcdb8 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/strings.html @@ -0,0 +1,366 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Chapter 7. Strings</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="bk01pt02.html" title="Part II. Standard Contents"/><link rel="prev" href="traits.html" title="Traits"/><link rel="next" href="localization.html" title="Chapter 8. Localization"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 7. + Strings + +</th></tr><tr><td align="left"><a accesskey="p" href="traits.html">Prev</a> </td><th width="60%" align="center">Part II. + Standard Contents + </th><td align="right"> <a accesskey="n" href="localization.html">Next</a></td></tr></table><hr/></div><div class="chapter" title="Chapter 7. Strings"><div class="titlepage"><div><div><h2 class="title"><a id="std.strings"/>Chapter 7. + Strings + <a id="id475084" class="indexterm"/> +</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="strings.html#std.strings.string">String Classes</a></span></dt><dd><dl><dt><span class="section"><a href="strings.html#strings.string.simple">Simple Transformations</a></span></dt><dt><span class="section"><a href="strings.html#strings.string.case">Case Sensitivity</a></span></dt><dt><span class="section"><a href="strings.html#strings.string.character_types">Arbitrary Character Types</a></span></dt><dt><span class="section"><a href="strings.html#strings.string.token">Tokenizing</a></span></dt><dt><span class="section"><a href="strings.html#strings.string.shrink">Shrink to Fit</a></span></dt><dt><span class="section"><a href="strings.html#strings.string.Cstring">CString (MFC)</a></span></dt></dl></dd></dl></div><div class="section" title="String Classes"><div class="titlepage"><div><div><h2 class="title"><a id="std.strings.string"/>String Classes</h2></div></div></div><div class="section" title="Simple Transformations"><div class="titlepage"><div><div><h3 class="title"><a id="strings.string.simple"/>Simple Transformations</h3></div></div></div><p> + Here are Standard, simple, and portable ways to perform common + transformations on a <code class="code">string</code> instance, such as + "convert to all upper case." The word transformations + is especially apt, because the standard template function + <code class="code">transform<></code> is used. + </p><p> + This code will go through some iterations. Here's a simple + version: + </p><pre class="programlisting"> + #include <string> + #include <algorithm> + #include <cctype> // old <ctype.h> + + struct ToLower + { + char operator() (char c) const { return std::tolower(c); } + }; + + struct ToUpper + { + char operator() (char c) const { return std::toupper(c); } + }; + + int main() + { + std::string s ("Some Kind Of Initial Input Goes Here"); + + // Change everything into upper case + std::transform (s.begin(), s.end(), s.begin(), ToUpper()); + + // Change everything into lower case + std::transform (s.begin(), s.end(), s.begin(), ToLower()); + + // Change everything back into upper case, but store the + // result in a different string + std::string capital_s; + capital_s.resize(s.size()); + std::transform (s.begin(), s.end(), capital_s.begin(), ToUpper()); + } + </pre><p> + <span class="emphasis"><em>Note</em></span> that these calls all + involve the global C locale through the use of the C functions + <code class="code">toupper/tolower</code>. This is absolutely guaranteed to work -- + but <span class="emphasis"><em>only</em></span> if the string contains <span class="emphasis"><em>only</em></span> characters + from the basic source character set, and there are <span class="emphasis"><em>only</em></span> + 96 of those. Which means that not even all English text can be + represented (certain British spellings, proper names, and so forth). + So, if all your input forevermore consists of only those 96 + characters (hahahahahaha), then you're done. + </p><p><span class="emphasis"><em>Note</em></span> that the + <code class="code">ToUpper</code> and <code class="code">ToLower</code> function objects + are needed because <code class="code">toupper</code> and <code class="code">tolower</code> + are overloaded names (declared in <code class="code"><cctype></code> and + <code class="code"><locale></code>) so the template-arguments for + <code class="code">transform<></code> cannot be deduced, as explained in + <a class="link" href="http://gcc.gnu.org/ml/libstdc++/2002-11/msg00180.html">this + message</a>. + + At minimum, you can write short wrappers like + </p><pre class="programlisting"> + char toLower (char c) + { + return std::tolower(c); + } </pre><p>(Thanks to James Kanze for assistance and suggestions on all of this.) + </p><p>Another common operation is trimming off excess whitespace. Much + like transformations, this task is trivial with the use of string's + <code class="code">find</code> family. These examples are broken into multiple + statements for readability: + </p><pre class="programlisting"> + std::string str (" \t blah blah blah \n "); + + // trim leading whitespace + string::size_type notwhite = str.find_first_not_of(" \t\n"); + str.erase(0,notwhite); + + // trim trailing whitespace + notwhite = str.find_last_not_of(" \t\n"); + str.erase(notwhite+1); </pre><p>Obviously, the calls to <code class="code">find</code> could be inserted directly + into the calls to <code class="code">erase</code>, in case your compiler does not + optimize named temporaries out of existence. + </p></div><div class="section" title="Case Sensitivity"><div class="titlepage"><div><div><h3 class="title"><a id="strings.string.case"/>Case Sensitivity</h3></div></div></div><p> + </p><p>The well-known-and-if-it-isn't-well-known-it-ought-to-be + <a class="link" href="http://www.gotw.ca/gotw/">Guru of the Week</a> + discussions held on Usenet covered this topic in January of 1998. + Briefly, the challenge was, <span class="quote">“<span class="quote">write a 'ci_string' class which + is identical to the standard 'string' class, but is + case-insensitive in the same way as the (common but nonstandard) + C function stricmp()</span>”</span>. + </p><pre class="programlisting"> + ci_string s( "AbCdE" ); + + // case insensitive + assert( s == "abcde" ); + assert( s == "ABCDE" ); + + // still case-preserving, of course + assert( strcmp( s.c_str(), "AbCdE" ) == 0 ); + assert( strcmp( s.c_str(), "abcde" ) != 0 ); </pre><p>The solution is surprisingly easy. The original answer was + posted on Usenet, and a revised version appears in Herb Sutter's + book <span class="emphasis"><em>Exceptional C++</em></span> and on his website as <a class="link" href="http://www.gotw.ca/gotw/029.htm">GotW 29</a>. + </p><p>See? Told you it was easy!</p><p> + <span class="emphasis"><em>Added June 2000:</em></span> The May 2000 issue of C++ + Report contains a fascinating <a class="link" href="http://lafstern.org/matt/col2_new.pdf"> article</a> by + Matt Austern (yes, <span class="emphasis"><em>the</em></span> Matt Austern) on why + case-insensitive comparisons are not as easy as they seem, and + why creating a class is the <span class="emphasis"><em>wrong</em></span> way to go + about it in production code. (The GotW answer mentions one of + the principle difficulties; his article mentions more.) + </p><p>Basically, this is "easy" only if you ignore some things, + things which may be too important to your program to ignore. (I chose + to ignore them when originally writing this entry, and am surprised + that nobody ever called me on it...) The GotW question and answer + remain useful instructional tools, however. + </p><p><span class="emphasis"><em>Added September 2000:</em></span> James Kanze provided a link to a + <a class="link" href="http://www.unicode.org/reports/tr21/tr21-5.html">Unicode + Technical Report discussing case handling</a>, which provides some + very good information. + </p></div><div class="section" title="Arbitrary Character Types"><div class="titlepage"><div><div><h3 class="title"><a id="strings.string.character_types"/>Arbitrary Character Types</h3></div></div></div><p> + </p><p>The <code class="code">std::basic_string</code> is tantalizingly general, in that + it is parameterized on the type of the characters which it holds. + In theory, you could whip up a Unicode character class and instantiate + <code class="code">std::basic_string<my_unicode_char></code>, or assuming + that integers are wider than characters on your platform, maybe just + declare variables of type <code class="code">std::basic_string<int></code>. + </p><p>That's the theory. Remember however that basic_string has additional + type parameters, which take default arguments based on the character + type (called <code class="code">CharT</code> here): + </p><pre class="programlisting"> + template <typename CharT, + typename Traits = char_traits<CharT>, + typename Alloc = allocator<CharT> > + class basic_string { .... };</pre><p>Now, <code class="code">allocator<CharT></code> will probably Do The Right + Thing by default, unless you need to implement your own allocator + for your characters. + </p><p>But <code class="code">char_traits</code> takes more work. The char_traits + template is <span class="emphasis"><em>declared</em></span> but not <span class="emphasis"><em>defined</em></span>. + That means there is only + </p><pre class="programlisting"> + template <typename CharT> + struct char_traits + { + static void foo (type1 x, type2 y); + ... + };</pre><p>and functions such as char_traits<CharT>::foo() are not + actually defined anywhere for the general case. The C++ standard + permits this, because writing such a definition to fit all possible + CharT's cannot be done. + </p><p>The C++ standard also requires that char_traits be specialized for + instantiations of <code class="code">char</code> and <code class="code">wchar_t</code>, and it + is these template specializations that permit entities like + <code class="code">basic_string<char,char_traits<char>></code> to work. + </p><p>If you want to use character types other than char and wchar_t, + such as <code class="code">unsigned char</code> and <code class="code">int</code>, you will + need suitable specializations for them. For a time, in earlier + versions of GCC, there was a mostly-correct implementation that + let programmers be lazy but it broke under many situations, so it + was removed. GCC 3.4 introduced a new implementation that mostly + works and can be specialized even for <code class="code">int</code> and other + built-in types. + </p><p>If you want to use your own special character class, then you have + <a class="link" href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00163.html">a lot + of work to do</a>, especially if you with to use i18n features + (facets require traits information but don't have a traits argument). + </p><p>Another example of how to specialize char_traits was given <a class="link" href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00260.html">on the + mailing list</a> and at a later date was put into the file <code class="code"> + include/ext/pod_char_traits.h</code>. We agree + that the way it's used with basic_string (scroll down to main()) + doesn't look nice, but that's because <a class="link" href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00236.html">the + nice-looking first attempt</a> turned out to <a class="link" href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00242.html">not + be conforming C++</a>, due to the rule that CharT must be a POD. + (See how tricky this is?) + </p></div><div class="section" title="Tokenizing"><div class="titlepage"><div><div><h3 class="title"><a id="strings.string.token"/>Tokenizing</h3></div></div></div><p> + </p><p>The Standard C (and C++) function <code class="code">strtok()</code> leaves a lot to + be desired in terms of user-friendliness. It's unintuitive, it + destroys the character string on which it operates, and it requires + you to handle all the memory problems. But it does let the client + code decide what to use to break the string into pieces; it allows + you to choose the "whitespace," so to speak. + </p><p>A C++ implementation lets us keep the good things and fix those + annoyances. The implementation here is more intuitive (you only + call it once, not in a loop with varying argument), it does not + affect the original string at all, and all the memory allocation + is handled for you. + </p><p>It's called stringtok, and it's a template function. Sources are + as below, in a less-portable form than it could be, to keep this + example simple (for example, see the comments on what kind of + string it will accept). + </p><pre class="programlisting"> +#include <string> +template <typename Container> +void +stringtok(Container &container, string const &in, + const char * const delimiters = " \t\n") +{ + const string::size_type len = in.length(); + string::size_type i = 0; + + while (i < len) + { + // Eat leading whitespace + i = in.find_first_not_of(delimiters, i); + if (i == string::npos) + return; // Nothing left but white space + + // Find the end of the token + string::size_type j = in.find_first_of(delimiters, i); + + // Push token + if (j == string::npos) + { + container.push_back(in.substr(i)); + return; + } + else + container.push_back(in.substr(i, j-i)); + + // Set up for next loop + i = j + 1; + } +} +</pre><p> + The author uses a more general (but less readable) form of it for + parsing command strings and the like. If you compiled and ran this + code using it: + </p><pre class="programlisting"> + std::list<string> ls; + stringtok (ls, " this \t is\t\n a test "); + for (std::list<string>const_iterator i = ls.begin(); + i != ls.end(); ++i) + { + std::cerr << ':' << (*i) << ":\n"; + } </pre><p>You would see this as output: + </p><pre class="programlisting"> + :this: + :is: + :a: + :test: </pre><p>with all the whitespace removed. The original <code class="code">s</code> is still + available for use, <code class="code">ls</code> will clean up after itself, and + <code class="code">ls.size()</code> will return how many tokens there were. + </p><p>As always, there is a price paid here, in that stringtok is not + as fast as strtok. The other benefits usually outweigh that, however. + </p><p><span class="emphasis"><em>Added February 2001:</em></span> Mark Wilden pointed out that the + standard <code class="code">std::getline()</code> function can be used with standard + <code class="code">istringstreams</code> to perform + tokenizing as well. Build an istringstream from the input text, + and then use std::getline with varying delimiters (the three-argument + signature) to extract tokens into a string. + </p></div><div class="section" title="Shrink to Fit"><div class="titlepage"><div><div><h3 class="title"><a id="strings.string.shrink"/>Shrink to Fit</h3></div></div></div><p> + </p><p>From GCC 3.4 calling <code class="code">s.reserve(res)</code> on a + <code class="code">string s</code> with <code class="code">res < s.capacity()</code> will + reduce the string's capacity to <code class="code">std::max(s.size(), res)</code>. + </p><p>This behaviour is suggested, but not required by the standard. Prior + to GCC 3.4 the following alternative can be used instead + </p><pre class="programlisting"> + std::string(str.data(), str.size()).swap(str); + </pre><p>This is similar to the idiom for reducing + a <code class="code">vector</code>'s memory usage + (see <a class="link" href="../faq.html#faq.size_equals_capacity" title="7.8.">this FAQ + entry</a>) but the regular copy constructor cannot be used + because libstdc++'s <code class="code">string</code> is Copy-On-Write. + </p><p>In <a class="link" href="status.html#status.iso.200x" title="C++ 200x">C++0x</a> mode you can call + <code class="code">s.shrink_to_fit()</code> to achieve the same effect as + <code class="code">s.reserve(s.size())</code>. + </p></div><div class="section" title="CString (MFC)"><div class="titlepage"><div><div><h3 class="title"><a id="strings.string.Cstring"/>CString (MFC)</h3></div></div></div><p> + </p><p>A common lament seen in various newsgroups deals with the Standard + string class as opposed to the Microsoft Foundation Class called + CString. Often programmers realize that a standard portable + answer is better than a proprietary nonportable one, but in porting + their application from a Win32 platform, they discover that they + are relying on special functions offered by the CString class. + </p><p>Things are not as bad as they seem. In + <a class="link" href="http://gcc.gnu.org/ml/gcc/1999-04n/msg00236.html">this + message</a>, Joe Buck points out a few very important things: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>The Standard <code class="code">string</code> supports all the operations + that CString does, with three exceptions. + </p></li><li class="listitem"><p>Two of those exceptions (whitespace trimming and case + conversion) are trivial to implement. In fact, we do so + on this page. + </p></li><li class="listitem"><p>The third is <code class="code">CString::Format</code>, which allows formatting + in the style of <code class="code">sprintf</code>. This deserves some mention: + </p></li></ul></div><p> + The old libg++ library had a function called form(), which did much + the same thing. But for a Standard solution, you should use the + stringstream classes. These are the bridge between the iostream + hierarchy and the string class, and they operate with regular + streams seamlessly because they inherit from the iostream + hierarchy. An quick example: + </p><pre class="programlisting"> + #include <iostream> + #include <string> + #include <sstream> + + string f (string& incoming) // incoming is "foo N" + { + istringstream incoming_stream(incoming); + string the_word; + int the_number; + + incoming_stream >> the_word // extract "foo" + >> the_number; // extract N + + ostringstream output_stream; + output_stream << "The word was " << the_word + << " and 3*N was " << (3*the_number); + + return output_stream.str(); + } </pre><p>A serious problem with CString is a design bug in its memory + allocation. Specifically, quoting from that same message: + </p><pre class="programlisting"> + CString suffers from a common programming error that results in + poor performance. Consider the following code: + + CString n_copies_of (const CString& foo, unsigned n) + { + CString tmp; + for (unsigned i = 0; i < n; i++) + tmp += foo; + return tmp; + } + + This function is O(n^2), not O(n). The reason is that each += + causes a reallocation and copy of the existing string. Microsoft + applications are full of this kind of thing (quadratic performance + on tasks that can be done in linear time) -- on the other hand, + we should be thankful, as it's created such a big market for high-end + ix86 hardware. :-) + + If you replace CString with string in the above function, the + performance is O(n). + </pre><p>Joe Buck also pointed out some other things to keep in mind when + comparing CString and the Standard string class: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>CString permits access to its internal representation; coders + who exploited that may have problems moving to <code class="code">string</code>. + </p></li><li class="listitem"><p>Microsoft ships the source to CString (in the files + MFC\SRC\Str{core,ex}.cpp), so you could fix the allocation + bug and rebuild your MFC libraries. + <span class="emphasis"><em><span class="emphasis"><em>Note:</em></span> It looks like the CString shipped + with VC++6.0 has fixed this, although it may in fact have been + one of the VC++ SPs that did it.</em></span> + </p></li><li class="listitem"><p><code class="code">string</code> operations like this have O(n) complexity + <span class="emphasis"><em>if the implementors do it correctly</em></span>. The libstdc++ + implementors did it correctly. Other vendors might not. + </p></li><li class="listitem"><p>While chapters of the SGI STL are used in libstdc++, their + string class is not. The SGI <code class="code">string</code> is essentially + <code class="code">vector<char></code> and does not do any reference + counting like libstdc++'s does. (It is O(n), though.) + So if you're thinking about SGI's string or rope classes, + you're now looking at four possibilities: CString, the + libstdc++ string, the SGI string, and the SGI rope, and this + is all before any allocator or traits customizations! (More + choices than you can shake a stick at -- want fries with that?) + </p></li></ul></div></div></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="traits.html">Prev</a> </td><td align="center"><a accesskey="u" href="bk01pt02.html">Up</a></td><td align="right"> <a accesskey="n" href="localization.html">Next</a></td></tr><tr><td align="left" valign="top">Traits </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Chapter 8. + Localization + +</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/stringstreams.html b/libstdc++-v3/doc/html/manual/stringstreams.html new file mode 100644 index 000000000..1107d61b1 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/stringstreams.html @@ -0,0 +1,37 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Memory Based Streams</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="io.html" title="Chapter 13. Input and Output"/><link rel="prev" href="streambufs.html" title="Stream Buffers"/><link rel="next" href="fstreams.html" title="File Based Streams"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Memory Based Streams</th></tr><tr><td align="left"><a accesskey="p" href="streambufs.html">Prev</a> </td><th width="60%" align="center">Chapter 13. + Input and Output + +</th><td align="right"> <a accesskey="n" href="fstreams.html">Next</a></td></tr></table><hr/></div><div class="section" title="Memory Based Streams"><div class="titlepage"><div><div><h2 class="title"><a id="std.io.memstreams"/>Memory Based Streams</h2></div></div></div><div class="section" title="Compatibility With strstream"><div class="titlepage"><div><div><h3 class="title"><a id="std.io.memstreams.compat"/>Compatibility With strstream</h3></div></div></div><p> + </p><p>Stringstreams (defined in the header <code class="code"><sstream></code>) + are in this author's opinion one of the coolest things since + sliced time. An example of their use is in the Received Wisdom + section for Sect1 21 (Strings), + <a class="link" href="strings.html#strings.string.Cstring" title="CString (MFC)"> describing how to + format strings</a>. + </p><p>The quick definition is: they are siblings of ifstream and ofstream, + and they do for <code class="code">std::string</code> what their siblings do for + files. All that work you put into writing <code class="code"><<</code> and + <code class="code">>></code> functions for your classes now pays off + <span class="emphasis"><em>again!</em></span> Need to format a string before passing the string + to a function? Send your stuff via <code class="code"><<</code> to an + ostringstream. You've read a string as input and need to parse it? + Initialize an istringstream with that string, and then pull pieces + out of it with <code class="code">>></code>. Have a stringstream and need to + get a copy of the string inside? Just call the <code class="code">str()</code> + member function. + </p><p>This only works if you've written your + <code class="code"><<</code>/<code class="code">>></code> functions correctly, though, + and correctly means that they take istreams and ostreams as + parameters, not i<span class="emphasis"><em>f</em></span>streams and o<span class="emphasis"><em>f</em></span>streams. If they + take the latter, then your I/O operators will work fine with + file streams, but with nothing else -- including stringstreams. + </p><p>If you are a user of the strstream classes, you need to update + your code. You don't have to explicitly append <code class="code">ends</code> to + terminate the C-style character array, you don't have to mess with + "freezing" functions, and you don't have to manage the + memory yourself. The strstreams have been officially deprecated, + which means that 1) future revisions of the C++ Standard won't + support them, and 2) if you use them, people will laugh at you. + </p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="streambufs.html">Prev</a> </td><td align="center"><a accesskey="u" href="io.html">Up</a></td><td align="right"> <a accesskey="n" href="fstreams.html">Next</a></td></tr><tr><td align="left" valign="top">Stream Buffers </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> File Based Streams</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/support.html b/libstdc++-v3/doc/html/manual/support.html new file mode 100644 index 000000000..39c8185c6 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/support.html @@ -0,0 +1,130 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Chapter 4. Support</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="bk01pt02.html" title="Part II. Standard Contents"/><link rel="prev" href="bk01pt02.html" title="Part II. Standard Contents"/><link rel="next" href="dynamic_memory.html" title="Dynamic Memory"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 4. + Support + +</th></tr><tr><td align="left"><a accesskey="p" href="bk01pt02.html">Prev</a> </td><th width="60%" align="center">Part II. + Standard Contents + </th><td align="right"> <a accesskey="n" href="dynamic_memory.html">Next</a></td></tr></table><hr/></div><div class="chapter" title="Chapter 4. Support"><div class="titlepage"><div><div><h2 class="title"><a id="std.support"/>Chapter 4. + Support + <a id="id471617" class="indexterm"/> +</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="support.html#std.support.types">Types</a></span></dt><dd><dl><dt><span class="section"><a href="support.html#std.support.types.fundamental">Fundamental Types</a></span></dt><dt><span class="section"><a href="support.html#std.support.types.numeric_limits">Numeric Properties</a></span></dt><dt><span class="section"><a href="support.html#std.support.types.null">NULL</a></span></dt></dl></dd><dt><span class="section"><a href="dynamic_memory.html">Dynamic Memory</a></span></dt><dt><span class="section"><a href="termination.html">Termination</a></span></dt><dd><dl><dt><span class="section"><a href="termination.html#support.termination.handlers">Termination Handlers</a></span></dt><dt><span class="section"><a href="termination.html#support.termination.verbose">Verbose Terminate Handler</a></span></dt></dl></dd></dl></div><p> + This part deals with the functions called and objects created + automatically during the course of a program's existence. + </p><p> + While we can't reproduce the contents of the Standard here (you + need to get your own copy from your nation's member body; see our + homepage for help), we can mention a couple of changes in what + kind of support a C++ program gets from the Standard Library. + </p><div class="section" title="Types"><div class="titlepage"><div><div><h2 class="title"><a id="std.support.types"/>Types</h2></div></div></div><div class="section" title="Fundamental Types"><div class="titlepage"><div><div><h3 class="title"><a id="std.support.types.fundamental"/>Fundamental Types</h3></div></div></div><p> + C++ has the following builtin types: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + char + </p></li><li class="listitem"><p> + signed char + </p></li><li class="listitem"><p> + unsigned char + </p></li><li class="listitem"><p> + signed short + </p></li><li class="listitem"><p> + signed int + </p></li><li class="listitem"><p> + signed long + </p></li><li class="listitem"><p> + unsigned short + </p></li><li class="listitem"><p> + unsigned int + </p></li><li class="listitem"><p> + unsigned long + </p></li><li class="listitem"><p> + bool + </p></li><li class="listitem"><p> + wchar_t + </p></li><li class="listitem"><p> + float + </p></li><li class="listitem"><p> + double + </p></li><li class="listitem"><p> + long double + </p></li></ul></div><p> + These fundamental types are always available, without having to + include a header file. These types are exactly the same in + either C++ or in C. + </p><p> + Specializing parts of the library on these types is prohibited: + instead, use a POD. + </p></div><div class="section" title="Numeric Properties"><div class="titlepage"><div><div><h3 class="title"><a id="std.support.types.numeric_limits"/>Numeric Properties</h3></div></div></div><p> + The header <code class="filename">limits</code> defines + traits classes to give access to various implementation + defined-aspects of the fundamental types. The traits classes -- + fourteen in total -- are all specializations of the template class + <code class="classname">numeric_limits</code>, documented <a class="link" href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a00593.html">here</a> + and defined as follows: + </p><pre class="programlisting"> + template<typename T> + struct class + { + static const bool is_specialized; + static T max() throw(); + static T min() throw(); + + static const int digits; + static const int digits10; + static const bool is_signed; + static const bool is_integer; + static const bool is_exact; + static const int radix; + static T epsilon() throw(); + static T round_error() throw(); + + static const int min_exponent; + static const int min_exponent10; + static const int max_exponent; + static const int max_exponent10; + + static const bool has_infinity; + static const bool has_quiet_NaN; + static const bool has_signaling_NaN; + static const float_denorm_style has_denorm; + static const bool has_denorm_loss; + static T infinity() throw(); + static T quiet_NaN() throw(); + static T denorm_min() throw(); + + static const bool is_iec559; + static const bool is_bounded; + static const bool is_modulo; + + static const bool traps; + static const bool tinyness_before; + static const float_round_style round_style; + }; + </pre></div><div class="section" title="NULL"><div class="titlepage"><div><div><h3 class="title"><a id="std.support.types.null"/>NULL</h3></div></div></div><p> + The only change that might affect people is the type of + <code class="constant">NULL</code>: while it is required to be a macro, + the definition of that macro is <span class="emphasis"><em>not</em></span> allowed + to be <code class="constant">(void*)0</code>, which is often used in C. + </p><p> + For <span class="command"><strong>g++</strong></span>, <code class="constant">NULL</code> is + <code class="code">#define</code>'d to be + <code class="constant">__null</code>, a magic keyword extension of + <span class="command"><strong>g++</strong></span>. + </p><p> + The biggest problem of #defining <code class="constant">NULL</code> to be + something like <span class="quote">“<span class="quote">0L</span>”</span> is that the compiler will view + that as a long integer before it views it as a pointer, so + overloading won't do what you expect. (This is why + <span class="command"><strong>g++</strong></span> has a magic extension, so that + <code class="constant">NULL</code> is always a pointer.) + </p><p>In his book <a class="link" href="http://www.awprofessional.com/titles/0-201-92488-9/"><span class="emphasis"><em>Effective + C++</em></span></a>, Scott Meyers points out that the best way + to solve this problem is to not overload on pointer-vs-integer + types to begin with. He also offers a way to make your own magic + <code class="constant">NULL</code> that will match pointers before it + matches integers. + </p><p>See + <a class="link" href="http://www.awprofessional.com/titles/0-201-31015-5/">the + Effective C++ CD example</a> + </p></div></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="bk01pt02.html">Prev</a> </td><td align="center"><a accesskey="u" href="bk01pt02.html">Up</a></td><td align="right"> <a accesskey="n" href="dynamic_memory.html">Next</a></td></tr><tr><td align="left" valign="top">Part II. + Standard Contents + </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Dynamic Memory</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/termination.html b/libstdc++-v3/doc/html/manual/termination.html new file mode 100644 index 000000000..cc5235943 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/termination.html @@ -0,0 +1,124 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Termination</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="support.html" title="Chapter 4. Support"/><link rel="prev" href="dynamic_memory.html" title="Dynamic Memory"/><link rel="next" href="diagnostics.html" title="Chapter 5. Diagnostics"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Termination</th></tr><tr><td align="left"><a accesskey="p" href="dynamic_memory.html">Prev</a> </td><th width="60%" align="center">Chapter 4. + Support + +</th><td align="right"> <a accesskey="n" href="diagnostics.html">Next</a></td></tr></table><hr/></div><div class="section" title="Termination"><div class="titlepage"><div><div><h2 class="title"><a id="std.support.termination"/>Termination</h2></div></div></div><div class="section" title="Termination Handlers"><div class="titlepage"><div><div><h3 class="title"><a id="support.termination.handlers"/>Termination Handlers</h3></div></div></div><p> + Not many changes here to <code class="filename">cstdlib</code>. You should note that the + <code class="function">abort()</code> function does not call the + destructors of automatic nor static objects, so if you're + depending on those to do cleanup, it isn't going to happen. + (The functions registered with <code class="function">atexit()</code> + don't get called either, so you can forget about that + possibility, too.) + </p><p> + The good old <code class="function">exit()</code> function can be a bit + funky, too, until you look closer. Basically, three points to + remember are: + </p><div class="orderedlist"><ol class="orderedlist"><li class="listitem"><p> + Static objects are destroyed in reverse order of their creation. + </p></li><li class="listitem"><p> + Functions registered with <code class="function">atexit()</code> are called in + reverse order of registration, once per registration call. + (This isn't actually new.) + </p></li><li class="listitem"><p> + The previous two actions are <span class="quote">“<span class="quote">interleaved,</span>”</span> that is, + given this pseudocode: + </p><pre class="programlisting"> + extern "C or C++" void f1 (void); + extern "C or C++" void f2 (void); + + static Thing obj1; + atexit(f1); + static Thing obj2; + atexit(f2); +</pre><p> + then at a call of <code class="function">exit()</code>, + <code class="varname">f2</code> will be called, then + <code class="varname">obj2</code> will be destroyed, then + <code class="varname">f1</code> will be called, and finally + <code class="varname">obj1</code> will be destroyed. If + <code class="varname">f1</code> or <code class="varname">f2</code> allow an + exception to propagate out of them, Bad Things happen. + </p></li></ol></div><p> + Note also that <code class="function">atexit()</code> is only required to store 32 + functions, and the compiler/library might already be using some of + those slots. If you think you may run out, we recommend using + the <code class="function">xatexit</code>/<code class="function">xexit</code> combination from <code class="literal">libiberty</code>, which has no such limit. + </p></div><div class="section" title="Verbose Terminate Handler"><div class="titlepage"><div><div><h3 class="title"><a id="support.termination.verbose"/>Verbose Terminate Handler</h3></div></div></div><p> + If you are having difficulty with uncaught exceptions and want a + little bit of help debugging the causes of the core dumps, you can + make use of a GNU extension, the verbose terminate handler. + </p><pre class="programlisting"> +#include <exception> + +int main() +{ + std::set_terminate(__gnu_cxx::__verbose_terminate_handler); + ... + + throw <em class="replaceable"><code>anything</code></em>; +} +</pre><p> + The <code class="function">__verbose_terminate_handler</code> function + obtains the name of the current exception, attempts to demangle + it, and prints it to stderr. If the exception is derived from + <code class="classname">exception</code> then the output from + <code class="function">what()</code> will be included. + </p><p> + Any replacement termination function is required to kill the + program without returning; this one calls abort. + </p><p> + For example: + </p><pre class="programlisting"> +#include <exception> +#include <stdexcept> + +struct argument_error : public std::runtime_error +{ + argument_error(const std::string& s): std::runtime_error(s) { } +}; + +int main(int argc) +{ + std::set_terminate(__gnu_cxx::__verbose_terminate_handler); + if (argc > 5) + throw argument_error(<span class="quote">“<span class="quote">argc is greater than 5!</span>”</span>); + else + throw argc; +} +</pre><p> + With the verbose terminate handler active, this gives: + </p><pre class="screen"> + <code class="computeroutput"> + % ./a.out + terminate called after throwing a `int' + Aborted + % ./a.out f f f f f f f f f f f + terminate called after throwing an instance of `argument_error' + what(): argc is greater than 5! + Aborted + </code> + </pre><p> + The 'Aborted' line comes from the call to + <code class="function">abort()</code>, of course. + </p><p> + This is the default termination handler; nothing need be done to + use it. To go back to the previous <span class="quote">“<span class="quote">silent death</span>”</span> + method, simply include <code class="filename">exception</code> and + <code class="filename">cstdlib</code>, and call + </p><pre class="programlisting"> + std::set_terminate(std::abort); + </pre><p> + After this, all calls to <code class="function">terminate</code> will use + <code class="function">abort</code> as the terminate handler. + </p><p> + Note: the verbose terminate handler will attempt to write to + stderr. If your application closes stderr or redirects it to an + inappropriate location, + <code class="function">__verbose_terminate_handler</code> will behave in + an unspecified manner. + </p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="dynamic_memory.html">Prev</a> </td><td align="center"><a accesskey="u" href="support.html">Up</a></td><td align="right"> <a accesskey="n" href="diagnostics.html">Next</a></td></tr><tr><td align="left" valign="top">Dynamic Memory </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Chapter 5. + Diagnostics + +</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/test.html b/libstdc++-v3/doc/html/manual/test.html new file mode 100644 index 000000000..b346c422b --- /dev/null +++ b/libstdc++-v3/doc/html/manual/test.html @@ -0,0 +1,639 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Test</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , test , testsuite , performance , conformance , ABI , exception safety "/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="appendix_porting.html" title="Appendix B. Porting and Maintenance"/><link rel="prev" href="internals.html" title="Porting to New Hardware or Operating Systems"/><link rel="next" href="abi.html" title="ABI Policy and Guidelines"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Test</th></tr><tr><td align="left"><a accesskey="p" href="internals.html">Prev</a> </td><th width="60%" align="center">Appendix B. + Porting and Maintenance + +</th><td align="right"> <a accesskey="n" href="abi.html">Next</a></td></tr></table><hr/></div><div class="section" title="Test"><div class="titlepage"><div><div><h2 class="title"><a id="manual.intro.setup.test"/>Test</h2></div></div></div><p> +The libstdc++ testsuite includes testing for standard conformance, +regressions, ABI, and performance. +</p><div class="section" title="Organization"><div class="titlepage"><div><div><h3 class="title"><a id="test.organization"/>Organization</h3></div></div></div><div class="section" title="Directory Layout"><div class="titlepage"><div><div><h4 class="title"><a id="test.organization.layout"/>Directory Layout</h4></div></div></div><p> + The directory <span class="emphasis"><em>libsrcdir/testsuite</em></span> contains the + individual test cases organized in sub-directories corresponding to + chapters of the C++ standard (detailed below), the dejagnu test + harness support files, and sources to various testsuite utilities + that are packaged in a separate testing library. +</p><p> + All test cases for functionality required by the runtime components + of the C++ standard (ISO 14882) are files within the following + directories. +</p><pre class="programlisting"> +17_intro +18_support +19_diagnostics +20_util +21_strings +22_locale +23_containers +25_algorithms +26_numerics +27_io +28_regex +29_atomics +30_threads + </pre><p> + In addition, the following directories include test files: + </p><pre class="programlisting"> +tr1 Tests for components as described by the Technical Report on Standard Library Extensions (TR1). +backward Tests for backwards compatibility and deprecated features. +demangle Tests for __cxa_demangle, the IA 64 C++ ABI demangler +ext Tests for extensions. +performance Tests for performance analysis, and performance regressions. + </pre><p> + Some directories don't have test files, but instead contain + auxiliary information: + </p><pre class="programlisting"> +config Files for the dejagnu test harness. +lib Files for the dejagnu test harness. +libstdc++* Files for the dejagnu test harness. +data Sample text files for testing input and output. +util Files for libtestc++, utilities and testing routines. + </pre><p> + Within a directory that includes test files, there may be + additional subdirectories, or files. Originally, test cases + were appended to one file that represented a particular section + of the chapter under test, and was named accordingly. For + instance, to test items related to <code class="code"> 21.3.6.1 - + basic_string::find [lib.string::find]</code> in the standard, + the following was used: + </p><pre class="programlisting"> +21_strings/find.cc + </pre><p> + However, that practice soon became a liability as the test cases + became huge and unwieldy, and testing new or extended + functionality (like wide characters or named locales) became + frustrating, leading to aggressive pruning of test cases on some + platforms that covered up implementation errors. Now, the test + suite has a policy of one file, one test case, which solves the + above issues and gives finer grained results and more manageable + error debugging. As an example, the test case quoted above + becomes: + </p><pre class="programlisting"> +21_strings/basic_string/find/char/1.cc +21_strings/basic_string/find/char/2.cc +21_strings/basic_string/find/char/3.cc +21_strings/basic_string/find/wchar_t/1.cc +21_strings/basic_string/find/wchar_t/2.cc +21_strings/basic_string/find/wchar_t/3.cc + </pre><p> + All new tests should be written with the policy of one test + case, one file in mind. + </p></div><div class="section" title="Naming Conventions"><div class="titlepage"><div><div><h4 class="title"><a id="test.organization.naming"/>Naming Conventions</h4></div></div></div><p> + In addition, there are some special names and suffixes that are + used within the testsuite to designate particular kinds of + tests. + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + <span class="emphasis"><em>_xin.cc</em></span> + </p><p> + This test case expects some kind of interactive input in order + to finish or pass. At the moment, the interactive tests are not + run by default. Instead, they are run by hand, like: + </p><pre class="programlisting"> +g++ 27_io/objects/char/3_xin.cc +cat 27_io/objects/char/3_xin.in | a.out + </pre></li><li class="listitem"><p> + <span class="emphasis"><em>.in</em></span> + </p><p> + This file contains the expected input for the corresponding <span class="emphasis"><em> + _xin.cc</em></span> test case. + </p></li><li class="listitem"><p> + <span class="emphasis"><em>_neg.cc</em></span> + </p><p> + This test case is expected to fail: it's a negative test. At the + moment, these are almost always compile time errors. + </p></li><li class="listitem"><p> + <span class="emphasis"><em>char</em></span> + </p><p> + This can either be a directory name or part of a longer file + name, and indicates that this file, or the files within this + directory are testing the <code class="code">char</code> instantiation of a + template. + </p></li><li class="listitem"><p> + <span class="emphasis"><em>wchar_t</em></span> + </p><p> + This can either be a directory name or part of a longer file + name, and indicates that this file, or the files within this + directory are testing the <code class="code">wchar_t</code> instantiation of + a template. Some hosts do not support <code class="code">wchar_t</code> + functionality, so for these targets, all of these tests will not + be run. + </p></li><li class="listitem"><p> + <span class="emphasis"><em>thread</em></span> + </p><p> + This can either be a directory name or part of a longer file + name, and indicates that this file, or the files within this + directory are testing situations where multiple threads are + being used. + </p></li><li class="listitem"><p> + <span class="emphasis"><em>performance</em></span> + </p><p> + This can either be an enclosing directory name or part of a + specific file name. This indicates a test that is used to + analyze runtime performance, for performance regression testing, + or for other optimization related analysis. At the moment, these + test cases are not run by default. + </p></li></ul></div></div></div><div class="section" title="Running the Testsuite"><div class="titlepage"><div><div><h3 class="title"><a id="test.run"/>Running the Testsuite</h3></div></div></div><div class="section" title="Basic"><div class="titlepage"><div><div><h4 class="title"><a id="test.run.basic"/>Basic</h4></div></div></div><p> + You can check the status of the build without installing it + using the dejagnu harness, much like the rest of the gcc + tools.</p><pre class="programlisting"> make check</pre><p>in the <span class="emphasis"><em>libbuilddir</em></span> directory.</p><p>or</p><pre class="programlisting"> make check-target-libstdc++-v3</pre><p>in the <span class="emphasis"><em>gccbuilddir</em></span> directory. + </p><p> + These commands are functionally equivalent and will create a + 'testsuite' directory underneath + <span class="emphasis"><em>libbuilddir</em></span> containing the results of the + tests. Two results files will be generated: <span class="emphasis"><em> + libstdc++.sum</em></span>, which is a PASS/FAIL summary for each + test, and <span class="emphasis"><em>libstdc++.log</em></span> which is a log of + the exact command line passed to the compiler, the compiler + output, and the executable output (if any). + </p><p> + Archives of test results for various versions and platforms are + available on the GCC website in the <a class="link" href="http://gcc.gnu.org/gcc-4.3/buildstat.html">build + status</a> section of each individual release, and are also + archived on a daily basis on the <a class="link" href="http://gcc.gnu.org/ml/gcc-testresults/current">gcc-testresults</a> + mailing list. Please check either of these places for a similar + combination of source version, operating system, and host CPU. + </p></div><div class="section" title="Variations"><div class="titlepage"><div><div><h4 class="title"><a id="test.run.variations"/>Variations</h4></div></div></div><p> + There are several options for running tests, including testing + the regression tests, testing a subset of the regression tests, + testing the performance tests, testing just compilation, testing + installed tools, etc. In addition, there is a special rule for + checking the exported symbols of the shared library. + </p><p> + To debug the dejagnu test harness during runs, try invoking with a + specific argument to the variable RUNTESTFLAGS, as below. + </p><pre class="programlisting"> +make check-target-libstdc++-v3 RUNTESTFLAGS="-v" +</pre><p> + or + </p><pre class="programlisting"> +make check-target-libstdc++-v3 RUNTESTFLAGS="-v -v" +</pre><p> + To run a subset of the library tests, you will need to generate + the <span class="emphasis"><em>testsuite_files</em></span> file by running + <span class="command"><strong>make testsuite_files</strong></span> in the + <span class="emphasis"><em>libbuilddir/testsuite</em></span> directory, described + below. Edit the file to remove the tests you don't want and + then run the testsuite as normal. + </p><p> + There are two ways to run on a simulator: set up DEJAGNU to point to a + specially crafted site.exp, or pass down --target_board flags. + </p><p> + Example flags to pass down for various embedded builds are as follows: + </p><pre class="programlisting"> + --target=powerpc-eabism (libgloss/sim) +make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=powerpc-sim" + +--target=calmrisc32 (libgloss/sid) +make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=calmrisc32-sid" + +--target=xscale-elf (newlib/sim) +make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=arm-sim" +</pre><p> + Also, here is an example of how to run the libstdc++ testsuite + for a multilibed build directory with different ABI settings: + </p><pre class="programlisting"> +make check-target-libstdc++-v3 RUNTESTFLAGS='--target_board \"unix{-mabi=32,,-mabi=64}\"' +</pre><p> + You can run the tests with a compiler and library that have + already been installed. Make sure that the compiler (e.g., + <code class="code">g++</code>) is in your <code class="code">PATH</code>. If you are + using shared libraries, then you must also ensure that the + directory containing the shared version of libstdc++ is in your + <code class="code">LD_LIBRARY_PATH</code>, or equivalent. If your GCC source + tree is at <code class="code">/path/to/gcc</code>, then you can run the tests + as follows: + </p><pre class="programlisting"> +runtest --tool libstdc++ --srcdir=/path/to/gcc/libstdc++-v3/testsuite +</pre><p> + The testsuite will create a number of files in the directory in + which you run this command,. Some of those files might use the + same name as files created by other testsuites (like the ones + for GCC and G++), so you should not try to run all the + testsuites in parallel from the same directory. + </p><p> + In addition, there are some testing options that are mostly of + interest to library maintainers and system integrators. As such, + these tests may not work on all cpu and host combinations, and + may need to be executed in the + <span class="emphasis"><em>libbuilddir/testsuite</em></span> directory. These + options include, but are not necessarily limited to, the + following: + </p><pre class="programlisting"> + make testsuite_files + </pre><p> + Five files are generated that determine what test files + are run. These files are: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + <span class="emphasis"><em>testsuite_files</em></span> + </p><p> + This is a list of all the test cases that will be run. Each + test case is on a separate line, given with an absolute path + from the <span class="emphasis"><em>libsrcdir/testsuite</em></span> directory. + </p></li><li class="listitem"><p> + <span class="emphasis"><em>testsuite_files_interactive</em></span> + </p><p> + This is a list of all the interactive test cases, using the + same format as the file list above. These tests are not run + by default. + </p></li><li class="listitem"><p> + <span class="emphasis"><em>testsuite_files_performance</em></span> + </p><p> + This is a list of all the performance test cases, using the + same format as the file list above. These tests are not run + by default. + </p></li><li class="listitem"><p> + <span class="emphasis"><em>testsuite_thread</em></span> + </p><p> + This file indicates that the host system can run tests which + involved multiple threads. + </p></li><li class="listitem"><p> + <span class="emphasis"><em>testsuite_wchar_t</em></span> + </p><p> + This file indicates that the host system can run the wchar_t + tests, and corresponds to the macro definition <code class="code"> + _GLIBCXX_USE_WCHAR_T</code> in the file c++config.h. + </p></li></ul></div><pre class="programlisting"> + make check-abi + </pre><p> + The library ABI can be tested. This involves testing the shared + library against an ABI-defining previous version of symbol + exports. + </p><pre class="programlisting"> + make check-compile + </pre><p> + This rule compiles, but does not link or execute, the + <span class="emphasis"><em>testsuite_files</em></span> test cases and displays the + output on stdout. + </p><pre class="programlisting"> + make check-performance + </pre><p> + This rule runs through the + <span class="emphasis"><em>testsuite_files_performance</em></span> test cases and + collects information for performance analysis and can be used to + spot performance regressions. Various timing information is + collected, as well as number of hard page faults, and memory + used. This is not run by default, and the implementation is in + flux. + </p><p> + We are interested in any strange failures of the testsuite; + please email the main libstdc++ mailing list if you see + something odd or have questions. + </p></div><div class="section" title="Permutations"><div class="titlepage"><div><div><h4 class="title"><a id="test.run.permutations"/>Permutations</h4></div></div></div><p> + To run the libstdc++ test suite under the <a class="link" href="debug_mode.html" title="Chapter 17. Debug Mode">debug mode</a>, edit + <code class="filename">libstdc++-v3/scripts/testsuite_flags</code> to add the + compile-time flag <code class="constant">-D_GLIBCXX_DEBUG</code> to the + result printed by the <code class="literal">--build-cxx</code> + option. Additionally, add the + <code class="constant">-D_GLIBCXX_DEBUG_PEDANTIC</code> flag to turn on + pedantic checking. The libstdc++ test suite should produce + precisely the same results under debug mode that it does under + release mode: any deviation indicates an error in either the + library or the test suite. + </p><p> + The <a class="link" href="parallel_mode.html" title="Chapter 18. Parallel Mode">parallel + mode</a> can be tested in much the same manner, substituting + <code class="constant">-D_GLIBCXX_PARALLEL</code> for + <code class="constant">-D_GLIBCXX_DEBUG</code> in the previous paragraph. + </p><p> + Or, just run the testsuites with <code class="constant">CXXFLAGS</code> + set to <code class="constant">-D_GLIBCXX_DEBUG</code> or + <code class="constant">-D_GLIBCXX_PARALLEL</code>. + </p></div></div><div class="section" title="Writing a new test case"><div class="titlepage"><div><div><h3 class="title"><a id="test.new_tests"/>Writing a new test case</h3></div></div></div><p> + The first step in making a new test case is to choose the correct + directory and file name, given the organization as previously + described. + </p><p> + All files are copyright the FSF, and GPL'd: this is very + important. The first copyright year should correspond to the date + the file was checked in to SVN. + </p><p> + As per the dejagnu instructions, always return 0 from main to + indicate success. + </p><p> + A bunch of utility functions and classes have already been + abstracted out into the testsuite utility library, <code class="code"> + libtestc++</code>. To use this functionality, just include the + appropriate header file: the library or specific object files will + automatically be linked in as part of the testsuite run. + </p><p> + For a test that needs to take advantage of the dejagnu test + harness, what follows below is a list of special keyword that + harness uses. Basically, a test case contains dg-keywords (see + dg.exp) indicating what to do and what kinds of behavior are to be + expected. New test cases should be written with the new style + DejaGnu framework in mind. + </p><p> + To ease transition, here is the list of dg-keyword documentation + lifted from dg.exp. + </p><pre class="programlisting"> +# The currently supported options are: +# +# dg-prms-id N +# set prms_id to N +# +# dg-options "options ..." [{ target selector }] +# specify special options to pass to the tool (eg: compiler) +# +# dg-do do-what-keyword [{ target/xfail selector }] +# `do-what-keyword' is tool specific and is passed unchanged to +# ${tool}-dg-test. An example is gcc where `keyword' can be any of: +# preprocess|compile|assemble|link|run +# and will do one of: produce a .i, produce a .s, produce a .o, +# produce an a.out, or produce an a.out and run it (the default is +# compile). +# +# dg-error regexp comment [{ target/xfail selector } [{.|0|linenum}]] +# indicate an error message <regexp> is expected on this line +# (the test fails if it doesn't occur) +# Linenum=0 for general tool messages (eg: -V arg missing). +# "." means the current line. +# +# dg-warning regexp comment [{ target/xfail selector } [{.|0|linenum}]] +# indicate a warning message <regexp> is expected on this line +# (the test fails if it doesn't occur) +# +# dg-bogus regexp comment [{ target/xfail selector } [{.|0|linenum}]] +# indicate a bogus error message <regexp> use to occur here +# (the test fails if it does occur) +# +# dg-build regexp comment [{ target/xfail selector }] +# indicate the build use to fail for some reason +# (errors covered here include bad assembler generated, tool crashes, +# and link failures) +# (the test fails if it does occur) +# +# dg-excess-errors comment [{ target/xfail selector }] +# indicate excess errors are expected (any line) +# (this should only be used sparingly and temporarily) +# +# dg-output regexp [{ target selector }] +# indicate the expected output of the program is <regexp> +# (there may be multiple occurrences of this, they are concatenated) +# +# dg-final { tcl code } +# add some tcl code to be run at the end +# (there may be multiple occurrences of this, they are concatenated) +# (unbalanced braces must be \-escaped) +# +# "{ target selector }" is a list of expressions that determine whether the +# test succeeds or fails for a particular target, or in some cases whether the +# option applies for a particular target. If the case of `dg-do' it specifies +# whether the test case is even attempted on the specified target. +# +# The target selector is always optional. The format is one of: +# +# { xfail *-*-* ... } - the test is expected to fail for the given targets +# { target *-*-* ... } - the option only applies to the given targets +# +# At least one target must be specified, use *-*-* for "all targets". +# At present it is not possible to specify both `xfail' and `target'. +# "native" may be used in place of "*-*-*". + +Example 1: Testing compilation only +// { dg-do compile } + +Example 2: Testing for expected warnings on line 36, which all targets fail +// { dg-warning "string literals" "" { xfail *-*-* } 36 + +Example 3: Testing for expected warnings on line 36 +// { dg-warning "string literals" "" { target *-*-* } 36 + +Example 4: Testing for compilation errors on line 41 +// { dg-do compile } +// { dg-error "no match for" "" { target *-*-* } 41 } + +Example 5: Testing with special command line settings, or without the +use of pre-compiled headers, in particular the stdc++.h.gch file. Any +options here will override the DEFAULT_CXXFLAGS and PCH_CXXFLAGS set +up in the normal.exp file. +// { dg-options "-O0" { target *-*-* } } +</pre><p> + More examples can be found in the libstdc++-v3/testsuite/*/*.cc files. + </p></div><div class="section" title="Test Harness and Utilities"><div class="titlepage"><div><div><h3 class="title"><a id="test.harness"/>Test Harness and Utilities</h3></div></div></div><div class="section" title="Dejagnu Harness Details"><div class="titlepage"><div><div><h4 class="title"><a id="test.harness.dejagnu"/>Dejagnu Harness Details</h4></div></div></div><p> + Underlying details of testing for conformance and regressions are + abstracted via the GNU Dejagnu package. This is similar to the + rest of GCC. + </p><p>This is information for those looking at making changes to the testsuite +structure, and/or needing to trace dejagnu's actions with --verbose. This +will not be useful to people who are "merely" adding new tests to the existing +structure. +</p><p>The first key point when working with dejagnu is the idea of a "tool". +Files, directories, and functions are all implicitly used when they are +named after the tool in use. Here, the tool will always be "libstdc++". +</p><p>The <code class="code">lib</code> subdir contains support routines. The +<code class="code">lib/libstdc++.exp</code> file ("support library") is loaded +automagically, and must explicitly load the others. For example, files can +be copied from the core compiler's support directory into <code class="code">lib</code>. +</p><p>Some routines in <code class="code">lib/libstdc++.exp</code> are callbacks, some are +our own. Callbacks must be prefixed with the name of the tool. To easily +distinguish the others, by convention our own routines are named "v3-*". +</p><p>The next key point when working with dejagnu is "test files". Any +directory whose name starts with the tool name will be searched for test files. +(We have only one.) In those directories, any <code class="code">.exp</code> file is +considered a test file, and will be run in turn. Our main test file is called +<code class="code">normal.exp</code>; it runs all the tests in testsuite_files using the +callbacks loaded from the support library. +</p><p>The <code class="code">config</code> directory is searched for any particular "target +board" information unique to this library. This is currently unused and sets +only default variables. +</p></div><div class="section" title="Utilities"><div class="titlepage"><div><div><h4 class="title"><a id="test.harness.utils"/>Utilities</h4></div></div></div><p> + </p><p> + The testsuite directory also contains some files that implement + functionality that is intended to make writing test cases easier, + or to avoid duplication, or to provide error checking in a way that + is consistent across platforms and test harnesses. A stand-alone + executable, called <span class="emphasis"><em>abi_check</em></span>, and a static + library called <span class="emphasis"><em>libtestc++</em></span> are + constructed. Both of these items are not installed, and only used + during testing. + </p><p> + These files include the following functionality: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + <span class="emphasis"><em>testsuite_abi.h</em></span>, + <span class="emphasis"><em>testsuite_abi.cc</em></span>, + <span class="emphasis"><em>testsuite_abi_check.cc</em></span> + </p><p> + Creates the executable <span class="emphasis"><em>abi_check</em></span>. + Used to check correctness of symbol versioning, visibility of + exported symbols, and compatibility on symbols in the shared + library, for hosts that support this feature. More information + can be found in the ABI documentation <a class="link" href="abi.html" title="ABI Policy and Guidelines">here</a> + </p></li><li class="listitem"><p> + <span class="emphasis"><em>testsuite_allocator.h</em></span>, + <span class="emphasis"><em>testsuite_allocator.cc</em></span> + </p><p> + Contains specialized allocators that keep track of construction + and destruction. Also, support for overriding global new and + delete operators, including verification that new and delete + are called during execution, and that allocation over max_size + fails. + </p></li><li class="listitem"><p> + <span class="emphasis"><em>testsuite_character.h</em></span> + </p><p> + Contains <code class="code">std::char_traits</code> and + <code class="code">std::codecvt</code> specializations for a user-defined + POD. + </p></li><li class="listitem"><p> + <span class="emphasis"><em>testsuite_hooks.h</em></span>, + <span class="emphasis"><em>testsuite_hooks.cc</em></span> + </p><p> + A large number of utilities, including: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>VERIFY</p></li><li class="listitem"><p>set_memory_limits</p></li><li class="listitem"><p>verify_demangle</p></li><li class="listitem"><p>run_tests_wrapped_locale</p></li><li class="listitem"><p>run_tests_wrapped_env</p></li><li class="listitem"><p>try_named_locale</p></li><li class="listitem"><p>try_mkfifo</p></li><li class="listitem"><p>func_callback</p></li><li class="listitem"><p>counter</p></li><li class="listitem"><p>copy_tracker</p></li><li class="listitem"><p>copy_constructor</p></li><li class="listitem"><p>assignment_operator</p></li><li class="listitem"><p>destructor</p></li><li class="listitem"><p>pod_char, pod_int and associated char_traits specializations</p></li></ul></div></li><li class="listitem"><p> + <span class="emphasis"><em>testsuite_io.h</em></span> + </p><p> + Error, exception, and constraint checking for + <code class="code">std::streambuf, std::basic_stringbuf, std::basic_filebuf</code>. + </p></li><li class="listitem"><p> + <span class="emphasis"><em>testsuite_iterators.h</em></span> + </p><p> + Wrappers for various iterators. + </p></li><li class="listitem"><p> + <span class="emphasis"><em>testsuite_performance.h</em></span> + </p><p> + A number of class abstractions for performance counters, and + reporting functions including: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>time_counter</p></li><li class="listitem"><p>resource_counter</p></li><li class="listitem"><p>report_performance</p></li></ul></div></li></ul></div></div></div><div class="section" title="Special Topics"><div class="titlepage"><div><div><h3 class="title"><a id="test.special"/>Special Topics</h3></div></div></div><div class="section" title="Qualifying Exception Safety Guarantees"><div class="titlepage"><div><div><h4 class="title"><a id="test.exception.safety"/> + Qualifying Exception Safety Guarantees + <a id="id498690" class="indexterm"/> +</h4></div></div></div><div class="section" title="Overview"><div class="titlepage"><div><div><h5 class="title"><a id="test.exception.safety.overview"/>Overview</h5></div></div></div><p> + Testing is composed of running a particular test sequence, + and looking at what happens to the surrounding code when + exceptions are thrown. Each test is composed of measuring + initial state, executing a particular sequence of code under + some instrumented conditions, measuring a final state, and + then examining the differences between the two states. + </p><p> + Test sequences are composed of constructed code sequences + that exercise a particular function or member function, and + either confirm no exceptions were generated, or confirm the + consistency/coherency of the test subject in the event of a + thrown exception. + </p><p> + Random code paths can be constructed using the basic test + sequences and instrumentation as above, only combined in a + random or pseudo-random way. + </p><p> To compute the code paths that throw, test instruments + are used that throw on allocation events + (<code class="classname">__gnu_cxx::throw_allocator_random</code> + and <code class="classname">__gnu_cxx::throw_allocator_limit</code>) + and copy, assignment, comparison, increment, swap, and + various operators + (<code class="classname">__gnu_cxx::throw_type_random</code> + and <code class="classname">__gnu_cxx::throw_type_limit</code>). Looping + through a given test sequence and conditionally throwing in + all instrumented places. Then, when the test sequence + completes without an exception being thrown, assume all + potential error paths have been exercised in a sequential + manner. + </p></div><div class="section" title="Existing tests"><div class="titlepage"><div><div><h5 class="title"><a id="test.exception.safety.status"/> + Existing tests +</h5></div></div></div><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + Ad Hoc + </p><p> + For example, + <code class="filename">testsuite/23_containers/list/modifiers/3.cc</code>. + </p></li><li class="listitem"><p> + Policy Based Data Structures + </p><p> + For example, take the test + functor <code class="classname">rand_reg_test</code> in + in <code class="filename">testsuite/ext/pb_ds/regression/tree_no_data_map_rand.cc</code>. This uses <code class="classname">container_rand_regression_test</code> in +<code class="filename">testsuite/util/regression/rand/assoc/container_rand_regression_test.h</code>. + + </p><p> + Which has several tests for container member functions, +Includes control and test container objects. Configuration includes +random seed, iterations, number of distinct values, and the +probability that an exception will be thrown. Assumes instantiating +container uses an extension +allocator, <code class="classname">__gnu_cxx::throw_allocator_random</code>, +as the allocator type. + </p></li><li class="listitem"><p> + C++0x Container Requirements. + </p><p> + Coverage is currently limited to testing container + requirements for exception safety, + although <code class="classname">__gnu_cxx::throw_type</code> meets + the additional type requirements for testing numeric data + structures and instantiating algorithms. + </p><p> + Of particular interest is extending testing to algorithms and + then to parallel algorithms. Also io and locales. + </p><p> + The test instrumentation should also be extended to add + instrumentation to <code class="classname">iterator</code> + and <code class="classname">const_iterator</code> types that throw + conditionally on iterator operations. + </p></li></ul></div></div><div class="section" title="C++0x Requirements Test Sequence Descriptions"><div class="titlepage"><div><div><h5 class="title"><a id="test.exception.safety.containers"/> +C++0x Requirements Test Sequence Descriptions +</h5></div></div></div><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + Basic + </p><p> + Basic consistency on exception propagation tests. For + each container, an object of that container is constructed, + a specific member function is exercised in + a <code class="literal">try</code> block, and then any thrown + exceptions lead to error checking in the appropriate + <code class="literal">catch</code> block. The container's use of + resources is compared to the container's use prior to the + test block. Resource monitoring is limited to allocations + made through the container's <span class="type">allocator_type</span>, + which should be sufficient for container data + structures. Included in these tests are member functions + are <span class="type">iterator</span> and <span class="type">const_iterator</span> + operations, <code class="function">pop_front</code>, <code class="function">pop_back</code>, <code class="function">push_front</code>, <code class="function">push_back</code>, <code class="function">insert</code>, <code class="function">erase</code>, <code class="function">swap</code>, <code class="function">clear</code>, + and <code class="function">rehash</code>. The container in question is + instantiated with two instrumented template arguments, + with <code class="classname">__gnu_cxx::throw_allocator_limit</code> + as the allocator type, and + with <code class="classname">__gnu_cxx::throw_type_limit</code> as + the value type. This allows the test to loop through + conditional throw points. + </p><p> + The general form is demonstrated in + <code class="filename">testsuite/23_containers/list/requirements/exception/basic.cc + </code>. The instantiating test object is <code class="classname">__gnu_test::basic_safety</code> and is detailed in <code class="filename">testsuite/util/exception/safety.h</code>. + </p></li><li class="listitem"><p> + Generation Prohibited + </p><p> + Exception generation tests. For each container, an object of + that container is constructed and all member functions + required to not throw exceptions are exercised. Included in + these tests are member functions + are <span class="type">iterator</span> and <span class="type">const_iterator</span> operations, <code class="function">erase</code>, <code class="function">pop_front</code>, <code class="function">pop_back</code>, <code class="function">swap</code>, + and <code class="function">clear</code>. The container in question is + instantiated with two instrumented template arguments, + with <code class="classname">__gnu_cxx::throw_allocator_random</code> + as the allocator type, and + with <code class="classname">__gnu_cxx::throw_type_random</code> as + the value type. This test does not loop, an instead is sudden + death: first error fails. + </p><p> + The general form is demonstrated in + <code class="filename">testsuite/23_containers/list/requirements/exception/generation_prohibited.cc + </code>. The instantiating test object is <code class="classname">__gnu_test::generation_prohibited</code> and is detailed in <code class="filename">testsuite/util/exception/safety.h</code>. + </p></li><li class="listitem"><p> + Propagation Consistent + </p><p> + Container rollback on exception propagation tests. For + each container, an object of that container is constructed, + a specific member function that requires rollback to a previous + known good state is exercised in + a <code class="literal">try</code> block, and then any thrown + exceptions lead to error checking in the appropriate + <code class="literal">catch</code> block. The container is compared to + the container's last known good state using such parameters + as size, contents, and iterator references. Included in these + tests are member functions + are <code class="function">push_front</code>, <code class="function">push_back</code>, <code class="function">insert</code>, + and <code class="function">rehash</code>. The container in question is + instantiated with two instrumented template arguments, + with <code class="classname">__gnu_cxx::throw_allocator_limit</code> + as the allocator type, and + with <code class="classname">__gnu_cxx::throw_type_limit</code> as + the value type. This allows the test to loop through + conditional throw points. + </p><p> + The general form demonstrated in + <code class="filename">testsuite/23_containers/list/requirements/exception/propagation_coherent.cc + </code>. The instantiating test object is <code class="classname">__gnu_test::propagation_coherent</code> and is detailed in <code class="filename">testsuite/util/exception/safety.h</code>. + </p></li></ul></div></div></div></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="internals.html">Prev</a> </td><td align="center"><a accesskey="u" href="appendix_porting.html">Up</a></td><td align="right"> <a accesskey="n" href="abi.html">Next</a></td></tr><tr><td align="left" valign="top">Porting to New Hardware or Operating Systems </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> ABI Policy and Guidelines</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/traits.html b/libstdc++-v3/doc/html/manual/traits.html new file mode 100644 index 000000000..4c04c7b15 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/traits.html @@ -0,0 +1,10 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Traits</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="utilities.html" title="Chapter 6. Utilities"/><link rel="prev" href="memory.html" title="Memory"/><link rel="next" href="strings.html" title="Chapter 7. Strings"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Traits</th></tr><tr><td align="left"><a accesskey="p" href="memory.html">Prev</a> </td><th width="60%" align="center">Chapter 6. + Utilities + +</th><td align="right"> <a accesskey="n" href="strings.html">Next</a></td></tr></table><hr/></div><div class="section" title="Traits"><div class="titlepage"><div><div><h2 class="title"><a id="std.util.traits"/>Traits</h2></div></div></div><p> + </p></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="memory.html">Prev</a> </td><td align="center"><a accesskey="u" href="utilities.html">Up</a></td><td align="right"> <a accesskey="n" href="strings.html">Next</a></td></tr><tr><td align="left" valign="top">Memory </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Chapter 7. + Strings + +</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/using.html b/libstdc++-v3/doc/html/manual/using.html new file mode 100644 index 000000000..f9eeb59bd --- /dev/null +++ b/libstdc++-v3/doc/html/manual/using.html @@ -0,0 +1,15 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Chapter 3. Using</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="intro.html" title="Part I. Introduction"/><link rel="prev" href="make.html" title="Make"/><link rel="next" href="using_headers.html" title="Headers"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 3. Using</th></tr><tr><td align="left"><a accesskey="p" href="make.html">Prev</a> </td><th width="60%" align="center">Part I. + Introduction + +</th><td align="right"> <a accesskey="n" href="using_headers.html">Next</a></td></tr></table><hr/></div><div class="chapter" title="Chapter 3. Using"><div class="titlepage"><div><div><h2 class="title"><a id="manual.intro.using"/>Chapter 3. Using</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="using.html#manual.intro.using.flags">Command Options</a></span></dt><dt><span class="section"><a href="using_headers.html">Headers</a></span></dt><dd><dl><dt><span class="section"><a href="using_headers.html#manual.intro.using.headers.all">Header Files</a></span></dt><dt><span class="section"><a href="using_headers.html#manual.intro.using.headers.mixing">Mixing Headers</a></span></dt><dt><span class="section"><a href="using_headers.html#manual.intro.using.headers.cheaders">The C Headers and <code class="code">namespace std</code></a></span></dt><dt><span class="section"><a href="using_headers.html#manual.intro.using.headers.pre">Precompiled Headers</a></span></dt></dl></dd><dt><span class="section"><a href="using_macros.html">Macros</a></span></dt><dt><span class="section"><a href="using_namespaces.html">Namespaces</a></span></dt><dd><dl><dt><span class="section"><a href="using_namespaces.html#manual.intro.using.namespaces.all">Available Namespaces</a></span></dt><dt><span class="section"><a href="using_namespaces.html#manual.intro.using.namespaces.std">namespace std</a></span></dt><dt><span class="section"><a href="using_namespaces.html#manual.intro.using.namespaces.comp">Using Namespace Composition</a></span></dt></dl></dd><dt><span class="section"><a href="using_dynamic_or_shared.html">Linking</a></span></dt><dd><dl><dt><span class="section"><a href="using_dynamic_or_shared.html#manual.intro.using.linkage.freestanding">Almost Nothing</a></span></dt><dt><span class="section"><a href="using_dynamic_or_shared.html#manual.intro.using.linkage.dynamic">Finding Dynamic or Shared Libraries</a></span></dt></dl></dd><dt><span class="section"><a href="using_concurrency.html">Concurrency</a></span></dt><dd><dl><dt><span class="section"><a href="using_concurrency.html#manual.intro.using.concurrency.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="using_concurrency.html#manual.intro.using.concurrency.thread_safety">Thread Safety</a></span></dt><dt><span class="section"><a href="using_concurrency.html#manual.intro.using.concurrency.atomics">Atomics</a></span></dt><dt><span class="section"><a href="using_concurrency.html#manual.intro.using.concurrency.io">IO</a></span></dt><dt><span class="section"><a href="using_concurrency.html#manual.intro.using.concurrency.containers">Containers</a></span></dt></dl></dd><dt><span class="section"><a href="using_exceptions.html">Exceptions</a></span></dt><dd><dl><dt><span class="section"><a href="using_exceptions.html#intro.using.exception.safety">Exception Safety</a></span></dt><dt><span class="section"><a href="using_exceptions.html#intro.using.exception.propagating">Exception Neutrality</a></span></dt><dt><span class="section"><a href="using_exceptions.html#intro.using.exception.no">Doing without</a></span></dt><dt><span class="section"><a href="using_exceptions.html#intro.using.exception.compat">Compatibility</a></span></dt></dl></dd><dt><span class="section"><a href="debug.html">Debugging Support</a></span></dt><dd><dl><dt><span class="section"><a href="debug.html#debug.compiler">Using <span class="command"><strong>g++</strong></span></a></span></dt><dt><span class="section"><a href="debug.html#debug.req">Debug Versions of Library Binary Files</a></span></dt><dt><span class="section"><a href="debug.html#debug.memory">Memory Leak Hunting</a></span></dt><dt><span class="section"><a href="debug.html#debug.races">Data Race Hunting</a></span></dt><dt><span class="section"><a href="debug.html#debug.gdb">Using <span class="command"><strong>gdb</strong></span></a></span></dt><dt><span class="section"><a href="debug.html#debug.exceptions">Tracking uncaught exceptions</a></span></dt><dt><span class="section"><a href="debug.html#debug.debug_mode">Debug Mode</a></span></dt><dt><span class="section"><a href="debug.html#debug.compile_time_checks">Compile Time Checking</a></span></dt><dt><span class="section"><a href="debug.html#debug.profile_mode">Profile-based Performance Analysis</a></span></dt></dl></dd></dl></div><div class="section" title="Command Options"><div class="titlepage"><div><div><h2 class="title"><a id="manual.intro.using.flags"/>Command Options</h2></div></div></div><p> + The set of features available in the GNU C++ library is shaped + by + several <a class="link" href="http://gcc.gnu.org/onlinedocs/gcc-4.3.2//gcc/Invoking-GCC.html">GCC + Command Options</a>. Options that impact libstdc++ are + enumerated and detailed in the table below. + </p><p> + By default, <span class="command"><strong>g++</strong></span> is equivalent to <span class="command"><strong>g++ -std=gnu++98</strong></span>. The standard library also defaults to this dialect. + </p><div class="table"><a id="id465910"/><p class="title"><strong>Table 3.1. C++ Command Options</strong></p><div class="table-contents"><table summary="C++ Command Options" border="1"><colgroup><col style="text-align: left" class="c1"/><col style="text-align: left" class="c2"/></colgroup><thead><tr><th style="text-align: left">Option Flags</th><th style="text-align: left">Description</th></tr></thead><tbody><tr><td style="text-align: left"><code class="literal">-std=c++98</code></td><td style="text-align: left">Use the 1998 ISO C++ standard plus amendments.</td></tr><tr><td style="text-align: left"><code class="literal">-std=gnu++98</code></td><td style="text-align: left">As directly above, with GNU extensions.</td></tr><tr><td style="text-align: left"><code class="literal">-std=c++0x</code></td><td style="text-align: left">Use the working draft of the upcoming ISO C++0x standard.</td></tr><tr><td style="text-align: left"><code class="literal">-std=gnu++0x</code></td><td style="text-align: left">As directly above, with GNU extensions.</td></tr><tr><td style="text-align: left"><code class="literal">-fexceptions</code></td><td style="text-align: left">See <a class="link" href="using_exceptions.html#intro.using.exception.no" title="Doing without">exception-free dialect</a></td></tr><tr><td style="text-align: left"><code class="literal">-frtti</code></td><td style="text-align: left">As above, but RTTI-free dialect.</td></tr><tr><td style="text-align: left"><code class="literal">-pthread</code> or <code class="literal">-pthreads</code></td><td style="text-align: left">For ISO C++0x <thread>, <future>, + <mutex>, or <condition_variable>.</td></tr><tr><td style="text-align: left"><code class="literal">-fopenmp</code></td><td style="text-align: left">For <a class="link" href="parallel_mode.html" title="Chapter 18. Parallel Mode">parallel</a> mode.</td></tr></tbody></table></div></div><br class="table-break"/></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="make.html">Prev</a> </td><td align="center"><a accesskey="u" href="intro.html">Up</a></td><td align="right"> <a accesskey="n" href="using_headers.html">Next</a></td></tr><tr><td align="left" valign="top">Make </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Headers</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/using_concurrency.html b/libstdc++-v3/doc/html/manual/using_concurrency.html new file mode 100644 index 000000000..a0ca2a651 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/using_concurrency.html @@ -0,0 +1,205 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Concurrency</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="using.html" title="Chapter 3. Using"/><link rel="prev" href="using_dynamic_or_shared.html" title="Linking"/><link rel="next" href="using_exceptions.html" title="Exceptions"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Concurrency</th></tr><tr><td align="left"><a accesskey="p" href="using_dynamic_or_shared.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td align="right"> <a accesskey="n" href="using_exceptions.html">Next</a></td></tr></table><hr/></div><div class="section" title="Concurrency"><div class="titlepage"><div><div><h2 class="title"><a id="manual.intro.using.concurrency"/>Concurrency</h2></div></div></div><p>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. + </p><div class="section" title="Prerequisites"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.concurrency.prereq"/>Prerequisites</h3></div></div></div><p>All normal disclaimers aside, multithreaded C++ application are + only supported when libstdc++ and all user code was built with + compilers which report (via <code class="code"> gcc/g++ -v </code>) the same thread + model and that model is not <span class="emphasis"><em>single</em></span>. 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 + <span class="emphasis"><em>single</em></span> 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.) + </p><p>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). + </p></div><div class="section" title="Thread Safety"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.concurrency.thread_safety"/>Thread Safety</h3></div></div></div><p> +We currently use the <a class="link" href="http://www.sgi.com/tech/stl/thread_safety.html">SGI STL</a> definition of thread safety. +</p><p>The library strives to be thread-safe when all of the following + conditions are met: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>The system's libc is itself thread-safe, + </p></li><li class="listitem"><p> + The compiler in use reports a thread model other than + 'single'. This can be tested via output from <code class="code">gcc + -v</code>. Multi-thread capable versions of gcc output + something like this: + </p><pre class="programlisting"> +%gcc -v +Using built-in specs. +... +Thread model: posix +gcc version 4.1.2 20070925 (Red Hat 4.1.2-33) +</pre><p>Look for "Thread model" lines that aren't equal to "single."</p></li><li class="listitem"><p> + Requisite command-line flags are used for atomic operations + and threading. Examples of this include <code class="code">-pthread</code> + and <code class="code">-march=native</code>, although specifics vary + depending on the host environment. See <a class="link" href="http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html">Machine + Dependent Options</a>. + </p></li><li class="listitem"><p> + An implementation of atomicity.h functions + exists for the architecture in question. See the internals documentation for more <a class="link" href="internals.html#internals.thread_safety" title="Thread Safety">details</a>. + </p></li></ul></div><p>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: + </p><pre class="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.</pre><p>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: + </p><pre class="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 (); + } </pre><p>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. + </p></div><div class="section" title="Atomics"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.concurrency.atomics"/>Atomics</h3></div></div></div><p> + </p></div><div class="section" title="IO"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.concurrency.io"/>IO</h3></div></div></div><p>This gets a bit tricky. Please read carefully, and bear with me. + </p><div class="section" title="Structure"><div class="titlepage"><div><div><h4 class="title"><a id="concurrency.io.structure"/>Structure</h4></div></div></div><p>A wrapper + type called <code class="code">__basic_file</code> provides our abstraction layer + for the <code class="code">std::filebuf</code> classes. Nearly all decisions dealing + with actual input and output must be made in <code class="code">__basic_file</code>. + </p><p>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). + </p></div><div class="section" title="Defaults"><div class="titlepage"><div><div><h4 class="title"><a id="concurrency.io.defaults"/>Defaults</h4></div></div></div><p>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 class="code">fopen</code>, + <code class="code">fwrite</code>, and so forth. + </p><p>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. + </p><p>(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 class="code">fclose(fs)</code> in one thread followed by an access of + <code class="code">fs</code> in another.) + </p><p>So, if your platform's C library is threadsafe, then your + <code class="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 class="code">std::ofstream</code>), you need to guard such accesses + like any other critical shared resource. + </p></div><div class="section" title="Future"><div class="titlepage"><div><div><h4 class="title"><a id="concurrency.io.future"/>Future</h4></div></div></div><p> 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. + </p><p>The libio code is a subset of the guts of the GNU libc (glibc) I/O + implementation. When libio is in use, the <code class="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 class="code">fread</code>, <code class="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*) + </p><p>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. + </p><p>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++. + </p></div><div class="section" title="Alternatives"><div class="titlepage"><div><div><h4 class="title"><a id="concurrency.io.alt"/>Alternatives</h4></div></div></div><p>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. + </p></div></div><div class="section" title="Containers"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.concurrency.containers"/>Containers</h3></div></div></div><p>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. + </p><p>Two excellent pages to read when working with the Standard C++ + containers and threads are + <a class="link" href="http://www.sgi.com/tech/stl/thread_safety.html">SGI's + http://www.sgi.com/tech/stl/thread_safety.html</a> and + <a class="link" href="http://www.sgi.com/tech/stl/Allocators.html">SGI's + http://www.sgi.com/tech/stl/Allocators.html</a>. + </p><p><span class="emphasis"><em>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.</em></span> + </p><p>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 + (<span class="emphasis"><em>For most clients...</em></span>), 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). + </p><p>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 <span class="emphasis"><em>to a certain + extent</em></span>, 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. + </p><p>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 <a class="link" href="using_macros.html" title="Macros">here</a>. Also + useful are details + on <a class="link" href="memory.html#std.util.memory.allocator" title="Allocators">allocator</a> + options and capabilities. + </p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="using_dynamic_or_shared.html">Prev</a> </td><td align="center"><a accesskey="u" href="using.html">Up</a></td><td align="right"> <a accesskey="n" href="using_exceptions.html">Next</a></td></tr><tr><td align="left" valign="top">Linking </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Exceptions</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/using_dynamic_or_shared.html b/libstdc++-v3/doc/html/manual/using_dynamic_or_shared.html new file mode 100644 index 000000000..6ca06caa7 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/using_dynamic_or_shared.html @@ -0,0 +1,109 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Linking</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="using.html" title="Chapter 3. Using"/><link rel="prev" href="using_namespaces.html" title="Namespaces"/><link rel="next" href="using_concurrency.html" title="Concurrency"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Linking</th></tr><tr><td align="left"><a accesskey="p" href="using_namespaces.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td align="right"> <a accesskey="n" href="using_concurrency.html">Next</a></td></tr></table><hr/></div><div class="section" title="Linking"><div class="titlepage"><div><div><h2 class="title"><a id="manual.intro.using.linkage"/>Linking</h2></div></div></div><div class="section" title="Almost Nothing"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.linkage.freestanding"/>Almost Nothing</h3></div></div></div><p> + 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: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + <code class="filename">cstdarg</code> + </p></li><li class="listitem"><p> + <code class="filename">cstddef</code> + </p></li><li class="listitem"><p> + <code class="filename">cstdlib</code> + </p></li><li class="listitem"><p> + <code class="filename">exception</code> + </p></li><li class="listitem"><p> + <code class="filename">limits</code> + </p></li><li class="listitem"><p> + <code class="filename">new</code> + </p></li><li class="listitem"><p> + <code class="filename">exception</code> + </p></li><li class="listitem"><p> + <code class="filename">typeinfo</code> + </p></li></ul></div><p> + In addition, throw in + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + <code class="filename">cxxabi.h</code>. + </p></li></ul></div><p> + In the + C++0x <a class="link" href="using.html#manual.intro.using.flags" title="Command Options">dialect</a> add + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + <code class="filename">initializer_list</code> + </p></li><li class="listitem"><p> + <code class="filename">type_traits</code> + </p></li></ul></div><p> There exists a library that offers runtime support for + just these headers, and it is called + <code class="filename">libsupc++.a</code>. To use it, compile with <span class="command"><strong>gcc</strong></span> instead of <span class="command"><strong>g++</strong></span>, like so: + </p><p> + <span class="command"><strong>gcc foo.cc -lsupc++</strong></span> + </p><p> + 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. + </p></div><div class="section" title="Finding Dynamic or Shared Libraries"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.linkage.dynamic"/>Finding Dynamic or Shared Libraries</h3></div></div></div><p> + If the only library built is the static library + (<code class="filename">libstdc++.a</code>), or if + specifying static linking, this section is can be skipped. But + if building or using a shared library + (<code class="filename">libstdc++.so</code>), then + additional location information will need to be provided. + </p><p> + But how? + </p><p> +A quick read of the relevant part of the GCC + manual, <a class="link" href="http://gcc.gnu.org/onlinedocs/gcc/Invoking-G_002b_002b.html#Invoking-G_002b_002b">Compiling + C++ Programs</a>, specifies linking against a C++ + library. More details from the + GCC <a class="link" href="http://gcc.gnu.org/faq.html#rpath">FAQ</a>, + which states <span class="emphasis"><em>GCC does not, by default, specify a + location so that the dynamic linker can find dynamic libraries at + runtime.</em></span> + </p><p> + Users will have to provide this information. + </p><p> + Methods vary for different platforms and different styles, and + are printed to the screen during installation. To summarize: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + At runtime set <code class="literal">LD_LIBRARY_PATH</code> 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 <code class="literal">LD_LIBRARY_PATH</code> first. + </p></li><li class="listitem"><p> + Compile the path to find the library at runtime into the + program. This can be done by passing certain options to + <span class="command"><strong>g++</strong></span>, which will in turn pass them on to + the linker. The exact format of the options is dependent on + which linker you use: + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + GNU ld (default on Linux): + <code class="literal">-Wl,-rpath,</code><code class="filename">destdir/lib</code> + </p></li><li class="listitem"><p> + IRIX ld: + <code class="literal">-Wl,-rpath,</code><code class="filename">destdir/lib</code> + </p></li><li class="listitem"><p> + Solaris ld: + <code class="literal">-Wl,-R</code><code class="filename">destdir/lib</code> + </p></li></ul></div></li><li class="listitem"><p> + Some linkers allow you to specify the path to the library by + setting <code class="literal">LD_RUN_PATH</code> in your environment + when linking. + </p></li><li class="listitem"><p> + On some platforms the system administrator can configure the + dynamic linker to always look for libraries in + <code class="filename">destdir/lib</code>, for example + by using the <span class="command"><strong>ldconfig</strong></span> utility on Linux + or the <span class="command"><strong>crle</strong></span> 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. + </p></li></ul></div><p> + Use the <span class="command"><strong>ldd</strong></span> utility on the linked executable + to show + which <code class="filename">libstdc++.so</code> + library the system will get at runtime. + </p><p> + A <code class="filename">libstdc++.la</code> file is + also installed, for use with Libtool. If you use Libtool to + create your executables, these details are taken care of for + you. + </p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="using_namespaces.html">Prev</a> </td><td align="center"><a accesskey="u" href="using.html">Up</a></td><td align="right"> <a accesskey="n" href="using_concurrency.html">Next</a></td></tr><tr><td align="left" valign="top">Namespaces </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Concurrency</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/using_exceptions.html b/libstdc++-v3/doc/html/manual/using_exceptions.html new file mode 100644 index 000000000..d1e2693ab --- /dev/null +++ b/libstdc++-v3/doc/html/manual/using_exceptions.html @@ -0,0 +1,307 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Exceptions</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" C++ , exception , error , exception neutrality , exception safety , exception propagation , -fno-exceptions "/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="using.html" title="Chapter 3. Using"/><link rel="prev" href="using_concurrency.html" title="Concurrency"/><link rel="next" href="debug.html" title="Debugging Support"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Exceptions</th></tr><tr><td align="left"><a accesskey="p" href="using_concurrency.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td align="right"> <a accesskey="n" href="debug.html">Next</a></td></tr></table><hr/></div><div class="section" title="Exceptions"><div class="titlepage"><div><div><h2 class="title"><a id="manual.intro.using.exceptions"/>Exceptions</h2></div></div></div><p> +The C++ language provides language support for stack unwinding +with <code class="literal">try</code> and <code class="literal">catch</code> blocks and +the <code class="literal">throw</code> keyword. +</p><p> +These are very powerful constructs, and require some thought when +applied to the standard library in order to yield components that work +efficiently while cleaning up resources when unexpectedly killed via +exceptional circumstances. +</p><p> +Two general topics of discussion follow: +exception neutrality and exception safety. +</p><div class="section" title="Exception Safety"><div class="titlepage"><div><div><h3 class="title"><a id="intro.using.exception.safety"/>Exception Safety</h3></div></div></div><p> + What is exception-safe code? + </p><p> + Will define this as reasonable and well-defined behavior by classes + and functions from the standard library when used by user-defined + classes and functions that are themselves exception safe. + </p><p> + Please note that using exceptions in combination with templates + imposes an additional requirement for exception + safety. Instantiating types are required to have destructors that + do no throw. + </p><p> + Using the layered approach from Abrahams, can classify library + components as providing set levels of safety. These will be called + exception guarantees, and can be divided into three categories. + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + One. Don't throw. + </p><p> + As specified in 23.2.1 general container requirements. Applicable + to container and string classes. + </p><p> + Member + functions <code class="function">erase</code>, <code class="function">pop_back</code>, <code class="function">pop_front</code>, <code class="function">swap</code>, <code class="function">clear</code>. And <span class="type">iterator</span> + copy constructor and assignment operator. + </p></li><li class="listitem"><p> + Two. Don't leak resources when exceptions are thrown. This is + also referred to as the <span class="quote">“<span class="quote">basic</span>”</span> exception safety guarantee. + </p><p> + This applicable throughout the standard library. + </p></li><li class="listitem"><p> + Three. Commit-or-rollback semantics. This is + referred to as <span class="quote">“<span class="quote">strong</span>”</span> exception safety guarantee. + </p><p> + As specified in 23.2.1 general container requirements. Applicable + to container and string classes. + </p><p> + Member functions <code class="function">insert</code> of a single + element, <code class="function">push_back</code>, <code class="function">push_front</code>, + and <code class="function">rehash</code>. + </p></li></ul></div></div><div class="section" title="Exception Neutrality"><div class="titlepage"><div><div><h3 class="title"><a id="intro.using.exception.propagating"/>Exception Neutrality</h3></div></div></div><p> + Simply put, once thrown an exception object should continue in + flight unless handled explicitly. In practice, this means + propagating exceptions should not be swallowed in + gratuitous <code class="literal">catch(...)</code> blocks. Instead, + matching <code class="literal">try</code> and <code class="literal">catch</code> + blocks should have specific catch handlers and allow un-handed + exception objects to propagate. If a + terminating <code class="literal">catch(...)</code> blocks exist then it + should end with a <code class="literal">throw</code> to re-throw the current + exception. + </p><p> + Why do this? + </p><p> + By allowing exception objects to propagate, a more flexible + approach to error handling is made possible (although not + required.) Instead of dealing with an error immediately, one can + allow the exception to propagate up until sufficient context is + available and the choice of exiting or retrying can be made in an + informed manner. + </p><p> + Unfortunately, this tends to be more of a guideline than a strict + rule as applied to the standard library. As such, the following is + a list of known problem areas where exceptions are not propagated. + </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p> + Input/Output + </p><p> + The destructor <code class="function">ios_base::Init::~Init()</code> + swallows all exceptions from <code class="function">flush</code> called on + all open streams at termination. + </p><p> + All formatted input in <code class="classname">basic_istream</code> or + formatted output in <code class="classname">basic_ostream</code> can be + configured to swallow exceptions + when <code class="function">exceptions</code> is set to + ignore <span class="type">ios_base::badbit</span>. + </p><p> + Functions that have been registered + with <code class="function">ios_base::register_callback</code> swallow all + exceptions when called as part of a callback event. + </p><p> + When closing the underlying + file, <code class="function">basic_filebuf::close</code> will swallow + (non-cancellation) exceptions thrown and return <code class="literal">NULL</code>. + </p></li><li class="listitem"><p> + Thread + </p><p> + The constructors of <code class="classname">thread</code> that take a + callable function argument swallow all exceptions resulting from + executing the function argument. + </p></li></ul></div></div><div class="section" title="Doing without"><div class="titlepage"><div><div><h3 class="title"><a id="intro.using.exception.no"/>Doing without</h3></div></div></div><p> + C++ is a language that strives to be as efficient as is possible + in delivering features. As such, considerable care is used by both + language implementer and designers to make sure unused features + not impose hidden or unexpected costs. The GNU system tries to be + as flexible and as configurable as possible. So, it should come as + no surprise that GNU C++ provides an optional language extension, + spelled <code class="literal">-fno-exceptions</code>, as a way to excise the + implicitly generated magic necessary to + support <code class="literal">try</code> and <code class="literal">catch</code> blocks + and thrown objects. (Language support + for <code class="literal">-fno-exceptions</code> is documented in the GNU + GCC <a class="link" href="http://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html#Code-Gen-Options">manual</a>.) + </p><p>Before detailing the library support + for <code class="literal">-fno-exceptions</code>, first a passing note on + the things lost when this flag is used: it will break exceptions + trying to pass through code compiled + with <code class="literal">-fno-exceptions</code> whether or not that code + has any <code class="literal">try</code> or <code class="literal">catch</code> + constructs. If you might have some code that throws, you shouldn't + use <code class="literal">-fno-exceptions</code>. If you have some code that + uses <code class="literal">try</code> or <code class="literal">catch</code>, you + shouldn't use <code class="literal">-fno-exceptions</code>. + </p><p> + And what it to be gained, tinkering in the back alleys with a + language like this? Exception handling overhead can be measured + in the size of the executable binary, and varies with the + capabilities of the underlying operating system and specific + configuration of the C++ compiler. On recent hardware with GNU + system software of the same age, the combined code and data size + overhead for enabling exception handling is around 7%. Of course, + if code size is of singular concern than using the appropriate + optimizer setting with exception handling enabled + (ie, <code class="literal">-Os -fexceptions</code>) may save up to twice + that, and preserve error checking. + </p><p> + So. Hell bent, we race down the slippery track, knowing the brakes + are a little soft and that the right front wheel has a tendency to + wobble at speed. Go on: detail the standard library support + for <code class="literal">-fno-exceptions</code>. + </p><p> + In sum, valid C++ code with exception handling is transformed into + a dialect without exception handling. In detailed steps: all use + of the C++ + keywords <code class="literal">try</code>, <code class="literal">catch</code>, + and <code class="literal">throw</code> in the standard library have been + permanently replaced with the pre-processor controlled equivalents + spelled <code class="literal">__try</code>, <code class="literal">__catch</code>, + and <code class="literal">__throw_exception_again</code>. They are defined + as follows. + </p><pre class="programlisting"> +#ifdef __EXCEPTIONS +# define __try try +# define __catch(X) catch(X) +# define __throw_exception_again throw +#else +# define __try if (true) +# define __catch(X) if (false) +# define __throw_exception_again +#endif +</pre><p> + In addition, for every object derived from + class <code class="classname">exception</code>, there exists a corresponding + function with C language linkage. An example: +</p><pre class="programlisting"> +#ifdef __EXCEPTIONS + void __throw_bad_exception(void) + { throw bad_exception(); } +#else + void __throw_bad_exception(void) + { abort(); } +#endif +</pre><p> + The last language feature needing to be transformed + by <code class="literal">-fno-exceptions</code> is treatment of exception + specifications on member functions. Fortunately, the compiler deals + with this by ignoring exception specifications and so no alternate + source markup is needed. +</p><p> + By using this combination of language re-specification by the + compiler, and the pre-processor tricks and the functional + indirection layer for thrown exception objects by the library, + libstdc++ files can be compiled + with <code class="literal">-fno-exceptions</code>. +</p><p> + User code that uses C++ keywords + like <code class="literal">throw</code>, <code class="literal">try</code>, + and <code class="literal">catch</code> will produce errors even if the user + code has included libstdc++ headers and is using constructs + like <code class="classname">basic_iostream</code>. Even though the standard + library has been transformed, user code may need modification. User + code that attempts or expects to do error checking on standard + library components compiled with exception handling disabled should + be evaluated and potentially made conditional. +</p><p> + Some issues remain with this approach (see bugzilla entry + 25191). Code paths are not equivalent, in + particular <code class="literal">catch</code> blocks are not evaluated. Also + problematic are <code class="literal">throw</code> expressions expecting a + user-defined throw handler. Known problem areas in the standard + library include using an instance + of <code class="classname">basic_istream</code> + with <code class="function">exceptions</code> set to specific + <span class="type">ios_base::iostate</span> conditions, or + cascading <code class="literal">catch</code> blocks that dispatch error + handling or recovery efforts based on the type of exception object + thrown. +</p><p> + Oh, and by the way: none of this hackery is at all + special. (Although perhaps well-deserving of a raised eyebrow.) + Support continues to evolve and may change in the future. Similar + and even additional techniques are used in other C++ libraries and + compilers. +</p><p> + C++ hackers with a bent for language and control-flow purity have + been successfully consoled by grizzled C veterans lamenting the + substitution of the C language keyword + <code class="literal">const</code> with the uglified + doppelganger <code class="literal">__const</code>. +</p></div><div class="section" title="Compatibility"><div class="titlepage"><div><div><h3 class="title"><a id="intro.using.exception.compat"/>Compatibility</h3></div></div></div><div class="section" title="With C"><div class="titlepage"><div><div><h4 class="title"><a id="using.exception.compat.c"/>With <code class="literal">C</code></h4></div></div></div><p> + C language code that is expecting to interoperate with C++ should be + compiled with <code class="literal">-fexceptions</code>. This will make + debugging a C language function called as part of C++-induced stack + unwinding possible. +</p><p> + In particular, unwinding into a frame with no exception handling +data will cause a runtime abort. If the unwinder runs out of unwind +info before it finds a handler, <code class="function">std::terminate()</code> +is called. +</p><p> + Please note that most development environments should take care of + getting these details right. For GNU systems, all appropriate parts + of the GNU C library are already compiled + with <code class="literal">-fexceptions</code>. +</p></div><div class="section" title="With POSIX thread cancellation"><div class="titlepage"><div><div><h4 class="title"><a id="using.exception.compat.posix"/>With <code class="literal">POSIX</code> thread cancellation</h4></div></div></div><p> + GNU systems re-use some of the exception handling mechanisms to + track control flow for <code class="literal">POSIX</code> thread cancellation. +</p><p> + Cancellation points are functions defined by POSIX as worthy of + special treatment. The standard library may use some of these + functions to implement parts of the ISO C++ standard or depend on + them for extensions. +</p><p> + Of note: +</p><p> + <code class="function">nanosleep</code>, + <code class="function">read</code>, <code class="function">write</code>, <code class="function">open</code>, <code class="function">close</code>, + and <code class="function">wait</code>. +</p><p> + The parts of libstdc++ that use C library functions marked as + cancellation points should take pains to be exception neutral. + Failing this, <code class="literal">catch</code> blocks have been augmented to + show that the POSIX cancellation object is in flight. +</p><p> + This augmentation adds a <code class="literal">catch</code> block + for <code class="classname">__cxxabiv1::__forced_unwind</code>, which is the + object representing the POSIX cancellation object. Like so: +</p><pre class="programlisting"> + catch(const __cxxabiv1::__forced_unwind&) + { + this->_M_setstate(ios_base::badbit); + throw; + } + catch(...) + { this->_M_setstate(ios_base::badbit); } +</pre></div></div><div class="bibliography" title="Bibliography"><div class="titlepage"><div><div><h3 class="title"><a id="using.exceptions.biblio"/>Bibliography</h3></div></div></div><div class="biblioentry"><a id="id470759"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + System Interface Definitions, Issue 7 (IEEE Std. 1003.1-2008) + </em>. </span><span class="pagenums"> + 2.9.5 Thread Cancellation + . </span><span class="copyright">Copyright © 2008 + The Open Group/The Institute of Electrical and Electronics + Engineers, Inc. + . </span></p></div><div class="biblioentry"><a id="id470792"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + Error and Exception Handling + </em>. </span><span class="author"><span class="firstname">David</span> <span class="surname">Abrahams </span>. </span><span class="publisher"><span class="publishername"> + Boost + . </span></span></p></div><div class="biblioentry"><a id="id470825"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + Exception-Safety in Generic Components + </em>. </span><span class="author"><span class="firstname">David</span> <span class="surname">Abrahams</span>. </span><span class="publisher"><span class="publishername"> + Boost + . </span></span></p></div><div class="biblioentry"><a id="id470858"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + Standard Library Exception Policy + </em>. </span><span class="author"><span class="firstname">Matt</span> <span class="surname">Austern</span>. </span><span class="publisher"><span class="publishername"> + WG21 N1077 + . </span></span></p></div><div class="biblioentry"><a id="id470891"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + ia64 c++ abi exception handling + </em>. </span><span class="author"><span class="firstname">Richard</span> <span class="surname">Henderson</span>. </span><span class="publisher"><span class="publishername"> + GNU + . </span></span></p></div><div class="biblioentry"><a id="id470924"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + Appendix E: Standard-Library Exception Safety + </em>. </span><span class="author"><span class="firstname">Bjarne</span> <span class="surname">Stroustrup</span>. </span></p></div><div class="biblioentry"><a id="id470950"/><p><span class="citetitle"><em class="citetitle"> + Exceptional C++ + </em>. </span><span class="pagenums"> + Exception-Safety Issues and Techniques + . </span><span class="author"><span class="firstname">Herb</span> <span class="surname">Sutter</span>. </span></p></div><div class="biblioentry"><a id="id470970"/><p><span class="biblioid"> + . </span><span class="citetitle"><em class="citetitle"> + GCC Bug 25191: exception_defines.h #defines try/catch + </em>. </span></p></div></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="using_concurrency.html">Prev</a> </td><td align="center"><a accesskey="u" href="using.html">Up</a></td><td align="right"> <a accesskey="n" href="debug.html">Next</a></td></tr><tr><td align="left" valign="top">Concurrency </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Debugging Support</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/using_headers.html b/libstdc++-v3/doc/html/manual/using_headers.html new file mode 100644 index 000000000..fde253e36 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/using_headers.html @@ -0,0 +1,104 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Headers</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="using.html" title="Chapter 3. Using"/><link rel="prev" href="using.html" title="Chapter 3. Using"/><link rel="next" href="using_macros.html" title="Macros"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Headers</th></tr><tr><td align="left"><a accesskey="p" href="using.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td align="right"> <a accesskey="n" href="using_macros.html">Next</a></td></tr></table><hr/></div><div class="section" title="Headers"><div class="titlepage"><div><div><h2 class="title"><a id="manual.intro.using.headers"/>Headers</h2></div></div></div><div class="section" title="Header Files"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.headers.all"/>Header Files</h3></div></div></div><p> + 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 class="code">#include</code>'s a + header, the contents of that header become available, no matter + how. + </p><p> + That said, in practice files are used. + </p><p> + 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). + </p><p> + Two dialects of standard headers are supported, corresponding to + the 1998 standard as updated for 2003, and the draft of the + upcoming 200x standard. + </p><p> + C++98/03 include files. These are available in the default compilation mode, i.e. <code class="code">-std=c++98</code> or <code class="code">-std=gnu++98</code>. + </p><div class="table"><a id="id466139"/><p class="title"><strong>Table 3.2. C++ 1998 Library Headers</strong></p><div class="table-contents"><table summary="C++ 1998 Library Headers" border="1"><colgroup><col style="text-align: left" class="c1"/><col style="text-align: left" class="c2"/><col style="text-align: left" class="c3"/><col style="text-align: left" class="c4"/><col style="text-align: left" class="c5"/></colgroup><tbody><tr><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="filename">bitset</code></td><td style="text-align: left"><code class="filename">complex</code></td><td style="text-align: left"><code class="filename">deque</code></td><td style="text-align: left"><code class="filename">exception</code></td></tr><tr><td style="text-align: left"><code class="filename">fstream</code></td><td style="text-align: left"><code class="filename">functional</code></td><td style="text-align: left"><code class="filename">iomanip</code></td><td style="text-align: left"><code class="filename">ios</code></td><td style="text-align: left"><code class="filename">iosfwd</code></td></tr><tr><td style="text-align: left"><code class="filename">iostream</code></td><td style="text-align: left"><code class="filename">istream</code></td><td style="text-align: left"><code class="filename">iterator</code></td><td style="text-align: left"><code class="filename">limits</code></td><td style="text-align: left"><code class="filename">list</code></td></tr><tr><td style="text-align: left"><code class="filename">locale</code></td><td style="text-align: left"><code class="filename">map</code></td><td style="text-align: left"><code class="filename">memory</code></td><td style="text-align: left"><code class="filename">new</code></td><td style="text-align: left"><code class="filename">numeric</code></td></tr><tr><td style="text-align: left"><code class="filename">ostream</code></td><td style="text-align: left"><code class="filename">queue</code></td><td style="text-align: left"><code class="filename">set</code></td><td style="text-align: left"><code class="filename">sstream</code></td><td style="text-align: left"><code class="filename">stack</code></td></tr><tr><td style="text-align: left"><code class="filename">stdexcept</code></td><td style="text-align: left"><code class="filename">streambuf</code></td><td style="text-align: left"><code class="filename">string</code></td><td style="text-align: left"><code class="filename">utility</code></td><td style="text-align: left"><code class="filename">typeinfo</code></td></tr><tr><td style="text-align: left"><code class="filename">valarray</code></td><td style="text-align: left"><code class="filename">vector</code></td><td class="auto-generated"> </td><td class="auto-generated"> </td><td class="auto-generated"> </td></tr></tbody></table></div></div><br class="table-break"/><p/><div class="table"><a id="id466443"/><p class="title"><strong>Table 3.3. C++ 1998 Library Headers for C Library Facilities</strong></p><div class="table-contents"><table summary="C++ 1998 Library Headers for C Library Facilities" border="1"><colgroup><col style="text-align: left" class="c1"/><col style="text-align: left" class="c2"/><col style="text-align: left" class="c3"/><col style="text-align: left" class="c4"/><col style="text-align: left" class="c5"/></colgroup><tbody><tr><td style="text-align: left"><code class="filename">cassert</code></td><td style="text-align: left"><code class="filename">cerrno</code></td><td style="text-align: left"><code class="filename">cctype</code></td><td style="text-align: left"><code class="filename">cfloat</code></td><td style="text-align: left"><code class="filename">ciso646</code></td></tr><tr><td style="text-align: left"><code class="filename">climits</code></td><td style="text-align: left"><code class="filename">clocale</code></td><td style="text-align: left"><code class="filename">cmath</code></td><td style="text-align: left"><code class="filename">csetjmp</code></td><td style="text-align: left"><code class="filename">csignal</code></td></tr><tr><td style="text-align: left"><code class="filename">cstdarg</code></td><td style="text-align: left"><code class="filename">cstddef</code></td><td style="text-align: left"><code class="filename">cstdio</code></td><td style="text-align: left"><code class="filename">cstdlib</code></td><td style="text-align: left"><code class="filename">cstring</code></td></tr><tr><td style="text-align: left"><code class="filename">ctime</code></td><td style="text-align: left"><code class="filename">cwchar</code></td><td style="text-align: left"><code class="filename">cwctype</code></td><td class="auto-generated"> </td><td class="auto-generated"> </td></tr></tbody></table></div></div><br class="table-break"/><p> +C++0x include files. These are only available in C++0x compilation +mode, i.e. <code class="literal">-std=c++0x</code> or <code class="literal">-std=gnu++0x</code>. +</p><p/><div class="table"><a id="id466649"/><p class="title"><strong>Table 3.4. C++ 200x Library Headers</strong></p><div class="table-contents"><table summary="C++ 200x Library Headers" border="1"><colgroup><col style="text-align: left" class="c1"/><col style="text-align: left" class="c2"/><col style="text-align: left" class="c3"/><col style="text-align: left" class="c4"/><col style="text-align: left" class="c5"/></colgroup><tbody><tr><td style="text-align: left"><code class="filename">algorithm</code></td><td style="text-align: left"><code class="filename">array</code></td><td style="text-align: left"><code class="filename">bitset</code></td><td style="text-align: left"><code class="filename">chrono</code></td><td style="text-align: left"><code class="filename">complex</code></td></tr><tr><td style="text-align: left"><code class="filename">condition_variable</code></td><td style="text-align: left"><code class="filename">deque</code></td><td style="text-align: left"><code class="filename">exception</code></td><td style="text-align: left"><code class="filename">forward_list</code></td><td style="text-align: left"><code class="filename">fstream</code></td></tr><tr><td style="text-align: left"><code class="filename">functional</code></td><td style="text-align: left"><code class="filename">future</code></td><td style="text-align: left"><code class="filename">initalizer_list</code></td><td style="text-align: left"><code class="filename">iomanip</code></td><td style="text-align: left"><code class="filename">ios</code></td></tr><tr><td style="text-align: left"><code class="filename">iosfwd</code></td><td style="text-align: left"><code class="filename">iostream</code></td><td style="text-align: left"><code class="filename">istream</code></td><td style="text-align: left"><code class="filename">iterator</code></td><td style="text-align: left"><code class="filename">limits</code></td></tr><tr><td style="text-align: left"><code class="filename">list</code></td><td style="text-align: left"><code class="filename">locale</code></td><td style="text-align: left"><code class="filename">map</code></td><td style="text-align: left"><code class="filename">memory</code></td><td style="text-align: left"><code class="filename">mutex</code></td></tr><tr><td style="text-align: left"><code class="filename">new</code></td><td style="text-align: left"><code class="filename">numeric</code></td><td style="text-align: left"><code class="filename">ostream</code></td><td style="text-align: left"><code class="filename">queue</code></td><td style="text-align: left"><code class="filename">random</code></td></tr><tr><td style="text-align: left"><code class="filename">ratio</code></td><td style="text-align: left"><code class="filename">regex</code></td><td style="text-align: left"><code class="filename">set</code></td><td style="text-align: left"><code class="filename">sstream</code></td><td style="text-align: left"><code class="filename">stack</code></td></tr><tr><td style="text-align: left"><code class="filename">stdexcept</code></td><td style="text-align: left"><code class="filename">streambuf</code></td><td style="text-align: left"><code class="filename">string</code></td><td style="text-align: left"><code class="filename">system_error</code></td><td style="text-align: left"><code class="filename">thread</code></td></tr><tr><td style="text-align: left"><code class="filename">tuple</code></td><td style="text-align: left"><code class="filename">type_traits</code></td><td style="text-align: left"><code class="filename">typeinfo</code></td><td style="text-align: left"><code class="filename">unordered_map</code></td><td style="text-align: left"><code class="filename">unordered_set</code></td></tr><tr><td style="text-align: left"><code class="filename">utility</code></td><td style="text-align: left"><code class="filename">valarray</code></td><td style="text-align: left"><code class="filename">vector</code></td><td class="auto-generated"> </td><td class="auto-generated"> </td></tr></tbody></table></div></div><br class="table-break"/><p/><div class="table"><a id="id467078"/><p class="title"><strong>Table 3.5. C++ 200x Library Headers for C Library Facilities</strong></p><div class="table-contents"><table summary="C++ 200x Library Headers for C Library Facilities" border="1"><colgroup><col style="text-align: left" class="c1"/><col style="text-align: left" class="c2"/><col style="text-align: left" class="c3"/><col style="text-align: left" class="c4"/><col style="text-align: left" class="c5"/></colgroup><tbody><tr><td style="text-align: left"><code class="filename">cassert</code></td><td style="text-align: left"><code class="filename">ccomplex</code></td><td style="text-align: left"><code class="filename">cctype</code></td><td style="text-align: left"><code class="filename">cerrno</code></td><td style="text-align: left"><code class="filename">cfenv</code></td></tr><tr><td style="text-align: left"><code class="filename">cfloat</code></td><td style="text-align: left"><code class="filename">cinttypes</code></td><td style="text-align: left"><code class="filename">ciso646</code></td><td style="text-align: left"><code class="filename">climits</code></td><td style="text-align: left"><code class="filename">clocale</code></td></tr><tr><td style="text-align: left"><code class="filename">cmath</code></td><td style="text-align: left"><code class="filename">csetjmp</code></td><td style="text-align: left"><code class="filename">csignal</code></td><td style="text-align: left"><code class="filename">cstdarg</code></td><td style="text-align: left"><code class="filename">cstdbool</code></td></tr><tr><td style="text-align: left"><code class="filename">cstddef</code></td><td style="text-align: left"><code class="filename">cstdint</code></td><td style="text-align: left"><code class="filename">cstdlib</code></td><td style="text-align: left"><code class="filename">cstdio</code></td><td style="text-align: left"><code class="filename">cstring</code></td></tr><tr><td style="text-align: left"><code class="filename">ctgmath</code></td><td style="text-align: left"><code class="filename">ctime</code></td><td style="text-align: left"><code class="filename">cuchar</code></td><td style="text-align: left"><code class="filename">cwchar</code></td><td style="text-align: left"><code class="filename">cwctype</code></td></tr></tbody></table></div></div><br class="table-break"/><p> + In addition, TR1 includes as: +</p><div class="table"><a id="id467327"/><p class="title"><strong>Table 3.6. C++ TR 1 Library Headers</strong></p><div class="table-contents"><table summary="C++ TR 1 Library Headers" border="1"><colgroup><col style="text-align: left" class="c1"/><col style="text-align: left" class="c2"/><col style="text-align: left" class="c3"/><col style="text-align: left" class="c4"/><col style="text-align: left" class="c5"/></colgroup><tbody><tr><td style="text-align: left"><code class="filename">tr1/array</code></td><td style="text-align: left"><code class="filename">tr1/complex</code></td><td style="text-align: left"><code class="filename">tr1/memory</code></td><td style="text-align: left"><code class="filename">tr1/functional</code></td><td style="text-align: left"><code class="filename">tr1/random</code></td></tr><tr><td style="text-align: left"><code class="filename">tr1/regex</code></td><td style="text-align: left"><code class="filename">tr1/tuple</code></td><td style="text-align: left"><code class="filename">tr1/type_traits</code></td><td style="text-align: left"><code class="filename">tr1/unordered_map</code></td><td style="text-align: left"><code class="filename">tr1/unordered_set</code></td></tr><tr><td style="text-align: left"><code class="filename">tr1/utility</code></td><td class="auto-generated"> </td><td class="auto-generated"> </td><td class="auto-generated"> </td><td class="auto-generated"> </td></tr></tbody></table></div></div><br class="table-break"/><p/><div class="table"><a id="id467468"/><p class="title"><strong>Table 3.7. C++ TR 1 Library Headers for C Library Facilities</strong></p><div class="table-contents"><table summary="C++ TR 1 Library Headers for C Library Facilities" border="1"><colgroup><col style="text-align: left" class="c1"/><col style="text-align: left" class="c2"/><col style="text-align: left" class="c3"/><col style="text-align: left" class="c4"/><col style="text-align: left" class="c5"/></colgroup><tbody><tr><td style="text-align: left"><code class="filename">tr1/ccomplex</code></td><td style="text-align: left"><code class="filename">tr1/cfenv</code></td><td style="text-align: left"><code class="filename">tr1/cfloat</code></td><td style="text-align: left"><code class="filename">tr1/cmath</code></td><td style="text-align: left"><code class="filename">tr1/cinttypes</code></td></tr><tr><td style="text-align: left"><code class="filename">tr1/climits</code></td><td style="text-align: left"><code class="filename">tr1/cstdarg</code></td><td style="text-align: left"><code class="filename">tr1/cstdbool</code></td><td style="text-align: left"><code class="filename">tr1/cstdint</code></td><td style="text-align: left"><code class="filename">tr1/cstdio</code></td></tr><tr><td style="text-align: left"><code class="filename">tr1/cstdlib</code></td><td style="text-align: left"><code class="filename">tr1/ctgmath</code></td><td style="text-align: left"><code class="filename">tr1/ctime</code></td><td style="text-align: left"><code class="filename">tr1/cwchar</code></td><td style="text-align: left"><code class="filename">tr1/cwctype</code></td></tr></tbody></table></div></div><br class="table-break"/><p>Decimal floating-point arithmetic is available if the C++ +compiler supports scalar decimal floating-point types defined via +<code class="code">__attribute__((mode(SD|DD|LD)))</code>. +</p><div class="table"><a id="id467644"/><p class="title"><strong>Table 3.8. C++ TR 24733 Decimal Floating-Point Header</strong></p><div class="table-contents"><table summary="C++ TR 24733 Decimal Floating-Point Header" border="1"><colgroup><col style="text-align: left" class="c1"/></colgroup><tbody><tr><td style="text-align: left"><code class="filename">decimal/decimal</code></td></tr></tbody></table></div></div><br class="table-break"/><p> + Also included are files for the C++ ABI interface: +</p><div class="table"><a id="id467690"/><p class="title"><strong>Table 3.9. C++ ABI Headers</strong></p><div class="table-contents"><table summary="C++ ABI Headers" border="1"><colgroup><col style="text-align: left" class="c1"/><col style="text-align: left" class="c2"/></colgroup><tbody><tr><td style="text-align: left"><code class="filename">cxxabi.h</code></td><td style="text-align: left"><code class="filename">cxxabi_forced.h</code></td></tr></tbody></table></div></div><br class="table-break"/><p> + And a large variety of extensions. +</p><div class="table"><a id="id467743"/><p class="title"><strong>Table 3.10. Extension Headers</strong></p><div class="table-contents"><table summary="Extension Headers" border="1"><colgroup><col style="text-align: left" class="c1"/><col style="text-align: left" class="c2"/><col style="text-align: left" class="c3"/><col style="text-align: left" class="c4"/><col style="text-align: left" class="c5"/></colgroup><tbody><tr><td style="text-align: left"><code class="filename">ext/algorithm</code></td><td style="text-align: left"><code class="filename">ext/atomicity.h</code></td><td style="text-align: left"><code class="filename">ext/array_allocator.h</code></td><td style="text-align: left"><code class="filename">ext/bitmap_allocator.h</code></td><td style="text-align: left"><code class="filename">ext/cast.h</code></td></tr><tr><td style="text-align: left"><code class="filename">ext/codecvt_specializations.h</code></td><td style="text-align: left"><code class="filename">ext/concurrence.h</code></td><td style="text-align: left"><code class="filename">ext/debug_allocator.h</code></td><td style="text-align: left"><code class="filename">ext/enc_filebuf.h</code></td><td style="text-align: left"><code class="filename">ext/extptr_allocator.h</code></td></tr><tr><td style="text-align: left"><code class="filename">ext/functional</code></td><td style="text-align: left"><code class="filename">ext/iterator</code></td><td style="text-align: left"><code class="filename">ext/malloc_allocator.h</code></td><td style="text-align: left"><code class="filename">ext/memory</code></td><td style="text-align: left"><code class="filename">ext/mt_allocator.h</code></td></tr><tr><td style="text-align: left"><code class="filename">ext/new_allocator.h</code></td><td style="text-align: left"><code class="filename">ext/numeric</code></td><td style="text-align: left"><code class="filename">ext/numeric_traits.h</code></td><td style="text-align: left"><code class="filename">ext/pb_ds/assoc_container.h</code></td><td style="text-align: left"><code class="filename">ext/pb_ds/priority_queue.h</code></td></tr><tr><td style="text-align: left"><code class="filename">ext/pod_char_traits.h</code></td><td style="text-align: left"><code class="filename">ext/pool_allocator.h</code></td><td style="text-align: left"><code class="filename">ext/rb_tree</code></td><td style="text-align: left"><code class="filename">ext/rope</code></td><td style="text-align: left"><code class="filename">ext/slist</code></td></tr><tr><td style="text-align: left"><code class="filename">ext/stdio_filebuf.h</code></td><td style="text-align: left"><code class="filename">ext/stdio_sync_filebuf.h</code></td><td style="text-align: left"><code class="filename">ext/throw_allocator.h</code></td><td style="text-align: left"><code class="filename">ext/typelist.h</code></td><td style="text-align: left"><code class="filename">ext/type_traits.h</code></td></tr><tr><td style="text-align: left"><code class="filename">ext/vstring.h</code></td><td class="auto-generated"> </td><td class="auto-generated"> </td><td class="auto-generated"> </td><td class="auto-generated"> </td></tr></tbody></table></div></div><br class="table-break"/><p/><div class="table"><a id="id468041"/><p class="title"><strong>Table 3.11. Extension Debug Headers</strong></p><div class="table-contents"><table summary="Extension Debug Headers" border="1"><colgroup><col style="text-align: left" class="c1"/><col style="text-align: left" class="c2"/><col style="text-align: left" class="c3"/><col style="text-align: left" class="c4"/><col style="text-align: left" class="c5"/></colgroup><tbody><tr><td style="text-align: left"><code class="filename">debug/bitset</code></td><td style="text-align: left"><code class="filename">debug/deque</code></td><td style="text-align: left"><code class="filename">debug/list</code></td><td style="text-align: left"><code class="filename">debug/map</code></td><td style="text-align: left"><code class="filename">debug/set</code></td></tr><tr><td style="text-align: left"><code class="filename">debug/string</code></td><td style="text-align: left"><code class="filename">debug/unordered_map</code></td><td style="text-align: left"><code class="filename">debug/unordered_set</code></td><td style="text-align: left"><code class="filename">debug/vector</code></td><td class="auto-generated"> </td></tr></tbody></table></div></div><br class="table-break"/><p/><div class="table"><a id="id468164"/><p class="title"><strong>Table 3.12. Extension Profile Headers</strong></p><div class="table-contents"><table summary="Extension Profile Headers" border="1"><colgroup><col style="text-align: left" class="c1"/><col style="text-align: left" class="c2"/><col style="text-align: left" class="c3"/><col style="text-align: left" class="c4"/></colgroup><tbody><tr><td style="text-align: left"><code class="filename">profile/bitset</code></td><td style="text-align: left"><code class="filename">profile/deque</code></td><td style="text-align: left"><code class="filename">profile/list</code></td><td style="text-align: left"><code class="filename">profile/map</code></td></tr><tr><td style="text-align: left"><code class="filename">profile/set</code></td><td style="text-align: left"><code class="filename">profile/unordered_map</code></td><td style="text-align: left"><code class="filename">profile/unordered_set</code></td><td style="text-align: left"><code class="filename">profile/vector</code></td></tr></tbody></table></div></div><br class="table-break"/><p/><div class="table"><a id="id468275"/><p class="title"><strong>Table 3.13. Extension Parallel Headers</strong></p><div class="table-contents"><table summary="Extension Parallel Headers" border="1"><colgroup><col style="text-align: left" class="c1"/><col style="text-align: left" class="c2"/></colgroup><tbody><tr><td style="text-align: left"><code class="filename">parallel/algorithm</code></td><td style="text-align: left"><code class="filename">parallel/numeric</code></td></tr></tbody></table></div></div><br class="table-break"/></div><div class="section" title="Mixing Headers"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.headers.mixing"/>Mixing Headers</h3></div></div></div><p> A few simple rules. +</p><p>First, mixing different dialects of the standard headers is not +possible. It's an all-or-nothing affair. Thus, code like +</p><pre class="programlisting"> +#include <array> +#include <functional> +</pre><p>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. +</p><p>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 class="code">__gnu_cxx::vstring</code>, or to use the +debug-mode versions of <code class="code">std::unordered_map</code>, one must use +the <code class="code">std=gnu++0x</code> compiler flag. (Or <code class="code">std=c++0x</code>, of course.) +</p><p>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: +</p><pre class="programlisting"> +#include <tr1/type_traits> +#include <type_traits> +</pre><p> Several parts of C++0x diverge quite substantially from TR1 predecessors. +</p></div><div class="section" title="The C Headers and namespace std"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.headers.cheaders"/>The C Headers and <code class="code">namespace std</code></h3></div></div></div><p> + 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 class="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. + </p><p> +Usage of C++-style headers is recommended, as then +C-linkage names can be disambiguated by explicit qualification, such +as by <code class="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 class="code">std::sin</code> has overloads for all the builtin +floating-point types. This means that <code class="code">std::sin</code> can be +used uniformly, instead of a combination +of <code class="code">std::sinf</code>, <code class="code">std::sin</code>, +and <code class="code">std::sinl</code>. +</p></div><div class="section" title="Precompiled Headers"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.headers.pre"/>Precompiled Headers</h3></div></div></div><p>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. +</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>stdc++.h</p><p>Includes all standard headers. Actual content varies depending on +language dialect. +</p></li><li class="listitem"><p>stdtr1c++.h</p><p>Includes all of <stdc++.h>, and adds all the TR1 headers. +</p></li><li class="listitem"><p>extc++.h</p><p>Includes all of <stdtr1c++.h>, and adds all the Extension headers. +</p></li></ul></div><p>How to construct a .gch file from one of these base header files.</p><p>First, find the include directory for the compiler. One way to do +this is:</p><pre class="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. +</pre><p>Then, create a precompiled header file with the same flags that +will be used to compile other projects.</p><pre class="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 +</pre><p>The resulting file will be quite large: the current size is around +thirty megabytes. </p><p>How to use the resulting file.</p><pre class="programlisting"> +g++ -I. -include stdc++.h -H -g -O2 hello.cc +</pre><p>Verification that the PCH file is being used is easy:</p><pre class="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 +</pre><p>The exclamation point to the left of the <code class="code">stdc++.h.gch</code> listing means that the generated PCH file was used, and thus the </p><p/><p> Detailed information about creating precompiled header files can be found in the GCC <a class="link" href="http://gcc.gnu.org/onlinedocs/gcc/Precompiled-Headers.html">documentation</a>. +</p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="using.html">Prev</a> </td><td align="center"><a accesskey="u" href="using.html">Up</a></td><td align="right"> <a accesskey="n" href="using_macros.html">Next</a></td></tr><tr><td align="left" valign="top">Chapter 3. Using </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Macros</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/using_macros.html b/libstdc++-v3/doc/html/manual/using_macros.html new file mode 100644 index 000000000..3e124e909 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/using_macros.html @@ -0,0 +1,77 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Macros</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="using.html" title="Chapter 3. Using"/><link rel="prev" href="using_headers.html" title="Headers"/><link rel="next" href="using_namespaces.html" title="Namespaces"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Macros</th></tr><tr><td align="left"><a accesskey="p" href="using_headers.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td align="right"> <a accesskey="n" href="using_namespaces.html">Next</a></td></tr></table><hr/></div><div class="section" title="Macros"><div class="titlepage"><div><div><h2 class="title"><a id="manual.intro.using.macros"/>Macros</h2></div></div></div><p> + All library macros begin with <code class="code">_GLIBCXX_</code>. + </p><p> + Furthermore, all pre-processor macros, switches, and + configuration options are gathered in the + file <code class="filename">c++config.h</code>, 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. <span class="emphasis"><em>These macros cannot + be redefined</em></span>. + </p><p> + 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. + </p><p>Below is the macro which users may check for library version + information. </p><div class="variablelist"><dl><dt><span class="term"><code class="code">__GLIBCXX__</code></span></dt><dd><p>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 <a class="link" href="abi.html" title="ABI Policy and Guidelines"> + document</a>. + </p></dd></dl></div><p>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.</p><p><span class="quote">“<span class="quote">Configurable</span>”</span> (or <span class="quote">“<span class="quote">Not configurable</span>”</span>) means + that the symbol is initially chosen (or not) based on + --enable/--disable options at library build and configure time + (documented <a class="link" href="configure.html" title="Configure">here</a>), with the + various --enable/--disable choices being translated to + #define/#undef). + </p><p> <acronym class="acronym">ABI</acronym> means that changing from the default value may + mean changing the <acronym class="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 <span class="emphasis"><em>headers</em></span> may see different code + paths, but the <span class="emphasis"><em>libraries</em></span> 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. + </p><div class="variablelist"><dl><dt><span class="term"><code class="code">_GLIBCXX_USE_DEPRECATED</code></span></dt><dd><p> + 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 class="code">-std=c++98</code> and <code class="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. + </p></dd><dt><span class="term"><code class="code">_GLIBCXX_FORCE_NEW</code></span></dt><dd><p> + Undefined by default. When defined, memory allocation and + allocators controlled by libstdc++ call operator new/delete + without caching and pooling. Configurable via + <code class="code">--enable-libstdcxx-allocator</code>. ABI-changing. + </p></dd><dt><span class="term"><code class="code">_GLIBCXX_CONCEPT_CHECKS</code></span></dt><dd><p> + Undefined by default. Configurable via + <code class="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 <a class="link" href="ext_compile_checks.html" title="Chapter 16. Compile Time Checks">here</a>. + </p></dd><dt><span class="term"><code class="code">_GLIBCXX_DEBUG</code></span></dt><dd><p> + Undefined by default. When defined, compiles user code using + the <a class="link" href="debug_mode.html" title="Chapter 17. Debug Mode">debug mode</a>. + </p></dd><dt><span class="term"><code class="code">_GLIBCXX_DEBUG_PEDANTIC</code></span></dt><dd><p> + Undefined by default. When defined while compiling with + the <a class="link" href="debug_mode.html" title="Chapter 17. Debug Mode">debug mode</a>, makes + the debug mode extremely picky by making the use of libstdc++ + extensions and libstdc++-specific behavior into errors. + </p></dd><dt><span class="term"><code class="code">_GLIBCXX_PARALLEL</code></span></dt><dd><p>Undefined by default. When defined, compiles user code + using the <a class="link" href="parallel_mode.html" title="Chapter 18. Parallel Mode">parallel + mode</a>. + </p></dd><dt><span class="term"><code class="code">_GLIBCXX_PROFILE</code></span></dt><dd><p>Undefined by default. When defined, compiles user code + using the <a class="link" href="profile_mode.html" title="Chapter 19. Profile Mode">profile + mode</a>. + </p></dd></dl></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="using_headers.html">Prev</a> </td><td align="center"><a accesskey="u" href="using.html">Up</a></td><td align="right"> <a accesskey="n" href="using_namespaces.html">Next</a></td></tr><tr><td align="left" valign="top">Headers </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Namespaces</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/using_namespaces.html b/libstdc++-v3/doc/html/manual/using_namespaces.html new file mode 100644 index 000000000..ffd6c6f63 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/using_namespaces.html @@ -0,0 +1,61 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Namespaces</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="using.html" title="Chapter 3. Using"/><link rel="prev" href="using_macros.html" title="Macros"/><link rel="next" href="using_dynamic_or_shared.html" title="Linking"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Namespaces</th></tr><tr><td align="left"><a accesskey="p" href="using_macros.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td align="right"> <a accesskey="n" href="using_dynamic_or_shared.html">Next</a></td></tr></table><hr/></div><div class="section" title="Namespaces"><div class="titlepage"><div><div><h2 class="title"><a id="manual.intro.using.namespaces"/>Namespaces</h2></div></div></div><div class="section" title="Available Namespaces"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.namespaces.all"/>Available Namespaces</h3></div></div></div><p> There are three main namespaces. +</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>std</p><p>The ISO C++ standards specify that "all library entities are defined +within namespace std." This includes namespaces nested +within <code class="code">namespace std</code>, such as <code class="code">namespace +std::tr1</code>. +</p></li><li class="listitem"><p>abi</p><p>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. +</p></li><li class="listitem"><p>__gnu_</p><p>Indicating one of several GNU extensions. Choices +include <code class="code">__gnu_cxx</code>, <code class="code">__gnu_debug</code>, <code class="code">__gnu_parallel</code>, +and <code class="code">__gnu_pbds</code>. +</p></li></ul></div><p> A complete list of implementation namespaces (including namespace contents) is available in the generated source <a class="link" href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/namespaces.html">documentation</a>. +</p></div><div class="section" title="namespace std"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.namespaces.std"/>namespace std</h3></div></div></div><p> + One standard requirement is that the library components are defined + in <code class="code">namespace std::</code>. Thus, in order to use these types or + functions, one must do one of two things: +</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>put a kind of <span class="emphasis"><em>using-declaration</em></span> in your source +(either <code class="code">using namespace std;</code> or i.e. <code class="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. + </p></li><li class="listitem"><p>use a <span class="emphasis"><em>fully +qualified name</em></span> for each library symbol +(i.e. <code class="code">std::string</code>, <code class="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.) + </p></li></ul></div></div><div class="section" title="Using Namespace Composition"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.namespaces.comp"/>Using Namespace Composition</h3></div></div></div><p> +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. +</p><p>For instance, consider a project that defines most of its classes in <code class="code">namespace gtk</code>. It is possible to + adapt <code class="code">namespace gtk</code> to <code class="code">namespace std</code> by using a C++-feature called + <span class="emphasis"><em>namespace composition</em></span>. This is what happens if + a <span class="emphasis"><em>using</em></span>-declaration is put into a + namespace-definition: the imported symbol(s) gets imported into the + currently active namespace(s). For example: +</p><pre class="programlisting"> +namespace gtk +{ + using std::string; + using std::tr1::array; + + class Window { ... }; +} +</pre><p> + In this example, <code class="code">std::string</code> gets imported into + <code class="code">namespace gtk</code>. The result is that use of + <code class="code">std::string</code> inside namespace gtk can just use <code class="code">string</code>, without the explicit qualification. + As an added bonus, + <code class="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 class="code">using</code>-declarations can wrapped in macros that + are set based on autoconf-tests to either "" or i.e. <code class="code">using + std::string;</code> (depending on whether the system has + libstdc++ in <code class="code">std::</code> or not). (ideas from + Llewelly and Karl Nelson) +</p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="using_macros.html">Prev</a> </td><td align="center"><a accesskey="u" href="using.html">Up</a></td><td align="right"> <a accesskey="n" href="using_dynamic_or_shared.html">Next</a></td></tr><tr><td align="left" valign="top">Macros </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Linking</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/utilities.html b/libstdc++-v3/doc/html/manual/utilities.html new file mode 100644 index 000000000..e41e994d2 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/utilities.html @@ -0,0 +1,17 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Chapter 6. Utilities</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="bk01pt02.html" title="Part II. Standard Contents"/><link rel="prev" href="bk01pt02ch05s02.html" title="Concept Checking"/><link rel="next" href="pairs.html" title="Pairs"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 6. + Utilities + +</th></tr><tr><td align="left"><a accesskey="p" href="bk01pt02ch05s02.html">Prev</a> </td><th width="60%" align="center">Part II. + Standard Contents + </th><td align="right"> <a accesskey="n" href="pairs.html">Next</a></td></tr></table><hr/></div><div class="chapter" title="Chapter 6. Utilities"><div class="titlepage"><div><div><h2 class="title"><a id="std.util"/>Chapter 6. + Utilities + <a id="id472594" class="indexterm"/> +</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="utilities.html#std.util.functors">Functors</a></span></dt><dt><span class="section"><a href="pairs.html">Pairs</a></span></dt><dt><span class="section"><a href="memory.html">Memory</a></span></dt><dd><dl><dt><span class="section"><a href="memory.html#std.util.memory.allocator">Allocators</a></span></dt><dt><span class="section"><a href="memory.html#std.util.memory.auto_ptr">auto_ptr</a></span></dt><dt><span class="section"><a href="memory.html#std.util.memory.shared_ptr">shared_ptr</a></span></dt></dl></dd><dt><span class="section"><a href="traits.html">Traits</a></span></dt></dl></div><div class="section" title="Functors"><div class="titlepage"><div><div><h2 class="title"><a id="std.util.functors"/>Functors</h2></div></div></div><p>If you don't know what functors are, you're not alone. Many people + get slightly the wrong idea. In the interest of not reinventing + the wheel, we will refer you to the introduction to the functor + concept written by SGI as chapter of their STL, in + <a class="link" href="http://www.sgi.com/tech/stl/functors.html">their + http://www.sgi.com/tech/stl/functors.html</a>. + </p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="bk01pt02ch05s02.html">Prev</a> </td><td align="center"><a accesskey="u" href="bk01pt02.html">Up</a></td><td align="right"> <a accesskey="n" href="pairs.html">Next</a></td></tr><tr><td align="left" valign="top">Concept Checking </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Pairs</td></tr></table></div></body></html> |