howto.html (Thread-safety): Rename section to ``The Standard C++ library and multithreading'' and update...

        * docs/html/17_intro/howto.html (Thread-safety): Rename
        section to ``The Standard C++ library and multithreading'' and
        update information based on recent mailing list traffic.  Move
        all discussion of __USE_MALLOC to...
        * docs/html/23_containers/howto.html (Containers and multithreading):
        ...here and rework it based on recent mailing list traffic.

From-SVN: r47102

3 files changed, 111 insertions, 50 deletions

diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog
index 3bff900..4feb240 100644
--- a/libstdc++-v3/ChangeLog
+++ b/libstdc++-v3/ChangeLog
@@ -1,3 +1,12 @@
+2001-11-16  Loren J. Rittle  <ljrittle@acm.org>
+
+	* docs/html/17_intro/howto.html (Thread-safety): Rename
+	section to ``The Standard C++ library and multithreading'' and
+	update information based on recent mailing list traffic.  Move
+	all discussion of __USE_MALLOC to...
+	* docs/html/23_containers/howto.html (Containers and multithreading):
+	...here and rework it based on recent mailing list traffic.
+
 2001-11-15  Loren J. Rittle  <ljrittle@acm.org>
 
 	* docs/html/faq/index.html (Is libstdc++-v3 thread-safe?): Clarify
diff --git a/libstdc++-v3/docs/html/17_intro/howto.html b/libstdc++-v3/docs/html/17_intro/howto.html
index 69d9886..c4bfcc3 100644
--- a/libstdc++-v3/docs/html/17_intro/howto.html
+++ b/libstdc++-v3/docs/html/17_intro/howto.html
@@ -25,7 +25,7 @@
 <h1>Contents</h1>
 <ul>
    <li><a href="#2">The Standard C++ header files</a>
-   <li><a href="#3">Thread-safety</a>
+   <li><a href="#3">The Standard C++ library and multithreading</a>
    <li><a href="#4"><code>&lt;foo&gt;</code> vs <code>&lt;foo.h&gt;</code></a>
    <li><a href="porting-howto.html">Porting HOWTO</a>
 </ul>
@@ -50,59 +50,77 @@
    </p>
 
 <hr>
-<h2><a name="3">Thread-safety</a></h2>
-   <p>This is a thorny issue that gets brought up on the libstdc++-v3
-      and gcc mailing lists on a regular basis (probably by a cron job).
-      This entry will mention a very little bit about the general MT
-      issues with libstdc++.  The latest status and quick notes will be
-      in FAQ 5.6.  Some discussion about thread-safe containers will be
-      in section 6.8 (the HOWTOs on containers).  This section only applies
-      when gcc and libstdc++-v3 were configured with --enable-threads.
+<h2><a name="3">The Standard C++ library and multithreading</a></h2>
+   <p>This section discusses issues surrounding the proper compilation
+      of multithreaded applications which use the Standard C++
+      library.  This information is gcc-specific since the C++
+      standard does not address matters of multithreaded applications.
+      Unless explicitly prefaced, all information in this section is
+      current as of the gcc 3.0 release and all later point releases.
    </p>
-   <p>The libstdc++ code (all of it, not just the containers) has been
-      designed so that thread-safety will be easily possible.  The first
-      (!) problem is finding a <em>fast</em> method of implementation
-      portable to all platforms.  A minor problem that pops up every so
-      often is different interpretations of what &quot;thread-safe&quot;
-      means for a library (not a general program).  We currently use the
-      <a href="http://www.sgi.com/tech/stl/thread_safety.html">same
-      definition that SGI</a> uses for their STL subset.
-      <em>Please see the many cautions given in
-      <a href="../23_containers/howto.html">HOWTOs on containers</a>.</em>
+   <p>Earlier gcc releases had a somewhat different approach to
+      threading configuration and proper compilation.  Before gcc 3.0,
+      configuration of the threading model was dictated by compiler
+      command-line options and macros (both of which were somewhat
+      thread-implementation and port-specific).  There were no
+      guarantees related to being able to link code compiled with one
+      set of options and macro setting with another set.  For gcc 3.0,
+      configuration of the threading model used with libraries and
+      user-code is performed when gcc is configured and built using
+      the --enable-threads and --disable-threads options.  The ABI is
+      stable for symbol name-mangling and limited functional
+      compatibility exists between code compiled under different
+      threading models.
    </p>
-   <p>Here is another attempt at explaining the dangers of using the
-      STL with threading support without understanding some important
-      details.  The STL implementation is currently configured to use
-      the high-speed caching memory allocator.  If you absolutely
-      think you must change this on a global basis for your platform
-      to support multi-threading, then please consult all commentary
-      in include/bits/c++config and the HOWTOs on containers.  Be
-      fully aware that you may change the external or internal ABI of
-      libstdc++-v3 when you provide -D__USE_MALLOC on the command line
-      or make a change to that configuration file.
+   <p>All normal disclaimers aside, multithreaded C++ application are
+      only supported when libstdc++ and all user code was built with
+      compilers which report (via <em>gcc/g++ -v</em>) the same thread
+      model and that model is not <em>single</em>.  As long as your
+      final application is actually single-threaded, then it should be
+      safe to mix user code built with a thread model of
+      <em>single</em> with a libstdc++ and other C++ libraries built
+      with another thread model useful on the platform.  Other mixes
+      may or may not work but are not considered supported.  (Thus, if
+      you distribute a shared C++ library in binary form only, it may
+      be best to compile it with a gcc configured with
+      --enable-threads for maximal interchangeability and usefulness
+      with a user population that may have built gcc with either
+      --enable-threads or --disable-threads.)
    </p>
