Commit 7145a3dd by Phil Edwards

explanations.html: New section, empty for now.

2001-11-27  Phil Edwards  <pme@gcc.gnu.org>

	* docs/html/explanations.html:  New section, empty for now.
	* docs/html/17_intro/howto.html:  Cleanup.  Move unrelated link...
	* docs/html/23_containers/howto.html:  ...to here.  Break up and
	rewrap threading discussion to emphasize warning.  Move malloc text...
	* docs/html/ext/howto.html:  ...to here.  New section.  Describe
	allocators and __USE_MALLOC effects.
	* docs/html/ext/sgiexts.html:  Mention their code.

From-SVN: r47391
parent 8a63621f
2001-11-27 Phil Edwards <pme@gcc.gnu.org>
* docs/html/explanations.html: New section, empty for now.
* docs/html/17_intro/howto.html: Cleanup. Move unrelated link...
* docs/html/23_containers/howto.html: ...to here. Break up and
rewrap threading discussion to emphasize warning. Move malloc text...
* docs/html/ext/howto.html: ...to here. New section. Describe
allocators and __USE_MALLOC effects.
* docs/html/ext/sgiexts.html: Mention their code.
2001-11-24 Joseph S. Myers <jsm28@cam.ac.uk> 2001-11-24 Joseph S. Myers <jsm28@cam.ac.uk>
* docs/doxygen/maint.cfg.in, docs/doxygen/user.cfg.in, * docs/doxygen/maint.cfg.in, docs/doxygen/user.cfg.in,
......
...@@ -74,7 +74,7 @@ ...@@ -74,7 +74,7 @@
</p> </p>
<p>All normal disclaimers aside, multithreaded C++ application are <p>All normal disclaimers aside, multithreaded C++ application are
only supported when libstdc++ and all user code was built with only supported when libstdc++ and all user code was built with
compilers which report (via <em>gcc/g++ -v</em>) the same thread compilers which report (via <code> gcc/g++ -v </code>) the same thread
model and that model is not <em>single</em>. As long as your model and that model is not <em>single</em>. As long as your
final application is actually single-threaded, then it should be final application is actually single-threaded, then it should be
safe to mix user code built with a thread model of safe to mix user code built with a thread model of
...@@ -89,7 +89,7 @@ ...@@ -89,7 +89,7 @@
</p> </p>
<p>When you link a multithreaded application, you will probably <p>When you link a multithreaded application, you will probably
need to add a library or flag to g++. This is a very need to add a library or flag to g++. This is a very
non-standardized area of gcc across ports. Some ports support a non-standardized area of GCC across ports. Some ports support a
special flag (the spelling isn't even standardized yet) to add special flag (the spelling isn't even standardized yet) to add
all required macros to a compilation (if any such flags are all required macros to a compilation (if any such flags are
required then you must provide the flag for all compilations not required then you must provide the flag for all compilations not
...@@ -135,9 +135,6 @@ ...@@ -135,9 +135,6 @@
This message</a> inspired a recent updating of issues with threading This message</a> inspired a recent updating of issues with threading
and the SGI STL library. It also contains some example and the SGI STL library. It also contains some example
POSIX-multithreaded STL code. POSIX-multithreaded STL code.
<li><a href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00136.html">
Here</a> is an early analysis of why __USE_MALLOC should be disabled
for the 3.0 release of libstdc++.</a>
</ul> </ul>
(A large selection of links to older messages has been removed; many (A large selection of links to older messages has been removed; many
of the messages from 1999 were lost in a disk crash, and the few of the messages from 1999 were lost in a disk crash, and the few
......
...@@ -244,14 +244,22 @@ ...@@ -244,14 +244,22 @@
</p> </p>
<p>The STL implementation is currently configured to use the <p>The STL implementation is currently configured to use the
high-speed caching memory allocator. If you absolutely think high-speed caching memory allocator. If you absolutely think
you must change this on a global basis for your platform to you must change this on a global basis for your platform to better
better support multi-threading, then please consult all support multi-threading, then please consult all commentary in
commentary in include/bits/c++config. (Explicit warning since include/bits/stl_alloc.h and the allocators link below.
so many people post after getting confused while attempting <blockquote>
this:) Adding -D__USE_MALLOC on the command line is not a good <p>(Explicit warning since so many people get confused while
idea. Related to threading or otherwise, the current attempting this:)
recommendation is that users not add any macro defines on the </p>
command line to enable features out of libstdc++-v3. There is <p><strong>Adding -D__USE_MALLOC on the command
line is almost certainly a bad idea.</strong> Memory efficiency is
almost guaranteed to suffer as a result; this is
<a href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00136.html">why
we disabled it for 3.0 in the first place</a>.
</p>
<p>Related to threading or otherwise, the current recommendation is
that users not add any macro defines on the command line to remove or
otherwise disable features of libstdc++-v3. There is
no condition under which it will help you without causing other no condition under which it will help you without causing other
issues to perhaps raise up (possible linkage/ABI problems). In issues to perhaps raise up (possible linkage/ABI problems). In
particular, __USE_MALLOC should only be added to a libstdc++-v3 particular, __USE_MALLOC should only be added to a libstdc++-v3
...@@ -259,22 +267,22 @@ ...@@ -259,22 +267,22 @@
action is cautioned against), and the entire library should be action is cautioned against), and the entire library should be
rebuilt. If you do not, then you might be violating the rebuilt. If you do not, then you might be violating the
one-definition rule of C/C++ and you might cause yourself untold one-definition rule of C/C++ and you might cause yourself untold
problems. If you find any platform where gcc reports a problems.
threading model other than single and where libstdc++-v3 builds </p>
</blockquote>
If you find any platform where gcc reports a
threading model other than single, and where libstdc++-v3 builds
a buggy container allocator when used with threads unless you a buggy container allocator when used with threads unless you
define __USE_MALLOC, we want to hear about it ASAP. In the define __USE_MALLOC, we want to hear about it ASAP. In the
past, correctness was the main reason people were led to believe past, correctness was the main reason people were led to believe
that they should define __USE_MALLOC when using threads. that they should define __USE_MALLOC when using threads.
</p> </p>
<p>There is a better way (not standardized yet): It is possible to <p>There is a better way (not standardized yet): It is possible to
force the malloc-based allocator on a per-case-basis for some force the malloc-based allocator on a per-case-basis for some
application code. The library team generally believes that this application code. The library team generally believes that this
is a better way to tune an application for high-speed using this is a better way to tune an application for high-speed using this
implementation of the STL. Here is one possible example implementation of the STL. There is
displaying the forcing of the malloc-based allocator over the <a href="../ext/howto.html#3">more information on allocators here</a>.
typically higher-speed default allocator:
<pre>
std::list &lt;my_type, std::__malloc_alloc_template&lt;0&gt; &gt; my_malloc_based_list;</pre>
</p> </p>
<p>Return <a href="#top">to top of page</a> or <p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
......
...@@ -61,6 +61,15 @@ design</a></h1> ...@@ -61,6 +61,15 @@ design</a></h1>
</p> </p>
<hr>
<a name="alloc"><h3>Internal Allocators</h3></a>
<p>
</p>
<p>Return <a href="#top">to the top of the page</a> or
<a href="http://gcc.gnu.org/libstdc++/">to the homepage</a>.
</p>
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr>
......
...@@ -25,7 +25,7 @@ libstdc++-v3</a></h1> ...@@ -25,7 +25,7 @@ libstdc++-v3</a></h1>
for a description). Not every chapter may have extensions, and the for a description). Not every chapter may have extensions, and the
extensions may come and go. Also, this page is incomplete because the extensions may come and go. Also, this page is incomplete because the
author is pressed for time. Check back often; the latest change was on author is pressed for time. Check back often; the latest change was on
$Date: 2001/10/11 18:41:47 $ (UTC). $Date: 2001/11/23 16:29:01 $ (UTC).
</p> </p>
<p>Descriptions range from the scanty to the verbose. You should also check <p>Descriptions range from the scanty to the verbose. You should also check
...@@ -60,6 +60,9 @@ libstdc++-v3</a></h1> ...@@ -60,6 +60,9 @@ libstdc++-v3</a></h1>
<li>mem_fun adaptor helpers mem_fun1 and mem_fun1_ref are provided for <li>mem_fun adaptor helpers mem_fun1 and mem_fun1_ref are provided for
backwards compatibility. backwards compatibility.
</ul></p> </ul></p>
<p>20.4.1 can use several different allocators; they are described on the
main extensions page.
</p>
<p>20.4.3 is extended with a special version of <p>20.4.3 is extended with a special version of
<code>get_temporary_buffer</code> taking a second argument. The argument <code>get_temporary_buffer</code> taking a second argument. The argument
is a pointer, which is ignored, but can be used to specify the template is a pointer, which is ignored, but can be used to specify the template
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment