From 08014c2d20a82d0835fa3992559972cbbeaa0c45 Mon Sep 17 00:00:00 2001 From: ljrittle Date: Fri, 16 Nov 2001 20:59:10 +0000 Subject: [PATCH] * 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. git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@47102 138bc75d-0d04-0410-961f-82ee72b054a4 --- libstdc++-v3/ChangeLog | 9 ++ libstdc++-v3/docs/html/17_intro/howto.html | 118 ++++++++++++++---------- libstdc++-v3/docs/html/23_containers/howto.html | 34 +++++++ 3 files changed, 111 insertions(+), 50 deletions(-) diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 3bff900f5c5..4feb2404051 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,12 @@ +2001-11-16 Loren J. Rittle + + * 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 * 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 69d9886887f..c4bfcc3f287 100644 --- a/libstdc++-v3/docs/html/17_intro/howto.html +++ b/libstdc++-v3/docs/html/17_intro/howto.html @@ -25,7 +25,7 @@

Contents

@@ -50,59 +50,77 @@

-

Thread-safety

-

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. +

The Standard C++ library and multithreading

+

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.

-

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 fast method of implementation - portable to all platforms. A minor problem that pops up every so - often is different interpretations of what "thread-safe" - 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. +

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.

-

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. +

All normal disclaimers aside, multithreaded C++ application are + only supported when libstdc++ and all user code was built with + compilers which report (via gcc/g++ -v) the same thread + model and that model is not single. 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 + single 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.)

-

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: - 

-      std::list <my_type, std::malloc_alloc>  my_malloc_based_list;
+

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).

-

A recent journal article has described "atomic integer - operations," 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 "may not be available on all systems, and - if they are, may have different interfaces." [quoting from - mailing list messages] +

See FAQ (general overview), 23 (containers), and 27 (I/O) for more information. +

+

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 fast 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 "thread-safe" means for a + library (not a general program). We currently use the same + definition that SGI uses for their STL subset. However, the + exception for read-only containers only applies to the STL + components.

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 59232b95dda..8cdaab1615a 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.

+

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. +

+

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: + 

+      std::list <my_type, std::__malloc_alloc_template<0> >  my_malloc_based_list;
+

Return to top of page or to the FAQ.

-- 2.11.0