core::atomic docs: what guarantees hold when compare_and_swap returns other values?

[pnkfelix]

The documentation for the various compare_and_swap methods (there's one each for AtomicBool, AtomicIsize, and AtomicUsize) says:

    /// If the return value is equal to `old` then the value was updated.

But it says nothing about other return values.

In particular, it does not say if the return value actually corresponds to a value that had been stored at some point in the memory. For all that this says, maybe its going to return old + 1 or !old, rather than the contents of memory at the time that the failed swap was attempted.

So right now, if I want to be portable and follow these docs, I need to issue a separate call to the load method to load a current value, e.g. if my plan is to loop around and recompute the next value I want to store from the concurrently updated current value.

---

Now, maybe this is not an oversight in the documentation, but is in fact a deliberate underspecification of the return value for compare_and_swap -- i.e. maybe we do not want to guarantee too much about the underling behavior of the target system.

But in my opinion, a return value that is so woefully underspecified is no better than returning a boolean flag indicating whether the swap was successful or not.

And in any case, if this is a deliberate underspecification on the part of the documentation, then it should explicitly say something like "when the value is not updated, then the return value will be unequal to old, but is otherwise unspecified." (Because right now it is very easy for a reader to infer that the "currently stored" value that is unequal to old is what is returned.)

[ranma42]

Some code in libstd seems to assume that compare_and_swap will always return the original value of the atomic entity.

Examples:

• https://github.com/rust-lang/rust/blob/master/src/libstd/sync/condvar.rs#L323

• https://github.com/rust-lang/rust/blob/master/src/libstd/sync/mpsc/oneshot.rs#L287

• https://github.com/rust-lang/rust/blob/master/src/libstd/sync/mpsc/oneshot.rs#L334

• https://github.com/rust-lang/rust/blob/master/src/libstd/sync/mpsc/shared.rs#L364

• https://github.com/rust-lang/rust/blob/master/src/libstd/sync/mpsc/stream.rs#L308

  This would be consistent with the definition of the cmpxchg LLVM instruction:

  The contents of memory at the location specified by the ‘‘ operand is read and compared to ‘‘; if the read value is the equal, the ‘‘ is written. The original value at the location is returned, together with a flag indicating success (true) or failure (false).

My understanding is that the same semantics holds for compare_and_swap in Rust, except that no flag is returned.

[steveklabnik]

@pnkfelix who do you think i should ask about clarifying this behavior?

[alexcrichton]

The semantics (just forgotten to be documented) are what @ranma42 pointed out. The previous value is always returned.