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

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.

(A large selection of links to older messages has been removed; many of the messages from 1999 were lost in a disk crash, and the few people with access to the backup tapes have been too swamped with work to restore them. Many of the points have been superceded anyhow.)

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.