Whole document tree

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 and multithreading
• <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.

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.

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.

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

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

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

• Our threading expert Loren gives a breakdown of the six situations involving threads for the 3.0 release series.
• This message inspired a recent updating of issues with threading and the SGI STL library. It also contains some example POSIX-multithreaded STL code.

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.