libstdc++-v3/doc/html/manual/using_concurrency.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Concurrency</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.3" /><meta name="keywords" content="&#10;      ISO C++&#10;    , &#10;      library&#10;    " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="using.html" title="Chapter 3. Using" /><link rel="prev" href="using_macros.html" title="Macros" /><link rel="next" href="using_exceptions.html" title="Exceptions" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Concurrency</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="using_macros.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td width="20%" align="right"> <a accesskey="n" href="using_exceptions.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.intro.using.concurrency"></a>Concurrency</h2></div></div></div><p>This section discusses issues surrounding the proper compilation
   4       of multithreaded applications which use the Standard C++
   5       library.  This information is GCC-specific since the C++
   6       standard does not address matters of multithreaded applications.
   7    </p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.concurrency.prereq"></a>Prerequisites</h3></div></div></div><p>All normal disclaimers aside, multithreaded C++ application are
   8       only supported when libstdc++ and all user code was built with
   9       compilers which report (via <code class="code"> gcc/g++ -v </code>) the same thread
  10       model and that model is not <span class="emphasis"><em>single</em></span>.  As long as your
  11       final application is actually single-threaded, then it should be
  12       safe to mix user code built with a thread model of
  13       <span class="emphasis"><em>single</em></span> with a libstdc++ and other C++ libraries built
  14       with another thread model useful on the platform.  Other mixes
  15       may or may not work but are not considered supported.  (Thus, if
  16       you distribute a shared C++ library in binary form only, it may
  17       be best to compile it with a GCC configured with
  18       --enable-threads for maximal interchangeability and usefulness
  19       with a user population that may have built GCC with either
  20       --enable-threads or --disable-threads.)
  21    </p><p>When you link a multithreaded application, you will probably
  22       need to add a library or flag to g++.  This is a very
  23       non-standardized area of GCC across ports.  Some ports support a
  24       special flag (the spelling isn't even standardized yet) to add
  25       all required macros to a compilation (if any such flags are
  26       required then you must provide the flag for all compilations not
  27       just linking) and link-library additions and/or replacements at
  28       link time.  The documentation is weak.  Here is a quick summary
  29       to display how ad hoc this is: On Solaris, both -pthreads and
  30       -threads (with subtly different meanings) are honored.  On OSF,
  31       -pthread and -threads (with subtly different meanings) are
  32       honored.  On Linux/i386, -pthread is honored.  On FreeBSD,
  33       -pthread is honored.  Some other ports use other switches.
  34       AFAIK, none of this is properly documented anywhere other than
  35       in ``gcc -dumpspecs'' (look at lib and cpp entries).
  36    </p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.concurrency.thread_safety"></a>Thread Safety</h3></div></div></div><p>
  37 We currently use the <a class="ulink" href="http://www.sgi.com/tech/stl/thread_safety.html" target="_top">SGI STL</a> definition of thread safety.
  38 </p><p>The library strives to be thread-safe when all of the following
  39          conditions are met:
  40       </p><div class="itemizedlist"><ul type="disc"><li><p>The system's libc is itself thread-safe,
  41        </p></li><li><p>
  42            The compiler in use reports a thread model other than
  43            'single'. This can be tested via output from <code class="code">gcc
  44            -v</code>. Multi-thread capable versions of gcc output
  45            something like this:
  46          </p><pre class="programlisting">
  47 %gcc -v
  48 Using built-in specs.
  49 ...
  50 Thread model: posix
  51 gcc version 4.1.2 20070925 (Red Hat 4.1.2-33)
  52 </pre><p>Look for "Thread model" lines that aren't equal to "single."</p></li><li><p>
  53          Requisite command-line flags are used for atomic operations
  54          and threading. Examples of this include <code class="code">-pthread</code>
  55          and <code class="code">-march=native</code>, although specifics vary
  56          depending on the host environment. See <a class="ulink" href="http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html" target="_top">Machine
  57          Dependent Options</a>.
  58        </p></li><li><p>
  59            An implementation of atomicity.h functions
  60            exists for the architecture in question. See the internals documentation for more <a class="link" href="internals.html#internals.thread_safety" title="Thread Safety">details</a>.
  61        </p></li></ul></div><p>The user-code must guard against concurrent method calls which may
  62          access any particular library object's state.  Typically, the
  63          application programmer may infer what object locks must be held
  64          based on the objects referenced in a method call.  Without getting
  65          into great detail, here is an example which requires user-level
  66          locks:
  67       </p><pre class="programlisting">
  68      library_class_a shared_object_a;
  69
  70      thread_main () {
  71        library_class_b *object_b = new library_class_b;
  72        shared_object_a.add_b (object_b);   // must hold lock for shared_object_a
  73        shared_object_a.mutate ();          // must hold lock for shared_object_a
  74      }
  75
  76      // Multiple copies of thread_main() are started in independent threads.</pre><p>Under the assumption that object_a and object_b are never exposed to
  77          another thread, here is an example that should not require any
  78          user-level locks:
  79       </p><pre class="programlisting">
  80      thread_main () {
  81        library_class_a object_a;
  82        library_class_b *object_b = new library_class_b;
  83        object_a.add_b (object_b);
  84        object_a.mutate ();
  85      } </pre><p>All library objects are safe to use in a multithreaded program as
  86          long as each thread carefully locks out access by any other
  87          thread while it uses any object visible to another thread, i.e.,
  88          treat library objects like any other shared resource.  In general,
  89          this requirement includes both read and write access to objects;
  90          unless otherwise documented as safe, do not assume that two threads
  91          may access a shared standard library object at the same time.
  92       </p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.concurrency.atomics"></a>Atomics</h3></div></div></div><p>
  93     </p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.concurrency.io"></a>IO</h3></div></div></div><p>This gets a bit tricky.  Please read carefully, and bear with me.
  94    </p><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="concurrency.io.structure"></a>Structure</h4></div></div></div><p>A wrapper
  95       type called <code class="code">__basic_file</code> provides our abstraction layer
  96       for the <code class="code">std::filebuf</code> classes.  Nearly all decisions dealing
  97       with actual input and output must be made in <code class="code">__basic_file</code>.
  98    </p><p>A generic locking mechanism is somewhat in place at the filebuf layer,
  99       but is not used in the current code.  Providing locking at any higher
 100       level is akin to providing locking within containers, and is not done
 101       for the same reasons (see the links above).
 102    </p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="concurrency.io.defaults"></a>Defaults</h4></div></div></div><p>The __basic_file type is simply a collection of small wrappers around
 103       the C stdio layer (again, see the link under Structure).  We do no
 104       locking ourselves, but simply pass through to calls to <code class="code">fopen</code>,
 105       <code class="code">fwrite</code>, and so forth.
 106    </p><p>So, for 3.0, the question of "is multithreading safe for I/O"
 107       must be answered with, "is your platform's C library threadsafe
 108       for I/O?"  Some are by default, some are not; many offer multiple
 109       implementations of the C library with varying tradeoffs of threadsafety
 110       and efficiency.  You, the programmer, are always required to take care
 111       with multiple threads.
 112    </p><p>(As an example, the POSIX standard requires that C stdio FILE*
 113        operations are atomic.  POSIX-conforming C libraries (e.g, on Solaris
 114        and GNU/Linux) have an internal mutex to serialize operations on
 115        FILE*s.  However, you still need to not do stupid things like calling
 116        <code class="code">fclose(fs)</code> in one thread followed by an access of
 117        <code class="code">fs</code> in another.)
 118    </p><p>So, if your platform's C library is threadsafe, then your
 119       <code class="code">fstream</code> I/O operations will be threadsafe at the lowest
 120       level.  For higher-level operations, such as manipulating the data
 121       contained in the stream formatting classes (e.g., setting up callbacks
 122       inside an <code class="code">std::ofstream</code>), you need to guard such accesses
 123       like any other critical shared resource.
 124    </p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="concurrency.io.future"></a>Future</h4></div></div></div><p> A
 125       second choice may be available for I/O implementations:  libio.  This is
 126       disabled by default, and in fact will not currently work due to other
 127       issues.  It will be revisited, however.
 128    </p><p>The libio code is a subset of the guts of the GNU libc (glibc) I/O
 129       implementation.  When libio is in use, the <code class="code">__basic_file</code>
 130       type is basically derived from FILE.  (The real situation is more
 131       complex than that... it's derived from an internal type used to
 132       implement FILE.  See libio/libioP.h to see scary things done with
 133       vtbls.)  The result is that there is no "layer" of C stdio
 134       to go through; the filebuf makes calls directly into the same
 135       functions used to implement <code class="code">fread</code>, <code class="code">fwrite</code>,
 136       and so forth, using internal data structures.  (And when I say
 137       "makes calls directly," I mean the function is literally
 138       replaced by a jump into an internal function.  Fast but frightening.
 139       *grin*)
 140    </p><p>Also, the libio internal locks are used.  This requires pulling in
 141       large chunks of glibc, such as a pthreads implementation, and is one
 142       of the issues preventing widespread use of libio as the libstdc++
 143       cstdio implementation.
 144    </p><p>But we plan to make this work, at least as an option if not a future
 145       default.  Platforms running a copy of glibc with a recent-enough
 146       version will see calls from libstdc++ directly into the glibc already
 147       installed.  For other platforms, a copy of the libio subsection will
 148       be built and included in libstdc++.
 149    </p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="concurrency.io.alt"></a>Alternatives</h4></div></div></div><p>Don't forget that other cstdio implementations are possible.  You could
 150       easily write one to perform your own forms of locking, to solve your
 151       "interesting" problems.
 152    </p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.concurrency.containers"></a>Containers</h3></div></div></div><p>This section discusses issues surrounding the design of
 153       multithreaded applications which use Standard C++ containers.
 154       All information in this section is current as of the gcc 3.0
 155       release and all later point releases.  Although earlier gcc
 156       releases had a different approach to threading configuration and
 157       proper compilation, the basic code design rules presented here
 158       were similar.  For information on all other aspects of
 159       multithreading as it relates to libstdc++, including details on
 160       the proper compilation of threaded code (and compatibility between
 161       threaded and non-threaded code), see Chapter 17.
 162    </p><p>Two excellent pages to read when working with the Standard C++
 163       containers and threads are
 164       <a class="ulink" href="http://www.sgi.com/tech/stl/thread_safety.html" target="_top">SGI's
 165       http://www.sgi.com/tech/stl/thread_safety.html</a> and
 166       <a class="ulink" href="http://www.sgi.com/tech/stl/Allocators.html" target="_top">SGI's
 167       http://www.sgi.com/tech/stl/Allocators.html</a>.
 168    </p><p><span class="emphasis"><em>However, please ignore all discussions about the user-level
 169       configuration of the lock implementation inside the STL
 170       container-memory allocator on those pages.  For the sake of this
 171       discussion, libstdc++ configures the SGI STL implementation,
 172       not you.  This is quite different from how gcc pre-3.0 worked.
 173       In particular, past advice was for people using g++ to
 174       explicitly define _PTHREADS or other macros or port-specific
 175       compilation options on the command line to get a thread-safe
 176       STL.  This is no longer required for any port and should no
 177       longer be done unless you really know what you are doing and
 178       assume all responsibility.</em></span>
 179    </p><p>Since the container implementation of libstdc++ uses the SGI
 180       code, we use the same definition of thread safety as SGI when
 181       discussing design.  A key point that beginners may miss is the
 182       fourth major paragraph of the first page mentioned above
 183       ("For most clients,"...), which points out that
 184       locking must nearly always be done outside the container, by
 185       client code (that'd be you, not us).  There is a notable
 186       exceptions to this rule.  Allocators called while a container or
 187       element is constructed uses an internal lock obtained and
 188       released solely within libstdc++ code (in fact, this is the
 189       reason STL requires any knowledge of the thread configuration).
 190    </p><p>For implementing a container which does its own locking, it is
 191       trivial to provide a wrapper class which obtains the lock (as
 192       SGI suggests), performs the container operation, and then
 193       releases the lock.  This could be templatized <span class="emphasis"><em>to a certain
 194       extent</em></span>, on the underlying container and/or a locking
 195       mechanism.  Trying to provide a catch-all general template
 196       solution would probably be more trouble than it's worth.
 197    </p><p>The library implementation may be configured to use the
 198       high-speed caching memory allocator, which complicates thread
 199       safety issues. For all details about how to globally override
 200       this at application run-time
 201       see <a class="link" href="using_macros.html" title="Macros">here</a>. Also
 202       useful are details
 203       on <a class="link" href="memory.html#manual.util.memory.allocator" title="Allocators">allocator</a>
 204       options and capabilities.
 205    </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="using_macros.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="using.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="using_exceptions.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Macros </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Exceptions</td></tr></table></div></body></html>