compiler_fence documentation is misleading

[RalfJung]

The current docs for compiler_fence explain that function in terms of reorderings:

compiler_fence does not emit any machine code, but restricts the kinds of memory re-ordering the compiler is allowed to do. Specifically, depending on the given Ordering semantics, the compiler may be disallowed from moving reads or writes from before or after the call to the other side of the call to compiler_fence. Note that it does not prevent the hardware from doing such re-ordering. This is not a problem in a single-threaded, execution context, but when other threads may modify memory at the same time, stronger synchronization primitives such as fence are required.

That's somewhat misleading. For good reasons, our fence docs quickly transition from "reordering" to "synchronization" terminology:

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.

compiler_fence should also be explained in terms of synchronizes-with, to avoid raising any false expectations. Specifically, compiler_fence is equivalent to C++ atomic_signal_fence, and so its synchronization rules are very similar to those of fence except that synchronization only occurs between a thread and its signal handler, not across different threads.

Cc @rust-lang/libs-api @rust-lang/opsem
Cc rust-lang/unsafe-code-guidelines#347 #54962

[jieyouxu]

(Sorry, race condition...)