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>Programming interfaces</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="../atomic.html" title="Chapter 6. Boost.Atomic"> 10<link rel="prev" href="thread_coordination.html" title="Thread coordination using Boost.Atomic"> 11<link rel="next" href="usage_examples.html" title="Usage examples"> 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="thread_coordination.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../atomic.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="usage_examples.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> 25</div> 26<div class="section"> 27<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 28<a name="atomic.interface"></a><a class="link" href="interface.html" title="Programming interfaces">Programming interfaces</a> 29</h2></div></div></div> 30<div class="toc"><dl class="toc"> 31<dt><span class="section"><a href="interface.html#atomic.interface.configuration">Configuration and building</a></span></dt> 32<dt><span class="section"><a href="interface.html#atomic.interface.interface_memory_order">Memory order</a></span></dt> 33<dt><span class="section"><a href="interface.html#atomic.interface.interface_atomic_flag">Atomic flags</a></span></dt> 34<dt><span class="section"><a href="interface.html#atomic.interface.interface_atomic_object">Atomic objects</a></span></dt> 35<dt><span class="section"><a href="interface.html#atomic.interface.interface_atomic_ref">Atomic references</a></span></dt> 36<dt><span class="section"><a href="interface.html#atomic.interface.interface_wait_notify_ops">Waiting and 37 notifying operations</a></span></dt> 38<dt><span class="section"><a href="interface.html#atomic.interface.interface_ipc">Atomic types for inter-process 39 communication</a></span></dt> 40<dt><span class="section"><a href="interface.html#atomic.interface.interface_fences">Fences</a></span></dt> 41<dt><span class="section"><a href="interface.html#atomic.interface.feature_macros">Feature testing macros</a></span></dt> 42</dl></div> 43<div class="section"> 44<div class="titlepage"><div><div><h3 class="title"> 45<a name="atomic.interface.configuration"></a><a class="link" href="interface.html#atomic.interface.configuration" title="Configuration and building">Configuration and building</a> 46</h3></div></div></div> 47<p> 48 The library contains header-only and compiled parts. The library is header-only 49 for lock-free cases but requires a separate binary to implement the lock-based 50 emulation and waiting and notifying operations on some platforms. Users are 51 able to detect whether linking to the compiled part is required by checking 52 the <a class="link" href="interface.html#atomic.interface.feature_macros" title="Feature testing macros">feature macros</a>. 53 </p> 54<p> 55 The following macros affect library behavior: 56 </p> 57<div class="informaltable"><table class="table"> 58<colgroup> 59<col> 60<col> 61</colgroup> 62<thead><tr> 63<th> 64 <p> 65 Macro 66 </p> 67 </th> 68<th> 69 <p> 70 Description 71 </p> 72 </th> 73</tr></thead> 74<tbody> 75<tr> 76<td> 77 <p> 78 <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_LOCK_POOL_SIZE_LOG2</span></code> 79 </p> 80 </td> 81<td> 82 <p> 83 Binary logarithm of the number of locks in the internal lock pool 84 used by <span class="bold"><strong>Boost.Atomic</strong></span> to implement 85 lock-based atomic operations and waiting and notifying operations 86 on some platforms. Must be an integer in range from 0 to 16, the 87 default value is 8. Only has effect when building <span class="bold"><strong>Boost.Atomic</strong></span>. 88 </p> 89 </td> 90</tr> 91<tr> 92<td> 93 <p> 94 <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_NO_CMPXCHG8B</span></code> 95 </p> 96 </td> 97<td> 98 <p> 99 Affects 32-bit x86 Oracle Studio builds. When defined, the library 100 assumes the target CPU does not support <code class="computeroutput"><span class="identifier">cmpxchg8b</span></code> 101 instruction used to support 64-bit atomic operations. This is the 102 case with very old CPUs (pre-Pentium). The library does not perform 103 runtime detection of this instruction, so running the code that 104 uses 64-bit atomics on such CPUs will result in crashes, unless 105 this macro is defined. Note that the macro does not affect MSVC, 106 GCC and compatible compilers because the library infers this information 107 from the compiler-defined macros. 108 </p> 109 </td> 110</tr> 111<tr> 112<td> 113 <p> 114 <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_NO_CMPXCHG16B</span></code> 115 </p> 116 </td> 117<td> 118 <p> 119 Affects 64-bit x86 MSVC and Oracle Studio builds. When defined, 120 the library assumes the target CPU does not support <code class="computeroutput"><span class="identifier">cmpxchg16b</span></code> instruction used to 121 support 128-bit atomic operations. This is the case with some early 122 64-bit AMD CPUs, all Intel CPUs and current AMD CPUs support this 123 instruction. The library does not perform runtime detection of 124 this instruction, so running the code that uses 128-bit atomics 125 on such CPUs will result in crashes, unless this macro is defined. 126 Note that the macro does not affect GCC and compatible compilers 127 because the library infers this information from the compiler-defined 128 macros. 129 </p> 130 </td> 131</tr> 132<tr> 133<td> 134 <p> 135 <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_NO_FLOATING_POINT</span></code> 136 </p> 137 </td> 138<td> 139 <p> 140 When defined, support for floating point operations is disabled. 141 Floating point types shall be treated similar to trivially copyable 142 structs and no capability macros will be defined. 143 </p> 144 </td> 145</tr> 146<tr> 147<td> 148 <p> 149 <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_FORCE_FALLBACK</span></code> 150 </p> 151 </td> 152<td> 153 <p> 154 When defined, all operations are implemented with locks. This is 155 mostly used for testing and should not be used in real world projects. 156 </p> 157 </td> 158</tr> 159<tr> 160<td> 161 <p> 162 <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_DYN_LINK</span></code> 163 and <code class="computeroutput"><span class="identifier">BOOST_ALL_DYN_LINK</span></code> 164 </p> 165 </td> 166<td> 167 <p> 168 Control library linking. If defined, the library assumes dynamic 169 linking, otherwise static. The latter macro affects all Boost libraries, 170 not just <span class="bold"><strong>Boost.Atomic</strong></span>. 171 </p> 172 </td> 173</tr> 174<tr> 175<td> 176 <p> 177 <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_NO_LIB</span></code> 178 and <code class="computeroutput"><span class="identifier">BOOST_ALL_NO_LIB</span></code> 179 </p> 180 </td> 181<td> 182 <p> 183 Control library auto-linking on Windows. When defined, disables 184 auto-linking. The latter macro affects all Boost libraries, not 185 just <span class="bold"><strong>Boost.Atomic</strong></span>. 186 </p> 187 </td> 188</tr> 189</tbody> 190</table></div> 191<p> 192 Besides macros, it is important to specify the correct compiler options for 193 the target CPU. With GCC and compatible compilers this affects whether particular 194 atomic operations are lock-free or not. 195 </p> 196<p> 197 Boost building process is described in the <a href="http://www.boost.org/doc/libs/release/more/getting_started/" target="_top">Getting 198 Started guide</a>. For example, you can build <span class="bold"><strong>Boost.Atomic</strong></span> 199 with the following command line: 200 </p> 201<pre class="programlisting">bjam --with-atomic variant=release instruction-set=core2 stage 202</pre> 203</div> 204<div class="section"> 205<div class="titlepage"><div><div><h3 class="title"> 206<a name="atomic.interface.interface_memory_order"></a><a class="link" href="interface.html#atomic.interface.interface_memory_order" title="Memory order">Memory order</a> 207</h3></div></div></div> 208<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">memory_order</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 209</pre> 210<p> 211 The enumeration <code class="literal">boost::memory_order</code> defines the following 212 values to represent memory ordering constraints: 213 </p> 214<div class="informaltable"><table class="table"> 215<colgroup> 216<col> 217<col> 218</colgroup> 219<thead><tr> 220<th> 221 <p> 222 Constant 223 </p> 224 </th> 225<th> 226 <p> 227 Description 228 </p> 229 </th> 230</tr></thead> 231<tbody> 232<tr> 233<td> 234 <p> 235 <code class="computeroutput"><span class="identifier">memory_order_relaxed</span></code> 236 </p> 237 </td> 238<td> 239 <p> 240 No ordering constraint. Informally speaking, following operations 241 may be reordered before, preceding operations may be reordered 242 after the atomic operation. This constraint is suitable only when 243 either a) further operations do not depend on the outcome of the 244 atomic operation or b) ordering is enforced through stand-alone 245 <code class="computeroutput"><span class="identifier">atomic_thread_fence</span></code> 246 operations. The operation on the atomic value itself is still atomic 247 though. 248 </p> 249 </td> 250</tr> 251<tr> 252<td> 253 <p> 254 <code class="computeroutput"><span class="identifier">memory_order_release</span></code> 255 </p> 256 </td> 257<td> 258 <p> 259 Perform <code class="computeroutput"><span class="identifier">release</span></code> 260 operation. Informally speaking, prevents all preceding memory operations 261 to be reordered past this point. 262 </p> 263 </td> 264</tr> 265<tr> 266<td> 267 <p> 268 <code class="computeroutput"><span class="identifier">memory_order_acquire</span></code> 269 </p> 270 </td> 271<td> 272 <p> 273 Perform <code class="computeroutput"><span class="identifier">acquire</span></code> 274 operation. Informally speaking, prevents succeeding memory operations 275 to be reordered before this point. 276 </p> 277 </td> 278</tr> 279<tr> 280<td> 281 <p> 282 <code class="computeroutput"><span class="identifier">memory_order_consume</span></code> 283 </p> 284 </td> 285<td> 286 <p> 287 Perform <code class="computeroutput"><span class="identifier">consume</span></code> 288 operation. More relaxed (and on some architectures potentially 289 more efficient) than <code class="computeroutput"><span class="identifier">memory_order_acquire</span></code> 290 as it only affects succeeding operations that are computationally-dependent 291 on the value retrieved from an atomic variable. Currently equivalent 292 to <code class="computeroutput"><span class="identifier">memory_order_acquire</span></code> 293 on all supported architectures (see <a class="link" href="limitations.html" title="Limitations">Limitations</a> 294 section for an explanation). 295 </p> 296 </td> 297</tr> 298<tr> 299<td> 300 <p> 301 <code class="computeroutput"><span class="identifier">memory_order_acq_rel</span></code> 302 </p> 303 </td> 304<td> 305 <p> 306 Perform both <code class="computeroutput"><span class="identifier">release</span></code> 307 and <code class="computeroutput"><span class="identifier">acquire</span></code> operation 308 </p> 309 </td> 310</tr> 311<tr> 312<td> 313 <p> 314 <code class="computeroutput"><span class="identifier">memory_order_seq_cst</span></code> 315 </p> 316 </td> 317<td> 318 <p> 319 Enforce sequential consistency. Implies <code class="computeroutput"><span class="identifier">memory_order_acq_rel</span></code>, 320 but additionally enforces total order for all operations such qualified. 321 </p> 322 </td> 323</tr> 324</tbody> 325</table></div> 326<p> 327 For compilers that support C++11 scoped enums, the library also defines scoped 328 synonyms that are preferred in modern programs: 329 </p> 330<div class="informaltable"><table class="table"> 331<colgroup> 332<col> 333<col> 334</colgroup> 335<thead><tr> 336<th> 337 <p> 338 Pre-C++11 constant 339 </p> 340 </th> 341<th> 342 <p> 343 C++11 equivalent 344 </p> 345 </th> 346</tr></thead> 347<tbody> 348<tr> 349<td> 350 <p> 351 <code class="computeroutput"><span class="identifier">memory_order_relaxed</span></code> 352 </p> 353 </td> 354<td> 355 <p> 356 <code class="computeroutput"><span class="identifier">memory_order</span><span class="special">::</span><span class="identifier">relaxed</span></code> 357 </p> 358 </td> 359</tr> 360<tr> 361<td> 362 <p> 363 <code class="computeroutput"><span class="identifier">memory_order_release</span></code> 364 </p> 365 </td> 366<td> 367 <p> 368 <code class="computeroutput"><span class="identifier">memory_order</span><span class="special">::</span><span class="identifier">release</span></code> 369 </p> 370 </td> 371</tr> 372<tr> 373<td> 374 <p> 375 <code class="computeroutput"><span class="identifier">memory_order_acquire</span></code> 376 </p> 377 </td> 378<td> 379 <p> 380 <code class="computeroutput"><span class="identifier">memory_order</span><span class="special">::</span><span class="identifier">acquire</span></code> 381 </p> 382 </td> 383</tr> 384<tr> 385<td> 386 <p> 387 <code class="computeroutput"><span class="identifier">memory_order_consume</span></code> 388 </p> 389 </td> 390<td> 391 <p> 392 <code class="computeroutput"><span class="identifier">memory_order</span><span class="special">::</span><span class="identifier">consume</span></code> 393 </p> 394 </td> 395</tr> 396<tr> 397<td> 398 <p> 399 <code class="computeroutput"><span class="identifier">memory_order_acq_rel</span></code> 400 </p> 401 </td> 402<td> 403 <p> 404 <code class="computeroutput"><span class="identifier">memory_order</span><span class="special">::</span><span class="identifier">acq_rel</span></code> 405 </p> 406 </td> 407</tr> 408<tr> 409<td> 410 <p> 411 <code class="computeroutput"><span class="identifier">memory_order_seq_cst</span></code> 412 </p> 413 </td> 414<td> 415 <p> 416 <code class="computeroutput"><span class="identifier">memory_order</span><span class="special">::</span><span class="identifier">seq_cst</span></code> 417 </p> 418 </td> 419</tr> 420</tbody> 421</table></div> 422<p> 423 See section <a class="link" href="thread_coordination.html" title="Thread coordination using Boost.Atomic"><span class="emphasis"><em>happens-before</em></span></a> 424 for explanation of the various ordering constraints. 425 </p> 426</div> 427<div class="section"> 428<div class="titlepage"><div><div><h3 class="title"> 429<a name="atomic.interface.interface_atomic_flag"></a><a class="link" href="interface.html#atomic.interface.interface_atomic_flag" title="Atomic flags">Atomic flags</a> 430</h3></div></div></div> 431<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">atomic</span><span class="special">/</span><span class="identifier">atomic_flag</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 432</pre> 433<p> 434 The <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic_flag</span></code> type provides the most basic 435 set of atomic operations suitable for implementing mutually exclusive access 436 to thread-shared data. The flag can have one of the two possible states: 437 set and clear. The class implements the following operations: 438 </p> 439<div class="informaltable"><table class="table"> 440<colgroup> 441<col> 442<col> 443</colgroup> 444<thead><tr> 445<th> 446 <p> 447 Syntax 448 </p> 449 </th> 450<th> 451 <p> 452 Description 453 </p> 454 </th> 455</tr></thead> 456<tbody> 457<tr> 458<td> 459 <p> 460 <code class="computeroutput"><span class="identifier">atomic_flag</span><span class="special">()</span></code> 461 </p> 462 </td> 463<td> 464 <p> 465 Initialize to the clear state. See the discussion below. 466 </p> 467 </td> 468</tr> 469<tr> 470<td> 471 <p> 472 <code class="computeroutput"><span class="keyword">bool</span> <span class="identifier">is_lock_free</span><span class="special">()</span></code> 473 </p> 474 </td> 475<td> 476 <p> 477 Checks if the atomic flag is lock-free; the returned value is consistent 478 with the <code class="computeroutput"><span class="identifier">is_always_lock_free</span></code> 479 static constant, see below. 480 </p> 481 </td> 482</tr> 483<tr> 484<td> 485 <p> 486 <code class="computeroutput"><span class="keyword">bool</span> <span class="identifier">has_native_wait_notify</span><span class="special">()</span></code> 487 </p> 488 </td> 489<td> 490 <p> 491 Indicates if the target platform natively supports waiting and 492 notifying operations for this object. Returns <code class="computeroutput"><span class="keyword">true</span></code> 493 if <code class="computeroutput"><span class="identifier">always_has_native_wait_notify</span></code> 494 is <code class="computeroutput"><span class="keyword">true</span></code>. 495 </p> 496 </td> 497</tr> 498<tr> 499<td> 500 <p> 501 <code class="computeroutput"><span class="keyword">bool</span> <span class="identifier">test</span><span class="special">(</span><span class="identifier">memory_order</span> 502 <span class="identifier">order</span><span class="special">)</span></code> 503 </p> 504 </td> 505<td> 506 <p> 507 Returns <code class="computeroutput"><span class="keyword">true</span></code> if the 508 flag is in the set state and <code class="computeroutput"><span class="keyword">false</span></code> 509 otherwise. 510 </p> 511 </td> 512</tr> 513<tr> 514<td> 515 <p> 516 <code class="computeroutput"><span class="keyword">bool</span> <span class="identifier">test_and_set</span><span class="special">(</span><span class="identifier">memory_order</span> 517 <span class="identifier">order</span><span class="special">)</span></code> 518 </p> 519 </td> 520<td> 521 <p> 522 Sets the atomic flag to the set state; returns <code class="computeroutput"><span class="keyword">true</span></code> 523 if the flag had been set prior to the operation. 524 </p> 525 </td> 526</tr> 527<tr> 528<td> 529 <p> 530 <code class="computeroutput"><span class="keyword">void</span> <span class="identifier">clear</span><span class="special">(</span><span class="identifier">memory_order</span> 531 <span class="identifier">order</span><span class="special">)</span></code> 532 </p> 533 </td> 534<td> 535 <p> 536 Sets the atomic flag to the clear state. 537 </p> 538 </td> 539</tr> 540<tr> 541<td> 542 <p> 543 <code class="computeroutput"><span class="keyword">bool</span> <span class="identifier">wait</span><span class="special">(</span><span class="keyword">bool</span> 544 <span class="identifier">old_val</span><span class="special">,</span> 545 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 546 </p> 547 </td> 548<td> 549 <p> 550 Potentially blocks the calling thread until unblocked by a notifying 551 operation and <code class="computeroutput"><span class="identifier">test</span><span class="special">(</span><span class="identifier">order</span><span class="special">)</span></code> returns value other than <code class="computeroutput"><span class="identifier">old_val</span></code>. Returns the result of 552 <code class="computeroutput"><span class="identifier">test</span><span class="special">(</span><span class="identifier">order</span><span class="special">)</span></code>. 553 </p> 554 </td> 555</tr> 556<tr> 557<td> 558 <p> 559 <code class="computeroutput"><span class="keyword">void</span> <span class="identifier">notify_one</span><span class="special">()</span></code> 560 </p> 561 </td> 562<td> 563 <p> 564 Unblocks at least one thread blocked in a waiting operation on 565 this atomic object. 566 </p> 567 </td> 568</tr> 569<tr> 570<td> 571 <p> 572 <code class="computeroutput"><span class="keyword">void</span> <span class="identifier">notify_all</span><span class="special">()</span></code> 573 </p> 574 </td> 575<td> 576 <p> 577 Unblocks all threads blocked in waiting operations on this atomic 578 object. 579 </p> 580 </td> 581</tr> 582<tr> 583<td> 584 <p> 585 <code class="computeroutput"><span class="keyword">static</span> <span class="keyword">constexpr</span> 586 <span class="keyword">bool</span> <span class="identifier">is_always_lock_free</span></code> 587 </p> 588 </td> 589<td> 590 <p> 591 This static boolean constant indicates if any atomic flag is lock-free 592 </p> 593 </td> 594</tr> 595<tr> 596<td> 597 <p> 598 <code class="computeroutput"><span class="keyword">static</span> <span class="keyword">constexpr</span> 599 <span class="keyword">bool</span> <span class="identifier">always_has_native_wait_notify</span></code> 600 </p> 601 </td> 602<td> 603 <p> 604 Indicates if the target platform always natively supports waiting 605 and notifying operations. 606 </p> 607 </td> 608</tr> 609</tbody> 610</table></div> 611<p> 612 <code class="computeroutput"><span class="identifier">order</span></code> always has <code class="computeroutput"><span class="identifier">memory_order_seq_cst</span></code> as default parameter. 613 </p> 614<p> 615 Waiting and notifying operations are described in detail in <a class="link" href="interface.html#atomic.interface.interface_wait_notify_ops" title="Waiting and notifying operations">this</a> 616 section. 617 </p> 618<p> 619 Note that the default constructor <code class="computeroutput"><span class="identifier">atomic_flag</span><span class="special">()</span></code> is unlike <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">atomic_flag</span></code>, 620 which leaves the default-constructed object uninitialized. This potentially 621 requires dynamic initialization during the program startup to perform the 622 object initialization, which makes it unsafe to create global <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic_flag</span></code> objects that can be used before 623 entring <code class="computeroutput"><span class="identifier">main</span><span class="special">()</span></code>. 624 Some compilers though (especially those supporting C++11 <code class="computeroutput"><span class="keyword">constexpr</span></code>) 625 may be smart enough to perform flag initialization statically (which is, 626 in C++11 terms, a constant initialization). 627 </p> 628<p> 629 This difference is deliberate and is done to support C++03 compilers. C++11 630 defines the <code class="computeroutput"><span class="identifier">ATOMIC_FLAG_INIT</span></code> 631 macro which can be used to statically initialize <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">atomic_flag</span></code> 632 to a clear state like this: 633 </p> 634<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">atomic_flag</span> <span class="identifier">flag</span> <span class="special">=</span> <span class="identifier">ATOMIC_FLAG_INIT</span><span class="special">;</span> <span class="comment">// constant initialization</span> 635</pre> 636<p> 637 This macro cannot be implemented in C++03 because for that <code class="computeroutput"><span class="identifier">atomic_flag</span></code> would have to be an aggregate 638 type, which it cannot be because it has to prohibit copying and consequently 639 define the default constructor. Thus the closest equivalent C++03 code using 640 <span class="bold"><strong>Boost.Atomic</strong></span> would be: 641 </p> 642<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic_flag</span> <span class="identifier">flag</span><span class="special">;</span> <span class="comment">// possibly, dynamic initialization in C++03;</span> 643 <span class="comment">// constant initialization in C++11</span> 644</pre> 645<p> 646 The same code is also valid in C++11, so this code can be used universally. 647 However, for interface parity with <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">atomic_flag</span></code>, 648 if possible, the library also defines the <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_FLAG_INIT</span></code> 649 macro, which is equivalent to <code class="computeroutput"><span class="identifier">ATOMIC_FLAG_INIT</span></code>: 650 </p> 651<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic_flag</span> <span class="identifier">flag</span> <span class="special">=</span> <span class="identifier">BOOST_ATOMIC_FLAG_INIT</span><span class="special">;</span> <span class="comment">// constant initialization</span> 652</pre> 653<p> 654 This macro will only be implemented on a C++11 compiler. When this macro 655 is not available, the library defines <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_NO_ATOMIC_FLAG_INIT</span></code>. 656 </p> 657</div> 658<div class="section"> 659<div class="titlepage"><div><div><h3 class="title"> 660<a name="atomic.interface.interface_atomic_object"></a><a class="link" href="interface.html#atomic.interface.interface_atomic_object" title="Atomic objects">Atomic objects</a> 661</h3></div></div></div> 662<div class="toc"><dl class="toc"> 663<dt><span class="section"><a href="interface.html#atomic.interface.interface_atomic_object.interface_atomic_generic"><code class="literal">boost::atomic<<span class="emphasis"><em>T</em></span>></code> 664 template class</a></span></dt> 665<dt><span class="section"><a href="interface.html#atomic.interface.interface_atomic_object.interface_atomic_integral"><code class="literal">boost::atomic<<span class="emphasis"><em>integral</em></span>></code> 666 template class</a></span></dt> 667<dt><span class="section"><a href="interface.html#atomic.interface.interface_atomic_object.interface_atomic_floating_point"><code class="literal">boost::atomic<<span class="emphasis"><em>floating-point</em></span>></code> 668 template class</a></span></dt> 669<dt><span class="section"><a href="interface.html#atomic.interface.interface_atomic_object.interface_atomic_pointer"><code class="literal">boost::atomic<<span class="emphasis"><em>pointer</em></span>></code> 670 template class</a></span></dt> 671<dt><span class="section"><a href="interface.html#atomic.interface.interface_atomic_object.interface_atomic_convenience_typedefs"><code class="literal">boost::atomic<<span class="emphasis"><em>T</em></span>></code> 672 convenience typedefs</a></span></dt> 673</dl></div> 674<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">atomic</span><span class="special">/</span><span class="identifier">atomic</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 675</pre> 676<p> 677 <code class="literal">boost::atomic<<span class="emphasis"><em>T</em></span>></code> provides methods 678 for atomically accessing variables of a suitable type <code class="literal"><span class="emphasis"><em>T</em></span></code>. 679 The type is suitable if it is <a href="https://en.cppreference.com/w/cpp/named_req/TriviallyCopyable" target="_top"><span class="emphasis"><em>trivially 680 copyable</em></span></a> (3.9/9 [basic.types]). Following are examples 681 of the types compatible with this requirement: 682 </p> 683<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 684<li class="listitem"> 685 a scalar type (e.g. integer, boolean, enum or pointer type) 686 </li> 687<li class="listitem"> 688 a <code class="literal">class</code> or <code class="literal">struct</code> that has no non-trivial 689 copy or move constructors or assignment operators, has a trivial destructor, 690 and that is comparable via <code class="literal">memcmp</code>. 691 </li> 692</ul></div> 693<p> 694 Note that classes with virtual functions or virtual base classes do not satisfy 695 the requirements. Also be warned that structures with padding bits may compare 696 non-equal via <code class="literal">memcmp</code> even though all members are equal. 697 This may also be the case with some floating point types, which include padding 698 bits themselves. 699 </p> 700<div class="note"><table border="0" summary="Note"> 701<tr> 702<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> 703<th align="left">Note</th> 704</tr> 705<tr><td align="left" valign="top"><p> 706 Although types with padding bits are generally not supported by the library, 707 <span class="bold"><strong>Boost.Atomic</strong></span> attempts to support operations 708 on floating point types on some platforms, where the location of the padding 709 bits is known. In particular, 80-bit <code class="computeroutput"><span class="keyword">long</span> 710 <span class="keyword">double</span></code> type on x86 targets is supported. 711 </p></td></tr> 712</table></div> 713<div class="section"> 714<div class="titlepage"><div><div><h4 class="title"> 715<a name="atomic.interface.interface_atomic_object.interface_atomic_generic"></a><a class="link" href="interface.html#atomic.interface.interface_atomic_object.interface_atomic_generic" title="boost::atomic<T> template class"><code class="literal">boost::atomic<<span class="emphasis"><em>T</em></span>></code> 716 template class</a> 717</h4></div></div></div> 718<p> 719 All atomic objects support the following operations and properties: 720 </p> 721<div class="informaltable"><table class="table"> 722<colgroup> 723<col> 724<col> 725</colgroup> 726<thead><tr> 727<th> 728 <p> 729 Syntax 730 </p> 731 </th> 732<th> 733 <p> 734 Description 735 </p> 736 </th> 737</tr></thead> 738<tbody> 739<tr> 740<td> 741 <p> 742 <code class="computeroutput"><span class="identifier">atomic</span><span class="special">()</span></code> 743 </p> 744 </td> 745<td> 746 <p> 747 Initialize to an unspecified value 748 </p> 749 </td> 750</tr> 751<tr> 752<td> 753 <p> 754 <code class="computeroutput"><span class="identifier">atomic</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">initial_value</span><span class="special">)</span></code> 755 </p> 756 </td> 757<td> 758 <p> 759 Initialize to <code class="literal">initial_value</code> 760 </p> 761 </td> 762</tr> 763<tr> 764<td> 765 <p> 766 <code class="computeroutput"><span class="keyword">bool</span> <span class="identifier">is_lock_free</span><span class="special">()</span></code> 767 </p> 768 </td> 769<td> 770 <p> 771 Checks if the atomic object is lock-free; the returned value 772 is consistent with the <code class="computeroutput"><span class="identifier">is_always_lock_free</span></code> 773 static constant, see below. 774 </p> 775 </td> 776</tr> 777<tr> 778<td> 779 <p> 780 <code class="computeroutput"><span class="keyword">bool</span> <span class="identifier">has_native_wait_notify</span><span class="special">()</span></code> 781 </p> 782 </td> 783<td> 784 <p> 785 Indicates if the target platform natively supports waiting and 786 notifying operations for this object. Returns <code class="computeroutput"><span class="keyword">true</span></code> 787 if <code class="computeroutput"><span class="identifier">always_has_native_wait_notify</span></code> 788 is <code class="computeroutput"><span class="keyword">true</span></code>. 789 </p> 790 </td> 791</tr> 792<tr> 793<td> 794 <p> 795 <code class="computeroutput"><span class="identifier">T</span><span class="special">&</span> 796 <span class="identifier">value</span><span class="special">()</span></code> 797 </p> 798 </td> 799<td> 800 <p> 801 Returns a reference to the value stored in the atomic object. 802 </p> 803 </td> 804</tr> 805<tr> 806<td> 807 <p> 808 <code class="computeroutput"><span class="identifier">T</span> <span class="identifier">load</span><span class="special">(</span><span class="identifier">memory_order</span> 809 <span class="identifier">order</span><span class="special">)</span></code> 810 </p> 811 </td> 812<td> 813 <p> 814 Return current value 815 </p> 816 </td> 817</tr> 818<tr> 819<td> 820 <p> 821 <code class="computeroutput"><span class="keyword">void</span> <span class="identifier">store</span><span class="special">(</span><span class="identifier">T</span> 822 <span class="identifier">value</span><span class="special">,</span> 823 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 824 </p> 825 </td> 826<td> 827 <p> 828 Write new value to atomic variable 829 </p> 830 </td> 831</tr> 832<tr> 833<td> 834 <p> 835 <code class="computeroutput"><span class="identifier">T</span> <span class="identifier">exchange</span><span class="special">(</span><span class="identifier">T</span> 836 <span class="identifier">new_value</span><span class="special">,</span> 837 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 838 </p> 839 </td> 840<td> 841 <p> 842 Exchange current value with <code class="computeroutput"><span class="identifier">new_value</span></code>, 843 returning current value 844 </p> 845 </td> 846</tr> 847<tr> 848<td> 849 <p> 850 <code class="computeroutput"><span class="keyword">bool</span> <span class="identifier">compare_exchange_weak</span><span class="special">(</span><span class="identifier">T</span> 851 <span class="special">&</span> <span class="identifier">expected</span><span class="special">,</span> <span class="identifier">T</span> 852 <span class="identifier">desired</span><span class="special">,</span> 853 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 854 </p> 855 </td> 856<td> 857 <p> 858 Compare current value with <code class="computeroutput"><span class="identifier">expected</span></code>, 859 change it to <code class="computeroutput"><span class="identifier">desired</span></code> 860 if matches. Returns <code class="computeroutput"><span class="keyword">true</span></code> 861 if an exchange has been performed, and always writes the previous 862 value back in <code class="computeroutput"><span class="identifier">expected</span></code>. 863 May fail spuriously, so must generally be retried in a loop. 864 </p> 865 </td> 866</tr> 867<tr> 868<td> 869 <p> 870 <code class="computeroutput"><span class="keyword">bool</span> <span class="identifier">compare_exchange_weak</span><span class="special">(</span><span class="identifier">T</span> 871 <span class="special">&</span> <span class="identifier">expected</span><span class="special">,</span> <span class="identifier">T</span> 872 <span class="identifier">desired</span><span class="special">,</span> 873 <span class="identifier">memory_order</span> <span class="identifier">success_order</span><span class="special">,</span> <span class="identifier">memory_order</span> 874 <span class="identifier">failure_order</span><span class="special">)</span></code> 875 </p> 876 </td> 877<td> 878 <p> 879 Compare current value with <code class="computeroutput"><span class="identifier">expected</span></code>, 880 change it to <code class="computeroutput"><span class="identifier">desired</span></code> 881 if matches. Returns <code class="computeroutput"><span class="keyword">true</span></code> 882 if an exchange has been performed, and always writes the previous 883 value back in <code class="computeroutput"><span class="identifier">expected</span></code>. 884 May fail spuriously, so must generally be retried in a loop. 885 </p> 886 </td> 887</tr> 888<tr> 889<td> 890 <p> 891 <code class="computeroutput"><span class="keyword">bool</span> <span class="identifier">compare_exchange_strong</span><span class="special">(</span><span class="identifier">T</span> 892 <span class="special">&</span> <span class="identifier">expected</span><span class="special">,</span> <span class="identifier">T</span> 893 <span class="identifier">desired</span><span class="special">,</span> 894 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 895 </p> 896 </td> 897<td> 898 <p> 899 Compare current value with <code class="computeroutput"><span class="identifier">expected</span></code>, 900 change it to <code class="computeroutput"><span class="identifier">desired</span></code> 901 if matches. Returns <code class="computeroutput"><span class="keyword">true</span></code> 902 if an exchange has been performed, and always writes the previous 903 value back in <code class="computeroutput"><span class="identifier">expected</span></code>. 904 </p> 905 </td> 906</tr> 907<tr> 908<td> 909 <p> 910 <code class="computeroutput"><span class="keyword">bool</span> <span class="identifier">compare_exchange_strong</span><span class="special">(</span><span class="identifier">T</span> 911 <span class="special">&</span> <span class="identifier">expected</span><span class="special">,</span> <span class="identifier">T</span> 912 <span class="identifier">desired</span><span class="special">,</span> 913 <span class="identifier">memory_order</span> <span class="identifier">success_order</span><span class="special">,</span> <span class="identifier">memory_order</span> 914 <span class="identifier">failure_order</span><span class="special">))</span></code> 915 </p> 916 </td> 917<td> 918 <p> 919 Compare current value with <code class="computeroutput"><span class="identifier">expected</span></code>, 920 change it to <code class="computeroutput"><span class="identifier">desired</span></code> 921 if matches. Returns <code class="computeroutput"><span class="keyword">true</span></code> 922 if an exchange has been performed, and always writes the previous 923 value back in <code class="computeroutput"><span class="identifier">expected</span></code>. 924 </p> 925 </td> 926</tr> 927<tr> 928<td> 929 <p> 930 <code class="computeroutput"><span class="identifier">T</span> <span class="identifier">wait</span><span class="special">(</span><span class="identifier">T</span> 931 <span class="identifier">old_val</span><span class="special">,</span> 932 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 933 </p> 934 </td> 935<td> 936 <p> 937 Potentially blocks the calling thread until unblocked by a notifying 938 operation and <code class="computeroutput"><span class="identifier">load</span><span class="special">(</span><span class="identifier">order</span><span class="special">)</span></code> returns value other than <code class="computeroutput"><span class="identifier">old_val</span></code>. Returns the result 939 of <code class="computeroutput"><span class="identifier">load</span><span class="special">(</span><span class="identifier">order</span><span class="special">)</span></code>. 940 </p> 941 </td> 942</tr> 943<tr> 944<td> 945 <p> 946 <code class="computeroutput"><span class="keyword">void</span> <span class="identifier">notify_one</span><span class="special">()</span></code> 947 </p> 948 </td> 949<td> 950 <p> 951 Unblocks at least one thread blocked in a waiting operation on 952 this atomic object. 953 </p> 954 </td> 955</tr> 956<tr> 957<td> 958 <p> 959 <code class="computeroutput"><span class="keyword">void</span> <span class="identifier">notify_all</span><span class="special">()</span></code> 960 </p> 961 </td> 962<td> 963 <p> 964 Unblocks all threads blocked in waiting operations on this atomic 965 object. 966 </p> 967 </td> 968</tr> 969<tr> 970<td> 971 <p> 972 <code class="computeroutput"><span class="keyword">static</span> <span class="keyword">constexpr</span> 973 <span class="keyword">bool</span> <span class="identifier">is_always_lock_free</span></code> 974 </p> 975 </td> 976<td> 977 <p> 978 This static boolean constant indicates if any atomic object of 979 this type is lock-free 980 </p> 981 </td> 982</tr> 983<tr> 984<td> 985 <p> 986 <code class="computeroutput"><span class="keyword">static</span> <span class="keyword">constexpr</span> 987 <span class="keyword">bool</span> <span class="identifier">always_has_native_wait_notify</span></code> 988 </p> 989 </td> 990<td> 991 <p> 992 Indicates if the target platform always natively supports waiting 993 and notifying operations. 994 </p> 995 </td> 996</tr> 997</tbody> 998</table></div> 999<p> 1000 <code class="computeroutput"><span class="identifier">order</span></code> always has <code class="computeroutput"><span class="identifier">memory_order_seq_cst</span></code> as default parameter. 1001 </p> 1002<p> 1003 Waiting and notifying operations are described in detail in <a class="link" href="interface.html#atomic.interface.interface_wait_notify_ops" title="Waiting and notifying operations">this</a> 1004 section. 1005 </p> 1006<p> 1007 The <code class="computeroutput"><span class="identifier">value</span></code> operation is 1008 a <span class="bold"><strong>Boost.Atomic</strong></span> extension. The returned 1009 reference can be used to invoke external operations on the atomic value, 1010 which are not part of <span class="bold"><strong>Boost.Atomic</strong></span> but 1011 are compatible with it on the target architecture. The primary example 1012 of such is <code class="computeroutput"><span class="identifier">futex</span></code> and similar 1013 operations available on some systems. The returned reference must not be 1014 used for reading or modifying the value of the atomic object in non-atomic 1015 manner, or to construct <a class="link" href="interface.html#atomic.interface.interface_atomic_ref" title="Atomic references">atomic 1016 references</a>. Doing so does not guarantee atomicity or memory ordering. 1017 </p> 1018<div class="note"><table border="0" summary="Note"> 1019<tr> 1020<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> 1021<th align="left">Note</th> 1022</tr> 1023<tr><td align="left" valign="top"><p> 1024 Even if <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic</span></code> for a given type is lock-free, 1025 an atomic reference for that type may not be. Therefore, <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic</span></code> and <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic_ref</span></code> 1026 operating on the same object may use different thread synchronization 1027 primitives incompatible with each other. 1028 </p></td></tr> 1029</table></div> 1030<p> 1031 The <code class="computeroutput"><span class="identifier">compare_exchange_weak</span></code>/<code class="computeroutput"><span class="identifier">compare_exchange_strong</span></code> variants taking 1032 four parameters differ from the three parameter variants in that they allow 1033 a different memory ordering constraint to be specified in case the operation 1034 fails. 1035 </p> 1036<p> 1037 In addition to these explicit operations, each <code class="literal">atomic<<span class="emphasis"><em>T</em></span>></code> 1038 object also supports implicit <code class="literal">store</code> and <code class="literal">load</code> 1039 through the use of "assignment" and "conversion to <code class="literal">T</code>" 1040 operators. Avoid using these operators, as they do not allow to specify 1041 a memory ordering constraint which always defaults to <code class="computeroutput"><span class="identifier">memory_order_seq_cst</span></code>. 1042 </p> 1043</div> 1044<div class="section"> 1045<div class="titlepage"><div><div><h4 class="title"> 1046<a name="atomic.interface.interface_atomic_object.interface_atomic_integral"></a><a class="link" href="interface.html#atomic.interface.interface_atomic_object.interface_atomic_integral" title="boost::atomic<integral> template class"><code class="literal">boost::atomic<<span class="emphasis"><em>integral</em></span>></code> 1047 template class</a> 1048</h4></div></div></div> 1049<p> 1050 In addition to the operations listed in the previous section, <code class="literal">boost::atomic<<span class="emphasis"><em>I</em></span>></code> 1051 for integral types <code class="literal"><span class="emphasis"><em>I</em></span></code>, except <code class="computeroutput"><span class="keyword">bool</span></code>, supports the following operations, 1052 which correspond to <code class="literal">std::atomic<<span class="emphasis"><em>I</em></span>></code>: 1053 </p> 1054<div class="informaltable"><table class="table"> 1055<colgroup> 1056<col> 1057<col> 1058</colgroup> 1059<thead><tr> 1060<th> 1061 <p> 1062 Syntax 1063 </p> 1064 </th> 1065<th> 1066 <p> 1067 Description 1068 </p> 1069 </th> 1070</tr></thead> 1071<tbody> 1072<tr> 1073<td> 1074 <p> 1075 <code class="computeroutput"><span class="identifier">I</span> <span class="identifier">fetch_add</span><span class="special">(</span><span class="identifier">I</span> 1076 <span class="identifier">v</span><span class="special">,</span> 1077 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1078 </p> 1079 </td> 1080<td> 1081 <p> 1082 Add <code class="computeroutput"><span class="identifier">v</span></code> to variable, 1083 returning previous value 1084 </p> 1085 </td> 1086</tr> 1087<tr> 1088<td> 1089 <p> 1090 <code class="computeroutput"><span class="identifier">I</span> <span class="identifier">fetch_sub</span><span class="special">(</span><span class="identifier">I</span> 1091 <span class="identifier">v</span><span class="special">,</span> 1092 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1093 </p> 1094 </td> 1095<td> 1096 <p> 1097 Subtract <code class="computeroutput"><span class="identifier">v</span></code> from 1098 variable, returning previous value 1099 </p> 1100 </td> 1101</tr> 1102<tr> 1103<td> 1104 <p> 1105 <code class="computeroutput"><span class="identifier">I</span> <span class="identifier">fetch_and</span><span class="special">(</span><span class="identifier">I</span> 1106 <span class="identifier">v</span><span class="special">,</span> 1107 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1108 </p> 1109 </td> 1110<td> 1111 <p> 1112 Apply bit-wise "and" with <code class="computeroutput"><span class="identifier">v</span></code> 1113 to variable, returning previous value 1114 </p> 1115 </td> 1116</tr> 1117<tr> 1118<td> 1119 <p> 1120 <code class="computeroutput"><span class="identifier">I</span> <span class="identifier">fetch_or</span><span class="special">(</span><span class="identifier">I</span> 1121 <span class="identifier">v</span><span class="special">,</span> 1122 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1123 </p> 1124 </td> 1125<td> 1126 <p> 1127 Apply bit-wise "or" with <code class="computeroutput"><span class="identifier">v</span></code> 1128 to variable, returning previous value 1129 </p> 1130 </td> 1131</tr> 1132<tr> 1133<td> 1134 <p> 1135 <code class="computeroutput"><span class="identifier">I</span> <span class="identifier">fetch_xor</span><span class="special">(</span><span class="identifier">I</span> 1136 <span class="identifier">v</span><span class="special">,</span> 1137 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1138 </p> 1139 </td> 1140<td> 1141 <p> 1142 Apply bit-wise "xor" with <code class="computeroutput"><span class="identifier">v</span></code> 1143 to variable, returning previous value 1144 </p> 1145 </td> 1146</tr> 1147</tbody> 1148</table></div> 1149<p> 1150 Additionally, as a <span class="bold"><strong>Boost.Atomic</strong></span> extension, 1151 the following operations are also provided: 1152 </p> 1153<div class="informaltable"><table class="table"> 1154<colgroup> 1155<col> 1156<col> 1157</colgroup> 1158<thead><tr> 1159<th> 1160 <p> 1161 Syntax 1162 </p> 1163 </th> 1164<th> 1165 <p> 1166 Description 1167 </p> 1168 </th> 1169</tr></thead> 1170<tbody> 1171<tr> 1172<td> 1173 <p> 1174 <code class="computeroutput"><span class="identifier">I</span> <span class="identifier">fetch_negate</span><span class="special">(</span><span class="identifier">memory_order</span> 1175 <span class="identifier">order</span><span class="special">)</span></code> 1176 </p> 1177 </td> 1178<td> 1179 <p> 1180 Change the sign of the value stored in the variable, returning 1181 previous value 1182 </p> 1183 </td> 1184</tr> 1185<tr> 1186<td> 1187 <p> 1188 <code class="computeroutput"><span class="identifier">I</span> <span class="identifier">fetch_complement</span><span class="special">(</span><span class="identifier">memory_order</span> 1189 <span class="identifier">order</span><span class="special">)</span></code> 1190 </p> 1191 </td> 1192<td> 1193 <p> 1194 Set the variable to the one's complement of the current value, 1195 returning previous value 1196 </p> 1197 </td> 1198</tr> 1199<tr> 1200<td> 1201 <p> 1202 <code class="computeroutput"><span class="identifier">I</span> <span class="identifier">negate</span><span class="special">(</span><span class="identifier">memory_order</span> 1203 <span class="identifier">order</span><span class="special">)</span></code> 1204 </p> 1205 </td> 1206<td> 1207 <p> 1208 Change the sign of the value stored in the variable, returning 1209 the result 1210 </p> 1211 </td> 1212</tr> 1213<tr> 1214<td> 1215 <p> 1216 <code class="computeroutput"><span class="identifier">I</span> <span class="identifier">add</span><span class="special">(</span><span class="identifier">I</span> 1217 <span class="identifier">v</span><span class="special">,</span> 1218 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1219 </p> 1220 </td> 1221<td> 1222 <p> 1223 Add <code class="computeroutput"><span class="identifier">v</span></code> to variable, 1224 returning the result 1225 </p> 1226 </td> 1227</tr> 1228<tr> 1229<td> 1230 <p> 1231 <code class="computeroutput"><span class="identifier">I</span> <span class="identifier">sub</span><span class="special">(</span><span class="identifier">I</span> 1232 <span class="identifier">v</span><span class="special">,</span> 1233 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1234 </p> 1235 </td> 1236<td> 1237 <p> 1238 Subtract <code class="computeroutput"><span class="identifier">v</span></code> from 1239 variable, returning the result 1240 </p> 1241 </td> 1242</tr> 1243<tr> 1244<td> 1245 <p> 1246 <code class="computeroutput"><span class="identifier">I</span> <span class="identifier">bitwise_and</span><span class="special">(</span><span class="identifier">I</span> 1247 <span class="identifier">v</span><span class="special">,</span> 1248 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1249 </p> 1250 </td> 1251<td> 1252 <p> 1253 Apply bit-wise "and" with <code class="computeroutput"><span class="identifier">v</span></code> 1254 to variable, returning the result 1255 </p> 1256 </td> 1257</tr> 1258<tr> 1259<td> 1260 <p> 1261 <code class="computeroutput"><span class="identifier">I</span> <span class="identifier">bitwise_or</span><span class="special">(</span><span class="identifier">I</span> 1262 <span class="identifier">v</span><span class="special">,</span> 1263 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1264 </p> 1265 </td> 1266<td> 1267 <p> 1268 Apply bit-wise "or" with <code class="computeroutput"><span class="identifier">v</span></code> 1269 to variable, returning the result 1270 </p> 1271 </td> 1272</tr> 1273<tr> 1274<td> 1275 <p> 1276 <code class="computeroutput"><span class="identifier">I</span> <span class="identifier">bitwise_xor</span><span class="special">(</span><span class="identifier">I</span> 1277 <span class="identifier">v</span><span class="special">,</span> 1278 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1279 </p> 1280 </td> 1281<td> 1282 <p> 1283 Apply bit-wise "xor" with <code class="computeroutput"><span class="identifier">v</span></code> 1284 to variable, returning the result 1285 </p> 1286 </td> 1287</tr> 1288<tr> 1289<td> 1290 <p> 1291 <code class="computeroutput"><span class="identifier">I</span> <span class="identifier">bitwise_complement</span><span class="special">(</span><span class="identifier">memory_order</span> 1292 <span class="identifier">order</span><span class="special">)</span></code> 1293 </p> 1294 </td> 1295<td> 1296 <p> 1297 Set the variable to the one's complement of the current value, 1298 returning the result 1299 </p> 1300 </td> 1301</tr> 1302<tr> 1303<td> 1304 <p> 1305 <code class="computeroutput"><span class="keyword">void</span> <span class="identifier">opaque_negate</span><span class="special">(</span><span class="identifier">memory_order</span> 1306 <span class="identifier">order</span><span class="special">)</span></code> 1307 </p> 1308 </td> 1309<td> 1310 <p> 1311 Change the sign of the value stored in the variable, returning 1312 nothing 1313 </p> 1314 </td> 1315</tr> 1316<tr> 1317<td> 1318 <p> 1319 <code class="computeroutput"><span class="keyword">void</span> <span class="identifier">opaque_add</span><span class="special">(</span><span class="identifier">I</span> 1320 <span class="identifier">v</span><span class="special">,</span> 1321 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1322 </p> 1323 </td> 1324<td> 1325 <p> 1326 Add <code class="computeroutput"><span class="identifier">v</span></code> to variable, 1327 returning nothing 1328 </p> 1329 </td> 1330</tr> 1331<tr> 1332<td> 1333 <p> 1334 <code class="computeroutput"><span class="keyword">void</span> <span class="identifier">opaque_sub</span><span class="special">(</span><span class="identifier">I</span> 1335 <span class="identifier">v</span><span class="special">,</span> 1336 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1337 </p> 1338 </td> 1339<td> 1340 <p> 1341 Subtract <code class="computeroutput"><span class="identifier">v</span></code> from 1342 variable, returning nothing 1343 </p> 1344 </td> 1345</tr> 1346<tr> 1347<td> 1348 <p> 1349 <code class="computeroutput"><span class="keyword">void</span> <span class="identifier">opaque_and</span><span class="special">(</span><span class="identifier">I</span> 1350 <span class="identifier">v</span><span class="special">,</span> 1351 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1352 </p> 1353 </td> 1354<td> 1355 <p> 1356 Apply bit-wise "and" with <code class="computeroutput"><span class="identifier">v</span></code> 1357 to variable, returning nothing 1358 </p> 1359 </td> 1360</tr> 1361<tr> 1362<td> 1363 <p> 1364 <code class="computeroutput"><span class="keyword">void</span> <span class="identifier">opaque_or</span><span class="special">(</span><span class="identifier">I</span> 1365 <span class="identifier">v</span><span class="special">,</span> 1366 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1367 </p> 1368 </td> 1369<td> 1370 <p> 1371 Apply bit-wise "or" with <code class="computeroutput"><span class="identifier">v</span></code> 1372 to variable, returning nothing 1373 </p> 1374 </td> 1375</tr> 1376<tr> 1377<td> 1378 <p> 1379 <code class="computeroutput"><span class="keyword">void</span> <span class="identifier">opaque_xor</span><span class="special">(</span><span class="identifier">I</span> 1380 <span class="identifier">v</span><span class="special">,</span> 1381 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1382 </p> 1383 </td> 1384<td> 1385 <p> 1386 Apply bit-wise "xor" with <code class="computeroutput"><span class="identifier">v</span></code> 1387 to variable, returning nothing 1388 </p> 1389 </td> 1390</tr> 1391<tr> 1392<td> 1393 <p> 1394 <code class="computeroutput"><span class="keyword">void</span> <span class="identifier">opaque_complement</span><span class="special">(</span><span class="identifier">memory_order</span> 1395 <span class="identifier">order</span><span class="special">)</span></code> 1396 </p> 1397 </td> 1398<td> 1399 <p> 1400 Set the variable to the one's complement of the current value, 1401 returning nothing 1402 </p> 1403 </td> 1404</tr> 1405<tr> 1406<td> 1407 <p> 1408 <code class="computeroutput"><span class="keyword">bool</span> <span class="identifier">negate_and_test</span><span class="special">(</span><span class="identifier">memory_order</span> 1409 <span class="identifier">order</span><span class="special">)</span></code> 1410 </p> 1411 </td> 1412<td> 1413 <p> 1414 Change the sign of the value stored in the variable, returning 1415 <code class="computeroutput"><span class="keyword">true</span></code> if the result 1416 is non-zero and <code class="computeroutput"><span class="keyword">false</span></code> 1417 otherwise 1418 </p> 1419 </td> 1420</tr> 1421<tr> 1422<td> 1423 <p> 1424 <code class="computeroutput"><span class="keyword">bool</span> <span class="identifier">add_and_test</span><span class="special">(</span><span class="identifier">I</span> 1425 <span class="identifier">v</span><span class="special">,</span> 1426 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1427 </p> 1428 </td> 1429<td> 1430 <p> 1431 Add <code class="computeroutput"><span class="identifier">v</span></code> to variable, 1432 returning <code class="computeroutput"><span class="keyword">true</span></code> if 1433 the result is non-zero and <code class="computeroutput"><span class="keyword">false</span></code> 1434 otherwise 1435 </p> 1436 </td> 1437</tr> 1438<tr> 1439<td> 1440 <p> 1441 <code class="computeroutput"><span class="keyword">bool</span> <span class="identifier">sub_and_test</span><span class="special">(</span><span class="identifier">I</span> 1442 <span class="identifier">v</span><span class="special">,</span> 1443 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1444 </p> 1445 </td> 1446<td> 1447 <p> 1448 Subtract <code class="computeroutput"><span class="identifier">v</span></code> from 1449 variable, returning <code class="computeroutput"><span class="keyword">true</span></code> 1450 if the result is non-zero and <code class="computeroutput"><span class="keyword">false</span></code> 1451 otherwise 1452 </p> 1453 </td> 1454</tr> 1455<tr> 1456<td> 1457 <p> 1458 <code class="computeroutput"><span class="keyword">bool</span> <span class="identifier">and_and_test</span><span class="special">(</span><span class="identifier">I</span> 1459 <span class="identifier">v</span><span class="special">,</span> 1460 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1461 </p> 1462 </td> 1463<td> 1464 <p> 1465 Apply bit-wise "and" with <code class="computeroutput"><span class="identifier">v</span></code> 1466 to variable, returning <code class="computeroutput"><span class="keyword">true</span></code> 1467 if the result is non-zero and <code class="computeroutput"><span class="keyword">false</span></code> 1468 otherwise 1469 </p> 1470 </td> 1471</tr> 1472<tr> 1473<td> 1474 <p> 1475 <code class="computeroutput"><span class="keyword">bool</span> <span class="identifier">or_and_test</span><span class="special">(</span><span class="identifier">I</span> 1476 <span class="identifier">v</span><span class="special">,</span> 1477 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1478 </p> 1479 </td> 1480<td> 1481 <p> 1482 Apply bit-wise "or" with <code class="computeroutput"><span class="identifier">v</span></code> 1483 to variable, returning <code class="computeroutput"><span class="keyword">true</span></code> 1484 if the result is non-zero and <code class="computeroutput"><span class="keyword">false</span></code> 1485 otherwise 1486 </p> 1487 </td> 1488</tr> 1489<tr> 1490<td> 1491 <p> 1492 <code class="computeroutput"><span class="keyword">bool</span> <span class="identifier">xor_and_test</span><span class="special">(</span><span class="identifier">I</span> 1493 <span class="identifier">v</span><span class="special">,</span> 1494 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1495 </p> 1496 </td> 1497<td> 1498 <p> 1499 Apply bit-wise "xor" with <code class="computeroutput"><span class="identifier">v</span></code> 1500 to variable, returning <code class="computeroutput"><span class="keyword">true</span></code> 1501 if the result is non-zero and <code class="computeroutput"><span class="keyword">false</span></code> 1502 otherwise 1503 </p> 1504 </td> 1505</tr> 1506<tr> 1507<td> 1508 <p> 1509 <code class="computeroutput"><span class="keyword">bool</span> <span class="identifier">complement_and_test</span><span class="special">(</span><span class="identifier">memory_order</span> 1510 <span class="identifier">order</span><span class="special">)</span></code> 1511 </p> 1512 </td> 1513<td> 1514 <p> 1515 Set the variable to the one's complement of the current value, 1516 returning <code class="computeroutput"><span class="keyword">true</span></code> if 1517 the result is non-zero and <code class="computeroutput"><span class="keyword">false</span></code> 1518 otherwise 1519 </p> 1520 </td> 1521</tr> 1522<tr> 1523<td> 1524 <p> 1525 <code class="computeroutput"><span class="keyword">bool</span> <span class="identifier">bit_test_and_set</span><span class="special">(</span><span class="keyword">unsigned</span> 1526 <span class="keyword">int</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">memory_order</span> 1527 <span class="identifier">order</span><span class="special">)</span></code> 1528 </p> 1529 </td> 1530<td> 1531 <p> 1532 Set bit number <code class="computeroutput"><span class="identifier">n</span></code> 1533 in the variable to 1, returning <code class="computeroutput"><span class="keyword">true</span></code> 1534 if the bit was previously set to 1 and <code class="computeroutput"><span class="keyword">false</span></code> 1535 otherwise 1536 </p> 1537 </td> 1538</tr> 1539<tr> 1540<td> 1541 <p> 1542 <code class="computeroutput"><span class="keyword">bool</span> <span class="identifier">bit_test_and_reset</span><span class="special">(</span><span class="keyword">unsigned</span> 1543 <span class="keyword">int</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">memory_order</span> 1544 <span class="identifier">order</span><span class="special">)</span></code> 1545 </p> 1546 </td> 1547<td> 1548 <p> 1549 Set bit number <code class="computeroutput"><span class="identifier">n</span></code> 1550 in the variable to 0, returning <code class="computeroutput"><span class="keyword">true</span></code> 1551 if the bit was previously set to 1 and <code class="computeroutput"><span class="keyword">false</span></code> 1552 otherwise 1553 </p> 1554 </td> 1555</tr> 1556<tr> 1557<td> 1558 <p> 1559 <code class="computeroutput"><span class="keyword">bool</span> <span class="identifier">bit_test_and_complement</span><span class="special">(</span><span class="keyword">unsigned</span> 1560 <span class="keyword">int</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">memory_order</span> 1561 <span class="identifier">order</span><span class="special">)</span></code> 1562 </p> 1563 </td> 1564<td> 1565 <p> 1566 Change bit number <code class="computeroutput"><span class="identifier">n</span></code> 1567 in the variable to the opposite value, returning <code class="computeroutput"><span class="keyword">true</span></code> if the bit was previously 1568 set to 1 and <code class="computeroutput"><span class="keyword">false</span></code> 1569 otherwise 1570 </p> 1571 </td> 1572</tr> 1573</tbody> 1574</table></div> 1575<div class="note"><table border="0" summary="Note"> 1576<tr> 1577<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> 1578<th align="left">Note</th> 1579</tr> 1580<tr><td align="left" valign="top"><p> 1581 In <span class="bold"><strong>Boost.Atomic</strong></span> 1.66 the <code class="literal"><span class="emphasis"><em>op</em></span>_and_test</code> 1582 operations returned the opposite value (i.e. <code class="computeroutput"><span class="keyword">true</span></code> 1583 if the result is zero). This was changed to the current behavior in 1.67 1584 for consistency with other operations in <span class="bold"><strong>Boost.Atomic</strong></span>, 1585 as well as with conventions taken in the C++ standard library. <span class="bold"><strong>Boost.Atomic</strong></span> 1.66 was the only release shipped 1586 with the old behavior. 1587 </p></td></tr> 1588</table></div> 1589<p> 1590 <code class="computeroutput"><span class="identifier">order</span></code> always has <code class="computeroutput"><span class="identifier">memory_order_seq_cst</span></code> as default parameter. 1591 </p> 1592<p> 1593 The <code class="literal">opaque_<span class="emphasis"><em>op</em></span></code> and <code class="literal"><span class="emphasis"><em>op</em></span>_and_test</code> 1594 variants of the operations may result in a more efficient code on some 1595 architectures because the original value of the atomic variable is not 1596 preserved. In the <code class="literal">bit_test_and_<span class="emphasis"><em>op</em></span></code> 1597 operations, the bit number <code class="computeroutput"><span class="identifier">n</span></code> 1598 starts from 0, which means the least significand bit, and must not exceed 1599 <code class="literal">std::numeric_limits<<span class="emphasis"><em>I</em></span>>::digits - 1</code>. 1600 </p> 1601<p> 1602 In addition to these explicit operations, each <code class="literal">boost::atomic<<span class="emphasis"><em>I</em></span>></code> 1603 object also supports implicit pre-/post- increment/decrement, as well as 1604 the operators <code class="computeroutput"><span class="special">+=</span></code>, <code class="computeroutput"><span class="special">-=</span></code>, <code class="computeroutput"><span class="special">&=</span></code>, 1605 <code class="computeroutput"><span class="special">|=</span></code> and <code class="computeroutput"><span class="special">^=</span></code>. 1606 Avoid using these operators, as they do not allow to specify a memory ordering 1607 constraint which always defaults to <code class="computeroutput"><span class="identifier">memory_order_seq_cst</span></code>. 1608 </p> 1609</div> 1610<div class="section"> 1611<div class="titlepage"><div><div><h4 class="title"> 1612<a name="atomic.interface.interface_atomic_object.interface_atomic_floating_point"></a><a class="link" href="interface.html#atomic.interface.interface_atomic_object.interface_atomic_floating_point" title="boost::atomic<floating-point> template class"><code class="literal">boost::atomic<<span class="emphasis"><em>floating-point</em></span>></code> 1613 template class</a> 1614</h4></div></div></div> 1615<div class="note"><table border="0" summary="Note"> 1616<tr> 1617<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> 1618<th align="left">Note</th> 1619</tr> 1620<tr><td align="left" valign="top"><p> 1621 The support for floating point types is optional and can be disabled 1622 by defining <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_NO_FLOATING_POINT</span></code>. 1623 </p></td></tr> 1624</table></div> 1625<p> 1626 In addition to the operations applicable to all atomic objects, <code class="literal">boost::atomic<<span class="emphasis"><em>F</em></span>></code> 1627 for floating point types <code class="literal"><span class="emphasis"><em>F</em></span></code> supports 1628 the following operations, which correspond to <code class="literal">std::atomic<<span class="emphasis"><em>F</em></span>></code>: 1629 </p> 1630<div class="informaltable"><table class="table"> 1631<colgroup> 1632<col> 1633<col> 1634</colgroup> 1635<thead><tr> 1636<th> 1637 <p> 1638 Syntax 1639 </p> 1640 </th> 1641<th> 1642 <p> 1643 Description 1644 </p> 1645 </th> 1646</tr></thead> 1647<tbody> 1648<tr> 1649<td> 1650 <p> 1651 <code class="computeroutput"><span class="identifier">F</span> <span class="identifier">fetch_add</span><span class="special">(</span><span class="identifier">F</span> 1652 <span class="identifier">v</span><span class="special">,</span> 1653 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1654 </p> 1655 </td> 1656<td> 1657 <p> 1658 Add <code class="computeroutput"><span class="identifier">v</span></code> to variable, 1659 returning previous value 1660 </p> 1661 </td> 1662</tr> 1663<tr> 1664<td> 1665 <p> 1666 <code class="computeroutput"><span class="identifier">F</span> <span class="identifier">fetch_sub</span><span class="special">(</span><span class="identifier">F</span> 1667 <span class="identifier">v</span><span class="special">,</span> 1668 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1669 </p> 1670 </td> 1671<td> 1672 <p> 1673 Subtract <code class="computeroutput"><span class="identifier">v</span></code> from 1674 variable, returning previous value 1675 </p> 1676 </td> 1677</tr> 1678</tbody> 1679</table></div> 1680<p> 1681 Additionally, as a <span class="bold"><strong>Boost.Atomic</strong></span> extension, 1682 the following operations are also provided: 1683 </p> 1684<div class="informaltable"><table class="table"> 1685<colgroup> 1686<col> 1687<col> 1688</colgroup> 1689<thead><tr> 1690<th> 1691 <p> 1692 Syntax 1693 </p> 1694 </th> 1695<th> 1696 <p> 1697 Description 1698 </p> 1699 </th> 1700</tr></thead> 1701<tbody> 1702<tr> 1703<td> 1704 <p> 1705 <code class="computeroutput"><span class="identifier">F</span> <span class="identifier">fetch_negate</span><span class="special">(</span><span class="identifier">memory_order</span> 1706 <span class="identifier">order</span><span class="special">)</span></code> 1707 </p> 1708 </td> 1709<td> 1710 <p> 1711 Change the sign of the value stored in the variable, returning 1712 previous value 1713 </p> 1714 </td> 1715</tr> 1716<tr> 1717<td> 1718 <p> 1719 <code class="computeroutput"><span class="identifier">F</span> <span class="identifier">negate</span><span class="special">(</span><span class="identifier">memory_order</span> 1720 <span class="identifier">order</span><span class="special">)</span></code> 1721 </p> 1722 </td> 1723<td> 1724 <p> 1725 Change the sign of the value stored in the variable, returning 1726 the result 1727 </p> 1728 </td> 1729</tr> 1730<tr> 1731<td> 1732 <p> 1733 <code class="computeroutput"><span class="identifier">F</span> <span class="identifier">add</span><span class="special">(</span><span class="identifier">F</span> 1734 <span class="identifier">v</span><span class="special">,</span> 1735 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1736 </p> 1737 </td> 1738<td> 1739 <p> 1740 Add <code class="computeroutput"><span class="identifier">v</span></code> to variable, 1741 returning the result 1742 </p> 1743 </td> 1744</tr> 1745<tr> 1746<td> 1747 <p> 1748 <code class="computeroutput"><span class="identifier">F</span> <span class="identifier">sub</span><span class="special">(</span><span class="identifier">F</span> 1749 <span class="identifier">v</span><span class="special">,</span> 1750 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1751 </p> 1752 </td> 1753<td> 1754 <p> 1755 Subtract <code class="computeroutput"><span class="identifier">v</span></code> from 1756 variable, returning the result 1757 </p> 1758 </td> 1759</tr> 1760<tr> 1761<td> 1762 <p> 1763 <code class="computeroutput"><span class="keyword">void</span> <span class="identifier">opaque_negate</span><span class="special">(</span><span class="identifier">memory_order</span> 1764 <span class="identifier">order</span><span class="special">)</span></code> 1765 </p> 1766 </td> 1767<td> 1768 <p> 1769 Change the sign of the value stored in the variable, returning 1770 nothing 1771 </p> 1772 </td> 1773</tr> 1774<tr> 1775<td> 1776 <p> 1777 <code class="computeroutput"><span class="keyword">void</span> <span class="identifier">opaque_add</span><span class="special">(</span><span class="identifier">F</span> 1778 <span class="identifier">v</span><span class="special">,</span> 1779 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1780 </p> 1781 </td> 1782<td> 1783 <p> 1784 Add <code class="computeroutput"><span class="identifier">v</span></code> to variable, 1785 returning nothing 1786 </p> 1787 </td> 1788</tr> 1789<tr> 1790<td> 1791 <p> 1792 <code class="computeroutput"><span class="keyword">void</span> <span class="identifier">opaque_sub</span><span class="special">(</span><span class="identifier">F</span> 1793 <span class="identifier">v</span><span class="special">,</span> 1794 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1795 </p> 1796 </td> 1797<td> 1798 <p> 1799 Subtract <code class="computeroutput"><span class="identifier">v</span></code> from 1800 variable, returning nothing 1801 </p> 1802 </td> 1803</tr> 1804</tbody> 1805</table></div> 1806<p> 1807 <code class="computeroutput"><span class="identifier">order</span></code> always has <code class="computeroutput"><span class="identifier">memory_order_seq_cst</span></code> as default parameter. 1808 </p> 1809<p> 1810 The <code class="literal">opaque_<span class="emphasis"><em>op</em></span></code> variants of the operations 1811 may result in a more efficient code on some architectures because the original 1812 value of the atomic variable is not preserved. 1813 </p> 1814<p> 1815 In addition to these explicit operations, each <code class="literal">boost::atomic<<span class="emphasis"><em>F</em></span>></code> 1816 object also supports operators <code class="computeroutput"><span class="special">+=</span></code> 1817 and <code class="computeroutput"><span class="special">-=</span></code>. Avoid using these 1818 operators, as they do not allow to specify a memory ordering constraint 1819 which always defaults to <code class="computeroutput"><span class="identifier">memory_order_seq_cst</span></code>. 1820 </p> 1821<p> 1822 When using atomic operations with floating point types, bear in mind that 1823 <span class="bold"><strong>Boost.Atomic</strong></span> always performs bitwise comparison 1824 of the stored values. This means that operations like <code class="computeroutput"><span class="identifier">compare_exchange</span><span class="special">*</span></code> may fail if the stored value and comparand 1825 have different binary representation, even if they would normally compare 1826 equal. This is typically the case when either of the numbers is <a href="https://en.wikipedia.org/wiki/Denormal_number" target="_top">denormalized</a>. 1827 This also means that the behavior with regard to special floating point 1828 values like NaN and signed zero is also different from normal C++. 1829 </p> 1830<p> 1831 Another source of the problem is padding bits that are added to some floating 1832 point types for alignment. One widespread example of that is Intel x87 1833 extended double format, which is typically stored as 80 bits of value padded 1834 with 16 or 48 unused bits. These padding bits are often uninitialized and 1835 contain garbage, which makes two equal numbers have different binary representation. 1836 The library attempts to account for the known such cases, but in general 1837 it is possible that some platforms are not covered. Note that the C++ standard 1838 makes no guarantees about reliability of <code class="computeroutput"><span class="identifier">compare_exchange</span><span class="special">*</span></code> operations in the face of padding or trap 1839 bits. 1840 </p> 1841</div> 1842<div class="section"> 1843<div class="titlepage"><div><div><h4 class="title"> 1844<a name="atomic.interface.interface_atomic_object.interface_atomic_pointer"></a><a class="link" href="interface.html#atomic.interface.interface_atomic_object.interface_atomic_pointer" title="boost::atomic<pointer> template class"><code class="literal">boost::atomic<<span class="emphasis"><em>pointer</em></span>></code> 1845 template class</a> 1846</h4></div></div></div> 1847<p> 1848 In addition to the operations applicable to all atomic objects, <code class="literal">boost::atomic<<span class="emphasis"><em>P</em></span>></code> 1849 for pointer types <code class="literal"><span class="emphasis"><em>P</em></span></code> (other than 1850 pointers to <code class="literal">void</code>, function or member pointers) support 1851 the following operations, which correspond to <code class="literal">std::atomic<<span class="emphasis"><em>P</em></span>></code>: 1852 </p> 1853<div class="informaltable"><table class="table"> 1854<colgroup> 1855<col> 1856<col> 1857</colgroup> 1858<thead><tr> 1859<th> 1860 <p> 1861 Syntax 1862 </p> 1863 </th> 1864<th> 1865 <p> 1866 Description 1867 </p> 1868 </th> 1869</tr></thead> 1870<tbody> 1871<tr> 1872<td> 1873 <p> 1874 <code class="computeroutput"><span class="identifier">T</span> <span class="identifier">fetch_add</span><span class="special">(</span><span class="identifier">ptrdiff_t</span> 1875 <span class="identifier">v</span><span class="special">,</span> 1876 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1877 </p> 1878 </td> 1879<td> 1880 <p> 1881 Add <code class="computeroutput"><span class="identifier">v</span></code> to variable, 1882 returning previous value 1883 </p> 1884 </td> 1885</tr> 1886<tr> 1887<td> 1888 <p> 1889 <code class="computeroutput"><span class="identifier">T</span> <span class="identifier">fetch_sub</span><span class="special">(</span><span class="identifier">ptrdiff_t</span> 1890 <span class="identifier">v</span><span class="special">,</span> 1891 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1892 </p> 1893 </td> 1894<td> 1895 <p> 1896 Subtract <code class="computeroutput"><span class="identifier">v</span></code> from 1897 variable, returning previous value 1898 </p> 1899 </td> 1900</tr> 1901</tbody> 1902</table></div> 1903<p> 1904 Similarly to integers, the following <span class="bold"><strong>Boost.Atomic</strong></span> 1905 extensions are also provided: 1906 </p> 1907<div class="informaltable"><table class="table"> 1908<colgroup> 1909<col> 1910<col> 1911</colgroup> 1912<thead><tr> 1913<th> 1914 <p> 1915 Syntax 1916 </p> 1917 </th> 1918<th> 1919 <p> 1920 Description 1921 </p> 1922 </th> 1923</tr></thead> 1924<tbody> 1925<tr> 1926<td> 1927 <p> 1928 <code class="computeroutput"><span class="keyword">void</span> <span class="identifier">add</span><span class="special">(</span><span class="identifier">ptrdiff_t</span> 1929 <span class="identifier">v</span><span class="special">,</span> 1930 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1931 </p> 1932 </td> 1933<td> 1934 <p> 1935 Add <code class="computeroutput"><span class="identifier">v</span></code> to variable, 1936 returning the result 1937 </p> 1938 </td> 1939</tr> 1940<tr> 1941<td> 1942 <p> 1943 <code class="computeroutput"><span class="keyword">void</span> <span class="identifier">sub</span><span class="special">(</span><span class="identifier">ptrdiff_t</span> 1944 <span class="identifier">v</span><span class="special">,</span> 1945 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1946 </p> 1947 </td> 1948<td> 1949 <p> 1950 Subtract <code class="computeroutput"><span class="identifier">v</span></code> from 1951 variable, returning the result 1952 </p> 1953 </td> 1954</tr> 1955<tr> 1956<td> 1957 <p> 1958 <code class="computeroutput"><span class="keyword">void</span> <span class="identifier">opaque_add</span><span class="special">(</span><span class="identifier">ptrdiff_t</span> 1959 <span class="identifier">v</span><span class="special">,</span> 1960 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1961 </p> 1962 </td> 1963<td> 1964 <p> 1965 Add <code class="computeroutput"><span class="identifier">v</span></code> to variable, 1966 returning nothing 1967 </p> 1968 </td> 1969</tr> 1970<tr> 1971<td> 1972 <p> 1973 <code class="computeroutput"><span class="keyword">void</span> <span class="identifier">opaque_sub</span><span class="special">(</span><span class="identifier">ptrdiff_t</span> 1974 <span class="identifier">v</span><span class="special">,</span> 1975 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1976 </p> 1977 </td> 1978<td> 1979 <p> 1980 Subtract <code class="computeroutput"><span class="identifier">v</span></code> from 1981 variable, returning nothing 1982 </p> 1983 </td> 1984</tr> 1985<tr> 1986<td> 1987 <p> 1988 <code class="computeroutput"><span class="keyword">bool</span> <span class="identifier">add_and_test</span><span class="special">(</span><span class="identifier">ptrdiff_t</span> 1989 <span class="identifier">v</span><span class="special">,</span> 1990 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 1991 </p> 1992 </td> 1993<td> 1994 <p> 1995 Add <code class="computeroutput"><span class="identifier">v</span></code> to variable, 1996 returning <code class="computeroutput"><span class="keyword">true</span></code> if 1997 the result is non-null and <code class="computeroutput"><span class="keyword">false</span></code> 1998 otherwise 1999 </p> 2000 </td> 2001</tr> 2002<tr> 2003<td> 2004 <p> 2005 <code class="computeroutput"><span class="keyword">bool</span> <span class="identifier">sub_and_test</span><span class="special">(</span><span class="identifier">ptrdiff_t</span> 2006 <span class="identifier">v</span><span class="special">,</span> 2007 <span class="identifier">memory_order</span> <span class="identifier">order</span><span class="special">)</span></code> 2008 </p> 2009 </td> 2010<td> 2011 <p> 2012 Subtract <code class="computeroutput"><span class="identifier">v</span></code> from 2013 variable, returning <code class="computeroutput"><span class="keyword">true</span></code> 2014 if the result is non-null and <code class="computeroutput"><span class="keyword">false</span></code> 2015 otherwise 2016 </p> 2017 </td> 2018</tr> 2019</tbody> 2020</table></div> 2021<p> 2022 <code class="computeroutput"><span class="identifier">order</span></code> always has <code class="computeroutput"><span class="identifier">memory_order_seq_cst</span></code> as default parameter. 2023 </p> 2024<p> 2025 In addition to these explicit operations, each <code class="literal">boost::atomic<<span class="emphasis"><em>P</em></span>></code> 2026 object also supports implicit pre-/post- increment/decrement, as well as 2027 the operators <code class="computeroutput"><span class="special">+=</span></code>, <code class="computeroutput"><span class="special">-=</span></code>. Avoid using these operators, as they 2028 do not allow explicit specification of a memory ordering constraint which 2029 always defaults to <code class="computeroutput"><span class="identifier">memory_order_seq_cst</span></code>. 2030 </p> 2031</div> 2032<div class="section"> 2033<div class="titlepage"><div><div><h4 class="title"> 2034<a name="atomic.interface.interface_atomic_object.interface_atomic_convenience_typedefs"></a><a class="link" href="interface.html#atomic.interface.interface_atomic_object.interface_atomic_convenience_typedefs" title="boost::atomic<T> convenience typedefs"><code class="literal">boost::atomic<<span class="emphasis"><em>T</em></span>></code> 2035 convenience typedefs</a> 2036</h4></div></div></div> 2037<p> 2038 For convenience, the following shorthand typedefs of <code class="literal">boost::atomic<<span class="emphasis"><em>T</em></span>></code> 2039 are provided: 2040 </p> 2041<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="keyword">char</span> <span class="special">></span> <span class="identifier">atomic_char</span><span class="special">;</span> 2042<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="keyword">unsigned</span> <span class="keyword">char</span> <span class="special">></span> <span class="identifier">atomic_uchar</span><span class="special">;</span> 2043<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="keyword">signed</span> <span class="keyword">char</span> <span class="special">></span> <span class="identifier">atomic_schar</span><span class="special">;</span> 2044<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="keyword">unsigned</span> <span class="keyword">short</span> <span class="special">></span> <span class="identifier">atomic_ushort</span><span class="special">;</span> 2045<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="keyword">short</span> <span class="special">></span> <span class="identifier">atomic_short</span><span class="special">;</span> 2046<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="special">></span> <span class="identifier">atomic_uint</span><span class="special">;</span> 2047<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="keyword">int</span> <span class="special">></span> <span class="identifier">atomic_int</span><span class="special">;</span> 2048<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="keyword">unsigned</span> <span class="keyword">long</span> <span class="special">></span> <span class="identifier">atomic_ulong</span><span class="special">;</span> 2049<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="keyword">long</span> <span class="special">></span> <span class="identifier">atomic_long</span><span class="special">;</span> 2050<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="keyword">unsigned</span> <span class="keyword">long</span> <span class="keyword">long</span> <span class="special">></span> <span class="identifier">atomic_ullong</span><span class="special">;</span> 2051<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="keyword">long</span> <span class="keyword">long</span> <span class="special">></span> <span class="identifier">atomic_llong</span><span class="special">;</span> 2052 2053<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="keyword">void</span><span class="special">*</span> <span class="special">></span> <span class="identifier">atomic_address</span><span class="special">;</span> 2054<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="keyword">bool</span> <span class="special">></span> <span class="identifier">atomic_bool</span><span class="special">;</span> 2055<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="keyword">wchar_t</span> <span class="special">></span> <span class="identifier">atomic_wchar_t</span><span class="special">;</span> 2056<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="identifier">char8_t</span> <span class="special">></span> <span class="identifier">atomic_char8_t</span><span class="special">;</span> 2057<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="keyword">char16_t</span> <span class="special">></span> <span class="identifier">atomic_char16_t</span><span class="special">;</span> 2058<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="keyword">char32_t</span> <span class="special">></span> <span class="identifier">atomic_char32_t</span><span class="special">;</span> 2059 2060<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="identifier">uint8_t</span> <span class="special">></span> <span class="identifier">atomic_uint8_t</span><span class="special">;</span> 2061<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="identifier">int8_t</span> <span class="special">></span> <span class="identifier">atomic_int8_t</span><span class="special">;</span> 2062<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="identifier">uint16_t</span> <span class="special">></span> <span class="identifier">atomic_uint16_t</span><span class="special">;</span> 2063<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="identifier">int16_t</span> <span class="special">></span> <span class="identifier">atomic_int16_t</span><span class="special">;</span> 2064<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="identifier">uint32_t</span> <span class="special">></span> <span class="identifier">atomic_uint32_t</span><span class="special">;</span> 2065<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="identifier">int32_t</span> <span class="special">></span> <span class="identifier">atomic_int32_t</span><span class="special">;</span> 2066<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="identifier">uint64_t</span> <span class="special">></span> <span class="identifier">atomic_uint64_t</span><span class="special">;</span> 2067<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="identifier">int64_t</span> <span class="special">></span> <span class="identifier">atomic_int64_t</span><span class="special">;</span> 2068 2069<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="identifier">int_least8_t</span> <span class="special">></span> <span class="identifier">atomic_int_least8_t</span><span class="special">;</span> 2070<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="identifier">uint_least8_t</span> <span class="special">></span> <span class="identifier">atomic_uint_least8_t</span><span class="special">;</span> 2071<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="identifier">int_least16_t</span> <span class="special">></span> <span class="identifier">atomic_int_least16_t</span><span class="special">;</span> 2072<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="identifier">uint_least16_t</span> <span class="special">></span> <span class="identifier">atomic_uint_least16_t</span><span class="special">;</span> 2073<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="identifier">int_least32_t</span> <span class="special">></span> <span class="identifier">atomic_int_least32_t</span><span class="special">;</span> 2074<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="identifier">uint_least32_t</span> <span class="special">></span> <span class="identifier">atomic_uint_least32_t</span><span class="special">;</span> 2075<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="identifier">int_least64_t</span> <span class="special">></span> <span class="identifier">atomic_int_least64_t</span><span class="special">;</span> 2076<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="identifier">uint_least64_t</span> <span class="special">></span> <span class="identifier">atomic_uint_least64_t</span><span class="special">;</span> 2077<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="identifier">int_fast8_t</span> <span class="special">></span> <span class="identifier">atomic_int_fast8_t</span><span class="special">;</span> 2078<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="identifier">uint_fast8_t</span> <span class="special">></span> <span class="identifier">atomic_uint_fast8_t</span><span class="special">;</span> 2079<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="identifier">int_fast16_t</span> <span class="special">></span> <span class="identifier">atomic_int_fast16_t</span><span class="special">;</span> 2080<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="identifier">uint_fast16_t</span> <span class="special">></span> <span class="identifier">atomic_uint_fast16_t</span><span class="special">;</span> 2081<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="identifier">int_fast32_t</span> <span class="special">></span> <span class="identifier">atomic_int_fast32_t</span><span class="special">;</span> 2082<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="identifier">uint_fast32_t</span> <span class="special">></span> <span class="identifier">atomic_uint_fast32_t</span><span class="special">;</span> 2083<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="identifier">int_fast64_t</span> <span class="special">></span> <span class="identifier">atomic_int_fast64_t</span><span class="special">;</span> 2084<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="identifier">uint_fast64_t</span> <span class="special">></span> <span class="identifier">atomic_uint_fast64_t</span><span class="special">;</span> 2085<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="identifier">intmax_t</span> <span class="special">></span> <span class="identifier">atomic_intmax_t</span><span class="special">;</span> 2086<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="identifier">uintmax_t</span> <span class="special">></span> <span class="identifier">atomic_uintmax_t</span><span class="special">;</span> 2087 2088<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="special">></span> <span class="identifier">atomic_size_t</span><span class="special">;</span> 2089<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ptrdiff_t</span> <span class="special">></span> <span class="identifier">atomic_ptrdiff_t</span><span class="special">;</span> 2090 2091<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="identifier">intptr_t</span> <span class="special">></span> <span class="identifier">atomic_intptr_t</span><span class="special">;</span> 2092<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="identifier">uintptr_t</span> <span class="special">></span> <span class="identifier">atomic_uintptr_t</span><span class="special">;</span> 2093 2094<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="keyword">unsigned</span> <span class="identifier">integral</span> <span class="special">></span> <span class="identifier">atomic_unsigned_lock_free</span><span class="special">;</span> 2095<span class="keyword">typedef</span> <span class="identifier">atomic</span><span class="special"><</span> <span class="keyword">signed</span> <span class="identifier">integral</span> <span class="special">></span> <span class="identifier">atomic_signed_lock_free</span><span class="special">;</span> 2096</pre> 2097<p> 2098 The typedefs are provided only if the corresponding value type is available. 2099 </p> 2100<p> 2101 The <code class="computeroutput"><span class="identifier">atomic_unsigned_lock_free</span></code> 2102 and <code class="computeroutput"><span class="identifier">atomic_signed_lock_free</span></code> 2103 types, if defined, indicate the atomic object type for an unsigned or signed 2104 integer, respectively, that is lock-free and that preferably has native 2105 support for <a class="link" href="interface.html#atomic.interface.interface_wait_notify_ops" title="Waiting and notifying operations">waiting 2106 and notifying operations</a>. 2107 </p> 2108</div> 2109</div> 2110<div class="section"> 2111<div class="titlepage"><div><div><h3 class="title"> 2112<a name="atomic.interface.interface_atomic_ref"></a><a class="link" href="interface.html#atomic.interface.interface_atomic_ref" title="Atomic references">Atomic references</a> 2113</h3></div></div></div> 2114<div class="toc"><dl class="toc"><dt><span class="section"><a href="interface.html#atomic.interface.interface_atomic_ref.caveats">Caveats</a></span></dt></dl></div> 2115<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">atomic</span><span class="special">/</span><span class="identifier">atomic_ref</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 2116</pre> 2117<p> 2118 <code class="literal">boost::atomic_ref<<span class="emphasis"><em>T</em></span>></code> also provides 2119 methods for atomically accessing external variables of type <code class="literal"><span class="emphasis"><em>T</em></span></code>. 2120 The requirements on the type <code class="literal"><span class="emphasis"><em>T</em></span></code> are 2121 the same as those imposed by <a class="link" href="interface.html#atomic.interface.interface_atomic_object" title="Atomic objects"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic</span></code></a>. Unlike <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic</span></code>, 2122 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic_ref</span></code> does not store the value internally 2123 and only refers to an external object of type <code class="literal"><span class="emphasis"><em>T</em></span></code>. 2124 </p> 2125<p> 2126 There are certain requirements on the objects compatible with <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic_ref</span></code>: 2127 </p> 2128<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 2129<li class="listitem"> 2130 The referenced object lifetime must not end before the last <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic_ref</span></code> referencing the object is 2131 destroyed. 2132 </li> 2133<li class="listitem"> 2134 The referenced object must have alignment not less than indicated by 2135 the <code class="literal">boost::atomic_ref<<span class="emphasis"><em>T</em></span>>::required_alignment</code> 2136 constant. That constant may be larger than the natural alignment of type 2137 <code class="literal"><span class="emphasis"><em>T</em></span></code>. In <span class="bold"><strong>Boost.Atomic</strong></span>, 2138 <code class="computeroutput"><span class="identifier">required_alignment</span></code> indicates 2139 the alignment at which operations on the object are lock-free; otherwise, 2140 if lock-free operations are not possible, <code class="computeroutput"><span class="identifier">required_alignment</span></code> 2141 shall not be less than the natural alignment of <code class="literal"><span class="emphasis"><em>T</em></span></code>. 2142 </li> 2143<li class="listitem"> 2144 The referenced object must not be a <a href="https://en.cppreference.com/w/cpp/language/object#Subobjects" target="_top"><span class="emphasis"><em>potentially 2145 overlapping object</em></span></a>. It must be the <span class="emphasis"><em>most 2146 derived object</em></span> (that is it must not be a base class subobject 2147 of an object of a derived class) and it must not be marked with the 2148 <code class="computeroutput"><span class="special">[[</span><span class="identifier">no_unique_address</span><span class="special">]]</span></code> attribute. 2149<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">Base</span> 2150<span class="special">{</span> 2151 <span class="keyword">short</span> <span class="identifier">a</span><span class="special">;</span> 2152 <span class="keyword">char</span> <span class="identifier">b</span><span class="special">;</span> 2153<span class="special">};</span> 2154 2155<span class="keyword">struct</span> <span class="identifier">Derived</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">Base</span> 2156<span class="special">{</span> 2157 <span class="keyword">char</span> <span class="identifier">c</span><span class="special">;</span> 2158<span class="special">};</span> 2159 2160<span class="identifier">Derived</span> <span class="identifier">x</span><span class="special">;</span> 2161<span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic_ref</span><span class="special"><</span><span class="identifier">Base</span><span class="special">></span> <span class="identifier">ref</span><span class="special">(</span><span class="identifier">x</span><span class="special">);</span> <span class="comment">// bad</span> 2162</pre> 2163 In the above example, <code class="computeroutput"><span class="identifier">ref</span></code> 2164 may silently corrupt the value of <code class="computeroutput"><span class="identifier">x</span><span class="special">.</span><span class="identifier">c</span></code> 2165 because it resides in the trailing padding of the <code class="computeroutput"><span class="identifier">Base</span></code> 2166 base class subobject of <code class="computeroutput"><span class="identifier">x</span></code>. 2167 </li> 2168<li class="listitem"> 2169 The referenced object must not reside in read-only memory. Even for non-modifying 2170 operations, like <code class="computeroutput"><span class="identifier">load</span><span class="special">()</span></code>, <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic_ref</span></code> 2171 may issue read-modify-write CPU instructions that require write access. 2172 </li> 2173<li class="listitem"> 2174 While at least one <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic_ref</span></code> 2175 referencing an object exists, that object must not be accessed by any 2176 other means, other than through <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic_ref</span></code>. 2177 </li> 2178</ul></div> 2179<p> 2180 Multiple <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic_ref</span></code> referencing the same object 2181 are allowed, and operations through any such reference are atomic and ordered 2182 with regard to each other, according to the memory order arguments. <code class="literal">boost::atomic_ref<<span class="emphasis"><em>T</em></span>></code> 2183 supports the same set of properties and operations as <code class="literal">boost::atomic<<span class="emphasis"><em>T</em></span>></code>, 2184 depending on the type <code class="literal"><span class="emphasis"><em>T</em></span></code>, with the 2185 following exceptions: 2186 </p> 2187<div class="informaltable"><table class="table"> 2188<colgroup> 2189<col> 2190<col> 2191</colgroup> 2192<thead><tr> 2193<th> 2194 <p> 2195 Syntax 2196 </p> 2197 </th> 2198<th> 2199 <p> 2200 Description 2201 </p> 2202 </th> 2203</tr></thead> 2204<tbody> 2205<tr> 2206<td> 2207 <p> 2208 <code class="computeroutput"><span class="identifier">atomic_ref</span><span class="special">()</span> 2209 <span class="special">=</span> <span class="keyword">delete</span></code> 2210 </p> 2211 </td> 2212<td> 2213 <p> 2214 <code class="computeroutput"><span class="identifier">atomic_ref</span></code> is not 2215 default-constructible. 2216 </p> 2217 </td> 2218</tr> 2219<tr> 2220<td> 2221 <p> 2222 <code class="computeroutput"><span class="identifier">atomic_ref</span><span class="special">(</span><span class="identifier">T</span><span class="special">&</span> 2223 <span class="identifier">object</span><span class="special">)</span></code> 2224 </p> 2225 </td> 2226<td> 2227 <p> 2228 Creates an atomic reference, referring to <code class="computeroutput"><span class="identifier">object</span></code>. 2229 May modify the object representation (see caveats below). 2230 </p> 2231 </td> 2232</tr> 2233<tr> 2234<td> 2235 <p> 2236 <code class="computeroutput"><span class="identifier">atomic_ref</span><span class="special">(</span><span class="identifier">atomic_ref</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">that</span><span class="special">)</span> <span class="keyword">noexcept</span></code> 2237 </p> 2238 </td> 2239<td> 2240 <p> 2241 Creates an atomic reference, referencing the object referred to 2242 by <code class="computeroutput"><span class="identifier">that</span></code>. 2243 </p> 2244 </td> 2245</tr> 2246<tr> 2247<td> 2248 <p> 2249 <code class="computeroutput"><span class="keyword">static</span> <span class="keyword">constexpr</span> 2250 <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">required_alignment</span></code> 2251 </p> 2252 </td> 2253<td> 2254 <p> 2255 A constant, indicating required alignment of objects of type <code class="literal"><span class="emphasis"><em>T</em></span></code> 2256 so that they are compatible with <code class="computeroutput"><span class="identifier">atomic_ref</span></code>. 2257 Shall not be less than <code class="literal">alignof(<span class="emphasis"><em>T</em></span>)</code>. 2258 In <span class="bold"><strong>Boost.Atomic</strong></span>, indicates the 2259 alignment required by lock-free operations on the referenced object, 2260 if lock-free operations are possible. 2261 </p> 2262 </td> 2263</tr> 2264</tbody> 2265</table></div> 2266<p> 2267 Note that <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic_ref</span></code> cannot be changed to refer to 2268 a different object after construction. Assigning to <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic_ref</span></code> 2269 will invoke an atomic operation of storing the new value to the referenced 2270 object. 2271 </p> 2272<div class="section"> 2273<div class="titlepage"><div><div><h4 class="title"> 2274<a name="atomic.interface.interface_atomic_ref.caveats"></a><a class="link" href="interface.html#atomic.interface.interface_atomic_ref.caveats" title="Caveats">Caveats</a> 2275</h4></div></div></div> 2276<p> 2277 There are a several disadvantages of using <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic_ref</span></code> 2278 compared to <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic</span></code>. 2279 </p> 2280<p> 2281 First, the user is required to maintain proper alignment of the referenced 2282 objects. This means that the user has to plan beforehand which variables 2283 will require atomic access in the program. In C++11 and later, the user 2284 can ensure the required alignment by applying <code class="computeroutput"><span class="keyword">alignas</span></code> 2285 specifier: 2286 </p> 2287<pre class="programlisting"><span class="keyword">alignas</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic_ref</span><span class="special"><</span><span class="keyword">int</span><span class="special">>::</span><span class="identifier">required_alignment</span><span class="special">)</span> 2288<span class="keyword">int</span> <span class="identifier">atomic_int</span><span class="special">;</span> 2289</pre> 2290<p> 2291 On compilers that don't support <code class="computeroutput"><span class="keyword">alignas</span></code> 2292 users have to use compiler-specific attributes or manual padding to achieve 2293 the required alignment. <a href="https://www.boost.org/doc/libs/release/libs/config/doc/html/boost_config/boost_macro_reference.html#boost_config.boost_macro_reference.macros_that_allow_use_of_c__11_features_with_c__03_compilers" target="_top"><code class="computeroutput"><span class="identifier">BOOST_ALIGNMENT</span></code></a> macro from <span class="bold"><strong>Boost.Config</strong></span> may be useful. 2294 </p> 2295<div class="note"><table border="0" summary="Note"> 2296<tr> 2297<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> 2298<th align="left">Note</th> 2299</tr> 2300<tr><td align="left" valign="top"><p> 2301 Do not rely on compilers to enforce the natural alignment for fundamental 2302 types, and that the default alignment will satisfy the <code class="computeroutput"><span class="identifier">atomic_ref</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="identifier">required_alignment</span></code> constraint. There 2303 are real world cases when the default alignment is below the required 2304 alignment for atomic references. For example, on 32-bit x86 targets it 2305 is common that 64-bit integers and floating point numbers have alignment 2306 of 4, which is not high enough for <code class="computeroutput"><span class="identifier">atomic_ref</span></code>. 2307 Users must always explicitly ensure the referenced objects are aligned 2308 to <code class="computeroutput"><span class="identifier">atomic_ref</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="identifier">required_alignment</span></code>. 2309 </p></td></tr> 2310</table></div> 2311<p> 2312 Next, some types may have padding bits, which are the bits of object representation 2313 that do not contribute to the object value. Typically, padding bits are 2314 used for alignment purposes. <span class="bold"><strong>Boost.Atomic</strong></span> 2315 does not support types with padding bits, with an exception of floating 2316 point types on platforms where the location of the padding bits is known 2317 at compile time. One notable example is <code class="computeroutput"><span class="keyword">long</span> 2318 <span class="keyword">double</span></code> on x86, where the value is 2319 represented by an <a href="https://en.wikipedia.org/wiki/Extended_precision#x86_extended_precision_format" target="_top">80-bit 2320 extended precision</a> floating point number complemented by 2 to 6 2321 bytes of padding, depending on the target ABI. 2322 </p> 2323<p> 2324 Padding bits pose a problem for <span class="bold"><strong>Boost.Atomic</strong></span> 2325 because they can break binary comparison of object (as if by <code class="computeroutput"><span class="identifier">memcmp</span></code>), which is used in <code class="computeroutput"><span class="identifier">compare_exchange_weak</span></code>/<code class="computeroutput"><span class="identifier">compare_exchange_strong</span></code> 2326 operations. <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic</span></code> manages the internal object representation 2327 and in some cases, like the mentioned <code class="computeroutput"><span class="keyword">long</span> 2328 <span class="keyword">double</span></code> example, it is able to initialize 2329 the padding bits so that binary comparison yields the expected result. 2330 This is not possible with <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic_ref</span></code> 2331 because the referenced object is initialized by external means and any 2332 particular content in the padding bits cannot be guaranteed. This requires 2333 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic_ref</span></code> to initialize padding bits 2334 on construction. Since there may be other atomic references referring to 2335 the same object, this initialization must be atomic. As a result, <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic_ref</span></code> construction can be relatively 2336 expensive and may potentially disrupt atomic operations that are being 2337 performed on the same object through other atomic references. It is recommended 2338 to avoid constructing <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic_ref</span></code> 2339 in tight loops or hot paths. 2340 </p> 2341<p> 2342 Finally, target platform may not have the necessary means to implement 2343 atomic operations on objects of some sizes. For example, on many hardware 2344 architectures atomic operations on the following structure are not possible: 2345 </p> 2346<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">rgb</span> 2347<span class="special">{</span> 2348 <span class="keyword">unsigned</span> <span class="keyword">char</span> <span class="identifier">r</span><span class="special">,</span> <span class="identifier">g</span><span class="special">,</span> <span class="identifier">b</span><span class="special">;</span> <span class="comment">// 3 bytes</span> 2349<span class="special">};</span> 2350</pre> 2351<p> 2352 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic</span><span class="special"><</span><span class="identifier">rgb</span><span class="special">></span></code> 2353 is able to implement lock-free operations if the target CPU supports 32-bit 2354 atomic instructions by padding <code class="computeroutput"><span class="identifier">rgb</span></code> 2355 structure internally to the size of 4 bytes. This is not possible for 2356 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic_ref</span><span class="special"><</span><span class="identifier">rgb</span><span class="special">></span></code>, 2357 as it has to operate on external objects. Thus, <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic_ref</span><span class="special"><</span><span class="identifier">rgb</span><span class="special">></span></code> will not provide lock-free operations 2358 and will resort to locking. 2359 </p> 2360<p> 2361 In general, it is advised to use <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic</span></code> 2362 wherever possible, as it is easier to use and is more efficient. Use <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic_ref</span></code> only when you absolutely have 2363 to. 2364 </p> 2365</div> 2366</div> 2367<div class="section"> 2368<div class="titlepage"><div><div><h3 class="title"> 2369<a name="atomic.interface.interface_wait_notify_ops"></a><a class="link" href="interface.html#atomic.interface.interface_wait_notify_ops" title="Waiting and notifying operations">Waiting and 2370 notifying operations</a> 2371</h3></div></div></div> 2372<p> 2373 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic_flag</span></code>, <code class="literal">boost::atomic<<span class="emphasis"><em>T</em></span>></code> 2374 and <code class="literal">boost::atomic_ref<<span class="emphasis"><em>T</em></span>></code> support 2375 <span class="emphasis"><em>waiting</em></span> and <span class="emphasis"><em>notifying</em></span> operations 2376 that were introduced in C++20. Waiting operations have the following forms: 2377 </p> 2378<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 2379 <code class="literal"><span class="emphasis"><em>T</em></span> wait(<span class="emphasis"><em>T</em></span> old_val, 2380 memory_order order)</code> (where <span class="emphasis"><em>T</em></span> is <code class="computeroutput"><span class="keyword">bool</span></code> for <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic_flag</span></code>) 2381 </li></ul></div> 2382<p> 2383 Here, <code class="computeroutput"><span class="identifier">order</span></code> must not be 2384 <code class="computeroutput"><span class="identifier">memory_order_release</span></code> or 2385 <code class="computeroutput"><span class="identifier">memory_order_acq_rel</span></code>. Note 2386 that unlike C++20, the <code class="computeroutput"><span class="identifier">wait</span></code> 2387 operation returns <span class="emphasis"><em>T</em></span> instead of <code class="computeroutput"><span class="keyword">void</span></code>. 2388 This is a <span class="bold"><strong>Boost.Atomic</strong></span> extension. 2389 </p> 2390<p> 2391 The waiting operation performs the following steps repeatedly: 2392 </p> 2393<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 2394<li class="listitem"> 2395 Loads the current value <code class="computeroutput"><span class="identifier">new_val</span></code> 2396 of the atomic object using the memory ordering constraint <code class="computeroutput"><span class="identifier">order</span></code>. 2397 </li> 2398<li class="listitem"> 2399 If the <code class="computeroutput"><span class="identifier">new_val</span></code> representation 2400 is different from <code class="computeroutput"><span class="identifier">old_val</span></code> 2401 (i.e. when compared as if by <code class="computeroutput"><span class="identifier">memcmp</span></code>), 2402 returns <code class="computeroutput"><span class="identifier">new_val</span></code>. 2403 </li> 2404<li class="listitem"> 2405 Blocks the calling thread until unblocked by a notifying operation or 2406 spuriously. 2407 </li> 2408</ul></div> 2409<p> 2410 Note that a waiting operation is allowed to return spuriously, i.e. without 2411 a corresponding notifying operation. It is also allowed to <span class="emphasis"><em>not</em></span> 2412 return if the atomic object value is different from <code class="computeroutput"><span class="identifier">old_val</span></code> 2413 only momentarily (this is known as <a href="https://en.wikipedia.org/wiki/ABA_problem" target="_top">ABA 2414 problem</a>). 2415 </p> 2416<p> 2417 Notifying operations have the following forms: 2418 </p> 2419<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 2420<li class="listitem"> 2421 <code class="computeroutput"><span class="keyword">void</span> <span class="identifier">notify_one</span><span class="special">()</span></code> 2422 </li> 2423<li class="listitem"> 2424 <code class="computeroutput"><span class="keyword">void</span> <span class="identifier">notify_all</span><span class="special">()</span></code> 2425 </li> 2426</ul></div> 2427<p> 2428 The <code class="computeroutput"><span class="identifier">notify_one</span></code> operation 2429 unblocks at least one thread blocked in the waiting operation on the same 2430 atomic object, and <code class="computeroutput"><span class="identifier">notify_all</span></code> 2431 unblocks all such threads. Notifying operations do not enforce memory ordering 2432 and should normally be preceeded with a store operation or a fence with the 2433 appropriate memory ordering constraint. 2434 </p> 2435<p> 2436 Waiting and notifying operations require special support from the operating 2437 system, which may not be universally available. Whether the operating system 2438 natively supports these operations is indicated by the <code class="computeroutput"><span class="identifier">always_has_native_wait_notify</span></code> 2439 static constant and <code class="computeroutput"><span class="identifier">has_native_wait_notify</span><span class="special">()</span></code> member function of a given atomic type. 2440 </p> 2441<p> 2442 Even for atomic objects that support lock-free operations (as indicated by 2443 the <code class="computeroutput"><span class="identifier">is_always_lock_free</span></code> property 2444 or the corresponding <a class="link" href="interface.html#atomic.interface.feature_macros" title="Feature testing macros">macro</a>), 2445 the waiting and notifying operations may involve locking and require linking 2446 with <span class="bold"><strong>Boost.Atomic</strong></span> compiled library. 2447 </p> 2448<p> 2449 Waiting and notifying operations are not address-free, meaning that the implementation 2450 may use process-local state and process-local addresses of the atomic objects 2451 to implement the operations. In particular, this means these operations cannot 2452 be used for communication between processes (when the atomic object is located 2453 in shared memory) or when the atomic object is mapped at different memory 2454 addresses in the same process. 2455 </p> 2456</div> 2457<div class="section"> 2458<div class="titlepage"><div><div><h3 class="title"> 2459<a name="atomic.interface.interface_ipc"></a><a class="link" href="interface.html#atomic.interface.interface_ipc" title="Atomic types for inter-process communication">Atomic types for inter-process 2460 communication</a> 2461</h3></div></div></div> 2462<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">atomic</span><span class="special">/</span><span class="identifier">ipc_atomic</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 2463<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">atomic</span><span class="special">/</span><span class="identifier">ipc_atomic_ref</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 2464<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">atomic</span><span class="special">/</span><span class="identifier">ipc_atomic_flag</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 2465</pre> 2466<p> 2467 <span class="bold"><strong>Boost.Atomic</strong></span> provides a dedicated set of 2468 types for inter-process communication: <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">ipc_atomic_flag</span></code>, 2469 <code class="literal">boost::ipc_atomic<<span class="emphasis"><em>T</em></span>></code> and <code class="literal">boost::ipc_atomic_ref<<span class="emphasis"><em>T</em></span>></code>. 2470 Collectively, these types are called inter-process communication atomic types 2471 or IPC atomic types, and their counterparts without the <code class="computeroutput"><span class="identifier">ipc_</span></code> 2472 prefix - non-IPC atomic types. 2473 </p> 2474<p> 2475 Each of the IPC atomic types have the same requirements on their value types 2476 and provide the same set of operations and properties as its non-IPC counterpart. 2477 All operations have the same signature, requirements and effects, with the 2478 following amendments: 2479 </p> 2480<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 2481<li class="listitem"> 2482 All operations, except constructors, destructors, <code class="computeroutput"><span class="identifier">is_lock_free</span><span class="special">()</span></code> and <code class="computeroutput"><span class="identifier">has_native_wait_notify</span><span class="special">()</span></code> have an additional precondition that 2483 <code class="computeroutput"><span class="identifier">is_lock_free</span><span class="special">()</span></code> 2484 returns <code class="computeroutput"><span class="keyword">true</span></code> for this atomic 2485 object. (Implementation note: The current implementation detects availability 2486 of atomic instructions at compile time, and the code that does not fulfull 2487 this requirement will fail to compile.) 2488 </li> 2489<li class="listitem"> 2490 The <code class="computeroutput"><span class="identifier">has_native_wait_notify</span><span class="special">()</span></code> method and <code class="computeroutput"><span class="identifier">always_has_native_wait_notify</span></code> 2491 static constant indicate whether the operating system has native support 2492 for inter-process waiting and notifying operations. This may be different 2493 from non-IPC atomic types as the OS may have different capabilities for 2494 inter-thread and inter-process communication. 2495 </li> 2496<li class="listitem"> 2497 All operations on objects of IPC atomic types are address-free, which 2498 allows to place such objects (in case of <code class="literal">boost::ipc_atomic_ref<<span class="emphasis"><em>T</em></span>></code> 2499 - objects referenced by <code class="computeroutput"><span class="identifier">ipc_atomic_ref</span></code>) 2500 in memory regions shared between processes or mapped at different addresses 2501 in the same process. 2502 </li> 2503</ul></div> 2504<div class="note"><table border="0" summary="Note"> 2505<tr> 2506<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> 2507<th align="left">Note</th> 2508</tr> 2509<tr><td align="left" valign="top"><p> 2510 Operations on lock-free non-IPC atomic objects, except <a class="link" href="interface.html#atomic.interface.interface_wait_notify_ops" title="Waiting and notifying operations">waiting 2511 and notifying operations</a>, are also address-free, so <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">atomic_flag</span></code>, <code class="literal">boost::atomic<<span class="emphasis"><em>T</em></span>></code> 2512 and <code class="literal">boost::atomic_ref<<span class="emphasis"><em>T</em></span>></code> 2513 could also be used for inter-process communication. However, the user must 2514 ensure that the given atomic object indeed supports lock-free operations. 2515 Failing to do this could result in a misbehaving program. IPC atomic types 2516 enforce this requirement and add support for address-free waiting and notifying 2517 operations. 2518 </p></td></tr> 2519</table></div> 2520<p> 2521 It should be noted that some operations on IPC atomic types may be more expensive 2522 than the non-IPC ones. This primarily concerns waiting and notifying operations, 2523 as the operating system may have to perform conversion of the process-mapped 2524 addresses of atomic objects to physical addresses. Also, when native support 2525 for inter-process waiting and notifying operations is not present (as indicated 2526 by <code class="computeroutput"><span class="identifier">has_native_wait_notify</span><span class="special">()</span></code>), waiting operations are emulated with 2527 a busy loop, which can affect performance and power consumption of the system. 2528 Native support for waiting and notifying operations can also be detected 2529 using <a class="link" href="interface.html#atomic.interface.feature_macros" title="Feature testing macros">capability macros</a>. 2530 </p> 2531<p> 2532 Users must not create and use IPC and non-IPC atomic references on the same 2533 referenced object at the same time. IPC and non-IPC atomic references are 2534 not required to communicate with each other. For example, a waiting operation 2535 on a non-IPC atomic reference may not be interrupted by a notifying operation 2536 on an IPC atomic reference referencing the same object. 2537 </p> 2538</div> 2539<div class="section"> 2540<div class="titlepage"><div><div><h3 class="title"> 2541<a name="atomic.interface.interface_fences"></a><a class="link" href="interface.html#atomic.interface.interface_fences" title="Fences">Fences</a> 2542</h3></div></div></div> 2543<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">atomic</span><span class="special">/</span><span class="identifier">fences</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 2544</pre> 2545<p> 2546 <a class="link" href="thread_coordination.html#atomic.thread_coordination.fences" title="Fences">Fences</a> are implemented 2547 with the following operations: 2548 </p> 2549<div class="informaltable"><table class="table"> 2550<colgroup> 2551<col> 2552<col> 2553</colgroup> 2554<thead><tr> 2555<th> 2556 <p> 2557 Syntax 2558 </p> 2559 </th> 2560<th> 2561 <p> 2562 Description 2563 </p> 2564 </th> 2565</tr></thead> 2566<tbody> 2567<tr> 2568<td> 2569 <p> 2570 <code class="computeroutput"><span class="keyword">void</span> <span class="identifier">atomic_thread_fence</span><span class="special">(</span><span class="identifier">memory_order</span> 2571 <span class="identifier">order</span><span class="special">)</span></code> 2572 </p> 2573 </td> 2574<td> 2575 <p> 2576 Issue fence for coordination with other threads. 2577 </p> 2578 </td> 2579</tr> 2580<tr> 2581<td> 2582 <p> 2583 <code class="computeroutput"><span class="keyword">void</span> <span class="identifier">atomic_signal_fence</span><span class="special">(</span><span class="identifier">memory_order</span> 2584 <span class="identifier">order</span><span class="special">)</span></code> 2585 </p> 2586 </td> 2587<td> 2588 <p> 2589 Issue fence for coordination with a signal handler (only in the 2590 same thread). 2591 </p> 2592 </td> 2593</tr> 2594</tbody> 2595</table></div> 2596<p> 2597 Note that <code class="computeroutput"><span class="identifier">atomic_signal_fence</span></code> 2598 does not implement thread synchronization and only acts as a barrier to prevent 2599 code reordering by the compiler (but not by CPU). The <code class="computeroutput"><span class="identifier">order</span></code> 2600 argument here specifies the direction, in which the fence prevents the compiler 2601 to reorder code. 2602 </p> 2603</div> 2604<div class="section"> 2605<div class="titlepage"><div><div><h3 class="title"> 2606<a name="atomic.interface.feature_macros"></a><a class="link" href="interface.html#atomic.interface.feature_macros" title="Feature testing macros">Feature testing macros</a> 2607</h3></div></div></div> 2608<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">atomic</span><span class="special">/</span><span class="identifier">capabilities</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 2609</pre> 2610<p> 2611 <span class="bold"><strong>Boost.Atomic</strong></span> defines a number of macros 2612 to allow compile-time detection whether an atomic data type is implemented 2613 using "true" atomic operations, or whether an internal "lock" 2614 is used to provide atomicity. The following macros will be defined to <code class="computeroutput"><span class="number">0</span></code> if operations on the data type always require 2615 a lock, to <code class="computeroutput"><span class="number">1</span></code> if operations on 2616 the data type may sometimes require a lock, and to <code class="computeroutput"><span class="number">2</span></code> 2617 if they are always lock-free: 2618 </p> 2619<div class="informaltable"><table class="table"> 2620<colgroup> 2621<col> 2622<col> 2623</colgroup> 2624<thead><tr> 2625<th> 2626 <p> 2627 Macro 2628 </p> 2629 </th> 2630<th> 2631 <p> 2632 Description 2633 </p> 2634 </th> 2635</tr></thead> 2636<tbody> 2637<tr> 2638<td> 2639 <p> 2640 <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_FLAG_LOCK_FREE</span></code> 2641 </p> 2642 </td> 2643<td> 2644 <p> 2645 Indicate whether <code class="computeroutput"><span class="identifier">atomic_flag</span></code> 2646 is lock-free 2647 </p> 2648 </td> 2649</tr> 2650<tr> 2651<td> 2652 <p> 2653 <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_BOOL_LOCK_FREE</span></code> 2654 </p> 2655 </td> 2656<td> 2657 <p> 2658 Indicate whether <code class="computeroutput"><span class="identifier">atomic</span><span class="special"><</span><span class="keyword">bool</span><span class="special">></span></code> is lock-free 2659 </p> 2660 </td> 2661</tr> 2662<tr> 2663<td> 2664 <p> 2665 <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_CHAR_LOCK_FREE</span></code> 2666 </p> 2667 </td> 2668<td> 2669 <p> 2670 Indicate whether <code class="computeroutput"><span class="identifier">atomic</span><span class="special"><</span><span class="keyword">char</span><span class="special">></span></code> (including signed/unsigned 2671 variants) is lock-free 2672 </p> 2673 </td> 2674</tr> 2675<tr> 2676<td> 2677 <p> 2678 <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_CHAR8_T_LOCK_FREE</span></code> 2679 </p> 2680 </td> 2681<td> 2682 <p> 2683 Indicate whether <code class="computeroutput"><span class="identifier">atomic</span><span class="special"><</span><span class="identifier">char8_t</span><span class="special">></span></code> (including signed/unsigned 2684 variants) is lock-free 2685 </p> 2686 </td> 2687</tr> 2688<tr> 2689<td> 2690 <p> 2691 <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_CHAR16_T_LOCK_FREE</span></code> 2692 </p> 2693 </td> 2694<td> 2695 <p> 2696 Indicate whether <code class="computeroutput"><span class="identifier">atomic</span><span class="special"><</span><span class="keyword">char16_t</span><span class="special">></span></code> (including signed/unsigned 2697 variants) is lock-free 2698 </p> 2699 </td> 2700</tr> 2701<tr> 2702<td> 2703 <p> 2704 <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_CHAR32_T_LOCK_FREE</span></code> 2705 </p> 2706 </td> 2707<td> 2708 <p> 2709 Indicate whether <code class="computeroutput"><span class="identifier">atomic</span><span class="special"><</span><span class="keyword">char32_t</span><span class="special">></span></code> (including signed/unsigned 2710 variants) is lock-free 2711 </p> 2712 </td> 2713</tr> 2714<tr> 2715<td> 2716 <p> 2717 <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_WCHAR_T_LOCK_FREE</span></code> 2718 </p> 2719 </td> 2720<td> 2721 <p> 2722 Indicate whether <code class="computeroutput"><span class="identifier">atomic</span><span class="special"><</span><span class="keyword">wchar_t</span><span class="special">></span></code> (including signed/unsigned 2723 variants) is lock-free 2724 </p> 2725 </td> 2726</tr> 2727<tr> 2728<td> 2729 <p> 2730 <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_SHORT_LOCK_FREE</span></code> 2731 </p> 2732 </td> 2733<td> 2734 <p> 2735 Indicate whether <code class="computeroutput"><span class="identifier">atomic</span><span class="special"><</span><span class="keyword">short</span><span class="special">></span></code> (including signed/unsigned 2736 variants) is lock-free 2737 </p> 2738 </td> 2739</tr> 2740<tr> 2741<td> 2742 <p> 2743 <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_INT_LOCK_FREE</span></code> 2744 </p> 2745 </td> 2746<td> 2747 <p> 2748 Indicate whether <code class="computeroutput"><span class="identifier">atomic</span><span class="special"><</span><span class="keyword">int</span><span class="special">></span></code> (including signed/unsigned 2749 variants) is lock-free 2750 </p> 2751 </td> 2752</tr> 2753<tr> 2754<td> 2755 <p> 2756 <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_LONG_LOCK_FREE</span></code> 2757 </p> 2758 </td> 2759<td> 2760 <p> 2761 Indicate whether <code class="computeroutput"><span class="identifier">atomic</span><span class="special"><</span><span class="keyword">long</span><span class="special">></span></code> (including signed/unsigned 2762 variants) is lock-free 2763 </p> 2764 </td> 2765</tr> 2766<tr> 2767<td> 2768 <p> 2769 <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_LLONG_LOCK_FREE</span></code> 2770 </p> 2771 </td> 2772<td> 2773 <p> 2774 Indicate whether <code class="computeroutput"><span class="identifier">atomic</span><span class="special"><</span><span class="keyword">long</span> 2775 <span class="keyword">long</span><span class="special">></span></code> 2776 (including signed/unsigned variants) is lock-free 2777 </p> 2778 </td> 2779</tr> 2780<tr> 2781<td> 2782 <p> 2783 <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_ADDRESS_LOCK_FREE</span></code> 2784 or <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_POINTER_LOCK_FREE</span></code> 2785 </p> 2786 </td> 2787<td> 2788 <p> 2789 Indicate whether <code class="computeroutput"><span class="identifier">atomic</span><span class="special"><</span><span class="identifier">T</span> 2790 <span class="special">*></span></code> is lock-free 2791 </p> 2792 </td> 2793</tr> 2794<tr> 2795<td> 2796 <p> 2797 <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_THREAD_FENCE</span></code> 2798 </p> 2799 </td> 2800<td> 2801 <p> 2802 Indicate whether <code class="computeroutput"><span class="identifier">atomic_thread_fence</span></code> 2803 function is lock-free 2804 </p> 2805 </td> 2806</tr> 2807<tr> 2808<td> 2809 <p> 2810 <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_SIGNAL_FENCE</span></code> 2811 </p> 2812 </td> 2813<td> 2814 <p> 2815 Indicate whether <code class="computeroutput"><span class="identifier">atomic_signal_fence</span></code> 2816 function is lock-free 2817 </p> 2818 </td> 2819</tr> 2820</tbody> 2821</table></div> 2822<p> 2823 In addition to these standard macros, <span class="bold"><strong>Boost.Atomic</strong></span> 2824 also defines a number of extension macros, which can also be useful. Like 2825 the standard ones, these macros are defined to values <code class="computeroutput"><span class="number">0</span></code>, 2826 <code class="computeroutput"><span class="number">1</span></code> and <code class="computeroutput"><span class="number">2</span></code> 2827 to indicate whether the corresponding operations are lock-free or not. 2828 </p> 2829<div class="informaltable"><table class="table"> 2830<colgroup> 2831<col> 2832<col> 2833</colgroup> 2834<thead><tr> 2835<th> 2836 <p> 2837 Macro 2838 </p> 2839 </th> 2840<th> 2841 <p> 2842 Description 2843 </p> 2844 </th> 2845</tr></thead> 2846<tbody> 2847<tr> 2848<td> 2849 <p> 2850 <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_INT8_LOCK_FREE</span></code> 2851 </p> 2852 </td> 2853<td> 2854 <p> 2855 Indicate whether <code class="computeroutput"><span class="identifier">atomic</span><span class="special"><</span><span class="identifier">int8_type</span><span class="special">></span></code> is lock-free. 2856 </p> 2857 </td> 2858</tr> 2859<tr> 2860<td> 2861 <p> 2862 <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_INT16_LOCK_FREE</span></code> 2863 </p> 2864 </td> 2865<td> 2866 <p> 2867 Indicate whether <code class="computeroutput"><span class="identifier">atomic</span><span class="special"><</span><span class="identifier">int16_type</span><span class="special">></span></code> is lock-free. 2868 </p> 2869 </td> 2870</tr> 2871<tr> 2872<td> 2873 <p> 2874 <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_INT32_LOCK_FREE</span></code> 2875 </p> 2876 </td> 2877<td> 2878 <p> 2879 Indicate whether <code class="computeroutput"><span class="identifier">atomic</span><span class="special"><</span><span class="identifier">int32_type</span><span class="special">></span></code> is lock-free. 2880 </p> 2881 </td> 2882</tr> 2883<tr> 2884<td> 2885 <p> 2886 <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_INT64_LOCK_FREE</span></code> 2887 </p> 2888 </td> 2889<td> 2890 <p> 2891 Indicate whether <code class="computeroutput"><span class="identifier">atomic</span><span class="special"><</span><span class="identifier">int64_type</span><span class="special">></span></code> is lock-free. 2892 </p> 2893 </td> 2894</tr> 2895<tr> 2896<td> 2897 <p> 2898 <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_INT128_LOCK_FREE</span></code> 2899 </p> 2900 </td> 2901<td> 2902 <p> 2903 Indicate whether <code class="computeroutput"><span class="identifier">atomic</span><span class="special"><</span><span class="identifier">int128_type</span><span class="special">></span></code> is lock-free. 2904 </p> 2905 </td> 2906</tr> 2907<tr> 2908<td> 2909 <p> 2910 <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_NO_ATOMIC_FLAG_INIT</span></code> 2911 </p> 2912 </td> 2913<td> 2914 <p> 2915 Defined after including <code class="computeroutput"><span class="identifier">atomic_flag</span><span class="special">.</span><span class="identifier">hpp</span></code>, 2916 if the implementation does not support the <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_FLAG_INIT</span></code> 2917 macro for static initialization of <code class="computeroutput"><span class="identifier">atomic_flag</span></code>. 2918 This macro is typically defined for pre-C++11 compilers. 2919 </p> 2920 </td> 2921</tr> 2922</tbody> 2923</table></div> 2924<p> 2925 In the table above, <code class="literal">int<span class="emphasis"><em>N</em></span>_type</code> is 2926 a type that fits storage of contiguous <span class="emphasis"><em>N</em></span> bits, suitably 2927 aligned for atomic operations. 2928 </p> 2929<p> 2930 For floating-point types the following macros are similarly defined: 2931 </p> 2932<div class="informaltable"><table class="table"> 2933<colgroup> 2934<col> 2935<col> 2936</colgroup> 2937<thead><tr> 2938<th> 2939 <p> 2940 Macro 2941 </p> 2942 </th> 2943<th> 2944 <p> 2945 Description 2946 </p> 2947 </th> 2948</tr></thead> 2949<tbody> 2950<tr> 2951<td> 2952 <p> 2953 <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_FLOAT_LOCK_FREE</span></code> 2954 </p> 2955 </td> 2956<td> 2957 <p> 2958 Indicate whether <code class="computeroutput"><span class="identifier">atomic</span><span class="special"><</span><span class="keyword">float</span><span class="special">></span></code> is lock-free. 2959 </p> 2960 </td> 2961</tr> 2962<tr> 2963<td> 2964 <p> 2965 <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_DOUBLE_LOCK_FREE</span></code> 2966 </p> 2967 </td> 2968<td> 2969 <p> 2970 Indicate whether <code class="computeroutput"><span class="identifier">atomic</span><span class="special"><</span><span class="keyword">double</span><span class="special">></span></code> is lock-free. 2971 </p> 2972 </td> 2973</tr> 2974<tr> 2975<td> 2976 <p> 2977 <code class="computeroutput"><span class="identifier">BOOST_ATOMIC_LONG_DOUBLE_LOCK_FREE</span></code> 2978 </p> 2979 </td> 2980<td> 2981 <p> 2982 Indicate whether <code class="computeroutput"><span class="identifier">atomic</span><span class="special"><</span><span class="keyword">long</span> 2983 <span class="keyword">double</span><span class="special">></span></code> 2984 is lock-free. 2985 </p> 2986 </td> 2987</tr> 2988</tbody> 2989</table></div> 2990<p> 2991 These macros are not defined when support for floating point types is disabled 2992 by user. 2993 </p> 2994<p> 2995 For any of the <code class="literal">BOOST_ATOMIC_<span class="emphasis"><em>X</em></span>_LOCK_FREE</code> 2996 macro described above, two additional macros named <code class="literal">BOOST_ATOMIC_HAS_NATIVE_<span class="emphasis"><em>X</em></span>_WAIT_NOTIFY</code> 2997 and <code class="literal">BOOST_ATOMIC_HAS_NATIVE_<span class="emphasis"><em>X</em></span>_IPC_WAIT_NOTIFY</code> 2998 are defined. The former indicates whether <a class="link" href="interface.html#atomic.interface.interface_wait_notify_ops" title="Waiting and notifying operations">waiting 2999 and notifying operations</a> are supported natively for non-IPC atomic 3000 types of a given type, and the latter does the same for <a class="link" href="interface.html#atomic.interface.interface_ipc" title="Atomic types for inter-process communication">IPC 3001 atomic types</a>. The macros take values of <code class="computeroutput"><span class="number">0</span></code>, 3002 <code class="computeroutput"><span class="number">1</span></code> or <code class="computeroutput"><span class="number">2</span></code>, 3003 where <code class="computeroutput"><span class="number">0</span></code> indicates that native 3004 operations are not available, <code class="computeroutput"><span class="number">1</span></code> 3005 means the operations may be available (which is determined at run time) and 3006 <code class="computeroutput"><span class="number">2</span></code> means always available. Note 3007 that the lock-free and native waiting/notifying operations macros for a given 3008 type may have different values. 3009 </p> 3010</div> 3011</div> 3012<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 3013<td align="left"></td> 3014<td align="right"><div class="copyright-footer">Copyright © 2011 Helge Bahmann<br>Copyright © 2012 Tim Blechmann<br>Copyright © 2013, 2017, 2018, 2020 Andrey 3015 Semashev<p> 3016 Distributed under the Boost Software License, Version 1.0. (See accompanying 3017 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>) 3018 </p> 3019</div></td> 3020</tr></table> 3021<hr> 3022<div class="spirit-nav"> 3023<a accesskey="p" href="thread_coordination.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../atomic.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="usage_examples.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> 3024</div> 3025</body> 3026</html> 3027
