/// Stores a value into the bool, returning the previous value.
///
/// `swap` takes an [`Ordering`] argument which describes the memory ordering
- /// of this operation.
+ /// of this operation. All ordering modes are possible. Note that using
+ /// [`Acquire`] makes the store part of this operation [`Relaxed`], and
+ /// using [`Release`] makes the load part [`Relaxed`].
///
/// [`Ordering`]: enum.Ordering.html
+ /// [`Relaxed`]: enum.Ordering.html#variant.Relaxed
+ /// [`Release`]: enum.Ordering.html#variant.Release
+ /// [`Acquire`]: enum.Ordering.html#variant.Acquire
///
/// # Examples
///
/// `compare_and_swap` also takes an [`Ordering`] argument which describes the memory
/// ordering of this operation. Notice that even when using [`AcqRel`], the operation
/// might fail and hence just perform an `Acquire` load, but not have `Release` semantics.
+ /// Using [`Acquire`] makes the store part of this operation [`Relaxed`] if it
+ /// happens, and using [`Release`] makes the load part [`Relaxed`].
///
/// [`Ordering`]: enum.Ordering.html
+ /// [`Relaxed`]: enum.Ordering.html#variant.Relaxed
+ /// [`Release`]: enum.Ordering.html#variant.Release
+ /// [`Acquire`]: enum.Ordering.html#variant.Acquire
/// [`AcqRel`]: enum.Ordering.html#variant.AcqRel
/// [`bool`]: ../../../std/primitive.bool.html
///
/// `compare_exchange` takes two [`Ordering`] arguments to describe the memory
/// ordering of this operation. The first describes the required ordering if the
/// operation succeeds while the second describes the required ordering when the
- /// operation fails. The failure ordering can't be [`Release`] or [`AcqRel`] and must
- /// be equivalent to or weaker than the success ordering.
+ /// operation fails. Using [`Acquire`] as success ordering makes the store part
+ /// of this operation [`Relaxed`], and using [`Release`] makes the successful load
+ /// [`Relaxed`]. The failure ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`]
+ /// and must be equivalent to or weaker than the success ordering.
+ ///
///
/// [`bool`]: ../../../std/primitive.bool.html
/// [`Ordering`]: enum.Ordering.html
+ /// [`Relaxed`]: enum.Ordering.html#variant.Relaxed
/// [`Release`]: enum.Ordering.html#variant.Release
- /// [`AcqRel`]: enum.Ordering.html#variant.Release
+ /// [`Acquire`]: enum.Ordering.html#variant.Acquire
+ /// [`SeqCst`]: enum.Ordering.html#variant.SeqCst
///
/// # Examples
///
/// previous value.
///
/// `compare_exchange_weak` takes two [`Ordering`] arguments to describe the memory
- /// ordering of this operation. The first describes the required ordering if the operation
- /// succeeds while the second describes the required ordering when the operation fails. The
- /// failure ordering can't be [`Release`] or [`AcqRel`] and must be equivalent or
- /// weaker than the success ordering.
+ /// ordering of this operation. The first describes the required ordering if the
+ /// operation succeeds while the second describes the required ordering when the
+ /// operation fails. Using [`Acquire`] as success ordering makes the store part
+ /// of this operation [`Relaxed`], and using [`Release`] makes the successful load
+ /// [`Relaxed`]. The failure ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`]
+ /// and must be equivalent to or weaker than the success ordering.
///
/// [`bool`]: ../../../std/primitive.bool.html
/// [`compare_exchange`]: #method.compare_exchange
/// [`Ordering`]: enum.Ordering.html
+ /// [`Relaxed`]: enum.Ordering.html#variant.Relaxed
/// [`Release`]: enum.Ordering.html#variant.Release
- /// [`AcqRel`]: enum.Ordering.html#variant.Release
+ /// [`Acquire`]: enum.Ordering.html#variant.Acquire
+ /// [`SeqCst`]: enum.Ordering.html#variant.SeqCst
///
/// # Examples
///
///
/// Returns the previous value.
///
+ /// `fetch_and` takes an [`Ordering`] argument which describes the memory ordering
+ /// of this operation. All ordering modes are possible. Note that using
+ /// [`Acquire`] makes the store part of this operation [`Relaxed`], and
+ /// using [`Release`] makes the load part [`Relaxed`].
+ ///
+ /// [`Ordering`]: enum.Ordering.html
+ /// [`Relaxed`]: enum.Ordering.html#variant.Relaxed
+ /// [`Release`]: enum.Ordering.html#variant.Release
+ /// [`Acquire`]: enum.Ordering.html#variant.Acquire
+ ///
/// # Examples
///
/// ```
///
/// Returns the previous value.
///
+ /// `fetch_nand` takes an [`Ordering`] argument which describes the memory ordering
+ /// of this operation. All ordering modes are possible. Note that using
+ /// [`Acquire`] makes the store part of this operation [`Relaxed`], and
+ /// using [`Release`] makes the load part [`Relaxed`].
+ ///
+ /// [`Ordering`]: enum.Ordering.html
+ /// [`Relaxed`]: enum.Ordering.html#variant.Relaxed
+ /// [`Release`]: enum.Ordering.html#variant.Release
+ /// [`Acquire`]: enum.Ordering.html#variant.Acquire
+ ///
/// # Examples
///
/// ```
///
/// Returns the previous value.
///
+ /// `fetch_or` takes an [`Ordering`] argument which describes the memory ordering
+ /// of this operation. All ordering modes are possible. Note that using
+ /// [`Acquire`] makes the store part of this operation [`Relaxed`], and
+ /// using [`Release`] makes the load part [`Relaxed`].
+ ///
+ /// [`Ordering`]: enum.Ordering.html
+ /// [`Relaxed`]: enum.Ordering.html#variant.Relaxed
+ /// [`Release`]: enum.Ordering.html#variant.Release
+ /// [`Acquire`]: enum.Ordering.html#variant.Acquire
+ ///
/// # Examples
///
/// ```
///
/// Returns the previous value.
///
+ /// `fetch_xor` takes an [`Ordering`] argument which describes the memory ordering
+ /// of this operation. All ordering modes are possible. Note that using
+ /// [`Acquire`] makes the store part of this operation [`Relaxed`], and
+ /// using [`Release`] makes the load part [`Relaxed`].
+ ///
+ /// [`Ordering`]: enum.Ordering.html
+ /// [`Relaxed`]: enum.Ordering.html#variant.Relaxed
+ /// [`Release`]: enum.Ordering.html#variant.Release
+ /// [`Acquire`]: enum.Ordering.html#variant.Acquire
+ ///
/// # Examples
///
/// ```
/// Stores a value into the pointer, returning the previous value.
///
/// `swap` takes an [`Ordering`] argument which describes the memory ordering
- /// of this operation.
+ /// of this operation. All ordering modes are possible. Note that using
+ /// [`Acquire`] makes the store part of this operation [`Relaxed`], and
+ /// using [`Release`] makes the load part [`Relaxed`].
///
/// [`Ordering`]: enum.Ordering.html
+ /// [`Relaxed`]: enum.Ordering.html#variant.Relaxed
+ /// [`Release`]: enum.Ordering.html#variant.Release
+ /// [`Acquire`]: enum.Ordering.html#variant.Acquire
///
/// # Examples
///
/// `compare_and_swap` also takes an [`Ordering`] argument which describes the memory
/// ordering of this operation. Notice that even when using [`AcqRel`], the operation
/// might fail and hence just perform an `Acquire` load, but not have `Release` semantics.
+ /// Using [`Acquire`] makes the store part of this operation [`Relaxed`] if it
+ /// happens, and using [`Release`] makes the load part [`Relaxed`].
///
/// [`Ordering`]: enum.Ordering.html
+ /// [`Relaxed`]: enum.Ordering.html#variant.Relaxed
+ /// [`Release`]: enum.Ordering.html#variant.Release
+ /// [`Acquire`]: enum.Ordering.html#variant.Acquire
+ /// [`AcqRel`]: enum.Ordering.html#variant.AcqRel
///
/// # Examples
///
/// the previous value. On success this value is guaranteed to be equal to `current`.
///
/// `compare_exchange` takes two [`Ordering`] arguments to describe the memory
- /// ordering of this operation. The first describes the required ordering if
- /// the operation succeeds while the second describes the required ordering when
- /// the operation fails. The failure ordering can't be [`Release`] or [`AcqRel`]
- /// and must be equivalent or weaker than the success ordering.
+ /// ordering of this operation. The first describes the required ordering if the
+ /// operation succeeds while the second describes the required ordering when the
+ /// operation fails. Using [`Acquire`] as success ordering makes the store part
+ /// of this operation [`Relaxed`], and using [`Release`] makes the successful load
+ /// [`Relaxed`]. The failure ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`]
+ /// and must be equivalent to or weaker than the success ordering.
///
/// [`Ordering`]: enum.Ordering.html
+ /// [`Relaxed`]: enum.Ordering.html#variant.Relaxed
/// [`Release`]: enum.Ordering.html#variant.Release
- /// [`AcqRel`]: enum.Ordering.html#variant.AcqRel
+ /// [`Acquire`]: enum.Ordering.html#variant.Acquire
+ /// [`SeqCst`]: enum.Ordering.html#variant.SeqCst
///
/// # Examples
///
/// previous value.
///
/// `compare_exchange_weak` takes two [`Ordering`] arguments to describe the memory
- /// ordering of this operation. The first describes the required ordering if the operation
- /// succeeds while the second describes the required ordering when the operation fails. The
- /// failure ordering can't be [`Release`] or [`AcqRel`] and must be equivalent or
- /// weaker than the success ordering.
+ /// ordering of this operation. The first describes the required ordering if the
+ /// operation succeeds while the second describes the required ordering when the
+ /// operation fails. Using [`Acquire`] as success ordering makes the store part
+ /// of this operation [`Relaxed`], and using [`Release`] makes the successful load
+ /// [`Relaxed`]. The failure ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`]
+ /// and must be equivalent to or weaker than the success ordering.
///
/// [`compare_exchange`]: #method.compare_exchange
/// [`Ordering`]: enum.Ordering.html
+ /// [`Relaxed`]: enum.Ordering.html#variant.Relaxed
/// [`Release`]: enum.Ordering.html#variant.Release
- /// [`AcqRel`]: enum.Ordering.html#variant.AcqRel
+ /// [`Acquire`]: enum.Ordering.html#variant.Acquire
+ /// [`SeqCst`]: enum.Ordering.html#variant.SeqCst
///
/// # Examples
///
doc_comment! {
concat!("Stores a value into the atomic integer, returning the previous value.
-`swap` takes an [`Ordering`] argument which describes the memory ordering of this operation.
+`swap` takes an [`Ordering`] argument which describes the memory ordering
+of this operation. All ordering modes are possible. Note that using
+[`Acquire`] makes the store part of this operation [`Relaxed`], and
+using [`Release`] makes the load part [`Relaxed`].
[`Ordering`]: enum.Ordering.html
+[`Relaxed`]: enum.Ordering.html#variant.Relaxed
+[`Release`]: enum.Ordering.html#variant.Release
+[`Acquire`]: enum.Ordering.html#variant.Acquire
# Examples
`compare_and_swap` also takes an [`Ordering`] argument which describes the memory
ordering of this operation. Notice that even when using [`AcqRel`], the operation
might fail and hence just perform an `Acquire` load, but not have `Release` semantics.
+Using [`Acquire`] makes the store part of this operation [`Relaxed`] if it
+happens, and using [`Release`] makes the load part [`Relaxed`].
[`Ordering`]: enum.Ordering.html
+[`Relaxed`]: enum.Ordering.html#variant.Relaxed
+[`Release`]: enum.Ordering.html#variant.Release
+[`Acquire`]: enum.Ordering.html#variant.Acquire
+[`AcqRel`]: enum.Ordering.html#variant.AcqRel
# Examples
`current`.
`compare_exchange` takes two [`Ordering`] arguments to describe the memory
-ordering of this operation. The first describes the required ordering if
-the operation succeeds while the second describes the required ordering when
-the operation fails. The failure ordering can't be [`Release`] or [`AcqRel`] and
-must be equivalent or weaker than the success ordering.
+ordering of this operation. The first describes the required ordering if the
+operation succeeds while the second describes the required ordering when the
+operation fails. Using [`Acquire`] as success ordering makes the store part
+of this operation [`Relaxed`], and using [`Release`] makes the successful load
+[`Relaxed`]. The failure ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`]
+and must be equivalent to or weaker than the success ordering.
[`Ordering`]: enum.Ordering.html
+[`Relaxed`]: enum.Ordering.html#variant.Relaxed
[`Release`]: enum.Ordering.html#variant.Release
-[`AcqRel`]: enum.Ordering.html#variant.AcqRel
+[`Acquire`]: enum.Ordering.html#variant.Acquire
+[`SeqCst`]: enum.Ordering.html#variant.SeqCst
# Examples
`compare_exchange_weak` takes two [`Ordering`] arguments to describe the memory
ordering of this operation. The first describes the required ordering if the
operation succeeds while the second describes the required ordering when the
-operation fails. The failure ordering can't be [`Release`] or [`AcqRel`] and
-must be equivalent or weaker than the success ordering.
+operation fails. Using [`Acquire`] as success ordering makes the store part
+of this operation [`Relaxed`], and using [`Release`] makes the successful load
+[`Relaxed`]. The failure ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`]
+and must be equivalent to or weaker than the success ordering.
[`compare_exchange`]: #method.compare_exchange
[`Ordering`]: enum.Ordering.html
+[`Relaxed`]: enum.Ordering.html#variant.Relaxed
[`Release`]: enum.Ordering.html#variant.Release
-[`AcqRel`]: enum.Ordering.html#variant.AcqRel
+[`Acquire`]: enum.Ordering.html#variant.Acquire
+[`SeqCst`]: enum.Ordering.html#variant.SeqCst
# Examples
This operation wraps around on overflow.
+`fetch_add` takes an [`Ordering`] argument which describes the memory ordering
+of this operation. All ordering modes are possible. Note that using
+[`Acquire`] makes the store part of this operation [`Relaxed`], and
+using [`Release`] makes the load part [`Relaxed`].
+
+[`Ordering`]: enum.Ordering.html
+[`Relaxed`]: enum.Ordering.html#variant.Relaxed
+[`Release`]: enum.Ordering.html#variant.Release
+[`Acquire`]: enum.Ordering.html#variant.Acquire
+
# Examples
```
This operation wraps around on overflow.
+`fetch_sub` takes an [`Ordering`] argument which describes the memory ordering
+of this operation. All ordering modes are possible. Note that using
+[`Acquire`] makes the store part of this operation [`Relaxed`], and
+using [`Release`] makes the load part [`Relaxed`].
+
+[`Ordering`]: enum.Ordering.html
+[`Relaxed`]: enum.Ordering.html#variant.Relaxed
+[`Release`]: enum.Ordering.html#variant.Release
+[`Acquire`]: enum.Ordering.html#variant.Acquire
+
# Examples
```
Returns the previous value.
+`fetch_and` takes an [`Ordering`] argument which describes the memory ordering
+of this operation. All ordering modes are possible. Note that using
+[`Acquire`] makes the store part of this operation [`Relaxed`], and
+using [`Release`] makes the load part [`Relaxed`].
+
+[`Ordering`]: enum.Ordering.html
+[`Relaxed`]: enum.Ordering.html#variant.Relaxed
+[`Release`]: enum.Ordering.html#variant.Release
+[`Acquire`]: enum.Ordering.html#variant.Acquire
+
# Examples
```
Returns the previous value.
+`fetch_nand` takes an [`Ordering`] argument which describes the memory ordering
+of this operation. All ordering modes are possible. Note that using
+[`Acquire`] makes the store part of this operation [`Relaxed`], and
+using [`Release`] makes the load part [`Relaxed`].
+
+[`Ordering`]: enum.Ordering.html
+[`Relaxed`]: enum.Ordering.html#variant.Relaxed
+[`Release`]: enum.Ordering.html#variant.Release
+[`Acquire`]: enum.Ordering.html#variant.Acquire
+
# Examples
```
Returns the previous value.
+`fetch_or` takes an [`Ordering`] argument which describes the memory ordering
+of this operation. All ordering modes are possible. Note that using
+[`Acquire`] makes the store part of this operation [`Relaxed`], and
+using [`Release`] makes the load part [`Relaxed`].
+
+[`Ordering`]: enum.Ordering.html
+[`Relaxed`]: enum.Ordering.html#variant.Relaxed
+[`Release`]: enum.Ordering.html#variant.Release
+[`Acquire`]: enum.Ordering.html#variant.Acquire
+
# Examples
```
Returns the previous value.
+`fetch_xor` takes an [`Ordering`] argument which describes the memory ordering
+of this operation. All ordering modes are possible. Note that using
+[`Acquire`] makes the store part of this operation [`Relaxed`], and
+using [`Release`] makes the load part [`Relaxed`].
+
+[`Ordering`]: enum.Ordering.html
+[`Relaxed`]: enum.Ordering.html#variant.Relaxed
+[`Release`]: enum.Ordering.html#variant.Release
+[`Acquire`]: enum.Ordering.html#variant.Acquire
+
# Examples
```
the meantime, as long as the function returns `Some(_)`, but the function will have been applied
but once to the stored value.
+`fetch_update` takes two [`Ordering`] arguments to describe the memory
+ordering of this operation. The first describes the required ordering for loads
+and failed updates while the second describes the required ordering when the
+operation finally succeeds. Beware that this is different from the two
+modes in [`compare_exchange`]!
+
+Using [`Acquire`] as success ordering makes the store part
+of this operation [`Relaxed`], and using [`Release`] makes the final successful load
+[`Relaxed`]. The (failed) load ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`]
+and must be equivalent to or weaker than the success ordering.
+
+[`bool`]: ../../../std/primitive.bool.html
+[`compare_exchange`]: #method.compare_exchange
+[`Ordering`]: enum.Ordering.html
+[`Relaxed`]: enum.Ordering.html#variant.Relaxed
+[`Release`]: enum.Ordering.html#variant.Release
+[`Acquire`]: enum.Ordering.html#variant.Acquire
+[`SeqCst`]: enum.Ordering.html#variant.SeqCst
+
# Examples
```rust
Returns the previous value.
+`fetch_max` takes an [`Ordering`] argument which describes the memory ordering
+of this operation. All ordering modes are possible. Note that using
+[`Acquire`] makes the store part of this operation [`Relaxed`], and
+using [`Release`] makes the load part [`Relaxed`].
+
+[`Ordering`]: enum.Ordering.html
+[`Relaxed`]: enum.Ordering.html#variant.Relaxed
+[`Release`]: enum.Ordering.html#variant.Release
+[`Acquire`]: enum.Ordering.html#variant.Acquire
+
# Examples
```
Returns the previous value.
+`fetch_min` takes an [`Ordering`] argument which describes the memory ordering
+of this operation. All ordering modes are possible. Note that using
+[`Acquire`] makes the store part of this operation [`Relaxed`], and
+using [`Release`] makes the load part [`Relaxed`].
+
+[`Ordering`]: enum.Ordering.html
+[`Relaxed`]: enum.Ordering.html#variant.Relaxed
+[`Release`]: enum.Ordering.html#variant.Release
+[`Acquire`]: enum.Ordering.html#variant.Acquire
+
# Examples
```