| Home | Libraries | People | FAQ | More

## Programming interfaces

### Memory order

The enumeration `boost::memory_order` defines the following values to represent memory ordering constraints:

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
`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 restrictive (and usually 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 additional enforces total order for all operations such qualified.

See section happens-before for explanation of the various ordering constraints.

### Atomic objects

`boost::atomic<T>` provides methods for atomically accessing variables of a suitable type `T`. The type is suitable if it satisfies one of the following constraints:

- it is an integer, boolean, enum or pointer type
- it is any other data-type (`class` or `struct`) that has a non-throwing default constructor, that is copyable via `memcpy` and comparable via `memcmp`.

Note that all classes having a trivial default constructor, no destructor and no virtual methods satisfy the second condition according to C++98. On a given platform, other data-types may also satisfy this constraint, however you should exercise caution as the behaviour becomes implementation-defined. Also be warned that structures with "padding" between data members may compare non-equal via `memcmp` even though all members are equal.

#### `boost::atomic<T>` template class

All atomic objects supports the following operations:

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.

#### `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:

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.

#### `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:

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.

### Fences

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).

### Feature testing macros

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:

Macro | Description
--- | ---
`BOOST_ATOMIC_CHAR_LOCK_FREE` | Indicate whether `atomic<char>` (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` | Indicate whether `atomic<T *>` is lock-free