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