l4/pkg/libstdc++-v3/contrib/libstdc++-v3-4.7/doc/html/manual/ext_concurrency.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml"><head><title>Chapter 30. Concurrency</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content="&#10;      ISO C++&#10;    , &#10;      library&#10;    "/><meta name="keywords" content="&#10;      ISO C++&#10;    , &#10;      library&#10;    "/><meta name="keywords" content="&#10;      ISO C++&#10;    , &#10;      runtime&#10;    , &#10;      library&#10;    "/><link rel="home" href="../index.html" title="The GNU C++ Library"/><link rel="up" href="extensions.html" title="Part III.  Extensions"/><link rel="prev" href="ext_demangling.html" title="Chapter 29. Demangling"/><link rel="next" href="bk01pt03ch30s02.html" title="Implementation"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 30. Concurrency</th></tr><tr><td align="left"><a accesskey="p" href="ext_demangling.html">Prev</a> </td><th width="60%" align="center">Part III.
   4   Extensions
   5
   6 </th><td align="right"> <a accesskey="n" href="bk01pt03ch30s02.html">Next</a></td></tr></table><hr/></div><div class="chapter" title="Chapter 30. Concurrency"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.concurrency"/>Chapter 30. Concurrency</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="ext_concurrency.html#manual.ext.concurrency.design">Design</a></span></dt><dd><dl><dt><span class="section"><a href="ext_concurrency.html#manual.ext.concurrency.design.threads">Interface to Locks and Mutexes</a></span></dt><dt><span class="section"><a href="ext_concurrency.html#manual.ext.concurrency.design.atomics">Interface to Atomic Functions</a></span></dt></dl></dd><dt><span class="section"><a href="bk01pt03ch30s02.html">Implementation</a></span></dt><dd><dl><dt><span class="section"><a href="bk01pt03ch30s02.html#manual.ext.concurrency.impl.atomic_fallbacks">Using Builtin Atomic Functions</a></span></dt><dt><span class="section"><a href="bk01pt03ch30s02.html#manual.ext.concurrency.impl.thread">Thread Abstraction</a></span></dt></dl></dd><dt><span class="section"><a href="bk01pt03ch30s03.html">Use</a></span></dt></dl></div><div class="section" title="Design"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.concurrency.design"/>Design</h2></div></div></div><div class="section" title="Interface to Locks and Mutexes"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.concurrency.design.threads"/>Interface to Locks and Mutexes</h3></div></div></div><p>The file <code class="filename">&lt;ext/concurrence.h&gt;</code>
   7 contains all the higher-level
   8 constructs for playing with threads. In contrast to the atomics layer,
   9 the concurrence layer consists largely of types. All types are defined within <code class="code">namespace __gnu_cxx</code>.
  10 </p><p>
  11 These types can be used in a portable manner, regardless of the
  12 specific environment. They are carefully designed to provide optimum
  13 efficiency and speed, abstracting out underlying thread calls and
  14 accesses when compiling for single-threaded situations (even on hosts
  15 that support multiple threads.)
  16 </p><p>The enumerated type <code class="code">_Lock_policy</code> details the set of
  17 available locking
  18 policies: <code class="code">_S_single</code>, <code class="code">_S_mutex</code>,
  19 and <code class="code">_S_atomic</code>.
  20 </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><code class="code">_S_single</code></p><p>Indicates single-threaded code that does not need locking.
  21 </p></li><li class="listitem"><p><code class="code">_S_mutex</code></p><p>Indicates multi-threaded code using thread-layer abstractions.
  22 </p></li><li class="listitem"><p><code class="code">_S_atomic</code></p><p>Indicates multi-threaded code using atomic operations.
  23 </p></li></ul></div><p>The compile-time constant <code class="code">__default_lock_policy</code> is set
  24 to one of the three values above, depending on characteristics of the
  25 host environment and the current compilation flags.
  26 </p><p>Two more datatypes make up the rest of the
  27 interface: <code class="code">__mutex</code>, and <code class="code">__scoped_lock</code>.
  28 </p><p>The scoped lock idiom is well-discussed within the C++
  29 community. This version takes a <code class="code">__mutex</code> reference, and
  30 locks it during construction of <code class="code">__scoped_lock</code> and
  31 unlocks it during destruction. This is an efficient way of locking
  32 critical sections, while retaining exception-safety.
  33 These types have been superseded in the ISO C++ 2011 standard by the
  34 mutex and lock types defined in the header
  35 <code class="filename">&lt;mutex&gt;</code>.
  36 </p></div><div class="section" title="Interface to Atomic Functions"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.concurrency.design.atomics"/>Interface to Atomic Functions</h3></div></div></div><p>
  37 Two functions and one type form the base of atomic support.
  38 </p><p>The type <code class="code">_Atomic_word</code> is a signed integral type
  39 supporting atomic operations.
  40 </p><p>
  41 The two functions functions are:
  42 </p><pre class="programlisting">
  43 _Atomic_word
  44 __exchange_and_add_dispatch(volatile _Atomic_word*, int);
  45
  46 void
  47 __atomic_add_dispatch(volatile _Atomic_word*, int);
  48 </pre><p>Both of these functions are declared in the header file
  49 &lt;ext/atomicity.h&gt;, and are in <code class="code">namespace __gnu_cxx</code>.
  50 </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>
  51 <code class="code">
  52 __exchange_and_add_dispatch
  53 </code>
  54 </p><p>Adds the second argument's value to the first argument. Returns the old value.
  55 </p></li><li class="listitem"><p>
  56 <code class="code">
  57 __atomic_add_dispatch
  58 </code>
  59 </p><p>Adds the second argument's value to the first argument. Has no return value.
  60 </p></li></ul></div><p>
  61 These functions forward to one of several specialized helper
  62 functions, depending on the circumstances. For instance,
  63 </p><p>
  64 <code class="code">
  65 __exchange_and_add_dispatch
  66 </code>
  67 </p><p>
  68 Calls through to either of:
  69 </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><code class="code">__exchange_and_add</code>
  70 </p><p>Multi-thread version. Inlined if compiler-generated builtin atomics
  71 can be used, otherwise resolved at link time to a non-builtin code
  72 sequence.
  73 </p></li><li class="listitem"><p><code class="code">__exchange_and_add_single</code>
  74 </p><p>Single threaded version. Inlined.</p></li></ul></div><p>However, only <code class="code">__exchange_and_add_dispatch</code>
  75 and <code class="code">__atomic_add_dispatch</code> should be used. These functions
  76 can be used in a portable manner, regardless of the specific
  77 environment. They are carefully designed to provide optimum efficiency
  78 and speed, abstracting out atomic accesses when they are not required
  79 (even on hosts that support compiler intrinsics for atomic
  80 operations.)
  81 </p><p>
  82 In addition, there are two macros
  83 </p><p>
  84 <code class="code">
  85 _GLIBCXX_READ_MEM_BARRIER
  86 </code>
  87 </p><p>
  88 <code class="code">
  89 _GLIBCXX_WRITE_MEM_BARRIER
  90 </code>
  91 </p><p>
  92 Which expand to the appropriate write and read barrier required by the
  93 host hardware and operating system.
  94 </p></div></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="ext_demangling.html">Prev</a> </td><td align="center"><a accesskey="u" href="extensions.html">Up</a></td><td align="right"> <a accesskey="n" href="bk01pt03ch30s02.html">Next</a></td></tr><tr><td align="left" valign="top">Chapter 29. Demangling </td><td align="center"><a accesskey="h" href="../index.html">Home</a></td><td align="right" valign="top"> Implementation</td></tr></table></div></body></html>