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

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