diff options
| author | ljrittle <ljrittle@138bc75d-0d04-0410-961f-82ee72b054a4> | 2001-05-31 02:45:04 +0000 |
|---|---|---|
| committer | ljrittle <ljrittle@138bc75d-0d04-0410-961f-82ee72b054a4> | 2001-05-31 02:45:04 +0000 |
| commit | ab51bd9094994e05f641597099c103f3b0edeb69 (patch) | |
| tree | 126aefb8df025937b18f4a001d9394c23a071104 /libstdc++-v3 | |
| parent | 28833db5b09cb3099e715f0169808d21e6fdf427 (diff) | |
| download | gcc-ab51bd9094994e05f641597099c103f3b0edeb69.tar.gz | |
* 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.
git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@42732 138bc75d-0d04-0410-961f-82ee72b054a4
Diffstat (limited to 'libstdc++-v3')
| -rw-r--r-- | libstdc++-v3/ChangeLog | 9 | ||||
| -rw-r--r-- | libstdc++-v3/docs/html/17_intro/howto.html | 54 | ||||
| -rw-r--r-- | libstdc++-v3/docs/html/23_containers/howto.html | 25 | ||||
| -rw-r--r-- | 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 <ljrittle@acm.org> + + * 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 <pme@sources.redhat.com> * 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 @@ <META NAME="GENERATOR" CONTENT="vi and eight fingers"> <TITLE>libstdc++-v3 HOWTO: Chapter 17</TITLE> <LINK REL=StyleSheet HREF="../lib3styles.css"> -<!-- $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 $ --> </HEAD> <BODY> @@ -67,6 +67,48 @@ 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 HOWTOs on containers.</EM> + </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. [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.] + </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 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 <void*, std::malloc_alloc> my_malloc_based_list; </P> <P>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. <UL> - <LI> + <LI><A HREF="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00384.html"> + inspired this most recent updating of issues with threading + and the SGI STL library. It also contains some example + POSIX-multithreaded STL code.</A> + <LI> <A HREF="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00136.html"> + an early analysis of why __USE_MALLOC should be disable for + the 3.0 release of libstdc++.</A> </UL> <BR> Here are discussions that took place before the current snapshot; @@ -144,7 +192,7 @@ <P CLASS="fineprint"><EM> Comments and suggestions are welcome, and may be sent to <A HREF="mailto:libstdc++@gcc.gnu.org">the mailing list</A>. -<BR> $Id: howto.html,v 1.3 2001/05/30 08:30:02 ljrittle Exp $ +<BR> $Id: howto.html,v 1.4 2001/05/30 21:54:57 pme Exp $ </EM></P> 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 @@ <META NAME="GENERATOR" CONTENT="vi and eight fingers"> <TITLE>libstdc++-v3 HOWTO: Chapter 23</TITLE> <LINK REL=StyleSheet HREF="../lib3styles.css"> -<!-- $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 $ --> </HEAD> <BODY> @@ -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*). + <EM>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.</EM> </P> <P>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 @@ <P CLASS="fineprint"><EM> Comments and suggestions are welcome, and may be sent to <A HREF="mailto:libstdc++@gcc.gnu.org">the mailing list</A>. -<BR> $Id: howto.html,v 1.3 2001/05/30 08:30:01 ljrittle Exp $ +<BR> $Id: howto.html,v 1.4 2001/05/30 21:55:01 pme Exp $ </EM></P> 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. |