html-to-markdown 2.23.4 → 2.24.1

data/rust-vendor/zerocopy/src/pointer/transmute.rs

@@ -13,7 +13,10 @@ use core::{
 };
 
 use crate::{
-    pointer::{cast, invariant::*},
+    pointer::{
+        cast::{self, CastExact, CastSizedExact},
+        invariant::*,
+    },
     FromBytes, Immutable, IntoBytes, Unalign,
 };
 
@@ -30,26 +33,31 @@ use crate::{
 ///
 /// ## Post-conditions
 ///
-/// Given `Dst: TryTransmuteFromPtr<Src, A, SV, DV, _>`, callers may assume the
-/// following:
+/// Given `Dst: TryTransmuteFromPtr<Src, A, SV, DV, C, _>`, callers may assume
+/// the following:
 ///
 /// Given `src: Ptr<'a, Src, (A, _, SV)>`, if the referent of `src` is
 /// `DV`-valid for `Dst`, then it is sound to transmute `src` into `dst: Ptr<'a,
-/// Dst, (A, Unaligned, DV)>` by preserving pointer address and metadata.
+/// Dst, (A, Unaligned, DV)>` using `C`.
 ///
 /// ## Pre-conditions
 ///
 /// Given `src: Ptr<Src, (A, _, SV)>` and `dst: Ptr<Dst, (A, Unaligned, DV)>`,
-/// `Dst: TryTransmuteFromPtr<Src, A, SV, DV, _>` is sound if all of the
+/// `Dst: TryTransmuteFromPtr<Src, A, SV, DV, C, _>` is sound if all of the
 /// following hold:
 /// - Forwards transmutation: Either of the following hold:
 ///   - So long as `dst` is active, no mutation of `dst`'s referent is allowed
 ///     except via `dst` itself
-///   - The set of `DV`-valid `Dst`s is a superset of the set of `SV`-valid
-///     `Src`s
+///   - The set of `DV`-valid referents of `dst` is a superset of the set of
+///     `SV`-valid referents of `src` (NOTE: this condition effectively bans
+///     shrinking or overwriting transmutes, which cannot satisfy this
+///     condition)
 /// - Reverse transmutation: Either of the following hold:
 ///   - `dst` does not permit mutation of its referent
-///   - The set of `DV`-valid `Dst`s is a subset of the set of `SV`-valid `Src`s
+///   - The set of `DV`-valid referents of `dst` is a subset of the set of
+///     `SV`-valid referents of `src` (NOTE: this condition effectively bans
+///     shrinking or overwriting transmutes, which cannot satisfy this
+///     condition)
 /// - No safe code, given access to `src` and `dst`, can cause undefined
 ///   behavior: Any of the following hold:
 ///   - `A` is `Exclusive`
@@ -62,60 +70,51 @@ use crate::{
 /// Given:
 /// - `src: Ptr<'a, Src, (A, _, SV)>`
 /// - `src`'s referent is `DV`-valid for `Dst`
-/// - `Dst: SizeEq<Src>`
 ///
-/// We are trying to prove that it is sound to perform a pointer address- and
-/// metadata-preserving transmute from `src` to a `dst: Ptr<'a, Dst, (A,
-/// Unaligned, DV)>`. We need to prove that such a transmute does not violate
-/// any of `src`'s invariants, and that it satisfies all invariants of the
-/// destination `Ptr` type.
+/// We are trying to prove that it is sound to perform a cast from `src` to a
+/// `dst: Ptr<'a, Dst, (A, Unaligned, DV)>` using `C`. We need to prove that
+/// such a cast does not violate any of `src`'s invariants, and that it
+/// satisfies all invariants of the destination `Ptr` type.
 ///
-/// First, all of `src`'s `PtrInner` invariants are upheld. `src`'s address and
-/// metadata are unchanged, so:
-/// - If its referent is not zero sized, then it still has valid provenance for
-///   its referent, which is still entirely contained in some Rust allocation,
-///   `A`
-/// - If its referent is not zero sized, `A` is guaranteed to live for at least
-///   `'a`
-///
-/// Since `Dst: SizeEq<Src>`, and since `dst` has the same address and metadata
-/// as `src`, `dst` addresses the same byte range as `src`. `dst` also has the
-/// same lifetime as `src`. Therefore, all of the `PtrInner` invariants
-/// mentioned above also hold for `dst`.
-///
-/// Second, since `src`'s address is unchanged, it still satisfies its
-/// alignment. Since `dst`'s alignment is `Unaligned`, it trivially satisfies
+/// First, by `C: CastExact`, `src`'s address is unchanged, so it still satisfies
+/// its alignment. Since `dst`'s alignment is `Unaligned`, it trivially satisfies
 /// its alignment.
 ///
-/// Third, aliasing is either `Exclusive` or `Shared`:
+/// Second, aliasing is either `Exclusive` or `Shared`:
 /// - If it is `Exclusive`, then both `src` and `dst` satisfy `Exclusive`
 ///   aliasing trivially: since `src` and `dst` have the same lifetime, `src` is
 ///   inaccessible so long as `dst` is alive, and no other live `Ptr`s or
 ///   references may reference the same referent.
 /// - If it is `Shared`, then either:
-///   - `Src: Immutable` and `Dst: Immutable`, and so `UnsafeCell`s trivially
-///     cover the same byte ranges in both types.
+///   - `Src: Immutable` and `Dst: Immutable`, and so neither `src` nor `dst`
+///     permit interior mutation.
 ///   - It is explicitly sound for safe code to operate on a `&Src` and a `&Dst`
 ///     pointing to the same byte range at the same time.
 ///
-/// Fourth, `src`'s validity is satisfied. By invariant, `src`'s referent began
+/// Third, `src`'s validity is satisfied. By invariant, `src`'s referent began
 /// as an `SV`-valid `Src`. It is guaranteed to remain so, as either of the
 /// following hold:
 /// - `dst` does not permit mutation of its referent.
-/// - The set of `DV`-valid `Dst`s is a superset of the set of `SV`-valid
-///   `Src`s. Thus, any value written via `dst` is guaranteed to be `SV`-valid
-///   for `Src`.
+/// - The set of `DV`-valid referents of `dst` is a subset of the set of
+///   `SV`-valid referents of `src`. Thus, any value written via `dst` is
+///   guaranteed to be an `SV`-valid referent of `src`.
 ///
-/// Fifth, `dst`'s validity is satisfied. It is a given of this proof that the
+/// Fourth, `dst`'s validity is satisfied. It is a given of this proof that the
 /// referent is `DV`-valid for `Dst`. It is guaranteed to remain so, as either
 /// of the following hold:
 /// - So long as `dst` is active, no mutation of the referent is allowed except
 ///   via `dst` itself.
-/// - The set of `DV`-valid `Dst`s is a superset of the set of `SV`-valid
-///   `Src`s. Thus, any value written via `src` is guaranteed to be a `DV`-valid
-///   `Dst`.
-pub unsafe trait TryTransmuteFromPtr<Src: ?Sized, A: Aliasing, SV: Validity, DV: Validity, R>:
-    SizeEq<Src>
+/// - The set of `DV`-valid referents of `dst` is a superset of the set of
+///   `SV`-valid referents of `src`. Thus, any value written via `src` is
+///   guaranteed to be a `DV`-valid referent of `dst`.
+pub unsafe trait TryTransmuteFromPtr<
+    Src: ?Sized,
+    A: Aliasing,
+    SV: Validity,
+    DV: Validity,
+    C: CastExact<Src, Self>,
+    R,
+>
 {
 }
 
@@ -131,27 +130,30 @@ pub enum BecauseMutationCompatible {}
 //       exists, no mutation is permitted except via that `Ptr`
 //     - Aliasing is `Shared`, `Src: Immutable`, and `Dst: Immutable`, in which
 //       case no mutation is possible via either `Ptr`
-//   - `Dst: TransmuteFrom<Src, SV, DV>`. Since `Dst: SizeEq<Src>`, this bound
-//     guarantees that the set of `DV`-valid `Dst`s is a supserset of the set of
-//     `SV`-valid `Src`s.
-// - Reverse transmutation: `Src: TransmuteFrom<Dst, DV, SV>`. Since `Dst:
-//   SizeEq<Src>`, this guarantees that the set of `DV`-valid `Dst`s is a subset
-//   of the set of `SV`-valid `Src`s.
+//   - Since the underlying cast is size-preserving, `dst` addresses the same
+//     referent as `src`. By `Dst: TransmuteFrom<Src, SV, DV>`, the set of
+//     `DV`-valid referents of `dst` is a superset of the set of `SV`-valid
+//     referents of `src`.
+// - Reverse transmutation: Since the underlying cast is size-preserving, `dst`
+//   addresses the same referent as `src`. By `Src: TransmuteFrom<Dst, DV, SV>`,
+//   the set of `DV`-valid referents of `src` is a subset of the set of
+//   `SV`-valid referents of `dst`.
 // - No safe code, given access to `src` and `dst`, can cause undefined
 //   behavior: By `Dst: MutationCompatible<Src, A, SV, DV, _>`, at least one of
 //   the following holds:
 //   - `A` is `Exclusive`
 //   - `Src: Immutable` and `Dst: Immutable`
 //   - `Dst: InvariantsEq<Src>`, which guarantees that `Src` and `Dst` have the
-//     same invariants, and have `UnsafeCell`s covering the same byte ranges
-unsafe impl<Src, Dst, SV, DV, A, R>
-    TryTransmuteFromPtr<Src, A, SV, DV, (BecauseMutationCompatible, R)> for Dst
+//     same invariants, and permit interior mutation on the same byte ranges
+unsafe impl<Src, Dst, SV, DV, A, C, R>
+    TryTransmuteFromPtr<Src, A, SV, DV, C, (BecauseMutationCompatible, R)> for Dst
 where
     A: Aliasing,
     SV: Validity,
     DV: Validity,
     Src: TransmuteFrom<Dst, DV, SV> + ?Sized,
-    Dst: MutationCompatible<Src, A, SV, DV, R> + SizeEq<Src> + ?Sized,
+    Dst: MutationCompatible<Src, A, SV, DV, R> + ?Sized,
+    C: CastExact<Src, Dst>,
 {
 }
 
@@ -162,12 +164,14 @@ where
 //   `dst` does not permit mutation of its referent.
 // - No safe code, given access to `src` and `dst`, can cause undefined
 //   behavior: `Src: Immutable` and `Dst: Immutable`
-unsafe impl<Src, Dst, SV, DV> TryTransmuteFromPtr<Src, Shared, SV, DV, BecauseImmutable> for Dst
+unsafe impl<Src, Dst, SV, DV, C> TryTransmuteFromPtr<Src, Shared, SV, DV, C, BecauseImmutable>
+    for Dst
 where
     SV: Validity,
     DV: Validity,
     Src: Immutable + ?Sized,
-    Dst: Immutable + SizeEq<Src> + ?Sized,
+    Dst: Immutable + ?Sized,
+    C: CastExact<Src, Dst>,
 {
 }
 
@@ -188,11 +192,11 @@ pub unsafe trait MutationCompatible<Src: ?Sized, A: Aliasing, SV, DV, R> {}
 pub enum BecauseRead {}
 
 // SAFETY: `Src: Read<A, _>` and `Dst: Read<A, _>`.
-unsafe impl<Src: ?Sized, Dst: ?Sized, A: Aliasing, SV: Validity, DV: Validity, R, S>
-    MutationCompatible<Src, A, SV, DV, (BecauseRead, (R, S))> for Dst
+unsafe impl<Src: ?Sized, Dst: ?Sized, A: Aliasing, SV: Validity, DV: Validity, R>
+    MutationCompatible<Src, A, SV, DV, (BecauseRead, R)> for Dst
 where
     Src: Read<A, R>,
-    Dst: Read<A, S>,
+    Dst: Read<A, R>,
 {
 }
 
@@ -259,17 +263,30 @@ unsafe impl<T: ?Sized> InvariantsEq<ManuallyDrop<T>> for T {}
 ///
 /// `Dst: TransmuteFromPtr<Src, A, SV, DV, _>` is equivalent to `Dst:
 /// TryTransmuteFromPtr<Src, A, SV, DV, _> + TransmuteFrom<Src, SV, DV>`.
-pub unsafe trait TransmuteFromPtr<Src: ?Sized, A: Aliasing, SV: Validity, DV: Validity, R>:
-    TryTransmuteFromPtr<Src, A, SV, DV, R> + TransmuteFrom<Src, SV, DV>
+pub unsafe trait TransmuteFromPtr<
+    Src: ?Sized,
+    A: Aliasing,
+    SV: Validity,
+    DV: Validity,
+    C: CastExact<Src, Self>,
+    R,
+>: TryTransmuteFromPtr<Src, A, SV, DV, C, R> + TransmuteFrom<Src, SV, DV>
 {
 }
 
 // SAFETY: The `where` bounds are equivalent to the safety invariant on
 // `TransmuteFromPtr`.
-unsafe impl<Src: ?Sized, Dst: ?Sized, A: Aliasing, SV: Validity, DV: Validity, R>
-    TransmuteFromPtr<Src, A, SV, DV, R> for Dst
+unsafe impl<
+        Src: ?Sized,
+        Dst: ?Sized,
+        A: Aliasing,
+        SV: Validity,
+        DV: Validity,
+        C: CastExact<Src, Dst>,
+        R,
+    > TransmuteFromPtr<Src, A, SV, DV, C, R> for Dst
 where
-    Dst: TransmuteFrom<Src, SV, DV> + TryTransmuteFromPtr<Src, A, SV, DV, R>,
+    Dst: TransmuteFrom<Src, SV, DV> + TryTransmuteFromPtr<Src, A, SV, DV, C, R>,
 {
 }
 
@@ -287,24 +304,26 @@ where
 /// DV>` conveys no safety guarantee.
 pub unsafe trait TransmuteFrom<Src: ?Sized, SV, DV> {}
 
+/// Carries the ability to perform a size-preserving cast or conversion from a
+/// raw pointer to `Src` to a raw pointer to `Self`.
+///
+/// The cast/conversion is carried by the associated [`CastFrom`] type, and
+/// may be a no-op cast (without updating pointer metadata) or a conversion
+/// which updates pointer metadata.
+///
 /// # Safety
 ///
-/// `T` and `Self` must have the same vtable kind (`Sized`, slice DST, `dyn`,
-/// etc) and have the same size. In particular:
-/// - If `T: Sized` and `Self: Sized`, then their sizes must be equal
-/// - If `T: ?Sized` and `Self: ?Sized`, then `Self::CastFrom` must be a
-///   size-preserving cast. *Note that it is **not** guaranteed that an `as`
-///   cast preserves referent size: it may be the case that `Self::CastFrom`
-///   modifies the pointer's metadata in order to preserve referent size, which
-///   an `as` cast does not do.*
-pub unsafe trait SizeEq<T: ?Sized> {
-    type CastFrom: cast::Cast<T, Self>;
+/// `SizeEq` on its own conveys no safety guarantee. Any safety guarantees come
+/// from the safety invariants on the associated [`CastFrom`] type, specifically
+/// the [`CastExact`] bound.
+///
+/// [`CastFrom`]: SizeEq::CastFrom
+/// [`CastExact`]: CastExact
+pub trait SizeEq<Src: ?Sized> {
+    type CastFrom: CastExact<Src, Self>;
 }
 
-// SAFETY: `T` trivially has the same size and vtable kind as `T`, and since
-// pointer `*mut T -> *mut T` pointer casts are no-ops, this cast trivially
-// preserves referent size (when `T: ?Sized`).
-unsafe impl<T: ?Sized> SizeEq<T> for T {
+impl<T: ?Sized> SizeEq<T> for T {
     type CastFrom = cast::IdCast;
 }
 
@@ -458,19 +477,12 @@ impl_transitive_transmute_from!(T: ?Sized => UnsafeCell<T> => T => Cell<T>);
 // https://doc.rust-lang.org/1.85.0/core/mem/union.MaybeUninit.html
 unsafe impl<T> TransmuteFrom<T, Uninit, Valid> for MaybeUninit<T> {}
 
-// SAFETY: `MaybeUninit<T>` has the same size as `T` [1].
-//
-// [1] Per https://doc.rust-lang.org/1.81.0/std/mem/union.MaybeUninit.html#layout-1:
-//
-//   `MaybeUninit<T>` is guaranteed to have the same size, alignment, and ABI as
-//   `T`
-unsafe impl<T> SizeEq<T> for MaybeUninit<T> {
-    type CastFrom = cast::CastSized;
+impl<T> SizeEq<T> for MaybeUninit<T> {
+    type CastFrom = CastSizedExact;
 }
 
-// SAFETY: See previous safety comment.
-unsafe impl<T> SizeEq<MaybeUninit<T>> for T {
-    type CastFrom = cast::CastSized;
+impl<T> SizeEq<MaybeUninit<T>> for T {
+    type CastFrom = CastSizedExact;
 }
 
 #[cfg(test)]
@@ -504,23 +516,4 @@ mod tests {
         // T: ?Sized => UnsafeCell<T> => T => Cell<T>
         test_size_eq::<UnsafeCell<u8>, Cell<u8>>(UnsafeCell::new(0u8));
     }
-
-    #[cfg(not(no_zerocopy_target_has_atomics_1_60_0))]
-    #[cfg(target_has_atomic = "8")]
-    #[test]
-    fn test_atomic_u8_transmutes() {
-        use core::sync::atomic::AtomicU8;
-
-        // 1. Atomic -> Prim (SizeEq<Atomic> for Prim)
-        test_size_eq::<AtomicU8, u8>(AtomicU8::new(0));
-
-        // 2. Prim -> Atomic (SizeEq<Prim> for Atomic)
-        test_size_eq::<u8, AtomicU8>(0u8);
-
-        // 3. Atomic -> UnsafeCell<Prim> (SizeEq<Atomic> for UnsafeCell<Prim>)
-        test_size_eq::<AtomicU8, UnsafeCell<u8>>(AtomicU8::new(0));
-
-        // 4. UnsafeCell<Prim> -> Atomic (SizeEq<UnsafeCell<Prim>> for Atomic)
-        test_size_eq::<UnsafeCell<u8>, AtomicU8>(UnsafeCell::new(0u8));
-    }
 }

data/rust-vendor/zerocopy/src/ref.rs

@@ -681,7 +681,7 @@ where
                 cast_for_sized::<
                     T,
                     _,
-                    (BecauseRead, (BecauseExclusive, BecauseExclusive)),
+                    (BecauseRead, BecauseExclusive),
                     (BecauseMutationCompatible, BecauseInvariantsEq),
                 >(ptr)
             };
@@ -857,7 +857,7 @@ where
                 cast_for_sized::<
                     T,
                     _,
-                    (BecauseRead, (BecauseExclusive, BecauseExclusive)),
+                    (BecauseRead, BecauseExclusive),
                     (BecauseMutationCompatible, BecauseInvariantsEq),
                 >(ptr)
             };
@@ -876,7 +876,7 @@ where
         let ptr = Ptr::from_mut(b)
             .try_cast_into_no_leftover::<T, BecauseExclusive>(None)
             .expect("zerocopy internal error: DerefMut::deref_mut should be infallible");
-        let ptr = ptr.recall_validity::<_, (_, (_, (BecauseExclusive, BecauseExclusive)))>();
+        let ptr = ptr.recall_validity::<_, (_, (_, BecauseExclusive))>();
         ptr.as_mut()
     }
 }
@@ -960,7 +960,7 @@ where
     T: FromBytes + KnownLayout + ?Sized,
     A: crate::invariant::Aliasing,
     [u8]: MutationCompatible<T, A, Initialized, Initialized, R>,
-    T: TransmuteFromPtr<T, A, Initialized, Valid, S>,
+    T: TransmuteFromPtr<T, A, Initialized, Valid, crate::pointer::cast::IdCast, S>,
 {
     use crate::pointer::cast::{Cast, Project};