Add KnownLayout trait

In its initial form, the `KnownLayout` trait encodes type layout
information slightly more complex than can be gleaned from any arbitrary
`T: ?Sized`. This allows it to support not just sized and slice types,
but also "custom DSTs" (those with fixed-size fields followed by a
trailing slice type). This is the first step to supporting various
operations on arbitrary custom DSTs.

Makes progress on #29

src/lib.rs

@@ -190,11 +190,7 @@ use core::{
 #[cfg(feature = "alloc")]
 extern crate alloc;
 #[cfg(feature = "alloc")]
-use {
- alloc::boxed::Box,
- alloc::vec::Vec,
- core::{alloc::Layout, ptr::NonNull},
-};
+use {alloc::boxed::Box, alloc::vec::Vec, core::alloc::Layout};
 
 // 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
@@ -204,6 +200,127 @@ mod zerocopy {
  pub(crate) use crate::*;
 }
 
+/// The layout of a type which might be dynamically-sized.
+///
+/// `DstLayout` describes the layout of sized types, slice types, and "custom
+/// DSTs" - ie, those that are known by the type system to have a trailing slice
+/// (as distinguished from `dyn Trait` types - such types *might* have a
+/// trailing slice type, but the type system isn't aware of it).
+#[doc(hidden)]
+#[allow(missing_debug_implementations, missing_copy_implementations)]
+pub struct DstLayout {
+ /// For sized types, `size_of::<T>()`. For DSTs, the size of the type when
+ /// the trailing slice field contains 0 elements.
+ _fixed_prefix_size: usize,
+ /// The alignment of the type.
+ _align: NonZeroUsize,
+ /// For sized types, `None`. For DSTs, the size of the element type of the
+ /// trailing slice.
+ _trailing_slice_elem_size: Option<usize>,
+}
+
+impl DstLayout {
+ /// Constructs a `DstLayout` which describes `T`.
+ ///
+ /// # Safety
+ ///
+ /// Unsafe code may assume that `DstLayout` is the correct layout for `T`.
+ const fn for_type<T>() -> DstLayout {
+ DstLayout {
+ _fixed_prefix_size: mem::size_of::<T>(),
+ _align: match NonZeroUsize::new(mem::align_of::<T>()) {
+ Some(align) => align,
+ None => panic!("core::mem::align_of should never return 0"),
+ },
+ _trailing_slice_elem_size: None,
+ }
+ }
+
+ /// Constructs a `DstLayout` which describes `[T]`.
+ ///
+ /// # Safety
+ ///
+ /// Unsafe code may assume that `DstLayout` is the correct layout for `[T]`.
+ const fn for_slice<T>() -> DstLayout {
+ DstLayout {
+ _fixed_prefix_size: 0,
+ _align: match NonZeroUsize::new(mem::align_of::<T>()) {
+ Some(align) => align,
+ None => panic!("core::mem::align_of should never return 0"),
+ },
+ _trailing_slice_elem_size: Some(mem::size_of::<T>()),
+ }
+ }
+}
+
+/// A trait which carries information about a type's layout that is used by the
+/// internals of this crate.
+///
+/// This trait is not meant for consumption by code outsie of this crate. While
+/// the normal semver stability guarantees apply with respect to which types
+/// implement this trait and which trait implementations are implied by this
+/// trait, no semver stability guarantees are made regarding its internals; they
+/// may change at any time, and code which makes use of them may break.
+///
+/// # Safety
+///
+/// This trait does not convey any safety guarantees to code outside this crate.
+#[doc(hidden)] // TODO: Remove this once KnownLayout is used by other APIs
+pub unsafe trait KnownLayout: sealed::KnownLayoutSealed {
+ #[doc(hidden)]
+ const LAYOUT: DstLayout;
+}
+
+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>();
+}
+
+/// Implements `KnownLayout` for a sized type.
+macro_rules! impl_known_layout {
+ ($(const $constvar:ident : $constty:ty, $tyvar:ident $(: ?$optbound:ident)? => $ty:ty),* $(,)?) => {
+ $(impl_known_layout!(@inner const $constvar: $constty, $tyvar $(: ?$optbound)? => $ty);)*
+ };
+ ($($tyvar:ident $(: ?$optbound:ident)? => $ty:ty),* $(,)?) => {
+ $(impl_known_layout!(@inner , $tyvar $(: ?$optbound)? => $ty);)*
+ };
+ ($($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>();
+ }
+ };
+}
+
+#[rustfmt::skip]
+impl_known_layout!(
+ (),
+ u8, i8, u16, i16, u32, i32, u64, i64, u128, i128, usize, isize, f32, f64,
+ bool, char,
+ NonZeroU8, NonZeroI8, NonZeroU16, NonZeroI16, NonZeroU32, NonZeroI32,
+ NonZeroU64, NonZeroI64, NonZeroU128, NonZeroI128, NonZeroUsize, NonZeroIsize
+);
+#[rustfmt::skip]
+impl_known_layout!(
+ T => Option<T>,
+ T: ?Sized => PhantomData<T>,
+ T => Wrapping<T>,
+ T => MaybeUninit<T>,
+);
+impl_known_layout!(const N: usize, T => [T; N]);
+
+safety_comment! {
+ /// SAFETY:
+ /// `str` and `ManuallyDrop<[T]>` have the same representations as `[u8]`
+ /// and `[T]` repsectively. `str` has different bit validity than `[u8]`,
+ /// but that doesn't affect the soundness of this impl.
+ unsafe_impl_known_layout!(#[repr([u8])] str);
+ unsafe_impl_known_layout!(T: ?Sized + KnownLayout => #[repr(T)] ManuallyDrop<T>);
+}
+
 /// Types for which a sequence of bytes all set to zero represents a valid
 /// instance of the type.
 ///
@@ -1171,6 +1288,7 @@ mod simd {
  use core::arch::$arch::{$($typ),*};
 
  use crate::*;
+ impl_known_layout!($($typ),*);
  safety_comment! {
  /// SAFETY:
  /// See comment on module definition for justification.
@@ -2279,7 +2397,8 @@ where
 }
 
 mod sealed {
- pub trait Sealed {}
+ pub trait ByteSliceSealed {}
+ pub trait KnownLayoutSealed {}
 }
 
 // ByteSlice and ByteSliceMut abstract over [u8] references (&[u8], &mut [u8],
@@ -2305,7 +2424,9 @@ mod sealed {
 ///
 /// [`Vec<u8>`]: alloc::vec::Vec
 /// [`split_at`]: crate::ByteSlice::split_at
-pub unsafe trait ByteSlice: Deref<Target = [u8]> + Sized + self::sealed::Sealed {
+pub unsafe trait ByteSlice:
+ Deref<Target = [u8]> + Sized + self::sealed::ByteSliceSealed
+{
  /// Gets a raw pointer to the first byte in the slice.
  #[inline]
  fn as_ptr(&self) -> *const u8 {
@@ -2336,7 +2457,7 @@ pub unsafe trait ByteSliceMut: ByteSlice + DerefMut {
  }
 }
 
-impl<'a> sealed::Sealed for &'a [u8] {}
+impl<'a> sealed::ByteSliceSealed for &'a [u8] {}
 // TODO(#61): Add a "SAFETY" comment and remove this `allow`.
 #[allow(clippy::undocumented_unsafe_blocks)]
 unsafe impl<'a> ByteSlice for &'a [u8] {
@@ -2346,7 +2467,7 @@ unsafe impl<'a> ByteSlice for &'a [u8] {
  }
 }
 
-impl<'a> sealed::Sealed for &'a mut [u8] {}
+impl<'a> sealed::ByteSliceSealed for &'a mut [u8] {}
 // TODO(#61): Add a "SAFETY" comment and remove this `allow`.
 #[allow(clippy::undocumented_unsafe_blocks)]
 unsafe impl<'a> ByteSlice for &'a mut [u8] {
@@ -2356,7 +2477,7 @@ unsafe impl<'a> ByteSlice for &'a mut [u8] {
  }
 }
 
-impl<'a> sealed::Sealed for cell::Ref<'a, [u8]> {}
+impl<'a> sealed::ByteSliceSealed for cell::Ref<'a, [u8]> {}
 // TODO(#61): Add a "SAFETY" comment and remove this `allow`.
 #[allow(clippy::undocumented_unsafe_blocks)]
 unsafe impl<'a> ByteSlice for cell::Ref<'a, [u8]> {
@@ -2366,7 +2487,7 @@ unsafe impl<'a> ByteSlice for cell::Ref<'a, [u8]> {
  }
 }
 
-impl<'a> sealed::Sealed for RefMut<'a, [u8]> {}
+impl<'a> sealed::ByteSliceSealed for RefMut<'a, [u8]> {}
 // TODO(#61): Add a "SAFETY" comment and remove this `allow`.
 #[allow(clippy::undocumented_unsafe_blocks)]
 unsafe impl<'a> ByteSlice for RefMut<'a, [u8]> {

src/macros.rs

@@ -193,6 +193,26 @@ macro_rules! impl_or_verify {
  };
 }
 
+/// Implements `KnownLayout` for a type in terms of the implementation of
+/// another type with the same representation.
+///
+/// # Safety
+///
+/// - `$ty` and `$repr` must have the same:
+/// - Fixed prefix size
+/// - Alignment
+/// - (For DSTs) trailing slice element size
+/// - It must be valid to perform an `as` cast from `*mut $repr` to `*mut $ty`,
+/// 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;
+ }
+ };
+}
+
 /// Uses `align_of` to confirm that a type or set of types have alignment 1.
 ///
 /// Note that `align_of<T>` requires `T: Sized`, so this macro doesn't work for