From addd05ec29a59fde43e58b4b07b0df2d7d68f37b Mon Sep 17 00:00:00 2001
From: Ralf Jung
Date: Wed, 7 Aug 2024 14:30:26 +0200
Subject: [PATCH] atomics: allow atomic and non-atomic reads to race
---
core/src/sync/atomic.rs | 62 +++++++++++++++++++++++++----------------
1 file changed, 38 insertions(+), 24 deletions(-)
diff --git a/core/src/sync/atomic.rs b/core/src/sync/atomic.rs
index b06a3bd4487d3..b3fe99f7f1a15 100644
--- a/core/src/sync/atomic.rs
+++ b/core/src/sync/atomic.rs
@@ -24,26 +24,37 @@
//!
//! ## Memory model for atomic accesses
//!
-//! Rust atomics currently follow the same rules as [C++20 atomics][cpp], specifically `atomic_ref`.
-//! Basically, creating a *shared reference* to one of the Rust atomic types corresponds to creating
-//! an `atomic_ref` in C++; the `atomic_ref` is destroyed when the lifetime of the shared reference
-//! ends. A Rust atomic type that is exclusively owned or behind a mutable reference does *not*
-//! correspond to an “atomic object†in C++, since the underlying primitive can be mutably accessed,
-//! for example with `get_mut`, to perform non-atomic operations.
+//! Rust atomics currently follow the same rules as [C++20 atomics][cpp], specifically the rules
+//! from the [`intro.races`][cpp-intro.races] section, without the "consume" memory ordering. Since
+//! C++ uses an object-based memory model whereas Rust is access-based, a bit of translation work
+//! has to be done to apply the C++ rules to Rust: whenever C++ talks about "the value of an
+//! object", we understand that to mean the resulting bytes obtained when doing a read. When the C++
+//! standard talks about "the value of an atomic object", this refers to the result of doing an
+//! atomic load (via the operations provided in this module). A "modification of an atomic object"
+//! refers to an atomic store.
+//!
+//! The end result is *almost* equivalent to saying that creating a *shared reference* to one of the
+//! Rust atomic types corresponds to creating an `atomic_ref` in C++, with the `atomic_ref` being
+//! destroyed when the lifetime of the shared reference ends. The main difference is that Rust
+//! permits concurrent atomic and non-atomic reads to the same memory as those cause no issue in the
+//! C++ memory model, they are just forbidden in C++ because memory is partitioned into "atomic
+//! objects" and "non-atomic objects" (with `atomic_ref` temporarily converting a non-atomic object
+//! into an atomic object).
+//!
+//! That said, Rust *does* inherit the C++ limitation that non-synchronized atomic accesses may not
+//! partially overlap: they must be either disjoint or access the exact same memory. This in
+//! particular rules out non-synchronized differently-sized accesses to the same data.
//!
//! [cpp]: https://en.cppreference.com/w/cpp/atomic
+//! [cpp-intro.races]: https://timsong-cpp.github.io/cppwp/n4868/intro.multithread#intro.races
//!
//! Each method takes an [`Ordering`] which represents the strength of
-//! the memory barrier for that operation. These orderings are the
-//! same as the [C++20 atomic orderings][1]. For more information see the [nomicon][2].
+//! the memory barrier for that operation. These orderings behave the
+//! same as the corresponding [C++20 atomic orderings][1]. For more information see the [nomicon][2].
//!
//! [1]: https://en.cppreference.com/w/cpp/atomic/memory_order
//! [2]: ../../../nomicon/atomics.html
//!
-//! Since C++ does not support mixing atomic and non-atomic accesses, or non-synchronized
-//! different-sized accesses to the same data, Rust does not support those operations either.
-//! Note that both of those restrictions only apply if the accesses are non-synchronized.
-//!
//! ```rust,no_run undefined_behavior
//! use std::sync::atomic::{AtomicU16, AtomicU8, Ordering};
//! use std::mem::transmute;
@@ -52,27 +63,30 @@
//! let atomic = AtomicU16::new(0);
//!
//! thread::scope(|s| {
-//! // This is UB: mixing atomic and non-atomic accesses
-//! s.spawn(|| atomic.store(1, Ordering::Relaxed));
-//! s.spawn(|| unsafe { atomic.as_ptr().write(2) });
+//! // This is UB: conflicting concurrent accesses.
+//! s.spawn(|| atomic.store(1, Ordering::Relaxed)); // atomic store
+//! s.spawn(|| unsafe { atomic.as_ptr().write(2) }); // non-atomic write
//! });
//!
//! thread::scope(|s| {
-//! // This is UB: even reads are not allowed to be mixed
-//! s.spawn(|| atomic.load(Ordering::Relaxed));
-//! s.spawn(|| unsafe { atomic.as_ptr().read() });
+//! // This is fine: the accesses do not conflict (as none of them performs any modification).
+//! // In C++ this would be disallowed since creating an `atomic_ref` precludes
+//! // further non-atomic accesses, but Rust does not have that limitation.
+//! s.spawn(|| atomic.load(Ordering::Relaxed)); // atomic load
+//! s.spawn(|| unsafe { atomic.as_ptr().read() }); // non-atomic read
//! });
//!
//! thread::scope(|s| {
//! // This is fine, `join` synchronizes the code in a way such that atomic
-//! // and non-atomic accesses can't happen "at the same time"
-//! let handle = s.spawn(|| atomic.store(1, Ordering::Relaxed));
-//! handle.join().unwrap();
-//! s.spawn(|| unsafe { atomic.as_ptr().write(2) });
+//! // and non-atomic accesses can't happen "at the same time".
+//! let handle = s.spawn(|| atomic.store(1, Ordering::Relaxed)); // atomic store
+//! handle.join().unwrap(); // synchronize
+//! s.spawn(|| unsafe { atomic.as_ptr().write(2) }); // non-atomic write
//! });
//!
//! thread::scope(|s| {
-//! // This is UB: using different-sized atomic accesses to the same data
+//! // This is UB: using differently-sized atomic accesses to the same data.
+//! // (It would be UB even if these are both loads.)
//! s.spawn(|| atomic.store(1, Ordering::Relaxed));
//! s.spawn(|| unsafe {
//! let differently_sized = transmute::<&AtomicU16, &AtomicU8>(&atomic);
@@ -82,7 +96,7 @@
//!
//! thread::scope(|s| {
//! // This is fine, `join` synchronizes the code in a way such that
-//! // differently-sized accesses can't happen "at the same time"
+//! // differently-sized accesses can't happen "at the same time".
//! let handle = s.spawn(|| atomic.store(1, Ordering::Relaxed));
//! handle.join().unwrap();
//! s.spawn(|| unsafe {