procyberian/gcc
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

containers.xml: Add section on unordered containers.

Browse source 
2013-02-10  François Dumont  <fdumont@gcc.gnu.org>
	    Jonathan Wakely  <jwakely.gcc@gmail.com>

	* doc/xml/manual/containers.xml: Add section on unordered containers.
	* doc/xml/manual/using.xml: Fix incomplete sentence.

Co-Authored-By: Jonathan Wakely <jwakely.gcc@gmail.com>

From-SVN: r195937
This commit is contained in:
François Dumont 2013-02-11 00:19:41 +00:00 • committed by Jonathan Wakely
parent dfed5434f3
commit adb1c4d1e0
3 changed files with 88 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
libstdc++-v3/ChangeLog
View file

@ -1,3 +1,9 @@
2013-02-10 François Dumont <fdumont@gcc.gnu.org>
Jonathan Wakely <jwakely.gcc@gmail.com>
* doc/xml/manual/containers.xml: Add section on unordered containers.
* doc/xml/manual/using.xml: Fix incomplete sentence.
2013-02-10 Jonathan Wakely <jwakely.gcc@gmail.com>
PR libstdc++/56267

82
libstdc++-v3/doc/xml/manual/containers.xml
View file

@ -349,7 +349,87 @@
</section>
<!-- Sect1 03 : Interacting with C -->
<!-- Sect1 03 : Unordered Associative -->
<section xml:id="std.containers.unordered" xreflabel="Unordered">
<info><title>Unordered Associative</title></info>
<?dbhtml filename="unordered_associative.html"?>
<section xml:id="containers.unordered.hash" xreflabel="Hash">
<info><title>Hash Code</title></info>
<section xml:id="containers.unordered.cache" xreflabel="Cache">
<info><title>Hash Code Caching Policy</title></info>
<para>
The unordered containers in libstdc++ may cache the hash code for each
element alongside the element itself. In some cases not recalculating
the hash code every time it's needed can improve performance, but the
additional memory overhead can also reduce performance, so whether an
unordered associative container caches the hash code or not depends on
a number of factors. The caching policy for GCC 4.8 is described below.
</para>
<para>
The C++ standard requires that <code>erase</code> and <code>swap</code>
operations must not throw exceptions. Those operations might need an
element's hash code, but cannot use the hash function if it could
throw.
This means the hash codes will be cached unless the hash function
has a non-throwing exception specification such as <code>noexcept</code>
or <code>throw()</code>.
</para>
<para>
Secondly, libstdc++ also needs the hash code in the implementation of
<code>local_iterator</code> and <code>const_local_iterator</code> in
order to know when the iterator has reached the end of the bucket.
This means that the local iterator types will embed a copy of the hash
function when possible.
Because the local iterator types must be DefaultConstructible and
CopyAssignable, if the hash function type does not model those concepts
then it cannot be embedded and so the hash code must be cached.
Note that a hash function might not be safe to use when
default-constructed (e.g if it a function pointer) so a hash
function that is contained in a local iterator won't be used until
the iterator is valid, so the hash function has been copied from a
correctly-initialized object.
</para>
<para>
If the hash function is non-throwing, DefaultConstructible and
CopyAssignable then libstdc++ doesn't need to cache the hash code for
correctness, but might still do so for performance if computing a
hash code is an expensive operation, as it may be for arbitrarily
long strings.
As an extension libstdc++ provides a trait type to describe whether
a hash function is fast. By default hash functions are assumed to be
fast unless the trait is specialized for the hash function and the
trait's value is false, in which case the hash code will always be
cached.
The trait can be specialized for user-defined hash functions like so:
</para>
<programlisting>
#include &lt;unordered_set&gt;
struct hasher
{
std::size_t operator()(int val) const noexcept
{
// Some very slow computation of a hash code from an int !
...
}
}
namespace std
{
template&lt;&gt;
struct __is_fast_hash&lt;hasher&gt; : std::false_type
{ };
}
</programlisting>
</section>
</section>
</section>
<!-- 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"?>

2
libstdc++-v3/doc/xml/manual/using.xml
View file

@ -755,7 +755,7 @@ g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe
. /mnt/share/bld/H-x86-gcc.20071201include/c++/4.3.0/string
</programlisting>
<para>The exclamation point to the left of the <code>stdc++.h.gch</code> listing means that the generated PCH file was used, and thus the </para>
<para>The exclamation point to the left of the <code>stdc++.h.gch</code> listing means that the generated PCH file was used.</para>
<para/>
<para> Detailed information about creating precompiled header files can be found in the GCC <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/gcc/Precompiled-Headers.html">documentation</link>.