</a></span></dt><dt><span class="section"><a href="manual/policy_based_data_structures_test.html#performance.branch.order_statistics">
Order-Statistics
</a></span></dt></dl></dd><dt><span class="section"><a href="manual/policy_based_data_structures_test.html#performance.multimap">Multimap</a></span></dt><dd><dl><dt><span class="section"><a href="manual/policy_based_data_structures_test.html#performance.multimap.text_find_small">
- Text <code class="function">find</code> with Small Secondary-to-Primary Key Ratios
+ Text <code class="function">find</code> with Small Secondary-to-Primary Key Ratios
</a></span></dt><dt><span class="section"><a href="manual/policy_based_data_structures_test.html#performance.multimap.text_find_large">
- Text <code class="function">find</code> with Large Secondary-to-Primary Key Ratios
+ Text <code class="function">find</code> with Large Secondary-to-Primary Key Ratios
</a></span></dt><dt><span class="section"><a href="manual/policy_based_data_structures_test.html#performance.multimap.text_insert_small">
Text <code class="function">insert</code> with Small
Secondary-to-Primary Key Ratios
<span class="command"><strong>autoconf</strong></span>) from the file
<code class="filename">configure.ac</code>.
</p><p>
- After the configure process is complete,
+ After the configure process is complete,
</p><pre class="screen">
<code class="computeroutput">
make all
<span class="command"><strong>automake</strong></span>) from the file
<code class="filename">Makefile.am</code>.
</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="build_hacking.overview.map"></a>What Comes from Where</h4></div></div></div><div class="figure"><a id="fig.build_hacking.deps"></a><p class="title"><strong>Figure B.1. Configure and Build File Dependencies</strong></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="../images/confdeps.png" 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
+ Regenerate all generated files by using the command
<span class="command"><strong>autoreconf</strong></span> at the top level of the libstdc++ source
directory.
</p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="build_hacking.configure"></a>Configure</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="build_hacking.configure.scripts"></a>Storing Information in non-AC files (like configure.host)</h4></div></div></div><p>
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-libstdcxx-visibility</code></span></dt><dd><p> In 4.2 and later, enables or disables visibility
+ </p></dd><dt><span class="term"><code class="code">--enable-libstdcxx-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, namespace std::tr2,
--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.
+ 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 templatized IO classes,
- <code class="classname">allocator</code>, and others.
+ <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.
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
+ 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>.
that are affected by the annotation macros, which can be done by
recompiling individual files.
Annotating <code class="code">std::string</code> and <code class="code">std::wstring</code>
- reference counting can be done by disabling extern templates (by defining
- <code class="code">_GLIBCXX_EXTERN_TEMPLATE=-1</code>) or by rebuilding the
+ reference counting can be done by disabling extern templates (by defining
+ <code class="code">_GLIBCXX_EXTERN_TEMPLATE=-1</code>) or by rebuilding the
<code class="filename">src/string-inst.cc</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>,
detection tools:
<a class="link" href="http://valgrind.org/docs/manual/drd-manual.html" target="_top">
DRD</a>,
- <a class="link" href="http://valgrind.org/docs/manual/hg-manual.html" target="_top">
+ <a class="link" href="http://valgrind.org/docs/manual/hg-manual.html" target="_top">
Helgrind</a>, and
- <a class="link" href="https://github.com/google/sanitizers" target="_top">
+ <a class="link" href="https://github.com/google/sanitizers" target="_top">
ThreadSanitizer</a> (this refers to ThreadSanitizer v1, not the
new "tsan" feature built-in to GCC itself).
</p><p>
the <a class="link" href="http://www.gnu.org/software/coreutils/" target="_top">GNU
coreutils</a>. (GNU versions of find, xargs, and possibly
sed and grep are used, just because the GNU versions make
- things very easy.)
+ things very easy.)
</p><p>
To generate the pretty pictures and hierarchy
graphs, the
</a></span></dt><dt><span class="section"><a href="policy_based_data_structures_test.html#performance.branch.order_statistics">
Order-Statistics
</a></span></dt></dl></dd><dt><span class="section"><a href="policy_based_data_structures_test.html#performance.multimap">Multimap</a></span></dt><dd><dl><dt><span class="section"><a href="policy_based_data_structures_test.html#performance.multimap.text_find_small">
- Text <code class="function">find</code> with Small Secondary-to-Primary Key Ratios
+ Text <code class="function">find</code> with Small Secondary-to-Primary Key Ratios
</a></span></dt><dt><span class="section"><a href="policy_based_data_structures_test.html#performance.multimap.text_find_large">
- Text <code class="function">find</code> with Large Secondary-to-Primary Key Ratios
+ Text <code class="function">find</code> with Large Secondary-to-Primary Key Ratios
</a></span></dt><dt><span class="section"><a href="policy_based_data_structures_test.html#performance.multimap.text_insert_small">
Text <code class="function">insert</code> with Small
Secondary-to-Primary Key Ratios
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> and define <code class="code">nl_catd</code> as int, but not for
-others. Fortunately, it's not heavily used and so only a minor irritant.
+others. Fortunately, it's not heavily used and so only a minor irritant.
This has been reported as a possible defect in the standard (LWG 2028).
</p><p>
Second, by making the member functions <code class="code">const</code>, it is
</a></span></dt><dt><span class="section"><a href="policy_based_data_structures_test.html#performance.branch.order_statistics">
Order-Statistics
</a></span></dt></dl></dd><dt><span class="section"><a href="policy_based_data_structures_test.html#performance.multimap">Multimap</a></span></dt><dd><dl><dt><span class="section"><a href="policy_based_data_structures_test.html#performance.multimap.text_find_small">
- Text <code class="function">find</code> with Small Secondary-to-Primary Key Ratios
+ Text <code class="function">find</code> with Small Secondary-to-Primary Key Ratios
</a></span></dt><dt><span class="section"><a href="policy_based_data_structures_test.html#performance.multimap.text_find_large">
- Text <code class="function">find</code> with Large Secondary-to-Primary Key Ratios
+ Text <code class="function">find</code> with Large Secondary-to-Primary Key Ratios
</a></span></dt><dt><span class="section"><a href="policy_based_data_structures_test.html#performance.multimap.text_insert_small">
Text <code class="function">insert</code> with Small
Secondary-to-Primary Key Ratios
with <code class="classname">Tag =</code> <code class="classname">rb_tree_tag</code> ) is
logarithmic in the number of elements. Consequently, the splay
tree has worse performance than the red-black tree.</p></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="performance.multimap"></a>Multimap</h4></div></div></div><p></p><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="performance.multimap.text_find_small"></a>
- Text <code class="function">find</code> with Small Secondary-to-Primary Key Ratios
+ Text <code class="function">find</code> with Small Secondary-to-Primary Key Ratios
</h5></div></div></div><p></p><div class="section"><div class="titlepage"><div><div><h6 class="title"><a id="multimap.text_find_small.info"></a>
Description
</h6></div></div></div><p>This test inserts a number of pairs into a container. The
Observations
</h6></div></div></div><p>See Observations::Mapping-Semantics
Considerations.</p></div></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="performance.multimap.text_find_large"></a>
- Text <code class="function">find</code> with Large Secondary-to-Primary Key Ratios
+ Text <code class="function">find</code> with Large Secondary-to-Primary Key Ratios
</h5></div></div></div><p></p><div class="section"><div class="titlepage"><div><div><h6 class="title"><a id="multimap.text_find_large.info"></a>
Description
</h6></div></div></div><p>This test inserts a number of pairs into a container. The
</a></span></dt><dt><span class="section"><a href="policy_based_data_structures_test.html#performance.branch.order_statistics">
Order-Statistics
</a></span></dt></dl></dd><dt><span class="section"><a href="policy_based_data_structures_test.html#performance.multimap">Multimap</a></span></dt><dd><dl><dt><span class="section"><a href="policy_based_data_structures_test.html#performance.multimap.text_find_small">
- Text <code class="function">find</code> with Small Secondary-to-Primary Key Ratios
+ Text <code class="function">find</code> with Small Secondary-to-Primary Key Ratios
</a></span></dt><dt><span class="section"><a href="policy_based_data_structures_test.html#performance.multimap.text_find_large">
- Text <code class="function">find</code> with Large Secondary-to-Primary Key Ratios
+ Text <code class="function">find</code> with Large Secondary-to-Primary Key Ratios
</a></span></dt><dt><span class="section"><a href="policy_based_data_structures_test.html#performance.multimap.text_insert_small">
Text <code class="function">insert</code> with Small
Secondary-to-Primary Key Ratios
Only k String DNA Hash
</strong></p><div class="equation-contents"><span class="mathphrase">
f<sub>2</sub>(s, m) = ∑ <sub>i
- = 0</sub><sup>k - 1</sup> s<sub>i</sub> a<sup>i</sup> mod m
+ = 0</sub><sup>k - 1</sup> s<sub>i</sub> a<sup>i</sup> mod m
</span></div></div><br class="equation-break" /><p>requiring scanning over only</p><p>k = log<sub>4</sub>( m )</p><p>characters.</p><p>Other more elaborate hash-functions might scan k
characters starting at a random position (determined at each
resize), or scanning k random positions (determined at
l<sub>i</sub>, and assume uniform distribution. Then</p><div class="equation"><a id="id-1.3.5.8.4.4.2.3.3.4.9"></a><p class="title"><strong>Equation 21.7.
Probability of Probe Sequence of Length k
</strong></p><div class="equation-contents"><span class="mathphrase">
- p<sub>1</sub> =
+ p<sub>1</sub> =
</span></div></div><br class="equation-break" /><p>P(l<sub>1</sub> ≥ k) =</p><p>
P(l<sub>1</sub> ≥ α ( 1 + k / α - 1) ≤ (a)
</p><p>
I(.) denote the indicator function. Then</p><div class="equation"><a id="id-1.3.5.8.4.4.2.3.3.4.14"></a><p class="title"><strong>Equation 21.8.
Probability Probe Sequence in Some Bin
</strong></p><div class="equation-contents"><span class="mathphrase">
- P( exists<sub>i</sub> l<sub>i</sub> ≥ k ) =
+ P( exists<sub>i</sub> l<sub>i</sub> ≥ k ) =
</span></div></div><br class="equation-break" /><p>P ( ∑ <sub>i = 1</sub><sup>m</sup>
I(l<sub>i</sub> ≥ k) ≥ 1 ) =</p><p>P ( ∑ <sub>i = 1</sub><sup>m</sup> I (
l<sub>i</sub> ≥ k ) ≥ m p<sub>1</sub> ( 1 + 1 / (m
be used with mod range hashing</p></li></ol></div><p>The graphic below gives an overall picture of the resize-related
classes. <code class="classname">basic_hash_table</code>
is parametrized by <code class="classname">Resize_Policy</code>, which it subclasses
- publicly. This class is currently instantiated only by <code class="classname">hash_standard_resize_policy</code>.
+ publicly. This class is currently instantiated only by <code class="classname">hash_standard_resize_policy</code>.
<code class="classname">hash_standard_resize_policy</code>
itself is parametrized by <code class="classname">Trigger_Policy</code> and
<code class="classname">Size_Policy</code>. Currently, <code class="classname">Trigger_Policy</code> is
node_end() const;
node_iterator
- node_end();
+ node_end();
</pre><p>The first pairs return node iterators corresponding to the
root node of the tree; the latter pair returns node iterators
corresponding to a just-after-leaf node.</p></div><div class="section"><div class="titlepage"><div><div><h6 class="title"><a id="container.tree.node.updator"></a>Node Updator</h6></div></div></div><p>The tree-based containers are parametrized by a
The tree defines within each node a <code class="classname">metadata_type</code>
object.</p><p><code class="classname">node_update</code> must also define the following method
for restoring node invariants:</p><pre class="programlisting">
- void
+ void
operator()(node_iterator nd_it, const_node_iterator end_nd_it)
</pre><p>In this method, <code class="varname">nd_it</code> is a
<code class="classname">node_iterator</code> corresponding to a node whose
data structure to use. Instantiating it by <code class="classname">pat_trie_tag</code>, specifies an
underlying PATRICIA trie (explained shortly); any other tag is
currently illegal.</p><p>Following is a description of a (PATRICIA) trie
- (this implementation follows <a class="xref" href="policy_data_structures.html#biblio.okasaki98mereable" title="Fast mergeable integer maps">[biblio.okasaki98mereable]</a> and
- <a class="xref" href="policy_data_structures.html#biblio.filliatre2000ptset" title="Ptset: Sets of integers implemented as Patricia trees">[biblio.filliatre2000ptset]</a>).
+ (this implementation follows <a class="xref" href="policy_data_structures.html#biblio.okasaki98mereable" title="Fast mergeable integer maps">[biblio.okasaki98mereable]</a> and
+ <a class="xref" href="policy_data_structures.html#biblio.filliatre2000ptset" title="Ptset: Sets of integers implemented as Patricia trees">[biblio.filliatre2000ptset]</a>).
</p><p>A (PATRICIA) trie is similar to a tree, but with the
following differences:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>It explicitly views keys as a sequence of elements.
E.g., a trie can view a string as a sequence of
which unconditionally move an accessed element to the front of
the list. The latter type is very useful in this library,
since there is no need to associate metadata with each element.
- (See <a class="xref" href="policy_data_structures.html#biblio.andrew04mtf" title="MTF, Bit, and COMB: A Guide to Deterministic and Randomized Algorithms for the List Update Problem">[biblio.andrew04mtf]</a>
+ (See <a class="xref" href="policy_data_structures.html#biblio.andrew04mtf" title="MTF, Bit, and COMB: A Guide to Deterministic and Randomized Algorithms for the List Update Problem">[biblio.andrew04mtf]</a>
</p></div><div class="section"><div class="titlepage"><div><div><h6 class="title"><a id="container.list.details.mapped"></a>Use in Multimaps</h6></div></div></div><p>In this library, there are no equivalents for the standard's
multimaps and multisets; instead one uses an associative
container mapping primary keys to secondary keys.</p><p>List-based containers are especially useful as associative
<code class="classname">binomial_heap_tag</code>,
<code class="classname">rc_binomial_heap_tag</code>,
or <code class="classname">thin_heap_tag</code>,
- specifies, respectively,
+ specifies, respectively,
an underlying pairing heap (<a class="xref" href="policy_data_structures.html#biblio.fredman86pairing" title="The pairing heap: a new form of self-adjusting heap">[biblio.fredman86pairing]</a>),
binary heap (<a class="xref" href="policy_data_structures.html#biblio.clrs2001" title="Introduction to Algorithms, 2nd edition">[biblio.clrs2001]</a>),
binomial heap (<a class="xref" href="policy_data_structures.html#biblio.clrs2001" title="Introduction to Algorithms, 2nd edition">[biblio.clrs2001]</a>),
heap, and so might be more appropriate for some graph
algorithms.</p></li></ol></div><p>Of course, one can use any order-preserving associative
container as a priority queue, as in the graphic above label C, possibly by creating an adapter class
- over the associative container (much as
+ over the associative container (much as
<code class="classname">std::priority_queue</code> can adapt <code class="classname">std::vector</code>).
This has the advantage that no cross-referencing is necessary
at all; the priority queue itself is an associative container.
types. <code class="classname">__gnu_pbds::priority_queue</code>
publicly defines <code class="classname">container_category</code> as one of the tags. Given any
container <code class="classname">Cntnr</code>, the tag of the underlying
- data structure can be found via <code class="classname">typename
+ data structure can be found via <code class="classname">typename
Cntnr::container_category</code>; this is one of the possible tags shown in the graphic below.
</p><div class="figure"><a id="id-1.3.5.8.4.4.6.3.4.4"></a><p class="title"><strong>Figure 21.33. Priority-Queue Data-Structure Tags.</strong></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="../images/pbds_priority_queue_tag_hierarchy.png" align="middle" alt="Priority-Queue Data-Structure Tags." /></div></div></div><br class="figure-break" /><p>Additionally, a traits mechanism can be used to query a
container type for its attributes. Given any container
<code class="classname">Cntnr</code>, then </p><pre class="programlisting">__gnu_pbds::container_traits<Cntnr></pre><p>
is a traits class identifying the properties of the
container.</p><p>To find if a container might throw if two of its objects are
- joined, one can use
+ joined, one can use
</p><pre class="programlisting">
container_traits<Cntnr>::split_join_can_throw
</pre><p>
<code class="code">begin</code>, <code class="code">end</code>, <code class="code">rbegin</code>, <code class="code">rend</code>,
<code class="code">front</code>, <code class="code">back</code>, <code class="code">data</code>,
<code class="code">find</code>, <code class="code">lower_bound</code>, <code class="code">upper_bound</code>,
- <code class="code">equal_range</code>, <code class="code">at</code>
+ <code class="code">equal_range</code>, <code class="code">at</code>
and, except in associative or unordered associative containers,
<code class="code">operator[]</code>. In other words, although they are non-const
so that they can return mutable iterators, those member functions
int i = *global_sp; // OK, operator* is const
int j = *local_sp; // OK, does not operate on global_sp
- // *global_sp = 2; // NOT OK, modifies int visible to other threads
- // *local_sp = 2; // NOT OK, modifies int visible to other threads
+ // *global_sp = 2; // NOT OK, modifies int visible to other threads
+ // *local_sp = 2; // NOT OK, modifies int visible to other threads
// global_sp.reset(); // NOT OK, reset is non-const
local_sp.reset(); // OK, does not operate on global_sp
}
</pre><p>For further details of the C++11 memory model see Hans-J. Boehm's
<a class="link" href="https://www.hboehm.info/c++mm/" target="_top">Threads
- and memory model for C++</a> pages, particularly the <a class="link" href="https://www.hboehm.info/c++mm/threadsintro.html" target="_top">introduction</a>
+ and memory model for C++</a> pages, particularly the <a class="link" href="https://www.hboehm.info/c++mm/threadsintro.html" target="_top">introduction</a>
and <a class="link" href="https://www.hboehm.info/c++mm/user-faq.html" target="_top">FAQ</a>.
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.concurrency.atomics"></a>Atomics</h3></div></div></div><p>
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.concurrency.io"></a>IO</h3></div></div></div><p>This gets a bit tricky. Please read carefully, and bear with me.
compilation errors, but will not define anything.
</p><p></p><div class="table"><a id="table.filesystemts_headers"></a><p class="title"><strong>Table 3.11. File System TS Header</strong></p><div class="table-contents"><table class="table" summary="File System TS Header" border="1"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td align="left"><code class="filename">experimental/filesystem</code></td></tr></tbody></table></div></div><br class="table-break" /><p>
<a class="xref" href="using_headers.html#table.libfundts_headers" title="Table 3.12. Library Fundamentals TS Headers">Table 3.12, “Library Fundamentals TS Headers”</a>,
-shows the additional include files define by the C++ Extensions for
+shows the additional include files define by the C++ Extensions for
Library Fundamentals Technical Specification, ISO/IEC TS 19568.
These are available in C++14 and later compilation modes.
Including these headers in earlier modes will not result in
<book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="api" xreflabel="Source Level Documentation">
-
+
<info>
<copyright>
<year>2007</year>
</copyright>
<legalnotice>
<para>
- <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="17_intro/license.html">License
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="17_intro/license.html">License
</link>
</para>
</legalnotice>
<part><info><title/></info>
<chapter><info><title/></info>
-
+
<para/>
</chapter>
</part>
<!-- Converted by db4-upgrade version 1.0 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="manual.intro" xreflabel="Introduction">
-
+
<info><title>Introduction</title>
<keywordset>
<keyword>ISO C++</keyword>
<section xml:id="manual.intro.status" xreflabel="Status"><info><title>Status</title></info>
-
+
<para>
The GNU C++ ...
</para>
</section>
<section xml:id="manual.intro.setup" xreflabel="Setup"><info><title>Setup</title></info>
-
+
<para>
The GNU C++ ...
</para>
<section xml:id="manual.intro.setup.next1" xreflabel="Next1"><info><title>Next1</title></info>
-
+
<para>
The GNU C++ ...
</para>
</section>
<section xml:id="manual.intro.setup.next2" xreflabel="Next2"><info><title>Next2</title></info>
-
+
<para>
The GNU C++ ...
</para>
- </section>
+ </section>
</section>
<section xml:id="manual.intro.using" xreflabel="Using"><info><title>Using</title></info>
-
+
<para>
The GNU C++ ...
</para>
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="manual.util.memory.allocator" xreflabel="allocator">
<?dbhtml filename="allocator.html"?>
-
+
<info><title>allocator</title>
<keywordset>
<keyword>ISO C++</keyword>
</listitem>
</itemizedlist>
- <para>
+ <para>
</para>
</section>
<para>
</para>
- <para>
+ <para>
</para>
</section>
<section><info><title>Interface Design</title></info>
-
+
<para>
</para>
-
- <para>
+
+ <para>
</para>
</section>
<section><info><title>Selecting Default Allocation Strategy</title></info>
-
- <para>
+
+ <para>
</para>
<orderedlist>
</section>
<section><info><title>Disabling Memory Caching</title></info>
-
- <para>
+
+ <para>
</para>
- <para>
+ <para>
</para>
</section>
</section>
<section xml:id="allocator.custom" xreflabel="allocator.custom"><info><title>Custom Allocators</title></info>
- <para>
+ <para>
</para>
- <para>
+ <para>
</para>
</section>
<bibliography xml:id="allocator.biblio" xreflabel="allocator.biblio">
-<info>
+<info>
<title>
Bibliography
</title>
</info>
-<!--
+<!--
<biblioentry xml:id="biblio.xxx">
<title>
<link xmlns:xlink="http://www.w3.org/1999/xlink"
</link>
</title>
<date>
-
+
</date>
<authorgroup>
-<appendix xmlns="http://docbook.org/ns/docbook" version="5.0"
+<appendix xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="appendix.gfdl-1.3">
<info><title>GNU Free Documentation License</title></info>
<?dbhtml filename="appendix_gfdl.html"?>
-
+
<simpara>Version 1.3, 3 November 2008</simpara>
<simpara>
Copyright © 2000, 2001, 2002, 2007, 2008
-<appendix xmlns="http://docbook.org/ns/docbook" version="5.0"
+<appendix xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="appendix.gpl-3.0"><info><title>
<acronym>GNU</acronym> General Public License version 3
</title></info>
<?dbhtml filename="appendix_gpl.html"?>
-
+
<para>
Version 3, 29 June 2007
</para>
-<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="appendix.porting.abi" xreflabel="abi">
<?dbhtml filename="abi.html"?>
</para>
<section xml:id="abi.versioning.goals"><info><title>Goals</title></info>
-
+
<para>Extending existing, stable ABIs. Versioning gives subsequent
releases of library binaries the ability to add new symbols and add
</section>
<section xml:id="abi.versioning.history"><info><title>History</title></info>
-
+
<para>
How can this complexity be managed? What does C++ versioning mean?
</section>
<section xml:id="abi.versioning.prereq"><info><title>Prerequisites</title></info>
-
+
<para>
Minimum environment that supports a versioned ABI: A supported
dynamic linker, a GNU linker of sufficient vintage to understand
</section>
<section xml:id="abi.versioning.config"><info><title>Configuring</title></info>
-
+
<para>
It turns out that most of the configure options that change
</section>
<section xml:id="abi.versioning.active"><info><title>Checking Active</title></info>
-
+
<para>
When the GNU C++ library is being built with symbol versioning
<section xml:id="abi.testing.single"><info><title>Single ABI Testing</title></info>
-
+
<para>
Testing for GNU C++ ABI changes is composed of two distinct
</section>
<section xml:id="abi.testing.multi"><info><title>Multiple ABI Testing</title></info>
-
+
<para>
A "C" application, dynamically linked to two shared libraries, liba,
libb. The dependent library liba is a C++ shared library compiled with
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="std.algorithms" xreflabel="Algorithms">
<?dbhtml filename="algorithms.html"?>
<!-- Sect1 02 : Mutating -->
<section xml:id="std.algorithms.mutating" xreflabel="Mutating"><info><title>Mutating</title></info>
-
+
<section xml:id="algorithms.mutating.swap" xreflabel="swap"><info><title><function>swap</function></title></info>
-
+
<section xml:id="algorithms.swap.specializations" xreflabel="Specializations"><info><title>Specializations</title></info>
-
+
<para>If you call <code> std::swap(x,y); </code> where x and y are standard
containers, then the call will automatically be replaced by a call to
-<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="std.util.memory.allocator" xreflabel="Allocator">
<?dbhtml filename="allocator.html"?>
-<appendix xmlns="http://docbook.org/ns/docbook" version="5.0"
+<appendix xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="appendix.contrib" xreflabel="Contributing">
<?dbhtml filename="appendix_contributing.html"?>
</para>
<section xml:id="contrib.list" xreflabel="Contributor Checklist"><info><title>Contributor Checklist</title></info>
-
+
<section xml:id="list.reading"><info><title>Reading</title></info>
-
+
<itemizedlist>
<listitem>
</section>
<section xml:id="list.copyright"><info><title>Assignment</title></info>
-
+
<para>
See the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/contribute.html#legal">legal prerequisites</link> for all GCC contributions.
</para>
</section>
<section xml:id="list.getting"><info><title>Getting Sources</title></info>
-
+
<para>
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/gitwrite.html">Getting write access
(look for "Write after approval")</link>
</section>
<section xml:id="list.patches"><info><title>Submitting Patches</title></info>
-
+
<para>
Every patch must have several pieces of information before it can be
<section xml:id="contrib.organization" xreflabel="Source Organization"><info><title>Directory Layout and Source Conventions</title></info>
<?dbhtml filename="source_organization.html"?>
-
+
<para>
The <filename class="directory">libstdc++-v3</filename> directory in the
<section xml:id="contrib.coding_style" xreflabel="Coding Style"><info><title>Coding Style</title></info>
<?dbhtml filename="source_code_style.html"?>
-
+
<para>
</para>
</section>
<section xml:id="coding_style.example"><info><title>By Example</title></info>
-
+
<literallayout class="normal">
This library is written to appropriate C++ coding standards. As such,
it is intended to precede the recommendations of the GNU Coding
<section xml:id="contrib.design_notes" xreflabel="Design Notes"><info><title>Design Notes</title></info>
<?dbhtml filename="source_design_notes.html"?>
-
+
<para>
</para>
-<appendix xmlns="http://docbook.org/ns/docbook" version="5.0"
+<appendix xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="appendix.free" xreflabel="Free">
<?dbhtml filename="appendix_free.html"?>
-<appendix xmlns="http://docbook.org/ns/docbook" version="5.0"
+<appendix xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="appendix.porting" xreflabel="Porting">
<?dbhtml filename="appendix_porting.html"?>
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="std.atomics" xreflabel="Atomics">
<?dbhtml filename="atomics.html"?>
<!-- Sect1 01 : API -->
<section xml:id="std.atomics.api"><info><title>API Reference</title></info>
-
+
<para>
All items are declared in the standard header
-<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="std.util.memory.auto_ptr" xreflabel="auto_ptr">
<?dbhtml filename="auto_ptr.html"?>
-<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="manual.appendix.porting.backwards" xreflabel="backwards">
<?dbhtml filename="backwards.html"?>
<para>Portability notes and known implementation limitations are as follows.</para>
<section xml:id="backwards.first.ios_base"><info><title>No <code>ios_base</code></title></info>
-
+
<para> At least some older implementations don't have <code>std::ios_base</code>, so you should use <code>std::ios::badbit</code>, <code>std::ios::failbit</code> and <code>std::ios::eofbit</code> and <code>std::ios::goodbit</code>.
</para>
</para>
<section xml:id="backwards.second.std"><info><title>Namespace <code>std::</code> not supported</title></info>
-
+
<para>
Some care is required to support C++ compiler and or library
<section xml:id="backwards.second.isspace"><info><title><code>isspace</code> from <filename class="headerfile"><cctype></filename> is a macro
</title></info>
-
+
<para>
Glibc 2.0.x and 2.1.x define <filename class="headerfile"><ctype.h></filename> functionality as macros
</section>
<section xml:id="backwards.second.wchar"><info><title>Little or no wide character support</title></info>
-
+
<para>
Classes <classname>wstring</classname> and
<classname>char_traits<wchar_t></classname> are
</section>
<section xml:id="backwards.second.iostream_templates"><info><title>No templatized iostreams</title></info>
-
+
<para>
Classes <classname>wfilebuf</classname> and
<classname>wstringstream</classname> are not supported.
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="manual.ext.allocator.bitmap" xreflabel="bitmap_allocator">
<?dbhtml filename="bitmap_allocator.html"?>
<section xml:id="bitmap.impl.free_list_store" xreflabel="Free List Store"><info><title>Free List Store</title></info>
-
+
<para>
The Free List Store (referred to as FLS for the remaining part of this
</section>
<section xml:id="bitmap.impl.super_block" xreflabel="Super Block"><info><title>Super Block</title></info>
-
+
<para>
A super block is the block of memory acquired from the FLS from
</section>
<section xml:id="bitmap.impl.super_block_data" xreflabel="Super Block Data"><info><title>Super Block Data Layout</title></info>
-
+
<para>
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
</section>
<section xml:id="bitmap.impl.max_wasted" xreflabel="Max Wasted Percentage"><info><title>Maximum Wasted Percentage</title></info>
-
+
<para>
This has nothing to do with the algorithm per-se,
</section>
<section xml:id="bitmap.impl.allocate" xreflabel="Allocate"><info><title><function>allocate</function></title></info>
-
+
<para>
The allocate function is specialized for single object allocation
</section>
<section xml:id="bitmap.impl.deallocate" xreflabel="Deallocate"><info><title><function>deallocate</function></title></info>
-
+
<para>
The deallocate function again is specialized for single objects ONLY.
For all n belonging to > 1, the operator delete is called without
</section>
<section xml:id="bitmap.impl.questions" xreflabel="Questions"><info><title>Questions</title></info>
-
+
<section xml:id="bitmap.impl.question.1" xreflabel="Question 1"><info><title>1</title></info>
-
+
<para>
Q1) The "Data Layout" section is
cryptic. I have no idea of what you are trying to say. Layout of what?
</section>
<section xml:id="bitmap.impl.question.2" xreflabel="Question 2"><info><title>2</title></info>
-
+
<para>
And since I just mentioned the
term `each bitmap', what in the world is meant by it? What does each
</section>
<section xml:id="bitmap.impl.question.3" xreflabel="Question 3"><info><title>3</title></info>
-
+
<para>
How do the allocate and deallocate functions work in regard to
bitmaps?
</section>
<section xml:id="bitmap.impl.locality" xreflabel="Locality"><info><title>Locality</title></info>
-
+
<para>
Another issue would be whether to keep the all bitmaps in a
separate area in memory, or to keep them near the actual blocks
</section>
<section xml:id="bitmap.impl.grow_policy" xreflabel="Grow Policy"><info><title>Overhead and Grow Policy</title></info>
-
+
<para>
Expected overhead per block would be 1 bit in memory. Also, once
the address of the free list has been found, the cost for
<para>
- After the configure process is complete,
+ After the configure process is complete,
</para>
<screen>
</figure>
<para>
- Regenerate all generated files by using the command
+ Regenerate all generated files by using the command
<command>autoreconf</command> at the top level of the libstdc++ source
directory.
</para>
-<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="std.localization.facet.codecvt" xreflabel="codecvt">
<?dbhtml filename="codecvt.html"?>
<section xml:id="codecvt.design.wchar_t_size"><info><title><type>wchar_t</type> Size</title></info>
-
+
<para>
The simple implementation detail of <type>wchar_t</type>'s size seems to
</section>
<section xml:id="codecvt.design.unicode"><info><title>Support for Unicode</title></info>
-
+
<para>
Probably the most frequently asked question about code conversion
is: "So dudes, what's the deal with Unicode strings?"
</section>
<section xml:id="codecvt.design.issues"><info><title>Other Issues</title></info>
-
+
<para>
In addition, multi-threaded and multi-locale environments also impact
the design and requirements for code conversions. In particular, they
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="std.concurrency" xreflabel="Concurrency">
<?dbhtml filename="concurrency.html"?>
<!-- Sect1 01 : API -->
<section xml:id="std.concurrency.api"><info><title>API Reference</title></info>
-
+
<para>
All items are declared in one of four standard header files.
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="manual.ext.concurrency" xreflabel="Concurrency Extensions">
<?dbhtml filename="ext_concurrency.html"?>
<section xml:id="manual.ext.concurrency.design" xreflabel="Design"><info><title>Design</title></info>
-
+
<section xml:id="manual.ext.concurrency.design.threads" xreflabel="Threads API"><info><title>Interface to Locks and Mutexes</title></info>
-
+
<para>The file <filename class="headerfile"><ext/concurrence.h></filename>
contains all the higher-level
</section>
<section xml:id="manual.ext.concurrency.design.atomics" xreflabel="Atomic API"><info><title>Interface to Atomic Functions</title></info>
-
+
<para>
<section xml:id="manual.ext.concurrency.impl" xreflabel="Implementation"><info><title>Implementation</title></info>
<?dbhtml filename="ext_concurrency_impl.html"?>
-
+
<section xml:id="manual.ext.concurrency.impl.atomic_fallbacks" xreflabel="Atomic F"><info><title>Using Built-in Atomic Functions</title></info>
-
+
<para>The functions for atomic operations described above are either
implemented via compiler intrinsics (if the underlying host is
</section>
<section xml:id="manual.ext.concurrency.impl.thread" xreflabel="Pthread"><info><title>Thread Abstraction</title></info>
-
+
<para>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
-<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="manual.intro.setup.configure" xreflabel="Configuring">
<?dbhtml filename="configure.html"?>
</listitem></varlistentry>
<varlistentry><term><code>--enable-libstdcxx-visibility</code></term>
- <listitem><para> In 4.2 and later, enables or disables visibility
+ <listitem><para> 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, namespace std::tr2,
<varlistentry><term><code>--enable-extern-template</code>[default]</term>
<listitem><para>Use extern template to pre-instantiate all required
- specializations for certain types defined in the standard libraries.
+ specializations for certain types defined in the standard libraries.
These types include <classname>string</classname> and dependents like
<classname>char_traits</classname>, the templatized IO classes,
- <classname>allocator</classname>, and others.
+ <classname>allocator</classname>, 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.
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="std.containers" xreflabel="Containers">
<?dbhtml filename="containers.html"?>
<!-- Sect1 01 : Sequences -->
<section xml:id="std.containers.sequences" xreflabel="Sequences"><info><title>Sequences</title></info>
<?dbhtml filename="sequences.html"?>
-
+
<section xml:id="containers.sequences.list" xreflabel="list"><info><title>list</title></info>
<?dbhtml filename="list.html"?>
-
+
<section xml:id="sequences.list.size" xreflabel="list::size() is O(n)"><info><title>list::size() is O(n)</title></info>
-
+
<para>
Yes it is, at least using the <link linkend="manual.intro.using.abi">old
ABI</link>, and that's okay. This is a decision that we preserved
<!-- Sect1 02 : Associative -->
<section xml:id="std.containers.associative" xreflabel="Associative"><info><title>Associative</title></info>
<?dbhtml filename="associative.html"?>
-
+
<section xml:id="containers.associative.insert_hints" xreflabel="Insertion Hints"><info><title>Insertion Hints</title></info>
-
+
<para>
Section [23.1.2], Table 69, of the C++ standard lists this
function for all of the associative containers (map, set, etc):
<section xml:id="containers.associative.bitset" xreflabel="bitset"><info><title>bitset</title></info>
<?dbhtml filename="bitset.html"?>
-
+
<section xml:id="associative.bitset.size_variable" xreflabel="Variable"><info><title>Size Variable</title></info>
-
+
<para>
No, you cannot write code of the form
</para>
</section>
<section xml:id="associative.bitset.type_string" xreflabel="Type String"><info><title>Type String</title></info>
-
+
<para>
</para>
<para>
<!-- Sect1 04 : Interacting with C -->
<section xml:id="std.containers.c" xreflabel="Interacting with C"><info><title>Interacting with C</title></info>
<?dbhtml filename="containers_and_c.html"?>
-
+
<section xml:id="containers.c.vs_array" xreflabel="Containers vs. Arrays"><info><title>Containers vs. Arrays</title></info>
-
+
<para>
You're writing some code and can't decide whether to use builtin
arrays or some kind of container. There are compelling reasons
-<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="std.localization.facet.ctype" xreflabel="ctype">
<?dbhtml filename="ctype.html"?>
<section xml:id="facet.ctype.impl.spec"><info><title>Specializations</title></info>
-
+
<para>
For the required specialization <classname>codecvt<wchar_t, char, mbstate_t></classname>,
-<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="manual.intro.using.debug" xreflabel="Debugging Support">
<?dbhtml filename="debug.html"?>
</para>
<para>
- Two annotation macros are used to explain low-level synchronization
+ Two annotation macros are used to explain low-level synchronization
to race detectors:
<code>_GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE()</code> and
<code> _GLIBCXX_SYNCHRONIZATION_HAPPENS_AFTER()</code>.
that are affected by the annotation macros, which can be done by
recompiling individual files.
Annotating <code>std::string</code> and <code>std::wstring</code>
- reference counting can be done by disabling extern templates (by defining
- <code>_GLIBCXX_EXTERN_TEMPLATE=-1</code>) or by rebuilding the
+ reference counting can be done by disabling extern templates (by defining
+ <code>_GLIBCXX_EXTERN_TEMPLATE=-1</code>) or by rebuilding the
<filename>src/string-inst.cc</filename> file.
Annotating the remaining atomic operations (at the time of writing these
are in <code>ios_base::Init::~Init</code>, <code>locale::_Impl</code>,
<para>
The approach described above is known to work with the following race
detection tools:
- <link xmlns:xlink="http://www.w3.org/1999/xlink"
+ <link xmlns:xlink="http://www.w3.org/1999/xlink"
xlink:href="http://valgrind.org/docs/manual/drd-manual.html">
DRD</link>,
- <link xmlns:xlink="http://www.w3.org/1999/xlink"
- xlink:href="http://valgrind.org/docs/manual/hg-manual.html">
+ <link xmlns:xlink="http://www.w3.org/1999/xlink"
+ xlink:href="http://valgrind.org/docs/manual/hg-manual.html">
Helgrind</link>, and
- <link xmlns:xlink="http://www.w3.org/1999/xlink"
- xlink:href="https://github.com/google/sanitizers">
+ <link xmlns:xlink="http://www.w3.org/1999/xlink"
+ xlink:href="https://github.com/google/sanitizers">
ThreadSanitizer</link> (this refers to ThreadSanitizer v1, not the
new "tsan" feature built-in to GCC itself).
</para>
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="manual.ext.debug_mode" xreflabel="Debug Mode">
<?dbhtml filename="debug_mode.html"?>
<section xml:id="manual.ext.debug_mode.intro" xreflabel="Intro"><info><title>Intro</title></info>
-
+
<para>
By default, libstdc++ is built with efficiency in mind, and
therefore performs little or no error checking that is not
<section xml:id="manual.ext.debug_mode.semantics" xreflabel="Semantics"><info><title>Semantics</title></info>
<?dbhtml filename="debug_mode_semantics.html"?>
-
+
<para>
</para>
<section xml:id="manual.ext.debug_mode.using" xreflabel="Using"><info><title>Using</title></info>
<?dbhtml filename="debug_mode_using.html"?>
-
+
<para>
</para>
<section xml:id="debug_mode.using.mode" xreflabel="Using Mode"><info><title>Using the Debug Mode</title></info>
-
+
<para>To use the libstdc++ debug mode, compile your application with the
compiler flag <code>-D_GLIBCXX_DEBUG</code>. Note that this flag
</section>
<section xml:id="debug_mode.using.specific" xreflabel="Using Specific"><info><title>Using a Specific Debug Container</title></info>
-
+
<para>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
<section xml:id="manual.ext.debug_mode.design" xreflabel="Design"><info><title>Design</title></info>
<?dbhtml filename="debug_mode_design.html"?>
-
+
<para>
</para>
<section xml:id="debug_mode.design.goals" xreflabel="Goals"><info><title>Goals</title></info>
-
+
<para>
</para>
<para> The libstdc++ debug mode replaces unsafe (but efficient) standard
</section>
<section xml:id="debug_mode.design.methods" xreflabel="Methods"><info><title>Methods</title></info>
-
+
<para>
</para>
<para>This section provides an overall view of the design of the
decisions and the stated design goals.</para>
<section xml:id="debug_mode.design.methods.wrappers" xreflabel="Method Wrapper"><info><title>The Wrapper Model</title></info>
-
+
<para>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
iterator from a different container.</para>
<section xml:id="debug_mode.design.methods.safe_iter" xreflabel="Method Safe Iter"><info><title>Safe Iterators</title></info>
-
+
<para>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,
</section>
<section xml:id="debug_mode.design.methods.safe_seq" xreflabel="Method Safe Seq"><info><title>Safe Sequences (Containers)</title></info>
-
+
<para>Container wrappers provide a debugging layer over a particular
container type. Because containers vary greatly in the member
</section>
<section xml:id="debug_mode.design.methods.precond" xreflabel="Precondition check"><info><title>Precondition Checking</title></info>
-
+
<para>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
</section>
<section xml:id="debug_mode.design.methods.coexistence" xreflabel="Coexistence"><info><title>Release- and debug-mode coexistence</title></info>
-
+
<para>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
(namely, safe iterators).</para>
<section xml:id="methods.coexistence.compile" xreflabel="Compile"><info><title>Compile-time coexistence of release- and debug-mode components</title></info>
-
+
<para>Both the release-mode components and the debug-mode
components need to exist within a single translation unit so that
<section xml:id="methods.coexistence.link" xreflabel="Link"><info><title>Link- and run-time coexistence of release- and
debug-mode components</title></info>
-
+
<para>Because each component has a distinct and separate release and
debug implementation, there is no issue with link-time
</section>
<section xml:id="debug_mode.design.other" xreflabel="Other"><info><title>Other Implementations</title></info>
-
+
<para>
</para>
<para> There are several existing implementations of debug modes for C++
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="std.diagnostics" xreflabel="Diagnostics">
<?dbhtml filename="diagnostics.html"?>
<section xml:id="std.diagnostics.exceptions" xreflabel="Exceptions"><info><title>Exceptions</title></info>
<?dbhtml filename="exceptions.html"?>
-
+
<section xml:id="std.diagnostics.exceptions.api"><info><title>API Reference</title></info>
-
+
<para>
Most exception classes are defined in one of the standard headers
<filename class="headerfile"><exception></filename>,
<classname>std::string</classname> member. A full hierarchy can be
found in the source documentation.
</para>
-
+
<!-- Doxygen XML: api/group__exceptions.xml -->
-
+
</section>
<section xml:id="std.diagnostics.exceptions.data" xreflabel="Adding Data to Exceptions"><info><title>Adding Data to <classname>exception</classname></title></info>
-
+
<para>
The standard exception classes carry with them a single string as
data (usually describing what went wrong or where the 'throw' took
<section xml:id="std.diagnostics.concept_checking" xreflabel="Concept Checking"><info><title>Concept Checking</title></info>
<?dbhtml filename="concept_checking.html"?>
-
+
<para>
In 1999, SGI added <quote>concept checkers</quote> to their
implementation of the STL: code which checked the template
-<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="appendix.porting.doc" xreflabel="Documentation Hacking">
<?dbhtml filename="documentation_hacking.html"?>
reference. Although divergent, this conforms to the GNU Project
recommendations as long as the output is of sufficient quality,
as per
- <link xmlns:xlink="http://www.w3.org/1999/xlink"
+ <link xmlns:xlink="http://www.w3.org/1999/xlink"
xlink:href="http://www.gnu.org/prep/standards/standards.html#Documentation">
GNU Manuals</link>.
</para>
<info>
<title>Generating Documentation</title>
</info>
-
+
<para>
Certain Makefile rules are required by the GNU Coding
Standards. These standard rules generate HTML, PDF, XML, or man
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<emphasis>make man</emphasis>
<filename>doc/libstdc++/libstdc++-manual.epub</filename>
</para>
</listitem>
- </varlistentry>
+ </varlistentry>
<varlistentry>
<term>
</section>
<section xml:id="doc.doxygen"><info><title>Doxygen</title></info>
-
+
<section xml:id="doxygen.prereq"><info><title>Prerequisites</title></info>
-
+
<table frame="all" xml:id="table.doxygen_prereq">
<title>Doxygen Prerequisites</title>
the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gnu.org/software/coreutils/">GNU
coreutils</link>. (GNU versions of find, xargs, and possibly
sed and grep are used, just because the GNU versions make
- things very easy.)
+ things very easy.)
</para>
<para>
</section>
<section xml:id="doxygen.rules"><info><title>Generating the Doxygen Files</title></info>
-
+
<para>
The following Makefile rules run Doxygen to generate HTML
docs, XML docs, XML docs as a single file, PDF docs, and the
<section xml:id="doxygen.debug">
<info><title>Debugging Generation</title></info>
-
+
<para>
Sometimes, mis-configuration of the pre-requisite tools can
lead to errors when attempting to build the
</section>
<section xml:id="doxygen.markup"><info><title>Markup</title></info>
-
+
<para>
In general, libstdc++ files should be formatted according to
<para>
Adding Doxygen markup to a file (informally called
<quote>doxygenating</quote>) is very simple. See the
- <link xmlns:xlink="http://www.w3.org/1999/xlink"
+ <link xmlns:xlink="http://www.w3.org/1999/xlink"
xlink:href="http://www.doxygen.nl/download.html#latestman">Doxygen
manual</link> for details.
We try to use a very-recent version of Doxygen.
</section>
<section xml:id="doc.docbook"><info><title>Docbook</title></info>
-
+
<section xml:id="docbook.prereq"><info><title>Prerequisites</title></info>
-
-
+
+
<table frame="all" xml:id="table.docbook_prereq">
<title>Docbook Prerequisites</title>
</section>
<section xml:id="docbook.rules"><info><title>Generating the DocBook Files</title></info>
-
+
<para>
The following Makefile rules generate (in order): an HTML
<para>
This is equivalent to doing:
</para>
-
+
<screen>
<userinput>
xmllint --noout --valid <filename>xml/index.xml</filename>
</section>
<section xml:id="docbook.examples"><info><title>File Organization and Basics</title></info>
-
+
<literallayout class="normal">
<emphasis>Which files are important</emphasis>
</section>
<section xml:id="docbook.markup"><info><title>Markup By Example</title></info>
-
+
<para>
Complete details on Docbook markup can be found in the
-<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="appendix.porting.api" xreflabel="api">
<?dbhtml filename="api.html"?>
-<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="appendix.porting.internals" xreflabel="Portin Internals">
<?dbhtml filename="internals.html"?>
<!-- Chapter 01 : Status -->
<chapter xml:id="manual.intro.status" xreflabel="Status"><info><title>Status</title></info>
<?dbhtml filename="status.html"?>
-
+
<!-- Section 01 : Implementation Status -->
<section xml:id="manual.intro.status.iso" xreflabel="Status"><info><title>Implementation Status</title></info>
-
+
<!-- Section 01.1 : Status C++ 1998 -->
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="status_cxx1998.xml">
<!-- Section 02 : License -->
<section xml:id="manual.intro.status.license" xreflabel="License"><info><title>License</title></info>
<?dbhtml filename="license.html"?>
-
+
<para>
There are two licenses affecting GNU libstdc++: one for the code,
and one for the documentation.
</para>
<section xml:id="manual.intro.status.license.gpl" xreflabel="License GPL"><info><title>The Code: GPL</title></info>
-
+
<para>
The source code is distributed under the <link linkend="appendix.gpl-3.0">GNU General Public License version 3</link>,
</section>
<section xml:id="manual.intro.status.license.fdl" xreflabel="License FDL"><info><title>The Documentation: GPL, FDL</title></info>
-
+
<para>
The documentation shipped with the library and made available over
<!-- Section 03 : Known Bugs -->
<section xml:id="manual.intro.status.bugs" xreflabel="Bugs"><info><title>Bugs</title></info>
<?dbhtml filename="bugs.html"?>
-
+
<section xml:id="manual.intro.status.bugs.impl" xreflabel="Bugs impl"><info><title>Implementation Bugs</title></info>
-
+
<para>
Information on known bugs, details on efforts to fix them, and
fixed bugs are all available as part of the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/bugs/">GCC bug tracking system</link>,
</section>
<section xml:id="manual.intro.status.bugs.iso" xreflabel="Bugs iso"><info><title>Standard Bugs</title></info>
-
+
<para>
Everybody's got issues. Even the C++ Standard Library.
</para>
<!-- Chapter 02 : Setup -->
<chapter xml:id="manual.intro.setup" xreflabel="Setup"><info><title>Setup</title></info>
<?dbhtml filename="setup.html"?>
-
+
<para>To transform libstdc++ sources into installed include files
and properly built binaries useful for linking to other software is
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="std.io" xreflabel="Input and Output">
<?dbhtml filename="io.html"?>
<!-- Sect1 01 : Iostream Objects -->
<section xml:id="std.io.objects" xreflabel="IO Objects"><info><title>Iostream Objects</title></info>
<?dbhtml filename="iostream_objects.html"?>
-
+
<para>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
<!-- Sect1 02 : Stream Buffers -->
<section xml:id="std.io.streambufs" xreflabel="Stream Buffers"><info><title>Stream Buffers</title></info>
<?dbhtml filename="streambufs.html"?>
-
+
<section xml:id="io.streambuf.derived" xreflabel="Derived streambuf Classes"><info><title>Derived streambuf Classes</title></info>
-
+
<para>
</para>
</section>
<section xml:id="io.streambuf.buffering" xreflabel="Buffering"><info><title>Buffering</title></info>
-
+
<para>First, are you sure that you understand buffering? Particularly
the fact that C++ may not, in fact, have anything to do with it?
</para>
<!-- Sect1 03 : Memory-based Streams -->
<section xml:id="std.io.memstreams" xreflabel="Memory Streams"><info><title>Memory Based Streams</title></info>
<?dbhtml filename="stringstreams.html"?>
-
+
<section xml:id="std.io.memstreams.compat" xreflabel="Compatibility strstream"><info><title>Compatibility With strstream</title></info>
-
+
<para>
</para>
<para>Stringstreams (defined in the header <code><sstream></code>)
<!-- Sect1 04 : File-based Streams -->
<section xml:id="std.io.filestreams" xreflabel="File Streams"><info><title>File Based Streams</title></info>
<?dbhtml filename="fstreams.html"?>
-
+
<section xml:id="std.io.filestreams.copying_a_file" xreflabel="Copying a File"><info><title>Copying a File</title></info>
-
+
<para>
</para>
</section>
<section xml:id="std.io.filestreams.binary" xreflabel="Binary Input and Output"><info><title>Binary Input and Output</title></info>
-
+
<para>
</para>
<para>The first and most important thing to remember about binary I/O is
<!-- Sect1 03 : Interacting with C -->
<section xml:id="std.io.c" xreflabel="Interacting with C"><info><title>Interacting with C</title></info>
<?dbhtml filename="io_and_c.html"?>
-
+
<section xml:id="std.io.c.FILE" xreflabel="Using FILE* and file descriptors"><info><title>Using FILE* and file descriptors</title></info>
-
+
<para>
See the <link linkend="manual.ext.io">extensions</link> for using
<type>FILE</type> and <type>file descriptors</type> with
</section>
<section xml:id="std.io.c.sync" xreflabel="Performance Issues"><info><title>Performance</title></info>
-
+
<para>
Pathetic Performance? Ditch C.
</para>
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="std.iterators" xreflabel="Iterators">
<?dbhtml filename="iterators.html"?>
<!-- Sect1 01 : Predefined -->
<section xml:id="std.iterators.predefined" xreflabel="Predefined"><info><title>Predefined</title></info>
-
+
<section xml:id="iterators.predefined.vs_pointers" xreflabel="Versus Pointers"><info><title>Iterators vs. Pointers</title></info>
-
+
<para>
The following
FAQ <link linkend="faq.iterator_as_pod">entry</link> points out that
</section>
<section xml:id="iterators.predefined.end" xreflabel="end() Is One Past the End"><info><title>One Past the End</title></info>
-
+
<para>This starts off sounding complicated, but is actually very easy,
especially towards the end. Trust me.
-<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="std.localization.locales.locale" xreflabel="Locale">
<info><title>locale</title>
<section xml:id="locale.impl.c"><info><title>Interacting with "C" locales</title></info>
-
+
<itemizedlist>
<listitem>
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="std.localization" xreflabel="Localization">
<?dbhtml filename="localization.html"?>
<!-- Section 01 : Locale -->
<section xml:id="std.localization.locales" xreflabel="Locales"><info><title>Locales</title></info>
<?dbhtml filename="locales.html"?>
-
+
<!-- Section 01 : locale -->
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="locale.xml">
<!-- Section 02 : Facet -->
<section xml:id="std.localization.facet" xreflabel="Facets"><info><title>Facets</title></info>
<?dbhtml filename="facets.html"?>
-
+
<!-- Section 01 : ctype -->
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="ctype.xml">
-<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="std.localization.facet.messages" xreflabel="Messages">
<?dbhtml filename="messages.html"?>
First, why is <code>messages_base::catalog</code> specified as a typedef
to int? This makes sense for implementations that use
<code>catopen</code> and define <code>nl_catd</code> as int, but not for
-others. Fortunately, it's not heavily used and so only a minor irritant.
+others. Fortunately, it's not heavily used and so only a minor irritant.
This has been reported as a possible defect in the standard (LWG 2028).
</para>
<section xml:id="messages.impl.models"><info><title>Models</title></info>
-
+
<para>
This is a relatively simple class, on the face of it. The standard
specifies very little in concrete terms, so generic
</section>
<section xml:id="messages.impl.gnu"><info><title>The GNU Model</title></info>
-
+
<para>
The messages facet, because it is retrieving and converting
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="manual.ext.allocator.mt" xreflabel="mt allocator">
<?dbhtml filename="mt_allocator.html"?>
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="std.numerics" xreflabel="Numerics">
<?dbhtml filename="numerics.html"?>
<!-- Sect1 01 : Complex -->
<section xml:id="std.numerics.complex" xreflabel="complex"><info><title>Complex</title></info>
<?dbhtml filename="complex.html"?>
-
+
<para>
</para>
<section xml:id="numerics.complex.processing" xreflabel="complex Processing"><info><title>complex Processing</title></info>
-
+
<para>
</para>
<para>Using <code>complex<></code> becomes even more comple- er, sorry,
<!-- Sect1 02 : Generalized Operations -->
<section xml:id="std.numerics.generalized_ops" xreflabel="Generalized Ops"><info><title>Generalized Operations</title></info>
<?dbhtml filename="generalized_numeric_operations.html"?>
-
+
<para>
</para>
<!-- Sect1 03 : Interacting with C -->
<section xml:id="std.numerics.c" xreflabel="Interacting with C"><info><title>Interacting with C</title></info>
<?dbhtml filename="numerics_and_c.html"?>
-
+
<section xml:id="numerics.c.array" xreflabel="Numerics vs. Arrays"><info><title>Numerics vs. Arrays</title></info>
-
+
<para>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
</section>
<section xml:id="numerics.c.c99" xreflabel="C99"><info><title>C99</title></info>
-
+
<para>In addition to the other topics on this page, we'll note here some
of the C99 features that appear in libstdc++.
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="manual.ext.parallel_mode" xreflabel="Parallel Mode">
<?dbhtml filename="parallel_mode.html"?>
</note>
<section xml:id="manual.ext.parallel_mode.intro" xreflabel="Intro"><info><title>Intro</title></info>
-
+
<para>The following library components in the include
<filename class="headerfile">numeric</filename> are included in the parallel mode:</para>
<section xml:id="manual.ext.parallel_mode.semantics" xreflabel="Semantics"><info><title>Semantics</title></info>
<?dbhtml filename="parallel_mode_semantics.html"?>
-
+
<para> The parallel mode STL algorithms are currently not exception-safe,
i.e. user-defined functors must not throw exceptions.
<section xml:id="manual.ext.parallel_mode.using" xreflabel="Using"><info><title>Using</title></info>
<?dbhtml filename="parallel_mode_using.html"?>
-
+
<section xml:id="parallel_mode.using.prereq_flags"><info><title>Prerequisite Compiler Flags</title></info>
-
+
<para>
Any use of parallel functionality requires additional compiler
</section>
<section xml:id="parallel_mode.using.parallel_mode"><info><title>Using Parallel Mode</title></info>
-
+
<para>
To use the libstdc++ parallel mode, compile your application with
</section>
<section xml:id="parallel_mode.using.specific"><info><title>Using Specific Parallel Components</title></info>
-
+
<para>When it is not feasible to recompile your entire application, or
only specific algorithms need to be parallel-aware, individual
<section xml:id="manual.ext.parallel_mode.design" xreflabel="Design"><info><title>Design</title></info>
<?dbhtml filename="parallel_mode_design.html"?>
-
+
<para>
</para>
<section xml:id="parallel_mode.design.intro" xreflabel="Intro"><info><title>Interface Basics</title></info>
-
+
<para>
All parallel algorithms are intended to have signatures that are
</section>
<section xml:id="parallel_mode.design.tuning" xreflabel="Tuning"><info><title>Configuration and Tuning</title></info>
-
+
<section xml:id="parallel_mode.design.tuning.omp" xreflabel="OpenMP Environment"><info><title>Setting up the OpenMP Environment</title></info>
-
+
<para>
Several aspects of the overall runtime environment can be manipulated
</section>
<section xml:id="parallel_mode.design.tuning.compile" xreflabel="Compile Switches"><info><title>Compile Time Switches</title></info>
-
+
<para>
To force an algorithm to execute sequentially, even though parallelism
</section>
<section xml:id="parallel_mode.design.tuning.settings" xreflabel="_Settings"><info><title>Run Time Settings and Defaults</title></info>
-
+
<para>
The default parallelization strategy, the choice of specific algorithm
</section>
<section xml:id="parallel_mode.design.impl" xreflabel="Impl"><info><title>Implementation Namespaces</title></info>
-
+
<para> One namespace contain versions of code that are always
explicitly sequential:
<section xml:id="manual.ext.parallel_mode.test" xreflabel="Testing"><info><title>Testing</title></info>
<?dbhtml filename="parallel_mode_test.html"?>
-
+
<para>
Both the normal conformance and regression tests and the
</textobject>
</mediaobject>
</figure>
-
+
<para>Let U be a domain (e.g., the integers, or the
strings of 3 characters). A hash-table algorithm needs to map
elements of U "uniformly" into the range [0,..., m -
0</subscript><superscript>t - 1</superscript> s<subscript>i</subscript> a<superscript>i</superscript> mod m
</mathphrase>
</equation>
-
+
<para>where a is some non-negative integral value. This is
the standard string-hashing function used in SGI's
</title>
<mathphrase>
f<subscript>2</subscript>(s, m) = ∑ <subscript>i
- = 0</subscript><superscript>k - 1</superscript> s<subscript>i</subscript> a<superscript>i</superscript> mod m
+ = 0</subscript><superscript>k - 1</superscript> s<subscript>i</subscript> a<superscript>i</superscript> mod m
</mathphrase>
</equation>
</textobject>
</mediaobject>
</figure>
-
+
<para>If <classname>cc_hash_table</classname>'s
hash-functor, <classname>Hash_Fn</classname> is instantiated by <classname>null_type</classname> , then <classname>Comb_Hash_Fn</classname> is taken to be
a ranged-hash function. The graphic below shows an <function>insert</function> sequence
</textobject>
</mediaobject>
</figure>
-
+
</section>
<section xml:id="hash_policies.implementation.probe">
Probability of Probe Sequence of Length k
</title>
<mathphrase>
- p<subscript>1</subscript> =
+ p<subscript>1</subscript> =
</mathphrase>
</equation>
Probability Probe Sequence in Some Bin
</title>
<mathphrase>
- P( exists<subscript>i</subscript> l<subscript>i</subscript> ≥ k ) =
+ P( exists<subscript>i</subscript> l<subscript>i</subscript> ≥ k ) =
</mathphrase>
</equation>
<para>The graphic below gives an overall picture of the resize-related
classes. <classname>basic_hash_table</classname>
is parametrized by <classname>Resize_Policy</classname>, which it subclasses
- publicly. This class is currently instantiated only by <classname>hash_standard_resize_policy</classname>.
+ publicly. This class is currently instantiated only by <classname>hash_standard_resize_policy</classname>.
<classname>hash_standard_resize_policy</classname>
itself is parametrized by <classname>Trigger_Policy</classname> and
<classname>Size_Policy</classname>. Currently, <classname>Trigger_Policy</classname> is
</textobject>
</mediaobject>
</figure>
-
+
<para>Supporting such trees is difficult for a number of
reasons:</para>
node_end() const;
node_iterator
- node_end();
+ node_end();
</programlisting>
<para>The first pairs return node iterators corresponding to the
<para><classname>node_update</classname> must also define the following method
for restoring node invariants:</para>
<programlisting>
- void
+ void
operator()(node_iterator nd_it, const_node_iterator end_nd_it)
</programlisting>
</section>
- </section>
+ </section>
<section xml:id="container.tree.details.split">
<info><title>Split and Join</title></info>
currently illegal.</para>
<para>Following is a description of a (PATRICIA) trie
- (this implementation follows <xref linkend="biblio.okasaki98mereable"/> and
- <xref linkend="biblio.filliatre2000ptset"/>).
+ (this implementation follows <xref linkend="biblio.okasaki98mereable"/> and
+ <xref linkend="biblio.filliatre2000ptset"/>).
</para>
<para>A (PATRICIA) trie is similar to a tree, but with the
which unconditionally move an accessed element to the front of
the list. The latter type is very useful in this library,
since there is no need to associate metadata with each element.
- (See <xref linkend="biblio.andrew04mtf"/>
+ (See <xref linkend="biblio.andrew04mtf"/>
</para>
</section>
<classname>binomial_heap_tag</classname>,
<classname>rc_binomial_heap_tag</classname>,
or <classname>thin_heap_tag</classname>,
- specifies, respectively,
+ specifies, respectively,
an underlying pairing heap (<xref linkend="biblio.fredman86pairing"/>),
binary heap (<xref linkend="biblio.clrs2001"/>),
binomial heap (<xref linkend="biblio.clrs2001"/>),
assert(p.top() == 3);
</programlisting>
-
+
<para>It should be noted that an alternative design could embed an
associative container in a priority queue. Could, but most
probably should not. To begin with, it should be noted that one
<para>Of course, one can use any order-preserving associative
container as a priority queue, as in the graphic above label C, possibly by creating an adapter class
- over the associative container (much as
+ over the associative container (much as
<classname>std::priority_queue</classname> can adapt <classname>std::vector</classname>).
This has the advantage that no cross-referencing is necessary
at all; the priority queue itself is an associative container.
types. <classname>__gnu_pbds::priority_queue</classname>
publicly defines <classname>container_category</classname> as one of the tags. Given any
container <classname>Cntnr</classname>, the tag of the underlying
- data structure can be found via <classname>typename
+ data structure can be found via <classname>typename
Cntnr::container_category</classname>; this is one of the possible tags shown in the graphic below.
</para>
container.</para>
<para>To find if a container might throw if two of its objects are
- joined, one can use
+ joined, one can use
<programlisting>
container_traits<Cntnr>::split_join_can_throw
</programlisting>
-<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="manual.intro.setup.prereq" xreflabel="Prerequisites">
<?dbhtml filename="prerequisites.html"?>
-<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="std.util.memory.shared_ptr" xreflabel="shared_ptr">
<?dbhtml filename="shared_ptr.html"?>
<section xml:id="shared_ptr.hier"><info><title>Class Hierarchy</title></info>
-
+
<para>
A <classname>shared_ptr<T></classname> contains a pointer of
</section>
<section xml:id="shared_ptr.thread"><info><title>Thread Safety</title></info>
-
+
<para>
The
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/libs/smart_ptr/shared_ptr.htm#ThreadSafety">Thread
</section>
<section xml:id="shared_ptr.policy"><info><title>Selecting Lock Policy</title></info>
-
+
<para>
</para>
<section xml:id="shared_ptr.examples"><info><title>Examples</title></info>
-
+
<para>
Examples of use can be found in the testsuite, under
<filename class="directory">testsuite/tr1/2_general_utilities/shared_ptr</filename>,
</section>
<section xml:id="shared_ptr.issues"><info><title>Unresolved Issues</title></info>
-
+
<para>
The <emphasis><classname>shared_ptr</classname> atomic access</emphasis>
clause in the C++11 standard is not implemented in GCC.
-<book xmlns="http://docbook.org/ns/docbook" version="5.0"
+<book xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="manual" xreflabel="Manual">
<?dbhtml dir="manual"?>
<?dbhtml filename="index.html"?>
-<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="status.iso.tr1" xreflabel="Status C++ TR1">
<?dbhtml filename="status_iso_cxxtr1.html"?>
-<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="status.iso.tr24733" xreflabel="Status C++ TR24733">
<?dbhtml filename="status_iso_cxxtr24733.html"?>
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="std.strings" xreflabel="Strings">
<?dbhtml filename="strings.html"?>
<!-- Sect1 02 : String Classes -->
<section xml:id="std.strings.string" xreflabel="string"><info><title>String Classes</title></info>
-
+
<section xml:id="strings.string.simple" xreflabel="Simple Transformations"><info><title>Simple Transformations</title></info>
-
+
<para>
Here are Standard, simple, and portable ways to perform common
transformations on a <code>string</code> instance, such as
</section>
<section xml:id="strings.string.case" xreflabel="Case Sensitivity"><info><title>Case Sensitivity</title></info>
-
+
<para>
</para>
</section>
<section xml:id="strings.string.character_types" xreflabel="Arbitrary Characters"><info><title>Arbitrary Character Types</title></info>
-
+
<para>
</para>
</section>
<section xml:id="strings.string.token" xreflabel="Tokenizing"><info><title>Tokenizing</title></info>
-
+
<para>
</para>
<para>The Standard C (and C++) function <code>strtok()</code> leaves a lot to
</section>
<section xml:id="strings.string.shrink" xreflabel="Shrink to Fit"><info><title>Shrink to Fit</title></info>
-
+
<para>
</para>
<para>From GCC 3.4 calling <code>s.reserve(res)</code> on a
</section>
<section xml:id="strings.string.Cstring" xreflabel="CString (MFC)"><info><title>CString (MFC)</title></info>
-
+
<para>
</para>
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="std.support" xreflabel="Support">
<?dbhtml filename="support.html"?>
-<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="manual.intro.setup.test" xreflabel="Testing">
<?dbhtml filename="test.html"?>
<section xml:id="test.run.basic"><info><title>Basic</title></info>
-
+
<para>
You can check the status of the build without installing it
</section>
<section xml:id="test.run.variations"><info><title>Variations</title></info>
-
+
<para>
There are several options for running tests, including testing
the regression tests, testing a subset of the regression tests,
</section>
<section xml:id="test.run.permutations"><info><title>Permutations</title></info>
-
+
<para>
The tests will be compiled with a set of default compiler flags defined
by the
<!-- 01 <a href="multimap_text_find_timing_test_small"> -->
<section xml:id="performance.multimap.text_find_small">
<info><title>
- Text <function>find</function> with Small Secondary-to-Primary Key Ratios
+ Text <function>find</function> with Small Secondary-to-Primary Key Ratios
</title></info>
<para></para>
<!-- 02 <a href="multimap_text_find_timing_test_large"> -->
<section xml:id="performance.multimap.text_find_large">
<info><title>
- Text <function>find</function> with Large Secondary-to-Primary Key Ratios
+ Text <function>find</function> with Large Secondary-to-Primary Key Ratios
</title></info>
<para></para>
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="manual.intro.using" xreflabel="Using">
<info><title>Using</title></info>
<?dbhtml filename="using.html"?>
<section xml:id="manual.intro.using.flags" xreflabel="Flags"><info><title>Command Options</title></info>
-
+
<para>
The set of features available in the GNU C++ library is shaped by
several <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/gcc-4.3.2/gcc/Invoking-GCC.html">GCC
<entry><literal>-fopenmp</literal></entry>
<entry>For <link linkend="manual.ext.parallel_mode">parallel</link> mode.</entry>
</row>
-
+
<row>
<entry><literal>-ltbb</literal></entry>
<entry>Linking to tbb (Thread Building Blocks) is required for use of the
<filename class="headerfile"><execution></filename>.
</entry>
</row>
-
+
</tbody>
</tgroup>
<section xml:id="manual.intro.using.headers" xreflabel="Headers"><info><title>Headers</title></info>
<?dbhtml filename="using_headers.html"?>
-
+
<section xml:id="manual.intro.using.headers.all" xreflabel="Header Files"><info><title>Header Files</title></info>
-
+
<para>
The C++ standard specifies the entire set of header files that
<para>
<xref linkend="table.libfundts_headers"/>,
-shows the additional include files define by the C++ Extensions for
+shows the additional include files define by the C++ Extensions for
Library Fundamentals Technical Specification, ISO/IEC TS 19568.
These are available in C++14 and later compilation modes.
Including these headers in earlier modes will not result in
</section>
<section xml:id="manual.intro.using.headers.mixing" xreflabel="Mixing Headers"><info><title>Mixing Headers</title></info>
-
+
<para> A few simple rules.
</para>
</section>
<section xml:id="manual.intro.using.headers.cheaders" xreflabel="C Headers and"><info><title>The C Headers and <code>namespace std</code></title></info>
-
+
<para>
The standard specifies that if one includes the C-style header
</section>
<section xml:id="manual.intro.using.headers.pre" xreflabel="Precompiled Headers"><info><title>Precompiled Headers</title></info>
-
+
<para>There are three base header files that are provided. They can be
<section xml:id="manual.intro.using.macros" xreflabel="Macros"><info><title>Macros</title></info>
<?dbhtml filename="using_macros.html"?>
-
+
<para>
All library macros begin with <code>_GLIBCXX_</code>.
<section xml:id="manual.intro.using.namespaces" xreflabel="Namespaces"><info><title>Namespaces</title></info>
<?dbhtml filename="using_namespaces.html"?>
-
+
<section xml:id="manual.intro.using.namespaces.all" xreflabel="Available Namespaces"><info><title>Available Namespaces</title></info>
-
+
</section>
<section xml:id="manual.intro.using.namespaces.std" xreflabel="namespace std"><info><title>namespace std</title></info>
-
+
<para>
</section>
<section xml:id="manual.intro.using.namespaces.comp" xreflabel="Using Namespace Composition"><info><title>Using Namespace Composition</title></info>
-
+
<para>
Best practice in programming suggests sequestering new data or
<section xml:id="manual.intro.using.linkage" xreflabel="Linkage"><info><title>Linking</title></info>
<?dbhtml filename="using_dynamic_or_shared.html"?>
-
+
<section xml:id="manual.intro.using.linkage.freestanding" xreflabel="Freestanding"><info><title>Almost Nothing</title></info>
-
+
<para>
Or as close as it gets: freestanding. This is a minimal
configuration, with only partial support for the standard
</section>
<section xml:id="manual.intro.using.linkage.dynamic" xreflabel="Dynamic and Shared"><info><title>Finding Dynamic or Shared Libraries</title></info>
-
+
<para>
If the only library built is the static library
<section xml:id="manual.intro.using.concurrency" xreflabel="Concurrency"><info><title>Concurrency</title></info>
<?dbhtml filename="using_concurrency.html"?>
-
+
<para>This section discusses issues surrounding the proper compilation
of multithreaded applications which use the Standard C++
</para>
<section xml:id="manual.intro.using.concurrency.prereq" xreflabel="Thread Prereq"><info><title>Prerequisites</title></info>
-
+
<para>All normal disclaimers aside, multithreaded C++ application are
only supported when libstdc++ and all user code was built with
</section>
<section xml:id="manual.intro.using.concurrency.thread_safety" xreflabel="Thread Safety"><info><title>Thread Safety</title></info>
-
+
<para>
In the terms of the 2011 C++ standard a thread-safe program is one which
<code>begin</code>, <code>end</code>, <code>rbegin</code>, <code>rend</code>,
<code>front</code>, <code>back</code>, <code>data</code>,
<code>find</code>, <code>lower_bound</code>, <code>upper_bound</code>,
- <code>equal_range</code>, <code>at</code>
+ <code>equal_range</code>, <code>at</code>
and, except in associative or unordered associative containers,
<code>operator[]</code>. In other words, although they are non-const
so that they can return mutable iterators, those member functions
int i = *global_sp; // OK, operator* is const
int j = *local_sp; // OK, does not operate on global_sp
- // *global_sp = 2; // NOT OK, modifies int visible to other threads
- // *local_sp = 2; // NOT OK, modifies int visible to other threads
+ // *global_sp = 2; // NOT OK, modifies int visible to other threads
+ // *local_sp = 2; // NOT OK, modifies int visible to other threads
// global_sp.reset(); // NOT OK, reset is non-const
local_sp.reset(); // OK, does not operate on global_sp
<para>For further details of the C++11 memory model see Hans-J. Boehm's
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.hboehm.info/c++mm/">Threads
- and memory model for C++</link> pages, particularly the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.hboehm.info/c++mm/threadsintro.html">introduction</link>
+ and memory model for C++</link> pages, particularly the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.hboehm.info/c++mm/threadsintro.html">introduction</link>
and <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.hboehm.info/c++mm/user-faq.html">FAQ</link>.
</para>
</section>
<section xml:id="manual.intro.using.concurrency.atomics" xreflabel="Atomics"><info><title>Atomics</title></info>
-
+
<para>
</para>
</section>
<section xml:id="manual.intro.using.concurrency.io" xreflabel="IO"><info><title>IO</title></info>
-
+
<para>This gets a bit tricky. Please read carefully, and bear with me.
</para>
<section xml:id="concurrency.io.structure" xreflabel="Structure"><info><title>Structure</title></info>
-
+
<para>A wrapper
type called <code>__basic_file</code> provides our abstraction layer
for the <code>std::filebuf</code> classes. Nearly all decisions dealing
</section>
<section xml:id="concurrency.io.defaults" xreflabel="Defaults"><info><title>Defaults</title></info>
-
+
<para>The __basic_file type is simply a collection of small wrappers around
the C stdio layer (again, see the link under Structure). We do no
locking ourselves, but simply pass through to calls to <code>fopen</code>,
</section>
<section xml:id="concurrency.io.future" xreflabel="Future"><info><title>Future</title></info>
-
+
<para> A
second choice may be available for I/O implementations: libio. This is
disabled by default, and in fact will not currently work due to other
</section>
<section xml:id="concurrency.io.alt" xreflabel="Alt"><info><title>Alternatives</title></info>
-
+
<para>Don't forget that other cstdio implementations are possible. You could
easily write one to perform your own forms of locking, to solve your
"interesting" problems.
</section>
<section xml:id="manual.intro.using.concurrency.containers" xreflabel="Containers"><info><title>Containers</title></info>
-
+
<para>This section discusses issues surrounding the design of
multithreaded applications which use Standard C++ containers.
-<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="manual.intro.using.exceptions" xreflabel="Using Exceptions">
<?dbhtml filename="using_exceptions.html"?>
Error and Exception Handling
</link>
</title>
-
+
<author><personname><firstname>David</firstname><surname>Abrahams </surname></personname></author>
<publisher>
<publishername>
Exception-Safety in Generic Components
</link>
</title>
-
+
<author><personname><firstname>David</firstname><surname>Abrahams</surname></personname></author>
<publisher>
<publishername>
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="std.util" xreflabel="Utilities">
<?dbhtml filename="utilities.html"?>
<!-- Section 01 : Functors -->
<section xml:id="std.util.functors" xreflabel="Functors"><info><title>Functors</title></info>
<?dbhtml filename="functors.html"?>
-
+
<para>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
<!-- Section 02 : Pairs -->
<section xml:id="std.util.pairs" xreflabel="Pairs"><info><title>Pairs</title></info>
<?dbhtml filename="pairs.html"?>
-
+
<para>The <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
<!-- Section 03 : Memory -->
<section xml:id="std.util.memory" xreflabel="Memory"><info><title>Memory</title></info>
<?dbhtml filename="memory.html"?>
-
+
<para>
Memory contains three general areas. First, function and operator
calls via <function>new</function> and <function>delete</function>
<!-- Section 04 : Traits -->
<section xml:id="std.util.traits" xreflabel="Traits"><info><title>Traits</title></info>
<?dbhtml filename="traits.html"?>
-
+
<para>
</para>
</section>
projects / gcc.git / commitdiff