Dangerously misleading introduction to std::sync::atomic::Ordering

[vorner]

When looking at https://doc.rust-lang.org/std/sync/atomic/enum.Ordering.html, this is in the intro:

At its most restrictive, "sequentially consistent" atomics allow neither reads nor writes to be moved either before or after the atomic operation;

This is not true (even the explanations for variants disprove this, but if someone reads only the intro, they could get to the conclusion that using SeqCst is good enough everywhere, which it actually isn't).

Eg, from the docs below:

SeqCst: Like AcqRel with the additional guarantee that all threads see all sequentially consistent operations in the same order.

AcqRel: For loads it uses Acquire ordering. For stores it uses the Release ordering.

So, atomic.load(Ordering::SeqCst) has Acquire semantics (+ participating in the global timeline of all SeqCst operations), which means reads and writes are allowed to be reordered after the operation. And even failed CAS operation is effectively just a read, so operations are allowed to be reordered after the operation.

I have the vague memory someone was updating it recently to actually point out these gotchas, but I can't find that now.

I can try rewording it, but I'm not really that good at writing good concise documentation.

[nagisa]

See also #54962

[ehuss]

The nightly docs has some updated wording from #53106.

[vorner]

It has some updated wording, but in the details below. But the intro wasn't changed there and it is still misleading. And if someone reads „SeqCst is allmighty“, they might just stop there and not read the rest.

But yes, that was the one I was referring to when I wrote about the vague memory.