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"><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-NS Stylesheets V1.78.1" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="using.html" title="Chapter 3. Using" /><link rel="prev" href="using_dynamic_or_shared.html" title="Linking" /><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_dynamic_or_shared.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="section"><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
   3       of multithreaded applications which use the Standard C++
   4       library.  This information is GCC-specific since the C++
   5       standard does not address matters of multithreaded applications.
   6    </p><div class="section"><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
   7       only supported when libstdc++ and all user code was built with
   8       compilers which report (via <code class="code"> gcc/g++ -v </code>) the same thread
   9       model and that model is not <span class="emphasis"><em>single</em></span>.  As long as your
  10       final application is actually single-threaded, then it should be
  11       safe to mix user code built with a thread model of
  12       <span class="emphasis"><em>single</em></span> with a libstdc++ and other C++ libraries built
  13       with another thread model useful on the platform.  Other mixes
  14       may or may not work but are not considered supported.  (Thus, if
  15       you distribute a shared C++ library in binary form only, it may
  16       be best to compile it with a GCC configured with
  17       --enable-threads for maximal interchangeability and usefulness
  18       with a user population that may have built GCC with either
  19       --enable-threads or --disable-threads.)
  20    </p><p>When you link a multithreaded application, you will probably
  21       need to add a library or flag to g++.  This is a very
  22       non-standardized area of GCC across ports.  Some ports support a
  23       special flag (the spelling isn't even standardized yet) to add
  24       all required macros to a compilation (if any such flags are
  25       required then you must provide the flag for all compilations not
  26       just linking) and link-library additions and/or replacements at
  27       link time.  The documentation is weak.  On several targets (including
  28       GNU/Linux, Solaris and various BSDs) -pthread is honored.
  29       Some other ports use other switches.
  30       This is not well documented anywhere other than
  31       in "gcc -dumpspecs" (look at the 'lib' and 'cpp' entries).
  32    </p><p>
  33      Some uses of <code class="classname">std::atomic</code> also require linking
  34      to <code class="filename">libatomic</code>.
  35    </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.concurrency.thread_safety"></a>Thread Safety</h3></div></div></div><p>
  36 In the terms of the 2011 C++ standard a thread-safe program is one which
  37 does not perform any conflicting non-atomic operations on memory locations
  38 and so does not contain any data races.
  39 The standard places requirements on the library to ensure that no data
  40 races are caused by the library itself or by programs which use the
  41 library correctly (as described below).
  42 The C++11 memory model and library requirements are a more formal version
  43 of the <a class="link" href="http://www.sgi.com/tech/stl/thread_safety.html" target="_top">SGI STL</a> definition of thread safety, which the library used
  44 prior to the 2011 standard.
  45 </p><p>The library strives to be thread-safe when all of the following
  46          conditions are met:
  47       </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>The system's libc is itself thread-safe,
  48        </p></li><li class="listitem"><p>
  49            The compiler in use reports a thread model other than
  50            'single'. This can be tested via output from <code class="code">gcc
  51            -v</code>. Multi-thread capable versions of gcc output
  52            something like this:
  53          </p><pre class="programlisting">
  54 %gcc -v
  55 Using built-in specs.
  56 ...
  57 Thread model: posix
  58 gcc version 4.1.2 20070925 (Red Hat 4.1.2-33)
  59 </pre><p>Look for "Thread model" lines that aren't equal to "single."</p></li><li class="listitem"><p>
  60          Requisite command-line flags are used for atomic operations
  61          and threading. Examples of this include <code class="code">-pthread</code>
  62          and <code class="code">-march=native</code>, although specifics vary
  63          depending on the host environment. See
  64          <a class="link" href="using.html#manual.intro.using.flags" title="Command Options">Command Options</a> and
  65          <a class="link" href="http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html" target="_top">Machine
  66          Dependent Options</a>.
  67        </p></li><li class="listitem"><p>
  68            An implementation of the
  69            <code class="filename">atomicity.h</code> functions
  70            exists for the architecture in question. See the
  71            <a class="link" href="internals.html#internals.thread_safety" title="Thread Safety">internals
  72            documentation</a> for more details.
  73        </p></li></ul></div><p>The user code must guard against concurrent function calls which
  74          access any particular library object's state when one or more of
  75          those accesses modifies the state. An object will be modified by
  76          invoking a non-const member function on it or passing it as a
  77          non-const argument to a library function. An object will not be
  78          modified by invoking a const member function on it or passing it to
  79          a function as a pointer- or reference-to-const.
  80          Typically, the application
  81          programmer may infer what object locks must be held based on the
  82          objects referenced in a function call and whether the objects are
  83          accessed as const or non-const.  Without getting
  84          into great detail, here is an example which requires user-level
  85          locks:
  86       </p><pre class="programlisting">
  87      library_class_a shared_object_a;
  88
  89      void thread_main () {
  90        library_class_b *object_b = new library_class_b;
  91        shared_object_a.add_b (object_b);   // must hold lock for shared_object_a
  92        shared_object_a.mutate ();          // must hold lock for shared_object_a
  93      }
  94
  95      // 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
  96          another thread, here is an example that does not require any
  97          user-level locks:
  98       </p><pre class="programlisting">
  99      void thread_main () {
 100        library_class_a object_a;
 101        library_class_b *object_b = new library_class_b;
 102        object_a.add_b (object_b);
 103        object_a.mutate ();
 104      } </pre><p>All library types are safe to use in a multithreaded program
 105          if objects are not shared between threads or as
 106          long each thread carefully locks out access by any other
 107          thread while it modifies any object visible to another thread.
 108          Unless otherwise documented, the only exceptions to these rules
 109          are atomic operations on the types in
 110          <code class="filename">&lt;atomic&gt;</code>
 111          and lock/unlock operations on the standard mutex types in
 112          <code class="filename">&lt;mutex&gt;</code>. These
 113          atomic operations allow concurrent accesses to the same object
 114          without introducing data races.
 115       </p><p>The following member functions of standard containers can be
 116          considered to be const for the purposes of avoiding data races:
 117          <code class="code">begin</code>, <code class="code">end</code>, <code class="code">rbegin</code>, <code class="code">rend</code>,
 118          <code class="code">front</code>, <code class="code">back</code>, <code class="code">data</code>,
 119          <code class="code">find</code>, <code class="code">lower_bound</code>, <code class="code">upper_bound</code>,
 120          <code class="code">equal_range</code>, <code class="code">at</code>
 121          and, except in associative or unordered associative containers,
 122          <code class="code">operator[]</code>. In other words, although they are non-const
 123          so that they can return mutable iterators, those member functions
 124          will not modify the container.
 125          Accessing an iterator might cause a non-modifying access to
 126          the container the iterator refers to (for example incrementing a
 127          list iterator must access the pointers between nodes, which are part
 128          of the container and so conflict with other accesses to the container).
 129       </p><p>Programs which follow the rules above will not encounter data
 130          races in library code, even when using library types which share
 131          state between distinct objects.  In the example below the
 132          <code class="code">shared_ptr</code> objects share a reference count, but
 133          because the code does not perform any non-const operations on the
 134          globally-visible object, the library ensures that the reference
 135          count updates are atomic and do not introduce data races:
 136       </p><pre class="programlisting">
 137     std::shared_ptr&lt;int&gt; global_sp;
 138
 139     void thread_main() {
 140       auto local_sp = global_sp;  // OK, copy constructor's parameter is reference-to-const
 141
 142       int i = *global_sp;         // OK, operator* is const
 143       int j = *local_sp;          // OK, does not operate on global_sp
 144
 145       // *global_sp = 2;          // NOT OK, modifies int visible to other threads
 146       // *local_sp = 2;           // NOT OK, modifies int visible to other threads
 147
 148       // global_sp.reset();       // NOT OK, reset is non-const
 149       local_sp.reset();           // OK, does not operate on global_sp
 150     }
 151
 152     int main() {
 153       global_sp.reset(new int(1));
 154       std::thread t1(thread_main);
 155       std::thread t2(thread_main);
 156       t1.join();
 157       t2.join();
 158     }
 159       </pre><p>For further details of the C++11 memory model see Hans-J. Boehm's
 160       <a class="link" href="http://www.hpl.hp.com/personal/Hans_Boehm/c++mm/user-faq.html" target="_top">Threads
 161       and memory model for C++</a> pages, particularly the <a class="link" href="http://www.hpl.hp.com/personal/Hans_Boehm/c++mm/threadsintro.html" target="_top">introduction</a>
 162       and <a class="link" href="http://www.hpl.hp.com/personal/Hans_Boehm/c++mm/user-faq.html" target="_top">FAQ</a>.
 163       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.concurrency.atomics"></a>Atomics</h3></div></div></div><p>
 164     </p></div><div class="section"><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.
 165    </p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="concurrency.io.structure"></a>Structure</h4></div></div></div><p>A wrapper
 166       type called <code class="code">__basic_file</code> provides our abstraction layer
 167       for the <code class="code">std::filebuf</code> classes.  Nearly all decisions dealing
 168       with actual input and output must be made in <code class="code">__basic_file</code>.
 169    </p><p>A generic locking mechanism is somewhat in place at the filebuf layer,
 170       but is not used in the current code.  Providing locking at any higher
 171       level is akin to providing locking within containers, and is not done
 172       for the same reasons (see the links above).
 173    </p></div><div class="section"><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
 174       the C stdio layer (again, see the link under Structure).  We do no
 175       locking ourselves, but simply pass through to calls to <code class="code">fopen</code>,
 176       <code class="code">fwrite</code>, and so forth.
 177    </p><p>So, for 3.0, the question of "is multithreading safe for I/O"
 178       must be answered with, "is your platform's C library threadsafe
 179       for I/O?"  Some are by default, some are not; many offer multiple
 180       implementations of the C library with varying tradeoffs of threadsafety
 181       and efficiency.  You, the programmer, are always required to take care
 182       with multiple threads.
 183    </p><p>(As an example, the POSIX standard requires that C stdio FILE*
 184        operations are atomic.  POSIX-conforming C libraries (e.g, on Solaris
 185        and GNU/Linux) have an internal mutex to serialize operations on
 186        FILE*s.  However, you still need to not do stupid things like calling
 187        <code class="code">fclose(fs)</code> in one thread followed by an access of
 188        <code class="code">fs</code> in another.)
 189    </p><p>So, if your platform's C library is threadsafe, then your
 190       <code class="code">fstream</code> I/O operations will be threadsafe at the lowest
 191       level.  For higher-level operations, such as manipulating the data
 192       contained in the stream formatting classes (e.g., setting up callbacks
 193       inside an <code class="code">std::ofstream</code>), you need to guard such accesses
 194       like any other critical shared resource.
 195    </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="concurrency.io.future"></a>Future</h4></div></div></div><p> A
 196       second choice may be available for I/O implementations:  libio.  This is
 197       disabled by default, and in fact will not currently work due to other
 198       issues.  It will be revisited, however.
 199    </p><p>The libio code is a subset of the guts of the GNU libc (glibc) I/O
 200       implementation.  When libio is in use, the <code class="code">__basic_file</code>
 201       type is basically derived from FILE.  (The real situation is more
 202       complex than that... it's derived from an internal type used to
 203       implement FILE.  See libio/libioP.h to see scary things done with
 204       vtbls.)  The result is that there is no "layer" of C stdio
 205       to go through; the filebuf makes calls directly into the same
 206       functions used to implement <code class="code">fread</code>, <code class="code">fwrite</code>,
 207       and so forth, using internal data structures.  (And when I say
 208       "makes calls directly," I mean the function is literally
 209       replaced by a jump into an internal function.  Fast but frightening.
 210       *grin*)
 211    </p><p>Also, the libio internal locks are used.  This requires pulling in
 212       large chunks of glibc, such as a pthreads implementation, and is one
 213       of the issues preventing widespread use of libio as the libstdc++
 214       cstdio implementation.
 215    </p><p>But we plan to make this work, at least as an option if not a future
 216       default.  Platforms running a copy of glibc with a recent-enough
 217       version will see calls from libstdc++ directly into the glibc already
 218       installed.  For other platforms, a copy of the libio subsection will
 219       be built and included in libstdc++.
 220    </p></div><div class="section"><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
 221       easily write one to perform your own forms of locking, to solve your
 222       "interesting" problems.
 223    </p></div></div><div class="section"><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
 224       multithreaded applications which use Standard C++ containers.
 225       All information in this section is current as of the gcc 3.0
 226       release and all later point releases.  Although earlier gcc
 227       releases had a different approach to threading configuration and
 228       proper compilation, the basic code design rules presented here
 229       were similar.  For information on all other aspects of
 230       multithreading as it relates to libstdc++, including details on
 231       the proper compilation of threaded code (and compatibility between
 232       threaded and non-threaded code), see Chapter 17.
 233    </p><p>Two excellent pages to read when working with the Standard C++
 234       containers and threads are
 235       <a class="link" href="http://www.sgi.com/tech/stl/thread_safety.html" target="_top">SGI's
 236       http://www.sgi.com/tech/stl/thread_safety.html</a> and
 237       <a class="link" href="http://www.sgi.com/tech/stl/Allocators.html" target="_top">SGI's
 238       http://www.sgi.com/tech/stl/Allocators.html</a>.
 239    </p><p><span class="emphasis"><em>However, please ignore all discussions about the user-level
 240       configuration of the lock implementation inside the STL
 241       container-memory allocator on those pages.  For the sake of this
 242       discussion, libstdc++ configures the SGI STL implementation,
 243       not you.  This is quite different from how gcc pre-3.0 worked.
 244       In particular, past advice was for people using g++ to
 245       explicitly define _PTHREADS or other macros or port-specific
 246       compilation options on the command line to get a thread-safe
 247       STL.  This is no longer required for any port and should no
 248       longer be done unless you really know what you are doing and
 249       assume all responsibility.</em></span>
 250    </p><p>Since the container implementation of libstdc++ uses the SGI
 251       code, we use the same definition of thread safety as SGI when
 252       discussing design.  A key point that beginners may miss is the
 253       fourth major paragraph of the first page mentioned above
 254       (<span class="emphasis"><em>For most clients...</em></span>), which points out that
 255       locking must nearly always be done outside the container, by
 256       client code (that'd be you, not us).  There is a notable
 257       exceptions to this rule.  Allocators called while a container or
 258       element is constructed uses an internal lock obtained and
 259       released solely within libstdc++ code (in fact, this is the
 260       reason STL requires any knowledge of the thread configuration).
 261    </p><p>For implementing a container which does its own locking, it is
 262       trivial to provide a wrapper class which obtains the lock (as
 263       SGI suggests), performs the container operation, and then
 264       releases the lock.  This could be templatized <span class="emphasis"><em>to a certain
 265       extent</em></span>, on the underlying container and/or a locking
 266       mechanism.  Trying to provide a catch-all general template
 267       solution would probably be more trouble than it's worth.
 268    </p><p>The library implementation may be configured to use the
 269       high-speed caching memory allocator, which complicates thread
 270       safety issues. For all details about how to globally override
 271       this at application run-time
 272       see <a class="link" href="using_macros.html" title="Macros">here</a>. Also
 273       useful are details
 274       on <a class="link" href="memory.html#std.util.memory.allocator" title="Allocators">allocator</a>
 275       options and capabilities.
 276    </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="using_dynamic_or_shared.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">Linking </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Exceptions</td></tr></table></div></body></html>