libstdc++-v3/doc/xml/manual/concurrency_extensions.xml

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