Permit shrinking transmutes in transmute machinery

Makes progress on #2701, #1940, #1852

gherrit-pr-id: Gd9d1c0de851091ffe6161889d21ca2167845a591

Author: joshlf

src/pointer/transmute.rs

@@ -13,8 +13,8 @@ use core::{
 };
 
 use crate::{
-    pointer::{cast, invariant::*},
     FromBytes, Immutable, IntoBytes, Unalign,
+    pointer::{cast, invariant::*},
 };
 
 /// Transmutations which are sound to attempt, conditional on validating the bit
@@ -46,15 +46,14 @@ use crate::{
 ///   - So long as `dst` is active, no mutation of `dst`'s referent is allowed
 ///     except via `dst` itself
 ///   - 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)
+///     (the prefixes of) `SV`-valid referents of `src`. The "prefix" caveat is
+///     necessary since this may be a shrinking transmute – ie, `dst` addresses
+///     a smaller referent than `src`.
 /// - Reverse transmutation: Either of the following hold:
 ///   - `dst` does not permit mutation of its referent
-///   - 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)
+///   - `<Dst as SizeEq<Src>>::CastFrom: CastExact`, and the set of `DV`-valid
+///     referents of `dst` is a subset of the set of `SV`-valid referents of
+///     `src`
 /// - No safe code, given access to `src` and `dst`, can cause undefined
 ///   behavior: Any of the following hold:
 ///   - `A` is `Exclusive`
@@ -94,18 +93,21 @@ use crate::{
 /// 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 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`.
+/// - `<Dst as SizeEq<Src>>::CastFrom: CastExact`, and the set of `DV`-valid
+///   referents of `dst` is a subset of the set of `SV`-valid referents of
+///   `src`. By `CastExact`, `src` and `dst` address the same number of bytes.
+///   Thus, any value written via `dst` is guaranteed to be an `SV`-valid
+///   referent of `src`.
 ///
 /// 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 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`.
+///   (the prefixes of) `SV`-valid referents of `src`. Thus, (the prefix of) 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, R>:
     SizeEq<Src>
 {
@@ -123,14 +125,14 @@ 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`
-//   - Since the underlying cast is performed using `<Dst as SizeEq<Src>>
-//     ::CastFrom::project`, `dst` addresses the same bytes as `src`. By `Dst:
-//     TransmuteFrom<Src, SV, DV>`, the set of `DV`-valid referents of `dst` is a
-//     supserset of the set of `SV`-valid referents of `src`.
+//   - By `Dst: TransmuteFrom<Src, SV, DV>`, the set of `DV`-valid referents of
+//     `dst` is a supserset of the set of (the prefixes of) `SV`-valid referents
+//     of `src`.
 // - Reverse transmutation: Since the underlying cast is performed using `<Dst
-//   as SizeEq<Src>>::CastFrom::project`, `dst` addresses the same bytes as
-//   `src`. By `Src: TransmuteFrom<Dst, DV, SV>`, the set of `DV`-valid
-//   referents of `dst` is a subset of the set of `SV`-valid referents of `src`.
+//   as SizeEq<Src>>::CastFrom::project`, and since `Dst::CastFrom: CastExact`,
+//   `dst` addresses the same bytes as `src`. By `Src: TransmuteFrom<Dst, DV,
+//   SV>`, the set of `DV`-valid referents of `dst` is a subset of the set of
+//   `SV`-valid referents of `src`.
 // - 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:
@@ -146,6 +148,7 @@ where
     DV: Validity,
     Src: TransmuteFrom<Dst, DV, SV> + ?Sized,
     Dst: MutationCompatible<Src, A, SV, DV, R> + SizeEq<Src> + ?Sized,
+    Dst::CastFrom: cast::CastExact<Src, Dst>,
 {
 }
 
@@ -267,6 +270,12 @@ where
 {
 }
 
+// TODO: We need to update the invariant of `TransmuteFrom` in order to make the
+// "reverse transmutation" impl of `TryTransmuteFromPtr` sound – currently, it
+// says that `Dst: TransmuteFrom<Src>` guarantees transmutation *even in the
+// case of a shrinking transmute*, but that's not currently guaranteed by
+// `TransmuteFrom`'s safety invariant.
+
 /// Denotes that any `SV`-valid `Src` may soundly be transmuted into a
 /// `DV`-valid `Self`.
 ///
@@ -292,12 +301,12 @@ pub unsafe trait TransmuteFrom<Src: ?Sized, SV, DV> {}
 ///
 /// `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.
+/// the [`Cast`] bound.
 ///
 /// [`CastFrom`]: SizeEq::CastFrom
-/// [`CastExact`]: cast::CastExact
+/// [`Cast`]: cast::Cast
 pub trait SizeEq<Src: ?Sized> {
-    type CastFrom: cast::CastExact<Src, Self>;
+    type CastFrom: cast::Cast<Src, Self>;
 }
 
 impl<T: ?Sized> SizeEq<T> for T {