-   <p>If you don't like caches of objects being retained inside the STL, then
-      you might be tempted to define __USE_MALLOC either on the command
-      line or by rebuilding c++config.h.  Please note, once you define
-      __USE_MALLOC, only the malloc allocator is visible to application code
-      (i.e. the typically higher-speed allocator is not even available
-      in this configuration).  There is a better way:  It is possible
-      to force the malloc-based allocator on a per-case-basis for some
-      application code even when the above macro symbol is not defined.
-      The library team generally believes that this is a better way to tune
-      an application for high-speed using this implementation of the STL.
-      Here is one possible example displaying the forcing of the malloc-based
-      allocator over the typically higher-speed default allocator:
-      <pre>
-      std::list &lt;my_type, std::malloc_alloc&gt;  my_malloc_based_list;</pre>
+   <p>When you link a multithreaded application, you will probably
+      need to add a library or flag to g++.  This is a very
+      non-standardized area of gcc across ports.  Some ports support a
+      special flag (the spelling isn't even standardized yet) to add
+      all required macros to a compilation (if any such flags are
+      required then you must provide the flag for all compilations not
+      just linking) and link-library additions and/or replacements at
+      link time.  The documentation is weak.  Here is a quick summary
+      to display how ad hoc this is: On Solaris, both -pthreads and
+      -threads (with subtly different meanings) are honored.  On OSF,
+      -pthread and -threads (with subtly different meanings) are
+      honored.  On Linux/i386, -pthread is honored.  On FreeBSD,
+      -pthread is honored.  Some other ports use other switches.
+      AFAIK, none of this is properly documented anywhere other than
+      in ``gcc -dumpspecs'' (look at lib and cpp entries).
    </p>
-   <p>A recent journal article has described &quot;atomic integer
-      operations,&quot; which would allow us to, well, perform updates
-      on integers atomically, and without requiring an explicit mutex
-      lock.  This appears promising, but the major difficulty is that
-      these operations &quot;may not be available on all systems, and
-      if they are, may have different interfaces.&quot; [quoting from
-      mailing list messages]
+   <p>See <a href="../faq/index.html#3">FAQ</a> (general overview), <a
+      href="../23_containers/howto.html#3">23</a> (containers), and <a
+      href="../27_io/howto.html#9">27</a> (I/O) for more information.
+   </p>
+   <p>The libstdc++-v3 library (unlike libstdc++-v2, all of it, not
+      just the STL) has been designed so that multithreaded
+      applications using it may be written.  The first problem is
+      finding a <em>fast</em> method of implementation portable to all
+      platforms.  Due to historical reasons, some of the library is
+      written against per-CPU-architecture spinlocks and other parts
+      against the gthr.h abstraction layer which is provided by gcc.
+      A minor problem that pops up every so often is different
+      interpretations of what &quot;thread-safe&quot; means for a
+      library (not a general program).  We currently use the <a
+      href="http://www.sgi.com/tech/stl/thread_safety.html">same
+      definition that SGI</a> uses for their STL subset.  However, the
+      exception for read-only containers only applies to the STL
+      components.
    </p>
    <p>Here is a small link farm to threads (no pun) in the mail archives
       that discuss the threading problem.  Each link is to the first
diff --git a/libstdc++-v3/docs/html/23_containers/howto.html b/libstdc++-v3/docs/html/23_containers/howto.html
index 59232b9..8cdaab1 100644
--- a/libstdc++-v3/docs/html/23_containers/howto.html
+++ b/libstdc++-v3/docs/html/23_containers/howto.html
@@ -242,6 +242,40 @@
       mechanism.  Trying to provide a catch-all general template
       solution would probably be more trouble than it's worth.
    </p>
+   <p>The STL implementation is currently configured to use the
+      high-speed caching memory allocator.  If you absolutely think
+      you must change this on a global basis for your platform to
+      better support multi-threading, then please consult all
+      commentary in include/bits/c++config.  (Explicit warning since
+      so many people post after getting confused while attempting
+      this:) Adding -D__USE_MALLOC on the command line is not a good
+      idea.  Related to threading or otherwise, the current
+      recommendation is that users not add any macro defines on the
+      command line to enable features out of libstdc++-v3.  There is
+      no condition under which it will help you without causing other
+      issues to perhaps raise up (possible linkage/ABI problems).  In
+      particular, __USE_MALLOC should only be added to a libstdc++-v3
+      configuration file, include/bits/c++config (where such user
+      action is cautioned against), and the entire library should be
+      rebuilt.  If you do not, then you might be violating the
+      one-definition rule of C/C++ and you might cause yourself untold
+      problems.  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
+      define __USE_MALLOC, we want to hear about it ASAP.  In the
+      past, correctness was the main reason people were led to believe
+      that they should define __USE_MALLOC when using threads.
+   </p>
+   <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
+      application code.  The library team generally believes that this
+      is a better way to tune an application for high-speed using this
+      implementation of the STL.  Here is one possible example
+      displaying the forcing of the malloc-based allocator over the
+      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>Return <a href="#top">to top of page</a> or
       <a href="../faq/index.html">to the FAQ</a>.
    </p>