Tracking Issue for pointer metadata APIs

[KodrAus]

This is a tracking issue for the RFC 2580 "Pointer metadata & VTable" (rust-lang/rfcs#2580).
The feature gate for the issue is #![feature(ptr_metadata)].

About tracking issues

Tracking issues are used to record the overall progress of implementation.
They are also used as hubs connecting to other relevant issues, e.g., bugs or open design questions.
A tracking issue is however not meant for large scale discussion, questions, or bug reports about a feature.
Instead, open a dedicated issue for the specific matter and add the relevant feature gate label.

Steps

• Implement the RFC (cc @rust-lang/libs @rust-lang/lang -- can anyone write up mentoring
  instructions?)
• Adjust documentation (see instructions on rustc-dev-guide)
• Stabilization PR (see instructions on rustc-dev-guide)

Unresolved Questions

Language-level:

• Is it, or should it be UB (through validity or safety invariants) to have a raw trait object wide pointer with an dangling vtable pointer? A null vtable pointer? If not, DynMetadata methods like size may need to be unsafe fn. Or maybe something like *const () should be metadata of trait objects instead of DynMetadata.
  Right now, there is some inconsistency here: size_of_val_raw(ptr) is unsafe, but metadta(ptr).size_of() does the same thing and is safe.
  Update (2024-10-04): It is definitely the case that the safety invariant for raw trait objects requires a valid vtable. So metadta(ptr).size_of() being safe is fine. size_of_val_raw(ptr) must be unsafe because of slices, so there is no inconsistency here.
• should Metadata be required to be Freeze

API level:

• Is *const () appropriate for the data component of pointers? Or should it be *const u8? Or *const Opaque with some new Opaque type? (Respectively *mut () and NonNull<()>)
• Should ptr::from_raw_parts and friends be unsafe fn?
• Should Thin be added as a supertrait of Sized? Or could it ever make sense to have fat pointers to statically-sized types?
• Should DynMetadata not have a type parameter? This might reduce monomorphization cost, but would force that the size, alignment, and destruction pointers be in the same location (offset) for every vtable. But keeping them in the same location is probaly desirable anyway to keep code size small.
• ACP: replace use of Pointee trait with a ptr::Metadata type libs-team#246
• DynMetadata::size_of does not always return the same value as size_of_val since the former only reads the size from the vtable, but the latter computes the size of the entire type. That seems like a pretty bad footgun?

API bikesheds:

• Name of new items: Pointee (v.s. Referent?), Thin (ThinPointee?), DynMetadata (VTablePtr?), etc
• Location of new items in core::ptr. For example: should Thin be in core::marker instead?

Implementation history

• Implement RFC 2580: Pointer metadata & VTable #81172 Initial implementation
• [ACP 362] genericize ptr::from_raw_parts #125701
• Generalize NonNull::from_raw_parts per ACP362 #132895

Tracked APIs

Last updated for #81172.

pub trait Pointee {
    /// One of `()`, `usize`, or `DynMetadata<dyn SomeTrait>`
    type Metadata;
}

pub trait Thin = Pointee<Metadata = ()>;

pub const fn metadata<T: ?Sized>(ptr: *const T) -> <T as Pointee>::Metadata {}

pub const fn from_raw_parts<T: ?Sized>(*const impl Thin, <T as Pointee>::Metadata) -> *const T {}
pub const fn from_raw_parts_mut<T: ?Sized>(*mut impl Thin, <T as Pointee>::Metadata) -> *mut T {}

impl<T: ?Sized> NonNull<T> {
    pub const fn from_raw_parts(NonNull<impl Thin>, <T as Pointee>::Metadata) -> NonNull<T> {}

    /// Convenience for `(ptr.cast(), metadata(ptr))`
    pub const fn to_raw_parts(self) -> (NonNull<()>, <T as Pointee>::Metadata) {}
}

impl<T: ?Sized> *const T {
    pub const fn to_raw_parts(self) -> (*const (), <T as Pointee>::Metadata) {}
}

impl<T: ?Sized> *mut T {
    pub const fn to_raw_parts(self) -> (*mut (), <T as Pointee>::Metadata) {}
}

/// `<dyn SomeTrait as Pointee>::Metadata == DynMetadata<dyn SomeTrait>`
pub struct DynMetadata<Dyn: ?Sized> {
    // Private pointer to vtable
}

impl<Dyn: ?Sized> DynMetadata<Dyn> {
    pub fn size_of(self) -> usize {}
    pub fn align_of(self) -> usize {}
    pub fn layout(self) -> crate::alloc::Layout {}
}

unsafe impl<Dyn: ?Sized> Send for DynMetadata<Dyn> {}
unsafe impl<Dyn: ?Sized> Sync for DynMetadata<Dyn> {}
impl<Dyn: ?Sized> Debug for DynMetadata<Dyn> {}
impl<Dyn: ?Sized> Unpin for DynMetadata<Dyn> {}
impl<Dyn: ?Sized> Copy for DynMetadata<Dyn> {}
impl<Dyn: ?Sized> Clone for DynMetadata<Dyn> {}
impl<Dyn: ?Sized> Eq for DynMetadata<Dyn> {}
impl<Dyn: ?Sized> PartialEq for DynMetadata<Dyn> {}
impl<Dyn: ?Sized> Ord for DynMetadata<Dyn> {}
impl<Dyn: ?Sized> PartialOrd for DynMetadata<Dyn> {}
impl<Dyn: ?Sized> Hash for DynMetadata<Dyn> {}

[matthieu-m]

After experimenting with custom implementations of Box, I think there is a strong case for having strongly typed meta-data for all kinds of pointers.

The pre-allocator representation of Box is:

struct Box<T: ?Sized> { ptr: NonNull<T>, }

The post-allocator representation is very similar:

struct Box<T: ?Sized, A: Allocator = Global> {
    allocator: A,
    ptr: NonNull<T>,
}

Both automatically implements CoerceUnsized<Box<U>> where T: Unsize<U>, and all is well.

If one wants to make Box generic over its storage, then the representation becomes:

pub struct RawBox<T: ?Sized + Pointee, S: SingleElementStorage> {
    storage: S,
    handle: S::Handle<T>,
}

If S::Handle<T> == NonNull<T>, then Box is still coercible; however, in the case of inline storage, that is:

• neither possible: when the Box is moved, so is the storage, and therefore any pointer into the storage is invalidated.
• nor desirable: in the case of inline storage, the pointer is redundant, wasting 8 bytes.

Hence, in the case of inline storage, S::Handle<T> is best defined as <T as Pointee>::Metadata.

In order to have Box<T> : CoerceUnsized<Box<U>> where T: Unsize<U>:

• We need: S::Handle<T>: CoerceUnsized<S::Handle<U>> where T: Unsize<U>,
• Which means: <T as Pointee>::Metadata: CoerceUnsized<<U as Pointee>::Metadata>> where T: Unsize<U>.

And of course, Box being coercible is very much desirable.

---

As a result, I believe a slight change of course is necessary:

1. All metadata should be strongly typed -- be it Metadata<dyn Debug>, Metadata<[u8]> or Metadata<[u8; 3]> -- no more () or usize.
2. The compiler should automatically implement Metadata<T>: CoerceUnsized<Metadata<U>> where T: Unsize<U>.

I would note that having a single Metadata<T> type rather than SizedMetadata<T>, SliceMetadata<[T]>, DynMetadata<dyn T> is not necessary, only the coercion is, and since the compiler is generating those, it's perfectly free to create them "cross type". I just used the same name as a short-cut.

---

Addendum: What's all that jazz about inline storage?

At a high-level, Box is not so much about where memory comes from, it's a container which allows:

• Dynamically Sized Types.
• And therefore Type Erasure.

Having the memory inline in the Box type preserves those 2 key properties whilst offering a self-contained type (not tied to any lifetime, nor any thread). It's allocation-less type-erasure.

A motivating example is therefore fn foo<T>() -> Box<dyn Future<T>, SomeInlineStorage>: it returns a stack-allocated container which contains any future type (fitting in the storage) which can evaluate to T.

[SimonSapin]

Box<dyn Future<T>, SomeInlineStorage> would have to be dynamically-sized itself, right? So in order to manipulate it without another lifetime or heap-allocated indirection you’d need the unsized locals language feature. And if you have that you can manipulate dyn Future<T> directly, so what’s the point of a box with inline storage?

IMO this is different from the case of Vec, which provides useful functionality on top of its storage so that ArrayVec (a.k.a. Vec with inline storage) makes sens. But Box pretty much is its storage.

[matthieu-m]

Box<dyn Future<T>, SomeInlineStorage> would have to be dynamically-sized itself, right?

No, that's the whole point of it actually.

In C++, you have std::string and std::function implementation typically using the "short string optimization", that is a sufficiently small payload is just embedded inside, and larger ones require a heap-allocation.

This is exactly the same principle:

• libstdc++'s std::string can contain up to 15 non-NUL characters without heap allocation on 64-bits platform.
• sizeof(std::string) == 24, regardless of whether it's empty, contains a single character, or contains 15.

So, here, SomeInlineStorage is generally speak over-reserving. You settle on a fixed alignment and size, and then you may get mem::size_of::<Box<dyn Future, SomeInlineStorage>>() == 128 regardless of what's stored inside.

If you stored a single pointer (+v-table), well, you're paying a bit too much, but that's the price for flexibility. It's up to you size it appropriately for the largest variant.

In any case, unsized locals is strictly unnecessary, as can be seen in the tests of storage-poc's RawBox.

[SimonSapin]

Oh I see, so this is more like SmallVec than ArrayVec and "inline" really means inline up to a certain size chosen a compile-time, and heap-allocated for values that turn out at run-time to be larger?

Back to pointer metadata though, I have a bit of a hard time following the CoerceUnsized discussion. But could you manage what you want if the handle for storage-generic Box<T> is not T::Metadata directly but another generic struct that contains that together with PhandomData<T>?

[matthieu-m]

Oh I see, so this is more like SmallVec than ArrayVec and "inline" really means inline up to a certain size chosen a compile-time, and heap-allocated for values that turn out at run-time to be larger?

It's up to you, you can have either a purely inline storage, or you can have "small" inline storage with heap fallback.

The main point is that the "inline" portion is always of fixed size and alignment (up to the storage) and therefore RawBox itself is always Sized.

(You can an equivalent of ArrayVec instantiated in this test-suite: RawVec<T, inline::SingleRange<...>>)

Back to pointer metadata though, I have a bit of a hard time following the CoerceUnsized discussion. But could you manage what you want if the handle for storage-generic Box<T> is not T::Metadata directly but another generic struct that contains that together with PhandomData<T>?

I don't think so, given the language from the documentation of CoerceUnsized:

For custom types, the coercion here works by coercing Foo<T> to Foo<U> provided an impl of CoerceUnsized<Foo<U>> for Foo<T> exists.

Such an impl can only be written if Foo<T> has only a single non-phantomdata field involving T.

If the type of that field is Bar<T>, an implementation of CoerceUnsized<Bar<U>> for Bar<T> must exist. The coercion will work by coercing the Bar<T> field into Bar<U> and filling in the rest of the fields from Foo<T> to create a Foo<U>. This will effectively drill down to a pointer field and coerce that.

It appears that PhantomData fields are ignored for the purpose of coercion.