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