136ac495dSmrg<?xml version="1.0" encoding="UTF-8" standalone="no"?> 236ac495dSmrg<!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 336ac495dSmrg of multithreaded applications which use the Standard C++ 436ac495dSmrg library. This information is GCC-specific since the C++ 536ac495dSmrg standard does not address matters of multithreaded applications. 636ac495dSmrg </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 736ac495dSmrg only supported when libstdc++ and all user code was built with 836ac495dSmrg compilers which report (via <code class="code"> gcc/g++ -v </code>) the same thread 936ac495dSmrg model and that model is not <span class="emphasis"><em>single</em></span>. As long as your 1036ac495dSmrg final application is actually single-threaded, then it should be 1136ac495dSmrg safe to mix user code built with a thread model of 1236ac495dSmrg <span class="emphasis"><em>single</em></span> with a libstdc++ and other C++ libraries built 1336ac495dSmrg with another thread model useful on the platform. Other mixes 1436ac495dSmrg may or may not work but are not considered supported. (Thus, if 1536ac495dSmrg you distribute a shared C++ library in binary form only, it may 1636ac495dSmrg be best to compile it with a GCC configured with 1736ac495dSmrg --enable-threads for maximal interchangeability and usefulness 1836ac495dSmrg with a user population that may have built GCC with either 1936ac495dSmrg --enable-threads or --disable-threads.) 2036ac495dSmrg </p><p>When you link a multithreaded application, you will probably 2136ac495dSmrg need to add a library or flag to g++. This is a very 2236ac495dSmrg non-standardized area of GCC across ports. Some ports support a 2336ac495dSmrg special flag (the spelling isn't even standardized yet) to add 2436ac495dSmrg all required macros to a compilation (if any such flags are 2536ac495dSmrg required then you must provide the flag for all compilations not 2636ac495dSmrg just linking) and link-library additions and/or replacements at 2736ac495dSmrg link time. The documentation is weak. On several targets (including 2836ac495dSmrg GNU/Linux, Solaris and various BSDs) -pthread is honored. 2936ac495dSmrg Some other ports use other switches. 3036ac495dSmrg This is not well documented anywhere other than 3136ac495dSmrg in "gcc -dumpspecs" (look at the 'lib' and 'cpp' entries). 3236ac495dSmrg </p><p> 3336ac495dSmrg Some uses of <code class="classname">std::atomic</code> also require linking 3436ac495dSmrg to <code class="filename">libatomic</code>. 3536ac495dSmrg </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> 3636ac495dSmrgIn the terms of the 2011 C++ standard a thread-safe program is one which 3736ac495dSmrgdoes not perform any conflicting non-atomic operations on memory locations 3836ac495dSmrgand so does not contain any data races. 3936ac495dSmrgThe standard places requirements on the library to ensure that no data 4036ac495dSmrgraces are caused by the library itself or by programs which use the 4136ac495dSmrglibrary correctly (as described below). 4236ac495dSmrgThe C++11 memory model and library requirements are a more formal version 43a2dc1f3fSmrgof 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 4436ac495dSmrgprior to the 2011 standard. 4536ac495dSmrg</p><p>The library strives to be thread-safe when all of the following 4636ac495dSmrg conditions are met: 4736ac495dSmrg </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>The system's libc is itself thread-safe, 4836ac495dSmrg </p></li><li class="listitem"><p> 4936ac495dSmrg The compiler in use reports a thread model other than 5036ac495dSmrg 'single'. This can be tested via output from <code class="code">gcc 5136ac495dSmrg -v</code>. Multi-thread capable versions of gcc output 5236ac495dSmrg something like this: 5336ac495dSmrg </p><pre class="programlisting"> 5436ac495dSmrg%gcc -v 5536ac495dSmrgUsing built-in specs. 5636ac495dSmrg... 5736ac495dSmrgThread model: posix 5836ac495dSmrggcc version 4.1.2 20070925 (Red Hat 4.1.2-33) 5936ac495dSmrg</pre><p>Look for "Thread model" lines that aren't equal to "single."</p></li><li class="listitem"><p> 6036ac495dSmrg Requisite command-line flags are used for atomic operations 6136ac495dSmrg and threading. Examples of this include <code class="code">-pthread</code> 6236ac495dSmrg and <code class="code">-march=native</code>, although specifics vary 6336ac495dSmrg depending on the host environment. See 6436ac495dSmrg <a class="link" href="using.html#manual.intro.using.flags" title="Command Options">Command Options</a> and 6536ac495dSmrg <a class="link" href="http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html" target="_top">Machine 6636ac495dSmrg Dependent Options</a>. 6736ac495dSmrg </p></li><li class="listitem"><p> 6836ac495dSmrg An implementation of the 6936ac495dSmrg <code class="filename">atomicity.h</code> functions 7036ac495dSmrg exists for the architecture in question. See the 7136ac495dSmrg <a class="link" href="internals.html#internals.thread_safety" title="Thread Safety">internals 7236ac495dSmrg documentation</a> for more details. 7336ac495dSmrg </p></li></ul></div><p>The user code must guard against concurrent function calls which 7436ac495dSmrg access any particular library object's state when one or more of 7536ac495dSmrg those accesses modifies the state. An object will be modified by 7636ac495dSmrg invoking a non-const member function on it or passing it as a 7736ac495dSmrg non-const argument to a library function. An object will not be 7836ac495dSmrg modified by invoking a const member function on it or passing it to 7936ac495dSmrg a function as a pointer- or reference-to-const. 8036ac495dSmrg Typically, the application 8136ac495dSmrg programmer may infer what object locks must be held based on the 8236ac495dSmrg objects referenced in a function call and whether the objects are 8336ac495dSmrg accessed as const or non-const. Without getting 8436ac495dSmrg into great detail, here is an example which requires user-level 8536ac495dSmrg locks: 8636ac495dSmrg </p><pre class="programlisting"> 8736ac495dSmrg library_class_a shared_object_a; 8836ac495dSmrg 8936ac495dSmrg void thread_main () { 9036ac495dSmrg library_class_b *object_b = new library_class_b; 9136ac495dSmrg shared_object_a.add_b (object_b); // must hold lock for shared_object_a 9236ac495dSmrg shared_object_a.mutate (); // must hold lock for shared_object_a 9336ac495dSmrg } 9436ac495dSmrg 9536ac495dSmrg // 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 9636ac495dSmrg another thread, here is an example that does not require any 9736ac495dSmrg user-level locks: 9836ac495dSmrg </p><pre class="programlisting"> 9936ac495dSmrg void thread_main () { 10036ac495dSmrg library_class_a object_a; 10136ac495dSmrg library_class_b *object_b = new library_class_b; 10236ac495dSmrg object_a.add_b (object_b); 10336ac495dSmrg object_a.mutate (); 10436ac495dSmrg } </pre><p>All library types are safe to use in a multithreaded program 10536ac495dSmrg if objects are not shared between threads or as 10636ac495dSmrg long each thread carefully locks out access by any other 10736ac495dSmrg thread while it modifies any object visible to another thread. 10836ac495dSmrg Unless otherwise documented, the only exceptions to these rules 10936ac495dSmrg are atomic operations on the types in 11036ac495dSmrg <code class="filename"><atomic></code> 11136ac495dSmrg and lock/unlock operations on the standard mutex types in 11236ac495dSmrg <code class="filename"><mutex></code>. These 11336ac495dSmrg atomic operations allow concurrent accesses to the same object 11436ac495dSmrg without introducing data races. 11536ac495dSmrg </p><p>The following member functions of standard containers can be 11636ac495dSmrg considered to be const for the purposes of avoiding data races: 11736ac495dSmrg <code class="code">begin</code>, <code class="code">end</code>, <code class="code">rbegin</code>, <code class="code">rend</code>, 11836ac495dSmrg <code class="code">front</code>, <code class="code">back</code>, <code class="code">data</code>, 11936ac495dSmrg <code class="code">find</code>, <code class="code">lower_bound</code>, <code class="code">upper_bound</code>, 12036ac495dSmrg <code class="code">equal_range</code>, <code class="code">at</code> 12136ac495dSmrg and, except in associative or unordered associative containers, 12236ac495dSmrg <code class="code">operator[]</code>. In other words, although they are non-const 12336ac495dSmrg so that they can return mutable iterators, those member functions 12436ac495dSmrg will not modify the container. 12536ac495dSmrg Accessing an iterator might cause a non-modifying access to 12636ac495dSmrg the container the iterator refers to (for example incrementing a 12736ac495dSmrg list iterator must access the pointers between nodes, which are part 12836ac495dSmrg of the container and so conflict with other accesses to the container). 12936ac495dSmrg </p><p>Programs which follow the rules above will not encounter data 13036ac495dSmrg races in library code, even when using library types which share 13136ac495dSmrg state between distinct objects. In the example below the 13236ac495dSmrg <code class="code">shared_ptr</code> objects share a reference count, but 13336ac495dSmrg because the code does not perform any non-const operations on the 13436ac495dSmrg globally-visible object, the library ensures that the reference 13536ac495dSmrg count updates are atomic and do not introduce data races: 13636ac495dSmrg </p><pre class="programlisting"> 13736ac495dSmrg std::shared_ptr<int> global_sp; 13836ac495dSmrg 13936ac495dSmrg void thread_main() { 14036ac495dSmrg auto local_sp = global_sp; // OK, copy constructor's parameter is reference-to-const 14136ac495dSmrg 14236ac495dSmrg int i = *global_sp; // OK, operator* is const 14336ac495dSmrg int j = *local_sp; // OK, does not operate on global_sp 14436ac495dSmrg 14536ac495dSmrg // *global_sp = 2; // NOT OK, modifies int visible to other threads 14636ac495dSmrg // *local_sp = 2; // NOT OK, modifies int visible to other threads 14736ac495dSmrg 14836ac495dSmrg // global_sp.reset(); // NOT OK, reset is non-const 14936ac495dSmrg local_sp.reset(); // OK, does not operate on global_sp 15036ac495dSmrg } 15136ac495dSmrg 15236ac495dSmrg int main() { 15336ac495dSmrg global_sp.reset(new int(1)); 15436ac495dSmrg std::thread t1(thread_main); 15536ac495dSmrg std::thread t2(thread_main); 15636ac495dSmrg t1.join(); 15736ac495dSmrg t2.join(); 15836ac495dSmrg } 15936ac495dSmrg </pre><p>For further details of the C++11 memory model see Hans-J. Boehm's 16036ac495dSmrg <a class="link" href="https://www.hboehm.info/c++mm/" target="_top">Threads 161*8feb0f0bSmrg 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> 16236ac495dSmrg and <a class="link" href="https://www.hboehm.info/c++mm/user-faq.html" target="_top">FAQ</a>. 16336ac495dSmrg </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> 16436ac495dSmrg </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. 16536ac495dSmrg </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 16636ac495dSmrg type called <code class="code">__basic_file</code> provides our abstraction layer 16736ac495dSmrg for the <code class="code">std::filebuf</code> classes. Nearly all decisions dealing 16836ac495dSmrg with actual input and output must be made in <code class="code">__basic_file</code>. 16936ac495dSmrg </p><p>A generic locking mechanism is somewhat in place at the filebuf layer, 17036ac495dSmrg but is not used in the current code. Providing locking at any higher 17136ac495dSmrg level is akin to providing locking within containers, and is not done 17236ac495dSmrg for the same reasons (see the links above). 17336ac495dSmrg </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 17436ac495dSmrg the C stdio layer (again, see the link under Structure). We do no 17536ac495dSmrg locking ourselves, but simply pass through to calls to <code class="code">fopen</code>, 17636ac495dSmrg <code class="code">fwrite</code>, and so forth. 17736ac495dSmrg </p><p>So, for 3.0, the question of "is multithreading safe for I/O" 17836ac495dSmrg must be answered with, "is your platform's C library threadsafe 17936ac495dSmrg for I/O?" Some are by default, some are not; many offer multiple 18036ac495dSmrg implementations of the C library with varying tradeoffs of threadsafety 18136ac495dSmrg and efficiency. You, the programmer, are always required to take care 18236ac495dSmrg with multiple threads. 18336ac495dSmrg </p><p>(As an example, the POSIX standard requires that C stdio 18436ac495dSmrg <code class="code">FILE*</code> operations are atomic. POSIX-conforming C libraries 18536ac495dSmrg (e.g, on Solaris and GNU/Linux) have an internal mutex to serialize 18636ac495dSmrg operations on <code class="code">FILE*</code>s. 18736ac495dSmrg However, you still need to not do stupid things like calling 18836ac495dSmrg <code class="code">fclose(fs)</code> in one thread followed by an access of 18936ac495dSmrg <code class="code">fs</code> in another.) 19036ac495dSmrg </p><p>So, if your platform's C library is threadsafe, then your 19136ac495dSmrg <code class="code">fstream</code> I/O operations will be threadsafe at the lowest 19236ac495dSmrg level. For higher-level operations, such as manipulating the data 19336ac495dSmrg contained in the stream formatting classes (e.g., setting up callbacks 19436ac495dSmrg inside an <code class="code">std::ofstream</code>), you need to guard such accesses 19536ac495dSmrg like any other critical shared resource. 19636ac495dSmrg </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 19736ac495dSmrg second choice may be available for I/O implementations: libio. This is 19836ac495dSmrg disabled by default, and in fact will not currently work due to other 19936ac495dSmrg issues. It will be revisited, however. 20036ac495dSmrg </p><p>The libio code is a subset of the guts of the GNU libc (glibc) I/O 20136ac495dSmrg implementation. When libio is in use, the <code class="code">__basic_file</code> 20236ac495dSmrg type is basically derived from FILE. (The real situation is more 20336ac495dSmrg complex than that... it's derived from an internal type used to 20436ac495dSmrg implement FILE. See libio/libioP.h to see scary things done with 20536ac495dSmrg vtbls.) The result is that there is no "layer" of C stdio 20636ac495dSmrg to go through; the filebuf makes calls directly into the same 20736ac495dSmrg functions used to implement <code class="code">fread</code>, <code class="code">fwrite</code>, 20836ac495dSmrg and so forth, using internal data structures. (And when I say 20936ac495dSmrg "makes calls directly," I mean the function is literally 21036ac495dSmrg replaced by a jump into an internal function. Fast but frightening. 21136ac495dSmrg *grin*) 21236ac495dSmrg </p><p>Also, the libio internal locks are used. This requires pulling in 21336ac495dSmrg large chunks of glibc, such as a pthreads implementation, and is one 21436ac495dSmrg of the issues preventing widespread use of libio as the libstdc++ 21536ac495dSmrg cstdio implementation. 21636ac495dSmrg </p><p>But we plan to make this work, at least as an option if not a future 21736ac495dSmrg default. Platforms running a copy of glibc with a recent-enough 21836ac495dSmrg version will see calls from libstdc++ directly into the glibc already 21936ac495dSmrg installed. For other platforms, a copy of the libio subsection will 22036ac495dSmrg be built and included in libstdc++. 22136ac495dSmrg </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 22236ac495dSmrg easily write one to perform your own forms of locking, to solve your 22336ac495dSmrg "interesting" problems. 22436ac495dSmrg </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 22536ac495dSmrg multithreaded applications which use Standard C++ containers. 22636ac495dSmrg All information in this section is current as of the gcc 3.0 22736ac495dSmrg release and all later point releases. Although earlier gcc 22836ac495dSmrg releases had a different approach to threading configuration and 22936ac495dSmrg proper compilation, the basic code design rules presented here 23036ac495dSmrg were similar. For information on all other aspects of 23136ac495dSmrg multithreading as it relates to libstdc++, including details on 23236ac495dSmrg the proper compilation of threaded code (and compatibility between 23336ac495dSmrg threaded and non-threaded code), see Chapter 17. 23436ac495dSmrg </p><p>Two excellent pages to read when working with the Standard C++ 23536ac495dSmrg containers and threads are 236a2dc1f3fSmrg <a class="link" href="https://web.archive.org/web/20171225062613/http://www.sgi.com/tech/stl/thread_safety.html" target="_top">SGI's 237a2dc1f3fSmrg https://web.archive.org/web/20171225062613/http://www.sgi.com/tech/stl/thread_safety.html</a> and 238a2dc1f3fSmrg <a class="link" href="https://web.archive.org/web/20171225062613/http://www.sgi.com/tech/stl/Allocators.html" target="_top">SGI's 239a2dc1f3fSmrg https://web.archive.org/web/20171225062613/http://www.sgi.com/tech/stl/Allocators.html</a>. 24036ac495dSmrg </p><p><span class="emphasis"><em>However, please ignore all discussions about the user-level 24136ac495dSmrg configuration of the lock implementation inside the STL 24236ac495dSmrg container-memory allocator on those pages. For the sake of this 24336ac495dSmrg discussion, libstdc++ configures the SGI STL implementation, 24436ac495dSmrg not you. This is quite different from how gcc pre-3.0 worked. 24536ac495dSmrg In particular, past advice was for people using g++ to 24636ac495dSmrg explicitly define _PTHREADS or other macros or port-specific 24736ac495dSmrg compilation options on the command line to get a thread-safe 24836ac495dSmrg STL. This is no longer required for any port and should no 24936ac495dSmrg longer be done unless you really know what you are doing and 25036ac495dSmrg assume all responsibility.</em></span> 25136ac495dSmrg </p><p>Since the container implementation of libstdc++ uses the SGI 25236ac495dSmrg code, we use the same definition of thread safety as SGI when 25336ac495dSmrg discussing design. A key point that beginners may miss is the 25436ac495dSmrg fourth major paragraph of the first page mentioned above 25536ac495dSmrg (<span class="emphasis"><em>For most clients...</em></span>), which points out that 25636ac495dSmrg locking must nearly always be done outside the container, by 25736ac495dSmrg client code (that'd be you, not us). There is a notable 25836ac495dSmrg exceptions to this rule. Allocators called while a container or 25936ac495dSmrg element is constructed uses an internal lock obtained and 26036ac495dSmrg released solely within libstdc++ code (in fact, this is the 26136ac495dSmrg reason STL requires any knowledge of the thread configuration). 26236ac495dSmrg </p><p>For implementing a container which does its own locking, it is 26336ac495dSmrg trivial to provide a wrapper class which obtains the lock (as 26436ac495dSmrg SGI suggests), performs the container operation, and then 26536ac495dSmrg releases the lock. This could be templatized <span class="emphasis"><em>to a certain 26636ac495dSmrg extent</em></span>, on the underlying container and/or a locking 26736ac495dSmrg mechanism. Trying to provide a catch-all general template 26836ac495dSmrg solution would probably be more trouble than it's worth. 26936ac495dSmrg </p><p>The library implementation may be configured to use the 27036ac495dSmrg high-speed caching memory allocator, which complicates thread 27136ac495dSmrg safety issues. For all details about how to globally override 27236ac495dSmrg this at application run-time 27336ac495dSmrg see <a class="link" href="using_macros.html" title="Macros">here</a>. Also 27436ac495dSmrg useful are details 27536ac495dSmrg on <a class="link" href="memory.html#std.util.memory.allocator" title="Allocators">allocator</a> 27636ac495dSmrg options and capabilities. 27736ac495dSmrg </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>