src/doc/unstable-book/src/library-features/compiler-fences.md

   1 # `compiler_fences`
   2
   3 The tracking issue for this feature is: [#41091]
   4
   5 [#41091]: https://github.com/rust-lang/rust/issues/41091
   6
   7 ------------------------
   8
   9 The `compiler_fences` feature exposes the `compiler_fence` function
  10 in `std::sync::atomic`. This function is conceptually similar to C++'s
  11 `atomic_signal_fence`, which can currently only be accessed in nightly
  12 Rust using the `atomic_singlethreadfence_*` instrinsic functions in
  13 `core`, or through the mostly equivalent literal assembly:
  14
  15 ```rust
  16 #![feature(asm)]
  17 unsafe { asm!("" ::: "memory" : "volatile") };
  18 ```
  19
  20 A `compiler_fence` restricts the kinds of memory re-ordering the
  21 compiler is allowed to do. Specifically, depending on the given ordering
  22 semantics, the compiler may be disallowed from moving reads or writes
  23 from before or after the call to the other side of the call to
  24 `compiler_fence`. Note that it does **not** prevent the *hardware*
  25 from doing such re-ordering. This is not a problem in a single-threaded,
  26 execution context, but when other threads may modify memory at the same
  27 time, stronger synchronization primitives are required.
  28
  29 ## Examples
  30
  31 `compiler_fence` is generally only useful for preventing a thread from
  32 racing *with itself*. That is, if a given thread is executing one piece
  33 of code, and is then interrupted, and starts executing code elsewhere
  34 (while still in the same thread, and conceptually still on the same
  35 core). In traditional programs, this can only occur when a signal
  36 handler is registered. In more low-level code, such situations can also
  37 arise when handling interrupts, when implementing green threads with
  38 pre-emption, etc.
  39
  40 To give a straightforward example of when a `compiler_fence` is
  41 necessary, consider the following example:
  42
  43 ```rust
  44 # use std::sync::atomic::{AtomicBool, AtomicUsize};
  45 # use std::sync::atomic::{ATOMIC_BOOL_INIT, ATOMIC_USIZE_INIT};
  46 # use std::sync::atomic::Ordering;
  47 static IMPORTANT_VARIABLE: AtomicUsize = ATOMIC_USIZE_INIT;
  48 static IS_READY: AtomicBool = ATOMIC_BOOL_INIT;
  49
  50 fn main() {
  51     IMPORTANT_VARIABLE.store(42, Ordering::Relaxed);
  52     IS_READY.store(true, Ordering::Relaxed);
  53 }
  54
  55 fn signal_handler() {
  56     if IS_READY.load(Ordering::Relaxed) {
  57         assert_eq!(IMPORTANT_VARIABLE.load(Ordering::Relaxed), 42);
  58     }
  59 }
  60 ```
  61
  62 The way it is currently written, the `assert_eq!` is *not* guaranteed to
  63 succeed, despite everything happening in a single thread. To see why,
  64 remember that the compiler is free to swap the stores to
  65 `IMPORTANT_VARIABLE` and `IS_READ` since they are both
  66 `Ordering::Relaxed`. If it does, and the signal handler is invoked right
  67 after `IS_READY` is updated, then the signal handler will see
  68 `IS_READY=1`, but `IMPORTANT_VARIABLE=0`.
  69
  70 Using a `compiler_fence`, we can remedy this situation:
  71
  72 ```rust
  73 #![feature(compiler_fences)]
  74 # use std::sync::atomic::{AtomicBool, AtomicUsize};
  75 # use std::sync::atomic::{ATOMIC_BOOL_INIT, ATOMIC_USIZE_INIT};
  76 # use std::sync::atomic::Ordering;
  77 use std::sync::atomic::compiler_fence;
  78
  79 static IMPORTANT_VARIABLE: AtomicUsize = ATOMIC_USIZE_INIT;
  80 static IS_READY: AtomicBool = ATOMIC_BOOL_INIT;
  81
  82 fn main() {
  83     IMPORTANT_VARIABLE.store(42, Ordering::Relaxed);
  84     // prevent earlier writes from being moved beyond this point
  85     compiler_fence(Ordering::Release);
  86     IS_READY.store(true, Ordering::Relaxed);
  87 }
  88
  89 fn signal_handler() {
  90     if IS_READY.load(Ordering::Relaxed) {
  91         assert_eq!(IMPORTANT_VARIABLE.load(Ordering::Relaxed), 42);
  92     }
  93 }
  94 ```
  95
  96 A deeper discussion of compiler barriers with various re-ordering
  97 semantics (such as `Ordering::SeqCst`) is beyond the scope of this text.
  98 Curious readers are encouraged to read the Linux kernel's discussion of
  99 [memory barriers][1], the C++ references on [`std::memory_order`][2] and
 100 [`atomic_signal_fence`][3], and [this StackOverflow answer][4] for
 101 further details.
 102
 103 [1]: https://www.kernel.org/doc/Documentation/memory-barriers.txt
 104 [2]: http://en.cppreference.com/w/cpp/atomic/memory_order
 105 [3]: http://www.cplusplus.com/reference/atomic/atomic_signal_fence/
 106 [4]: http://stackoverflow.com/a/18454971/472927