diff options
Diffstat (limited to 'libstdc++-v3/doc/xml')
| -rw-r--r-- | libstdc++-v3/doc/xml/faq.xml | 24 | ||||
| -rw-r--r-- | libstdc++-v3/doc/xml/manual/debug.xml | 79 | ||||
| -rw-r--r-- | libstdc++-v3/doc/xml/manual/evolution.xml | 9 | ||||
| -rw-r--r-- | libstdc++-v3/doc/xml/manual/intro.xml | 16 | ||||
| -rw-r--r-- | libstdc++-v3/doc/xml/manual/shared_ptr.xml | 6 | ||||
| -rw-r--r-- | libstdc++-v3/doc/xml/manual/status_cxx2017.xml | 33 | ||||
| -rw-r--r-- | libstdc++-v3/doc/xml/manual/using.xml | 4 |
7 files changed, 120 insertions, 51 deletions
diff --git a/libstdc++-v3/doc/xml/faq.xml b/libstdc++-v3/doc/xml/faq.xml index edc07f16acb..b4bf333e26a 100644 --- a/libstdc++-v3/doc/xml/faq.xml +++ b/libstdc++-v3/doc/xml/faq.xml @@ -1001,21 +1001,31 @@ <qandaentry xml:id="faq.memory_leaks"> <question xml:id="q-memory_leaks"> <para> - <quote>Memory leaks</quote> in containers + <quote>Memory leaks</quote> in libstdc++ </para> </question> <answer xml:id="a-memory_leaks"> - <note> - <para>This answer is old and probably no longer be relevant.</para> - </note> <para> - A few people have reported that the standard containers appear + Since GCC 5.1.0, libstdc++ automatically allocates a pool + of a few dozen kilobytes on startup. This pool is used to ensure it's + possible to throw exceptions (such as <classname>bad_alloc</classname>) + even when <code>malloc</code> is unable to allocate any more memory. + With some versions of <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://valgrind.org/"><command>valgrind</command></link> + this pool will be shown as "still reachable" when the process exits, e.g. + <code>still reachable: 72,704 bytes in 1 blocks</code>. + This memory is not a leak, because it's still in use by libstdc++, + and the memory will be returned to the OS when the process exits. + Later versions of <command>valgrind</command> know how to free this + pool as the process exits, and so won't show any "still reachable" memory. + </para> + <para> + In the past, a few people reported that the standard containers appear to leak memory when tested with memory checkers such as <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://valgrind.org/"><command>valgrind</command></link>. Under some (non-default) configurations the library's allocators keep free memory in a - pool for later reuse, rather than returning it to the OS. Although - this memory is always reachable by the library and is never + pool for later reuse, rather than deallocating it with <code>delete</code> + Although this memory is always reachable by the library and is never lost, memory debugging tools can report it as a leak. If you want to test the library for memory leaks please read <link linkend="debug.memory">Tips for memory leak hunting</link> diff --git a/libstdc++-v3/doc/xml/manual/debug.xml b/libstdc++-v3/doc/xml/manual/debug.xml index 37e330d3ed2..091e0b6914c 100644 --- a/libstdc++-v3/doc/xml/manual/debug.xml +++ b/libstdc++-v3/doc/xml/manual/debug.xml @@ -94,50 +94,35 @@ <section xml:id="debug.memory"><info><title>Memory Leak Hunting</title></info> +<para> + On many targets GCC supports AddressSanitizer, a fast memory error detector, + which is enabled by the <option>-fsanitize=address</option> option. +</para> <para> - There are various third party memory tracing and debug utilities + There are also various third party memory tracing and debug utilities that can be used to provide detailed memory allocation information about C++ code. An exhaustive list of tools is not going to be attempted, but includes <code>mtrace</code>, <code>valgrind</code>, - <code>mudflap</code>, and the non-free commercial product - <code>purify</code>. In addition, <code>libcwd</code> has a - replacement for the global new and delete operators that can track - memory allocation and deallocation and provide useful memory - statistics. -</para> - -<para> - Regardless of the memory debugging tool being used, there is one - thing of great importance to keep in mind when debugging C++ code - that uses <code>new</code> and <code>delete</code>: there are - different kinds of allocation schemes that can be used by <code> - std::allocator</code>. For implementation details, see the <link linkend="manual.ext.allocator.mt">mt allocator</link> documentation and - look specifically for <code>GLIBCXX_FORCE_NEW</code>. -</para> - -<para> - In a nutshell, the optional <classname>mt_allocator</classname> - is a high-performance pool allocator, and can - give the mistaken impression that in a suspect executable, memory is - being leaked, when in reality the memory "leak" is a pool being used - by the library's allocator and is reclaimed after program - termination. + <code>mudflap</code> (no longer supported since GCC 4.9.0), ElectricFence, + and the non-free commercial product <code>purify</code>. + In addition, <code>libcwd</code>, jemalloc and TCMalloc have replacements + for the global <code>new</code> and <code>delete</code> operators + that can track memory allocation and deallocation and provide useful + memory statistics. </para> <para> For valgrind, there are some specific items to keep in mind. First of all, use a version of valgrind that will work with current GNU C++ tools: the first that can do this is valgrind 1.0.4, but later - versions should work at least as well. Second of all, use a - completely unoptimized build to avoid confusing valgrind. Third, use - GLIBCXX_FORCE_NEW to keep extraneous pool allocation noise from - cluttering debug information. + versions should work better. Second, using an unoptimized build + might avoid confusing valgrind. </para> <para> - Fourth, it may be necessary to force deallocation in other libraries - as well, namely the "C" library. On linux, this can be accomplished + Third, it may be necessary to force deallocation in other libraries + as well, namely the "C" library. On GNU/Linux, this can be accomplished with the appropriate use of the <code>__cxa_atexit</code> or <code>atexit</code> functions. </para> @@ -157,7 +142,6 @@ } </programlisting> - <para>or, using <code>__cxa_atexit</code>:</para> <programlisting> @@ -184,6 +168,39 @@ valgrind -v --num-callers=20 --leak-check=yes --leak-resolution=high --show-reachable=yes a.out </programlisting> +<section xml:id="debug.memory.mtalloc"> +<info><title>Non-memory leaks in Pool and MT allocators</title></info> + +<para> + There are different kinds of allocation schemes that can be used by + <code>std::allocator</code>. Prior to GCC 3.4.0 the default was to use + a pooling allocator, <classname>pool_allocator</classname>, + which is still available as the optional + <classname>__pool_alloc</classname> extension. + Another optional extension, <classname>__mt_alloc</classname>, + is a high-performance pool allocator. +</para> + +<para> + In a suspect executable these pooling allocators can give + the mistaken impression that memory is being leaked, + when in reality the memory "leak" is a pool being used + by the library's allocator and is reclaimed after program + termination. +</para> + +<para> + If you're using memory debugging tools on a program that uses + one of these pooling allocators, you can set the environment variable + <literal>GLIBCXX_FORCE_NEW</literal> to keep extraneous pool allocation + noise from cluttering debug information. + For more details, see the + <link linkend="manual.ext.allocator.mt">mt allocator</link> + documentation and look specifically for <code>GLIBCXX_FORCE_NEW</code>. +</para> + +</section> + </section> <section xml:id="debug.races"><info><title>Data Race Hunting</title></info> diff --git a/libstdc++-v3/doc/xml/manual/evolution.xml b/libstdc++-v3/doc/xml/manual/evolution.xml index 3288e2f6cf2..90b2f7b6f28 100644 --- a/libstdc++-v3/doc/xml/manual/evolution.xml +++ b/libstdc++-v3/doc/xml/manual/evolution.xml @@ -80,11 +80,12 @@ Removal of <filename class="headerfile">ext/tree</filename>, moved to <filename <para> For GCC releases from 2.95 through the 3.1 series, defining <literal>__USE_MALLOC</literal> on the gcc command line would change the - default allocation strategy to instead use <code> malloc</code> and - <function>free</function>. For the 3.2 and 3.3 release series the same + default allocation strategy to instead use <code>malloc</code> and + <code>free</code>. For the 3.2 and 3.3 release series the same functionality was spelled <literal>_GLIBCXX_FORCE_NEW</literal>. From - GCC 3.4 onwards the functionality is enabled by setting - <literal>GLIBCXX_FORCE_NEW</literal> in the environment, see + GCC 3.4 onwards the default allocator uses <code>new</code> anyway, + but for the optional pooling allocators the functionality is enabled by + setting <literal>GLIBCXX_FORCE_NEW</literal> in the environment, see <link linkend="manual.ext.allocator.mt">the mt allocator chapter</link> for details. </para> diff --git a/libstdc++-v3/doc/xml/manual/intro.xml b/libstdc++-v3/doc/xml/manual/intro.xml index 71c2d8bbba0..66ad6e7062d 100644 --- a/libstdc++-v3/doc/xml/manual/intro.xml +++ b/libstdc++-v3/doc/xml/manual/intro.xml @@ -1105,6 +1105,14 @@ requirements of the license of GCC. ill-formed. </para></listitem></varlistentry> + <varlistentry xml:id="manual.bugs.dr2537"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&DR;#2537">2537</link>: + <emphasis>Constructors for <code>priority_queue</code> taking allocators + should call <code>make_heap</code> + </emphasis> + </term> + <listitem><para>Call <code>make_heap</code>. + </para></listitem></varlistentry> + <varlistentry xml:id="manual.bugs.dr2583"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&DR;#2583">2583</link>: <emphasis>There is no way to supply an allocator for <code>basic_string(str, pos)</code> </emphasis> @@ -1112,6 +1120,14 @@ requirements of the license of GCC. <listitem><para>Add new constructor </para></listitem></varlistentry> + <varlistentry xml:id="manual.bugs.dr2586"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&DR;#2586">2586</link>: + <emphasis>Wrong value category used in <code>scoped_allocator_adaptor::construct()</code> + </emphasis> + </term> + <listitem><para>Change internal helper for uses-allocator construction + to always check using const lvalue allocators. + </para></listitem></varlistentry> + <varlistentry xml:id="manual.bugs.dr2684"><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&DR;#2684">2684</link>: <emphasis><code>priority_queue</code> lacking comparator typedef </emphasis> diff --git a/libstdc++-v3/doc/xml/manual/shared_ptr.xml b/libstdc++-v3/doc/xml/manual/shared_ptr.xml index fcbade6d5bf..24e275e95eb 100644 --- a/libstdc++-v3/doc/xml/manual/shared_ptr.xml +++ b/libstdc++-v3/doc/xml/manual/shared_ptr.xml @@ -239,7 +239,7 @@ available policies are: <orderedlist> <listitem> <para> - <constant>_S_Atomic</constant> + <constant>_S_atomic</constant> </para> <para> Selected when GCC supports a builtin atomic compare-and-swap operation @@ -252,7 +252,7 @@ synchronisation. <listitem> <para> - <constant>_S_Mutex</constant> + <constant>_S_mutex</constant> </para> <para> The _Sp_counted_base specialization for this policy contains a mutex, @@ -263,7 +263,7 @@ builtins aren't available so explicit memory barriers are needed in places. <listitem> <para> - <constant>_S_Single</constant> + <constant>_S_single</constant> </para> <para> This policy uses a non-reentrant add_ref_lock() with no locking. It is diff --git a/libstdc++-v3/doc/xml/manual/status_cxx2017.xml b/libstdc++-v3/doc/xml/manual/status_cxx2017.xml index aa0914cff72..462530cb6dd 100644 --- a/libstdc++-v3/doc/xml/manual/status_cxx2017.xml +++ b/libstdc++-v3/doc/xml/manual/status_cxx2017.xml @@ -25,8 +25,8 @@ not in any particular release. </para> <para> -The following table lists new library features that have been accepted into -the C++17 working draft. The "Proposal" column provides a link to the +The following table lists new library features that are included in +the C++17 standard. The "Proposal" column provides a link to the ISO C++ committee proposal that describes the feature, while the "Status" column indicates the first version of GCC that contains an implementation of this feature (if it has been implemented). @@ -382,7 +382,7 @@ Feature-testing recommendations for C++</link>. </link> </entry> <entry align="center"> 7.1 </entry> - <entry><code> </code></entry> + <entry><code>__cpp_lib_raw_memory_algorithms >= 201606L</code></entry> </row> <row> @@ -788,6 +788,31 @@ Feature-testing recommendations for C++</link>. <code> __cpp_lib_to_chars >= 201611 </code></entry> </row> + <row> + <entry> Homogeneous interface for variant, any and optional </entry> + <entry> + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0032r3.pdf"> + P0032R3 + </link> + </entry> + <entry align="center"> 7.1 </entry> + <entry> + <code> __cpp_lib_any >= 201606 </code>, + <code> __cpp_lib_optional >= 201606 </code>, + <code> __cpp_lib_variant >= 201606 </code> + </entry> + </row> + + <row> + <entry> Making Optional Greater Equal Again </entry> + <entry> + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0307r2.pdf"> + P0307R2 + </link> + </entry> + <entry align="center"> 7.1 </entry> + <entry> <code> __cpp_lib_optional >= 201606 </code> </entry> + </row> </tbody> </tgroup> @@ -1049,7 +1074,7 @@ and test for <code>__STDCPP_MATH_SPEC_FUNCS__ >= 201003L</code>. <para> <emphasis>30.10.2.1 [fs.conform.9945]</emphasis> The behavior of the filesystem library implementation will depend on - the target operating system. Some features will not be not supported + the target operating system. Some features will not be supported on some targets. </para> diff --git a/libstdc++-v3/doc/xml/manual/using.xml b/libstdc++-v3/doc/xml/manual/using.xml index 873fac402b5..c9013c32d27 100644 --- a/libstdc++-v3/doc/xml/manual/using.xml +++ b/libstdc++-v3/doc/xml/manual/using.xml @@ -1130,8 +1130,8 @@ g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe enabled for <classname>std::vector<T, std::allocator<T>></classname> and only when <classname>std::allocator</classname> is derived from - <xref linkend="allocator.impl"><classname>new_allocator</classname> - or <classname>malloc_allocator</classname></xref>. The annotations + <link linkend="allocator.impl"><classname>new_allocator</classname> + or <classname>malloc_allocator</classname></link>. The annotations must be present on all vector operations or none, so this macro must be defined to the same value for all translation units that create, destroy or modify vectors. |