Contradiction in documentation about alignment of AtomicBool

[FeldrinH]

Location

https://doc.rust-lang.org/nightly/core/sync/atomic/struct.AtomicBool.html

Summary

The introductory section for AtomicBool states:

This type has the same size, alignment, and bit validity as a bool.

But later the safety requirements for from_ptr state:

ptr must be aligned to align_of::<AtomicBool>() (note that on some platforms this can be bigger than align_of::<bool>()).

This seems to be a contradiction. If AtomicBool has the same alignment as bool then how can align_of::<AtomicBool>() be bigger than align_of::<bool>().

[lolbinarycat]

the alignment requirement seems to have been copy-pasted across every *::from_ptr method. it could be argued that this alignment requirement could be desirable to allow emulating AtomicBool on platforms that only have word-sized atomic operations in the future, but we probably shouldn't make this into UB when it was arguably not UB before.

[zachs18]

Rust guarantees that size % align == 0, so since the size is 1 the only possible alignment for AtomicBool that wouldn't also require changing the size is 1. I agree that from_ptr's docs should be clarified, either by removing that line, or perhaps changing it to something like

ptr must be aligned to align_of::<AtomicBool>() (note that this is always true, because align_of::<AtomicBool>() == 1).

so that it is clear that alignment is being considered, it's just never an issue.

The docs for Atomic{U,I}8 have a similar issue, since they also guarantee their size is the same as {u,i}8 (and therefore have size 1), but have the same copy-pasted note about alignment in their from_ptr's docs. (Though for them, this would be more annoying to fix, since their from_ptr is generated by a macro shared with the other atomic integers, which can be more aligned than their corresponding primitives.)

---

Tangent about "[...] allow emulating AtomicBool on platforms that only have word-sized atomic operations [...]"

Note that at the codegen level (but not at the language level), this is sort of already being done. E.g. if the platform only has 32-bit atomics, we mask the address to the aligned 4-byte word containing the AtomicBool, and then perform a fetch_update loop masking the value to the approriate byte in the word. This is how Atomic{Bool,{U,I}{8,16}} are implemented "under the hood" by LLVM on such platforms, like RISC-V (example) which have 32-bit (but not 8/16-bit) atomic read-modify-write instructions.