From 8a11172d6b7707818142861f9405faeec7768af6 Mon Sep 17 00:00:00 2001 From: Michal Budzynski Date: Fri, 15 Sep 2017 14:51:44 +0200 Subject: [PATCH 1/3] stabilized compiler_fences (fixes #41091) --- .../src/library-features/compiler-fences.md | 106 ------------------ src/libcore/sync/atomic.rs | 2 +- 2 files changed, 1 insertion(+), 107 deletions(-) delete mode 100644 src/doc/unstable-book/src/library-features/compiler-fences.md diff --git a/src/doc/unstable-book/src/library-features/compiler-fences.md b/src/doc/unstable-book/src/library-features/compiler-fences.md deleted file mode 100644 index b1e36ab13d5..00000000000 --- a/src/doc/unstable-book/src/library-features/compiler-fences.md +++ /dev/null @@ -1,106 +0,0 @@ -# `compiler_fences` - -The tracking issue for this feature is: [#41091] - -[#41091]: https://github.com/rust-lang/rust/issues/41091 - ------------------------- - -The `compiler_fences` feature exposes the `compiler_fence` function -in `std::sync::atomic`. This function is conceptually similar to C++'s -`atomic_signal_fence`, which can currently only be accessed in nightly -Rust using the `atomic_singlethreadfence_*` instrinsic functions in -`core`, or through the mostly equivalent literal assembly: - -```rust -#![feature(asm)] -unsafe { asm!("" ::: "memory" : "volatile") }; -``` - -A `compiler_fence` 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 are required. - -## Examples - -`compiler_fence` is generally only useful for preventing a thread from -racing *with itself*. That is, if a given thread is executing one piece -of code, and is then interrupted, and starts executing code elsewhere -(while still in the same thread, and conceptually still on the same -core). In traditional programs, this can only occur when a signal -handler is registered. In more low-level code, such situations can also -arise when handling interrupts, when implementing green threads with -pre-emption, etc. - -To give a straightforward example of when a `compiler_fence` is -necessary, consider the following example: - -```rust -# use std::sync::atomic::{AtomicBool, AtomicUsize}; -# use std::sync::atomic::{ATOMIC_BOOL_INIT, ATOMIC_USIZE_INIT}; -# use std::sync::atomic::Ordering; -static IMPORTANT_VARIABLE: AtomicUsize = ATOMIC_USIZE_INIT; -static IS_READY: AtomicBool = ATOMIC_BOOL_INIT; - -fn main() { - IMPORTANT_VARIABLE.store(42, Ordering::Relaxed); - IS_READY.store(true, Ordering::Relaxed); -} - -fn signal_handler() { - if IS_READY.load(Ordering::Relaxed) { - assert_eq!(IMPORTANT_VARIABLE.load(Ordering::Relaxed), 42); - } -} -``` - -The way it is currently written, the `assert_eq!` is *not* guaranteed to -succeed, despite everything happening in a single thread. To see why, -remember that the compiler is free to swap the stores to -`IMPORTANT_VARIABLE` and `IS_READ` since they are both -`Ordering::Relaxed`. If it does, and the signal handler is invoked right -after `IS_READY` is updated, then the signal handler will see -`IS_READY=1`, but `IMPORTANT_VARIABLE=0`. - -Using a `compiler_fence`, we can remedy this situation: - -```rust -#![feature(compiler_fences)] -# use std::sync::atomic::{AtomicBool, AtomicUsize}; -# use std::sync::atomic::{ATOMIC_BOOL_INIT, ATOMIC_USIZE_INIT}; -# use std::sync::atomic::Ordering; -use std::sync::atomic::compiler_fence; - -static IMPORTANT_VARIABLE: AtomicUsize = ATOMIC_USIZE_INIT; -static IS_READY: AtomicBool = ATOMIC_BOOL_INIT; - -fn main() { - IMPORTANT_VARIABLE.store(42, Ordering::Relaxed); - // prevent earlier writes from being moved beyond this point - compiler_fence(Ordering::Release); - IS_READY.store(true, Ordering::Relaxed); -} - -fn signal_handler() { - if IS_READY.load(Ordering::Relaxed) { - assert_eq!(IMPORTANT_VARIABLE.load(Ordering::Relaxed), 42); - } -} -``` - -A deeper discussion of compiler barriers with various re-ordering -semantics (such as `Ordering::SeqCst`) is beyond the scope of this text. -Curious readers are encouraged to read the Linux kernel's discussion of -[memory barriers][1], the C++ references on [`std::memory_order`][2] and -[`atomic_signal_fence`][3], and [this StackOverflow answer][4] for -further details. - -[1]: https://www.kernel.org/doc/Documentation/memory-barriers.txt -[2]: http://en.cppreference.com/w/cpp/atomic/memory_order -[3]: http://www.cplusplus.com/reference/atomic/atomic_signal_fence/ -[4]: http://stackoverflow.com/a/18454971/472927 diff --git a/src/libcore/sync/atomic.rs b/src/libcore/sync/atomic.rs index 09f3586a8c9..c6291630a35 100644 --- a/src/libcore/sync/atomic.rs +++ b/src/libcore/sync/atomic.rs @@ -1703,7 +1703,7 @@ pub fn fence(order: Ordering) { /// [`AcqRel`]: enum.Ordering.html#variant.AcqRel /// [`Relaxed`]: enum.Ordering.html#variant.Relaxed #[inline] -#[unstable(feature = "compiler_fences", issue = "41091")] +#[stable(feature = "compiler_fences", since = "1.22.0")] pub fn compiler_fence(order: Ordering) { unsafe { match order { From 9a60bb077c02d424b1031fc4ea93712dda111f2e Mon Sep 17 00:00:00 2001 From: Michal Budzynski Date: Fri, 15 Sep 2017 17:03:09 +0200 Subject: [PATCH 2/3] Added example to `compiler_fence` docs taken from unstable-book --- src/libcore/sync/atomic.rs | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/src/libcore/sync/atomic.rs b/src/libcore/sync/atomic.rs index c6291630a35..8e4625b7159 100644 --- a/src/libcore/sync/atomic.rs +++ b/src/libcore/sync/atomic.rs @@ -1695,6 +1695,40 @@ pub fn fence(order: Ordering) { /// /// Panics if `order` is [`Relaxed`]. /// +/// # Examples +/// +/// Without `compiler_fence`, the `assert_eq!` in following code +/// is *not* guaranteed to succeed, despite everything happening in a single thread. +/// To see why, remember that the compiler is free to swap the stores to +/// `IMPORTANT_VARIABLE` and `IS_READ` since they are both +/// `Ordering::Relaxed`. If it does, and the signal handler is invoked right +/// after `IS_READY` is updated, then the signal handler will see +/// `IS_READY=1`, but `IMPORTANT_VARIABLE=0`. +/// Using a `compiler_fence` remedies this situation. +/// +/// ``` +/// use std::sync::atomic::{AtomicBool, AtomicUsize}; +/// use std::sync::atomic::{ATOMIC_BOOL_INIT, ATOMIC_USIZE_INIT}; +/// use std::sync::atomic::Ordering; +/// use std::sync::atomic::compiler_fence; +/// +/// static IMPORTANT_VARIABLE: AtomicUsize = ATOMIC_USIZE_INIT; +/// static IS_READY: AtomicBool = ATOMIC_BOOL_INIT; +/// +/// fn main() { +/// IMPORTANT_VARIABLE.store(42, Ordering::Relaxed); +/// // prevent earlier writes from being moved beyond this point +/// compiler_fence(Ordering::Release); +/// IS_READY.store(true, Ordering::Relaxed); +/// } +/// +/// fn signal_handler() { +/// if IS_READY.load(Ordering::Relaxed) { +/// assert_eq!(IMPORTANT_VARIABLE.load(Ordering::Relaxed), 42); +/// } +/// } +/// ``` +/// /// [`fence`]: fn.fence.html /// [`Ordering`]: enum.Ordering.html /// [`Acquire`]: enum.Ordering.html#variant.Acquire From 5f62c0c8649a61fb304466e90325a042f8c40449 Mon Sep 17 00:00:00 2001 From: Michal Budzynski Date: Sat, 16 Sep 2017 22:16:49 +0200 Subject: [PATCH 3/3] Added more text from unstable-book to `compiler_fence` docs --- src/libcore/sync/atomic.rs | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/src/libcore/sync/atomic.rs b/src/libcore/sync/atomic.rs index 8e4625b7159..3dd08e69710 100644 --- a/src/libcore/sync/atomic.rs +++ b/src/libcore/sync/atomic.rs @@ -1679,10 +1679,14 @@ pub fn fence(order: Ordering) { /// A compiler memory fence. /// -/// `compiler_fence` does not emit any machine code, but prevents the compiler from re-ordering -/// memory operations across this point. Which reorderings are disallowed is dictated by the given -/// [`Ordering`]. Note that `compiler_fence` does *not* introduce inter-thread memory -/// synchronization; for that, a [`fence`] is needed. +/// `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. /// /// The re-ordering prevented by the different ordering semantics are: /// @@ -1691,6 +1695,16 @@ pub fn fence(order: Ordering) { /// - with [`Acquire`], subsequent reads and writes cannot be moved ahead of preceding reads. /// - with [`AcqRel`], both of the above rules are enforced. /// +/// `compiler_fence` is generally only useful for preventing a thread from +/// racing *with itself*. That is, if a given thread is executing one piece +/// of code, and is then interrupted, and starts executing code elsewhere +/// (while still in the same thread, and conceptually still on the same +/// core). In traditional programs, this can only occur when a signal +/// handler is registered. In more low-level code, such situations can also +/// arise when handling interrupts, when implementing green threads with +/// pre-emption, etc. Curious readers are encouraged to read the Linux kernel's +/// discussion of [memory barriers]. +/// /// # Panics /// /// Panics if `order` is [`Relaxed`]. @@ -1736,6 +1750,7 @@ pub fn fence(order: Ordering) { /// [`Release`]: enum.Ordering.html#variant.Release /// [`AcqRel`]: enum.Ordering.html#variant.AcqRel /// [`Relaxed`]: enum.Ordering.html#variant.Relaxed +/// [memory barriers]: https://www.kernel.org/doc/Documentation/memory-barriers.txt #[inline] #[stable(feature = "compiler_fences", since = "1.22.0")] pub fn compiler_fence(order: Ordering) {