1// Based on
2// https://github.com/matthieu-m/rfc2580/blob/b58d1d3cba0d4b5e859d3617ea2d0943aaa31329/examples/thin.rs
3// by matthieu-m
4use crate::alloc::{self, Layout, LayoutError};
5use core::error::Error;
6use core::fmt::{self, Debug, Display, Formatter};
7#[cfg(not(no_global_oom_handling))]
8use core::intrinsics::const_allocate;
9use core::marker::PhantomData;
10#[cfg(not(no_global_oom_handling))]
11use core::marker::Unsize;
12use core::mem;
13#[cfg(not(no_global_oom_handling))]
14use core::mem::SizedTypeProperties;
15use core::ops::{Deref, DerefMut};
16use core::ptr::Pointee;
17use core::ptr::{self, NonNull};
18
19/// ThinBox.
20///
21/// A thin pointer for heap allocation, regardless of T.
22///
23/// # Examples
24///
25/// ```
26/// #![feature(thin_box)]
27/// use std::boxed::ThinBox;
28///
29/// let five = ThinBox::new(5);
30/// let thin_slice = ThinBox::<[i32]>::new_unsize([1, 2, 3, 4]);
31///
32/// use std::mem::{size_of, size_of_val};
33/// let size_of_ptr = size_of::<*const ()>();
34/// assert_eq!(size_of_ptr, size_of_val(&five));
35/// assert_eq!(size_of_ptr, size_of_val(&thin_slice));
36/// ```
37#[unstable(feature = "thin_box", issue = "92791")]
38pub struct ThinBox<T: ?Sized> {
39 // This is essentially `WithHeader<<T as Pointee>::Metadata>`,
40 // but that would be invariant in `T`, and we want covariance.
41 ptr: WithOpaqueHeader,
42 _marker: PhantomData<T>,
43}
44
45/// `ThinBox<T>` is `Send` if `T` is `Send` because the data is owned.
46#[unstable(feature = "thin_box", issue = "92791")]
47unsafe impl<T: ?Sized + Send> Send for ThinBox<T> {}
48
49/// `ThinBox<T>` is `Sync` if `T` is `Sync` because the data is owned.
50#[unstable(feature = "thin_box", issue = "92791")]
51unsafe impl<T: ?Sized + Sync> Sync for ThinBox<T> {}
52
53#[unstable(feature = "thin_box", issue = "92791")]
54impl<T> ThinBox<T> {
55 /// Moves a type to the heap with its [`Metadata`] stored in the heap allocation instead of on
56 /// the stack.
57 ///
58 /// # Examples
59 ///
60 /// ```
61 /// #![feature(thin_box)]
62 /// use std::boxed::ThinBox;
63 ///
64 /// let five = ThinBox::new(5);
65 /// ```
66 ///
67 /// [`Metadata`]: core::ptr::Pointee::Metadata
68 #[cfg(not(no_global_oom_handling))]
69 pub fn new(value: T) -> Self {
70 let meta = ptr::metadata(&value);
71 let ptr = WithOpaqueHeader::new(meta, value);
72 ThinBox { ptr, _marker: PhantomData }
73 }
74
75 /// Moves a type to the heap with its [`Metadata`] stored in the heap allocation instead of on
76 /// the stack. Returns an error if allocation fails, instead of aborting.
77 ///
78 /// # Examples
79 ///
80 /// ```
81 /// #![feature(allocator_api)]
82 /// #![feature(thin_box)]
83 /// use std::boxed::ThinBox;
84 ///
85 /// let five = ThinBox::try_new(5)?;
86 /// # Ok::<(), std::alloc::AllocError>(())
87 /// ```
88 ///
89 /// [`Metadata`]: core::ptr::Pointee::Metadata
90 pub fn try_new(value: T) -> Result<Self, core::alloc::AllocError> {
91 let meta = ptr::metadata(&value);
92 WithOpaqueHeader::try_new(meta, value).map(|ptr| ThinBox { ptr, _marker: PhantomData })
93 }
94}
95
96#[unstable(feature = "thin_box", issue = "92791")]
97impl<Dyn: ?Sized> ThinBox<Dyn> {
98 /// Moves a type to the heap with its [`Metadata`] stored in the heap allocation instead of on
99 /// the stack.
100 ///
101 /// # Examples
102 ///
103 /// ```
104 /// #![feature(thin_box)]
105 /// use std::boxed::ThinBox;
106 ///
107 /// let thin_slice = ThinBox::<[i32]>::new_unsize([1, 2, 3, 4]);
108 /// ```
109 ///
110 /// [`Metadata`]: core::ptr::Pointee::Metadata
111 #[cfg(not(no_global_oom_handling))]
112 pub fn new_unsize<T>(value: T) -> Self
113 where
114 T: Unsize<Dyn>,
115 {
116 if mem::size_of::<T>() == 0 {
117 let ptr = WithOpaqueHeader::new_unsize_zst::<Dyn, T>(value);
118 ThinBox { ptr, _marker: PhantomData }
119 } else {
120 let meta = ptr::metadata(&value as &Dyn);
121 let ptr = WithOpaqueHeader::new(meta, value);
122 ThinBox { ptr, _marker: PhantomData }
123 }
124 }
125}
126
127#[unstable(feature = "thin_box", issue = "92791")]
128impl<T: ?Sized + Debug> Debug for ThinBox<T> {
129 fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
130 Debug::fmt(self.deref(), f)
131 }
132}
133
134#[unstable(feature = "thin_box", issue = "92791")]
135impl<T: ?Sized + Display> Display for ThinBox<T> {
136 fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
137 Display::fmt(self.deref(), f)
138 }
139}
140
141#[unstable(feature = "thin_box", issue = "92791")]
142impl<T: ?Sized> Deref for ThinBox<T> {
143 type Target = T;
144
145 fn deref(&self) -> &T {
146 let value: *mut u8 = self.data();
147 let metadata: ::Metadata = self.meta();
148 let pointer: *const T = ptr::from_raw_parts(data_pointer:value as *const (), metadata);
149 unsafe { &*pointer }
150 }
151}
152
153#[unstable(feature = "thin_box", issue = "92791")]
154impl<T: ?Sized> DerefMut for ThinBox<T> {
155 fn deref_mut(&mut self) -> &mut T {
156 let value: *mut u8 = self.data();
157 let metadata: ::Metadata = self.meta();
158 let pointer: *mut T = ptr::from_raw_parts_mut::<T>(data_pointer:value as *mut (), metadata);
159 unsafe { &mut *pointer }
160 }
161}
162
163#[unstable(feature = "thin_box", issue = "92791")]
164impl<T: ?Sized> Drop for ThinBox<T> {
165 fn drop(&mut self) {
166 unsafe {
167 let value: &mut T = self.deref_mut();
168 let value: *mut T = value as *mut T;
169 self.with_header().drop::<T>(value);
170 }
171 }
172}
173
174#[unstable(feature = "thin_box", issue = "92791")]
175impl<T: ?Sized> ThinBox<T> {
176 fn meta(&self) -> <T as Pointee>::Metadata {
177 // Safety:
178 // - NonNull and valid.
179 unsafe { *self.with_header().header() }
180 }
181
182 fn data(&self) -> *mut u8 {
183 self.with_header().value()
184 }
185
186 fn with_header(&self) -> &WithHeader<<T as Pointee>::Metadata> {
187 // SAFETY: both types are transparent to `NonNull<u8>`
188 unsafe { &*(core::ptr::addr_of!(self.ptr) as *const WithHeader<_>) }
189 }
190}
191
192/// A pointer to type-erased data, guaranteed to either be:
193/// 1. `NonNull::dangling()`, in the case where both the pointee (`T`) and
194/// metadata (`H`) are ZSTs.
195/// 2. A pointer to a valid `T` that has a header `H` directly before the
196/// pointed-to location.
197#[repr(transparent)]
198struct WithHeader<H>(NonNull<u8>, PhantomData<H>);
199
200/// An opaque representation of `WithHeader<H>` to avoid the
201/// projection invariance of `<T as Pointee>::Metadata`.
202#[repr(transparent)]
203struct WithOpaqueHeader(NonNull<u8>);
204
205impl WithOpaqueHeader {
206 #[cfg(not(no_global_oom_handling))]
207 fn new<H, T>(header: H, value: T) -> Self {
208 let ptr: WithHeader = WithHeader::new(header, value);
209 Self(ptr.0)
210 }
211
212 #[cfg(not(no_global_oom_handling))]
213 fn new_unsize_zst<Dyn, T>(value: T) -> Self
214 where
215 Dyn: ?Sized,
216 T: Unsize<Dyn>,
217 {
218 let ptr: WithHeader<::Metadata> = WithHeader::<<Dyn as Pointee>::Metadata>::new_unsize_zst::<Dyn, T>(value);
219 Self(ptr.0)
220 }
221
222 fn try_new<H, T>(header: H, value: T) -> Result<Self, core::alloc::AllocError> {
223 WithHeader::try_new(header, value).map(|ptr: WithHeader| Self(ptr.0))
224 }
225}
226
227impl<H> WithHeader<H> {
228 #[cfg(not(no_global_oom_handling))]
229 fn new<T>(header: H, value: T) -> WithHeader<H> {
230 let value_layout = Layout::new::<T>();
231 let Ok((layout, value_offset)) = Self::alloc_layout(value_layout) else {
232 // We pass an empty layout here because we do not know which layout caused the
233 // arithmetic overflow in `Layout::extend` and `handle_alloc_error` takes `Layout` as
234 // its argument rather than `Result<Layout, LayoutError>`, also this function has been
235 // stable since 1.28 ._.
236 //
237 // On the other hand, look at this gorgeous turbofish!
238 alloc::handle_alloc_error(Layout::new::<()>());
239 };
240
241 unsafe {
242 // Note: It's UB to pass a layout with a zero size to `alloc::alloc`, so
243 // we use `layout.dangling()` for this case, which should have a valid
244 // alignment for both `T` and `H`.
245 let ptr = if layout.size() == 0 {
246 // Some paranoia checking, mostly so that the ThinBox tests are
247 // more able to catch issues.
248 debug_assert!(value_offset == 0 && T::IS_ZST && H::IS_ZST);
249 layout.dangling()
250 } else {
251 let ptr = alloc::alloc(layout);
252 if ptr.is_null() {
253 alloc::handle_alloc_error(layout);
254 }
255 // Safety:
256 // - The size is at least `aligned_header_size`.
257 let ptr = ptr.add(value_offset) as *mut _;
258
259 NonNull::new_unchecked(ptr)
260 };
261
262 let result = WithHeader(ptr, PhantomData);
263 ptr::write(result.header(), header);
264 ptr::write(result.value().cast(), value);
265
266 result
267 }
268 }
269
270 /// Non-panicking version of `new`.
271 /// Any error is returned as `Err(core::alloc::AllocError)`.
272 fn try_new<T>(header: H, value: T) -> Result<WithHeader<H>, core::alloc::AllocError> {
273 let value_layout = Layout::new::<T>();
274 let Ok((layout, value_offset)) = Self::alloc_layout(value_layout) else {
275 return Err(core::alloc::AllocError);
276 };
277
278 unsafe {
279 // Note: It's UB to pass a layout with a zero size to `alloc::alloc`, so
280 // we use `layout.dangling()` for this case, which should have a valid
281 // alignment for both `T` and `H`.
282 let ptr = if layout.size() == 0 {
283 // Some paranoia checking, mostly so that the ThinBox tests are
284 // more able to catch issues.
285 debug_assert!(
286 value_offset == 0 && mem::size_of::<T>() == 0 && mem::size_of::<H>() == 0
287 );
288 layout.dangling()
289 } else {
290 let ptr = alloc::alloc(layout);
291 if ptr.is_null() {
292 return Err(core::alloc::AllocError);
293 }
294
295 // Safety:
296 // - The size is at least `aligned_header_size`.
297 let ptr = ptr.add(value_offset) as *mut _;
298
299 NonNull::new_unchecked(ptr)
300 };
301
302 let result = WithHeader(ptr, PhantomData);
303 ptr::write(result.header(), header);
304 ptr::write(result.value().cast(), value);
305
306 Ok(result)
307 }
308 }
309
310 // `Dyn` is `?Sized` type like `[u32]`, and `T` is ZST type like `[u32; 0]`.
311 #[cfg(not(no_global_oom_handling))]
312 fn new_unsize_zst<Dyn, T>(value: T) -> WithHeader<H>
313 where
314 Dyn: Pointee<Metadata = H> + ?Sized,
315 T: Unsize<Dyn>,
316 {
317 assert!(mem::size_of::<T>() == 0);
318
319 const fn max(a: usize, b: usize) -> usize {
320 if a > b { a } else { b }
321 }
322
323 // Compute a pointer to the right metadata. This will point to the beginning
324 // of the header, past the padding, so the assigned type makes sense.
325 // It also ensures that the address at the end of the header is sufficiently
326 // aligned for T.
327 let alloc: &<Dyn as Pointee>::Metadata = const {
328 // FIXME: just call `WithHeader::alloc_layout` with size reset to 0.
329 // Currently that's blocked on `Layout::extend` not being `const fn`.
330
331 let alloc_align =
332 max(mem::align_of::<T>(), mem::align_of::<<Dyn as Pointee>::Metadata>());
333
334 let alloc_size =
335 max(mem::align_of::<T>(), mem::size_of::<<Dyn as Pointee>::Metadata>());
336
337 unsafe {
338 // SAFETY: align is power of two because it is the maximum of two alignments.
339 let alloc: *mut u8 = const_allocate(alloc_size, alloc_align);
340
341 let metadata_offset =
342 alloc_size.checked_sub(mem::size_of::<<Dyn as Pointee>::Metadata>()).unwrap();
343 // SAFETY: adding offset within the allocation.
344 let metadata_ptr: *mut <Dyn as Pointee>::Metadata =
345 alloc.add(metadata_offset).cast();
346 // SAFETY: `*metadata_ptr` is within the allocation.
347 metadata_ptr.write(ptr::metadata::<Dyn>(ptr::dangling::<T>() as *const Dyn));
348
349 // SAFETY: we have just written the metadata.
350 &*(metadata_ptr)
351 }
352 };
353
354 // SAFETY: `alloc` points to `<Dyn as Pointee>::Metadata`, so addition stays in-bounds.
355 let value_ptr =
356 unsafe { (alloc as *const <Dyn as Pointee>::Metadata).add(1) }.cast::<T>().cast_mut();
357 debug_assert!(value_ptr.is_aligned());
358 mem::forget(value);
359 WithHeader(NonNull::new(value_ptr.cast()).unwrap(), PhantomData)
360 }
361
362 // Safety:
363 // - Assumes that either `value` can be dereferenced, or is the
364 // `NonNull::dangling()` we use when both `T` and `H` are ZSTs.
365 unsafe fn drop<T: ?Sized>(&self, value: *mut T) {
366 struct DropGuard<H> {
367 ptr: NonNull<u8>,
368 value_layout: Layout,
369 _marker: PhantomData<H>,
370 }
371
372 impl<H> Drop for DropGuard<H> {
373 fn drop(&mut self) {
374 // All ZST are allocated statically.
375 if self.value_layout.size() == 0 {
376 return;
377 }
378
379 unsafe {
380 // SAFETY: Layout must have been computable if we're in drop
381 let (layout, value_offset) =
382 WithHeader::<H>::alloc_layout(self.value_layout).unwrap_unchecked();
383
384 // Since we only allocate for non-ZSTs, the layout size cannot be zero.
385 debug_assert!(layout.size() != 0);
386 alloc::dealloc(self.ptr.as_ptr().sub(value_offset), layout);
387 }
388 }
389 }
390
391 unsafe {
392 // `_guard` will deallocate the memory when dropped, even if `drop_in_place` unwinds.
393 let _guard = DropGuard {
394 ptr: self.0,
395 value_layout: Layout::for_value_raw(value),
396 _marker: PhantomData::<H>,
397 };
398
399 // We only drop the value because the Pointee trait requires that the metadata is copy
400 // aka trivially droppable.
401 ptr::drop_in_place::<T>(value);
402 }
403 }
404
405 fn header(&self) -> *mut H {
406 // Safety:
407 // - At least `size_of::<H>()` bytes are allocated ahead of the pointer.
408 // - We know that H will be aligned because the middle pointer is aligned to the greater
409 // of the alignment of the header and the data and the header size includes the padding
410 // needed to align the header. Subtracting the header size from the aligned data pointer
411 // will always result in an aligned header pointer, it just may not point to the
412 // beginning of the allocation.
413 let hp = unsafe { self.0.as_ptr().sub(Self::header_size()) as *mut H };
414 debug_assert!(hp.is_aligned());
415 hp
416 }
417
418 fn value(&self) -> *mut u8 {
419 self.0.as_ptr()
420 }
421
422 const fn header_size() -> usize {
423 mem::size_of::<H>()
424 }
425
426 fn alloc_layout(value_layout: Layout) -> Result<(Layout, usize), LayoutError> {
427 Layout::new::<H>().extend(value_layout)
428 }
429}
430
431#[unstable(feature = "thin_box", issue = "92791")]
432impl<T: ?Sized + Error> Error for ThinBox<T> {
433 fn source(&self) -> Option<&(dyn Error + 'static)> {
434 self.deref().source()
435 }
436}
437