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

alloc/boxed/
thin.rs
