Update of threading documentation in chapter 23

[Loren James Rittle <rittle at latour dot rsch dot comm dot mot dot com>]

Here is an update to the documentation in chapter 23 addressing
threading issues.  It better reflects current reality and explicitly
names the gcc versions where the information applies.  It seemed
better to provide the updated section text here rather than in patch
form.  An update to chapter 17 is on-going and will be posted here.
Some redundant information was removed with a stronger pointer to
chapter 17.  All non-container information was relocated there.

Also, I have removed the explicit reference to "mutex locking" since I
have come to realize that Nathan's ideas about internal library locks
based on the atomic operation abstraction should be investigated.
During the reworked of this aspect of the library configuration, the
main goal was to remove the direct and exclusive use of pthreads, not
rework the internal design that used the mutex abstraction.  The
selection of one locking technique verses another does not directly
affect the user of the library (other than if it is now changed, a
non-name mangling incompatibility is introduced - thus it would have
to be timed for a major gcc release point).

Phil, or anyone else, comments?

Regards,
Loren

<h2><a name="3">Containers and multithreading</a></h2>
   <p>This section discusses issues surrounding the design of
      multithreaded applications which use Standard C++ containers.
      All information in this section is current as of the gcc 3.0
      release and all later point releases.  Although earlier gcc
      releases had a different approach to threading configuration and
      proper compilation, the basic code design rules presented here
      were similar.  For information on all other aspects of
      multithreading as it relates to libstdc++, including details on
      the proper compilation of threaded code (and compatibility between
      threaded and non-threaded code), see Chapter 17.
  </p>
   <p>Two excellent pages to read when working with the Standard C++
      containers and threads are
      <a href="http://www.sgi.com/tech/stl/thread_safety.html";>SGI's
      http://www.sgi.com/tech/stl/thread_safety.html</a> and
      <a href="http://www.sgi.com/tech/stl/Allocators.html";>SGI's
      http://www.sgi.com/tech/stl/Allocators.html</a>.
  </p>
   <p><em>However, please ignore all discussions about the user-level
      configuration of the lock implementation inside the STL
      container-memory allocator on those pages.  For the sake of this
      discussion, libstdc++-v3 configures the SGI STL implementation,
      not you.  This is quite different from how gcc pre-3.0 worked.
      In particular, past advice was for people using g++ to
      explicitly define _PTHREADS or other macros or port-specific
      options on the command line to get a thread-safe STL.  This is
      no longer required for any port and should no longer be done
      unless you really know what you are doing and assume all
      responsibility.</em>
  </p>
   <p>Since the container implementation of libstdc++-v3 uses the SGI
      code, we use the same definition of thread safety as SGI when
      discussing design.  A key point that beginners may miss is the
      fourth major paragraph of the first page mentioned above
      (&quot;For most clients,&quot;...), which points out that
      locking must nearly always be done outside the container, by
      client code (that'd be you, not us).  There is a notable
      exceptions to this rule.  Allocators called while a container or
      element is constructed uses an internal lock obtained and
      released solely within libstdc++-v3 code (in fact, this is the
      reason STL requires any knowledge of the thread configuration).
  </p>
   <p>For implementing a container which does its own locking, it is
      trivial to provide a wrapper class which obtains the lock (as
      SGI suggests), performs the container operation, and then
      releases the lock.  This could be templatized <em>to a certain
      extent</em>, on the underlying container and/or a locking
      mechanism.  Trying to provide a catch-all general template
      solution would probably be more trouble than it's worth.
   </p>