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">
3 <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 V1.73.2" /><meta name="keywords" content=" ISO C++ , library " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="using.html" title="Chapter 3. Using" /><link rel="prev" href="bk01pt01ch03s04.html" title="Macros" /><link rel="next" href="bk01pt01ch03s06.html" title="Exception Safety" /></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="bk01pt01ch03s04.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt01ch03s06.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><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
4 of multithreaded applications which use the Standard C++
5 library. This information is GCC-specific since the C++
6 standard does not address matters of multithreaded applications.
7 </p><div class="sect2" lang="en" xml:lang="en"><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
8 only supported when libstdc++ and all user code was built with
9 compilers which report (via <code class="code"> gcc/g++ -v </code>) the same thread
10 model and that model is not <span class="emphasis"><em>single</em></span>. As long as your
11 final application is actually single-threaded, then it should be
12 safe to mix user code built with a thread model of
13 <span class="emphasis"><em>single</em></span> with a libstdc++ and other C++ libraries built
14 with another thread model useful on the platform. Other mixes
15 may or may not work but are not considered supported. (Thus, if
16 you distribute a shared C++ library in binary form only, it may
17 be best to compile it with a GCC configured with
18 --enable-threads for maximal interchangeability and usefulness
19 with a user population that may have built GCC with either
20 --enable-threads or --disable-threads.)
21 </p><p>When you link a multithreaded application, you will probably
22 need to add a library or flag to g++. This is a very
23 non-standardized area of GCC across ports. Some ports support a
24 special flag (the spelling isn't even standardized yet) to add
25 all required macros to a compilation (if any such flags are
26 required then you must provide the flag for all compilations not
27 just linking) and link-library additions and/or replacements at
28 link time. The documentation is weak. Here is a quick summary
29 to display how ad hoc this is: On Solaris, both -pthreads and
30 -threads (with subtly different meanings) are honored. On OSF,
31 -pthread and -threads (with subtly different meanings) are
32 honored. On Linux/i386, -pthread is honored. On FreeBSD,
33 -pthread is honored. Some other ports use other switches.
34 AFAIK, none of this is properly documented anywhere other than
35 in ``gcc -dumpspecs'' (look at lib and cpp entries).
36 </p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.concurrency.thread_safety"></a>Thread Safety</h3></div></div></div><p>
37 We currently use the <a class="ulink" href="http://www.sgi.com/tech/stl/thread_safety.html" target="_top">SGI STL</a> definition of thread safety.
38 </p><p>The library strives to be thread-safe when all of the following
40 </p><div class="itemizedlist"><ul type="disc"><li><p>The system's libc is itself thread-safe,
42 The compiler in use reports a thread model other than
43 'single'. This can be tested via output from <code class="code">gcc
44 -v</code>. Multi-thread capable versions of gcc output
46 </p><pre class="programlisting">
51 gcc version 4.1.2 20070925 (Red Hat 4.1.2-33)
52 </pre><p>Look for "Thread model" lines that aren't equal to "single."</p></li><li><p>
53 Requisite command-line flags are used for atomic operations
54 and threading. Examples of this include <code class="code">-pthread</code>
55 and <code class="code">-march=native</code>, although specifics vary
56 depending on the host environment. See <a class="ulink" href="http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html" target="_top">Machine
57 Dependent Options</a>.
59 An implementation of atomicity.h functions
60 exists for the architecture in question. See the internals documentation for more <a class="ulink" href="../ext/concurrence.html" target="_top">details</a>.
61 </p></li></ul></div><p>The user-code must guard against concurrent method calls which may
62 access any particular library object's state. Typically, the
63 application programmer may infer what object locks must be held
64 based on the objects referenced in a method call. Without getting
65 into great detail, here is an example which requires user-level
67 </p><pre class="programlisting">
68 library_class_a shared_object_a;
71 library_class_b *object_b = new library_class_b;
72 shared_object_a.add_b (object_b); // must hold lock for shared_object_a
73 shared_object_a.mutate (); // must hold lock for shared_object_a
76 // 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
77 another thread, here is an example that should not require any
79 </p><pre class="programlisting">
81 library_class_a object_a;
82 library_class_b *object_b = new library_class_b;
83 object_a.add_b (object_b);
85 } </pre><p>All library objects are safe to use in a multithreaded program as
86 long as each thread carefully locks out access by any other
87 thread while it uses any object visible to another thread, i.e.,
88 treat library objects like any other shared resource. In general,
89 this requirement includes both read and write access to objects;
90 unless otherwise documented as safe, do not assume that two threads
91 may access a shared standard library object at the same time.
92 </p><p>See chapters <a class="ulink" href="../17_intro/howto.html#3" target="_top">17</a> (library
93 introduction), <a class="ulink" href="../23_containers/howto.html#3" target="_top">23</a>
94 (containers), and <a class="ulink" href="../27_io/howto.html#9" target="_top">27</a> (I/O) for
96 </p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.concurrency.atomics"></a>Atomics</h3></div></div></div><p>
97 </p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.concurrency.io"></a>IO</h3></div></div></div><p>I'll assume that you have already read the
98 <a class="ulink" href="../17_intro/howto.html#3" target="_top">general notes on library threads</a>,
100 <a class="ulink" href="../23_containers/howto.html#3" target="_top">notes on threaded container
101 access</a> (you might not think of an I/O stream as a container, but
102 the points made there also hold here). If you have not read them,
104 </p><p>This gets a bit tricky. Please read carefully, and bear with me.
105 </p><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="concurrency.io.structure"></a>Structure</h4></div></div></div><p>A wrapper
106 type called <code class="code">__basic_file</code> provides our abstraction layer
107 for the <code class="code">std::filebuf</code> classes. Nearly all decisions dealing
108 with actual input and output must be made in <code class="code">__basic_file</code>.
109 </p><p>A generic locking mechanism is somewhat in place at the filebuf layer,
110 but is not used in the current code. Providing locking at any higher
111 level is akin to providing locking within containers, and is not done
112 for the same reasons (see the links above).
113 </p></div><div class="sect3" lang="en" xml:lang="en"><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
114 the C stdio layer (again, see the link under Structure). We do no
115 locking ourselves, but simply pass through to calls to <code class="code">fopen</code>,
116 <code class="code">fwrite</code>, and so forth.
117 </p><p>So, for 3.0, the question of "is multithreading safe for I/O"
118 must be answered with, "is your platform's C library threadsafe
119 for I/O?" Some are by default, some are not; many offer multiple
120 implementations of the C library with varying tradeoffs of threadsafety
121 and efficiency. You, the programmer, are always required to take care
122 with multiple threads.
123 </p><p>(As an example, the POSIX standard requires that C stdio FILE*
124 operations are atomic. POSIX-conforming C libraries (e.g, on Solaris
125 and GNU/Linux) have an internal mutex to serialize operations on
126 FILE*s. However, you still need to not do stupid things like calling
127 <code class="code">fclose(fs)</code> in one thread followed by an access of
128 <code class="code">fs</code> in another.)
129 </p><p>So, if your platform's C library is threadsafe, then your
130 <code class="code">fstream</code> I/O operations will be threadsafe at the lowest
131 level. For higher-level operations, such as manipulating the data
132 contained in the stream formatting classes (e.g., setting up callbacks
133 inside an <code class="code">std::ofstream</code>), you need to guard such accesses
134 like any other critical shared resource.
135 </p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="concurrency.io.future"></a>Future</h4></div></div></div><p> A
136 second choice may be available for I/O implementations: libio. This is
137 disabled by default, and in fact will not currently work due to other
138 issues. It will be revisited, however.
139 </p><p>The libio code is a subset of the guts of the GNU libc (glibc) I/O
140 implementation. When libio is in use, the <code class="code">__basic_file</code>
141 type is basically derived from FILE. (The real situation is more
142 complex than that... it's derived from an internal type used to
143 implement FILE. See libio/libioP.h to see scary things done with
144 vtbls.) The result is that there is no "layer" of C stdio
145 to go through; the filebuf makes calls directly into the same
146 functions used to implement <code class="code">fread</code>, <code class="code">fwrite</code>,
147 and so forth, using internal data structures. (And when I say
148 "makes calls directly," I mean the function is literally
149 replaced by a jump into an internal function. Fast but frightening.
151 </p><p>Also, the libio internal locks are used. This requires pulling in
152 large chunks of glibc, such as a pthreads implementation, and is one
153 of the issues preventing widespread use of libio as the libstdc++
154 cstdio implementation.
155 </p><p>But we plan to make this work, at least as an option if not a future
156 default. Platforms running a copy of glibc with a recent-enough
157 version will see calls from libstdc++ directly into the glibc already
158 installed. For other platforms, a copy of the libio subsection will
159 be built and included in libstdc++.
160 </p></div><div class="sect3" lang="en" xml:lang="en"><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
161 easily write one to perform your own forms of locking, to solve your
162 "interesting" problems.
163 </p></div></div><div class="sect2" lang="en" xml:lang="en"><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
164 multithreaded applications which use Standard C++ containers.
165 All information in this section is current as of the gcc 3.0
166 release and all later point releases. Although earlier gcc
167 releases had a different approach to threading configuration and
168 proper compilation, the basic code design rules presented here
169 were similar. For information on all other aspects of
170 multithreading as it relates to libstdc++, including details on
171 the proper compilation of threaded code (and compatibility between
172 threaded and non-threaded code), see Chapter 17.
173 </p><p>Two excellent pages to read when working with the Standard C++
174 containers and threads are
175 <a class="ulink" href="http://www.sgi.com/tech/stl/thread_safety.html" target="_top">SGI's
176 http://www.sgi.com/tech/stl/thread_safety.html</a> and
177 <a class="ulink" href="http://www.sgi.com/tech/stl/Allocators.html" target="_top">SGI's
178 http://www.sgi.com/tech/stl/Allocators.html</a>.
179 </p><p><span class="emphasis"><em>However, please ignore all discussions about the user-level
180 configuration of the lock implementation inside the STL
181 container-memory allocator on those pages. For the sake of this
182 discussion, libstdc++ configures the SGI STL implementation,
183 not you. This is quite different from how gcc pre-3.0 worked.
184 In particular, past advice was for people using g++ to
185 explicitly define _PTHREADS or other macros or port-specific
186 compilation options on the command line to get a thread-safe
187 STL. This is no longer required for any port and should no
188 longer be done unless you really know what you are doing and
189 assume all responsibility.</em></span>
190 </p><p>Since the container implementation of libstdc++ uses the SGI
191 code, we use the same definition of thread safety as SGI when
192 discussing design. A key point that beginners may miss is the
193 fourth major paragraph of the first page mentioned above
194 ("For most clients,"...), which points out that
195 locking must nearly always be done outside the container, by
196 client code (that'd be you, not us). There is a notable
197 exceptions to this rule. Allocators called while a container or
198 element is constructed uses an internal lock obtained and
199 released solely within libstdc++ code (in fact, this is the
200 reason STL requires any knowledge of the thread configuration).
201 </p><p>For implementing a container which does its own locking, it is
202 trivial to provide a wrapper class which obtains the lock (as
203 SGI suggests), performs the container operation, and then
204 releases the lock. This could be templatized <span class="emphasis"><em>to a certain
205 extent</em></span>, on the underlying container and/or a locking
206 mechanism. Trying to provide a catch-all general template
207 solution would probably be more trouble than it's worth.
208 </p><p>The STL implementation is currently configured to use the
209 high-speed caching memory allocator. Some people like to
210 test and/or normally run threaded programs with a different
211 default. For all details about how to globally override this
212 at application run-time see <a class="ulink" href="../ext/howto.html#3" target="_top">here</a>.
213 </p><p>There is a better way (not standardized yet): It is possible to
214 force the malloc-based allocator on a per-case-basis for some
215 application code. The library team generally believes that this
216 is a better way to tune an application for high-speed using this
217 implementation of the STL. There is
218 <a class="ulink" href="../ext/howto.html#3" target="_top">more information on allocators here</a>.
219 </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt01ch03s04.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="bk01pt01ch03s06.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Macros </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Exception Safety</td></tr></table></div></body></html>
projects / l4.git / blob