libstdc++-v3/docs/html/17_intro/howto.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
   2 <html>
   3 <head>
   4    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   5    <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)">
   6    <meta name="KEYWORDS" content="HOWTO, libstdc++, gcc, g++, libg++, STL">
   7    <meta name="DESCRIPTION" content="HOWTO for libstdc++ chapter 17.">
   8    <meta name="GENERATOR" content="vi and eight fingers">
   9    <title>libstdc++-v3 HOWTO:  Chapter 17</title>
  10 <link rel="StyleSheet" href="../lib3styles.css">
  11 </head>
  12 <body>
  13
  14 <h1 class="centered"><a name="top">Chapter 17:  Library Introduction</a></h1>
  15
  16 <p>Chapter 17 is actually a list of definitions and descriptions used
  17    in the following chapters of the Standard when describing the actual
  18    library.  Here, we use &quot;Introduction&quot; as an introduction
  19    to the <em>GNU implementation of</em> the ISO Standard C++ Library.
  20 </p>
  21
  22
  23 <!-- ####################################################### -->
  24 <hr>
  25 <h1>Contents</h1>
  26 <ul>
  27    <li><a href="#2">The Standard C++ header files</a>
  28    <li><a href="#3">The Standard C++ library and multithreading</a>
  29    <li><a href="#4"><code>&lt;foo&gt;</code> vs <code>&lt;foo.h&gt;</code></a>
  30    <li><a href="porting-howto.html">Porting HOWTO</a>
  31 </ul>
  32
  33 <hr>
  34
  35 <!-- ####################################################### -->
  36
  37 <h2><a name="2">The Standard C++ header files</a></h2>
  38    <p>The Standard C++ Library specifies 50 header files that must be
  39       available to all hosted implementations.  Actually, the word
  40       &quot;files&quot; is a misnomer, since the contents of the headers
  41       don't necessarily have to be in any kind of external file.  The
  42       only rule is that when you <code>#include</code> a certain header, the
  43       contents of that header, as defined by the Standard, become
  44       available to you, no matter how.
  45    </p>
  46    <p>The names of the headers can be easily seen in
  47       <a href="headers_cc.txt"><code>testsuite/17_intro/headers.cc</code></a>,
  48       which is a small testbed we use to make certain that the headers
  49       all compile and run.
  50    </p>
  51
  52 <hr>
  53 <h2><a name="3">The Standard C++ library and multithreading</a></h2>
  54    <p>This section discusses issues surrounding the proper compilation
  55       of multithreaded applications which use the Standard C++
  56       library.  This information is gcc-specific since the C++
  57       standard does not address matters of multithreaded applications.
  58       Unless explicitly prefaced, all information in this section is
  59       current as of the gcc 3.0 release and all later point releases.
  60    </p>
  61    <p>Earlier gcc releases had a somewhat different approach to
  62       threading configuration and proper compilation.  Before gcc 3.0,
  63       configuration of the threading model was dictated by compiler
  64       command-line options and macros (both of which were somewhat
  65       thread-implementation and port-specific).  There were no
  66       guarantees related to being able to link code compiled with one
  67       set of options and macro setting with another set.  For gcc 3.0,
  68       configuration of the threading model used with libraries and
  69       user-code is performed when gcc is configured and built using
  70       the --enable-threads and --disable-threads options.  The ABI is
  71       stable for symbol name-mangling and limited functional
  72       compatibility exists between code compiled under different
  73       threading models.
  74    </p>
  75    <p>All normal disclaimers aside, multithreaded C++ application are
  76       only supported when libstdc++ and all user code was built with
  77       compilers which report (via <em>gcc/g++ -v</em>) the same thread
  78       model and that model is not <em>single</em>.  As long as your
  79       final application is actually single-threaded, then it should be
  80       safe to mix user code built with a thread model of
  81       <em>single</em> with a libstdc++ and other C++ libraries built
  82       with another thread model useful on the platform.  Other mixes
  83       may or may not work but are not considered supported.  (Thus, if
  84       you distribute a shared C++ library in binary form only, it may
  85       be best to compile it with a gcc configured with
  86       --enable-threads for maximal interchangeability and usefulness
  87       with a user population that may have built gcc with either
  88       --enable-threads or --disable-threads.)
  89    </p>
  90    <p>When you link a multithreaded application, you will probably
  91       need to add a library or flag to g++.  This is a very
  92       non-standardized area of gcc across ports.  Some ports support a
  93       special flag (the spelling isn't even standardized yet) to add
  94       all required macros to a compilation (if any such flags are
  95       required then you must provide the flag for all compilations not
  96       just linking) and link-library additions and/or replacements at
  97       link time.  The documentation is weak.  Here is a quick summary
  98       to display how ad hoc this is: On Solaris, both -pthreads and
  99       -threads (with subtly different meanings) are honored.  On OSF,
 100       -pthread and -threads (with subtly different meanings) are
 101       honored.  On Linux/i386, -pthread is honored.  On FreeBSD,
 102       -pthread is honored.  Some other ports use other switches.
 103       AFAIK, none of this is properly documented anywhere other than
 104       in ``gcc -dumpspecs'' (look at lib and cpp entries).
 105    </p>
 106    <p>See <a href="../faq/index.html#3">FAQ</a> (general overview), <a
 107       href="../23_containers/howto.html#3">23</a> (containers), and <a
 108       href="../27_io/howto.html#9">27</a> (I/O) for more information.
 109    </p>
 110    <p>The libstdc++-v3 library (unlike libstdc++-v2, all of it, not
 111       just the STL) has been designed so that multithreaded
 112       applications using it may be written.  The first problem is
 113       finding a <em>fast</em> method of implementation portable to all
 114       platforms.  Due to historical reasons, some of the library is
 115       written against per-CPU-architecture spinlocks and other parts
 116       against the gthr.h abstraction layer which is provided by gcc.
 117       A minor problem that pops up every so often is different
 118       interpretations of what &quot;thread-safe&quot; means for a
 119       library (not a general program).  We currently use the <a
 120       href="http://www.sgi.com/tech/stl/thread_safety.html">same
 121       definition that SGI</a> uses for their STL subset.  However, the
 122       exception for read-only containers only applies to the STL
 123       components.
 124    </p>
 125    <p>Here is a small link farm to threads (no pun) in the mail archives
 126       that discuss the threading problem.  Each link is to the first
 127       relevent message in the thread; from there you can use
 128       &quot;Thread Next&quot; to move down the thread.  This farm is in
 129       latest-to-oldest order.
 130       <ul>
 131         <li>Our threading expert Loren gives a breakdown of
 132         <a href="http://gcc.gnu.org/ml/libstdc++/2001-10/msg00024.html">the
 133         six situations involving threads</a> for the 3.0 release series.
 134         <li><a href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00384.html">
 135         This message</a> inspired a recent updating of issues with threading
 136         and the SGI STL library.  It also contains some example
 137         POSIX-multithreaded STL code.
 138         <li><a href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00136.html">
 139         Here</a> is an early analysis of why __USE_MALLOC should be disabled
 140         for the 3.0 release of libstdc++.</a>
 141       </ul>
 142       (A large selection of links to older messages has been removed; many
 143       of the messages from 1999 were lost in a disk crash, and the few
 144       people with access to the backup tapes have been too swamped with work
 145       to restore them.  Many of the points have been superceded anyhow.)
 146    </p>
 147    <p>This section will be updated as new and interesting issues come
 148       to light.
 149    </p>
 150    <p>Return <a href="#top">to top of page</a> or
 151       <a href="../faq/index.html">to the FAQ</a>.
 152    </p>
 153
 154 <hr>
 155 <h2><a name="4"><code>&lt;foo&gt;</code> vs <code>&lt;foo.h&gt;</code></a></h2>
 156    <p>The new-style headers are fully supported in libstdc++-v3.  The compiler
 157       itself fully supports namespaces, including <code>std::</code>.
 158    </p>
 159    <p>For those of you new to ISO C++98, no, that isn't a typo, the headers
 160       really have new names.  Marshall Cline's C++ FAQ Lite has a good
 161       explanation in
 162 <a href="http://www.cerfnet.com/~mpcline/On-Line-C++-FAQ/coding-standards.html#[25.4]">item [25.4]</a>.
 163    </p>
 164    <p>Return <a href="#top">to top of page</a> or
 165       <a href="../faq/index.html">to the FAQ</a>.
 166    </p>
 167
 168
 169
 170 <!-- ####################################################### -->
 171
 172 <hr>
 173 <p class="fineprint"><em>
 174 See <a href="license.html">license.html</a> for copying conditions.
 175 Comments and suggestions are welcome, and may be sent to
 176 <a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
 177 </em></p>
 178
 179
 180 </body>
 181 </html>
 182
 183