From 7897f60021b95b853b28e600ee858e21f49e8575 Mon Sep 17 00:00:00 2001 From: Alexis Bourget Date: Fri, 5 Jun 2020 19:07:24 +0200 Subject: [PATCH] Improve the new documentation to be more precise about the necessary platform's capabilities --- src/libcore/sync/atomic.rs | 164 ++++++++++++++++++++++--------------- 1 file changed, 97 insertions(+), 67 deletions(-) diff --git a/src/libcore/sync/atomic.rs b/src/libcore/sync/atomic.rs index cf84c63e67c..aec679dd4f8 100644 --- a/src/libcore/sync/atomic.rs +++ b/src/libcore/sync/atomic.rs @@ -153,7 +153,8 @@ pub fn spin_loop_hint() { /// /// This type has the same in-memory representation as a [`bool`]. /// -/// **Note**: This type may not be available on some platforms. +/// **Note**: This type is only available on platforms that support atomic +/// loads and stores of booleans (as `u8`). /// /// [`bool`]: ../../../std/primitive.bool.html #[cfg(target_has_atomic_load_store = "8")] @@ -181,8 +182,8 @@ unsafe impl Sync for AtomicBool {} /// /// This type has the same in-memory representation as a `*mut T`. /// -/// **Note**: This type may not be available on some platforms. Its size depends -/// on the target pointer's size. +/// **Note**: This type is only available on platforms that support atomic +/// loads and stores of pointers. Its size depends on the target pointer's size. #[cfg(target_has_atomic_load_store = "ptr")] #[stable(feature = "rust1", since = "1.0.0")] #[cfg_attr(target_pointer_width = "16", repr(C, align(2)))] @@ -452,6 +453,9 @@ pub fn store(&self, val: bool, order: Ordering) { /// [`Acquire`] makes the store part of this operation [`Relaxed`], and /// using [`Release`] makes the load part [`Relaxed`]. /// + /// **Note:** This method is only available on platforms that support atomic + /// operations on `u8`. + /// /// [`Ordering`]: enum.Ordering.html /// [`Relaxed`]: enum.Ordering.html#variant.Relaxed /// [`Release`]: enum.Ordering.html#variant.Release @@ -467,8 +471,6 @@ pub fn store(&self, val: bool, order: Ordering) { /// assert_eq!(some_bool.swap(false, Ordering::Relaxed), true); /// assert_eq!(some_bool.load(Ordering::Relaxed), false); /// ``` - /// - /// **Note**: This method may not be available on some platforms. #[inline] #[stable(feature = "rust1", since = "1.0.0")] #[cfg(target_has_atomic = "8")] @@ -488,6 +490,9 @@ pub fn swap(&self, val: bool, order: Ordering) -> bool { /// Using [`Acquire`] makes the store part of this operation [`Relaxed`] if it /// happens, and using [`Release`] makes the load part [`Relaxed`]. /// + /// **Note:** This method is only available on platforms that support atomic + /// operations on `u8`. + /// /// [`Ordering`]: enum.Ordering.html /// [`Relaxed`]: enum.Ordering.html#variant.Relaxed /// [`Release`]: enum.Ordering.html#variant.Release @@ -508,8 +513,6 @@ pub fn swap(&self, val: bool, order: Ordering) -> bool { /// assert_eq!(some_bool.compare_and_swap(true, true, Ordering::Relaxed), false); /// assert_eq!(some_bool.load(Ordering::Relaxed), false); /// ``` - /// - /// **Note**: This method may not be available on some platforms. #[inline] #[stable(feature = "rust1", since = "1.0.0")] #[cfg(target_has_atomic = "8")] @@ -533,6 +536,8 @@ pub fn compare_and_swap(&self, current: bool, new: bool, order: Ordering) -> boo /// [`Relaxed`]. The failure ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`] /// and must be equivalent to or weaker than the success ordering. /// + /// **Note:** This method is only available on platforms that support atomic + /// operations on `u8`. /// /// [`bool`]: ../../../std/primitive.bool.html /// [`Ordering`]: enum.Ordering.html @@ -561,8 +566,6 @@ pub fn compare_and_swap(&self, current: bool, new: bool, order: Ordering) -> boo /// Err(false)); /// assert_eq!(some_bool.load(Ordering::Relaxed), false); /// ``` - /// - /// **Note**: This method may not be available on some platforms. #[inline] #[stable(feature = "extended_compare_and_swap", since = "1.10.0")] #[cfg(target_has_atomic = "8")] @@ -597,6 +600,9 @@ pub fn compare_exchange( /// [`Relaxed`]. The failure ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`] /// and must be equivalent to or weaker than the success ordering. /// + /// **Note:** This method is only available on platforms that support atomic + /// operations on `u8`. + /// /// [`bool`]: ../../../std/primitive.bool.html /// [`compare_exchange`]: #method.compare_exchange /// [`Ordering`]: enum.Ordering.html @@ -621,8 +627,6 @@ pub fn compare_exchange( /// } /// } /// ``` - /// - /// **Note**: This method may not be available on some platforms. #[inline] #[stable(feature = "extended_compare_and_swap", since = "1.10.0")] #[cfg(target_has_atomic = "8")] @@ -659,6 +663,9 @@ pub fn compare_exchange_weak( /// [`Release`]: enum.Ordering.html#variant.Release /// [`Acquire`]: enum.Ordering.html#variant.Acquire /// + /// **Note:** This method is only available on platforms that support atomic + /// operations on `u8`. + /// /// # Examples /// /// ``` @@ -676,8 +683,6 @@ pub fn compare_exchange_weak( /// assert_eq!(foo.fetch_and(false, Ordering::SeqCst), false); /// assert_eq!(foo.load(Ordering::SeqCst), false); /// ``` - /// - /// **Note**: This method may not be available on some platforms. #[inline] #[stable(feature = "rust1", since = "1.0.0")] #[cfg(target_has_atomic = "8")] @@ -698,6 +703,9 @@ pub fn fetch_and(&self, val: bool, order: Ordering) -> bool { /// [`Acquire`] makes the store part of this operation [`Relaxed`], and /// using [`Release`] makes the load part [`Relaxed`]. /// + /// **Note:** This method is only available on platforms that support atomic + /// operations on `u8`. + /// /// [`Ordering`]: enum.Ordering.html /// [`Relaxed`]: enum.Ordering.html#variant.Relaxed /// [`Release`]: enum.Ordering.html#variant.Release @@ -721,8 +729,6 @@ pub fn fetch_and(&self, val: bool, order: Ordering) -> bool { /// assert_eq!(foo.fetch_nand(false, Ordering::SeqCst), false); /// assert_eq!(foo.load(Ordering::SeqCst), true); /// ``` - /// - /// **Note**: This method may not be available on some platforms. #[inline] #[stable(feature = "rust1", since = "1.0.0")] #[cfg(target_has_atomic = "8")] @@ -754,6 +760,9 @@ pub fn fetch_nand(&self, val: bool, order: Ordering) -> bool { /// [`Acquire`] makes the store part of this operation [`Relaxed`], and /// using [`Release`] makes the load part [`Relaxed`]. /// + /// **Note:** This method is only available on platforms that support atomic + /// operations on `u8`. + /// /// [`Ordering`]: enum.Ordering.html /// [`Relaxed`]: enum.Ordering.html#variant.Relaxed /// [`Release`]: enum.Ordering.html#variant.Release @@ -776,8 +785,6 @@ pub fn fetch_nand(&self, val: bool, order: Ordering) -> bool { /// assert_eq!(foo.fetch_or(false, Ordering::SeqCst), false); /// assert_eq!(foo.load(Ordering::SeqCst), false); /// ``` - /// - /// **Note**: This method may not be available on some platforms. #[inline] #[stable(feature = "rust1", since = "1.0.0")] #[cfg(target_has_atomic = "8")] @@ -798,6 +805,9 @@ pub fn fetch_or(&self, val: bool, order: Ordering) -> bool { /// [`Acquire`] makes the store part of this operation [`Relaxed`], and /// using [`Release`] makes the load part [`Relaxed`]. /// + /// **Note:** This method is only available on platforms that support atomic + /// operations on `u8`. + /// /// [`Ordering`]: enum.Ordering.html /// [`Relaxed`]: enum.Ordering.html#variant.Relaxed /// [`Release`]: enum.Ordering.html#variant.Release @@ -820,8 +830,6 @@ pub fn fetch_or(&self, val: bool, order: Ordering) -> bool { /// assert_eq!(foo.fetch_xor(false, Ordering::SeqCst), false); /// assert_eq!(foo.load(Ordering::SeqCst), false); /// ``` - /// - /// **Note**: This method may not be available on some platforms. #[inline] #[stable(feature = "rust1", since = "1.0.0")] #[cfg(target_has_atomic = "8")] @@ -1002,6 +1010,9 @@ pub fn store(&self, ptr: *mut T, order: Ordering) { /// [`Acquire`] makes the store part of this operation [`Relaxed`], and /// using [`Release`] makes the load part [`Relaxed`]. /// + /// **Note:** This method is only available on platforms that support atomic + /// operations on pointers. + /// /// [`Ordering`]: enum.Ordering.html /// [`Relaxed`]: enum.Ordering.html#variant.Relaxed /// [`Release`]: enum.Ordering.html#variant.Release @@ -1019,8 +1030,6 @@ pub fn store(&self, ptr: *mut T, order: Ordering) { /// /// let value = some_ptr.swap(other_ptr, Ordering::Relaxed); /// ``` - /// - /// **Note**: This method may not be available on some platforms. #[inline] #[stable(feature = "rust1", since = "1.0.0")] #[cfg(target_has_atomic = "ptr")] @@ -1040,6 +1049,9 @@ pub fn swap(&self, ptr: *mut T, order: Ordering) -> *mut T { /// Using [`Acquire`] makes the store part of this operation [`Relaxed`] if it /// happens, and using [`Release`] makes the load part [`Relaxed`]. /// + /// **Note:** This method is only available on platforms that support atomic + /// operations on pointers. + /// /// [`Ordering`]: enum.Ordering.html /// [`Relaxed`]: enum.Ordering.html#variant.Relaxed /// [`Release`]: enum.Ordering.html#variant.Release @@ -1058,8 +1070,6 @@ pub fn swap(&self, ptr: *mut T, order: Ordering) -> *mut T { /// /// let value = some_ptr.compare_and_swap(ptr, other_ptr, Ordering::Relaxed); /// ``` - /// - /// **Note**: This method may not be available on some platforms. #[inline] #[stable(feature = "rust1", since = "1.0.0")] #[cfg(target_has_atomic = "ptr")] @@ -1083,6 +1093,9 @@ pub fn compare_and_swap(&self, current: *mut T, new: *mut T, order: Ordering) -> /// [`Relaxed`]. The failure ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`] /// and must be equivalent to or weaker than the success ordering. /// + /// **Note:** This method is only available on platforms that support atomic + /// operations on pointers. + /// /// [`Ordering`]: enum.Ordering.html /// [`Relaxed`]: enum.Ordering.html#variant.Relaxed /// [`Release`]: enum.Ordering.html#variant.Release @@ -1102,8 +1115,6 @@ pub fn compare_and_swap(&self, current: *mut T, new: *mut T, order: Ordering) -> /// let value = some_ptr.compare_exchange(ptr, other_ptr, /// Ordering::SeqCst, Ordering::Relaxed); /// ``` - /// - /// **Note**: This method may not be available on some platforms. #[inline] #[stable(feature = "extended_compare_and_swap", since = "1.10.0")] #[cfg(target_has_atomic = "ptr")] @@ -1145,6 +1156,9 @@ pub fn compare_exchange( /// [`Relaxed`]. The failure ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`] /// and must be equivalent to or weaker than the success ordering. /// + /// **Note:** This method is only available on platforms that support atomic + /// operations on pointers. + /// /// [`compare_exchange`]: #method.compare_exchange /// [`Ordering`]: enum.Ordering.html /// [`Relaxed`]: enum.Ordering.html#variant.Relaxed @@ -1168,8 +1182,6 @@ pub fn compare_exchange( /// } /// } /// ``` - /// - /// **Note**: This method may not be available on some platforms. #[inline] #[stable(feature = "extended_compare_and_swap", since = "1.10.0")] #[cfg(target_has_atomic = "ptr")] @@ -1252,7 +1264,12 @@ macro_rules! atomic_int { /// non-atomic types as well as information about the portability of /// this type, please see the [module-level documentation]. /// - /// **Note**: This type may not be available on some platforms. + /// **Note:** This type is only available on platforms that support + /// atomic loads and stores of [` + #[doc = $s_int_type] + /// `]( + #[doc = $int_ref] + /// ). /// /// [module-level documentation]: index.html #[$stable] @@ -1439,6 +1456,9 @@ pub fn store(&self, val: $int_type, order: Ordering) { [`Acquire`] makes the store part of this operation [`Relaxed`], and using [`Release`] makes the load part [`Relaxed`]. +**Note**: This method is only available on platforms that support atomic +operations on [`", $s_int_type, "`](", $int_ref, "). + [`Ordering`]: enum.Ordering.html [`Relaxed`]: enum.Ordering.html#variant.Relaxed [`Release`]: enum.Ordering.html#variant.Release @@ -1452,9 +1472,7 @@ pub fn store(&self, val: $int_type, order: Ordering) { let some_var = ", stringify!($atomic_type), "::new(5); assert_eq!(some_var.swap(10, Ordering::Relaxed), 5); -``` - -**Note**: This method may not be available on some platforms."), +```"), #[inline] #[$stable] #[$cfg_cas] @@ -1477,6 +1495,9 @@ pub fn swap(&self, val: $int_type, order: Ordering) -> $int_type { Using [`Acquire`] makes the store part of this operation [`Relaxed`] if it happens, and using [`Release`] makes the load part [`Relaxed`]. +**Note**: This method is only available on platforms that support atomic +operations on [`", $s_int_type, "`](", $int_ref, "). + [`Ordering`]: enum.Ordering.html [`Relaxed`]: enum.Ordering.html#variant.Relaxed [`Release`]: enum.Ordering.html#variant.Release @@ -1495,9 +1516,7 @@ pub fn swap(&self, val: $int_type, order: Ordering) -> $int_type { assert_eq!(some_var.compare_and_swap(6, 12, Ordering::Relaxed), 10); assert_eq!(some_var.load(Ordering::Relaxed), 10); -``` - -**Note**: This method may not be available on some platforms."), +```"), #[inline] #[$stable] #[$cfg_cas] @@ -1531,6 +1550,9 @@ pub fn compare_and_swap(&self, [`Relaxed`]. The failure ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`] and must be equivalent to or weaker than the success ordering. +**Note**: This method is only available on platforms that support atomic +operations on [`", $s_int_type, "`](", $int_ref, "). + [`Ordering`]: enum.Ordering.html [`Relaxed`]: enum.Ordering.html#variant.Relaxed [`Release`]: enum.Ordering.html#variant.Release @@ -1555,9 +1577,7 @@ pub fn compare_and_swap(&self, Ordering::Acquire), Err(10)); assert_eq!(some_var.load(Ordering::Relaxed), 10); -``` - -**Note**: This method may not be available on some platforms."), +```"), #[inline] #[$stable_cxchg] #[$cfg_cas] @@ -1595,6 +1615,9 @@ pub fn compare_exchange(&self, [`Acquire`]: enum.Ordering.html#variant.Acquire [`SeqCst`]: enum.Ordering.html#variant.SeqCst +**Note**: This method is only available on platforms that support atomic +operations on [`", $s_int_type, "`](", $int_ref, "). + # Examples ``` @@ -1610,9 +1633,7 @@ pub fn compare_exchange(&self, Err(x) => old = x, } } -``` - -**Note**: This method may not be available on some platforms."), +```"), #[inline] #[$stable_cxchg] #[$cfg_cas] @@ -1638,6 +1659,9 @@ pub fn compare_exchange_weak(&self, [`Acquire`] makes the store part of this operation [`Relaxed`], and using [`Release`] makes the load part [`Relaxed`]. +**Note**: This method is only available on platforms that support atomic +operations on [`", $s_int_type, "`](", $int_ref, "). + [`Ordering`]: enum.Ordering.html [`Relaxed`]: enum.Ordering.html#variant.Relaxed [`Release`]: enum.Ordering.html#variant.Release @@ -1651,9 +1675,7 @@ pub fn compare_exchange_weak(&self, let foo = ", stringify!($atomic_type), "::new(0); assert_eq!(foo.fetch_add(10, Ordering::SeqCst), 0); assert_eq!(foo.load(Ordering::SeqCst), 10); -``` - -**Note**: This method may not be available on some platforms."), +```"), #[inline] #[$stable] #[$cfg_cas] @@ -1673,6 +1695,9 @@ pub fn fetch_add(&self, val: $int_type, order: Ordering) -> $int_type { [`Acquire`] makes the store part of this operation [`Relaxed`], and using [`Release`] makes the load part [`Relaxed`]. +**Note**: This method is only available on platforms that support atomic +operations on [`", $s_int_type, "`](", $int_ref, "). + [`Ordering`]: enum.Ordering.html [`Relaxed`]: enum.Ordering.html#variant.Relaxed [`Release`]: enum.Ordering.html#variant.Release @@ -1686,9 +1711,7 @@ pub fn fetch_add(&self, val: $int_type, order: Ordering) -> $int_type { let foo = ", stringify!($atomic_type), "::new(20); assert_eq!(foo.fetch_sub(10, Ordering::SeqCst), 20); assert_eq!(foo.load(Ordering::SeqCst), 10); -``` - -**Note**: This method may not be available on some platforms."), +```"), #[inline] #[$stable] #[$cfg_cas] @@ -1711,6 +1734,9 @@ pub fn fetch_sub(&self, val: $int_type, order: Ordering) -> $int_type { [`Acquire`] makes the store part of this operation [`Relaxed`], and using [`Release`] makes the load part [`Relaxed`]. +**Note**: This method is only available on platforms that support atomic +operations on [`", $s_int_type, "`](", $int_ref, "). + [`Ordering`]: enum.Ordering.html [`Relaxed`]: enum.Ordering.html#variant.Relaxed [`Release`]: enum.Ordering.html#variant.Release @@ -1724,9 +1750,7 @@ pub fn fetch_sub(&self, val: $int_type, order: Ordering) -> $int_type { let foo = ", stringify!($atomic_type), "::new(0b101101); assert_eq!(foo.fetch_and(0b110011, Ordering::SeqCst), 0b101101); assert_eq!(foo.load(Ordering::SeqCst), 0b100001); -``` - -**Note**: This method may not be available on some platforms."), +```"), #[inline] #[$stable] #[$cfg_cas] @@ -1749,6 +1773,9 @@ pub fn fetch_and(&self, val: $int_type, order: Ordering) -> $int_type { [`Acquire`] makes the store part of this operation [`Relaxed`], and using [`Release`] makes the load part [`Relaxed`]. +**Note**: This method is only available on platforms that support atomic +operations on [`", $s_int_type, "`](", $int_ref, "). + [`Ordering`]: enum.Ordering.html [`Relaxed`]: enum.Ordering.html#variant.Relaxed [`Release`]: enum.Ordering.html#variant.Release @@ -1763,9 +1790,7 @@ pub fn fetch_and(&self, val: $int_type, order: Ordering) -> $int_type { let foo = ", stringify!($atomic_type), "::new(0x13); assert_eq!(foo.fetch_nand(0x31, Ordering::SeqCst), 0x13); assert_eq!(foo.load(Ordering::SeqCst), !(0x13 & 0x31)); -``` - -**Note**: This method may not be available on some platforms."), +```"), #[inline] #[$stable_nand] #[$cfg_cas] @@ -1788,6 +1813,9 @@ pub fn fetch_nand(&self, val: $int_type, order: Ordering) -> $int_type { [`Acquire`] makes the store part of this operation [`Relaxed`], and using [`Release`] makes the load part [`Relaxed`]. +**Note**: This method is only available on platforms that support atomic +operations on [`", $s_int_type, "`](", $int_ref, "). + [`Ordering`]: enum.Ordering.html [`Relaxed`]: enum.Ordering.html#variant.Relaxed [`Release`]: enum.Ordering.html#variant.Release @@ -1801,9 +1829,7 @@ pub fn fetch_nand(&self, val: $int_type, order: Ordering) -> $int_type { let foo = ", stringify!($atomic_type), "::new(0b101101); assert_eq!(foo.fetch_or(0b110011, Ordering::SeqCst), 0b101101); assert_eq!(foo.load(Ordering::SeqCst), 0b111111); -``` - -**Note**: This method may not be available on some platforms."), +```"), #[inline] #[$stable] #[$cfg_cas] @@ -1826,6 +1852,9 @@ pub fn fetch_or(&self, val: $int_type, order: Ordering) -> $int_type { [`Acquire`] makes the store part of this operation [`Relaxed`], and using [`Release`] makes the load part [`Relaxed`]. +**Note**: This method is only available on platforms that support atomic +operations on [`", $s_int_type, "`](", $int_ref, "). + [`Ordering`]: enum.Ordering.html [`Relaxed`]: enum.Ordering.html#variant.Relaxed [`Release`]: enum.Ordering.html#variant.Release @@ -1839,9 +1868,7 @@ pub fn fetch_or(&self, val: $int_type, order: Ordering) -> $int_type { let foo = ", stringify!($atomic_type), "::new(0b101101); assert_eq!(foo.fetch_xor(0b110011, Ordering::SeqCst), 0b101101); assert_eq!(foo.load(Ordering::SeqCst), 0b011110); -``` - -**Note**: This method may not be available on some platforms."), +```"), #[inline] #[$stable] #[$cfg_cas] @@ -1870,6 +1897,9 @@ pub fn fetch_xor(&self, val: $int_type, order: Ordering) -> $int_type { [`Relaxed`]. The (failed) load ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`] and must be equivalent to or weaker than the success ordering. +**Note**: This method is only available on platforms that support atomic +operations on [`", $s_int_type, "`](", $int_ref, "). + [`bool`]: ../../../std/primitive.bool.html [`compare_exchange`]: #method.compare_exchange [`Ordering`]: enum.Ordering.html @@ -1888,9 +1918,7 @@ pub fn fetch_xor(&self, val: $int_type, order: Ordering) -> $int_type { assert_eq!(x.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |x| Some(x + 1)), Ok(7)); assert_eq!(x.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |x| Some(x + 1)), Ok(8)); assert_eq!(x.load(Ordering::SeqCst), 9); -``` - -**Note**: This method may not be available on some platforms."), +```"), #[inline] #[stable(feature = "no_more_cas", since = "1.45.0")] #[$cfg_cas] @@ -1923,6 +1951,9 @@ pub fn fetch_update(&self, [`Acquire`] makes the store part of this operation [`Relaxed`], and using [`Release`] makes the load part [`Relaxed`]. +**Note**: This method is only available on platforms that support atomic +operations on [`", $s_int_type, "`](", $int_ref, "). + [`Ordering`]: enum.Ordering.html [`Relaxed`]: enum.Ordering.html#variant.Relaxed [`Release`]: enum.Ordering.html#variant.Release @@ -1947,9 +1978,7 @@ pub fn fetch_update(&self, let bar = 42; let max_foo = foo.fetch_max(bar, Ordering::SeqCst).max(bar); assert!(max_foo == 42); -``` - -**Note**: This method may not be available on some platforms."), +```"), #[inline] #[stable(feature = "atomic_min_max", since = "1.45.0")] #[$cfg_cas] @@ -1972,6 +2001,9 @@ pub fn fetch_max(&self, val: $int_type, order: Ordering) -> $int_type { [`Acquire`] makes the store part of this operation [`Relaxed`], and using [`Release`] makes the load part [`Relaxed`]. +**Note**: This method is only available on platforms that support atomic +operations on [`", $s_int_type, "`](", $int_ref, "). + [`Ordering`]: enum.Ordering.html [`Relaxed`]: enum.Ordering.html#variant.Relaxed [`Release`]: enum.Ordering.html#variant.Release @@ -1998,9 +2030,7 @@ pub fn fetch_max(&self, val: $int_type, order: Ordering) -> $int_type { let bar = 12; let min_foo = foo.fetch_min(bar, Ordering::SeqCst).min(bar); assert_eq!(min_foo, 12); -``` - -**Note**: This method may not be available on some platforms."), +```"), #[inline] #[stable(feature = "atomic_min_max", since = "1.45.0")] #[$cfg_cas] -- 2.44.0