nordic-dev.net/bytemuck
2
0
Fork 0
mirror of https://github.com/Lokathor/bytemuck.git synced 2024-11-25 00:02:22 +00:00
Code Issues Packages Projects Releases Wiki Activity

Rework TransparentWrapper to not require that the wrapped type be public

Browse Source
This commit is contained in:
Thom Chiovoloni 2020-01-11 07:31:17 -08:00
parent c383083c16
commit f62e320bba
1 changed files with 74 additions and 75 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

149
src/transparent.rs
View File

@ -3,33 +3,38 @@ use super::*;
/// A trait which indicates that a type is a `repr(transparent)` wrapper around
/// the `Wrapped` value.
///
/// This allows safely creating references to `T` from those to `T::Wrapped`,
/// using the [`wrap_ref`] and [`wrap_mut`] functions.
/// This allows safely creating references to `T` from those to the `Wrapped`
/// type, using the `wrap_ref` and `wrap_mut` functions.
///
/// # Safety
///
/// The safety contract of `TransparentWrapper` is relatively simple:
///
/// For a given `T` which implements `TransparentWrapper`:
/// For a given `Wrapper` which implements `TransparentWrapper<Wrapped>`:
///
/// 1. T must be a `#[repr(transparent)]` struct and contain a field of type
/// `T::Wrapped`.
/// 1. Wrapper must be a `#[repr(transparent)]` wrapper around `Wrapped`. This
/// either means that it must be a `#[repr(transparent)]` struct which
/// contains a either a field of type `Wrapped` (or a field of some other
/// transparent wrapper for `Wrapped`) as the only non-ZST field.
///
/// 2. Any fields *other* than the `T::Wrapped` field must be trivially
/// 2. Any fields *other* than the `Wrapped` field must be trivially
/// constructable ZSTs, for example `PhantomData`, `PhantomPinned`, etc.
///
/// 3. The `T` may not impose additional alignment requirements over
/// `T::Wrapped`.
/// 3. The `Wrapper` may not impose additional alignment requirements over
/// `Wrapped`.
/// - Note: this is currently guaranteed by repr(transparent), but there
/// have been discussions of lifting it, so it's stated here explictly.
///
/// 4. The `wrap_ref` and `wrap_mut` functions on `TransparentWrapper` may not
/// be overridden.
///
/// ## Caveats
///
/// If the wrapper imposes additional constraints upon the wrapped type which
/// are required for safety, it's responsible for ensuring those still hold --
/// this generally requires preventing access to instances of the wrapped type,
/// as implementing `TransparentWrapper` means anybody can call
/// `bytemuck::cast_ref`.
/// as implementing `TransparentWrapper<U> for T` means anybody can call
/// `T::cast_ref(any_instance_of_u)`.
///
/// For example, it would be invalid to implement TransparentWrapper for `str`
/// to implement `TransparentWrapper` around `[u8]` because of this.
@ -39,24 +44,22 @@ use super::*;
/// ## Basic
///
/// ```
/// use bytemuck::{wrap_ref, wrap_mut, TransparentWrapper};
/// use bytemuck::TransparentWrapper;
/// # #[derive(Default)]
/// # struct SomeStruct(u32);
///
/// #[repr(transparent)]
/// struct MyWrapper(SomeStruct);
///
/// unsafe impl TransparentWrapper for MyWrapper {
/// type Wrapped = SomeStruct;
/// }
/// unsafe impl TransparentWrapper<SomeStruct> for MyWrapper {}
///
/// // interpret a reference to &SomeStruct as a &MyWrapper
/// let thing = SomeStruct::default();
/// let wrapped_ref: &MyWrapper = wrap_ref(&thing);
/// let wrapped_ref: &MyWrapper = MyWrapper::wrap_ref(&thing);
///
/// // Works with &mut too.
/// let mut mut_thing = SomeStruct::default();
/// let wrapped_mut: &mut MyWrapper = wrap_mut(&mut mut_thing);
/// let wrapped_mut: &mut MyWrapper = MyWrapper::wrap_mut(&mut mut_thing);
///
/// # let _ = (wrapped_ref, wrapped_mut); // silence warnings
/// ```
@ -64,73 +67,71 @@ use super::*;
/// ## Use with dynamically sized types
///
/// ```
/// use bytemuck::{wrap_ref, wrap_mut, TransparentWrapper};
/// use bytemuck::TransparentWrapper;
///
/// #[repr(transparent)]
/// struct Slice<T>([T]);
///
/// unsafe impl<T> TransparentWrapper for Slice<T> {
/// type Wrapped = [T];
/// }
/// unsafe impl<T> TransparentWrapper<[T]> for Slice<T> {}
///
/// let s = wrap_ref::<Slice<_>>(&[1u32, 2, 3]);
/// let s = Slice::wrap_ref(&[1u32, 2, 3]);
/// assert_eq!(&s.0, &[1, 2, 3]);
///
/// // Otherwise you'd need separate Slice<'a, T> and SliceMut<'a, T>, for example
/// let mut buf = [1, 2, 3u8];
/// let sm = wrap_mut::<Slice<_>>(&mut buf);
/// assert_eq!(&s.0, &[1, 2, 3]);
/// let sm = Slice::wrap_mut(&mut buf);
/// ```
pub unsafe trait TransparentWrapper {
/// The wrapped type.
type Wrapped: ?Sized;
}
pub unsafe trait TransparentWrapper<Wrapped: ?Sized> {
/// Convert a reference to a wrapped type into a reference to the wrapper.
///
/// This is a trait method so that you can write `MyType::wrap_ref(...)` in
/// your code. It is part of the safety contract for this trait that if you
/// implement `TransparentWrapper<_>` for your type you **must not** override
/// this method.
#[inline]
fn wrap_ref(s: &Wrapped) -> &Self {
unsafe {
assert!(size_of::<*const Wrapped>() == size_of::<*const Self>());
// Using a pointer cast doesn't work here because rustc can't tell that the
// vtables match (if we lifted the ?Sized restriction, this would go away),
// and transmute doesn't work for the usual reasons it doesn't work inside
// generic functions.
//
// SAFETY: The unsafe contract requires that these have identical
// representations. Using this transmute_copy instead of transmute here is
// annoying, but is required as `Self` and `Self::Int` have unspecified
// sizes still.
let wrapped_ptr = s as *const Wrapped;
let wrapper_ptr: *const Self = transmute_copy(&wrapped_ptr);
&*wrapper_ptr
}
}
/// Convert a reference to a wrapped type into a reference to the wrapper.
///
/// See [`TransparentWrapper`] for details.
#[inline]
pub fn wrap_ref<W: TransparentWrapper + ?Sized>(r: &W::Wrapped) -> &W {
unsafe {
// Ideally we'd check more than just this, but...
assert!(size_of::<*const W::Wrapped>() == size_of::<*const W>());
// Using a pointer cast doesn't work here because rustc can't tell that the
// vtables match (if we lifted the ?Sized restriction, this would go away),
// and transmute doesn't work for the usual reasons it doesn't work inside
// generic functions.
//
// SAFETY: The unsafe contract requires that these have identical
// representations. Using this transmute_copy instead of transmute here is
// annoying, but is required as `Self` and `Self::Int` have unspecified
// sizes still.
let wrapped_ptr = r as *const W::Wrapped;
let wrapper_ptr: *const W = transmute_copy(&wrapped_ptr);
&*wrapper_ptr
/// Convert a mut reference to a wrapped type into a mut reference to the
/// wrapper.
///
/// This is a trait method so that you can write `MyType::wrap_mut(...)` in
/// your code. It is part of the safety contract for this trait that if you implement
/// `TransparentWrapper<_>` for your type you **must not** override this method.
#[inline]
fn wrap_mut(s: &mut Wrapped) -> &mut Self {
unsafe {
assert!(size_of::<*mut Wrapped>() == size_of::<*mut Self>());
// Using a pointer cast doesn't work here because rustc can't tell that the
// vtables match (if we lifted the ?Sized restriction, this would go away),
// and transmute doesn't work for the usual reasons it doesn't work inside
// generic functions.
//
// SAFETY: The unsafe contract requires that these have identical
// representations. Using this transmute_copy instead of transmute here is
// annoying, but is required as `Self` and `Self::Int` have unspecified
// sizes still.
let wrapped_ptr = s as *mut Wrapped;
let wrapper_ptr: *mut Self = transmute_copy(&wrapped_ptr);
&mut *wrapper_ptr
}
}
}
/// Convert a mut reference to a wrapped type into a mut reference to the
/// wrapper.
///
/// See [`TransparentWrapper`] for details.
#[inline]
pub fn wrap_mut<W: TransparentWrapper + ?Sized>(r: &mut W::Wrapped) -> &mut W {
unsafe {
assert!(size_of::<*mut W::Wrapped>() == size_of::<*mut W>());
// Using a pointer cast doesn't work here because rustc can't tell that the
// vtables match (if we lifted the ?Sized restriction, this would go away),
// and transmute doesn't work for the usual reasons it doesn't work inside
// generic functions.
//
// SAFETY: The unsafe contract requires that these have identical
// representations. Using this transmute_copy instead of transmute here is
// annoying, but is required as `Self` and `Self::Int` have unspecified
// sizes still.
let wrapped_ptr = r as *mut W::Wrapped;
let wrapper_ptr: *mut W = transmute_copy(&wrapped_ptr);
&mut *wrapper_ptr
}
}
#[cfg(all(test, feature = "extern_crate_alloc"))]
mod test {
use super::*;
@ -141,9 +142,7 @@ mod test {
#[repr(transparent)]
struct DisplayTraitObj(dyn Display);
unsafe impl TransparentWrapper for DisplayTraitObj {
type Wrapped = dyn Display;
}
unsafe impl TransparentWrapper<dyn Display> for DisplayTraitObj {}
impl Display for DisplayTraitObj {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
@ -153,12 +152,12 @@ mod test {
#[test]
fn test_vtabled() {
let v: &DisplayTraitObj = wrap_ref(&5i32 as &dyn Display);
let v = DisplayTraitObj::wrap_ref(&5i32);
let s = format!("{}", v);
assert_eq!(s, "5");
let mut x = 100i32;
let v_mut: &mut DisplayTraitObj = wrap_mut(&mut x as &mut dyn Display);
let v_mut = DisplayTraitObj::wrap_mut(&mut x);
let s = format!("{}", v_mut);
assert_eq!(s, "100");
}