atomic::Ordering: Get rid of misleading parts of intro

[vorner]

Remove the parts of atomic::Ordering's intro that wrongly claimed that
SeqCst prevents all reorderings around it.

Closes#55196

This is a (minimal) alternative to #55233.

I also wonder if it would be worth adding at least some warnings that atomics are often a footgun/hard to use correctly, similarly like mem::transmute or other functions have.

[rust-highfive]

r? @bluss

(rust_highfive has picked a reviewer for you, use r? to override)

[bluss]

r? @stjepang

[ghost]

This seems correct - approving.

However, I personally don't find the intro about Relaxed and SeqCst particularly useful. It's full of jargon and lacking details:

• What does "synchronized" mean?
• What does "total order" mean?
• What is a store-load pair? How do operations pair up?
• What memory do store-load SeqCst operations synchronize?

For people who don't know about memory orderings that might sound like gibberish. :) And for people who do, it's not very informative anyway.

Just saying something equivalent to "use SeqCst if in doubt and read the LLVM docs to learn more" would be enough, I think.

[vorner]

However, I personally don't find the intro about Relaxed and SeqCst particularly useful. It's full of jargon and lacking details

Well, I tried to write something more useful in #55233 and the consensus was that such things should probably go to nomicon (and I plan on updating that eventually). So, I don't know how much I'm able to say without giving a full, digestible explanation and still be correct.

I'm open to discussing what level of explanation is appropriate here and in the nomicon. But I'd like to get rid of the wrong parts first.

Just saying something equivalent to "use SeqCst if in doubt and read the LLVM docs to learn more" would be enough, I think.

That's the other quite often given advice about atomics I quite don't like, because it is misleading. If in doubt, read the LLVM docs ‒ sure, but using SeqCst without understanding how the synchronization works is likely to lead to wrong code (eg. SeqCst on compare_and_swap that didn't swap won't publish my changes and it's a non-obvious trap).

That's what I was asking about the warning ‒ should we say something like „Don't mess with these until you read the docs and use Mutex instead“?

[ghost]

Well, I tried to write something more useful in #55233 and the consensus was that such things should probably go to nomicon (and I plan on updating that eventually).

That'd be fantastic! <3

That's the other quite often given advice about atomics I quite don't like, because it is misleading.

You're right and the pitfall of sequentially consistent CAS operations is a very good point. However, I'll be a little sad if our docs say "if you don't understand memory orderings, use mutexes".

In Java, volatile variables are just sequentially consistent atomics and I think they can be productively used by anyone without a deep understanding of memory orderings. The same applies to e.g. Go and JavaScript. Note that the docs of those languages don't even mention orderings. In C++, std::atomic is designed so that SeqCst is the default ordering for all operations and you can use it without even thinking about memory barriers. I wish atomics in Rust don't get reserved for advanced users only.

Also, I'd point out that mutexes and RW locks come with their own similar pitfalls. For example, they're not guaranteed to be sequentially consistent. Or, read operations in RW locks can elide actual locking if there's no contention. And yet, mutexes and RW locks can be used fearlessly by anyone without even understanding those words.

Anyways, just my two cents. :) This PR is good to go as far as I'm concerned. 👍

[TimNN]

@bors r=@stjepang

[bors]

📌 Commit cc63bd4 has been approved by @stjepang

[TimNN]

@bors rollup