Rollup merge of #103315 - RalfJung:interpret-switchint-ice, r=bjorn3

[rust.git] / library / core / src / sync / atomic.rs

diff --git a/library/core/src/sync/atomic.rs b/library/core/src/sync/atomic.rs
index 3c96290fc537e19bbe1e2b400a5eabf13ece5a0c..edc68d6fae51bcb03f01a099ff20b0f489af9780 100644 (file)
--- a/library/core/src/sync/atomic.rs
+++ b/library/core/src/sync/atomic.rs
@@ -294,7 +294,7 @@ impl AtomicBool {
     /// ```
     /// use std::sync::atomic::AtomicBool;
     ///
-    /// let atomic_true  = AtomicBool::new(true);
+    /// let atomic_true = AtomicBool::new(true);
     /// let atomic_false = AtomicBool::new(false);
     /// ```
     #[inline]
@@ -955,6 +955,14 @@ pub fn as_mut_ptr(&self) -> *mut bool {
     /// **Note:** This method is only available on platforms that support atomic
     /// operations on `u8`.
     ///
+    /// # Considerations
+    ///
+    /// This method is not magic;  it is not provided by the hardware.
+    /// It is implemented in terms of [`AtomicBool::compare_exchange_weak`], and suffers from the same drawbacks.
+    /// In particular, this method will not circumvent the [ABA Problem].
+    ///
+    /// [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem
+    ///
     /// # Examples
     ///
     /// ```rust
@@ -1171,7 +1179,7 @@ pub const fn into_inner(self) -> *mut T {
     /// use std::sync::atomic::{AtomicPtr, Ordering};
     ///
     /// let ptr = &mut 5;
-    /// let some_ptr  = AtomicPtr::new(ptr);
+    /// let some_ptr = AtomicPtr::new(ptr);
     ///
     /// let value = some_ptr.load(Ordering::Relaxed);
     /// ```
@@ -1198,7 +1206,7 @@ pub fn load(&self, order: Ordering) -> *mut T {
     /// use std::sync::atomic::{AtomicPtr, Ordering};
     ///
     /// let ptr = &mut 5;
-    /// let some_ptr  = AtomicPtr::new(ptr);
+    /// let some_ptr = AtomicPtr::new(ptr);
     ///
     /// let other_ptr = &mut 10;
     ///
@@ -1230,7 +1238,7 @@ pub fn store(&self, ptr: *mut T, order: Ordering) {
     /// use std::sync::atomic::{AtomicPtr, Ordering};
     ///
     /// let ptr = &mut 5;
-    /// let some_ptr  = AtomicPtr::new(ptr);
+    /// let some_ptr = AtomicPtr::new(ptr);
     ///
     /// let other_ptr = &mut 10;
     ///
@@ -1282,9 +1290,9 @@ pub fn swap(&self, ptr: *mut T, order: Ordering) -> *mut T {
     /// use std::sync::atomic::{AtomicPtr, Ordering};
     ///
     /// let ptr = &mut 5;
-    /// let some_ptr  = AtomicPtr::new(ptr);
+    /// let some_ptr = AtomicPtr::new(ptr);
     ///
-    /// let other_ptr   = &mut 10;
+    /// let other_ptr = &mut 10;
     ///
     /// let value = some_ptr.compare_and_swap(ptr, other_ptr, Ordering::Relaxed);
     /// ```
@@ -1325,9 +1333,9 @@ pub fn compare_and_swap(&self, current: *mut T, new: *mut T, order: Ordering) ->
     /// use std::sync::atomic::{AtomicPtr, Ordering};
     ///
     /// let ptr = &mut 5;
-    /// let some_ptr  = AtomicPtr::new(ptr);
+    /// let some_ptr = AtomicPtr::new(ptr);
     ///
-    /// let other_ptr   = &mut 10;
+    /// let other_ptr = &mut 10;
     ///
     /// let value = some_ptr.compare_exchange(ptr, other_ptr,
     ///                                       Ordering::SeqCst, Ordering::Relaxed);
@@ -1422,6 +1430,14 @@ pub fn compare_exchange_weak(
     /// **Note:** This method is only available on platforms that support atomic
     /// operations on pointers.
     ///
+    /// # Considerations
+    ///
+    /// This method is not magic;  it is not provided by the hardware.
+    /// It is implemented in terms of [`AtomicPtr::compare_exchange_weak`], and suffers from the same drawbacks.
+    /// In particular, this method will not circumvent the [ABA Problem].
+    ///
+    /// [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem
+    ///
     /// # Examples
     ///
     /// ```rust
@@ -1626,8 +1642,8 @@ pub fn fetch_byte_sub(&self, val: usize, order: Ordering) -> *mut T {
     /// and the argument `val`, and stores a pointer with provenance of the
     /// current pointer and the resulting address.
     ///
-    /// This is equivalent equivalent to using [`map_addr`] to atomically
-    /// perform `ptr = ptr.map_addr(|a| a | val)`. This can be used in tagged
+    /// This is equivalent to using [`map_addr`] to atomically perform
+    /// `ptr = ptr.map_addr(|a| a | val)`. This can be used in tagged
     /// pointer schemes to atomically set tag bits.
     ///
     /// **Caveat**: This operation returns the previous value. To compute the
@@ -1677,8 +1693,8 @@ pub fn fetch_or(&self, val: usize, order: Ordering) -> *mut T {
     /// pointer, and the argument `val`, and stores a pointer with provenance of
     /// the current pointer and the resulting address.
     ///
-    /// This is equivalent equivalent to using [`map_addr`] to atomically
-    /// perform `ptr = ptr.map_addr(|a| a & val)`. This can be used in tagged
+    /// This is equivalent to using [`map_addr`] to atomically perform
+    /// `ptr = ptr.map_addr(|a| a & val)`. This can be used in tagged
     /// pointer schemes to atomically unset tag bits.
     ///
     /// **Caveat**: This operation returns the previous value. To compute the
@@ -1727,8 +1743,8 @@ pub fn fetch_and(&self, val: usize, order: Ordering) -> *mut T {
     /// pointer, and the argument `val`, and stores a pointer with provenance of
     /// the current pointer and the resulting address.
     ///
-    /// This is equivalent equivalent to using [`map_addr`] to atomically
-    /// perform `ptr = ptr.map_addr(|a| a ^ val)`. This can be used in tagged
+    /// This is equivalent to using [`map_addr`] to atomically perform
+    /// `ptr = ptr.map_addr(|a| a ^ val)`. This can be used in tagged
     /// pointer schemes to atomically toggle tag bits.
     ///
     /// **Caveat**: This operation returns the previous value. To compute the
@@ -2510,6 +2526,16 @@ pub fn fetch_xor(&self, val: $int_type, order: Ordering) -> $int_type {
             /// **Note**: This method is only available on platforms that support atomic operations on
             #[doc = concat!("[`", $s_int_type, "`].")]
             ///
+            /// # Considerations
+            ///
+            /// This method is not magic;  it is not provided by the hardware.
+            /// It is implemented in terms of
+            #[doc = concat!("[`", stringify!($atomic_type), "::compare_exchange_weak`],")]
+            /// and suffers from the same drawbacks.
+            /// In particular, this method will not circumvent the [ABA Problem].
+            ///
+            /// [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem
+            ///
             /// # Examples
             ///
             /// ```rust