rust-lang/rust
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Update docs for AtomicU8/I8.

Browse Source 
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.
This commit is contained in:
Zachary S
2024-06-09 21:15:48 -05:00
parent 7885c7b7b2
commit 2d4cb7aa5a
1 changed files with 31 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
library/core/src/sync/atomic.rs
View File

@@ -2091,10 +2091,10 @@ impl<T> From<*mut T> for AtomicPtr<T> {
} }
#[allow(unused_macros)] // This macro ends up being unused on some architectures. #[allow(unused_macros)] // This macro ends up being unused on some architectures.
macro_rules! if_not_8_bit { macro_rules! if_8_bit {
(u8, $($tt:tt)*) => { "" }; (u8, $( yes = [$($yes:tt)*], )? $( no = [$($no:tt)*], )? ) => { concat!("", $($($yes)*)?) };
(i8, $($tt:tt)*) => { "" }; (i8, $( yes = [$($yes:tt)*], )? $( no = [$($no:tt)*], )? ) => { concat!("", $($($yes)*)?) };
($_:ident, $($tt:tt)*) => { $($tt)* }; ($_:ident, $( yes = [$($yes:tt)*], )? $( no = [$($no:tt)*], )? ) => { concat!("", $($($no)*)?) };
} }
#[cfg(target_has_atomic_load_store)] #[cfg(target_has_atomic_load_store)]
@@ -2116,18 +2116,24 @@ macro_rules! atomic_int {
$int_type:ident $atomic_type:ident) => { $int_type:ident $atomic_type:ident) => {
/// An integer type which can be safely shared between threads. /// An integer type which can be safely shared between threads.
/// ///
/// This type has the same size and bit validity as the underlying /// This type has the same
/// integer type, [` #[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 = $s_int_type]
/// `]. /// `].
#[doc = if_not_8_bit! { #[doc = if_8_bit! {
$int_type, $int_type,
concat!( no = [
"However, the alignment of this type is always equal to its ", "However, the alignment of this type is always equal to its ",
"size, even on targets where [`", $s_int_type, "`] has a ", "size, even on targets where [`", $s_int_type, "`] has a ",
"lesser alignment." "lesser alignment."
) ],
}] }]
///
/// For more about the differences between atomic types and /// For more about the differences between atomic types and
/// non-atomic types as well as information about the portability of /// non-atomic types as well as information about the portability of
/// this type, please see the [module-level documentation]. /// this type, please see the [module-level documentation].
@@ -2220,9 +2226,19 @@ macro_rules! atomic_int {
/// ///
/// # Safety /// # Safety
/// ///
#[doc = concat!(" * `ptr` must be aligned to \ /// * `ptr` must be aligned to
`align_of::<", stringify!($atomic_type), ">()` (note that on some platforms this \ #[doc = concat!(" `align_of::<", stringify!($atomic_type), ">()`")]
can be bigger than `align_of::<", stringify!($int_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`. /// * `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 /// * 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, /// 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 = concat!("Get atomic access to a `&mut ", stringify!($int_type), "`.")]
/// ///
#[doc = if_not_8_bit! { #[doc = if_8_bit! {
$int_type, $int_type,
concat!( no = [
"**Note:** This function is only available on targets where `", "**Note:** This function is only available on targets where `",
stringify!($int_type), "` has an alignment of ", $align, " bytes." stringify!($int_type), "` has an alignment of ", $align, " bytes."
) ],
}] }]
/// ///
/// # Examples /// # Examples