1 #![unstable(feature = "ptr_metadata", issue = "81513")]
4 use crate::hash::{Hash, Hasher};
6 /// Provides the pointer metadata type of any pointed-to type.
10 /// Raw pointer types and reference types in Rust can be thought of as made of two parts:
11 /// a data pointer that contains the memory address of the value, and some metadata.
13 /// For statically-sized types (that implement the `Sized` traits)
14 /// as well as for `extern` types,
15 /// pointers are said to be “thin”: metadata is zero-sized and its type is `()`.
17 /// Pointers to [dynamically-sized types][dst] are said to be “wide” or “fat”,
18 /// they have non-zero-sized metadata:
20 /// * For structs whose last field is a DST, metadata is the metadata for the last field
21 /// * For the `str` type, metadata is the length in bytes as `usize`
22 /// * For slice types like `[T]`, metadata is the length in items as `usize`
23 /// * For trait objects like `dyn SomeTrait`, metadata is [`DynMetadata<Self>`][DynMetadata]
24 /// (e.g. `DynMetadata<dyn SomeTrait>`)
26 /// In the future, the Rust language may gain new kinds of types
27 /// that have different pointer metadata.
29 /// [dst]: https://doc.rust-lang.org/nomicon/exotic-sizes.html#dynamically-sized-types-dsts
32 /// # The `Pointee` trait
34 /// The point of this trait is its `Metadata` associated type,
35 /// which is `()` or `usize` or `DynMetadata<_>` as described above.
36 /// It is automatically implemented for every type.
37 /// It can be assumed to be implemented in a generic context, even without a corresponding bound.
42 /// Raw pointers can be decomposed into the data address and metadata components
43 /// with their [`to_raw_parts`] method.
45 /// Alternatively, metadata alone can be extracted with the [`metadata`] function.
46 /// A reference can be passed to [`metadata`] and implicitly coerced.
48 /// A (possibly-wide) pointer can be put back together from its address and metadata
49 /// with [`from_raw_parts`] or [`from_raw_parts_mut`].
51 /// [`to_raw_parts`]: *const::to_raw_parts
52 #[lang = "pointee_trait"]
54 /// The type for metadata in pointers and references to `Self`.
55 #[lang = "metadata_type"]
56 // NOTE: Keep trait bounds in `static_assert_expected_bounds_for_metadata`
57 // in `library/core/src/ptr/metadata.rs`
58 // in sync with those here:
59 type Metadata: Copy + Send + Sync + Ord + Hash + Unpin;
62 /// Pointers to types implementing this trait alias are “thin”.
64 /// This includes statically-`Sized` types and `extern` types.
69 /// #![feature(ptr_metadata)]
71 /// fn this_never_panics<T: std::ptr::Thin>() {
72 /// assert_eq!(std::mem::size_of::<&T>(), std::mem::size_of::<usize>())
75 #[unstable(feature = "ptr_metadata", issue = "81513")]
76 // NOTE: don’t stabilize this before trait aliases are stable in the language?
77 pub trait Thin = Pointee<Metadata = ()>;
79 /// Extract the metadata component of a pointer.
81 /// Values of type `*mut T`, `&T`, or `&mut T` can be passed directly to this function
82 /// as they implicitly coerce to `*const T`.
87 /// #![feature(ptr_metadata)]
89 /// assert_eq!(std::ptr::metadata("foo"), 3_usize);
91 #[rustc_const_unstable(feature = "ptr_metadata", issue = "81513")]
93 pub const fn metadata<T: ?Sized>(ptr: *const T) -> <T as Pointee>::Metadata {
94 // SAFETY: Accessing the value from the `PtrRepr` union is safe since *const T
95 // and PtrComponents<T> have the same memory layouts. Only std can make this
97 unsafe { PtrRepr { const_ptr: ptr }.components.metadata }
100 /// Forms a (possibly-wide) raw pointer from a data address and metadata.
102 /// This function is safe but the returned pointer is not necessarily safe to dereference.
103 /// For slices, see the documentation of [`slice::from_raw_parts`] for safety requirements.
104 /// For trait objects, the metadata must come from a pointer to the same underlying erased type.
106 /// [`slice::from_raw_parts`]: crate::slice::from_raw_parts
107 #[unstable(feature = "ptr_metadata", issue = "81513")]
108 #[rustc_const_unstable(feature = "ptr_metadata", issue = "81513")]
110 pub const fn from_raw_parts<T: ?Sized>(
111 data_address: *const (),
112 metadata: <T as Pointee>::Metadata,
114 // SAFETY: Accessing the value from the `PtrRepr` union is safe since *const T
115 // and PtrComponents<T> have the same memory layouts. Only std can make this
117 unsafe { PtrRepr { components: PtrComponents { data_address, metadata } }.const_ptr }
120 /// Performs the same functionality as [`from_raw_parts`], except that a
121 /// raw `*mut` pointer is returned, as opposed to a raw `*const` pointer.
123 /// See the documentation of [`from_raw_parts`] for more details.
124 #[unstable(feature = "ptr_metadata", issue = "81513")]
125 #[rustc_const_unstable(feature = "ptr_metadata", issue = "81513")]
127 pub const fn from_raw_parts_mut<T: ?Sized>(
128 data_address: *mut (),
129 metadata: <T as Pointee>::Metadata,
131 // SAFETY: Accessing the value from the `PtrRepr` union is safe since *const T
132 // and PtrComponents<T> have the same memory layouts. Only std can make this
134 unsafe { PtrRepr { components: PtrComponents { data_address, metadata } }.mut_ptr }
138 pub(crate) union PtrRepr<T: ?Sized> {
139 pub(crate) const_ptr: *const T,
140 pub(crate) mut_ptr: *mut T,
141 pub(crate) components: PtrComponents<T>,
145 pub(crate) struct PtrComponents<T: ?Sized> {
146 pub(crate) data_address: *const (),
147 pub(crate) metadata: <T as Pointee>::Metadata,
150 // Manual impl needed to avoid `T: Copy` bound.
151 impl<T: ?Sized> Copy for PtrComponents<T> {}
153 // Manual impl needed to avoid `T: Clone` bound.
154 impl<T: ?Sized> Clone for PtrComponents<T> {
155 fn clone(&self) -> Self {
160 /// The metadata for a `Dyn = dyn SomeTrait` trait object type.
162 /// It is a pointer to a vtable (virtual call table)
163 /// that represents all the necessary information
164 /// to manipulate the concrete type stored inside a trait object.
165 /// The vtable notably it contains:
169 /// * a pointer to the type’s `drop_in_place` impl (may be a no-op for plain-old-data)
170 /// * pointers to all the methods for the type’s implementation of the trait
172 /// Note that the first three are special because they’re necessary to allocate, drop,
173 /// and deallocate any trait object.
175 /// It is possible to name this struct with a type parameter that is not a `dyn` trait object
176 /// (for example `DynMetadata<u64>`) but not to obtain a meaningful value of that struct.
177 #[lang = "dyn_metadata"]
178 pub struct DynMetadata<Dyn: ?Sized> {
179 vtable_ptr: &'static VTable,
180 phantom: crate::marker::PhantomData<Dyn>,
184 /// Opaque type for accessing vtables.
186 /// Private implementation detail of `DynMetadata::size_of` etc.
187 /// There is conceptually not actually any Abstract Machine memory behind this pointer.
191 impl<Dyn: ?Sized> DynMetadata<Dyn> {
192 /// Returns the size of the type associated with this vtable.
194 pub fn size_of(self) -> usize {
195 // Note that "size stored in vtable" is *not* the same as "result of size_of_val_raw".
196 // Consider a reference like `&(i32, dyn Send)`: the vtable will only store the size of the
198 // SAFETY: DynMetadata always contains a valid vtable pointer
200 crate::intrinsics::vtable_size(self.vtable_ptr as *const VTable as *const ())
204 /// Returns the alignment of the type associated with this vtable.
206 pub fn align_of(self) -> usize {
207 // SAFETY: DynMetadata always contains a valid vtable pointer
209 crate::intrinsics::vtable_align(self.vtable_ptr as *const VTable as *const ())
213 /// Returns the size and alignment together as a `Layout`
215 pub fn layout(self) -> crate::alloc::Layout {
216 // SAFETY: the compiler emitted this vtable for a concrete Rust type which
217 // is known to have a valid layout. Same rationale as in `Layout::for_value`.
218 unsafe { crate::alloc::Layout::from_size_align_unchecked(self.size_of(), self.align_of()) }
222 unsafe impl<Dyn: ?Sized> Send for DynMetadata<Dyn> {}
223 unsafe impl<Dyn: ?Sized> Sync for DynMetadata<Dyn> {}
225 impl<Dyn: ?Sized> fmt::Debug for DynMetadata<Dyn> {
226 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
227 f.debug_tuple("DynMetadata").field(&(self.vtable_ptr as *const VTable)).finish()
231 // Manual impls needed to avoid `Dyn: $Trait` bounds.
233 impl<Dyn: ?Sized> Unpin for DynMetadata<Dyn> {}
235 impl<Dyn: ?Sized> Copy for DynMetadata<Dyn> {}
237 impl<Dyn: ?Sized> Clone for DynMetadata<Dyn> {
239 fn clone(&self) -> Self {
244 impl<Dyn: ?Sized> Eq for DynMetadata<Dyn> {}
246 impl<Dyn: ?Sized> PartialEq for DynMetadata<Dyn> {
248 fn eq(&self, other: &Self) -> bool {
249 crate::ptr::eq::<VTable>(self.vtable_ptr, other.vtable_ptr)
253 impl<Dyn: ?Sized> Ord for DynMetadata<Dyn> {
255 fn cmp(&self, other: &Self) -> crate::cmp::Ordering {
256 (self.vtable_ptr as *const VTable).cmp(&(other.vtable_ptr as *const VTable))
260 impl<Dyn: ?Sized> PartialOrd for DynMetadata<Dyn> {
262 fn partial_cmp(&self, other: &Self) -> Option<crate::cmp::Ordering> {
263 Some(self.cmp(other))
267 impl<Dyn: ?Sized> Hash for DynMetadata<Dyn> {
269 fn hash<H: Hasher>(&self, hasher: &mut H) {
270 crate::ptr::hash::<VTable, _>(self.vtable_ptr, hasher)