Change:
/// An atomic fence. /// <del> /// Depending on the specified order, a fence prevents the compiler and CPU from /// reordering certain types of memory operations around it. /// That creates synchronizes-with relationships between it and atomic operations /// or fences in other threads. </del> <ins> /// Fences create synchronization between themselves and atomic operations or fences in other /// threads. To achieve this, a fence prevents the compiler and CPU from reordering certain types of /// memory operations around it. </ins> /// /// A fence 'A' which has (at least) [`Release`] ordering semantics, synchronizes /// with a fence 'B' with (at least) [`Acquire`] semantics, if and only if there

Discussion:
The current docs for  explain that function in terms of reorderings: That's somewhat misleading. For good reasons, our  docs quickly transition from "reordering" to "synchronization" terminology: should also be explained in terms of synchronizes-with, to avoid raising any false expectations. Specifically, compilerfence is equivalent to C++ , and so its synchronization rules are very similar to those of except that synchronization only occurs between a thread and its signal handler, not across different threads. Cc Cc
(Sorry, race condition...)

The documentation for with say "no re-ordering of reads and writes across this point is allowed". As I understand it, for a single thread doesn't give anything more than . E.g., a store before the fence could be moved past a load after then fence. Is that correct? cc
Hmm, that's a good point, though the details are a little subtle. From the : I think what this translates into is that guarantees that: no subsequent operations can be moved before this operation if it is a load, and no operations can be moved after this operation if it is a store. The italic parts there aren't present in the current documentation, so that should probably be rectified. I think some annotated source code would really help here!
It actually depends on the other operation, does it not? stores after the fence can be moved up, but stores cannot. TBH I have a hard time thinking in terms of reorderings; I usually think in terms of what actually happens in the underlying memory model. Some of these models can be fully characterized by the allowed reorderings, but not all of them can (as far as we know). And anyway, SC fences are broken in the C11 memory model and probably going to change in the next version, so...^^ On top of that, all are in a total order, and that is the entire point of . (The website says it but you left it away in your quote. Just making sure nobody thinks that a load is the same as an load. It is not.)
I'm actually not entirely sure about that. Another store to the same memory location shouldn't be ordered before, but I don't see from the reference text why an unrelated store with couldn't be. I'd be happy for this to be rephrased this in terms of the memory model, but I'm not entirely sure how we'd even do that. Proposals welcome. I think talking about what can and cannot happen, with examples, is probably the most understandable way to present what the different orderings do. I left off the total order part because it didn't seem directly related to the original question. But you're right that it's a vital part of that shouldn't get lost in the docs!

It says The sequentially-consistent ordering consists of all operation, across all locations, and the order in which they are observed must be consistent across all threads. In particular, if one thread performs two operations (i.e., they are ordered by program-order), then the order in which it does them must match the order in which every other thread observes them. That rules out reordering them. This is the sole justification for the existence of .
Yes, good point. So how about we move the bullet point to bottom and change it to say