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

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html
   3           PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   4           "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   5
   6 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   7 <head>
   8    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
   9    <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
  10    <meta name="KEYWORDS" content="HOWTO, libstdc++, gcc, g++, libg++, STL" />
  11    <meta name="DESCRIPTION" content="HOWTO for libstdc++ chapter 17." />
  12    <meta name="GENERATOR" content="vi and eight fingers" />
  13    <title>libstdc++-v3 HOWTO:  Chapter 17</title>
  14 <link rel="StyleSheet" href="../lib3styles.css" />
  15 </head>
  16 <body>
  17
  18 <h1 class="centered"><a name="top">Chapter 17:  Library Introduction</a></h1>
  19
  20 <p>Chapter 17 is actually a list of definitions and descriptions used
  21    in the following chapters of the Standard when describing the actual
  22    library.  Here, we use &quot;Introduction&quot; as an introduction
  23    to the <em>GNU implementation of</em> the ISO Standard C++ Library.
  24 </p>
  25
  26
  27 <!-- ####################################################### -->
  28 <hr />
  29 <h1>Contents</h1>
  30 <ul>
  31    <li><a href="#2">The Standard C++ header files</a></li>
  32    <li><a href="#3">The Standard C++ library and multithreading</a></li>
  33    <li><a href="#4"><code>&lt;foo&gt;</code> vs <code>&lt;foo.h&gt;</code></a></li>
  34    <li><a href="porting-howto.html">Porting HOWTO</a></li>
  35    <li><a href="#5">Behavior specific to libstdc++-v3</a></li>
  36    <li><a href="#6">Preprocessor macros controlling the library</a></li>
  37 </ul>
  38
  39 <hr />
  40
  41 <!-- ####################################################### -->
  42
  43 <h2><a name="2">The Standard C++ header files</a></h2>
  44    <p>The Standard C++ Library specifies 50 header files that must be
  45       available to all hosted implementations.  Actually, the word
  46       &quot;files&quot; is a misnomer, since the contents of the headers
  47       don't necessarily have to be in any kind of external file.  The
  48       only rule is that when you <code>#include</code> a certain header, the
  49       contents of that header, as defined by the Standard, become
  50       available to you, no matter how.
  51    </p>
  52    <p>The names of the headers can be easily seen in
  53       <a href="headers_cc.txt"><code>testsuite/17_intro/headers.cc</code></a>,
  54       which is a small testbed we use to make certain that the headers
  55       all compile and run.
  56    </p>
  57
  58 <hr />
  59 <h2><a name="3">The Standard C++ library and multithreading</a></h2>
  60    <p>This section discusses issues surrounding the proper compilation
  61       of multithreaded applications which use the Standard C++
  62       library.  This information is GCC-specific since the C++
  63       standard does not address matters of multithreaded applications.
  64       Unless explicitly prefaced, all information in this section is
  65       current as of the GCC 3.0 release and all later point releases.
  66    </p>
  67    <p>Earlier GCC releases had a somewhat different approach to
  68       threading configuration and proper compilation.  Before GCC 3.0,
  69       configuration of the threading model was dictated by compiler
  70       command-line options and macros (both of which were somewhat
  71       thread-implementation and port-specific).  There were no
  72       guarantees related to being able to link code compiled with one
  73       set of options and macro setting with another set.  For GCC 3.0,
  74       configuration of the threading model used with libraries and
  75       user-code is performed when GCC is configured and built using
  76       the --enable-threads and --disable-threads options.  The ABI is
  77       stable for symbol name-mangling and limited functional
  78       compatibility exists between code compiled under different
  79       threading models.
  80    </p>
  81    <p>All normal disclaimers aside, multithreaded C++ application are
  82       only supported when libstdc++ and all user code was built with
  83       compilers which report (via <code> gcc/g++ -v </code>) the same thread
  84       model and that model is not <em>single</em>.  As long as your
  85       final application is actually single-threaded, then it should be
  86       safe to mix user code built with a thread model of
  87       <em>single</em> with a libstdc++ and other C++ libraries built
  88       with another thread model useful on the platform.  Other mixes
  89       may or may not work but are not considered supported.  (Thus, if
  90       you distribute a shared C++ library in binary form only, it may
  91       be best to compile it with a GCC configured with
  92       --enable-threads for maximal interchangeability and usefulness
  93       with a user population that may have built GCC with either
  94       --enable-threads or --disable-threads.)
  95    </p>
  96    <p>When you link a multithreaded application, you will probably
  97       need to add a library or flag to g++.  This is a very
  98       non-standardized area of GCC across ports.  Some ports support a
  99       special flag (the spelling isn't even standardized yet) to add
 100       all required macros to a compilation (if any such flags are
 101       required then you must provide the flag for all compilations not
 102       just linking) and link-library additions and/or replacements at
 103       link time.  The documentation is weak.  Here is a quick summary
 104       to display how ad hoc this is: On Solaris, both -pthreads and
 105       -threads (with subtly different meanings) are honored.  On OSF,
 106       -pthread and -threads (with subtly different meanings) are
 107       honored.  On Linux/i386, -pthread is honored.  On FreeBSD,
 108       -pthread is honored.  Some other ports use other switches.
 109       AFAIK, none of this is properly documented anywhere other than
 110       in ``gcc -dumpspecs'' (look at lib and cpp entries).
 111    </p>
 112    <p>See <a href="../faq/index.html#3">FAQ</a> (general overview), <a
 113       href="../23_containers/howto.html#3">23</a> (containers), and <a
 114       href="../27_io/howto.html#9">27</a> (I/O) for more information.
 115    </p>
 116    <p>The libstdc++-v3 library (unlike libstdc++-v2, all of it, not
 117       just the STL) has been designed so that multithreaded
 118       applications using it may be written.  The first problem is
 119       finding a <em>fast</em> method of implementation portable to all
 120       platforms.  Due to historical reasons, some of the library is
 121       written against per-CPU-architecture spinlocks and other parts
 122       against the gthr.h abstraction layer which is provided by gcc.
 123       A minor problem that pops up every so often is different
 124       interpretations of what &quot;thread-safe&quot; means for a
 125       library (not a general program).  We currently use the <a
 126       href="http://www.sgi.com/tech/stl/thread_safety.html">same
 127       definition that SGI</a> uses for their STL subset.  However, the
 128       exception for read-only containers only applies to the STL
 129       components.
 130    </p>
 131    <p>Here is a small link farm to threads (no pun) in the mail archives
 132       that discuss the threading problem.  Each link is to the first
 133       relevant message in the thread; from there you can use
 134       &quot;Thread Next&quot; to move down the thread.  This farm is in
 135       latest-to-oldest order.
 136    </p>
 137       <ul>
 138         <li>Our threading expert Loren gives a breakdown of
 139         <a href="http://gcc.gnu.org/ml/libstdc++/2001-10/msg00024.html">the
 140         six situations involving threads</a> for the 3.0 release series.</li>
 141         <li><a href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00384.html">
 142         This message</a> inspired a recent updating of issues with threading
 143         and the SGI STL library.  It also contains some example
 144         POSIX-multithreaded STL code.</li>
 145       </ul>
 146    <p> (A large selection of links to older messages has been removed; many
 147       of the messages from 1999 were lost in a disk crash, and the few
 148       people with access to the backup tapes have been too swamped with work
 149       to restore them.  Many of the points have been superseded anyhow.)
 150    </p>
 151    <p>This section will be updated as new and interesting issues come
 152       to light.
 153    </p>
 154    <p>Return <a href="#top">to top of page</a> or
 155       <a href="../faq/index.html">to the FAQ</a>.
 156    </p>
 157
 158 <hr />
 159 <h2><a name="4"><code>&lt;foo&gt;</code> vs <code>&lt;foo.h&gt;</code></a></h2>
 160    <p>The new-style headers are fully supported in libstdc++-v3.  The compiler
 161       itself fully supports namespaces, including <code>std::</code>.
 162    </p>
 163    <p>For those of you new to ISO C++98, no, that isn't a typo, the headers
 164       really have new names.  Marshall Cline's C++ FAQ Lite has a good
 165       explanation in
 166 <a href="http://www.parashift.com/c++-faq-lite/coding-standards.html#faq-27.4">item [27.4]</a>.
 167    </p>
 168    <p>Return <a href="#top">to top of page</a> or
 169       <a href="../faq/index.html">to the FAQ</a>.
 170    </p>
 171
 172 <hr />
 173 <h2><a name="5">Behavior specific to libstdc++-v3</a></h2>
 174    <p>The ISO standard defines the following phrase:
 175    </p>
 176      <blockquote><dl>
 177      <dt><code>[1.3.5] implementation-defined behavior</code></dt>
 178      <dd>behavior, for a well-formed program construct and correct data, that
 179          depends on the implementation <strong>and that each implementation
 180          shall document</strong>.
 181      </dd>
 182      </dl></blockquote>
 183    <p>We do so here, for the C++ library only.  Behavior of the compiler,
 184       linker, runtime loader, and other elements of &quot;the
 185       implementation&quot; are documented elsewhere.  Everything listed in
 186       Annex B, Implemenation Qualities, are also part of the compiler, not
 187       the library.
 188    </p>
 189    <p>For each entry, we give the section number of the standard, when
 190       applicable.  This list is probably incomplet and inkorrekt.
 191    </p>
 192    <p><strong>[1.9]/11 #3</strong> If <code>isatty(3)</code> is true, then
 193       interactive stream support is implied.
 194    </p>
 195    <p><strong>[17.4.4.5]</strong> Non-reentrant functions are probably best
 196       discussed in the various sections on multithreading (see above).
 197    </p>
 198    <!-- [17.4.4.8]/3 says any function that doesn't have an exception-spec
 199         can throw whatever we want; see also its footnote.  Let's list those
 200         in the sections where the function itself occurs.
 201    -->
 202    <p><strong>[18.1]/4</strong> The type of <code>NULL</code> is described
 203       <a href="../18_support/howto.html#1">here</a>.
 204    </p>
 205    <p><strong>[18.3]/8</strong> Even though it's listed in the library
 206       sections, libstdc++-v3 has zero control over what the cleanup code hands
 207       back to the runtime loader.  Talk to the compiler people.  :-)
 208    </p>
 209    <p><strong>[18.4.2.1]/5</strong> (bad_alloc),<br />
 210       <strong>[18.5.2]/5</strong> (bad_cast),<br />
 211       <strong>[18.5.3]/5</strong> (bad_typeid),<br />
 212       <strong>[18.6.1]/8</strong> (exception),<br />
 213       <strong>[18.6.2.1]/5</strong> (bad_exception):  The <code>what()</code>
 214       member function of class <code>std::exception</code>, and these other
 215       classes publicly derived from it, simply returns the name of the
 216       class.  But they are the <em>mangled</em> names; you will need to call
 217       <code>c++filt</code> and pass the names as command-line parameters to
 218       demangle them, or call a
 219       <a href="../18_support/howto.html#5">runtime demangler function</a>.
 220       (The classes in <code>&lt;stdexcept&gt;</code> have constructors which
 221       require an argument to use later for <code>what()</code> calls, so the
 222       problem of <code>what()</code>'s value does not arise in most
 223       user-defined exceptions.)
 224    </p>
 225    <p><strong>[18.5.1]/7</strong> The return value of
 226       <code>std::type_info::name()</code> is the mangled type name (see the
 227       previous entry for more).
 228    </p>
 229    <p><strong>[20.1.5]/5</strong> <em>&quot;Implementors are encouraged to
 230       supply libraries that can accept allocators that encapsulate more
 231       general memory models and that support non-equal instances.  In such
 232       implementations, any requirements imposed on allocators by containers
 233       beyond those requirements that appear in Table 32, and the semantics
 234       of containers and algorithms when allocator instances compare
 235       non-equal, are implementation-defined.&quot;</em>  As yet we don't
 236       have any allocators which compare non-equal, so we can't describe how
 237       they behave.
 238    </p>
 239    <p><strong>[21.1.3.1]/3,4</strong>,<br />
 240       <strong>[21.1.3.2]/2</strong>,<br />
 241       <strong>[23.*]'s foo::iterator</strong>,<br />
 242       <strong>[27.*]'s foo::*_type</strong>,<br />
 243       <strong>others...</strong>
 244       Nope, these types are called implementation-defined because you
 245       shouldn't be taking advantage of their underlying types.  Listing them
 246       here would defeat the purpose.  :-)
 247    </p>
 248    <p><strong>[21.1.3.1]/5</strong> I don't really know about the mbstate_t
 249       stuff... see the <a href="../22_locale/howto.html">chapter 22 notes</a>
 250       for what does exist.
 251    </p>
 252    <p><strong>[22.*]</strong> Anything and everything we have on locale
 253       implemenation will be described
 254       <a href="../22_locale/howto.html">over here</a>.
 255    </p>
 256    <p><strong>[26.2.8]/9</strong> I have no idea what
 257       <code>complex&lt;T&gt;</code>'s pow(0,0) returns.
 258    </p>
 259    <p><strong>[27.4.2.4]/2</strong> Calling
 260       <code>std::ios_base::sync_with_stdio</code> after I/O has already been
 261       performed on the standard stream objects will
 262       flush the buffers, and <!-- this line might go away -->
 263       destroy and recreate the underlying buffer instances.  Whether or not
 264       the previously-written I/O is destroyed in this process depends mostly
 265       on the --enable-libio choice:  for stdio, if the written data is
 266       already in the stdio buffer, the data may be completely safe!
 267    </p>
 268    <p><strong>[27.6.1.1.2]</strong>,<br />
 269       <strong>[27.6.2.3]</strong> The I/O sentry ctor and dtor can perform
 270       additional work than the minimum required.  We are not currently taking
 271       advantage of this yet.
 272    </p>
 273    <p><strong>[27.7.1.3]/16</strong>,<br />
 274       <strong>[27.8.1.4]/10</strong>
 275       The effects of <code>pubsetbuf/setbuf</code> are described
 276       <a href="../27_io/howto.html#2">in this chapter</a>.
 277    </p>
 278    <p><strong>[27.8.1.4]/16</strong> Calling <code>fstream::sync</code> when
 279       a get area exists will... whatever <code>fflush()</code> does, I think.
 280    </p>
 281    <p>Return <a href="#top">to top of page</a> or
 282       <a href="../faq/index.html">to the FAQ</a>.
 283    </p>
 284
 285 <hr />
 286 <h2><a name="6">Preprocessor macros controlling the library</a></h2>
 287    <p>Some of the semantics of the libstdc++-v3 implementation are
 288       controlled by preprocessor macros, both during build/installation and
 289       during compilation of user code.  Many of these choices are made when
 290       the library is built and installed (actually, during
 291       <a href="../configopts.html">the configuration step</a>, with the
 292       various --enable/--disable choices being translated to #define/#undef).
 293    </p>
 294    <p>All library macros begin with <code>_GLIBCPP_</code>.  The fact that
 295       these symbols start with a leading underscore should give you a clue
 296       that (by default) they aren't meant to be changed by the user.  :-)
 297    </p>
 298    <p>These macros are all gathered in the file <code>c++config.h</code>,
 299       which is generated during installation.  <strong>You must assume that
 300       these macros cannot be redefined by your own code</strong>, unless we
 301       document otherwise here.  Some of the choices control code which has
 302       already been compiled (i.e., libstdc++.a/.so).  If you explicitly
 303       #define or #undef these macros, the <em>headers</em> may see different
 304       code paths, but the <em>libraries</em> which you link against will not.
 305       If you want to experiment with different values, you must change the
 306       config headers before building/installing the library.
 307    </p>
 308    <p>Below are macros which, for 3.1 and later, you may change yourself,
 309       in your own code with #define/#undef or with -D/-U compiler flags.
 310       The default state of the symbol is listed.  &quot;Configurable&quot;
 311       (or &quot;Not configurable&quot;) means that the symbol is initially
 312       chosen (or not) based on --enable/--disable options at configure time.
 313    </p>
 314     <dl>
 315     <dt><code>_GLIBCPP_DEPRECATED</code></dt>
 316     <dd>Undefined by default.  Not configurable.  Turning this on enables
 317         older ARM-style iostreams code, and other anachronisms.  This may be
 318         useful in updating old C++ programs which no longer meet the
 319         requirements of the language.
 320     </dd>
 321     <!--
 322      Can this actually be turned off and still produce a working lib?  Must
 323      check.  -pme
 324      No, it can't.  Hmmm.  -pme
 325     <dt><code>_GLIBCPP_RESOLVE_LIB_DEFECTS</code></dt>
 326     <dd>Defined by default.  Not configurable.  The library follows
 327         corrections and updates from the ISO committee, see
 328         <a href="../faq/index.html#5_2">here</a> and
 329         <a href="../ext/howto.html#5">here</a> for more on this feature.
 330         If you have code which depends on the first version of the standard,
 331         you might try undefining this macro.
 332     </dd>
 333     -->
 334     <dt><code>_GLIBCPP_CONCEPT_CHECKS</code></dt>
 335     <dd>Undefined by default.  Configurable.  When defined, performs
 336         compile-time checking on certain template instantiations to detect
 337         violations of the requirements of the standard.  This is described
 338         in more detail <a href="../19_diagnostics/howto.html#3">here</a>.
 339     </dd>
 340     <!--
 341     <dt><code></code></dt>
 342     <dd>
 343     </dd>
 344     -->
 345     </dl>
 346    <p>Return <a href="#top">to top of page</a> or
 347       <a href="../faq/index.html">to the FAQ</a>.
 348    </p>
 349
 350
 351
 352 <!-- ####################################################### -->
 353
 354 <hr />
 355 <p class="fineprint"><em>
 356 See <a href="license.html">license.html</a> for copying conditions.
 357 Comments and suggestions are welcome, and may be sent to
 358 <a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
 359 </em></p>
 360
 361
 362 </body>
 363 </html>
 364
 365