From 33e2d7e8de66dc577b4e61830ee1dc0168f76d97 Mon Sep 17 00:00:00 2001 From: Jack Wrenn Date: Tue, 27 Aug 2024 14:05:54 +0000 Subject: [PATCH] safe transmute: Rename `BikeshedIntrinsicFrom` to `TransmuteFrom` As our implementation of MCP411 nears completion and we begin to solicit testing, it's no longer reasonable to expect testers to type or remember `BikeshedIntrinsicFrom`. The name degrades the ease-of-reading of documentation, and the overall experience of using compiler safe transmute. Tentatively, we'll instead adopt `TransmuteFrom`. This name seems to be the one most likely to be stabilized, after discussion on Zulip [1]. We may want to revisit the ordering of `Src` and `Dst` before stabilization, at which point we'd likely consider `TransmuteInto` or `Transmute`. [1] https://rust-lang.zulipchat.com/#narrow/stream/216762-project-safe-transmute/topic/What.20should.20.60BikeshedIntrinsicFrom.60.20be.20named.3F --- core/src/mem/mod.rs | 2 +- core/src/mem/transmutability.rs | 109 ++++++++++++++++---------------- 2 files changed, 54 insertions(+), 57 deletions(-) diff --git a/core/src/mem/mod.rs b/core/src/mem/mod.rs index 7a9ca4011be84..e602b497d171a 100644 --- a/core/src/mem/mod.rs +++ b/core/src/mem/mod.rs @@ -19,7 +19,7 @@ pub use maybe_uninit::MaybeUninit; mod transmutability; #[unstable(feature = "transmutability", issue = "99571")] -pub use transmutability::{Assume, BikeshedIntrinsicFrom}; +pub use transmutability::{Assume, TransmuteFrom}; #[stable(feature = "rust1", since = "1.0.0")] #[doc(inline)] diff --git a/core/src/mem/transmutability.rs b/core/src/mem/transmutability.rs index 62d454a5289b1..049b32ede9c3d 100644 --- a/core/src/mem/transmutability.rs +++ b/core/src/mem/transmutability.rs @@ -11,10 +11,10 @@ use crate::marker::{ConstParamTy_, UnsizedConstParamTy}; /// /// # Safety /// -/// If `Dst: BikeshedIntrinsicFrom`, the compiler guarantees -/// that `Src` is soundly *union-transmutable* into a value of type `Dst`, -/// provided that the programmer has guaranteed that the given -/// [`ASSUMPTIONS`](Assume) are satisfied. +/// If `Dst: TransmuteFrom`, the compiler guarantees that +/// `Src` is soundly *union-transmutable* into a value of type `Dst`, provided +/// that the programmer has guaranteed that the given [`ASSUMPTIONS`](Assume) +/// are satisfied. /// /// A union-transmute is any bit-reinterpretation conversion in the form of: /// @@ -47,7 +47,7 @@ use crate::marker::{ConstParamTy_, UnsizedConstParamTy}; #[cfg_attr(not(bootstrap), doc = "```rust")] /// #![feature(transmutability)] /// -/// use core::mem::{Assume, BikeshedIntrinsicFrom}; +/// use core::mem::{Assume, TransmuteFrom}; /// /// let src = 42u8; // size = 1 /// @@ -55,7 +55,7 @@ use crate::marker::{ConstParamTy_, UnsizedConstParamTy}; /// struct Dst(u8); // size = 2 // /// let _ = unsafe { -/// >::transmute(src) +/// >::transmute(src) /// }; /// ``` /// @@ -87,7 +87,7 @@ use crate::marker::{ConstParamTy_, UnsizedConstParamTy}; #[lang = "transmute_trait"] #[rustc_deny_explicit_impl(implement_via_object = false)] #[rustc_coinductive] -pub unsafe trait BikeshedIntrinsicFrom +pub unsafe trait TransmuteFrom where Src: ?Sized, { @@ -140,23 +140,21 @@ where } } -/// Configurable proof assumptions of [`BikeshedIntrinsicFrom`]. +/// Configurable proof assumptions of [`TransmuteFrom`]. /// /// When `false`, the respective proof obligation belongs to the compiler. When /// `true`, the onus of the safety proof belongs to the programmer. -/// [`BikeshedIntrinsicFrom`]. #[unstable(feature = "transmutability", issue = "99571")] #[lang = "transmute_opts"] #[derive(PartialEq, Eq, Clone, Copy, Debug)] pub struct Assume { - /// When `false`, [`BikeshedIntrinsicFrom`] is not implemented for - /// transmutations that might violate the the alignment requirements of - /// references; e.g.: + /// When `false`, [`TransmuteFrom`] is not implemented for transmutations + /// that might violate the the alignment requirements of references; e.g.: /// #[cfg_attr(bootstrap, doc = "```rust,ignore not runnable on bootstrap")] #[cfg_attr(not(bootstrap), doc = "```compile_fail,E0277")] /// #![feature(transmutability)] - /// use core::mem::{align_of, BikeshedIntrinsicFrom}; + /// use core::mem::{align_of, TransmuteFrom}; /// /// assert_eq!(align_of::<[u8; 2]>(), 1); /// assert_eq!(align_of::(), 2); @@ -165,18 +163,18 @@ pub struct Assume { /// /// // SAFETY: No safety obligations. /// let dst: &u16 = unsafe { - /// <_ as BikeshedIntrinsicFrom<_>>::transmute(src) + /// <_ as TransmuteFrom<_>>::transmute(src) /// }; /// ``` /// - /// When `true`, [`BikeshedIntrinsicFrom`] assumes that *you* have ensured + /// When `true`, [`TransmuteFrom`] assumes that *you* have ensured /// that references in the transmuted value satisfy the alignment /// requirements of their referent types; e.g.: /// #[cfg_attr(bootstrap, doc = "```rust,ignore not runnable on bootstrap")] #[cfg_attr(not(bootstrap), doc = "```rust")] /// #![feature(pointer_is_aligned_to, transmutability)] - /// use core::mem::{align_of, Assume, BikeshedIntrinsicFrom}; + /// use core::mem::{align_of, Assume, TransmuteFrom}; /// /// let src: &[u8; 2] = &[0xFF, 0xFF]; /// @@ -184,7 +182,7 @@ pub struct Assume { /// // SAFETY: We have checked above that the address of `src` satisfies the /// // alignment requirements of `u16`. /// Some(unsafe { - /// <_ as BikeshedIntrinsicFrom<_, { Assume::ALIGNMENT }>>::transmute(src) + /// <_ as TransmuteFrom<_, { Assume::ALIGNMENT }>>::transmute(src) /// }) /// } else { /// None @@ -194,21 +192,21 @@ pub struct Assume { /// ``` pub alignment: bool, - /// When `false`, [`BikeshedIntrinsicFrom`] is not implemented for - /// transmutations that extend the lifetimes of references. + /// When `false`, [`TransmuteFrom`] is not implemented for transmutations + /// that extend the lifetimes of references. /// - /// When `true`, [`BikeshedIntrinsicFrom`] assumes that *you* have ensured - /// that references in the transmuted value do not outlive their referents. + /// When `true`, [`TransmuteFrom`] assumes that *you* have ensured that + /// references in the transmuted value do not outlive their referents. pub lifetimes: bool, - /// When `false`, [`BikeshedIntrinsicFrom`] is not implemented for - /// transmutations that might violate the library safety invariants of the - /// destination type; e.g.: + /// When `false`, [`TransmuteFrom`] is not implemented for transmutations + /// that might violate the library safety invariants of the destination + /// type; e.g.: /// #[cfg_attr(bootstrap, doc = "```rust,ignore not runnable on bootstrap")] #[cfg_attr(not(bootstrap), doc = "```compile_fail,E0277")] /// #![feature(transmutability)] - /// use core::mem::BikeshedIntrinsicFrom; + /// use core::mem::TransmuteFrom; /// /// let src: u8 = 3; /// @@ -219,18 +217,18 @@ pub struct Assume { /// /// // SAFETY: No safety obligations. /// let dst: EvenU8 = unsafe { - /// <_ as BikeshedIntrinsicFrom<_>>::transmute(src) + /// <_ as TransmuteFrom<_>>::transmute(src) /// }; /// ``` /// - /// When `true`, [`BikeshedIntrinsicFrom`] assumes that *you* have ensured + /// When `true`, [`TransmuteFrom`] assumes that *you* have ensured /// that undefined behavior does not arise from using the transmuted value; /// e.g.: /// #[cfg_attr(bootstrap, doc = "```rust,ignore not runnable on bootstrap")] #[cfg_attr(not(bootstrap), doc = "```rust")] /// #![feature(transmutability)] - /// use core::mem::{Assume, BikeshedIntrinsicFrom}; + /// use core::mem::{Assume, TransmuteFrom}; /// /// let src: u8 = 42; /// @@ -242,7 +240,7 @@ pub struct Assume { /// let maybe_dst: Option = if src % 2 == 0 { /// // SAFETY: We have checked above that the value of `src` is even. /// Some(unsafe { - /// <_ as BikeshedIntrinsicFrom<_, { Assume::SAFETY }>>::transmute(src) + /// <_ as TransmuteFrom<_, { Assume::SAFETY }>>::transmute(src) /// }) /// } else { /// None @@ -252,31 +250,31 @@ pub struct Assume { /// ``` pub safety: bool, - /// When `false`, [`BikeshedIntrinsicFrom`] is not implemented for - /// transmutations that might violate the language-level bit-validity - /// invariant of the destination type; e.g.: + /// When `false`, [`TransmuteFrom`] is not implemented for transmutations + /// that might violate the language-level bit-validity invariant of the + /// destination type; e.g.: /// #[cfg_attr(bootstrap, doc = "```rust,ignore not runnable on bootstrap")] #[cfg_attr(not(bootstrap), doc = "```compile_fail,E0277")] /// #![feature(transmutability)] - /// use core::mem::BikeshedIntrinsicFrom; + /// use core::mem::TransmuteFrom; /// /// let src: u8 = 3; /// /// // SAFETY: No safety obligations. /// let dst: bool = unsafe { - /// <_ as BikeshedIntrinsicFrom<_>>::transmute(src) + /// <_ as TransmuteFrom<_>>::transmute(src) /// }; /// ``` /// - /// When `true`, [`BikeshedIntrinsicFrom`] assumes that *you* have ensured + /// When `true`, [`TransmuteFrom`] assumes that *you* have ensured /// that the value being transmuted is a bit-valid instance of the /// transmuted value; e.g.: /// #[cfg_attr(bootstrap, doc = "```rust,ignore not runnable on bootstrap")] #[cfg_attr(not(bootstrap), doc = "```rust")] /// #![feature(transmutability)] - /// use core::mem::{Assume, BikeshedIntrinsicFrom}; + /// use core::mem::{Assume, TransmuteFrom}; /// /// let src: u8 = 1; /// @@ -284,7 +282,7 @@ pub struct Assume { /// // SAFETY: We have checked above that the value of `src` is a bit-valid /// // instance of `bool`. /// Some(unsafe { - /// <_ as BikeshedIntrinsicFrom<_, { Assume::VALIDITY }>>::transmute(src) + /// <_ as TransmuteFrom<_, { Assume::VALIDITY }>>::transmute(src) /// }) /// } else { /// None @@ -301,35 +299,34 @@ impl ConstParamTy_ for Assume {} impl UnsizedConstParamTy for Assume {} impl Assume { - /// With this, [`BikeshedIntrinsicFrom`] does not assume you have ensured - /// any safety obligations are met, and relies only upon its own analysis to - /// (dis)prove transmutability. + /// With this, [`TransmuteFrom`] does not assume you have ensured any safety + /// obligations are met, and relies only upon its own analysis to (dis)prove + /// transmutability. #[unstable(feature = "transmutability", issue = "99571")] pub const NOTHING: Self = Self { alignment: false, lifetimes: false, safety: false, validity: false }; - /// With this, [`BikeshedIntrinsicFrom`] assumes only that you have ensured - /// that references in the transmuted value satisfy the alignment - /// requirements of their referent types. See [`Assume::alignment`] for - /// examples. + /// With this, [`TransmuteFrom`] assumes only that you have ensured that + /// references in the transmuted value satisfy the alignment requirements of + /// their referent types. See [`Assume::alignment`] for examples. #[unstable(feature = "transmutability", issue = "99571")] pub const ALIGNMENT: Self = Self { alignment: true, ..Self::NOTHING }; - /// With this, [`BikeshedIntrinsicFrom`] assumes only that you have ensured - /// that references in the transmuted value do not outlive their referents. - /// See [`Assume::lifetimes`] for examples. + /// With this, [`TransmuteFrom`] assumes only that you have ensured that + /// references in the transmuted value do not outlive their referents. See + /// [`Assume::lifetimes`] for examples. #[unstable(feature = "transmutability", issue = "99571")] pub const LIFETIMES: Self = Self { lifetimes: true, ..Self::NOTHING }; - /// With this, [`BikeshedIntrinsicFrom`] assumes only that you have ensured - /// that undefined behavior does not arise from using the transmuted value. - /// See [`Assume::safety`] for examples. + /// With this, [`TransmuteFrom`] assumes only that you have ensured that + /// undefined behavior does not arise from using the transmuted value. See + /// [`Assume::safety`] for examples. #[unstable(feature = "transmutability", issue = "99571")] pub const SAFETY: Self = Self { safety: true, ..Self::NOTHING }; - /// With this, [`BikeshedIntrinsicFrom`] assumes only that you have ensured - /// that the value being transmuted is a bit-valid instance of the - /// transmuted value. See [`Assume::validity`] for examples. + /// With this, [`TransmuteFrom`] assumes only that you have ensured that the + /// value being transmuted is a bit-valid instance of the transmuted value. + /// See [`Assume::validity`] for examples. #[unstable(feature = "transmutability", issue = "99571")] pub const VALIDITY: Self = Self { validity: true, ..Self::NOTHING }; @@ -348,7 +345,7 @@ impl Assume { /// transmutability, /// )] /// #![allow(incomplete_features)] - /// use core::mem::{align_of, Assume, BikeshedIntrinsicFrom}; + /// use core::mem::{align_of, Assume, TransmuteFrom}; /// /// /// Attempts to transmute `src` to `&Dst`. /// /// @@ -360,7 +357,7 @@ impl Assume { /// /// alignment, are satisfied. /// unsafe fn try_transmute_ref<'a, Src, Dst, const ASSUME: Assume>(src: &'a Src) -> Option<&'a Dst> /// where - /// &'a Dst: BikeshedIntrinsicFrom<&'a Src, { ASSUME.and(Assume::ALIGNMENT) }>, + /// &'a Dst: TransmuteFrom<&'a Src, { ASSUME.and(Assume::ALIGNMENT) }>, /// { /// if <*const _>::is_aligned_to(src, align_of::()) { /// // SAFETY: By the above dynamic check, we have ensured that the address @@ -368,7 +365,7 @@ impl Assume { /// // on the caller, the safety obligations required by `ASSUME` have also /// // been satisfied. /// Some(unsafe { - /// <_ as BikeshedIntrinsicFrom<_, { ASSUME.and(Assume::ALIGNMENT) }>>::transmute(src) + /// <_ as TransmuteFrom<_, { ASSUME.and(Assume::ALIGNMENT) }>>::transmute(src) /// }) /// } else { /// None