Skip to content

Commit

Permalink
Rollup merge of rust-lang#129657 - jswrenn:transmute-name, r=compiler…
Browse files Browse the repository at this point in the history 
…-errors

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

Tracking Issue: rust-lang#99571

r​? `@compiler-errors`
  • Loading branch information
@matthiaskrgr
matthiaskrgr authored Aug 28, 2024
2 parents 1d44fab + 33e2d7e commit 5a4fe40
Show file tree
Hide file tree
Showing 2 changed files with 54 additions and 57 deletions.
2 changes: 1 addition & 1 deletion core/src/mem/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)]
Expand Down
109 changes: 53 additions & 56 deletions core/src/mem/transmutability.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,10 @@ use crate::marker::{ConstParamTy_, UnsizedConstParamTy};
///
/// # Safety
///
/// If `Dst: BikeshedIntrinsicFrom<Src, ASSUMPTIONS>`, 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<Src, ASSUMPTIONS>`, 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:
///
Expand Down Expand Up @@ -47,15 +47,15 @@ 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
///
/// #[repr(C, align(2))]
/// struct Dst(u8); // size = 2
//
/// let _ = unsafe {
/// <Dst as BikeshedIntrinsicFrom<u8, { Assume::SAFETY }>>::transmute(src)
/// <Dst as TransmuteFrom<u8, { Assume::SAFETY }>>::transmute(src)
/// };
/// ```
///
Expand Down Expand Up @@ -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<Src, const ASSUME: Assume = { Assume::NOTHING }>
pub unsafe trait TransmuteFrom<Src, const ASSUME: Assume = { Assume::NOTHING }>
where
Src: ?Sized,
{
Expand Down Expand Up @@ -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::<u16>(), 2);
Expand All @@ -165,26 +163,26 @@ 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];
///
/// let maybe_dst: Option<&u16> = if <*const _>::is_aligned_to(src, align_of::<u16>()) {
/// // 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
Expand All @@ -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;
///
Expand All @@ -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;
///
Expand All @@ -242,7 +240,7 @@ pub struct Assume {
/// let maybe_dst: Option<EvenU8> = 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
Expand All @@ -252,39 +250,39 @@ 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;
///
/// let maybe_dst: Option<bool> = if src == 0 || src == 1 {
/// // 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
Expand All @@ -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 };

Expand All @@ -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`.
/// ///
Expand All @@ -360,15 +357,15 @@ 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::<Dst>()) {
/// // SAFETY: By the above dynamic check, we have ensured that the address
/// // of `src` satisfies the alignment requirements of `&Dst`. By contract
/// // 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
Expand Down

0 comments on commit 5a4fe40

Please sign in to comment.