From: Alexis Bourget Date: Thu, 4 Jun 2020 20:07:56 +0000 (+0200) Subject: Add a **Note**: comment in documentation when the type/method/function is not always... X-Git-Url: https://git.lizzy.rs/?a=commitdiff_plain;h=817d6a078eb6b7ef1103781bd9114c6d9b811db9;p=rust.git Add a **Note**: comment in documentation when the type/method/function is not always available --- diff --git a/src/libcore/sync/atomic.rs b/src/libcore/sync/atomic.rs index 449aac85bc7..cf84c63e67c 100644 --- a/src/libcore/sync/atomic.rs +++ b/src/libcore/sync/atomic.rs @@ -153,6 +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. +/// /// [`bool`]: ../../../std/primitive.bool.html #[cfg(target_has_atomic_load_store = "8")] #[stable(feature = "rust1", since = "1.0.0")] @@ -178,6 +180,9 @@ unsafe impl Sync for AtomicBool {} /// A raw pointer type which can be safely shared between threads. /// /// 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. #[cfg(target_has_atomic_load_store = "ptr")] #[stable(feature = "rust1", since = "1.0.0")] #[cfg_attr(target_pointer_width = "16", repr(C, align(2)))] @@ -462,6 +467,8 @@ 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")] @@ -501,6 +508,8 @@ 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")] @@ -552,6 +561,8 @@ 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")] @@ -610,6 +621,8 @@ 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")] @@ -663,6 +676,8 @@ 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")] @@ -706,6 +721,8 @@ 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")] @@ -759,6 +776,8 @@ 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")] @@ -801,6 +820,8 @@ 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")] @@ -998,6 +1019,8 @@ 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")] @@ -1035,6 +1058,8 @@ 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")] @@ -1077,6 +1102,8 @@ 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")] @@ -1141,6 +1168,8 @@ 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")] @@ -1223,6 +1252,8 @@ 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. + /// /// [module-level documentation]: index.html #[$stable] #[repr(C, align($align))] @@ -1421,7 +1452,9 @@ 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] @@ -1462,7 +1495,9 @@ 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] @@ -1520,7 +1555,9 @@ 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] @@ -1573,7 +1610,9 @@ pub fn compare_exchange(&self, Err(x) => old = x, } } -```"), +``` + +**Note**: This method may not be available on some platforms."), #[inline] #[$stable_cxchg] #[$cfg_cas] @@ -1612,7 +1651,9 @@ 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] @@ -1645,7 +1686,9 @@ 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] @@ -1681,7 +1724,9 @@ 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] @@ -1718,7 +1763,9 @@ 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] @@ -1754,7 +1801,9 @@ 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] @@ -1790,7 +1839,9 @@ 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] @@ -1837,7 +1888,9 @@ 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] @@ -1894,7 +1947,9 @@ 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] @@ -1943,7 +1998,9 @@ 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]