diff --git a/library/core/src/sync/atomic.rs b/library/core/src/sync/atomic.rs index 9b1b13e7129ee..7afd3f8097533 100644 --- a/library/core/src/sync/atomic.rs +++ b/library/core/src/sync/atomic.rs @@ -1113,15 +1113,12 @@ impl AtomicBool { /// Returns a mutable pointer to the underlying [`bool`]. /// - /// Doing non-atomic reads and writes on the resulting boolean can be a data race. - /// This method is mostly useful for FFI, where the function signature may use - /// `*mut bool` instead of `&AtomicBool`. + /// Note that doing non-atomic reads or writes on the resulting integer can be + /// Undefined Behavior due to a data race; see the [memory model section] for further information. /// - /// Returning an `*mut` pointer from a shared reference to this atomic is safe because the - /// atomic types work with interior mutability. All modifications of an atomic change the value - /// through a shared reference, and can do so safely as long as they use atomic operations. Any - /// use of the returned raw pointer requires an `unsafe` block and still has to uphold the same - /// restriction: operations on it must be atomic. + /// This method is mostly useful for FFI, where the function signature may use + /// `*mut bool` instead of `&AtomicBool`. All modifications of an atomic change the value + /// through a shared reference, and can do so safely as long as they use atomic operations. /// /// # Examples /// @@ -1134,11 +1131,14 @@ impl AtomicBool { /// } /// /// let mut atomic = AtomicBool::new(true); + /// + /// // SAFETY: `my_atomic_op` only uses atomic operations so it will not lead to a data race. /// unsafe { /// my_atomic_op(atomic.as_ptr()); /// } /// # } /// ``` + /// [memory model section]: self#memory-model-for-atomic-accesses #[inline] #[stable(feature = "atomic_as_ptr", since = "1.70.0")] #[rustc_const_stable(feature = "atomic_as_ptr", since = "1.70.0")] @@ -2306,15 +2306,12 @@ impl AtomicPtr { /// Returns a mutable pointer to the underlying pointer. /// - /// Doing non-atomic reads and writes on the resulting pointer can be a data race. - /// This method is mostly useful for FFI, where the function signature may use - /// `*mut *mut T` instead of `&AtomicPtr`. + /// Note that doing non-atomic reads or writes on the resulting integer can be + /// Undefined Behavior due to a data race; see the [memory model section] for further information. /// - /// Returning an `*mut` pointer from a shared reference to this atomic is safe because the - /// atomic types work with interior mutability. All modifications of an atomic change the value - /// through a shared reference, and can do so safely as long as they use atomic operations. Any - /// use of the returned raw pointer requires an `unsafe` block and still has to uphold the same - /// restriction: operations on it must be atomic. + /// This method is mostly useful for FFI, where the function signature may use + /// `*mut *mut T` instead of `&AtomicPtr`. All modifications of an atomic change the value + /// through a shared reference, and can do so safely as long as they use atomic operations. /// /// # Examples /// @@ -2333,6 +2330,7 @@ impl AtomicPtr { /// my_atomic_op(atomic.as_ptr()); /// } /// ``` + /// [memory model section]: self#memory-model-for-atomic-accesses #[inline] #[stable(feature = "atomic_as_ptr", since = "1.70.0")] #[rustc_const_stable(feature = "atomic_as_ptr", since = "1.70.0")] @@ -3398,15 +3396,13 @@ macro_rules! atomic_int { /// Returns a mutable pointer to the underlying integer. /// - /// Doing non-atomic reads and writes on the resulting integer can be a data race. + /// Note that doing non-atomic reads or writes on the resulting integer can be + /// Undefined Behavior due to a data race; see the [memory model section] for further information. + /// /// This method is mostly useful for FFI, where the function signature may use #[doc = concat!("`*mut ", stringify!($int_type), "` instead of `&", stringify!($atomic_type), "`.")] - /// - /// Returning an `*mut` pointer from a shared reference to this atomic is safe because the - /// atomic types work with interior mutability. All modifications of an atomic change the value - /// through a shared reference, and can do so safely as long as they use atomic operations. Any - /// use of the returned raw pointer requires an `unsafe` block and still has to uphold the same - /// restriction: operations on it must be atomic. + /// All modifications of an atomic change the value through a shared reference, and can do so safely + /// as long as they use atomic operations. /// /// # Examples /// @@ -3420,12 +3416,13 @@ macro_rules! atomic_int { /// #[doc = concat!("let atomic = ", stringify!($atomic_type), "::new(1);")] /// - /// // SAFETY: Safe as long as `my_atomic_op` is atomic. + /// // SAFETY: `my_atomic_op` only uses atomic operations so it will not lead to a data race. /// unsafe { /// my_atomic_op(atomic.as_ptr()); /// } /// # } /// ``` + /// [memory model section]: self#memory-model-for-atomic-accesses #[inline] #[stable(feature = "atomic_as_ptr", since = "1.70.0")] #[rustc_const_stable(feature = "atomic_as_ptr", since = "1.70.0")]