library/alloc/src/boxed/thin.rs

   1 // Based on
   2 // https://github.com/matthieu-m/rfc2580/blob/b58d1d3cba0d4b5e859d3617ea2d0943aaa31329/examples/thin.rs
   3 // by matthieu-m
   4 use crate::alloc::{self, Layout, LayoutError};
   5 use core::error::Error;
   6 use core::fmt::{self, Debug, Display, Formatter};
   7 use core::marker::PhantomData;
   8 #[cfg(not(no_global_oom_handling))]
   9 use core::marker::Unsize;
  10 use core::mem;
  11 use core::ops::{Deref, DerefMut};
  12 use core::ptr::Pointee;
  13 use core::ptr::{self, NonNull};
  14
  15 /// ThinBox.
  16 ///
  17 /// A thin pointer for heap allocation, regardless of T.
  18 ///
  19 /// # Examples
  20 ///
  21 /// ```
  22 /// #![feature(thin_box)]
  23 /// use std::boxed::ThinBox;
  24 ///
  25 /// let five = ThinBox::new(5);
  26 /// let thin_slice = ThinBox::<[i32]>::new_unsize([1, 2, 3, 4]);
  27 ///
  28 /// use std::mem::{size_of, size_of_val};
  29 /// let size_of_ptr = size_of::<*const ()>();
  30 /// assert_eq!(size_of_ptr, size_of_val(&five));
  31 /// assert_eq!(size_of_ptr, size_of_val(&thin_slice));
  32 /// ```
  33 #[unstable(feature = "thin_box", issue = "92791")]
  34 pub struct ThinBox<T: ?Sized> {
  35     // This is essentially `WithHeader<<T as Pointee>::Metadata>`,
  36     // but that would be invariant in `T`, and we want covariance.
  37     ptr: WithOpaqueHeader,
  38     _marker: PhantomData<T>,
  39 }
  40
  41 /// `ThinBox<T>` is `Send` if `T` is `Send` because the data is owned.
  42 #[unstable(feature = "thin_box", issue = "92791")]
  43 unsafe impl<T: ?Sized + Send> Send for ThinBox<T> {}
  44
  45 /// `ThinBox<T>` is `Sync` if `T` is `Sync` because the data is owned.
  46 #[unstable(feature = "thin_box", issue = "92791")]
  47 unsafe impl<T: ?Sized + Sync> Sync for ThinBox<T> {}
  48
  49 #[unstable(feature = "thin_box", issue = "92791")]
  50 impl<T> ThinBox<T> {
  51     /// Moves a type to the heap with its `Metadata` stored in the heap allocation instead of on
  52     /// the stack.
  53     ///
  54     /// # Examples
  55     ///
  56     /// ```
  57     /// #![feature(thin_box)]
  58     /// use std::boxed::ThinBox;
  59     ///
  60     /// let five = ThinBox::new(5);
  61     /// ```
  62     #[cfg(not(no_global_oom_handling))]
  63     pub fn new(value: T) -> Self {
  64         let meta = ptr::metadata(&value);
  65         let ptr = WithOpaqueHeader::new(meta, value);
  66         ThinBox { ptr, _marker: PhantomData }
  67     }
  68 }
  69
  70 #[unstable(feature = "thin_box", issue = "92791")]
  71 impl<Dyn: ?Sized> ThinBox<Dyn> {
  72     /// Moves a type to the heap with its `Metadata` stored in the heap allocation instead of on
  73     /// the stack.
  74     ///
  75     /// # Examples
  76     ///
  77     /// ```
  78     /// #![feature(thin_box)]
  79     /// use std::boxed::ThinBox;
  80     ///
  81     /// let thin_slice = ThinBox::<[i32]>::new_unsize([1, 2, 3, 4]);
  82     /// ```
  83     #[cfg(not(no_global_oom_handling))]
  84     pub fn new_unsize<T>(value: T) -> Self
  85     where
  86         T: Unsize<Dyn>,
  87     {
  88         let meta = ptr::metadata(&value as &Dyn);
  89         let ptr = WithOpaqueHeader::new(meta, value);
  90         ThinBox { ptr, _marker: PhantomData }
  91     }
  92 }
  93
  94 #[unstable(feature = "thin_box", issue = "92791")]
  95 impl<T: ?Sized + Debug> Debug for ThinBox<T> {
  96     fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
  97         Debug::fmt(self.deref(), f)
  98     }
  99 }
 100
 101 #[unstable(feature = "thin_box", issue = "92791")]
 102 impl<T: ?Sized + Display> Display for ThinBox<T> {
 103     fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
 104         Display::fmt(self.deref(), f)
 105     }
 106 }
 107
 108 #[unstable(feature = "thin_box", issue = "92791")]
 109 impl<T: ?Sized> Deref for ThinBox<T> {
 110     type Target = T;
 111
 112     fn deref(&self) -> &T {
 113         let value = self.data();
 114         let metadata = self.meta();
 115         let pointer = ptr::from_raw_parts(value as *const (), metadata);
 116         unsafe { &*pointer }
 117     }
 118 }
 119
 120 #[unstable(feature = "thin_box", issue = "92791")]
 121 impl<T: ?Sized> DerefMut for ThinBox<T> {
 122     fn deref_mut(&mut self) -> &mut T {
 123         let value = self.data();
 124         let metadata = self.meta();
 125         let pointer = ptr::from_raw_parts_mut::<T>(value as *mut (), metadata);
 126         unsafe { &mut *pointer }
 127     }
 128 }
 129
 130 #[unstable(feature = "thin_box", issue = "92791")]
 131 impl<T: ?Sized> Drop for ThinBox<T> {
 132     fn drop(&mut self) {
 133         unsafe {
 134             let value = self.deref_mut();
 135             let value = value as *mut T;
 136             self.with_header().drop::<T>(value);
 137         }
 138     }
 139 }
 140
 141 #[unstable(feature = "thin_box", issue = "92791")]
 142 impl<T: ?Sized> ThinBox<T> {
 143     fn meta(&self) -> <T as Pointee>::Metadata {
 144         //  Safety:
 145         //  -   NonNull and valid.
 146         unsafe { *self.with_header().header() }
 147     }
 148
 149     fn data(&self) -> *mut u8 {
 150         self.with_header().value()
 151     }
 152
 153     fn with_header(&self) -> &WithHeader<<T as Pointee>::Metadata> {
 154         // SAFETY: both types are transparent to `NonNull<u8>`
 155         unsafe { &*((&self.ptr) as *const WithOpaqueHeader as *const WithHeader<_>) }
 156     }
 157 }
 158
 159 /// A pointer to type-erased data, guaranteed to either be:
 160 /// 1. `NonNull::dangling()`, in the case where both the pointee (`T`) and
 161 ///    metadata (`H`) are ZSTs.
 162 /// 2. A pointer to a valid `T` that has a header `H` directly before the
 163 ///    pointed-to location.
 164 #[repr(transparent)]
 165 struct WithHeader<H>(NonNull<u8>, PhantomData<H>);
 166
 167 /// An opaque representation of `WithHeader<H>` to avoid the
 168 /// projection invariance of `<T as Pointee>::Metadata`.
 169 #[repr(transparent)]
 170 struct WithOpaqueHeader(NonNull<u8>);
 171
 172 impl WithOpaqueHeader {
 173     #[cfg(not(no_global_oom_handling))]
 174     fn new<H, T>(header: H, value: T) -> Self {
 175         let ptr = WithHeader::new(header, value);
 176         Self(ptr.0)
 177     }
 178 }
 179
 180 impl<H> WithHeader<H> {
 181     #[cfg(not(no_global_oom_handling))]
 182     fn new<T>(header: H, value: T) -> WithHeader<H> {
 183         let value_layout = Layout::new::<T>();
 184         let Ok((layout, value_offset)) = Self::alloc_layout(value_layout) else {
 185             // We pass an empty layout here because we do not know which layout caused the
 186             // arithmetic overflow in `Layout::extend` and `handle_alloc_error` takes `Layout` as
 187             // its argument rather than `Result<Layout, LayoutError>`, also this function has been
 188             // stable since 1.28 ._.
 189             //
 190             // On the other hand, look at this gorgeous turbofish!
 191             alloc::handle_alloc_error(Layout::new::<()>());
 192         };
 193
 194         unsafe {
 195             // Note: It's UB to pass a layout with a zero size to `alloc::alloc`, so
 196             // we use `layout.dangling()` for this case, which should have a valid
 197             // alignment for both `T` and `H`.
 198             let ptr = if layout.size() == 0 {
 199                 // Some paranoia checking, mostly so that the ThinBox tests are
 200                 // more able to catch issues.
 201                 debug_assert!(
 202                     value_offset == 0 && mem::size_of::<T>() == 0 && mem::size_of::<H>() == 0
 203                 );
 204                 layout.dangling()
 205             } else {
 206                 let ptr = alloc::alloc(layout);
 207                 if ptr.is_null() {
 208                     alloc::handle_alloc_error(layout);
 209                 }
 210                 // Safety:
 211                 // - The size is at least `aligned_header_size`.
 212                 let ptr = ptr.add(value_offset) as *mut _;
 213
 214                 NonNull::new_unchecked(ptr)
 215             };
 216
 217             let result = WithHeader(ptr, PhantomData);
 218             ptr::write(result.header(), header);
 219             ptr::write(result.value().cast(), value);
 220
 221             result
 222         }
 223     }
 224
 225     // Safety:
 226     // - Assumes that either `value` can be dereferenced, or is the
 227     //   `NonNull::dangling()` we use when both `T` and `H` are ZSTs.
 228     unsafe fn drop<T: ?Sized>(&self, value: *mut T) {
 229         struct DropGuard<H> {
 230             ptr: NonNull<u8>,
 231             value_layout: Layout,
 232             _marker: PhantomData<H>,
 233         }
 234
 235         impl<H> Drop for DropGuard<H> {
 236             fn drop(&mut self) {
 237                 unsafe {
 238                     // SAFETY: Layout must have been computable if we're in drop
 239                     let (layout, value_offset) =
 240                         WithHeader::<H>::alloc_layout(self.value_layout).unwrap_unchecked();
 241
 242                     // Note: Don't deallocate if the layout size is zero, because the pointer
 243                     // didn't come from the allocator.
 244                     if layout.size() != 0 {
 245                         alloc::dealloc(self.ptr.as_ptr().sub(value_offset), layout);
 246                     } else {
 247                         debug_assert!(
 248                             value_offset == 0
 249                                 && mem::size_of::<H>() == 0
 250                                 && self.value_layout.size() == 0
 251                         );
 252                     }
 253                 }
 254             }
 255         }
 256
 257         unsafe {
 258             // `_guard` will deallocate the memory when dropped, even if `drop_in_place` unwinds.
 259             let _guard = DropGuard {
 260                 ptr: self.0,
 261                 value_layout: Layout::for_value_raw(value),
 262                 _marker: PhantomData::<H>,
 263             };
 264
 265             // We only drop the value because the Pointee trait requires that the metadata is copy
 266             // aka trivially droppable.
 267             ptr::drop_in_place::<T>(value);
 268         }
 269     }
 270
 271     fn header(&self) -> *mut H {
 272         //  Safety:
 273         //  - At least `size_of::<H>()` bytes are allocated ahead of the pointer.
 274         //  - We know that H will be aligned because the middle pointer is aligned to the greater
 275         //    of the alignment of the header and the data and the header size includes the padding
 276         //    needed to align the header. Subtracting the header size from the aligned data pointer
 277         //    will always result in an aligned header pointer, it just may not point to the
 278         //    beginning of the allocation.
 279         let hp = unsafe { self.0.as_ptr().sub(Self::header_size()) as *mut H };
 280         debug_assert!(hp.is_aligned());
 281         hp
 282     }
 283
 284     fn value(&self) -> *mut u8 {
 285         self.0.as_ptr()
 286     }
 287
 288     const fn header_size() -> usize {
 289         mem::size_of::<H>()
 290     }
 291
 292     fn alloc_layout(value_layout: Layout) -> Result<(Layout, usize), LayoutError> {
 293         Layout::new::<H>().extend(value_layout)
 294     }
 295 }
 296
 297 #[unstable(feature = "thin_box", issue = "92791")]
 298 impl<T: ?Sized + Error> Error for ThinBox<T> {
 299     fn source(&self) -> Option<&(dyn Error + 'static)> {
 300         self.deref().source()
 301     }
 302 }