Initial commit of Ptr pointer type

`Ptr` is like `NonNull`, but has many restrictions which make it so that
using a `Ptr` in unsafe code requires much simpler soundness proofs.
Notably, it supports a `try_cast_into<U>` method where `U: ?Sized +
KnownLayout`, which is a building block of `TryFromBytes`.

Author: joshlf

src/lib.rs

@@ -195,17 +195,27 @@ use core::{
         NonZeroU16, NonZeroU32, NonZeroU64, NonZeroU8, NonZeroUsize, Wrapping,
     },
     ops::{Deref, DerefMut},
-    ptr, slice,
+    ptr::{self, NonNull},
+    slice,
 };
 
 #[cfg(feature = "alloc")]
 extern crate alloc;
 #[cfg(feature = "alloc")]
 use {
     alloc::{boxed::Box, vec::Vec},
-    core::{alloc::Layout, ptr::NonNull},
+    core::alloc::Layout,
 };
 
+// For each polyfill, as soon as the corresponding feature is stable, the
+// polyfill import will be unused because method/function resolution will prefer
+// the inherent method/function over a trait method/function. Thus, we suppress
+// the `unused_imports` warning.
+//
+// See the documentation on `util::polyfills` for more information.
+#[allow(unused_imports)]
+use crate::util::polyfills::{NonNullExt as _, NonNullSliceExt as _};
+
 // This is a hack to allow zerocopy-derive derives to work in this crate. They
 // assume that zerocopy is linked as an extern crate, so they access items from
 // it as `zerocopy::Xxx`. This makes that still work.
@@ -300,8 +310,11 @@ impl SizeInfo {
     }
 }
 
-#[cfg_attr(test, derive(Copy, Clone, Debug))]
-enum _CastType {
+#[doc(hidden)]
+#[derive(Copy, Clone)]
+#[cfg_attr(test, derive(Debug))]
+#[allow(missing_debug_implementations)]
+pub enum _CastType {
     _Prefix,
     _Suffix,
 }
@@ -406,6 +419,9 @@ impl DstLayout {
     ///
     /// # Panics
     ///
+    /// `validate_cast_and_convert_metadata` will panic if `self` describes a
+    /// DST whose trailing slice element is zero-sized.
+    ///
     /// If `addr + bytes_len` overflows `usize`,
     /// `validate_cast_and_convert_metadata` may panic, or it may return
     /// incorrect results. No guarantees are made about when
@@ -573,12 +589,27 @@ impl DstLayout {
 pub unsafe trait KnownLayout: sealed::KnownLayoutSealed {
     #[doc(hidden)]
     const LAYOUT: DstLayout;
+
+    /// SAFETY: The returned pointer has the same address and provenance as
+    /// `bytes`. If `Self` is a DST, the returned pointer's referent has `elems`
+    /// elements in its trailing slice. If `Self` is sized, `elems` is ignored.
+    #[doc(hidden)]
+    fn raw_from_ptr_len(bytes: NonNull<u8>, elems: usize) -> NonNull<Self>;
 }
 
 impl<T: KnownLayout> sealed::KnownLayoutSealed for [T] {}
 // SAFETY: Delegates safety to `DstLayout::for_slice`.
 unsafe impl<T: KnownLayout> KnownLayout for [T] {
     const LAYOUT: DstLayout = DstLayout::for_slice::<T>();
+
+    // SAFETY: `.cast` preserves address and provenance. The returned pointer
+    // refers to an object with `elems` elements by construction.
+    #[inline(always)]
+    fn raw_from_ptr_len(data: NonNull<u8>, elems: usize) -> NonNull<Self> {
+        // TODO(#67): Remove this allow. See NonNullExt for more details.
+        #[allow(unstable_name_collisions)]
+        NonNull::slice_from_raw_parts(data.cast::<T>(), elems)
+    }
 }
 
 #[rustfmt::skip]

src/macros.rs

@@ -204,11 +204,21 @@ macro_rules! impl_known_layout {
     };
     ($($ty:ty),*) => { $(impl_known_layout!(@inner , => $ty);)* };
     (@inner $(const $constvar:ident : $constty:ty)? , $($tyvar:ident $(: ?$optbound:ident)?)? => $ty:ty) => {
-        impl<$(const $constvar : $constty,)? $($tyvar $(: ?$optbound)?)?> sealed::KnownLayoutSealed for $ty {}
-        // SAFETY: Delegates safety to `DstLayout::for_type`.
-        unsafe impl<$(const $constvar : $constty,)? $($tyvar $(: ?$optbound)?)?> KnownLayout for $ty {
-            const LAYOUT: DstLayout = DstLayout::for_type::<$ty>();
-        }
+        const _: () = {
+            use core::ptr::NonNull;
+
+            impl<$(const $constvar : $constty,)? $($tyvar $(: ?$optbound)?)?> sealed::KnownLayoutSealed for $ty {}
+            // SAFETY: Delegates safety to `DstLayout::for_type`.
+            unsafe impl<$(const $constvar : $constty,)? $($tyvar $(: ?$optbound)?)?> KnownLayout for $ty {
+                const LAYOUT: DstLayout = DstLayout::for_type::<$ty>();
+
+                // SAFETY: `.cast` preserves address and provenance.
+                #[inline(always)]
+                fn raw_from_ptr_len(bytes: NonNull<u8>, _elems: usize) -> NonNull<Self> {
+                    bytes.cast::<Self>()
+                }
+            }
+        };
     };
 }
 
@@ -225,10 +235,25 @@ macro_rules! impl_known_layout {
 ///   and this operation must preserve referent size (ie, `size_of_val_raw`).
 macro_rules! unsafe_impl_known_layout {
     ($($tyvar:ident: ?Sized + KnownLayout =>)? #[repr($repr:ty)] $ty:ty) => {
-        impl<$($tyvar: ?Sized + KnownLayout)?> sealed::KnownLayoutSealed for $ty {}
-        unsafe impl<$($tyvar: ?Sized + KnownLayout)?> KnownLayout for $ty {
-            const LAYOUT: DstLayout = <$repr as KnownLayout>::LAYOUT;
-        }
+        const _: () = {
+            use core::ptr::NonNull;
+
+            impl<$($tyvar: ?Sized + KnownLayout)?> sealed::KnownLayoutSealed for $ty {}
+            unsafe impl<$($tyvar: ?Sized + KnownLayout)?> KnownLayout for $ty {
+                const LAYOUT: DstLayout = <$repr as KnownLayout>::LAYOUT;
+
+                // SAFETY: All operations preserve address and provenance. Caller
+                // has promised that the `as` cast preserves size.
+                #[inline(always)]
+                #[allow(unused_qualifications)] // for `core::ptr::NonNull`
+                fn raw_from_ptr_len(bytes: NonNull<u8>, elems: usize) -> NonNull<Self> {
+                    #[allow(clippy::as_conversions)]
+                    let ptr = <$repr>::raw_from_ptr_len(bytes, elems).as_ptr() as *mut Self;
+                    // SAFETY: `ptr` was converted from `bytes`, which is non-null.
+                    unsafe { NonNull::new_unchecked(ptr) }
+                }
+            }
+        };
     };
 }