doc/html/atomic.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   5 <title>Chapter&#160;6.&#160;Boost.Atomic</title>
   6 <link rel="stylesheet" href="../../doc/src/boostbook.css" type="text/css">
   7 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   8 <link rel="home" href="index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
   9 <link rel="up" href="libraries.html" title="Part&#160;I.&#160;The Boost C++ Libraries (BoostBook Subset)">
  10 <link rel="prev" href="array/ack.html" title="Acknowledgements">
  11 <link rel="next" href="atomic/thread_coordination.html" title="Thread coordination using Boost.Atomic">
  12 </head>
  13 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  14 <table cellpadding="2" width="100%"><tr>
  15 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../boost.png"></td>
  16 <td align="center"><a href="../../index.html">Home</a></td>
  17 <td align="center"><a href="../../libs/libraries.htm">Libraries</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  19 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  20 <td align="center"><a href="../../more/index.htm">More</a></td>
  21 </tr></table>
  22 <hr>
  23 <div class="spirit-nav">
  24 <a accesskey="p" href="array/ack.html"><img src="../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="libraries.html"><img src="../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="atomic/thread_coordination.html"><img src="../../doc/src/images/next.png" alt="Next"></a>
  25 </div>
  26 <div class="chapter">
  27 <div class="titlepage"><div>
  28 <div><h2 class="title">
  29 <a name="atomic"></a>Chapter&#160;6.&#160;Boost.Atomic</h2></div>
  30 <div><div class="author"><h3 class="author">
  31 <span class="firstname">Helge</span> <span class="surname">Bahmann</span>
  32 </h3></div></div>
  33 <div><div class="author"><h3 class="author">
  34 <span class="firstname">Andrey</span> <span class="surname">Semashev</span>
  35 </h3></div></div>
  36 <div><p class="copyright">Copyright &#169; 2011 Helge Bahmann</p></div>
  37 <div><p class="copyright">Copyright &#169; 2012 Tim Blechmann</p></div>
  38 <div><p class="copyright">Copyright &#169; 2013, 2017, 2018 Andrey Semashev</p></div>
  39 <div><div class="legalnotice">
  40 <a name="atomic.legal"></a><p>
  41         Distributed under the Boost Software License, Version 1.0. (See accompanying
  42         file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
  43       </p>
  44 </div></div>
  45 </div></div>
  46 <div class="toc">
  47 <p><b>Table of Contents</b></p>
  48 <dl class="toc">
  49 <dt><span class="section"><a href="atomic.html#atomic.introduction">Introduction</a></span></dt>
  50 <dd><dl>
  51 <dt><span class="section"><a href="atomic.html#atomic.introduction.introduction_presenting">Presenting
  52       Boost.Atomic</a></span></dt>
  53 <dt><span class="section"><a href="atomic.html#atomic.introduction.introduction_purpose">Purpose</a></span></dt>
  54 </dl></dd>
  55 <dt><span class="section"><a href="atomic/thread_coordination.html">Thread coordination using Boost.Atomic</a></span></dt>
  56 <dd><dl>
  57 <dt><span class="section"><a href="atomic/thread_coordination.html#atomic.thread_coordination.mutex">Enforcing <span class="emphasis"><em>happens-before</em></span>
  58       through mutual exclusion</a></span></dt>
  59 <dt><span class="section"><a href="atomic/thread_coordination.html#atomic.thread_coordination.release_acquire"><span class="emphasis"><em>happens-before</em></span>
  60       through <code class="literal">release</code> and <code class="literal">acquire</code></a></span></dt>
  61 <dt><span class="section"><a href="atomic/thread_coordination.html#atomic.thread_coordination.fences">Fences</a></span></dt>
  62 <dt><span class="section"><a href="atomic/thread_coordination.html#atomic.thread_coordination.release_consume"><span class="emphasis"><em>happens-before</em></span>
  63       through <code class="literal">release</code> and <code class="literal">consume</code></a></span></dt>
  64 <dt><span class="section"><a href="atomic/thread_coordination.html#atomic.thread_coordination.seq_cst">Sequential consistency</a></span></dt>
  65 </dl></dd>
  66 <dt><span class="section"><a href="atomic/interface.html">Programming interfaces</a></span></dt>
  67 <dd><dl>
  68 <dt><span class="section"><a href="atomic/interface.html#atomic.interface.configuration">Configuration and building</a></span></dt>
  69 <dt><span class="section"><a href="atomic/interface.html#atomic.interface.interface_memory_order">Memory order</a></span></dt>
  70 <dt><span class="section"><a href="atomic/interface.html#atomic.interface.interface_atomic_flag">Atomic flags</a></span></dt>
  71 <dt><span class="section"><a href="atomic/interface.html#atomic.interface.interface_atomic_object">Atomic objects</a></span></dt>
  72 <dt><span class="section"><a href="atomic/interface.html#atomic.interface.interface_fences">Fences</a></span></dt>
  73 <dt><span class="section"><a href="atomic/interface.html#atomic.interface.feature_macros">Feature testing macros</a></span></dt>
  74 </dl></dd>
  75 <dt><span class="section"><a href="atomic/usage_examples.html">Usage examples</a></span></dt>
  76 <dd><dl>
  77 <dt><span class="section"><a href="atomic/usage_examples.html#boost_atomic.usage_examples.example_reference_counters">Reference
  78       counting</a></span></dt>
  79 <dt><span class="section"><a href="atomic/usage_examples.html#boost_atomic.usage_examples.example_spinlock">Spinlock</a></span></dt>
  80 <dt><span class="section"><a href="atomic/usage_examples.html#boost_atomic.usage_examples.singleton">Singleton with
  81       double-checked locking pattern</a></span></dt>
  82 <dt><span class="section"><a href="atomic/usage_examples.html#boost_atomic.usage_examples.example_ringbuffer">Wait-free
  83       ring buffer</a></span></dt>
  84 <dt><span class="section"><a href="atomic/usage_examples.html#boost_atomic.usage_examples.mp_queue">Wait-free multi-producer
  85       queue</a></span></dt>
  86 </dl></dd>
  87 <dt><span class="section"><a href="atomic/limitations.html">Limitations</a></span></dt>
  88 <dt><span class="section"><a href="atomic/porting.html">Porting</a></span></dt>
  89 <dd><dl>
  90 <dt><span class="section"><a href="atomic/porting.html#atomic.porting.unit_tests">Unit tests</a></span></dt>
  91 <dt><span class="section"><a href="atomic/porting.html#atomic.porting.tested_compilers">Tested compilers</a></span></dt>
  92 <dt><span class="section"><a href="atomic/porting.html#atomic.porting.acknowledgements">Acknowledgements</a></span></dt>
  93 </dl></dd>
  94 </dl>
  95 </div>
  96 <div class="section">
  97 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  98 <a name="atomic.introduction"></a><a class="link" href="atomic.html#atomic.introduction" title="Introduction">Introduction</a>
  99 </h2></div></div></div>
 100 <div class="toc"><dl class="toc">
 101 <dt><span class="section"><a href="atomic.html#atomic.introduction.introduction_presenting">Presenting
 102       Boost.Atomic</a></span></dt>
 103 <dt><span class="section"><a href="atomic.html#atomic.introduction.introduction_purpose">Purpose</a></span></dt>
 104 </dl></div>
 105 <div class="section">
 106 <div class="titlepage"><div><div><h3 class="title">
 107 <a name="atomic.introduction.introduction_presenting"></a><a class="link" href="atomic.html#atomic.introduction.introduction_presenting" title="Presenting Boost.Atomic">Presenting
 108       Boost.Atomic</a>
 109 </h3></div></div></div>
 110 <p>
 111         <span class="bold"><strong>Boost.Atomic</strong></span> is a library that provides
 112         <code class="literal">atomic</code> data types and operations on these data types,
 113         as well as memory ordering constraints required for coordinating multiple
 114         threads through atomic variables. It implements the interface as defined
 115         by the C++11 standard, but makes this feature available for platforms lacking
 116         system/compiler support for this particular C++11 feature.
 117       </p>
 118 <p>
 119         Users of this library should already be familiar with concurrency in general,
 120         as well as elementary concepts such as "mutual exclusion".
 121       </p>
 122 <p>
 123         The implementation makes use of processor-specific instructions where possible
 124         (via inline assembler, platform libraries or compiler intrinsics), and falls
 125         back to "emulating" atomic operations through locking.
 126       </p>
 127 </div>
 128 <div class="section">
 129 <div class="titlepage"><div><div><h3 class="title">
 130 <a name="atomic.introduction.introduction_purpose"></a><a class="link" href="atomic.html#atomic.introduction.introduction_purpose" title="Purpose">Purpose</a>
 131 </h3></div></div></div>
 132 <p>
 133         Operations on "ordinary" variables are not guaranteed to be atomic.
 134         This means that with <code class="literal">int n=0</code> initially, two threads concurrently
 135         executing
 136       </p>
 137 <pre class="programlisting"><span class="keyword">void</span> <span class="identifier">function</span><span class="special">()</span>
 138 <span class="special">{</span>
 139   <span class="identifier">n</span> <span class="special">++;</span>
 140 <span class="special">}</span>
 141 </pre>
 142 <p>
 143         might result in <code class="literal">n==1</code> instead of 2: Each thread will read
 144         the old value into a processor register, increment it and write the result
 145         back. Both threads may therefore write <code class="literal">1</code>, unaware that
 146         the other thread is doing likewise.
 147       </p>
 148 <p>
 149         Declaring <code class="literal">atomic&lt;int&gt; n=0</code> instead, the same operation
 150         on this variable will always result in <code class="literal">n==2</code> as each operation
 151         on this variable is <span class="emphasis"><em>atomic</em></span>: This means that each operation
 152         behaves as if it were strictly sequentialized with respect to the other.
 153       </p>
 154 <p>
 155         Atomic variables are useful for two purposes:
 156       </p>
 157 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 158 <li class="listitem">
 159             as a means for coordinating multiple threads via custom coordination
 160             protocols
 161           </li>
 162 <li class="listitem">
 163             as faster alternatives to "locked" access to simple variables
 164           </li>
 165 </ul></div>
 166 <p>
 167         Take a look at the <a class="link" href="atomic/usage_examples.html" title="Usage examples">examples</a>
 168         section for common patterns.
 169       </p>
 170 </div>
 171 </div>
 172 </div>
 173 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 174 <td align="left"><p><small>Last revised: December 10, 2019 at 00:27:07 GMT</small></p></td>
 175 <td align="right"><div class="copyright-footer"></div></td>
 176 </tr></table>
 177 <hr>
 178 <div class="spirit-nav">
 179 <a accesskey="p" href="array/ack.html"><img src="../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="libraries.html"><img src="../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="atomic/thread_coordination.html"><img src="../../doc/src/images/next.png" alt="Next"></a>
 180 </div>
 181 </body>
 182 </html>