Stablize trait_upcasting feature

[crlf0710]

Closes #65991.
Closes #89460.

[crlf0710]

r? @nikomatsakis

[fee1-dead]

Note: FCP for unblocking upcasts at #101336.

[nikomatsakis]

@crlf0710 we need a stabilization report to propose FCP -- I think we can adapt the notes from #101336, however.

[crlf0710]

Stabilization report

This PR proposes the stablization of the dyn trait upcasting coercion feature, which is a long-wished-for feature since 2013, and tracked with the Dyn upcasting coercion initiative. The associated Reference PR in flight is
rust-lang/reference#1259.

We are stablizing a new kind of coercion, which is "upcasts" from a dyn Trait to its supertraits:

trait Foo {
    fn foo_method(&self);
}
trait Bar: Foo {
    fn bar_method(&self);
}

let x: &dyn Bar = /* ... */;
let y: &dyn Foo = x; // compiles

The key factor for these upcasts is that they require adjusting the vtable. The current implementation strategy is that the vtables for the Bar trait embed pointers to a Foo vtable within them:

+----------------------------+
| Bar vtable for some type T |
|----------------------------|
| Foo vtable                 | ----------> +------------------+
| foo_method                 | -----+      | Foo vtable for T |
| bar_method                 | --+  |      |------------------|
+----------------------------+   |  |      | foo_method       | ---+
                                 |  |      +------------------+    |
                                 |  |                              |
                                 |  +---> <T as Foo>::foo_method <-+
                                 v
                     <T as Bar>::bar_method
                 
(this diagram is only meant to convey the general idea of the vtable
 layout, and doesn't represent the exact offsets we would use etc;
 in fact, with the current implementation,
 the first supertrait is stored 'inline' and hence no load is required)

This way, given a &dyn Bar object, we convert its Bar vtable to the appropriate Foo vtable by loading the appropriate field.

For some examples of code patterns that this feature enables, see Integration with Any: You can give any trait object downcast ability by using Any as its supertrait and Aligning type-erased closure bounds: You can use &mut dyn Fn as if it's a &mut dyn FnMut.

[nikomatsakis]

@rfcbot fcp merge

Now that the FCP in #101336 has ended, I'm going to move to stabilize dyn upcasting. @crlf0710 has provided a stabilization report here.

[rfcbot]

Team member @nikomatsakis has proposed to merge this. The next step is review by the rest of the tagged team members:

• @cramertj
• @joshtriplett
• @nikomatsakis
• @pnkfelix
• @scottmcm

Concerns:

• doc-pr (Stablize trait_upcasting feature #101718 (comment))
• rfc (Stablize trait_upcasting feature #101718 (comment))

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[nikomatsakis]

@rfcbot concern doc-pr

I believe we need a PR against the reference describing when upcasts are allowed (it doesn't, I think, have to document the vtable layout or anything like that).

I'm not sure if the reference also talks at all about validity/unsafety invariants, though.

[nikomatsakis]

@rustbot label +I-types-nominated

I'm nominating this for @rust-lang/types visibility, however, to make sure we feel comfortable with this being stabilized from a type system perspective. It is implemented by extending the existing ability to "upcast" a &dyn T to &dyn U (e.g., from Foo + Send to Foo).

[crlf0710]

The Reference PR is at rust-lang/reference#1259, though admittedly the descriptions are pretty brief, only covered the major points... Let me know if the text needs any expansion :)

[joshtriplett]

@rfcbot concern rfc

This has been the subject of a great deal of discussion and iteration, and I really do think this should have an RFC before stabilization. I've been expecting that it would get an RFC.

[nikomatsakis]

Per discussion in the meeting, we're going to author an RFC for this change, so I'm canceling the FCP and closing the PR for now. @crlf0710 let's talk!

@rfcbot fcp cancel

[rfcbot]

@nikomatsakis proposal cancelled.

[nikomatsakis]

I think we should keep the reference PR open, but add a note.