Chapter 17: Library Introduction

Chapter 17 is actually a list of definitions and descriptions used in the following chapters of the Standard when describing the actual library. Here, we use "Introduction" as an introduction to the GNU implementation of the ISO Standard C++ Library.

Contents

• The Standard C++ header files
• Thread-safety
• <foo> vs <foo.h>
• Porting HOWTO

The Standard C++ header files

The Standard C++ Library specifies 50 header files that must be available to all hosted implementations. Actually, the word "files" is a misnomer, since the contents of the headers don't necessarily have to be in any kind of external file. The only rule is that when you #include a certain header, the contents of that header, as defined by the Standard, become available to you, no matter how.

The names of the headers can be easily seen in testsuite/17_intro/headers.cc, which is a small testbed we use to make certain that the headers all compile and run.

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

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.

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;

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]

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 relevent message in the thread; from there you can use "Thread Next" to move down the thread. This farm is in latest-to-oldest order.

• inspired this most recent updating of issues with threading and the SGI STL library. It also contains some example POSIX-multithreaded STL code.
• an early analysis of why __USE_MALLOC should be disabled for the 3.0 release of libstdc++.

• One way of preventing memory leaks by the old default memory allocator in multithreaded code is discussed here.
• This thread concerns strings.
• So does this one. This initial message also refers to another thread in the GCC mailing list...
• which is here, and goes on for some time. Ironically, the initial message in this thread also mentions another threading thread...
• beginning here, and talking about pthreads. (Note that a much more recent message from the first thread in this list notes that pthreads should not be used as a starting point for making libstdc++ threadsafe.)
• This message, this one, and this one are the tops of related threads (all within the same time period) discussing threading and the IO library. Much of it is dealing with the C library, but C++ is included as well.

This section will be updated as new and interesting issues come to light.

Return to top of page or to the FAQ.

<foo> vs <foo.h>

The new-style headers are fully supported in libstdc++-v3. The compiler itself fully supports namespaces, including std::.

For those of you new to ISO C++98, no, that isn't a typo, the headers really have new names. Marshall Cline's C++ FAQ Lite has a good explanation in item [25.4].

Return to top of page or to the FAQ.

See license.html for copying conditions. Comments and suggestions are welcome, and may be sent to the libstdc++ mailing list.