From ac3636f297d265d12cc31a4f77bbd586a4d2fb1d Mon Sep 17 00:00:00 2001 From: "Loren J. Rittle" Date: Thu, 11 Oct 2001 06:07:50 +0000 Subject: [PATCH] index.html (Is libstdc++-v3 thread-safe?): Rewrite. * docs/html/faq/index.html (Is libstdc++-v3 thread-safe?): Rewrite. * docs/html/23_containers/howto.html (Containers and multithreading): Update. From-SVN: r46175 --- libstdc++-v3/ChangeLog | 6 ++ .../docs/html/23_containers/howto.html | 101 ++++++++---------- libstdc++-v3/docs/html/faq/index.html | 65 ++++++++--- 3 files changed, 102 insertions(+), 70 deletions(-) diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 1397e0f21fc..6f310e786cf 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,9 @@ +2001-10-11 Loren J. Rittle + + * docs/html/faq/index.html (Is libstdc++-v3 thread-safe?): Rewrite. + * docs/html/23_containers/howto.html (Containers and multithreading): + Update. + 2001-10-09 Phil Edwards * docs/html/17_intro/howto.html: Tweak markup and value type. diff --git a/libstdc++-v3/docs/html/23_containers/howto.html b/libstdc++-v3/docs/html/23_containers/howto.html index 58e88df8cd5..9106c82b591 100644 --- a/libstdc++-v3/docs/html/23_containers/howto.html +++ b/libstdc++-v3/docs/html/23_containers/howto.html @@ -192,68 +192,55 @@

Containers and multithreading

-

This section will mention some of the problems in designing MT - programs that use Standard containers. For information on other - aspects of multithreading (e.g., the library as a whole), see - the Received Wisdom on Chapter 17. This section only applies - when gcc and libstdc++-v3 were configured with --enable-threads. -

-

Two excellent pages to read when working with templatized containers - and threads are +

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

+

Two excellent pages to read when working with the Standard C++ + containers and threads are SGI's http://www.sgi.com/tech/stl/thread_safety.html and SGI's - http://www.sgi.com/tech/stl/Allocators.html. The - libstdc++-v3 uses the same definition of thread safety - when discussing design. A key point that beginners may miss is the + http://www.sgi.com/tech/stl/Allocators.html. +

+

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

+

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 - ("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 - is no longer 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 - of the points that would otherwise have to be made here (and does - a better job). -

-

That's much better. Now, the issue of MT has been brought up on - the libstdc++-v3 mailing list as well as the main GCC mailing list - several times. The Chapter 17 HOWTO has some links into the mail - archives, so you can see what's been thrown around. The usual - container (or pseudo-container, depending on how you look at it) - that people have in mind is string, which is one of the - points where libstdc++ departs from the SGI STL. As of the - 2.90.8 snapshot, the libstdc++-v3 string class is safe for - certain kinds of multithreaded access. -

+ ("For most clients,"...), 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). +

For implementing a container which does its own locking, it is - trivial to (as SGI suggests) provide a wrapper class which obtains - the lock, performs the container operation, then releases the lock. - This could be templatized to a certain extent, 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. + 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 to a certain + extent, 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.

Return to top of page or to the FAQ. diff --git a/libstdc++-v3/docs/html/faq/index.html b/libstdc++-v3/docs/html/faq/index.html index 0b711973a8d..898821afcf3 100644 --- a/libstdc++-v3/docs/html/faq/index.html +++ b/libstdc++-v3/docs/html/faq/index.html @@ -686,19 +686,58 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff

5.6 Is libstdc++-v3 thread-safe?

-

Quick answer: no, as of 3.0, most of the library is not - safe for multithreaded access. The string class is MT-safe. -

-

This is assuming that your idea of "multithreaded" - is the same as ours... The general question of multithreading - and libstdc++-v3 is addressed in the chapter-specific advice for - Library Introduction. - Threadsafe containers are covered in more detail in - the Received Wisdom section - on containers. Threading and I/O are discussed in - the I/O chapter. - +

When the system's libc is itself thread-safe, libstdc++-v3 + strives to be thread-safe. The user-code must guard against + concurrent method calls which may access any particular + library object's state. Typically, the application + programmer may infer what object locks must be held based on + the objects referenced in a method call. Without getting + into great detail, here is an example which requires + user-level locks: +

+ 
+       library_class_a shared_object_a;
+
+       thread_main () {
+         library_class_b *object_b = new library_class_b;
+	 shared_object_a.add_b (object_b); // must hold lock for shared_object_a
+	 shared_object_a.mutate (); // must hold lock for shared_object_a
+       }
+
+       // Multiple copies of thread_main() are started in independent threads.
+
+

Under the assumption that object_a and object_b are never + exposed to another thread, here is an example that should not + require any user-level locks: +

+ 
+       thread_main () {
+         library_class_a object_a;
+         library_class_b *object_b = new library_class_b;
+	 object_a.add_b (object_b);
+	 object_a.mutate ();
+       }
+
+

However, as of gcc 3.0 and point releases, beware that there + may be cases where shared nested or global objects (neither + of which are visible to user-code) are affected or used + without any internal locking. + +

+

In some cases, a stronger thread-safe claim is made. The + string class is thread-safe without user-code guards (i.e. a + string object may be shared and accessed between threads + without user-level locking). The IO classes are thread-safe + with user-code guards whenever the same user-visible object + may be accessed by multiple threads. The container classes + are thread-safe with user-code guards whenever the same + container may be accessed by multiple threads. All accesses + to hidden shared objects (e.g. the global allocator objects) + are believed to be properly guarded within the library. +

+

See chapters 17, + 23 and + 27 for more information.

-- 2.30.2