Auto merge of #34046 - Vtec234:fix-atomic-doc, r=steveklabnik

Fix wrong statement in compare_exchange doc

The documentation for `core::sync::atomic::AtomicSomething::compare_exchange` contains a wrong, or imprecise, statement about the return value. It goes:

The return value is a result indicating whether the new value was written and containing
the previous value. On success this value is guaranteed to be equal to `new`.

In the second sentence, `this value` is gramatically understood as referring to `return value` from the first sentence. Due to how CAS works, the returned value is always what was in the atomic variable _before_ the operation occurred, not what was written into it during the operation. Hence, the fixed doc should say:

The return value is a result indicating whether the new value was written and containing
the previous value. On success this value is guaranteed to be equal to `current`.

This version is confirmed by the runnable examples in variants of `AtomicSomething`, e.g.

    assert_eq!(some_bool.compare_exchange(true, false, Ordering::Acquire, Ordering::Relaxed),
    Ok(true));

where the returned value is `Ok(current)`. This PR fixes all occurrences of this bug I could find.

An alternative solution would be to modify the second sentence so that it refers to the value _written_ into the Atomic rather than what was there before, in which case it would be correct. Example alternative formulation:

On success the value written into the `bool`/`usize`/`whatever` is guaranteed to be equal to `new`.

r? @steveklabnik

0 files changed, 0 insertions, 0 deletions