From 44513f7ca13f8d2d539a3875d40dc93ae5555602 Mon Sep 17 00:00:00 2001 From: Samuel Selleck <121394688+samuelselleck@users.noreply.github.com> Date: Sat, 4 Nov 2023 05:04:56 -0700 Subject: [PATCH] Add TODOs related to #429 and quotes to safety comments. (#433) * Add TODOs related to #429 and quotes to safety comments. * Update src/lib.rs * Update src/lib.rs * Update src/lib.rs --------- Co-authored-by: Joshua Liebow-Feeser --- src/lib.rs | 78 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 54 insertions(+), 24 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index afad1386c1..c926c25183 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -732,7 +732,9 @@ safety_comment! { /// `ManuallyDrop` is guaranteed to have the same layout and bit /// validity as `T` /// - /// TODO(#429): Once this text (added in + /// TODO(#429): + /// - Add quotes from docs. + /// - Once [1] (added in /// https://github.com/rust-lang/rust/pull/115522) is available on stable, /// quote the stable docs instead of the nightly docs. unsafe_impl_known_layout!(#[repr([u8])] str); @@ -965,6 +967,8 @@ pub unsafe trait FromZeroes { // as required by `u8`. // - Since `Self: FromZeroes`, the all-zeroes instance is a valid // instance of `Self.` + // + // TODO(#429): Add references to docs and quotes. unsafe { ptr::write_bytes(slf.cast::(), 0, len) }; } @@ -1605,6 +1609,8 @@ pub unsafe trait AsBytes { // - The total size of the resulting slice is no larger than // `isize::MAX` because no allocation produced by safe code can be // larger than `isize::MAX`. + // + // TODO(#429): Add references to docs and quotes. unsafe { slice::from_raw_parts(slf.cast::(), len) } } @@ -1640,6 +1646,8 @@ pub unsafe trait AsBytes { // - The total size of the resulting slice is no larger than // `isize::MAX` because no allocation produced by safe code can be // larger than `isize::MAX`. + // + // TODO(#429): Add references to docs and quotes. unsafe { slice::from_raw_parts_mut(slf.cast::(), len) } } @@ -1736,6 +1744,8 @@ safety_comment! { /// - 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] 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 @@ -1762,7 +1772,9 @@ safety_comment! { /// - `AsBytes`: the `{f32,f64}::to_bits` methods' documentation [4,5] /// states that they are currently equivalent to `transmute`. [3] /// - /// TODO: Make these arguments more precisely in terms of the documentation. + /// 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 @@ -1776,11 +1788,12 @@ safety_comment! { safety_comment! { /// SAFETY: - /// - `FromZeroes`: Per the reference [1], 0x00 is a valid bit pattern for - /// `bool`. - /// - `AsBytes`: Per the reference [1], `bool` always has a size of 1 with - /// valid bit patterns 0x01 and 0x00, so the only byte of the bool is - /// always initialized + /// - `FromZeroes`: Valid since "[t]he value false has the bit pattern + /// 0x00" [1]. + /// - `AsBytes`: Since "the boolean type has a size and alignment of 1 each" + /// and "The value false has the bit pattern 0x00 and the value true has + /// the bit pattern 0x01" [1]. Thus, the only byte of the bool is always + /// initialized. /// - `Unaligned`: Per the reference [1], "[a]n object with the boolean type /// has a size and alignment of 1 each." /// @@ -1790,24 +1803,28 @@ safety_comment! { } safety_comment! { /// SAFETY: - /// - `FromZeroes`: Per the reference [1], 0x0000 is a valid bit pattern for - /// `char`. - /// - `AsBytes`: `char` is represented as a 32-bit unsigned word (`u32`) - /// [1], which is `AsBytes`. Note that unlike `u32`, not all bit patterns - /// are valid for `char`. + /// - `FromZeroes`: Per reference [1], "[a] value of type char is a Unicode + /// scalar value (i.e. a code point that is not a surrogate), represented + /// as a 32-bit unsigned word in the 0x0000 to 0xD7FF or 0xE000 to + /// 0x10FFFF range" which contains 0x0000. + /// - `AsBytes`: `char` is per reference [1] "represented as a 32-bit + /// unsigned word" (`u32`) which is `AsBytes`. Note that unlike `u32`, not + /// all bit patterns are valid for `char`. /// /// [1] https://doc.rust-lang.org/reference/types/textual.html unsafe_impl!(char: FromZeroes, AsBytes); } safety_comment! { /// SAFETY: - /// - `FromZeroes`, `AsBytes`, `Unaligned`: Per the reference [1], `str` has - /// the same layout as `[u8]`, and `[u8]` is `FromZeroes`, `AsBytes`, and - /// `Unaligned`. + /// - `FromZeroes`, `AsBytes`, `Unaligned`: Per the reference [1], `str` + /// has the same layout as `[u8]`, and `[u8]` is `FromZeroes`, `AsBytes`, + /// and `Unaligned`. /// /// Note that we don't `assert_unaligned!(str)` because `assert_unaligned!` /// uses `align_of`, which only works for `Sized` types. /// + /// TODO(#429): Add quotes from documentation. + /// /// [1] https://doc.rust-lang.org/reference/type-layout.html#str-layout unsafe_impl!(str: FromZeroes, AsBytes, Unaligned); } @@ -1830,6 +1847,8 @@ safety_comment! { /// be 0 bytes, which means that they must be 1 byte. The only valid /// alignment for a 1-byte type is 1. /// + /// TODO(#429): Add quotes from documentation. + /// /// [1] https://doc.rust-lang.org/stable/std/num/struct.NonZeroU8.html /// [2] https://doc.rust-lang.org/stable/std/num/struct.NonZeroI8.html /// TODO(https://github.com/rust-lang/rust/pull/104082): Cite documentation @@ -1860,6 +1879,8 @@ safety_comment! { /// unthinkable that that would ever change. The only valid alignment for /// a 1-byte type is 1. /// + /// TODO(#429): Add quotes from documentation. + /// /// [1] https://doc.rust-lang.org/stable/std/num/struct.NonZeroU8.html /// [2] https://doc.rust-lang.org/stable/std/num/struct.NonZeroI8.html /// @@ -1913,7 +1934,11 @@ safety_comment! { safety_comment! { /// SAFETY: - /// For all `T`, `PhantomData` has size 0 and alignment 1. [1] + /// Per reference [1]: + /// "For all T, the following are guaranteed: + /// size_of::>() == 0 + /// align_of::>() == 1". + /// This gives: /// - `FromZeroes`, `FromBytes`: There is only one possible sequence of 0 /// bytes, and `PhantomData` is inhabited. /// - `AsBytes`: Since `PhantomData` has size 0, it contains no padding @@ -1935,7 +1960,11 @@ safety_comment! { /// field, which is `pub`. Per the reference [2], this means that the /// `#[repr(transparent)]` attribute is "considered part of the public ABI". /// - /// [1] https://doc.rust-lang.org/nightly/core/num/struct.Wrapping.html#layout-1 + /// TODO(#429): Add quotes from documentation. + /// + /// [1] TODO(https://doc.rust-lang.org/nightly/core/num/struct.Wrapping.html#layout-1): + /// Reference this documentation once it's available on stable. + /// /// [2] https://doc.rust-lang.org/nomicon/other-reprs.html#reprtransparent unsafe_impl!(T: FromZeroes => FromZeroes for Wrapping); unsafe_impl!(T: FromBytes => FromBytes for Wrapping); @@ -1954,11 +1983,10 @@ safety_comment! { /// Thus, we require `T: FromZeroes` and `T: FromBytes` in order to ensure /// that `T` - and thus `MaybeUninit` - contains to `UnsafeCell`s. /// Thus, requiring that `T` implement each of these traits is sufficient - /// - `Unaligned`: `MaybeUninit` is guaranteed by its documentation [1] - /// to have the same alignment as `T`. + /// - `Unaligned`: "MaybeUninit is guaranteed to have the same size, + /// alignment, and ABI as T" [1] /// - /// [1] - /// https://doc.rust-lang.org/nightly/core/mem/union.MaybeUninit.html#layout-1 + /// [1] https://doc.rust-lang.org/stable/core/mem/union.MaybeUninit.html#layout-1 /// /// TODO(https://github.com/google/zerocopy/issues/251): If we split /// `FromBytes` and `RefFromBytes`, or if we introduce a separate @@ -1988,12 +2016,14 @@ safety_comment! { /// - `Unaligned`: `ManuallyDrop` has the same layout (and thus alignment) /// as `T`, and `T: Unaligned` guarantees that that alignment is 1. /// - /// [1] Per https://doc.rust-lang.org/nightly/core/mem/struct.ManuallyDrop.html: - /// /// `ManuallyDrop` is guaranteed to have the same layout and bit /// validity as `T` /// - /// TODO(#429): Once this text (added in + /// [1] Per https://doc.rust-lang.org/nightly/core/mem/struct.ManuallyDrop.html: + /// + /// TODO(#429): + /// - Add quotes from docs. + /// - Once [1] (added in /// https://github.com/rust-lang/rust/pull/115522) is available on stable, /// quote the stable docs instead of the nightly docs. unsafe_impl!(T: ?Sized + FromZeroes => FromZeroes for ManuallyDrop);