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=UTF-8"> 5<title>Chapter 6. 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 I. 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 6. 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 © 2011 Helge Bahmann</p></div> 37<div><p class="copyright">Copyright © 2012 Tim Blechmann</p></div> 38<div><p class="copyright">Copyright © 2013, 2017, 2018, 2020 Andrey 39 Semashev</p></div> 40<div><div class="legalnotice"> 41<a name="atomic.legal"></a><p> 42 Distributed under the Boost Software License, Version 1.0. (See accompanying 43 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>) 44 </p> 45</div></div> 46</div></div> 47<div class="toc"> 48<p><b>Table of Contents</b></p> 49<dl class="toc"> 50<dt><span class="section"><a href="atomic.html#atomic.introduction">Introduction</a></span></dt> 51<dd><dl> 52<dt><span class="section"><a href="atomic.html#atomic.introduction.introduction_presenting">Presenting 53 Boost.Atomic</a></span></dt> 54<dt><span class="section"><a href="atomic.html#atomic.introduction.introduction_purpose">Purpose</a></span></dt> 55</dl></dd> 56<dt><span class="section"><a href="atomic/thread_coordination.html">Thread coordination using Boost.Atomic</a></span></dt> 57<dd><dl> 58<dt><span class="section"><a href="atomic/thread_coordination.html#atomic.thread_coordination.mutex">Enforcing <span class="emphasis"><em>happens-before</em></span> 59 through mutual exclusion</a></span></dt> 60<dt><span class="section"><a href="atomic/thread_coordination.html#atomic.thread_coordination.release_acquire"><span class="emphasis"><em>happens-before</em></span> 61 through <code class="literal">release</code> and <code class="literal">acquire</code></a></span></dt> 62<dt><span class="section"><a href="atomic/thread_coordination.html#atomic.thread_coordination.fences">Fences</a></span></dt> 63<dt><span class="section"><a href="atomic/thread_coordination.html#atomic.thread_coordination.release_consume"><span class="emphasis"><em>happens-before</em></span> 64 through <code class="literal">release</code> and <code class="literal">consume</code></a></span></dt> 65<dt><span class="section"><a href="atomic/thread_coordination.html#atomic.thread_coordination.seq_cst">Sequential consistency</a></span></dt> 66</dl></dd> 67<dt><span class="section"><a href="atomic/interface.html">Programming interfaces</a></span></dt> 68<dd><dl> 69<dt><span class="section"><a href="atomic/interface.html#atomic.interface.configuration">Configuration and building</a></span></dt> 70<dt><span class="section"><a href="atomic/interface.html#atomic.interface.interface_memory_order">Memory order</a></span></dt> 71<dt><span class="section"><a href="atomic/interface.html#atomic.interface.interface_atomic_flag">Atomic flags</a></span></dt> 72<dt><span class="section"><a href="atomic/interface.html#atomic.interface.interface_atomic_object">Atomic objects</a></span></dt> 73<dt><span class="section"><a href="atomic/interface.html#atomic.interface.interface_atomic_ref">Atomic references</a></span></dt> 74<dt><span class="section"><a href="atomic/interface.html#atomic.interface.interface_wait_notify_ops">Waiting and 75 notifying operations</a></span></dt> 76<dt><span class="section"><a href="atomic/interface.html#atomic.interface.interface_ipc">Atomic types for inter-process 77 communication</a></span></dt> 78<dt><span class="section"><a href="atomic/interface.html#atomic.interface.interface_fences">Fences</a></span></dt> 79<dt><span class="section"><a href="atomic/interface.html#atomic.interface.feature_macros">Feature testing macros</a></span></dt> 80</dl></dd> 81<dt><span class="section"><a href="atomic/usage_examples.html">Usage examples</a></span></dt> 82<dd><dl> 83<dt><span class="section"><a href="atomic/usage_examples.html#boost_atomic.usage_examples.example_reference_counters">Reference 84 counting</a></span></dt> 85<dt><span class="section"><a href="atomic/usage_examples.html#boost_atomic.usage_examples.example_spinlock">Spinlock</a></span></dt> 86<dt><span class="section"><a href="atomic/usage_examples.html#boost_atomic.usage_examples.singleton">Singleton with 87 double-checked locking pattern</a></span></dt> 88<dt><span class="section"><a href="atomic/usage_examples.html#boost_atomic.usage_examples.example_ringbuffer">Wait-free 89 ring buffer</a></span></dt> 90<dt><span class="section"><a href="atomic/usage_examples.html#boost_atomic.usage_examples.mp_queue">Lock-free multi-producer 91 queue</a></span></dt> 92</dl></dd> 93<dt><span class="section"><a href="atomic/limitations.html">Limitations</a></span></dt> 94<dt><span class="section"><a href="atomic/porting.html">Porting</a></span></dt> 95<dd><dl> 96<dt><span class="section"><a href="atomic/porting.html#atomic.porting.unit_tests">Unit tests</a></span></dt> 97<dt><span class="section"><a href="atomic/porting.html#atomic.porting.tested_compilers">Tested compilers</a></span></dt> 98<dt><span class="section"><a href="atomic/porting.html#atomic.porting.acknowledgements">Acknowledgements</a></span></dt> 99</dl></dd> 100</dl> 101</div> 102<div class="section"> 103<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 104<a name="atomic.introduction"></a><a class="link" href="atomic.html#atomic.introduction" title="Introduction">Introduction</a> 105</h2></div></div></div> 106<div class="toc"><dl class="toc"> 107<dt><span class="section"><a href="atomic.html#atomic.introduction.introduction_presenting">Presenting 108 Boost.Atomic</a></span></dt> 109<dt><span class="section"><a href="atomic.html#atomic.introduction.introduction_purpose">Purpose</a></span></dt> 110</dl></div> 111<div class="section"> 112<div class="titlepage"><div><div><h3 class="title"> 113<a name="atomic.introduction.introduction_presenting"></a><a class="link" href="atomic.html#atomic.introduction.introduction_presenting" title="Presenting Boost.Atomic">Presenting 114 Boost.Atomic</a> 115</h3></div></div></div> 116<p> 117 <span class="bold"><strong>Boost.Atomic</strong></span> is a library that provides 118 <code class="literal">atomic</code> data types and operations on these data types, 119 as well as memory ordering constraints required for coordinating multiple 120 threads through atomic variables. It implements the interface as defined 121 by the C++11 standard, but makes this feature available for platforms lacking 122 system/compiler support for this particular C++11 feature. 123 </p> 124<p> 125 Users of this library should already be familiar with concurrency in general, 126 as well as elementary concepts such as "mutual exclusion". 127 </p> 128<p> 129 The implementation makes use of processor-specific instructions where possible 130 (via inline assembler, platform libraries or compiler intrinsics), and falls 131 back to "emulating" atomic operations through locking. 132 </p> 133</div> 134<div class="section"> 135<div class="titlepage"><div><div><h3 class="title"> 136<a name="atomic.introduction.introduction_purpose"></a><a class="link" href="atomic.html#atomic.introduction.introduction_purpose" title="Purpose">Purpose</a> 137</h3></div></div></div> 138<p> 139 Operations on "ordinary" variables are not guaranteed to be atomic. 140 This means that with <code class="literal">int n=0</code> initially, two threads concurrently 141 executing 142 </p> 143<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">function</span><span class="special">()</span> 144<span class="special">{</span> 145 <span class="identifier">n</span> <span class="special">++;</span> 146<span class="special">}</span> 147</pre> 148<p> 149 might result in <code class="literal">n==1</code> instead of 2: Each thread will read 150 the old value into a processor register, increment it and write the result 151 back. Both threads may therefore write <code class="literal">1</code>, unaware that 152 the other thread is doing likewise. 153 </p> 154<p> 155 Declaring <code class="literal">atomic<int> n=0</code> instead, the same operation 156 on this variable will always result in <code class="literal">n==2</code> as each operation 157 on this variable is <span class="emphasis"><em>atomic</em></span>: This means that each operation 158 behaves as if it were strictly sequentialized with respect to the other. 159 </p> 160<p> 161 Atomic variables are useful for two purposes: 162 </p> 163<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 164<li class="listitem"> 165 as a means for coordinating multiple threads via custom coordination 166 protocols 167 </li> 168<li class="listitem"> 169 as faster alternatives to "locked" access to simple variables 170 </li> 171</ul></div> 172<p> 173 Take a look at the <a class="link" href="atomic/usage_examples.html" title="Usage examples">examples</a> 174 section for common patterns. 175 </p> 176</div> 177</div> 178</div> 179<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 180<td align="left"><p><small>Last revised: August 11, 2020 at 15:04:03 GMT</small></p></td> 181<td align="right"><div class="copyright-footer"></div></td> 182</tr></table> 183<hr> 184<div class="spirit-nav"> 185<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> 186</div> 187</body> 188</html> 189
