From 2598e4574e9136690add3cef55fbb8ac7356f3d2 Mon Sep 17 00:00:00 2001
From: Jon Gjengset <jon@thesquareplanet.com>
Date: Wed, 5 Apr 2017 15:33:24 -0400
Subject: Add safe wrapper for atomic_singlethreadfence_*

---
 src/libcore/sync/atomic.rs | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

(limited to 'src/libcore/sync')

diff --git a/src/libcore/sync/atomic.rs b/src/libcore/sync/atomic.rs
index ae47e6fdfa9..948edda832b 100644
--- a/src/libcore/sync/atomic.rs
+++ b/src/libcore/sync/atomic.rs
@@ -1572,6 +1572,47 @@ pub fn fence(order: Ordering) {
 }
 
 
+/// A compiler memory barrier.
+///
+/// `compiler_barrier` 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_barrier` does *not* introduce inter-thread memory
+/// synchronization; for that, a [`fence`] is needed.
+///
+/// The re-ordering prevented by the different ordering semantics are:
+///
+///  - with [`SeqCst`], no re-ordering of reads and writes across this point is allowed.
+///  - with [`Release`], preceding reads and writes cannot be moved past subsequent writes.
+///  - with [`Acquire`], subsequent reads and writes cannot be moved ahead of preceding reads.
+///  - with [`AcqRel`], both of the above rules are enforced.
+///
+/// # Panics
+///
+/// Panics if `order` is [`Relaxed`].
+///
+/// [`fence`]: fn.fence.html
+/// [`Ordering`]: enum.Ordering.html
+/// [`Acquire`]: enum.Ordering.html#variant.Acquire
+/// [`SeqCst`]: enum.Ordering.html#variant.SeqCst
+/// [`Release`]: enum.Ordering.html#variant.Release
+/// [`AcqRel`]: enum.Ordering.html#variant.AcqRel
+/// [`Relaxed`]: enum.Ordering.html#variant.Relaxed
+#[inline]
+#[unstable(feature = "std_compiler_fences", issue = "41091")]
+pub fn compiler_barrier(order: Ordering) {
+    unsafe {
+        match order {
+            Acquire => intrinsics::atomic_singlethreadfence_acq(),
+            Release => intrinsics::atomic_singlethreadfence_rel(),
+            AcqRel => intrinsics::atomic_singlethreadfence_acqrel(),
+            SeqCst => intrinsics::atomic_singlethreadfence(),
+            Relaxed => panic!("there is no such thing as a relaxed barrier"),
+            __Nonexhaustive => panic!("invalid memory ordering"),
+        }
+    }
+}
+
+
 #[cfg(target_has_atomic = "8")]
 #[stable(feature = "atomic_debug", since = "1.3.0")]
 impl fmt::Debug for AtomicBool {
-- 
cgit 1.4.1-3-g733a5


From f6d262a326b3a44954773fed6983215b62fe4862 Mon Sep 17 00:00:00 2001
From: Jon Gjengset <jon@thesquareplanet.com>
Date: Wed, 5 Apr 2017 21:39:43 -0400
Subject: Add unstable book entry

---
 src/doc/unstable-book/src/SUMMARY.md           |  1 +
 src/doc/unstable-book/src/compiler-barriers.md | 98 ++++++++++++++++++++++++++
 src/libcore/sync/atomic.rs                     |  2 +-
 3 files changed, 100 insertions(+), 1 deletion(-)
 create mode 100644 src/doc/unstable-book/src/compiler-barriers.md

(limited to 'src/libcore/sync')

diff --git a/src/doc/unstable-book/src/SUMMARY.md b/src/doc/unstable-book/src/SUMMARY.md
index 292f5a1ec81..68f31ca75e0 100644
--- a/src/doc/unstable-book/src/SUMMARY.md
+++ b/src/doc/unstable-book/src/SUMMARY.md
@@ -37,6 +37,7 @@
 - [collections](collections.md)
 - [collections_range](collections-range.md)
 - [command_envs](command-envs.md)
+- [compiler_barriers](compiler-barriers.md)
 - [compiler_builtins](compiler-builtins.md)
 - [compiler_builtins_lib](compiler-builtins-lib.md)
 - [concat_idents](concat-idents.md)
diff --git a/src/doc/unstable-book/src/compiler-barriers.md b/src/doc/unstable-book/src/compiler-barriers.md
new file mode 100644
index 00000000000..84190dab327
--- /dev/null
+++ b/src/doc/unstable-book/src/compiler-barriers.md
@@ -0,0 +1,98 @@
+# `compiler_barriers`
+
+The tracking issue for this feature is: [#41092]
+
+[#41092]: https://github.com/rust-lang/rust/issues/41092
+
+------------------------
+
+The `compiler_barriers` feature exposes the `compiler_barrier` 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_barrier` 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_barrier`.
+
+## Examples
+
+The need to prevent re-ordering of reads and writes often arises when
+working with low-level devices. Consider a piece of code that interacts
+with an ethernet card with a set of internal registers that are accessed
+through an address port register (`a: &mut usize`) and a data port
+register (`d: &usize`). To read internal register 5, the following code
+might then be used:
+
+```rust
+fn read_fifth(a: &mut usize, d: &usize) -> usize {
+    *a = 5;
+    *d
+}
+```
+
+In this case, the compiler is free to re-order these two statements if
+it thinks doing so might result in better performance, register use, or
+anything else compilers care about. However, in doing so, it would break
+the code, as `x` would be set to the value of some other device
+register!
+
+By inserting a compiler barrier, we can force the compiler to not
+re-arrange these two statements, making the code function correctly
+again:
+
+```rust
+#![feature(compiler_barriers)]
+use std::sync::atomic;
+
+fn read_fifth(a: &mut usize, d: &usize) -> usize {
+    *a = 5;
+    atomic::compiler_barrier(atomic::Ordering::SeqCst);
+    *d
+}
+```
+
+Compiler barriers are also useful in code that implements low-level
+synchronization primitives. Consider a structure with two different
+atomic variables, with a dependency chain between them:
+
+```rust
+use std::sync::atomic;
+
+fn thread1(x: &atomic::AtomicUsize, y: &atomic::AtomicUsize) {
+    x.store(1, atomic::Ordering::Release);
+    let v1 = y.load(atomic::Ordering::Acquire);
+}
+fn thread2(x: &atomic::AtomicUsize, y: &atomic::AtomicUsize) {
+    y.store(1, atomic::Ordering::Release);
+    let v2 = x.load(atomic::Ordering::Acquire);
+}
+```
+
+This code will guarantee that `thread1` sees any writes to `y` made by
+`thread2`, and that `thread2` sees any writes to `x`. Intuitively, one
+might also expect that if `thread2` sees `v2 == 0`, `thread1` must see
+`v1 == 1` (since `thread2`'s store happened before its `load`, and its
+load did not see `thread1`'s store). However, the code as written does
+*not* guarantee this, because the compiler is allowed to re-order the
+store and load within each thread. To enforce this particular behavior,
+a call to `compiler_barrier(Ordering::SeqCst)` would need to be inserted
+between the `store` and `load` in both functions.
+
+Compiler barriers with weaker re-ordering semantics (such as
+`Ordering::Acquire`) can also be useful, but are beyond the scope of
+this text. Curious readers are encouraged to read the Linux kernel's
+discussion of [memory barriers][1], as well as C++ references on
+[`std::memory_order`][2] and [`atomic_signal_fence`][3].
+
+[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/
diff --git a/src/libcore/sync/atomic.rs b/src/libcore/sync/atomic.rs
index 948edda832b..8cf1d1d54a5 100644
--- a/src/libcore/sync/atomic.rs
+++ b/src/libcore/sync/atomic.rs
@@ -1598,7 +1598,7 @@ pub fn fence(order: Ordering) {
 /// [`AcqRel`]: enum.Ordering.html#variant.AcqRel
 /// [`Relaxed`]: enum.Ordering.html#variant.Relaxed
 #[inline]
-#[unstable(feature = "std_compiler_fences", issue = "41091")]
+#[unstable(feature = "compiler_barriers", issue = "41091")]
 pub fn compiler_barrier(order: Ordering) {
     unsafe {
         match order {
-- 
cgit 1.4.1-3-g733a5