libstdc++-v3 HOWTO: Chapter 17

From 85836c0b6339c6e5e5636016e6b7ad3e39e843e1 Mon Sep 17 00:00:00 2001 From: "Loren J. Rittle" Date: Thu, 31 May 2001 02:45:04 +0000 Subject: [PATCH] c++config (__USE_MALLOC): Do not define it. * include/bits/c++config (__USE_MALLOC): Do not define it. Document why not and give pointers to more information. * docs/html/23_containers/howto.html: Update documentation to reflect recent understanding of problem. * docs/html/17_intro/howto.html: Likewise. From-SVN: r42732 --- libstdc++-v3/ChangeLog | 9 ++++ libstdc++-v3/docs/html/17_intro/howto.html | 54 +++++++++++++++++-- .../docs/html/23_containers/howto.html | 25 ++++++++- libstdc++-v3/include/bits/c++config | 11 ++-- 4 files changed, 91 insertions(+), 8 deletions(-) diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 73bbce6b157..efbefbd8bd6 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,12 @@ +2001-05-30 Loren J. Rittle + + * include/bits/c++config (__USE_MALLOC): Do not define it. + Document why not and give pointers to more information. + + * docs/html/23_containers/howto.html: Update documentation + to reflect recent understanding of problem. + * docs/html/17_intro/howto.html: Likewise. + 2001-05-30 Phil Edwards * docs/doxygen/user.cfg.in: Minor addition. diff --git a/libstdc++-v3/docs/html/17_intro/howto.html b/libstdc++-v3/docs/html/17_intro/howto.html index f284aa5b2b2..3b1cf13d6c4 100644 --- a/libstdc++-v3/docs/html/17_intro/howto.html +++ b/libstdc++-v3/docs/html/17_intro/howto.html @@ -8,7 +8,7 @@ libstdc++-v3 HOWTO: Chapter 17 - + @@ -67,6 +67,48 @@ means for a library (not a general program). We currently use the same definition that SGI uses for their STL subset. + Please see the many cautions given in HOWTOs on containers. +

+ 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. [Placeholder in + case other patches don't make it before the 3.0 release: That + memory allocator can appear buggy in multithreaded C++ programs + (and has been reported to leak memory), if STL is misconfigured + for your platform. You may need to provide -D_PTHREADS on the + command line in this case to ensure the memory allocator for + containers is really protected by a mutex. Also, be aware that + you just changed the ABI of libstdc++-v3 when you did that thus + your entire application and all libraries must be compiled with + compatible flags. The STL implementation doesn't currently + protect you from changing the mutex locking implementation to + one that doesn't really play together with the implementation + you may have compiled other application code with.] +

+ 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 author of this + comment believes that 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: + + std::list my_malloc_based_list;

A recent journal article has described "atomic integer operations," which would allow us to, well, perform updates @@ -82,7 +124,13 @@ "Thread Next" to move down the thread. This farm is in latest-to-oldest order.

Here are discussions that took place before the current snapshot; @@ -144,7 +192,7 @@

Comments and suggestions are welcome, and may be sent to the mailing list. -
$Id: howto.html,v 1.3 2001/05/30 08:30:02 ljrittle Exp $ +
$Id: howto.html,v 1.4 2001/05/30 21:54:57 pme Exp $

diff --git a/libstdc++-v3/docs/html/23_containers/howto.html b/libstdc++-v3/docs/html/23_containers/howto.html index 603c49939ed..bc05128bd99 100644 --- a/libstdc++-v3/docs/html/23_containers/howto.html +++ b/libstdc++-v3/docs/html/23_containers/howto.html @@ -8,7 +8,7 @@ libstdc++-v3 HOWTO: Chapter 23 - + @@ -199,6 +199,27 @@ ("For most clients,"...), pointing out that locking must nearly always be done outside the container, by client code (that'd be you, not us *grin*). + However, please take caution when considering the discussion + about the user-level configuration of the mutex lock + implementation inside the STL container-memory allocator on that + page. For the sake of this discussion, libstdc++-v3 configures + the SGI STL implementation, not you. We attempt to configure + the mutex lock as is best for your platform. In particular, + past advice was for people using g++ to explicitly define + _PTHREADS on the command line to get a thread-safe STL. This + may or may not be required for your port. It may or may not be + a good idea for your port. Extremely big caution: if you + compile some of your application code against the STL with one + set of threading flags and macros and another portion of the + code with different flags and macros that influence the + selection of the mutex lock, you may well end up with multiple + locking mechanisms in use which don't impact each other in the + manner that they should. Everything might link and all code + might have been built with a perfectly reasonable thread model + but you may have two internal ABIs in play within the + application. This might produce races, memory leaks and fatal + crashes. In any multithreaded application using STL, this + is the first thing to study well before blaming the allocator.

You didn't read it, did you? *sigh* I'm serious, go read the SGI page. It's really good and doesn't take long, and makes most @@ -237,7 +258,7 @@

Comments and suggestions are welcome, and may be sent to the mailing list. -
$Id: howto.html,v 1.3 2001/05/30 08:30:01 ljrittle Exp $ +
$Id: howto.html,v 1.4 2001/05/30 21:55:01 pme Exp $

diff --git a/libstdc++-v3/include/bits/c++config b/libstdc++-v3/include/bits/c++config index f87f58e03fd..d3d99baa926 100644 --- a/libstdc++-v3/include/bits/c++config +++ b/libstdc++-v3/include/bits/c++config @@ -101,9 +101,14 @@ # define __STL_UNWIND(action) #endif -// This is the "underlying allocator" for STL. The alternatives are -// homegrown schemes involving a kind of mutex and free list; see stl_alloc.h. -#define __USE_MALLOC +// Default to the typically high-speed, pool-based allocator (as +// libstdc++-v2) instead of the malloc-based allocator (libstdc++-v3 +// snapshots). See libstdc++-v3/docs/html/17_intro/howto.html for +// details on why you don't want to override this setting. Ensure +// that threads are properly configured on your platform before +// assigning blame to the STL container-memory allocator. After doing +// so, please report any possible issues to libstdc++@gcc.gnu.org . +// Do not blindly #define __USE_MALLOC here or on the command line. // The remainder of the prewritten config is mostly automatic; all the // user hooks are listed above. -- 2.30.2