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