Rollup merge of #53022 - RalfJung:volatile, r=alexcrichton

volatile operations docs: clarify that this does not help wrt. concurrency

Triggered by https://github.com/rust-lang/rust/pull/52391. Cc @stjepang @Amanieu

Should the intrinsics themselves also get more documentation? They generally do not seem to have much of that.

1 files changed, 30 insertions, 0 deletions

diff --git a/src/libcore/ptr.rs b/src/libcore/ptr.rs
index 479c10c4ffb..c8670e5ec34 100644
--- a/src/libcore/ptr.rs
+++ b/src/libcore/ptr.rs
@@ -448,6 +448,12 @@ pub unsafe fn write_unaligned<T>(dst: *mut T, src: T) {
 /// `write_bytes`, or `copy`). Note that `*src = foo` counts as a use
 /// because it will attempt to drop the value previously at `*src`.
 ///
+/// Just like in C, whether an operation is volatile has no bearing whatsoever
+/// on questions involving concurrent access from multiple threads. Volatile
+/// accesses behave exactly like non-atomic accesses in that regard. In particular,
+/// a race between a `read_volatile` and any write operation to the same location
+/// is undefined behavior.
+///
 /// # Examples
 ///
 /// Basic usage:
@@ -498,6 +504,12 @@ pub unsafe fn read_volatile<T>(src: *const T) -> T {
 /// This is appropriate for initializing uninitialized memory, or overwriting
 /// memory that has previously been `read` from.
 ///
+/// Just like in C, whether an operation is volatile has no bearing whatsoever
+/// on questions involving concurrent access from multiple threads. Volatile
+/// accesses behave exactly like non-atomic accesses in that regard. In particular,
+/// a race between a `write_volatile` and any other operation (reading or writing)
+/// on the same location is undefined behavior.
+///
 /// # Examples
 ///
 /// Basic usage:
@@ -1057,6 +1069,12 @@ impl<T: ?Sized> *const T {
     /// `write_bytes`, or `copy`). Note that `*self = foo` counts as a use
     /// because it will attempt to drop the value previously at `*self`.
     ///
+    /// Just like in C, whether an operation is volatile has no bearing whatsoever
+    /// on questions involving concurrent access from multiple threads. Volatile
+    /// accesses behave exactly like non-atomic accesses in that regard. In particular,
+    /// a race between a `read_volatile` and any write operation to the same location
+    /// is undefined behavior.
+    ///
     /// # Examples
     ///
     /// Basic usage:
@@ -1790,6 +1808,12 @@ impl<T: ?Sized> *mut T {
     /// `write_bytes`, or `copy`). Note that `*self = foo` counts as a use
     /// because it will attempt to drop the value previously at `*self`.
     ///
+    /// Just like in C, whether an operation is volatile has no bearing whatsoever
+    /// on questions involving concurrent access from multiple threads. Volatile
+    /// accesses behave exactly like non-atomic accesses in that regard. In particular,
+    /// a race between a `read_volatile` and any write operation to the same location
+    /// is undefined behavior.
+    ///
     /// # Examples
     ///
     /// Basic usage:
@@ -2105,6 +2129,12 @@ impl<T: ?Sized> *mut T {
     /// This is appropriate for initializing uninitialized memory, or overwriting
     /// memory that has previously been `read` from.
     ///
+    /// Just like in C, whether an operation is volatile has no bearing whatsoever
+    /// on questions involving concurrent access from multiple threads. Volatile
+    /// accesses behave exactly like non-atomic accesses in that regard. In particular,
+    /// a race between a `write_volatile` and any other operation (reading or writing)
+    /// on the same location is undefined behavior.
+    ///
     /// # Examples
     ///
     /// Basic usage: