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@sources.redhat.com (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 <!-- $Id: howto.html,v 1.4 2001/05/30 21:54:57 pme Exp $ -->
  12 </HEAD>
  13 <BODY>
  14
  15 <H1 CLASS="centered"><A NAME="top">Chapter 17:  Library Introduction</A></H1>
  16
  17 <P>Chapter 17 is actually a list of definitions and descriptions used
  18    in the following chapters of the Standard when describing the actual
  19    library.  Here, we use &quot;Introduction&quot; as an introduction
  20    to the <EM>GNU implementation of</EM> the ISO Standard C++ Library.
  21 </P>
  22
  23
  24 <!-- ####################################################### -->
  25 <HR>
  26 <H1>Contents</H1>
  27 <UL>
  28    <LI><A HREF="#2">The Standard C++ header files</A>
  29    <LI><A HREF="#3">Thread-safety</A>
  30    <LI><A HREF="#4"><TT>&lt;foo&gt;</TT> vs <TT>&lt;foo.h&gt;</TT></A>
  31    <LI><A HREF="porting-howto.html">Porting-howto</A>
  32 </UL>
  33
  34 <HR>
  35
  36 <!-- ####################################################### -->
  37
  38 <H2><A NAME="2">The Standard C++ header files</A></H2>
  39    <P>The Standard C++ Library specifies 50 header files that must be
  40       available to all hosted implementations.  Actually, the word
  41       &quot;files&quot; is a misnomer, since the contents of the headers
  42       don't necessarily have to be in any kind of external file.  The
  43       only rule is that when you <TT>#include</TT> a certain header, the
  44       contents of that header, as defined by the Standard, become
  45       available to you, no matter how.
  46    </P>
  47    <P>The names of the headers can be easily seen in
  48       <A HREF="headers_cc.txt"><TT>testsuite/17_intro/headers.cc</TT></A>,
  49       which is a small testbed we use to make certain that the headers
  50       all compile and run.
  51    </P>
  52
  53 <HR>
  54 <H2><A NAME="3">Thread-safety</A></H2>
  55    <P>This is a thorny issue that gets brought up on the libstdc++-v3
  56       and gcc mailing lists on a regular basis (probably by a cron job).
  57       This entry will mention a very little bit about the general MT
  58       issues with libstdc++.  The latest status and quick notes will be
  59       in FAQ 5.6.  Some discussion about thread-safe containers will be
  60       in section 6.8 (the HOWTOs on containers).
  61    </P>
  62    <P>The libstdc++ code (all of it, not just the containers) has been
  63       designed so that thread-safety will be easily possible.  The first
  64       (!) problem is finding a <EM>fast</EM> method of implementation
  65       portable to all platforms.  A minor problem that pops up every so
  66       often is different interpretations of what &quot;thread-safe&quot;
  67       means for a library (not a general program).  We currently use the
  68       <A HREF="http://www.sgi.com/tech/stl/thread_safety.html">same
  69       definition that SGI</A> uses for their STL subset.
  70       <EM>Please see the many cautions given in HOWTOs on containers.</EM>
  71    </P>
  72    <P>
  73       Here is another attempt at explaining the dangers of using the
  74       STL with threading support without understanding some important
  75       details.  The STL implementation is currently configured to use
  76       the high-speed caching memory allocator.  If you absolutely
  77       think you must change this on a global basis for your platform
  78       to support multi-threading, then please consult all commentary
  79       in include/bits/c++config and the HOWTOs on containers.  Be
  80       fully aware that you may change the external or internal ABI of
  81       libstdc++-v3 when you provide -D__USE_MALLOC on the command line
  82       or make a change to that configuration file. [Placeholder in
  83       case other patches don't make it before the 3.0 release: That
  84       memory allocator can appear buggy in multithreaded C++ programs
  85       (and has been reported to leak memory), if STL is misconfigured
  86       for your platform.  You may need to provide -D_PTHREADS on the
  87       command line in this case to ensure the memory allocator for
  88       containers is really protected by a mutex.  Also, be aware that
  89       you just changed the ABI of libstdc++-v3 when you did that thus
  90       your entire application and all libraries must be compiled with
  91       compatible flags.  The STL implementation doesn't currently
  92       protect you from changing the mutex locking implementation to
  93       one that doesn't really play together with the implementation
  94       you may have compiled other application code with.]
  95    </P>
  96    <P>
  97       If you don't like caches of objects being retained inside the
  98       STL, then you might be tempted to define __USE_MALLOC either on
  99       the command line or by rebuilding c++config.h.  Please note,
 100       once you define __USE_MALLOC, only the malloc allocator is
 101       visible to application code (i.e. the typically higher-speed
 102       allocator is not even available in this configuration).  There
 103       is a better way: It is possible to force the malloc-based
 104       allocator on a per-case-basis for some application code even
 105       when the above macro symbol is not defined.  The author of this
 106       comment believes that is a better way to tune an application for
 107       high-speed using this implementation of the STL.  Here is one
 108       possible example displaying the forcing of the malloc-based
 109       allocator over the typically higher-speed default allocator:
 110
 111       std::list <void*, std::malloc_alloc> my_malloc_based_list;
 112    </P>
 113    <P>A recent journal article has described &quot;atomic integer
 114       operations,&quot; which would allow us to, well, perform updates
 115       on integers atomically, and without requiring an explicit mutex
 116       lock.  This appears promising, but the major difficulty is that
 117       these operations &quot;may not be available on all systems, and
 118       if they are, may have different interfaces.&quot; [quoting from
 119       mailing list messages]
 120    </P>
 121    <P>Here is a small link farm to threads (no pun) in the mail archives
 122       that discuss the threading problem.  Each link is to the first
 123       relevent message in the thread; from there you can use
 124       &quot;Thread Next&quot; to move down the thread.  This farm is in
 125       latest-to-oldest order.
 126       <UL>
 127         <LI><A HREF="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00384.html">
 128         inspired this most recent updating of issues with threading
 129         and the SGI STL library.  It also contains some example
 130         POSIX-multithreaded STL code.</A>
 131         <LI> <A HREF="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00136.html">
 132         an early analysis of why __USE_MALLOC should be disable for
 133         the 3.0 release of libstdc++.</A>
 134       </UL>
 135       <BR>
 136       Here are discussions that took place before the current snapshot;
 137       they are still relevant and instructive.
 138       <BR>
 139       <UL>
 140         <LI>One way of preventing memory leaks by the old default memory
 141             allocator in multithreaded code is
 142             <A HREF="http://gcc.gnu.org/ml/gcc/1999-11n/msg00431.html">discussed here</A>.
 143         <LI><A HREF="http://gcc.gnu.org/ml/libstdc++/1999-q3/msg00167.html">This thread
 144             concerns strings</A>.
 145         <LI><A HREF="http://gcc.gnu.org/ml/libstdc++/1999-q2/msg00339.html">So does this
 146             one</A>.  This initial message also refers to another
 147             thread in the GCC mailing list...
 148         <LI><A HREF="http://gcc.gnu.org/ml/gcc/1999-06n/msg00680.html">which is here</A>,
 149             and goes on for some time.  Ironically, the initial message
 150             in this thread also mentions another threading thread...
 151         <LI><A HREF="http://gcc.gnu.org/ml/gcc-bugs/1999-04n/msg00777.html">beginning here</A>,
 152             and talking about pthreads.  (Note that a much more recent
 153             message from the first thread in this list notes that
 154             <A HREF="http://gcc.gnu.org/ml/libstdc++/1999-q3/msg00176.html">pthreads
 155             should not be used as a starting point</A> for making
 156             libstdc++ threadsafe.)
 157         <LI><A HREF="http://gcc.gnu.org/ml/libstdc++/1999-q2/msg00168.html">This
 158             message</A>,
 159             <A HREF="http://gcc.gnu.org/ml/libstdc++/1999-q2/msg00159.html">this one</A>,
 160             and <A HREF="http://gcc.gnu.org/ml/libstdc++/1999-q2/msg00156.html">this one</A>
 161             are the tops of related threads (all within the same time
 162             period) discussing threading and the IO library.  Much of it
 163             is dealing with the C library, but C++ is included as well.
 164       </UL>
 165    </P>
 166    <P>This section will be updated as new and interesting issues come
 167       to light.
 168    </P>
 169    <P>Return <A HREF="#top">to top of page</A> or
 170       <A HREF="../faq/index.html">to the FAQ</A>.
 171    </P>
 172
 173 <HR>
 174 <H2><A NAME="4"><TT>&lt;foo&gt;</TT> vs <TT>&lt;foo.h&gt;</TT></A></H2>
 175    <P>The new-style headers are fully supported in libstdc++-v3.  The compiler
 176       itself fully supports namespaces, including <TT>std::</TT>.
 177    </P>
 178    <P>For those of you new to ISO C++98, no, that isn't a typo, the headers
 179       really have new names.  Marshall Cline's C++ FAQ Lite has a good
 180       explanation in
 181 <A HREF="http://www.cerfnet.com/~mpcline/On-Line-C++-FAQ/coding-standards.html#[25.4]">item [25.4]</A>.
 182    </P>
 183    <P>Return <A HREF="#top">to top of page</A> or
 184       <A HREF="../faq/index.html">to the FAQ</A>.
 185    </P>
 186
 187
 188
 189 <!-- ####################################################### -->
 190
 191 <HR>
 192 <P CLASS="fineprint"><EM>
 193 Comments and suggestions are welcome, and may be sent to
 194 <A HREF="mailto:libstdc++@gcc.gnu.org">the mailing list</A>.
 195 <BR> $Id: howto.html,v 1.4 2001/05/30 21:54:57 pme Exp $
 196 </EM></P>
 197
 198
 199 </BODY>
 200 </HTML>
 201
 202