Update docs for AtomicU8/I8.

Clarify that they always have the same alignment as u8/i8, (unlike other atomic types). Clarify in from_ptr that alignment is never an issue because of this.
rust-lang · Jun 10, 2024 · 2d4cb7a · 2d4cb7a
1 parent 7885c7b
commit 2d4cb7a
Showing 1 changed file with 31 additions and 15 deletions.
diff --git a/library/core/src/sync/atomic.rs b/library/core/src/sync/atomic.rs
@@ -2091,10 2091,10 @@ impl<T> From<*mut T> for AtomicPtr<T> {
 }
 
 #[allow(unused_macros)] // This macro ends up being unused on some architectures.
-macro_rules! if_not_8_bit {
- (u8, $($tt:tt)*) => { "" };
- (i8, $($tt:tt)*) => { "" };
- ($_:ident, $($tt:tt)*) => { $($tt)* };
 macro_rules! if_8_bit {
  (u8, $( yes = [$($yes:tt)*], )? $( no = [$($no:tt)*], )? ) => { concat!("", $($($yes)*)?) };
  (i8, $( yes = [$($yes:tt)*], )? $( no = [$($no:tt)*], )? ) => { concat!("", $($($yes)*)?) };
  ($_:ident, $( yes = [$($yes:tt)*], )? $( no = [$($no:tt)*], )? ) => { concat!("", $($($no)*)?) };
 }
 
 #[cfg(target_has_atomic_load_store)]
@@ -2116,18 2116,24 @@ macro_rules! atomic_int {
  $int_type:ident $atomic_type:ident) => {
  /// An integer type which can be safely shared between threads.
  ///
- /// This type has the same size and bit validity as the underlying
- /// integer type, [`
  /// This type has the same
  #[doc = if_8_bit!(
  $int_type,
  yes = ["size, alignment, and bit validity"],
  no = ["size and bit validity"],
  )]
  /// as the underlying integer type, [`
  #[doc = $s_int_type]
  /// `].
- #[doc = if_not_8_bit! {
  #[doc = if_8_bit! {
  $int_type,
- concat!(
  no = [
  "However, the alignment of this type is always equal to its ",
  "size, even on targets where [`", $s_int_type, "`] has a ",
  "lesser alignment."
- )
  ],
  }]
  ///
  /// For more about the differences between atomic types and
  /// non-atomic types as well as information about the portability of
  /// this type, please see the [module-level documentation].
@@ -2220,9 2226,19 @@ macro_rules! atomic_int {
  ///
  /// # Safety
  ///
- #[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 aligned to
  #[doc = concat!(" `align_of::<", stringify!($atomic_type), ">()`")]
  #[doc = if_8_bit!{
  $int_type,
  yes = [
  " (note that this is always true, since `align_of::<",
  stringify!($atomic_type), ">() == 1`)."
  ],
  no = [
  " (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`.
  /// * You must adhere to the [Memory model for atomic accesses]. In particular, it is not
  /// allowed to mix atomic and non-atomic accesses, or atomic accesses of different sizes,
@@ -2261,12 2277,12 @@ macro_rules! atomic_int {
 
  #[doc = concat!("Get atomic access to a `&mut ", stringify!($int_type), "`.")]
  ///
- #[doc = if_not_8_bit! {
  #[doc = if_8_bit! {
  $int_type,
- concat!(
  no = [
  "**Note:** This function is only available on targets where `",
  stringify!($int_type), "` has an alignment of ", $align, " bytes."
- )
  ],
  }]
  ///
  /// # Examples