Document MaybeUninit bit validity

Co-authored-by: Ralf Jung <[email protected]>
Edited-by: TC

Author: 2 people

library/core/src/mem/maybe_uninit.rs

@@ -252,6 +252,54 @@ use crate::{fmt, intrinsics, ptr, slice};
 ///     std::process::exit(*code); // UB! Accessing uninitialized memory.
 /// }
 /// ```
+///
+/// # Validity
+///
+/// A `MaybeUninit<T>` has no validity requirement – any sequence of
+/// [bytes][reference-byte] of the appropriate length, initialized or
+/// uninitialized, are a valid representation of `MaybeUninit<T>`.
+///
+/// However, "round-tripping" via `MaybeUninit` does not always result in the
+/// original value. `MaybeUninit` can have padding, and the contents of that
+/// padding are not preserved. Concretely, given distinct `T` and `U` where
+/// `size_of::<T>() == size_of::<U>()`, the following code is not guaranteed to
+/// be sound:
+///
+/// ```rust,no_run
+/// # use core::mem::{MaybeUninit, transmute};
+/// # struct T; struct U;
+/// fn identity(t: T) -> T {
+///     unsafe {
+///         let u: MaybeUninit<U> = transmute(t);
+///         transmute(u)
+///     }
+/// }
+/// ```
+///
+/// If the representation of `t` contains initialized bytes at byte offsets
+/// where `U` contains padding bytes, these may not be preserved in
+/// `MaybeUninit<U>`. Transmuting `u` back to `T` (i.e., `transmute(u)` above)
+/// may thus be undefined behavior or yield a value different from `t` due to
+/// those bytes being lost. This is an active area of discussion, and this code
+/// may become sound in the future.
+///
+/// However, so long as no such byte offsets exist, then the preceding
+/// `identity` example *is* sound. In particular, since `[u8; N]` has no padding
+/// bytes, transmuting `t` to `MaybeUninit<[u8; size_of::<T>]>` and back will
+/// always produce the original value `t` again. This is true even if `t`
+/// contains [provenance]: the resulting value will have the same provenance as
+/// the original `t`.
+///
+/// Note a potential footgun: if `t` contains a reference, then there may be
+/// implicit reborrows of the reference any time it is copied, which may alter
+/// its provenance. In that case, the value returned by `identity` may not be
+/// exactly the same as its argument. However, even in this case, it remains
+/// true that `identity` behaves the same as a function that just returns `t`
+/// immediately (i.e., `fn identity<T>(t: T) -> T { t }`).
+///
+/// [provenance]: crate::ptr#provenance
+///
+/// [reference-byte]: ../../reference/memory-model.html#bytes
 #[stable(feature = "maybe_uninit", since = "1.36.0")]
 // Lang item so we can wrap other types in it. This is useful for coroutines.
 #[lang = "maybe_uninit"]