Skip to main content

core/ptr/
metadata.rs

1#![unstable(feature = "ptr_metadata", issue = "81513")]
2
3use crate::clone::TrivialClone;
4use crate::fmt;
5use crate::hash::{Hash, Hasher};
6use crate::intrinsics::{aggregate_raw_ptr, ptr_metadata};
7use crate::marker::{Freeze, PointeeSized};
8use crate::ptr::NonNull;
9
10/// Provides the pointer metadata type of any pointed-to type.
11///
12/// # Pointer metadata
13///
14/// Raw pointer types and reference types in Rust can be thought of as made of two parts:
15/// a data pointer that contains the memory address of the value, and some metadata.
16///
17/// For statically-sized types (that implement the `Sized` traits)
18/// as well as for `extern` types,
19/// pointers are said to be “thin”: metadata is zero-sized and its type is `()`.
20///
21/// Pointers to [dynamically-sized types][dst] are said to be “wide” or “fat”,
22/// they have non-zero-sized metadata:
23///
24/// * For structs whose last field is a DST, metadata is the metadata for the last field
25/// * For the `str` type, metadata is the length in bytes as `usize`
26/// * For slice types like `[T]`, metadata is the length in items as `usize`
27/// * For trait objects like `dyn SomeTrait`, metadata is [`DynMetadata<Self>`][DynMetadata]
28///   (e.g. `DynMetadata<dyn SomeTrait>`)
29///
30/// In the future, the Rust language may gain new kinds of types
31/// that have different pointer metadata.
32///
33/// [dst]: https://doc.rust-lang.org/nomicon/exotic-sizes.html#dynamically-sized-types-dsts
34///
35///
36/// # The `Pointee` trait
37///
38/// The point of this trait is its `Metadata` associated type,
39/// which is `()` or `usize` or `DynMetadata<_>` as described above.
40/// It is automatically implemented for every type.
41/// It can be assumed to be implemented in a generic context, even without a corresponding bound.
42///
43///
44/// # Usage
45///
46/// Raw pointers can be decomposed into the data pointer and metadata components
47/// with their [`to_raw_parts`] method.
48///
49/// Alternatively, metadata alone can be extracted with the [`metadata`] function.
50/// A reference can be passed to [`metadata`] and implicitly coerced.
51///
52/// A (possibly-wide) pointer can be put back together from its data pointer and metadata
53/// with [`from_raw_parts`] or [`from_raw_parts_mut`].
54///
55/// [`to_raw_parts`]: *const::to_raw_parts
56#[lang = "pointee_trait"]
57#[rustc_deny_explicit_impl]
58#[rustc_dyn_incompatible_trait]
59pub trait Pointee: PointeeSized {
60    /// The type for metadata in pointers and references to `Self`.
61    #[lang = "metadata_type"]
62    // NOTE: Keep trait bounds in `static_assert_expected_bounds_for_metadata`
63    // in `library/core/src/ptr/metadata.rs`
64    // in sync with those here:
65    // NOTE: The metadata of `dyn Trait + 'a` is `DynMetadata<dyn Trait + 'a>`
66    // so a `'static` bound must not be added.
67    type Metadata: fmt::Debug + Copy + Send + Sync + Ord + Hash + Unpin + Freeze;
68}
69
70/// Pointers to types implementing this trait alias are “thin”.
71///
72/// This includes statically-`Sized` types and `extern` types.
73///
74/// # Example
75///
76/// ```rust
77/// #![feature(ptr_metadata)]
78///
79/// fn this_never_panics<T: std::ptr::Thin>() {
80///     assert_eq!(size_of::<&T>(), size_of::<usize>())
81/// }
82/// ```
83#[unstable(feature = "ptr_metadata", issue = "81513")]
84// NOTE: don’t stabilize this before trait aliases are stable in the language?
85pub trait Thin = Pointee<Metadata = ()> + PointeeSized;
86
87/// Extracts the metadata component of a pointer.
88///
89/// Values of type `*mut T`, `&T`, or `&mut T` can be passed directly to this function
90/// as they implicitly coerce to `*const T`.
91///
92/// # Example
93///
94/// ```
95/// #![feature(ptr_metadata)]
96///
97/// assert_eq!(std::ptr::metadata("foo"), 3_usize);
98/// ```
99#[inline]
100pub const fn metadata<T: PointeeSized>(ptr: *const T) -> <T as Pointee>::Metadata {
101    ptr_metadata(ptr)
102}
103
104/// Forms a (possibly-[wide]) raw pointer from a data pointer and metadata.
105///
106/// This function is safe but the returned pointer is not necessarily safe to dereference.
107/// For slices, see the documentation of [`slice::from_raw_parts`] for safety requirements.
108/// For trait objects, the metadata must come from a pointer to the same underlying erased type.
109///
110/// If you are attempting to deconstruct a DST in a generic context to be reconstructed later,
111/// a thin pointer can always be obtained by casting `*const T` to `*const ()`.
112///
113/// [`slice::from_raw_parts`]: crate::slice::from_raw_parts
114/// [wide]: core::ptr#thin-and-wide-pointers
115#[unstable(feature = "ptr_metadata", issue = "81513")]
116#[inline]
117pub const fn from_raw_parts<T: PointeeSized>(
118    data_pointer: *const impl Thin,
119    metadata: <T as Pointee>::Metadata,
120) -> *const T {
121    aggregate_raw_ptr(data_pointer, metadata)
122}
123
124/// Performs the same functionality as [`from_raw_parts`], except that a
125/// raw `*mut` pointer is returned, as opposed to a raw `*const` pointer.
126///
127/// See the documentation of [`from_raw_parts`] for more details.
128#[unstable(feature = "ptr_metadata", issue = "81513")]
129#[inline]
130pub const fn from_raw_parts_mut<T: PointeeSized>(
131    data_pointer: *mut impl Thin,
132    metadata: <T as Pointee>::Metadata,
133) -> *mut T {
134    aggregate_raw_ptr(data_pointer, metadata)
135}
136
137/// The metadata for a `Dyn = dyn SomeTrait` trait object type.
138///
139/// It is a pointer to a vtable (virtual call table)
140/// that represents all the necessary information
141/// to manipulate the concrete type stored inside a trait object.
142/// The vtable notably contains:
143///
144/// * type size
145/// * type alignment
146/// * a pointer to the type’s `drop_in_place` impl (may be a no-op for plain-old-data)
147/// * pointers to all the methods for the type’s implementation of the trait
148///
149/// Note that the first three are special because they’re necessary to allocate, drop,
150/// and deallocate any trait object.
151///
152/// It is possible to name this struct with a type parameter that is not a `dyn` trait object
153/// (for example `DynMetadata<u64>`) but not to obtain a meaningful value of that struct.
154///
155/// Note that while this type implements `PartialEq`, comparing vtable pointers is unreliable:
156/// pointers to vtables of the same type for the same trait can compare inequal (because vtables are
157/// duplicated in multiple codegen units), and pointers to vtables of *different* types/traits can
158/// compare equal (since identical vtables can be deduplicated within a codegen unit).
159#[lang = "dyn_metadata"]
160pub struct DynMetadata<Dyn: PointeeSized> {
161    _vtable_ptr: NonNull<VTable>,
162    _phantom: crate::marker::PhantomData<Dyn>,
163}
164
165unsafe extern "C" {
166    /// Opaque type for accessing vtables.
167    ///
168    /// Private implementation detail of `DynMetadata::size_of` etc.
169    /// There is conceptually not actually any Abstract Machine memory behind this pointer.
170    type VTable;
171}
172
173impl<Dyn: PointeeSized> DynMetadata<Dyn> {
174    /// When `DynMetadata` appears as the metadata field of a wide pointer, the rustc_middle layout
175    /// computation does magic and the resulting layout is *not* a `FieldsShape::Aggregate`, instead
176    /// it is a `FieldsShape::Primitive`. This means that the same type can have different layout
177    /// depending on whether it appears as the metadata field of a wide pointer or as a stand-alone
178    /// type, which understandably confuses codegen and leads to ICEs when trying to project to a
179    /// field of `DynMetadata`. To work around that issue, we use `transmute` instead of using a
180    /// field projection.
181    #[inline]
182    fn vtable_ptr(self) -> *const VTable {
183        // SAFETY: this layout assumption is hard-coded into the compiler.
184        // If it's somehow not a size match, the transmute will error.
185        unsafe { crate::mem::transmute::<Self, *const VTable>(self) }
186    }
187
188    /// Returns the size of the type associated with this vtable.
189    #[inline]
190    pub fn size_of(self) -> usize {
191        // Note that "size stored in vtable" is *not* the same as "result of size_of_val_raw".
192        // Consider a reference like `&(i32, dyn Send)`: the vtable will only store the size of the
193        // `Send` part!
194        // SAFETY: DynMetadata always contains a valid vtable pointer
195        unsafe { crate::intrinsics::vtable_size(self.vtable_ptr() as *const ()) }
196    }
197
198    /// Returns the alignment of the type associated with this vtable.
199    #[inline]
200    pub fn align_of(self) -> usize {
201        // SAFETY: DynMetadata always contains a valid vtable pointer
202        unsafe { crate::intrinsics::vtable_align(self.vtable_ptr() as *const ()) }
203    }
204
205    /// Returns the size and alignment together as a `Layout`
206    #[inline]
207    pub fn layout(self) -> crate::alloc::Layout {
208        // SAFETY: the compiler emitted this vtable for a concrete Rust type which
209        // is known to have a valid layout. Same rationale as in `Layout::for_value`.
210        unsafe { crate::alloc::Layout::from_size_align_unchecked(self.size_of(), self.align_of()) }
211    }
212}
213
214unsafe impl<Dyn: PointeeSized> Send for DynMetadata<Dyn> {}
215unsafe impl<Dyn: PointeeSized> Sync for DynMetadata<Dyn> {}
216
217impl<Dyn: PointeeSized> fmt::Debug for DynMetadata<Dyn> {
218    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
219        f.debug_tuple("DynMetadata").field(&self.vtable_ptr()).finish()
220    }
221}
222
223// Manual impls needed to avoid `Dyn: $Trait` bounds.
224
225impl<Dyn: PointeeSized> Unpin for DynMetadata<Dyn> {}
226
227impl<Dyn: PointeeSized> Copy for DynMetadata<Dyn> {}
228
229impl<Dyn: PointeeSized> Clone for DynMetadata<Dyn> {
230    #[inline]
231    fn clone(&self) -> Self {
232        *self
233    }
234}
235
236#[doc(hidden)]
237unsafe impl<Dyn: PointeeSized> TrivialClone for DynMetadata<Dyn> {}
238
239impl<Dyn: PointeeSized> Eq for DynMetadata<Dyn> {}
240
241impl<Dyn: PointeeSized> PartialEq for DynMetadata<Dyn> {
242    #[inline]
243    fn eq(&self, other: &Self) -> bool {
244        crate::ptr::eq::<VTable>(self.vtable_ptr(), other.vtable_ptr())
245    }
246}
247
248impl<Dyn: PointeeSized> Ord for DynMetadata<Dyn> {
249    #[inline]
250    #[allow(ambiguous_wide_pointer_comparisons)]
251    fn cmp(&self, other: &Self) -> crate::cmp::Ordering {
252        <*const VTable>::cmp(&self.vtable_ptr(), &other.vtable_ptr())
253    }
254}
255
256impl<Dyn: PointeeSized> PartialOrd for DynMetadata<Dyn> {
257    #[inline]
258    fn partial_cmp(&self, other: &Self) -> Option<crate::cmp::Ordering> {
259        Some(self.cmp(other))
260    }
261}
262
263impl<Dyn: PointeeSized> Hash for DynMetadata<Dyn> {
264    #[inline]
265    fn hash<H: Hasher>(&self, hasher: &mut H) {
266        crate::ptr::hash::<VTable, _>(self.vtable_ptr(), hasher)
267    }
268}