Update docs for AtomicBool/U8/I8 with regard to alignment
Fixes#126084.
Since `AtomicBool`/`AtomicU8`/`AtomicI8` are guaranteed to have size == 1, and Rust guarantees that `size % align == 0`, they also must have alignment equal to 1, so some current docs are contradictory/confusing when describing their alignment requirements.
Specifically:
* Fix `AtomicBool::from_ptr` claiming that `align_of::<AtomicBool>() > align_of::<bool>()` on some platforms. (same for `AtomicU8::from_ptr`/`AtomicI8::from_ptr`)
* Explicitly state that `AtomicU8`/`AtomicI8` have the same alignment as `u8`/`i8` (in addition to size and bit validity)
* (internal) Change the `if_not_8_bit` macro to be `if_8_bit` and to allow an "if-else"-like structure, instead of just "if"-like.
---
I opted to leave the "`ptr` must be aligned" wording in `from_ptr`'s docs and just clarify that it is always satsified, instead of just removing the wording entirely. If that is instead preferred I can do that.
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.
Many, many projects use `size_of` to get the size of a type. However,
it's also often equally easy to hardcode a size (e.g. `8` instead of
`size_of::<u64>()`). Minimizing friction in the use of `size_of` helps
ensure that people use it and make code more self-documenting.
The name `size_of` is unambiguous: the name alone, without any prefix or
path, is self-explanatory and unmistakeable for any other functionality.
Adding it to the prelude cannot produce any name conflicts, as any local
definition will silently shadow the one from the prelude. Thus, we don't
need to wait for a new edition prelude to add it.
Add `size_of_val`, `align_of`, and `align_of_val` as well, with similar
justification: widely useful, self-explanatory, unmistakeable for
anything else, won't produce conflicts.
Clarify atomic bit validity
The previous definition used the phrase "representation", which is ambiguous given the current state of memory model nomenclature in Rust. For integer types and for `AtomicPtr<T>`, the new wording clarifies that size and bit validity are guaranteed to match the corresponding native integer type/`*mut T`. For `AtomicBool`, the new wording clarifies that size, alignment, and bit validity are guaranteed to match `bool`.
Note that we use the phrase "size and alignment" rather than "layout" since the latter term also implies that the field types are the same. This isn't true - `AtomicXxx` doesn't store an `xxx`, but rather an `UnsafeCell<xxx>`. This distinction is important for some `unsafe` code, which needs to reason about the presence or absence of interior mutability in order to ensure that their code is sound (see e.g. https://github.com/google/zerocopy/issues/251).
The previous definition used the phrase "representation", which is ambiguous given the current state of memory model nomenclature in Rust. The new wording clarifies that size and bit validity are guaranteed to match the corresponding native integer type.
The documentation for atomic integers says that they have the "same
in-memory representation" as their underlying integers. This might be
misconstrued as implying that they have the same layout. Therefore,
clarify that atomic integers' alignment is equal to their size.
I done this for this reasons:
1. The example now shows that there is more Orderings than just SeqCst.
2. People who would copy from example would now have more suitable orderings for the job.
3. SeqCst is both much harder to reason about and not needed in most situations.
IMHO, we should encourage people to think and use memory orderings that is suitable to task instead of blindly defaulting to SeqCst.
* Remove duplicate alignment note that mentioned `AtomicBool` with other
types
* Update safety requirements about when non-atomic operations are
allowed
Optimize `AtomicBool` for target that don't support byte-sized atomics
`AtomicBool` is defined to have the same layout as `bool`, which means that we guarantee that it has a size of 1 byte. However on certain architectures such as RISC-V, LLVM will emulate byte atomics using a masked CAS loop on an aligned word.
We can take advantage of the fact that `bool` only ever has a value of 0 or 1 to replace `swap` operations with `and`/`or` operations that LLVM can lower to word-sized atomic `and`/`or` operations. This takes advantage of the fact that the incoming value to a `swap` or `compare_exchange` for `AtomicBool` is often a compile-time constant.
### Example
```rust
pub fn swap_true(atomic: &AtomicBool) -> bool {
atomic.swap(true, Ordering::Relaxed)
}
```
### Old
```asm
andi a1, a0, -4
slli a0, a0, 3
li a2, 255
sllw a2, a2, a0
li a3, 1
sllw a3, a3, a0
slli a3, a3, 32
srli a3, a3, 32
.LBB1_1:
lr.w a4, (a1)
mv a5, a3
xor a5, a5, a4
and a5, a5, a2
xor a5, a5, a4
sc.w a5, a5, (a1)
bnez a5, .LBB1_1
srlw a0, a4, a0
andi a0, a0, 255
snez a0, a0
ret
```
### New
```asm
andi a1, a0, -4
slli a0, a0, 3
li a2, 1
sllw a2, a2, a0
amoor.w a1, a2, (a1)
srlw a0, a1, a0
andi a0, a0, 255
snez a0, a0
ret
```
`AtomicBool` is defined to have the same layout as `bool`, which means
that we guarantee that it has a size of 1 byte. However on certain
architectures such as RISC-V, LLVM will emulate byte atomics using a
masked CAS loop on an aligned word.
We can take advantage of the fact that `bool` only ever has a value of 0
or 1 to replace `swap` operations with `and`/`or` operations that LLVM
can lower to word-sized atomic `and`/`or` operations. This takes
advantage of the fact that the incoming value to a `swap` or
`compare_exchange` for `AtomicBool` is often a compile-time constant.
