alloc/boxed/
thin.rs

1//! Based on
2//! <https://github.com/matthieu-m/rfc2580/blob/b58d1d3cba0d4b5e859d3617ea2d0943aaa31329/examples/thin.rs>
3//! by matthieu-m
4
5use core::error::Error;
6use core::fmt::{self, Debug, Display, Formatter};
7#[cfg(not(no_global_oom_handling))]
8use core::intrinsics::{const_allocate, const_make_global};
9use core::marker::PhantomData;
10#[cfg(not(no_global_oom_handling))]
11use core::marker::Unsize;
12#[cfg(not(no_global_oom_handling))]
13use core::mem;
14use core::mem::SizedTypeProperties;
15use core::ops::{Deref, DerefMut};
16use core::ptr::{self, NonNull, Pointee};
17
18use crate::alloc::{self, Layout, LayoutError};
19
20/// ThinBox.
21///
22/// A thin pointer for heap allocation, regardless of T.
23///
24/// # Examples
25///
26/// ```
27/// #![feature(thin_box)]
28/// use std::boxed::ThinBox;
29///
30/// let five = ThinBox::new(5);
31/// let thin_slice = ThinBox::<[i32]>::new_unsize([1, 2, 3, 4]);
32///
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 T::IS_ZST {
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 = self.data();
147        let metadata = self.meta();
148        let pointer = ptr::from_raw_parts(value as *const (), metadata);
149        // SAFETY: &ThinBox<T> points to a valid pointer for T.
150        unsafe { &*pointer }
151    }
152}
153
154#[unstable(feature = "thin_box", issue = "92791")]
155impl<T: ?Sized> DerefMut for ThinBox<T> {
156    fn deref_mut(&mut self) -> &mut T {
157        let value = self.data();
158        let metadata = self.meta();
159        let pointer = ptr::from_raw_parts_mut::<T>(value as *mut (), metadata);
160        // SAFETY: &mut ThinBox<T> points to a valid and unique pointer for T.
161        unsafe { &mut *pointer }
162    }
163}
164
165#[unstable(feature = "thin_box", issue = "92791")]
166impl<T: ?Sized> Drop for ThinBox<T> {
167    fn drop(&mut self) {
168        let value = self.deref_mut();
169        let value = value as *mut T;
170        // SAFETY: `value` is valid for reads and writes for our `T`.
171        unsafe {
172            self.with_header().drop::<T>(value);
173        }
174    }
175}
176
177#[unstable(feature = "thin_box", issue = "92791")]
178impl<T: ?Sized> ThinBox<T> {
179    fn meta(&self) -> <T as Pointee>::Metadata {
180        // SAFETY: NonNull and valid.
181        unsafe { *self.with_header().header() }
182    }
183
184    fn data(&self) -> *mut u8 {
185        self.with_header().value()
186    }
187
188    fn with_header(&self) -> &WithHeader<<T as Pointee>::Metadata> {
189        // SAFETY: both types are transparent to `NonNull<u8>`
190        unsafe { &*((&raw const self.ptr) as *const WithHeader<_>) }
191    }
192}
193
194/// A pointer to type-erased data, guaranteed to either be:
195/// 1. `NonNull::dangling()`, in the case where both the pointee (`T`) and
196///    metadata (`H`) are ZSTs.
197/// 2. A pointer to a valid `T` that has a header `H` directly before the
198///    pointed-to location.
199#[repr(transparent)]
200struct WithHeader<H>(NonNull<u8>, PhantomData<H>);
201
202/// An opaque representation of `WithHeader<H>` to avoid the
203/// projection invariance of `<T as Pointee>::Metadata`.
204#[repr(transparent)]
205struct WithOpaqueHeader(NonNull<u8>);
206
207impl WithOpaqueHeader {
208    #[cfg(not(no_global_oom_handling))]
209    fn new<H, T>(header: H, value: T) -> Self {
210        let ptr = WithHeader::new(header, value);
211        Self(ptr.0)
212    }
213
214    #[cfg(not(no_global_oom_handling))]
215    fn new_unsize_zst<Dyn, T>(value: T) -> Self
216    where
217        Dyn: ?Sized,
218        T: Unsize<Dyn>,
219    {
220        let ptr = WithHeader::<<Dyn as Pointee>::Metadata>::new_unsize_zst::<Dyn, T>(value);
221        Self(ptr.0)
222    }
223
224    fn try_new<H, T>(header: H, value: T) -> Result<Self, core::alloc::AllocError> {
225        WithHeader::try_new(header, value).map(|ptr| Self(ptr.0))
226    }
227}
228
229impl<H> WithHeader<H> {
230    #[cfg(not(no_global_oom_handling))]
231    fn new<T>(header: H, value: T) -> WithHeader<H> {
232        let value_layout = Layout::new::<T>();
233        let Ok((layout, value_offset)) = Self::alloc_layout(value_layout) else {
234            // We pass an empty layout here because we do not know which layout caused the
235            // arithmetic overflow in `Layout::extend` and `handle_alloc_error` takes `Layout` as
236            // its argument rather than `Result<Layout, LayoutError>`, also this function has been
237            // stable since 1.28 ._.
238            //
239            // On the other hand, look at this gorgeous turbofish!
240            alloc::handle_alloc_error(Layout::new::<()>());
241        };
242
243        // Note: It's UB to pass a layout with a zero size to `alloc::alloc`, so
244        // we use `layout.dangling()` for this case, which should have a valid
245        // alignment for both `T` and `H`.
246        let ptr = if layout.size() == 0 {
247            // Some paranoia checking, mostly so that the ThinBox tests are
248            // more able to catch issues.
249            debug_assert!(value_offset == 0 && T::IS_ZST && H::IS_ZST);
250            layout.dangling_ptr()
251        } else {
252            // SAFETY: We check above that the layout size is nonzero.
253            let ptr = unsafe { alloc::alloc(layout) };
254            if ptr.is_null() {
255                alloc::handle_alloc_error(layout);
256            }
257            // SAFETY:
258            // - The size is at least `aligned_header_size`.
259            unsafe {
260                let ptr = ptr.add(value_offset) as *mut _;
261
262                NonNull::new_unchecked(ptr)
263            }
264        };
265
266        let result = WithHeader(ptr, PhantomData);
267
268        // SAFETY: `result.header()` promises to give us a valid place for writing
269        // the header, and `result.value()` promises the same for the value.
270        unsafe {
271            ptr::write(result.header(), header);
272            ptr::write(result.value().cast(), value);
273        }
274
275        result
276    }
277
278    /// Non-panicking version of `new`.
279    /// Any error is returned as `Err(core::alloc::AllocError)`.
280    fn try_new<T>(header: H, value: T) -> Result<WithHeader<H>, core::alloc::AllocError> {
281        let value_layout = Layout::new::<T>();
282        let Ok((layout, value_offset)) = Self::alloc_layout(value_layout) else {
283            return Err(core::alloc::AllocError);
284        };
285
286        // Note: It's UB to pass a layout with a zero size to `alloc::alloc`, so
287        // we use `layout.dangling()` for this case, which should have a valid
288        // alignment for both `T` and `H`.
289        let ptr = if layout.size() == 0 {
290            // Some paranoia checking, mostly so that the ThinBox tests are
291            // more able to catch issues.
292            debug_assert!(value_offset == 0 && T::IS_ZST && H::IS_ZST);
293            layout.dangling_ptr()
294        } else {
295            // SAFETY: We check above that the layout size is nonzero.
296            let ptr = unsafe { alloc::alloc(layout) };
297            if ptr.is_null() {
298                return Err(core::alloc::AllocError);
299            }
300
301            // SAFETY:
302            // - The size is at least `aligned_header_size`.
303            unsafe {
304                let ptr = ptr.add(value_offset) as *mut _;
305
306                NonNull::new_unchecked(ptr)
307            }
308        };
309
310        let result = WithHeader(ptr, PhantomData);
311
312        // SAFETY: `result.header()` promises to give us a valid place for writing
313        // the header, and `result.value()` promises the same for the value.
314        unsafe {
315            ptr::write(result.header(), header);
316            ptr::write(result.value().cast(), value);
317        }
318
319        Ok(result)
320    }
321
322    // `Dyn` is `?Sized` type like `[u32]`, and `T` is ZST type like `[u32; 0]`.
323    #[cfg(not(no_global_oom_handling))]
324    fn new_unsize_zst<Dyn, T>(value: T) -> WithHeader<H>
325    where
326        Dyn: Pointee<Metadata = H> + ?Sized,
327        T: Unsize<Dyn>,
328    {
329        assert!(T::IS_ZST);
330
331        const fn max(a: usize, b: usize) -> usize {
332            if a > b { a } else { b }
333        }
334
335        // Compute a pointer to the right metadata. This will point to the beginning
336        // of the header, past the padding, so the assigned type makes sense.
337        // It also ensures that the address at the end of the header is sufficiently
338        // aligned for T.
339        let alloc: &<Dyn as Pointee>::Metadata = const {
340            // FIXME: just call `WithHeader::alloc_layout` with size reset to 0.
341            // Currently that's blocked on `Layout::extend` not being `const fn`.
342
343            let alloc_align = max(align_of::<T>(), align_of::<<Dyn as Pointee>::Metadata>());
344
345            let alloc_size = max(align_of::<T>(), size_of::<<Dyn as Pointee>::Metadata>());
346
347            // SAFETY: align is power of two because it is the maximum of two alignments.
348            let alloc: *mut u8 = unsafe { const_allocate(alloc_size, alloc_align) };
349
350            let metadata_offset =
351                alloc_size.checked_sub(size_of::<<Dyn as Pointee>::Metadata>()).unwrap();
352            let metadata_ptr: *mut <Dyn as Pointee>::Metadata =
353                // SAFETY: adding offset within the allocation.
354                unsafe { alloc.add(metadata_offset).cast() };
355            // SAFETY: `*metadata_ptr` is within the allocation.
356            unsafe {
357                metadata_ptr.write(ptr::metadata::<Dyn>(ptr::dangling::<T>() as *const Dyn));
358            }
359            // SAFETY: valid heap allocation
360            unsafe { const_make_global(alloc) };
361            // SAFETY: we have just written the metadata.
362            unsafe { &*metadata_ptr }
363        };
364
365        let value_ptr =
366            // SAFETY: `alloc` points to `<Dyn as Pointee>::Metadata`, so addition stays in-bounds.
367            unsafe { (alloc as *const <Dyn as Pointee>::Metadata).add(1) }.cast::<T>().cast_mut();
368        debug_assert!(value_ptr.is_aligned());
369        mem::forget(value);
370        WithHeader(NonNull::new(value_ptr.cast()).unwrap(), PhantomData)
371    }
372
373    /// # Safety
374    ///
375    /// `value` must point to an undropped owned `T`, and `self` must not be
376    /// accessed again after this is called.
377    unsafe fn drop<T: ?Sized>(&self, value: *mut T) {
378        struct DropGuard<H> {
379            ptr: NonNull<u8>,
380            value_layout: Layout,
381            _marker: PhantomData<H>,
382        }
383
384        impl<H> Drop for DropGuard<H> {
385            fn drop(&mut self) {
386                // All ZST are allocated statically.
387                if self.value_layout.size() == 0 {
388                    return;
389                }
390
391                let (layout, value_offset) =
392                    // SAFETY: Layout must have been computable if we're in drop
393                    unsafe { WithHeader::<H>::alloc_layout(self.value_layout).unwrap_unchecked() };
394
395                // Since we only allocate for non-ZSTs, the layout size cannot be zero.
396                debug_assert!(layout.size() != 0);
397                // SAFETY: We own the allocation with `layout` at `ptr - value_offset`.
398                unsafe { alloc::dealloc(self.ptr.as_ptr().sub(value_offset), layout) };
399            }
400        }
401
402        // `_guard` will deallocate the memory when dropped, even if `drop_in_place` unwinds.
403        let _guard = DropGuard {
404            ptr: self.0,
405            // SAFETY: Caller ensures `value` is valid.
406            value_layout: unsafe { Layout::for_value_raw(value) },
407            _marker: PhantomData::<H>,
408        };
409
410        // We only drop the value because the Pointee trait requires that the metadata is copy
411        // aka trivially droppable.
412        // SAFETY: We're the only droppers of `value` and it's not dropped again.
413        unsafe { ptr::drop_in_place::<T>(value) };
414    }
415
416    fn header(&self) -> *mut H {
417        // SAFETY:
418        //  - At least `size_of::<H>()` bytes are allocated ahead of the pointer.
419        //  - We know that H will be aligned because the middle pointer is aligned to the greater
420        //    of the alignment of the header and the data and the header size includes the padding
421        //    needed to align the header. Subtracting the header size from the aligned data pointer
422        //    will always result in an aligned header pointer, it just may not point to the
423        //    beginning of the allocation.
424        let hp = unsafe { self.0.as_ptr().sub(Self::header_size()) as *mut H };
425        debug_assert!(hp.is_aligned());
426        hp
427    }
428
429    fn value(&self) -> *mut u8 {
430        self.0.as_ptr()
431    }
432
433    const fn header_size() -> usize {
434        size_of::<H>()
435    }
436
437    fn alloc_layout(value_layout: Layout) -> Result<(Layout, usize), LayoutError> {
438        Layout::new::<H>().extend(value_layout)
439    }
440}
441
442#[unstable(feature = "thin_box", issue = "92791")]
443impl<T: ?Sized + Error> Error for ThinBox<T> {
444    fn source(&self) -> Option<&(dyn Error + 'static)> {
445        self.deref().source()
446    }
447}
448
449#[cfg(not(no_global_oom_handling))]
450#[unstable(feature = "thin_box", issue = "92791")]
451impl<T> From<T> for ThinBox<T> {
452    #[inline(always)]
453    fn from(value: T) -> Self {
454        Self::new(value)
455    }
456}
alloc/boxed/thin.rs

alloc/boxed/
thin.rs
