From 3effe732164da3b626359d197cf0c4baa2481a17 Mon Sep 17 00:00:00 2001 From: Joshua Liebow-Feeser Date: Wed, 4 Oct 2023 09:50:40 -0700 Subject: [PATCH] Safety comments quote new bit validity guarantees https://github.com/rust-lang/reference/pull/1392 adds bit validity guarantees for numeric types. This commit makes use of those guarantees to provide stronger soundness justifications for some trait impls. Closes #440 --- src/lib.rs | 52 +++++++++++++++++++++++++--------------------------- 1 file changed, 25 insertions(+), 27 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 04f46f1542..3c42b7fe32 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1734,20 +1734,38 @@ safety_comment! { safety_comment! { /// SAFETY: - /// - `FromZeroes`, `FromBytes`: all bit patterns are valid for integers [1] - /// - `AsBytes`: integers have no padding bytes [1] + /// - `FromZeroes`, `FromBytes`: all bit patterns are valid for numeric + /// types [1] + /// - `AsBytes`: numeric types have no padding bytes [1] /// - `Unaligned` (`u8` and `i8` only): The reference [2] specifies the size /// of `u8` and `i8` as 1 byte. We also know that: - /// - Alignment is >= 1 - /// - Size is an integer multiple of alignment + /// - Alignment is >= 1 [3] + /// - Size is an integer multiple of alignment [4] /// - The only value >= 1 for which 1 is an integer multiple is 1 /// Therefore, the only possible alignment for `u8` and `i8` is 1. /// - /// TODO(#429): Add quotes from documentation. + /// [1] Per https://doc.rust-lang.org/beta/reference/types/numeric.html#bit-validity: + /// + /// For every numeric type, `T`, the bit validity of `T` is equivalent to + /// the bit validity of `[u8; size_of::()]`. An uninitialized byte is + /// not a valid `u8`. + /// + /// TODO(https://github.com/rust-lang/reference/pull/1392): Once this text + /// is available on the Stable docs, cite those instead. /// - /// [1] TODO(https://github.com/rust-lang/reference/issues/1291): Once the - /// reference explicitly guarantees these properties, cite it. /// [2] https://doc.rust-lang.org/reference/type-layout.html#primitive-data-layout + /// + /// [3] Per https://doc.rust-lang.org/reference/type-layout.html#size-and-alignment: + /// + /// Alignment is measured in bytes, and must be at least 1. + /// + /// [4] Per https://doc.rust-lang.org/reference/type-layout.html#size-and-alignment: + /// + /// The size of a value is always a multiple of its alignment. + /// + /// TODO(#278): Once we've updated the trait docs to refer to `u8`s rather + /// than bits or bytes, update this comment, especially the reference to + /// [1]. unsafe_impl!(u8: FromZeroes, FromBytes, AsBytes, Unaligned); unsafe_impl!(i8: FromZeroes, FromBytes, AsBytes, Unaligned); assert_unaligned!(u8, i8); @@ -1761,26 +1779,6 @@ safety_comment! { unsafe_impl!(i128: FromZeroes, FromBytes, AsBytes); unsafe_impl!(usize: FromZeroes, FromBytes, AsBytes); unsafe_impl!(isize: FromZeroes, FromBytes, AsBytes); -} - -safety_comment! { - /// SAFETY: - /// - `FromZeroes`, `FromBytes`: the `{f32,f64}::from_bits` constructors' - /// documentation [1,2] states that they are currently equivalent to - /// `transmute`. [3] - /// - `AsBytes`: the `{f32,f64}::to_bits` methods' documentation [4,5] - /// states that they are currently equivalent to `transmute`. [3] - /// - /// TODO(#429): - /// - Make these arguments more precisely in terms of the documentation. - /// - Add quotes from documentation. - /// - /// [1] https://doc.rust-lang.org/nightly/std/primitive.f32.html#method.from_bits - /// [2] https://doc.rust-lang.org/nightly/std/primitive.f64.html#method.from_bits - /// [3] TODO(https://github.com/rust-lang/reference/issues/1291): Once the - /// reference explicitly guarantees these properties, cite it. - /// [4] https://doc.rust-lang.org/nightly/std/primitive.f32.html#method.to_bits - /// [5] https://doc.rust-lang.org/nightly/std/primitive.f64.html#method.to_bits unsafe_impl!(f32: FromZeroes, FromBytes, AsBytes); unsafe_impl!(f64: FromZeroes, FromBytes, AsBytes); }