1 <chapter xmlns=
"http://docbook.org/ns/docbook" version=
"5.0"
2 xml:
id=
"manual.ext.concurrency" xreflabel=
"Concurrency Extensions">
3 <?dbhtml filename=
"ext_concurrency.html"?>
5 <info><title>Concurrency
</title>
18 <section xml:
id=
"manual.ext.concurrency.design" xreflabel=
"Design"><info><title>Design
</title></info>
21 <section xml:
id=
"manual.ext.concurrency.design.threads" xreflabel=
"Threads API"><info><title>Interface to Locks and Mutexes
</title></info>
24 <para>The file
<ext/concurrence.h
> contains all the higher-level
25 constructs for playing with threads. In contrast to the atomics layer,
26 the concurrence layer consists largely of types. All types are defined within
<code>namespace __gnu_cxx
</code>.
30 These types can be used in a portable manner, regardless of the
31 specific environment. They are carefully designed to provide optimum
32 efficiency and speed, abstracting out underlying thread calls and
33 accesses when compiling for single-threaded situations (even on hosts
34 that support multiple threads.)
37 <para>The enumerated type
<code>_Lock_policy
</code> details the set of
39 policies:
<code>_S_single
</code>,
<code>_S_mutex
</code>,
40 and
<code>_S_atomic
</code>.
44 <listitem><para><code>_S_single
</code></para>
45 <para>Indicates single-threaded code that does not need locking.
49 <listitem><para><code>_S_mutex
</code></para>
50 <para>Indicates multi-threaded code using thread-layer abstractions.
53 <listitem><para><code>_S_atomic
</code></para>
54 <para>Indicates multi-threaded code using atomic operations.
59 <para>The compile-time constant
<code>__default_lock_policy
</code> is set
60 to one of the three values above, depending on characteristics of the
61 host environment and the current compilation flags.
64 <para>Two more datatypes make up the rest of the
65 interface:
<code>__mutex
</code>, and
<code>__scoped_lock
</code>.
71 <para>The scoped lock idiom is well-discussed within the C++
72 community. This version takes a
<code>__mutex
</code> reference, and
73 locks it during construction of
<code>__scoped_locke
</code> and
74 unlocks it during destruction. This is an efficient way of locking
75 critical sections, while retaining exception-safety.
79 <section xml:
id=
"manual.ext.concurrency.design.atomics" xreflabel=
"Atomic API"><info><title>Interface to Atomic Functions
</title></info>
84 Two functions and one type form the base of atomic support.
88 <para>The type
<code>_Atomic_word
</code> is a signed integral type
89 supporting atomic operations.
93 The two functions functions are:
98 __exchange_and_add_dispatch(volatile _Atomic_word*, int);
101 __atomic_add_dispatch(volatile _Atomic_word*, int);
104 <para>Both of these functions are declared in the header file
105 <ext/atomicity.h
>, and are in
<code>namespace __gnu_cxx
</code>.
111 __exchange_and_add_dispatch
114 <para>Adds the second argument's value to the first argument. Returns the old value.
119 __atomic_add_dispatch
122 <para>Adds the second argument's value to the first argument. Has no return value.
128 These functions forward to one of several specialized helper
129 functions, depending on the circumstances. For instance,
134 __exchange_and_add_dispatch
139 Calls through to either of:
143 <listitem><para><code>__exchange_and_add
</code>
145 <para>Multi-thread version. Inlined if compiler-generated builtin atomics
146 can be used, otherwise resolved at link time to a non-builtin code
151 <listitem><para><code>__exchange_and_add_single
</code>
153 <para>Single threaded version. Inlined.
</para>
157 <para>However, only
<code>__exchange_and_add_dispatch
</code>
158 and
<code>__atomic_add_dispatch
</code> should be used. These functions
159 can be used in a portable manner, regardless of the specific
160 environment. They are carefully designed to provide optimum efficiency
161 and speed, abstracting out atomic accesses when they are not required
162 (even on hosts that support compiler intrinsics for atomic
167 In addition, there are two macros
172 _GLIBCXX_READ_MEM_BARRIER
177 _GLIBCXX_WRITE_MEM_BARRIER
182 Which expand to the appropriate write and read barrier required by the
183 host hardware and operating system.
190 <section xml:
id=
"manual.ext.concurrency.impl" xreflabel=
"Implementation"><info><title>Implementation
</title></info>
192 <section xml:
id=
"manual.ext.concurrency.impl.atomic_fallbacks" xreflabel=
"Atomic F"><info><title>Using Builtin Atomic Functions
</title></info>
195 <para>The functions for atomic operations described above are either
196 implemented via compiler intrinsics (if the underlying host is
197 capable) or by library fallbacks.
</para>
199 <para>Compiler intrinsics (builtins) are always preferred. However, as
200 the compiler builtins for atomics are not universally implemented,
201 using them directly is problematic, and can result in undefined
202 function calls. (An example of an undefined symbol from the use
203 of
<code>__sync_fetch_and_add
</code> on an unsupported host is a
204 missing reference to
<code>__sync_fetch_and_add_4
</code>.)
207 <para>In addition, on some hosts the compiler intrinsics are enabled
208 conditionally, via the
<code>-march
</code> command line flag. This makes
209 usage vary depending on the target hardware and the flags used during
217 Incomplete/inconsistent. This is only C++
11.
222 If builtins are possible for bool-sized integral types,
223 <code>ATOMIC_BOOL_LOCK_FREE
</code> will be defined.
224 If builtins are possible for int-sized integral types,
225 <code>ATOMIC_INT_LOCK_FREE
</code> will be defined.
229 <para>For the following hosts, intrinsics are enabled by default.
233 <listitem><para>alpha
</para></listitem>
234 <listitem><para>ia64
</para></listitem>
235 <listitem><para>powerpc
</para></listitem>
236 <listitem><para>s390
</para></listitem>
239 <para>For others, some form of
<code>-march
</code> may work. On
240 non-ancient x86 hardware,
<code>-march=native
</code> usually does the
243 <para> For hosts without compiler intrinsics, but with capable
244 hardware, hand-crafted assembly is selected. This is the case for the following hosts:
248 <listitem><para>cris
</para></listitem>
249 <listitem><para>hppa
</para></listitem>
250 <listitem><para>i386
</para></listitem>
251 <listitem><para>i486
</para></listitem>
252 <listitem><para>m48k
</para></listitem>
253 <listitem><para>mips
</para></listitem>
254 <listitem><para>sparc
</para></listitem>
257 <para>And for the rest, a simulated atomic lock via pthreads.
260 <para> Detailed information about compiler intrinsics for atomic operations can be found in the GCC
<link xmlns:
xlink=
"http://www.w3.org/1999/xlink" xlink:
href=
"http://gcc.gnu.org/onlinedocs/gcc/Atomic-Builtins.html"> documentation
</link>.
263 <para> More details on the library fallbacks from the porting
<link linkend=
"internals.thread_safety">section
</link>.
268 <section xml:
id=
"manual.ext.concurrency.impl.thread" xreflabel=
"Pthread"><info><title>Thread Abstraction
</title></info>
271 <para>A thin layer above IEEE
1003.1 (i.e. pthreads) is used to abstract
272 the thread interface for GCC. This layer is called
"gthread," and is
273 comprised of one header file that wraps the host's default thread layer with
274 a POSIX-like interface.
277 <para> The file
<gthr-default.h
> points to the deduced wrapper for
278 the current host. In libstdc++ implementation files,
279 <bits/gthr.h
> is used to select the proper gthreads file.
282 <para>Within libstdc++ sources, all calls to underlying thread functionality
283 use this layer. More detail as to the specific interface can be found in the source
<link xmlns:
xlink=
"http://www.w3.org/1999/xlink" xlink:
href=
"http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a00883_source.html">documentation
</link>.
286 <para>By design, the gthread layer is interoperable with the types,
287 functions, and usage found in the usual
<pthread.h
> file,
288 including
<code>pthread_t
</code>,
<code>pthread_once_t
</code>,
<code>pthread_create
</code>,
295 <section xml:
id=
"manual.ext.concurrency.use" xreflabel=
"Use"><info><title>Use
</title></info>
299 <para>Typical usage of the last two constructs is demonstrated as follows:
303 #include
<ext/concurrence.h
>
307 __gnu_cxx::__mutex safe_base_mutex;
308 } // anonymous namespace
315 __gnu_cxx::__scoped_lock sentry(safe_base_mutex);
316 for (int i =
0; i
< max; ++i)
318 _Safe_iterator_base* __old = __iter;
319 __iter = __iter-
<_M_next;
320 __old-
<_M_detach_single();
325 <para>In this sample code, an anonymous namespace is used to keep
326 the
<code>__mutex
</code> private to the compilation unit,
327 and
<code>__scoped_lock
</code> is used to guard access to the critical
328 section within the for loop, locking the mutex on creation and freeing
329 the mutex as control moves out of this block.
332 <para>Several exception classes are used to keep track of
333 concurrence-related errors. These classes
334 are:
<code>__concurrence_lock_error
</code>,
<code>__concurrence_unlock_error
</code>,
<code>__concurrence_wait_error
</code>,
335 and
<code>__concurrence_broadcast_error
</code>.