From 3209d2d46e4ce3a8216c0a54fb9dd8baafe73586 Mon Sep 17 00:00:00 2001 From: Trevor Gross Date: Sat, 9 Sep 2023 15:56:42 -0400 Subject: [PATCH 1/2] Correct documentation for `atomic_from_ptr` * Remove duplicate alignment note that mentioned `AtomicBool` with other types * Update safety requirements about when non-atomic operations are allowed --- library/core/src/sync/atomic.rs | 43 +++++++++++++++++++++++++++------ 1 file changed, 36 insertions(+), 7 deletions(-) diff --git a/library/core/src/sync/atomic.rs b/library/core/src/sync/atomic.rs index cf1fbe2d389d7..3cb8f9f424105 100644 --- a/library/core/src/sync/atomic.rs +++ b/library/core/src/sync/atomic.rs @@ -346,9 +346,17 @@ impl AtomicBool { /// /// # Safety /// - /// * `ptr` must be aligned to `align_of::()` (note that on some platforms this can be bigger than `align_of::()`). + /// * `ptr` must be aligned to `align_of::()` (note that on some platforms this can + /// be bigger than `align_of::()`). /// * `ptr` must be [valid] for both reads and writes for the whole lifetime `'a`. - /// * The value behind `ptr` must not be accessed through non-atomic operations for the whole lifetime `'a`. + /// * Non-atomic accesses to the value behind `ptr` must have a happens-before relationship + /// with atomic accesses via the returned value (or vice-versa). + /// * In other words, time periods where the value is accessed atomically may not overlap + /// with periods where the value is accessed non-atomically. + /// * This requirement is trivially satisfied if `ptr` is never used non-atomically for the + /// duration of lifetime `'a`. Most use cases should be able to follow this guideline. + /// * This requirement is also trivially satisfied if all accesses (atomic or not) are done + /// from the same thread. /// /// [valid]: crate::ptr#safety #[unstable(feature = "atomic_from_ptr", issue = "108652")] @@ -1140,9 +1148,19 @@ impl AtomicPtr { /// /// # Safety /// - /// * `ptr` must be aligned to `align_of::>()` (note that on some platforms this can be bigger than `align_of::<*mut T>()`). + /// * `ptr` must be aligned to `align_of::>()` (note that on some platforms this + /// can be bigger than `align_of::<*mut T>()`). /// * `ptr` must be [valid] for both reads and writes for the whole lifetime `'a`. - /// * The value behind `ptr` must not be accessed through non-atomic operations for the whole lifetime `'a`. + /// * Non-atomic accesses to the value behind `ptr` must have a happens-before relationship + /// with atomic accesses via the returned value (or vice-versa). + /// * In other words, time periods where the value is accessed atomically may not overlap + /// with periods where the value is accessed non-atomically. + /// * This requirement is trivially satisfied if `ptr` is never used non-atomically for the + /// duration of lifetime `'a`. Most use cases should be able to follow this guideline. + /// * This requirement is also trivially satisfied if all accesses (atomic or not) are done + /// from the same thread. + /// * This method should not be used to create overlapping or mixed-size atomic accesses, as + /// these are not supported by the memory model. /// /// [valid]: crate::ptr#safety #[unstable(feature = "atomic_from_ptr", issue = "108652")] @@ -2111,10 +2129,21 @@ macro_rules! atomic_int { /// /// # Safety /// - /// * `ptr` must be aligned to `align_of::()` (note that on some platforms this can be bigger than `align_of::()`). - #[doc = concat!(" * `ptr` must be aligned to `align_of::<", stringify!($atomic_type), ">()` (note that on some platforms this can be bigger than `align_of::<", stringify!($int_type), ">()`).")] + #[doc = concat!(" * `ptr` must be aligned to \ + `align_of::<", stringify!($atomic_type), ">()` (note that on some platforms this \ + can be bigger than `align_of::<", stringify!($int_type), ">()`).")] /// * `ptr` must be [valid] for both reads and writes for the whole lifetime `'a`. - /// * The value behind `ptr` must not be accessed through non-atomic operations for the whole lifetime `'a`. + /// * Non-atomic accesses to the value behind `ptr` must have a happens-before + /// relationship with atomic accesses via the returned value (or vice-versa). + /// * In other words, time periods where the value is accessed atomically may not + /// overlap with periods where the value is accessed non-atomically. + /// * This requirement is trivially satisfied if `ptr` is never used non-atomically + /// for the duration of lifetime `'a`. Most use cases should be able to follow + /// this guideline. + /// * This requirement is also trivially satisfied if all accesses (atomic or not) are + /// done from the same thread. + /// * This method should not be used to create overlapping or mixed-size atomic + /// accesses, as these are not supported by the memory model. /// /// [valid]: crate::ptr#safety #[unstable(feature = "atomic_from_ptr", issue = "108652")] From 227c844b167743c65750808eed65b498c0e03cee Mon Sep 17 00:00:00 2001 From: Trevor Gross Date: Sat, 9 Sep 2023 16:09:32 -0400 Subject: [PATCH 2/2] Stabilize 'atomic_from_ptr', move const gate to 'const_atomic_from_ptr' --- library/core/src/sync/atomic.rs | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/library/core/src/sync/atomic.rs b/library/core/src/sync/atomic.rs index 3cb8f9f424105..1271dcc78e0fd 100644 --- a/library/core/src/sync/atomic.rs +++ b/library/core/src/sync/atomic.rs @@ -319,7 +319,7 @@ impl AtomicBool { /// # Examples /// /// ``` - /// #![feature(atomic_from_ptr, pointer_is_aligned)] + /// #![feature(pointer_is_aligned)] /// use std::sync::atomic::{self, AtomicBool}; /// use std::mem::align_of; /// @@ -359,8 +359,8 @@ impl AtomicBool { /// from the same thread. /// /// [valid]: crate::ptr#safety - #[unstable(feature = "atomic_from_ptr", issue = "108652")] - #[rustc_const_unstable(feature = "atomic_from_ptr", issue = "108652")] + #[stable(feature = "atomic_from_ptr", since = "CURRENT_RUSTC_VERSION")] + #[rustc_const_unstable(feature = "const_atomic_from_ptr", issue = "108652")] pub const unsafe fn from_ptr<'a>(ptr: *mut bool) -> &'a AtomicBool { // SAFETY: guaranteed by the caller unsafe { &*ptr.cast() } @@ -1121,7 +1121,7 @@ impl AtomicPtr { /// # Examples /// /// ``` - /// #![feature(atomic_from_ptr, pointer_is_aligned)] + /// #![feature(pointer_is_aligned)] /// use std::sync::atomic::{self, AtomicPtr}; /// use std::mem::align_of; /// @@ -1163,8 +1163,8 @@ impl AtomicPtr { /// these are not supported by the memory model. /// /// [valid]: crate::ptr#safety - #[unstable(feature = "atomic_from_ptr", issue = "108652")] - #[rustc_const_unstable(feature = "atomic_from_ptr", issue = "108652")] + #[stable(feature = "atomic_from_ptr", since = "CURRENT_RUSTC_VERSION")] + #[rustc_const_unstable(feature = "const_atomic_from_ptr", issue = "108652")] pub const unsafe fn from_ptr<'a>(ptr: *mut *mut T) -> &'a AtomicPtr { // SAFETY: guaranteed by the caller unsafe { &*ptr.cast() } @@ -2101,7 +2101,7 @@ macro_rules! atomic_int { /// # Examples /// /// ``` - /// #![feature(atomic_from_ptr, pointer_is_aligned)] + /// #![feature(pointer_is_aligned)] #[doc = concat!($extra_feature, "use std::sync::atomic::{self, ", stringify!($atomic_type), "};")] /// use std::mem::align_of; /// @@ -2146,8 +2146,8 @@ macro_rules! atomic_int { /// accesses, as these are not supported by the memory model. /// /// [valid]: crate::ptr#safety - #[unstable(feature = "atomic_from_ptr", issue = "108652")] - #[rustc_const_unstable(feature = "atomic_from_ptr", issue = "108652")] + #[stable(feature = "atomic_from_ptr", since = "CURRENT_RUSTC_VERSION")] + #[rustc_const_unstable(feature = "const_atomic_from_ptr", issue = "108652")] pub const unsafe fn from_ptr<'a>(ptr: *mut $int_type) -> &'a $atomic_type { // SAFETY: guaranteed by the caller unsafe { &*ptr.cast() }