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 | #[cfg (not(no_global_oom_handling))] |
8 | use core::intrinsics::const_allocate; |
9 | use core::marker::PhantomData; |
10 | #[cfg (not(no_global_oom_handling))] |
11 | use core::marker::Unsize; |
12 | use core::mem; |
13 | #[cfg (not(no_global_oom_handling))] |
14 | use core::mem::SizedTypeProperties; |
15 | use core::ops::{Deref, DerefMut}; |
16 | use core::ptr::Pointee; |
17 | use 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" )] |
38 | pub 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" )] |
47 | unsafe 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" )] |
51 | unsafe impl<T: ?Sized + Sync> Sync for ThinBox<T> {} |
52 | |
53 | #[unstable (feature = "thin_box" , issue = "92791" )] |
54 | impl<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" )] |
97 | impl<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" )] |
128 | impl<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" )] |
135 | impl<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" )] |
142 | impl<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" )] |
154 | impl<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" )] |
164 | impl<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" )] |
175 | impl<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)] |
198 | struct 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)] |
203 | struct WithOpaqueHeader(NonNull<u8>); |
204 | |
205 | impl 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 | |
227 | impl<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" )] |
432 | impl<T: ?Sized + Error> Error for ThinBox<T> { |
433 | fn source(&self) -> Option<&(dyn Error + 'static)> { |
434 | self.deref().source() |
435 | } |
436 | } |
437 | |