|
24 | 24 | //! |
25 | 25 | //! ## Memory model for atomic accesses |
26 | 26 | //! |
27 | | -//! Rust atomics currently follow the same rules as [C++20 atomics][cpp], specifically `atomic_ref`. |
28 | | -//! Basically, creating a *shared reference* to one of the Rust atomic types corresponds to creating |
29 | | -//! an `atomic_ref` in C++; the `atomic_ref` is destroyed when the lifetime of the shared reference |
30 | | -//! ends. A Rust atomic type that is exclusively owned or behind a mutable reference does *not* |
31 | | -//! correspond to an “atomic object” in C++, since the underlying primitive can be mutably accessed, |
32 | | -//! for example with `get_mut`, to perform non-atomic operations. |
| 27 | +//! Rust atomics currently follow the same rules as [C++20 atomics][cpp], specifically the rules |
| 28 | +//! from the [`intro.races`][cpp-intro.races] section, without the "consume" memory ordering. Since |
| 29 | +//! C++ uses an object-based memory model whereas Rust is access-based, a bit of translation work |
| 30 | +//! has to be done to apply the C++ rules to Rust: whenever C++ talks about "the value of an |
| 31 | +//! object", we understand that to mean the resulting bytes obtained when doing a read. When the C++ |
| 32 | +//! standard talks about "the value of an atomic object", this refers to the result of doing an |
| 33 | +//! atomic load (via the operations provided in this module). A "modification of an atomic object" |
| 34 | +//! refers to an atomic store. |
33 | 35 | //! |
34 | | -//! [cpp]: https://en.cppreference.com/w/cpp/atomic |
| 36 | +//! The end result is *almost* equivalent to saying that creating a *shared reference* to one of the |
| 37 | +//! Rust atomic types corresponds to creating an `atomic_ref` in C++, with the `atomic_ref` being |
| 38 | +//! destroyed when the lifetime of the shared reference ends. The main difference is that Rust |
| 39 | +//! permits concurrent atomic and non-atomic reads to the same memory as those cause no issue in the |
| 40 | +//! C++ memory model, they are just forbidden in C++ because memory is partitioned into "atomic |
| 41 | +//! objects" and "non-atomic objects" (with `atomic_ref` temporarily converting a non-atomic object |
| 42 | +//! into an atomic object). |
| 43 | +//! |
| 44 | +//! The most important aspect of this model is that *data races* are undefined behavior. A data race |
| 45 | +//! is defined as conflicting non-synchronized accesses where at least one of the accesses is |
| 46 | +//! non-atomic. Here, accesses are *conflicting* if they affect overlapping regions of memory and at |
| 47 | +//! least one of them is a write. They are *non-synchronized* if neither of them *happens-before* |
| 48 | +//! the other, according to the happens-before order of the memory model. |
35 | 49 | //! |
36 | | -//! Each method takes an [`Ordering`] which represents the strength of |
37 | | -//! the memory barrier for that operation. These orderings are the |
38 | | -//! same as the [C++20 atomic orderings][1]. For more information see the [nomicon][2]. |
| 50 | +//! The other possible cause of undefined behavior in the memory model are mixed-size accesses: Rust |
| 51 | +//! inherits the C++ limitation that non-synchronized conflicting atomic accesses may not partially |
| 52 | +//! overlap. In other words, every pair of non-synchronized atomic accesses must be either disjoint, |
| 53 | +//! access the exact same memory (including using the same access size), or both be reads. |
39 | 54 | //! |
40 | | -//! [1]: https://en.cppreference.com/w/cpp/atomic/memory_order |
41 | | -//! [2]: ../../../nomicon/atomics.html |
| 55 | +//! Each atomic access takes an [`Ordering`] which defines how the operation interacts with the |
| 56 | +//! happens-before order. These orderings behave the same as the corresponding [C++20 atomic |
| 57 | +//! orderings][cpp_memory_order]. For more information, see the [nomicon]. |
42 | 58 | //! |
43 | | -//! Since C++ does not support mixing atomic and non-atomic accesses, or non-synchronized |
44 | | -//! different-sized accesses to the same data, Rust does not support those operations either. |
45 | | -//! Note that both of those restrictions only apply if the accesses are non-synchronized. |
| 59 | +//! [cpp]: https://en.cppreference.com/w/cpp/atomic |
| 60 | +//! [cpp-intro.races]: https://timsong-cpp.github.io/cppwp/n4868/intro.multithread#intro.races |
| 61 | +//! [cpp_memory_order]: https://en.cppreference.com/w/cpp/atomic/memory_order |
| 62 | +//! [nomicon]: ../../../nomicon/atomics.html |
46 | 63 | //! |
47 | 64 | //! ```rust,no_run undefined_behavior |
48 | 65 | //! use std::sync::atomic::{AtomicU16, AtomicU8, Ordering}; |
|
52 | 69 | //! let atomic = AtomicU16::new(0); |
53 | 70 | //! |
54 | 71 | //! thread::scope(|s| { |
55 | | -//! // This is UB: mixing atomic and non-atomic accesses |
56 | | -//! s.spawn(|| atomic.store(1, Ordering::Relaxed)); |
57 | | -//! s.spawn(|| unsafe { atomic.as_ptr().write(2) }); |
| 72 | +//! // This is UB: conflicting non-synchronized accesses, at least one of which is non-atomic. |
| 73 | +//! s.spawn(|| atomic.store(1, Ordering::Relaxed)); // atomic store |
| 74 | +//! s.spawn(|| unsafe { atomic.as_ptr().write(2) }); // non-atomic write |
58 | 75 | //! }); |
59 | 76 | //! |
60 | 77 | //! thread::scope(|s| { |
61 | | -//! // This is UB: even reads are not allowed to be mixed |
62 | | -//! s.spawn(|| atomic.load(Ordering::Relaxed)); |
63 | | -//! s.spawn(|| unsafe { atomic.as_ptr().read() }); |
| 78 | +//! // This is fine: the accesses do not conflict (as none of them performs any modification). |
| 79 | +//! // In C++ this would be disallowed since creating an `atomic_ref` precludes |
| 80 | +//! // further non-atomic accesses, but Rust does not have that limitation. |
| 81 | +//! s.spawn(|| atomic.load(Ordering::Relaxed)); // atomic load |
| 82 | +//! s.spawn(|| unsafe { atomic.as_ptr().read() }); // non-atomic read |
64 | 83 | //! }); |
65 | 84 | //! |
66 | 85 | //! thread::scope(|s| { |
67 | | -//! // This is fine, `join` synchronizes the code in a way such that atomic |
68 | | -//! // and non-atomic accesses can't happen "at the same time" |
69 | | -//! let handle = s.spawn(|| atomic.store(1, Ordering::Relaxed)); |
70 | | -//! handle.join().unwrap(); |
71 | | -//! s.spawn(|| unsafe { atomic.as_ptr().write(2) }); |
| 86 | +//! // This is fine: `join` synchronizes the code in a way such that the atomic |
| 87 | +//! // store happens-before the non-atomic write. |
| 88 | +//! let handle = s.spawn(|| atomic.store(1, Ordering::Relaxed)); // atomic store |
| 89 | +//! handle.join().unwrap(); // synchronize |
| 90 | +//! s.spawn(|| unsafe { atomic.as_ptr().write(2) }); // non-atomic write |
72 | 91 | //! }); |
73 | 92 | //! |
74 | 93 | //! thread::scope(|s| { |
75 | | -//! // This is UB: using different-sized atomic accesses to the same data |
| 94 | +//! // This is UB: non-synchronized conflicting differently-sized atomic accesses. |
76 | 95 | //! s.spawn(|| atomic.store(1, Ordering::Relaxed)); |
77 | 96 | //! s.spawn(|| unsafe { |
78 | 97 | //! let differently_sized = transmute::<&AtomicU16, &AtomicU8>(&atomic); |
|
81 | 100 | //! }); |
82 | 101 | //! |
83 | 102 | //! thread::scope(|s| { |
84 | | -//! // This is fine, `join` synchronizes the code in a way such that |
85 | | -//! // differently-sized accesses can't happen "at the same time" |
| 103 | +//! // This is fine: `join` synchronizes the code in a way such that |
| 104 | +//! // the 1-byte store happens-before the 2-byte store. |
86 | 105 | //! let handle = s.spawn(|| atomic.store(1, Ordering::Relaxed)); |
87 | 106 | //! handle.join().unwrap(); |
88 | 107 | //! s.spawn(|| unsafe { |
|
137 | 156 | //! |
138 | 157 | //! # Atomic accesses to read-only memory |
139 | 158 | //! |
140 | | -//! In general, *all* atomic accesses on read-only memory are Undefined Behavior. For instance, attempting |
| 159 | +//! In general, *all* atomic accesses on read-only memory are undefined behavior. For instance, attempting |
141 | 160 | //! to do a `compare_exchange` that will definitely fail (making it conceptually a read-only |
142 | 161 | //! operation) can still cause a segmentation fault if the underlying memory page is mapped read-only. Since |
143 | 162 | //! atomic `load`s might be implemented using compare-exchange operations, even a `load` can fault |
|
153 | 172 | //! |
154 | 173 | //! As an exception from the general rule stated above, "sufficiently small" atomic loads with |
155 | 174 | //! `Ordering::Relaxed` are implemented in a way that works on read-only memory, and are hence not |
156 | | -//! Undefined Behavior. The exact size limit for what makes a load "sufficiently small" varies |
| 175 | +//! undefined behavior. The exact size limit for what makes a load "sufficiently small" varies |
157 | 176 | //! depending on the target: |
158 | 177 | //! |
159 | 178 | //! | `target_arch` | Size limit | |
|
0 commit comments