libstdc++-v3/doc/html/ext/concurrence.html

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html
   3           PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   4           "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   5
   6 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   7 <head>
   8    <meta name="AUTHOR" content="bkoz@gcc.gnu.org (Benjamin Kosnik)" />
   9    <meta name="KEYWORDS" content="C++, libstdc++, MT, thread, pthread, mutex, loc, atomic" />
  10    <meta name="DESCRIPTION" content="Concurrency Support" />
  11    <meta name="GENERATOR" content="emacs and ten fingers" />
  12    <title>Concurrency Support</title>
  13 <link rel="StyleSheet" href="lib3styles.css" type="text/css" />
  14 <link rel="Start" href="documentation.html" type="text/html"
  15   title="GNU C++ Standard Library" />
  16 <link rel="Copyright" href="17_intro/license.html" type="text/html" />
  17 </head>
  18 <body>
  19
  20 <h1 class="centered"><a name="top">Concurrency Support</a></h1>
  21
  22 <p class="fineprint"><em>
  23    The latest version of this document is always available at
  24    <a href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/concurrence.html">
  25    http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/concurrence.html</a>.
  26 </em></p>
  27
  28 <p><em>
  29    To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++ homepage</a>.
  30 </em></p>
  31
  32
  33 <!-- ####################################################### -->
  34
  35 <hr />
  36
  37
  38 <p>The interface for concurrency support is divided into two files:
  39 &lt;ext/atomicity.h&gt; which provides support for atomic operations,
  40 and &lt;ext/concurrence.h&gt;, which provides mutex and lock objects
  41 as well as compile-time data structures for querying thread
  42 support.</p>
  43
  44 <p>It is expected that support for concurrence will evolve into what
  45 is specified in the draft C++0x standard.</p>
  46
  47 <h3 class="left">
  48   <a name="atomic_api">Atomics Interface</a>
  49 </h3>
  50
  51 <p>
  52 Two functions and one type form the base of atomic support.
  53 </p>
  54
  55
  56 <p>The type <code>_Atomic_word</code> is a signed integral type
  57 supporting atomic operations.
  58 </p>
  59
  60 <p>
  61 The two functions functions are:
  62 </p>
  63
  64 <pre>
  65 _Atomic_word
  66 __exchange_and_add_dispatch(volatile _Atomic_word*, int);
  67
  68 void
  69 __atomic_add_dispatch(volatile _Atomic_word*, int);
  70 </pre>
  71
  72 <p>Both of these functions are declared in the header file
  73 &lt;ext/atomicity.h&gt;, and are in <code>namespace __gnu_cxx</code>.
  74 </p>
  75
  76 <ul>
  77 <li>
  78 <code>
  79 __exchange_and_add_dispatch
  80 </code>
  81 <p>Adds the second argument's value to the first argument. Returns the old value.
  82 </p>
  83 </li>
  84 <li>
  85 <code>
  86 __atomic_add_dispatch
  87 </code>
  88 <p>Adds the second argument's value to the first argument. Has no return value.
  89 </p>
  90 </li>
  91 </ul>
  92
  93 <p>
  94 These functions forward to one of several specialized helper
  95 functions, depending on the circumstances. For instance,
  96 </p>
  97
  98 <p>
  99 <code>
 100 __exchange_and_add_dispatch
 101 </code>
 102 </p>
 103
 104 <p>
 105 Calls through to either of:
 106 </p>
 107
 108 <ul>
 109 <li><code>__exchange_and_add</code>
 110 <p>Multi-thread version. Inlined if compiler-generated builtin atomics
 111 can be used, otherwise resolved at link time to a non-builtin code
 112 sequence.
 113 </p>
 114 </li>
 115
 116 <li><code>__exchange_and_add_single</code>
 117 <p>Single threaded version. Inlined.</p>
 118 </li>
 119 </ul>
 120
 121 <p>However, only <code>__exchange_and_add_dispatch</code>
 122 and <code>__atomic_add_dispatch</code> should be used. These functions
 123 can be used in a portable manner, regardless of the specific
 124 environment. They are carefully designed to provide optimum efficiency
 125 and speed, abstracting out atomic accesses when they are not required
 126 (even on hosts that support compiler intrinsics for atomic
 127 operations.)
 128 </p>
 129
 130 <p>
 131 In addition, there are two macros
 132 </p>
 133
 134 <p>
 135 <code>
 136 _GLIBCXX_READ_MEM_BARRIER
 137 </code>
 138 </p>
 139 <p>
 140 <code>
 141 _GLIBCXX_WRITE_MEM_BARRIER
 142 </code>
 143 </p>
 144
 145 <p>
 146 Which expand to the appropriate write and read barrier required by the
 147 host hardware and operating system.
 148 </p>
 149
 150 <h3 class="left">
 151   <a name="pthread_api">Pthread Interface</a>
 152 </h3>
 153
 154 <p>A thin layer above IEEE 1003.1 (ie pthreads) is used to abstract
 155 the thread interface for GCC. This layer is called "gthread," and is
 156 comprised of one header file that wraps the host's default thread layer with
 157 a POSIX-like interface.
 158 </p>
 159
 160 <p> The file &lt;gthr-default.h&gt; points to the deduced wrapper for
 161 the current host. In libstdc++ implementation files,
 162 &lt;bits/gthr.h&gt; is used to select the proper gthreads file.
 163 </p>
 164
 165 <p>Within libstdc++ sources, all calls to underlying thread functionality
 166 use this layer. More detail as to the specific interface can be found in the source <a href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/gthr_8h-source.html">documentation</a>.
 167 </p>
 168
 169 <p>By design, the gthread layer is interoperable with the types,
 170 functions, and usage found in the usual &lt;pthread.h&gt; file,
 171 including <code>pthread_t</code>, <code>pthread_once_t</code>, <code>pthread_create</code>,
 172 etc.
 173 </p>
 174
 175 <h3 class="left">
 176   <a name="concur_api">Concurrence Interface</a>
 177 </h3>
 178
 179 <p>The file &lt;ext/concurrence.h&gt; contains all the higher-level
 180 constructs for playing with threads. In contrast to the atomics layer,
 181 the concurrence layer consists largely of types. All types are defined within <code>namespace __gnu_cxx</code>.
 182 </p>
 183
 184 <p>
 185 These types can be used in a portable manner, regardless of the
 186 specific environment. They are carefully designed to provide optimum
 187 efficiency and speed, abstracting out underlying thread calls and
 188 accesses when compiling for single-threaded situations (even on hosts
 189 that support multiple threads.)
 190 </p>
 191
 192 <p>The enumerated type <code>_Lock_policy</code> details the set of
 193 available locking
 194 policies: <code>_S_single</code>, <code>_S_mutex</code>,
 195 and <code>_S_atomic</code>.
 196 </p>
 197
 198 <ul>
 199 <li><code>_S_single</code>
 200 <p>Indicates single-threaded code that does not need locking.
 201 </p>
 202
 203 </li>
 204 <li><code>_S_mutex</code>
 205 <p>Indicates multi-threaded code using thread-layer abstractions.
 206 </p>
 207 </li>
 208 <li><code>_S_atomic</code>
 209 <p>Indicates multi-threaded code using atomic operations.
 210 </p>
 211 </li>
 212 </ul>
 213
 214 <p>The compile-time constant <code>__default_lock_policy</code> is set
 215 to one of the three values above, depending on characteristics of the
 216 host environment and the current compilation flags.
 217 </p>
 218
 219 <p>Two more datatypes make up the rest of the
 220 interface: <code>__mutex</code>, and <code>__scoped_lock</code>.
 221 </p>
 222
 223 <p>
 224 </p>
 225
 226 <p>The scoped lock idiom is well-discussed within the C++
 227 community. This version takes a <code>__mutex</code> reference, and
 228 locks it during construction of <code>__scoped_locke</code> and
 229 unlocks it during destruction. This is an efficient way of locking
 230 critical sections, while retaining exception-safety.
 231 </p>
 232
 233 <p>Typical usage of the last two constructs is demonstrated as follows:
 234 </p>
 235
 236 <pre>
 237 #include &lt;ext/concurrence.h&gt;
 238
 239 namespace
 240 {
 241   __gnu_cxx::__mutex safe_base_mutex;
 242 } // anonymous namespace
 243
 244 namespace other
 245 {
 246   void
 247   foo()
 248   {
 249     __gnu_cxx::__scoped_lock sentry(safe_base_mutex);
 250     for (int i = 0; i &lt; max;  ++i)
 251       {
 252         _Safe_iterator_base* __old = __iter;
 253         __iter = __iter-&lt;_M_next;
 254         __old-&lt;_M_detach_single();
 255       }
 256 }
 257 </pre>
 258
 259 <p>In this sample code, an anonymous namespace is used to keep
 260 the <code>__mutex</code> private to the compilation unit,
 261 and <code>__scoped_lock</code> is used to guard access to the critical
 262 section within the for loop, locking the mutex on creation and freeing
 263 the mutex as control moves out of this block.
 264 </p>
 265
 266 <p>Several exception classes are used to keep track of
 267 concurrence-related errors. These classes
 268 are: <code>__concurrence_lock_error</code>, <code>__concurrence_unlock_error</code>, <code>__concurrence_wait_error</code>,
 269 and <code>__concurrence_broadcast_error</code>.
 270 </p>
 271
 272
 273
 274 <h3 class="left">
 275   <a name="atomic_impl">Details on builtin atomic support and library fallbacks</a>
 276 </h3>
 277
 278 <p>The functions for atomic operations described above are either
 279 implemented via compiler intrinsics (if the underlying host is
 280 capable) or by library fallbacks.</p>
 281
 282 <p>Compiler intrinsics (builtins) are always preferred.  However, as
 283 the compiler builtins for atomics are not universally implemented,
 284 using them directly is problematic, and can result in undefined
 285 function calls. (An example of an undefined symbol from the use
 286 of <code>__sync_fetch_and_add</code> on an unsupported host is a
 287 missing reference to <code>__sync_fetch_and_add_4</code>.)
 288 </p>
 289
 290 <p>In addition, on some hosts the compiler intrinsics are enabled
 291 conditionally, via the <code>-march</code> command line flag. This makes
 292 usage vary depending on the target hardware and the flags used during
 293 compile.
 294 </p>
 295
 296 <p> If builtins are possible, <code>_GLIBCXX_ATOMIC_BUILTINS</code>
 297 will be defined.
 298 </p>
 299
 300
 301 <p>For the following hosts, intrinsics are enabled by default.
 302 </p>
 303
 304 <ul>
 305   <li>alpha</li>
 306   <li>ia64</li>
 307   <li>powerpc</li>
 308   <li>s390</li>
 309 </ul>
 310
 311 <p>For others, some form of <code>-march</code> may work. On
 312 non-ancient x86 hardware, <code>-march=native</code> usually does the
 313 trick.</p>
 314
 315 <p> For hosts without compiler intrinsics, but with capable
 316 hardware, hand-crafted assembly is selected. This is the case for the following hosts:
 317 </p>
 318
 319 <ul>
 320   <li>cris</li>
 321   <li>hppa</li>
 322   <li>i386</li>
 323   <li>i486</li>
 324   <li>m48k</li>
 325   <li>mips</li>
 326   <li>sparc</li>
 327 </ul>
 328
 329 <p>And for the rest, a simulated atomic lock via pthreads.
 330 </p>
 331
 332 <p> Detailed information about compiler intrinsics for atomic operations can be found in the GCC <a href="http://gcc.gnu.org/onlinedocs/gcc/Atomic-Builtins.html"> documentation</a>.
 333 </p>
 334
 335 <p> More details on the library fallbacks from the porting <a href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/porting.html#Thread%20safety">section</a>.
 336 </p>
 337
 338
 339
 340 </body>
 341 </html>
 342