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"><atomic></code> 111 and lock/unlock operations on the standard mutex types in 112 <code class="filename"><mutex></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<int> 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>