+[/

+ / Copyright (c) 2009 Helge Bahmann

+ / Copyright (c) 2014 Andrey Semashev

+ /

+ / Distributed under the Boost Software License, Version 1.0. (See accompanying

+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

+ /]

+

+[library Boost.Atomic

+ [quickbook 1.4]

+ [authors [Bahmann, Helge][Semashev, Andrey]]

+ [copyright 2011 Helge Bahmann]

+ [copyright 2012 Tim Blechmann]

+ [copyright 2013 Andrey Semashev]

+ [id atomic]

+ [dirname atomic]

+ [purpose Atomic operations]

+ [license

+ Distributed under the Boost Software License, Version 1.0.

+ (See accompanying file LICENSE_1_0.txt or copy at

+ [@http://www.boost.org/LICENSE_1_0.txt])

+ ]

+]

+

+[section:introduction Introduction]

+

+[section:introduction_presenting Presenting Boost.Atomic]

+

+[*Boost.Atomic] is a library that provides [^atomic]

+data types and operations on these data types, as well as memory

+ordering constraints required for coordinating multiple threads through

+atomic variables. It implements the interface as defined by the C++11

+standard, but makes this feature available for platforms lacking

+system/compiler support for this particular C++11 feature.

+

+Users of this library should already be familiar with concurrency

+in general, as well as elementary concepts such as "mutual exclusion".

+

+The implementation makes use of processor-specific instructions where

+possible (via inline assembler, platform libraries or compiler

+intrinsics), and falls back to "emulating" atomic operations through

+locking.

+

+[endsect]

+

+[section:introduction_purpose Purpose]

+

+Operations on "ordinary" variables are not guaranteed to be atomic.

+This means that with [^int n=0] initially, two threads concurrently

+executing

+

+[c++]

+

+ void function()

+ {

+ n ++;

+ }

+

+might result in [^n==1] instead of 2: Each thread will read the

+old value into a processor register, increment it and write the result

+back. Both threads may therefore write [^1], unaware that the other thread

+is doing likewise.

+

+Declaring [^atomic<int> n=0] instead, the same operation on

+this variable will always result in [^n==2] as each operation on this

+variable is ['atomic]: This means that each operation behaves as if it

+were strictly sequentialized with respect to the other.

+

+Atomic variables are useful for two purposes:

+

+* as a means for coordinating multiple threads via custom

+ coordination protocols

+* as faster alternatives to "locked" access to simple variables

+

+Take a look at the [link atomic.usage_examples examples] section

+for common patterns.

+

+[endsect]

+

+[endsect]

+

+[section:thread_coordination Thread coordination using Boost.Atomic]

+

+The most common use of [*Boost.Atomic] is to realize custom

+thread synchronization protocols: The goal is to coordinate

+accesses of threads to shared variables in order to avoid

+"conflicts". The

+programmer must be aware of the fact that

+compilers, CPUs and the cache

+hierarchies may generally reorder memory references at will.

+As a consequence a program such as:

+

+[c++]

+

+ int x = 0, int y = 0;

+

+ thread1:

+ x = 1;

+ y = 1;

+

+ thread2

+ if (y == 1) {

+ assert(x == 1);

+ }

+

+might indeed fail as there is no guarantee that the read of `x`

+by thread2 "sees" the write by thread1.

+

+[*Boost.Atomic] uses a synchronisation concept based on the

+['happens-before] relation to describe the guarantees under

+which situations such as the above one cannot occur.

+

+The remainder of this section will discuss ['happens-before] in

+a "hands-on" way instead of giving a fully formalized definition.

+The reader is encouraged to additionally have a

+look at the discussion of the correctness of a few of the

+[link atomic.usage_examples examples] afterwards.

+

+[section:mutex Enforcing ['happens-before] through mutual exclusion]

+

+As an introductory example to understand how arguing using

+['happens-before] works, consider two threads synchronizing

+using a common mutex:

+

+[c++]

+

+ mutex m;

+

+ thread1:

+ m.lock();

+ ... /* A */

+ m.unlock();

+

+ thread2:

+ m.lock();

+ ... /* B */

+ m.unlock();

+

+The "lockset-based intuition" would be to argue that A and B

+cannot be executed concurrently as the code paths require a

+common lock to be held.

+

+One can however also arrive at the same conclusion using

+['happens-before]: Either thread1 or thread2 will succeed first

+at [^m.lock()]. If this is be thread1, then as a consequence,

+thread2 cannot succeed at [^m.lock()] before thread1 has executed

+[^m.unlock()], consequently A ['happens-before] B in this case.

+By symmetry, if thread2 succeeds at [^m.lock()] first, we can

+conclude B ['happens-before] A.

+

+Since this already exhausts all options, we can conclude that

+either A ['happens-before] B or B ['happens-before] A must

+always hold. Obviously cannot state ['which] of the two relationships

+holds, but either one is sufficient to conclude that A and B

+cannot conflict.

+

+Compare the [link boost_atomic.usage_examples.example_spinlock spinlock]

+implementation to see how the mutual exclusion concept can be

+mapped to [*Boost.Atomic].

+

+[endsect]

+

+[section:release_acquire ['happens-before] through [^release] and [^acquire]]

+

+The most basic pattern for coordinating threads via [*Boost.Atomic]

+uses [^release] and [^acquire] on an atomic variable for coordination: If ...

+

+* ... thread1 performs an operation A,

+* ... thread1 subsequently writes (or atomically

+ modifies) an atomic variable with [^release] semantic,

+* ... thread2 reads (or atomically reads-and-modifies)

+ the value this value from the same atomic variable with

+ [^acquire] semantic and

+* ... thread2 subsequently performs an operation B,

+

+... then A ['happens-before] B.

+

+Consider the following example

+

+[c++]

+

+ atomic<int> a(0);

+

+ thread1:

+ ... /* A */

+ a.fetch_add(1, memory_order_release);

+

+ thread2:

+ int tmp = a.load(memory_order_acquire);

+ if (tmp == 1) {

+ ... /* B */

+ } else {

+ ... /* C */

+ }

+

+In this example, two avenues for execution are possible:

+

+* The [^store] operation by thread1 precedes the [^load] by thread2:

+ In this case thread2 will execute B and "A ['happens-before] B"

+ holds as all of the criteria above are satisfied.

+* The [^load] operation by thread2 precedes the [^store] by thread1:

+ In this case, thread2 will execute C, but "A ['happens-before] C"

+ does ['not] hold: thread2 does not read the value written by

+ thread1 through [^a].

+

+Therefore, A and B cannot conflict, but A and C ['can] conflict.

+

+[endsect]

+

+[section:fences Fences]

+

+Ordering constraints are generally specified together with an access to

+an atomic variable. It is however also possible to issue "fence"

+operations in isolation, in this case the fence operates in

+conjunction with preceding (for `acquire`, `consume` or `seq_cst`

+operations) or succeeding (for `release` or `seq_cst`) atomic

+operations.

+

+The example from the previous section could also be written in

+the following way:

+

+[c++]

+

+ atomic<int> a(0);

+

+ thread1:

+ ... /* A */

+ atomic_thread_fence(memory_order_release);

+ a.fetch_add(1, memory_order_relaxed);

+

+ thread2:

+ int tmp = a.load(memory_order_relaxed);

+ if (tmp == 1) {

+ atomic_thread_fence(memory_order_acquire);

+ ... /* B */

+ } else {

+ ... /* C */

+ }

+

+This provides the same ordering guarantees as previously, but

+elides a (possibly expensive) memory ordering operation in

+the case C is executed.

+

+[endsect]

+

+[section:release_consume ['happens-before] through [^release] and [^consume]]

+

+The second pattern for coordinating threads via [*Boost.Atomic]

+uses [^release] and [^consume] on an atomic variable for coordination: If ...

+

+* ... thread1 performs an operation A,

+* ... thread1 subsequently writes (or atomically modifies) an

+ atomic variable with [^release] semantic,

+* ... thread2 reads (or atomically reads-and-modifies)

+ the value this value from the same atomic variable with [^consume] semantic and

+* ... thread2 subsequently performs an operation B that is ['computationally

+ dependent on the value of the atomic variable],

+

+... then A ['happens-before] B.

+

+Consider the following example

+

+[c++]

+

+ atomic<int> a(0);

+ complex_data_structure data[2];

+

+ thread1:

+ data[1] = ...; /* A */

+ a.store(1, memory_order_release);

+

+ thread2:

+ int index = a.load(memory_order_consume);

+ complex_data_structure tmp = data[index]; /* B */

+

+In this example, two avenues for execution are possible:

+

+* The [^store] operation by thread1 precedes the [^load] by thread2:

+ In this case thread2 will read [^data\[1\]] and "A ['happens-before] B"

+ holds as all of the criteria above are satisfied.

+* The [^load] operation by thread2 precedes the [^store] by thread1:

+ In this case thread2 will read [^data\[0\]] and "A ['happens-before] B"

+ does ['not] hold: thread2 does not read the value written by

+ thread1 through [^a].

+

+Here, the ['happens-before] relationship helps ensure that any

+accesses (presumable writes) to [^data\[1\]] by thread1 happen before

+before the accesses (presumably reads) to [^data\[1\]] by thread2:

+Lacking this relationship, thread2 might see stale/inconsistent

+data.

+

+Note that in this example, the fact that operation B is computationally

+dependent on the atomic variable, therefore the following program would

+be erroneous:

+

+[c++]

+

+ atomic<int> a(0);

+ complex_data_structure data[2];

+

+ thread1:

+ data[1] = ...; /* A */

+ a.store(1, memory_order_release);

+

+ thread2:

+ int index = a.load(memory_order_consume);

+ complex_data_structure tmp;

+ if (index == 0)

+ tmp = data[0];

+ else

+ tmp = data[1];

+

+[^consume] is most commonly (and most safely! see

+[link atomic.limitations limitations]) used with

+pointers, compare for example the

+[link boost_atomic.usage_examples.singleton singleton with double-checked locking].

+

+[endsect]

+

+[section:seq_cst Sequential consistency]

+

+The third pattern for coordinating threads via [*Boost.Atomic]

+uses [^seq_cst] for coordination: If ...

+

+* ... thread1 performs an operation A,

+* ... thread1 subsequently performs any operation with [^seq_cst],

+* ... thread1 subsequently performs an operation B,

+* ... thread2 performs an operation C,

+* ... thread2 subsequently performs any operation with [^seq_cst],

+* ... thread2 subsequently performs an operation D,

+

+then either "A ['happens-before] D" or "C ['happens-before] B" holds.

+

+In this case it does not matter whether thread1 and thread2 operate

+on the same or different atomic variables, or use a "stand-alone"

+[^atomic_thread_fence] operation.

+

+[endsect]

+

+[endsect]

+

+[section:interface Programming interfaces]

+

+[section:configuration Configuration and building]

+

+The library contains header-only and compiled parts. The library is

+header-only for lock-free cases but requires a separate binary to

+implement the lock-based emulation. Users are able to detect whether

+linking to the compiled part is required by checking the

+[link atomic.interface.feature_macros feature macros].

+

+The following macros affect library behavior:

+

+[table

+ [[Macro] [Description]]

+ [[`BOOST_ATOMIC_NO_CMPXCHG16B`] [Affects 64-bit x86 MSVC builds. When defined,

+ the library assumes the target CPU does not support `cmpxchg16b` instruction used

+ to support 128-bit atomic operations. This is the case with some early 64-bit AMD CPUs,

+ all Intel CPUs and current AMD CPUs support this instruction. The library does not

+ perform runtime detection of this instruction, so running the code that uses 128-bit

+ atomics on such CPUs will result in crashes, unless this macro is defined. Note that

+ the macro does not affect GCC and compatible compilers because the library infers

+ this information from the compiler-defined macros.]]

+ [[`BOOST_ATOMIC_FORCE_FALLBACK`] [When defined, all operations are implemented with locks.

+ This is mostly used for testing and should not be used in real world projects.]]

+ [[`BOOST_ATOMIC_DYN_LINK` and `BOOST_ALL_DYN_LINK`] [Control library linking. If defined,

+ the library assumes dynamic linking, otherwise static. The latter macro affects all Boost

+ libraries, not just [*Boost.Atomic].]]

+ [[`BOOST_ATOMIC_NO_LIB` and `BOOST_ALL_NO_LIB`] [Control library auto-linking on Windows.

+ When defined, disables auto-linking. The latter macro affects all Boost libraries,

+ not just [*Boost.Atomic].]]

+]

+

+Besides macros, it is important to specify the correct compiler options for the target CPU.

+With GCC and compatible compilers this affects whether particular atomic operations are

+lock-free or not.

+

+Boost building process is described in the [@http://www.boost.org/doc/libs/release/more/getting_started/ Getting Started guide].

+For example, you can build [*Boost.Atomic] with the following command line:

+

+[pre

+ bjam --with-atomic variant=release instruction-set=core2 stage

+]

+

+[endsect]

+

+[section:interface_memory_order Memory order]

+

+ #include <boost/memory_order.hpp>

+

+The enumeration [^boost::memory_order] defines the following

+values to represent memory ordering constraints:

+

+[table

+ [[Constant] [Description]]

+ [[`memory_order_relaxed`] [No ordering constraint.

+ Informally speaking, following operations may be reordered before,

+ preceding operations may be reordered after the atomic

+ operation. This constraint is suitable only when

+ either a) further operations do not depend on the outcome

+ of the atomic operation or b) ordering is enforced through

+ stand-alone `atomic_thread_fence` operations. The operation on

+ the atomic value itself is still atomic though.

+ ]]

+ [[`memory_order_release`] [

+ Perform `release` operation. Informally speaking,

+ prevents all preceding memory operations to be reordered

+ past this point.

+ ]]

+ [[`memory_order_acquire`] [

+ Perform `acquire` operation. Informally speaking,

+ prevents succeeding memory operations to be reordered

+ before this point.

+ ]]

+ [[`memory_order_consume`] [

+ Perform `consume` operation. More relaxed (and

+ on some architectures more efficient) than `memory_order_acquire`

+ as it only affects succeeding operations that are

+ computationally-dependent on the value retrieved from

+ an atomic variable.

+ ]]

+ [[`memory_order_acq_rel`] [Perform both `release` and `acquire` operation]]

+ [[`memory_order_seq_cst`] [

+ Enforce sequential consistency. Implies `memory_order_acq_rel`, but

+ additionally enforces total order for all operations such qualified.

+ ]]

+]

+

+See section [link atomic.thread_coordination ['happens-before]] for explanation

+of the various ordering constraints.

+

+[endsect]

+

+[section:interface_atomic_object Atomic objects]

+

+ #include <boost/atomic/atomic.hpp>

+

+[^boost::atomic<['T]>] provides methods for atomically accessing

+variables of a suitable type [^['T]]. The type is suitable if

+it is /trivially copyable/ (3.9/9 \[basic.types\]). Following are

+examples of the types compatible with this requirement:

+

+* a scalar type (e.g. integer, boolean, enum or pointer type)

+* a [^class] or [^struct] that has no non-trivial copy or move

+ constructors or assignment operators, has a trivial destructor,

+ and that is comparable via [^memcmp].

+

+Note that classes with virtual functions or virtual base classes

+do not satisfy the requirements. Also be warned

+that structures with "padding" between data members may compare

+non-equal via [^memcmp] even though all members are equal.

+

+[section:interface_atomic_generic [^boost::atomic<['T]>] template class]

+

+All atomic objects supports the following operations:

+

+[table

+ [[Syntax] [Description]]

+ [

+ [`atomic()`]

+ [Initialize to an unspecified value]

+ ]

+ [

+ [`atomic(T initial_value)`]

+ [Initialize to [^initial_value]]

+ ]

+ [

+ [`bool is_lock_free()`]

+ [Checks if the atomic object is lock-free]

+ ]

+ [

+ [`T load(memory_order order)`]

+ [Return current value]

+ ]

+ [

+ [`void store(T value, memory_order order)`]

+ [Write new value to atomic variable]

+ ]

+ [

+ [`T exchange(T new_value, memory_order order)`]

+ [Exchange current value with `new_value`, returning current value]

+ ]

+ [

+ [`bool compare_exchange_weak(T & expected, T desired, memory_order order)`]

+ [Compare current value with `expected`, change it to `desired` if matches.

+ Returns `true` if an exchange has been performed, and always writes the

+ previous value back in `expected`. May fail spuriously, so must generally be

+ retried in a loop.]

+ ]

+ [

+ [`bool compare_exchange_weak(T & expected, T desired, memory_order success_order, memory_order failure_order)`]

+ [Compare current value with `expected`, change it to `desired` if matches.

+ Returns `true` if an exchange has been performed, and always writes the

+ previous value back in `expected`. May fail spuriously, so must generally be

+ retried in a loop.]

+ ]

+ [

+ [`bool compare_exchange_strong(T & expected, T desired, memory_order order)`]

+ [Compare current value with `expected`, change it to `desired` if matches.

+ Returns `true` if an exchange has been performed, and always writes the

+ previous value back in `expected`.]

+ ]

+ [

+ [`bool compare_exchange_strong(T & expected, T desired, memory_order success_order, memory_order failure_order))`]

+ [Compare current value with `expected`, change it to `desired` if matches.

+ Returns `true` if an exchange has been performed, and always writes the

+ previous value back in `expected`.]

+ ]

+]

+

+`order` always has `memory_order_seq_cst` as default parameter.

+

+The `compare_exchange_weak`/`compare_exchange_strong` variants

+taking four parameters differ from the three parameter variants

+in that they allow a different memory ordering constraint to

+be specified in case the operation fails.

+

+In addition to these explicit operations, each

+[^atomic<['T]>] object also supports

+implicit [^store] and [^load] through the use of "assignment"

+and "conversion to [^T]" operators. Avoid using these operators,

+as they do not allow explicit specification of a memory ordering

+constraint.

+

+[endsect]

+

+[section:interface_atomic_integral [^boost::atomic<['integral]>] template class]

+

+In addition to the operations listed in the previous section,

+[^boost::atomic<['I]>] for integral

+types [^['I]] supports the following operations:

+

+[table

+ [[Syntax] [Description]]

+ [

+ [`T fetch_add(T v, memory_order order)`]

+ [Add `v` to variable, returning previous value]

+ ]

+ [

+ [`T fetch_sub(T v, memory_order order)`]

+ [Subtract `v` from variable, returning previous value]

+ ]

+ [

+ [`T fetch_and(T v, memory_order order)`]

+ [Apply bit-wise "and" with `v` to variable, returning previous value]

+ ]

+ [

+ [`T fetch_or(T v, memory_order order)`]

+ [Apply bit-wise "or" with `v` to variable, returning previous value]

+ ]

+ [

+ [`T fetch_xor(T v, memory_order order)`]

+ [Apply bit-wise "xor" with `v` to variable, returning previous value]

+ ]

+]

+

+`order` always has `memory_order_seq_cst` as default parameter.

+

+In addition to these explicit operations, each

+[^boost::atomic<['I]>] object also

+supports implicit pre-/post- increment/decrement, as well

+as the operators `+=`, `-=`, `&=`, `|=` and `^=`.

+Avoid using these operators,

+as they do not allow explicit specification of a memory ordering

+constraint.

+

+[endsect]

+

+[section:interface_atomic_pointer [^boost::atomic<['pointer]>] template class]

+

+In addition to the operations applicable to all atomic object,

+[^boost::atomic<['P]>] for pointer

+types [^['P]] (other than [^void] pointers) support the following operations:

+

+[table

+ [[Syntax] [Description]]

+ [

+ [`T fetch_add(ptrdiff_t v, memory_order order)`]

+ [Add `v` to variable, returning previous value]

+ ]

+ [

+ [`T fetch_sub(ptrdiff_t v, memory_order order)`]

+ [Subtract `v` from variable, returning previous value]

+ ]

+]

+

+`order` always has `memory_order_seq_cst` as default parameter.

+

+In addition to these explicit operations, each

+[^boost::atomic<['P]>] object also

+supports implicit pre-/post- increment/decrement, as well

+as the operators `+=`, `-=`. Avoid using these operators,

+as they do not allow explicit specification of a memory ordering

+constraint.

+

+[endsect]

+

+[endsect]

+

+[section:interface_fences Fences]

+

+ #include <boost/atomic/fences.hpp>

+

+[table

+ [[Syntax] [Description]]

+ [

+ [`void atomic_thread_fence(memory_order order)`]

+ [Issue fence for coordination with other threads.]

+ ]

+ [

+ [`void atomic_signal_fence(memory_order order)`]

+ [Issue fence for coordination with signal handler (only in same thread).]

+ ]

+]

+

+[endsect]

+

+[section:feature_macros Feature testing macros]

+

+ #include <boost/atomic/capabilities.hpp>

+

+[*Boost.Atomic] defines a number of macros to allow compile-time

+detection whether an atomic data type is implemented using

+"true" atomic operations, or whether an internal "lock" is

+used to provide atomicity. The following macros will be

+defined to `0` if operations on the data type always

+require a lock, to `1` if operations on the data type may

+sometimes require a lock, and to `2` if they are always lock-free:

+

+[table

+ [[Macro] [Description]]

+ [

+ [`BOOST_ATOMIC_FLAG_LOCK_FREE`]

+ [Indicate whether `atomic_flag` is lock-free]

+ ]

+ [

+ [`BOOST_ATOMIC_BOOL_LOCK_FREE`]

+ [Indicate whether `atomic<bool>` is lock-free]

+ ]

+ [

+ [`BOOST_ATOMIC_CHAR_LOCK_FREE`]

+ [Indicate whether `atomic<char>` (including signed/unsigned variants) is lock-free]

+ ]

+ [

+ [`BOOST_ATOMIC_CHAR16_T_LOCK_FREE`]

+ [Indicate whether `atomic<char16_t>` (including signed/unsigned variants) is lock-free]

+ ]

+ [

+ [`BOOST_ATOMIC_CHAR32_T_LOCK_FREE`]

+ [Indicate whether `atomic<char32_t>` (including signed/unsigned variants) is lock-free]

+ ]

+ [

+ [`BOOST_ATOMIC_WCHAR_T_LOCK_FREE`]

+ [Indicate whether `atomic<wchar_t>` (including signed/unsigned variants) is lock-free]

+ ]

+ [

+ [`BOOST_ATOMIC_SHORT_LOCK_FREE`]

+ [Indicate whether `atomic<short>` (including signed/unsigned variants) is lock-free]

+ ]

+ [

+ [`BOOST_ATOMIC_INT_LOCK_FREE`]

+ [Indicate whether `atomic<int>` (including signed/unsigned variants) is lock-free]

+ ]

+ [

+ [`BOOST_ATOMIC_LONG_LOCK_FREE`]

+ [Indicate whether `atomic<long>` (including signed/unsigned variants) is lock-free]

+ ]

+ [

+ [`BOOST_ATOMIC_LLONG_LOCK_FREE`]

+ [Indicate whether `atomic<long long>` (including signed/unsigned variants) is lock-free]

+ ]

+ [

+ [`BOOST_ATOMIC_ADDRESS_LOCK_FREE` or `BOOST_ATOMIC_POINTER_LOCK_FREE`]

+ [Indicate whether `atomic<T *>` is lock-free]

+ ]

+ [

+ [`BOOST_ATOMIC_THREAD_FENCE`]

+ [Indicate whether `atomic_thread_fence` function is lock-free]

+ ]

+ [

+ [`BOOST_ATOMIC_SIGNAL_FENCE`]

+ [Indicate whether `atomic_signal_fence` function is lock-free]

+ ]

+]

+

+In addition to these standard macros, [*Boost.Atomic] also defines a number of extension macros,

+which can also be useful. Like the standard ones, these macros are defined to values `0`, `1` and `2`

+to indicate whether the corresponding operations are lock-free or not.

+

+[table

+ [[Macro] [Description]]

+ [

+ [`BOOST_ATOMIC_INT8_LOCK_FREE`]

+ [Indicate whether `atomic<int8_type>` is lock-free.]

+ ]

+ [

+ [`BOOST_ATOMIC_INT16_LOCK_FREE`]

+ [Indicate whether `atomic<int16_type>` is lock-free.]

+ ]

+ [

+ [`BOOST_ATOMIC_INT32_LOCK_FREE`]

+ [Indicate whether `atomic<int32_type>` is lock-free.]

+ ]

+ [

+ [`BOOST_ATOMIC_INT64_LOCK_FREE`]

+ [Indicate whether `atomic<int64_type>` is lock-free.]

+ ]

+ [

+ [`BOOST_ATOMIC_INT128_LOCK_FREE`]

+ [Indicate whether `atomic<int128_type>` is lock-free.]

+ ]

+ [

+ [`BOOST_ATOMIC_NO_ATOMIC_FLAG_INIT`]

+ [Defined after including `atomic_flag.hpp`, if the implementation

+ does not support the `BOOST_ATOMIC_FLAG_INIT` macro for static

+ initialization of `atomic_flag`. This macro is typically defined

+ for pre-C++11 compilers.]

+ ]

+]

+

+In the table above, `intN_type` is a type that fits storage of contiguous `N` bits, suitably aligned for atomic operations.

+

+[endsect]

+

+[endsect]

+

+[section:usage_examples Usage examples]

+

+[include examples.qbk]

+

+[endsect]

+

+[/

+[section:platform_support Implementing support for additional platforms]

+

+[include platform.qbk]

+

+[endsect]

+]

+

+[/ [xinclude autodoc.xml] ]

+

+[section:limitations Limitations]

+

+While [*Boost.Atomic] strives to implement the atomic operations

+from C++11 as faithfully as possible, there are a few

+limitations that cannot be lifted without compiler support:

+

+* [*Using non-POD-classes as template parameter to `atomic<T>` results

+ in undefined behavior]: This means that any class containing a

+ constructor, destructor, virtual methods or access control

+ specifications is not a valid argument in C++98. C++11 relaxes

+ this slightly by allowing "trivial" classes containing only

+ empty constructors. [*Advise]: Use only POD types.

+* [*C++98 compilers may transform computation- to control-dependency]:

+ Crucially, `memory_order_consume` only affects computationally-dependent

+ operations, but in general there is nothing preventing a compiler

+ from transforming a computation dependency into a control dependency.

+ A C++11 compiler would be forbidden from such a transformation.

+ [*Advise]: Use `memory_order_consume` only in conjunction with

+ pointer values, as the compiler cannot speculate and transform

+ these into control dependencies.

+* [*Fence operations enforce "too strong" compiler ordering]:

+ Semantically, `memory_order_acquire`/`memory_order_consume`

+ and `memory_order_release` need to restrain reordering of

+ memory operations only in one direction. Since there is no

+ way to express this constraint to the compiler, these act

+ as "full compiler barriers" in this implementation. In corner

+ cases this may result in a less efficient code than a C++11 compiler

+ could generate.

+* [*No interprocess fallback]: using `atomic<T>` in shared memory only works

+ correctly, if `atomic<T>::is_lock_free() == true`.

+

+[endsect]

+

+[section:porting Porting]

+

+[section:unit_tests Unit tests]

+

+[*Boost.Atomic] provides a unit test suite to verify that the

+implementation behaves as expected:

+

+* [*fallback_api.cpp] verifies that the fallback-to-locking aspect

+ of [*Boost.Atomic] compiles and has correct value semantics.

+* [*native_api.cpp] verifies that all atomic operations have correct

+ value semantics (e.g. "fetch_add" really adds the desired value,

+ returning the previous). It is a rough "smoke-test" to help weed

+ out the most obvious mistakes (for example width overflow,

+ signed/unsigned extension, ...).

+* [*lockfree.cpp] verifies that the [*BOOST_ATOMIC_*_LOCKFREE] macros

+ are set properly according to the expectations for a given

+ platform, and that they match up with the [*is_lock_free] member

+ functions of the [*atomic] object instances.

+* [*atomicity.cpp] lets two threads race against each other modifying

+ a shared variable, verifying that the operations behave atomic

+ as appropriate. By nature, this test is necessarily stochastic, and

+ the test self-calibrates to yield 99% confidence that a

+ positive result indicates absence of an error. This test is

+ very useful on uni-processor systems with preemption already.

+* [*ordering.cpp] lets two threads race against each other accessing

+ multiple shared variables, verifying that the operations

+ exhibit the expected ordering behavior. By nature, this test is

+ necessarily stochastic, and the test attempts to self-calibrate to

+ yield 99% confidence that a positive result indicates absence

+ of an error. This only works on true multi-processor (or multi-core)

+ systems. It does not yield any result on uni-processor systems

+ or emulators (due to there being no observable reordering even

+ the order=relaxed case) and will report that fact.

+

+[endsect]

+

+[section:tested_compilers Tested compilers]

+

+[*Boost.Atomic] has been tested on and is known to work on

+the following compilers/platforms:

+

+* gcc 4.x: i386, x86_64, ppc32, ppc64, sparcv9, armv6, alpha

+* Visual Studio Express 2008/Windows XP, x86, x64, ARM

+

+[endsect]

+

+[section:acknowledgements Acknowledgements]

+

+* Adam Wulkiewicz created the logo used on the [@https://github.com/boostorg/atomic GitHub project page]. The logo was taken from his [@https://github.com/awulkiew/boost-logos collection] of Boost logos.

+

+[endsect]

+

+[endsect]