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 &lt;ext/concurrence.h&gt; 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>.
  27 </para>
  28
  29 <para>
  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.)
  35 </para>
  36
  37 <para>The enumerated type <code>_Lock_policy</code> details the set of
  38 available locking
  39 policies: <code>_S_single</code>, <code>_S_mutex</code>,
  40 and <code>_S_atomic</code>.
  41 </para>
  42
  43 <itemizedlist>
  44 <listitem><para><code>_S_single</code></para>
  45 <para>Indicates single-threaded code that does not need locking.
  46 </para>
  47
  48 </listitem>
  49 <listitem><para><code>_S_mutex</code></para>
  50 <para>Indicates multi-threaded code using thread-layer abstractions.
  51 </para>
  52 </listitem>
  53 <listitem><para><code>_S_atomic</code></para>
  54 <para>Indicates multi-threaded code using atomic operations.
  55 </para>
  56 </listitem>
  57 </itemizedlist>
  58
  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.
  62 </para>
  63
  64 <para>Two more datatypes make up the rest of the
  65 interface: <code>__mutex</code>, and <code>__scoped_lock</code>.
  66 </para>
  67
  68 <para>
  69 </para>
  70
  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.
  76 </para>
  77   </section>
  78
  79   <section xml:id="manual.ext.concurrency.design.atomics" xreflabel="Atomic API"><info><title>Interface to Atomic Functions</title></info>
  80
  81
  82
  83 <para>
  84 Two functions and one type form the base of atomic support.
  85 </para>
  86
  87
  88 <para>The type <code>_Atomic_word</code> is a signed integral type
  89 supporting atomic operations.
  90 </para>
  91
  92 <para>
  93 The two functions functions are:
  94 </para>
  95
  96 <programlisting>
  97 _Atomic_word
  98 __exchange_and_add_dispatch(volatile _Atomic_word*, int);
  99
 100 void
 101 __atomic_add_dispatch(volatile _Atomic_word*, int);
 102 </programlisting>
 103
 104 <para>Both of these functions are declared in the header file
 105 &lt;ext/atomicity.h&gt;, and are in <code>namespace __gnu_cxx</code>.
 106 </para>
 107
 108 <itemizedlist>
 109 <listitem><para>
 110 <code>
 111 __exchange_and_add_dispatch
 112 </code>
 113 </para>
 114 <para>Adds the second argument's value to the first argument. Returns the old value.
 115 </para>
 116 </listitem>
 117 <listitem><para>
 118 <code>
 119 __atomic_add_dispatch
 120 </code>
 121 </para>
 122 <para>Adds the second argument's value to the first argument. Has no return value.
 123 </para>
 124 </listitem>
 125 </itemizedlist>
 126
 127 <para>
 128 These functions forward to one of several specialized helper
 129 functions, depending on the circumstances. For instance,
 130 </para>
 131
 132 <para>
 133 <code>
 134 __exchange_and_add_dispatch
 135 </code>
 136 </para>
 137
 138 <para>
 139 Calls through to either of:
 140 </para>
 141
 142 <itemizedlist>
 143 <listitem><para><code>__exchange_and_add</code>
 144 </para>
 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
 147 sequence.
 148 </para>
 149 </listitem>
 150
 151 <listitem><para><code>__exchange_and_add_single</code>
 152 </para>
 153 <para>Single threaded version. Inlined.</para>
 154 </listitem>
 155 </itemizedlist>
 156
 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
 163 operations.)
 164 </para>
 165
 166 <para>
 167 In addition, there are two macros
 168 </para>
 169
 170 <para>
 171 <code>
 172 _GLIBCXX_READ_MEM_BARRIER
 173 </code>
 174 </para>
 175 <para>
 176 <code>
 177 _GLIBCXX_WRITE_MEM_BARRIER
 178 </code>
 179 </para>
 180
 181 <para>
 182 Which expand to the appropriate write and read barrier required by the
 183 host hardware and operating system.
 184 </para>
 185   </section>
 186
 187 </section>
 188
 189
 190 <section xml:id="manual.ext.concurrency.impl" xreflabel="Implementation"><info><title>Implementation</title></info>
 191
 192   <section xml:id="manual.ext.concurrency.impl.atomic_fallbacks" xreflabel="Atomic F"><info><title>Using Builtin Atomic Functions</title></info>
 193
 194
 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>
 198
 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>.)
 205 </para>
 206
 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
 210 compile.
 211 </para>
 212
 213 <para>
 214 If builtins are possible for bool-sized integral types,
 215 <code>_GLIBCXX_ATOMIC_BUILTINS_1</code> will be defined.
 216 If builtins are possible for int-sized integral types,
 217 <code>_GLIBCXX_ATOMIC_BUILTINS_4</code> will be defined.
 218 </para>
 219
 220
 221 <para>For the following hosts, intrinsics are enabled by default.
 222 </para>
 223
 224 <itemizedlist>
 225   <listitem><para>alpha</para></listitem>
 226   <listitem><para>ia64</para></listitem>
 227   <listitem><para>powerpc</para></listitem>
 228   <listitem><para>s390</para></listitem>
 229 </itemizedlist>
 230
 231 <para>For others, some form of <code>-march</code> may work. On
 232 non-ancient x86 hardware, <code>-march=native</code> usually does the
 233 trick.</para>
 234
 235 <para> For hosts without compiler intrinsics, but with capable
 236 hardware, hand-crafted assembly is selected. This is the case for the following hosts:
 237 </para>
 238
 239 <itemizedlist>
 240   <listitem><para>cris</para></listitem>
 241   <listitem><para>hppa</para></listitem>
 242   <listitem><para>i386</para></listitem>
 243   <listitem><para>i486</para></listitem>
 244   <listitem><para>m48k</para></listitem>
 245   <listitem><para>mips</para></listitem>
 246   <listitem><para>sparc</para></listitem>
 247 </itemizedlist>
 248
 249 <para>And for the rest, a simulated atomic lock via pthreads.
 250 </para>
 251
 252 <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>.
 253 </para>
 254
 255 <para> More details on the library fallbacks from the porting <link linkend="internals.thread_safety">section</link>.
 256 </para>
 257
 258
 259   </section>
 260   <section xml:id="manual.ext.concurrency.impl.thread" xreflabel="Pthread"><info><title>Thread Abstraction</title></info>
 261
 262
 263 <para>A thin layer above IEEE 1003.1 (i.e. pthreads) is used to abstract
 264 the thread interface for GCC. This layer is called "gthread," and is
 265 comprised of one header file that wraps the host's default thread layer with
 266 a POSIX-like interface.
 267 </para>
 268
 269 <para> The file &lt;gthr-default.h&gt; points to the deduced wrapper for
 270 the current host. In libstdc++ implementation files,
 271 &lt;bits/gthr.h&gt; is used to select the proper gthreads file.
 272 </para>
 273
 274 <para>Within libstdc++ sources, all calls to underlying thread functionality
 275 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>.
 276 </para>
 277
 278 <para>By design, the gthread layer is interoperable with the types,
 279 functions, and usage found in the usual &lt;pthread.h&gt; file,
 280 including <code>pthread_t</code>, <code>pthread_once_t</code>, <code>pthread_create</code>,
 281 etc.
 282 </para>
 283
 284   </section>
 285 </section>
 286
 287 <section xml:id="manual.ext.concurrency.use" xreflabel="Use"><info><title>Use</title></info>
 288
 289
 290
 291 <para>Typical usage of the last two constructs is demonstrated as follows:
 292 </para>
 293
 294 <programlisting>
 295 #include &lt;ext/concurrence.h&gt;
 296
 297 namespace
 298 {
 299   __gnu_cxx::__mutex safe_base_mutex;
 300 } // anonymous namespace
 301
 302 namespace other
 303 {
 304   void
 305   foo()
 306   {
 307     __gnu_cxx::__scoped_lock sentry(safe_base_mutex);
 308     for (int i = 0; i &lt; max;  ++i)
 309       {
 310         _Safe_iterator_base* __old = __iter;
 311         __iter = __iter-&lt;_M_next;
 312         __old-&lt;_M_detach_single();
 313       }
 314 }
 315 </programlisting>
 316
 317 <para>In this sample code, an anonymous namespace is used to keep
 318 the <code>__mutex</code> private to the compilation unit,
 319 and <code>__scoped_lock</code> is used to guard access to the critical
 320 section within the for loop, locking the mutex on creation and freeing
 321 the mutex as control moves out of this block.
 322 </para>
 323
 324 <para>Several exception classes are used to keep track of
 325 concurrence-related errors. These classes
 326 are: <code>__concurrence_lock_error</code>, <code>__concurrence_unlock_error</code>, <code>__concurrence_wait_error</code>,
 327 and <code>__concurrence_broadcast_error</code>.
 328 </para>
 329
 330
 331 </section>
 332
 333 </chapter>