xref: /netbsd-src/external/gpl3/gcc.old/dist/libstdc++-v3/doc/html/manual/using_concurrency.html (revision 8feb0f0b7eaff0608f8350bbfa3098827b4bb91b)
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 Stylesheets Vsnapshot" /><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>
36In the terms of the 2011 C++ standard a thread-safe program is one which
37does not perform any conflicting non-atomic operations on memory locations
38and so does not contain any data races.
39The standard places requirements on the library to ensure that no data
40races are caused by the library itself or by programs which use the
41library correctly (as described below).
42The C++11 memory model and library requirements are a more formal version
43of the <a class="link" href="https://web.archive.org/web/20171225062613/http://www.sgi.com/tech/stl/thread_safety.html" target="_top">SGI STL</a> definition of thread safety, which the library used
44prior 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
55Using built-in specs.
56...
57Thread model: posix
58gcc 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="https://www.hboehm.info/c++mm/" target="_top">Threads
161      and memory model for C++</a> pages, particularly the <a class="link" href="https://www.hboehm.info/c++mm/threadsintro.html" target="_top">introduction</a>
162      and <a class="link" href="https://www.hboehm.info/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
184       <code class="code">FILE*</code> operations are atomic.  POSIX-conforming C libraries
185       (e.g, on Solaris and GNU/Linux) have an internal mutex to serialize
186       operations on <code class="code">FILE*</code>s.
187       However, you still need to not do stupid things like calling
188       <code class="code">fclose(fs)</code> in one thread followed by an access of
189       <code class="code">fs</code> in another.)
190   </p><p>So, if your platform's C library is threadsafe, then your
191      <code class="code">fstream</code> I/O operations will be threadsafe at the lowest
192      level.  For higher-level operations, such as manipulating the data
193      contained in the stream formatting classes (e.g., setting up callbacks
194      inside an <code class="code">std::ofstream</code>), you need to guard such accesses
195      like any other critical shared resource.
196   </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
197      second choice may be available for I/O implementations:  libio.  This is
198      disabled by default, and in fact will not currently work due to other
199      issues.  It will be revisited, however.
200   </p><p>The libio code is a subset of the guts of the GNU libc (glibc) I/O
201      implementation.  When libio is in use, the <code class="code">__basic_file</code>
202      type is basically derived from FILE.  (The real situation is more
203      complex than that... it's derived from an internal type used to
204      implement FILE.  See libio/libioP.h to see scary things done with
205      vtbls.)  The result is that there is no "layer" of C stdio
206      to go through; the filebuf makes calls directly into the same
207      functions used to implement <code class="code">fread</code>, <code class="code">fwrite</code>,
208      and so forth, using internal data structures.  (And when I say
209      "makes calls directly," I mean the function is literally
210      replaced by a jump into an internal function.  Fast but frightening.
211      *grin*)
212   </p><p>Also, the libio internal locks are used.  This requires pulling in
213      large chunks of glibc, such as a pthreads implementation, and is one
214      of the issues preventing widespread use of libio as the libstdc++
215      cstdio implementation.
216   </p><p>But we plan to make this work, at least as an option if not a future
217      default.  Platforms running a copy of glibc with a recent-enough
218      version will see calls from libstdc++ directly into the glibc already
219      installed.  For other platforms, a copy of the libio subsection will
220      be built and included in libstdc++.
221   </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
222      easily write one to perform your own forms of locking, to solve your
223      "interesting" problems.
224   </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
225      multithreaded applications which use Standard C++ containers.
226      All information in this section is current as of the gcc 3.0
227      release and all later point releases.  Although earlier gcc
228      releases had a different approach to threading configuration and
229      proper compilation, the basic code design rules presented here
230      were similar.  For information on all other aspects of
231      multithreading as it relates to libstdc++, including details on
232      the proper compilation of threaded code (and compatibility between
233      threaded and non-threaded code), see Chapter 17.
234   </p><p>Two excellent pages to read when working with the Standard C++
235      containers and threads are
236      <a class="link" href="https://web.archive.org/web/20171225062613/http://www.sgi.com/tech/stl/thread_safety.html" target="_top">SGI's
237      https://web.archive.org/web/20171225062613/http://www.sgi.com/tech/stl/thread_safety.html</a> and
238      <a class="link" href="https://web.archive.org/web/20171225062613/http://www.sgi.com/tech/stl/Allocators.html" target="_top">SGI's
239      https://web.archive.org/web/20171225062613/http://www.sgi.com/tech/stl/Allocators.html</a>.
240   </p><p><span class="emphasis"><em>However, please ignore all discussions about the user-level
241      configuration of the lock implementation inside the STL
242      container-memory allocator on those pages.  For the sake of this
243      discussion, libstdc++ configures the SGI STL implementation,
244      not you.  This is quite different from how gcc pre-3.0 worked.
245      In particular, past advice was for people using g++ to
246      explicitly define _PTHREADS or other macros or port-specific
247      compilation options on the command line to get a thread-safe
248      STL.  This is no longer required for any port and should no
249      longer be done unless you really know what you are doing and
250      assume all responsibility.</em></span>
251   </p><p>Since the container implementation of libstdc++ uses the SGI
252      code, we use the same definition of thread safety as SGI when
253      discussing design.  A key point that beginners may miss is the
254      fourth major paragraph of the first page mentioned above
255      (<span class="emphasis"><em>For most clients...</em></span>), which points out that
256      locking must nearly always be done outside the container, by
257      client code (that'd be you, not us).  There is a notable
258      exceptions to this rule.  Allocators called while a container or
259      element is constructed uses an internal lock obtained and
260      released solely within libstdc++ code (in fact, this is the
261      reason STL requires any knowledge of the thread configuration).
262   </p><p>For implementing a container which does its own locking, it is
263      trivial to provide a wrapper class which obtains the lock (as
264      SGI suggests), performs the container operation, and then
265      releases the lock.  This could be templatized <span class="emphasis"><em>to a certain
266      extent</em></span>, on the underlying container and/or a locking
267      mechanism.  Trying to provide a catch-all general template
268      solution would probably be more trouble than it's worth.
269   </p><p>The library implementation may be configured to use the
270      high-speed caching memory allocator, which complicates thread
271      safety issues. For all details about how to globally override
272      this at application run-time
273      see <a class="link" href="using_macros.html" title="Macros">here</a>. Also
274      useful are details
275      on <a class="link" href="memory.html#std.util.memory.allocator" title="Allocators">allocator</a>
276      options and capabilities.
277   </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>