Repository: rust
Issue: Tracking issue for dyn upcasting coercion
Labels: A-trait-system,T-lang,T-compiler,C-tracking-issue,disposition-merge,finished-final-comment-period,F-trait_upcasting,S-tracking-ready-to-stabilize,T-types

This is a tracking issue for [RFC3324](https://github.com/rust-lang/rfcs/pull/3324). Corresponding [MCP](https://github.com/rust-lang/lang-team/issues/98) is here.
The feature gate for the issue is `#![feature(trait_upcasting)]`.

### STATUS UPDATE

#### We are in the process of stabilizing.

### 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

- [x] Implement the experimental feature behind a feature gate.
- [x] Define the semantics explicitly.
- [x] Gathering design docs into initiative repo: https://github.com/rust-lang/dyn-upcasting-coercion-initiative
- [x] Adjust documentation ([see instructions on rustc-dev-guide][doc-guide]) https://github.com/rust-lang/reference/pull/1259
- [x] Gather data about memory usage? https://github.com/rust-lang/rust/issues/112355
- [x] Stabilization PR ([see instructions on rustc-dev-guide][stabilization-guide]) ~~https://github.com/rust-lang/rust/pull/101718~~, https://github.com/rust-lang/rust/pull/118133
- [x] Fix soundness problems.
  - https://github.com/rust-lang/rust/pull/120248
- [ ] Restabilize.

### Previous discussions
* RFC401: https://github.com/rust-lang/rfcs/pull/401
* RFC982: https://github.com/rust-lang/rfcs/pull/982
* RFC-issue2765: https://github.com/rust-lang/rfcs/issues/2765
* MCP: https://github.com/rust-lang/lang-team/issues/98 (Current lang-team MCP)
* Initiative: [Dyn upcasting coercion initiative](https://github.com/rust-lang/dyn-upcasting-coercion-initiative)
* RFC: https://github.com/rust-lang/rfcs/pull/3324

### Unresolved Questions
* ~~Currently `CoerceUnsized` trait cannot express this case: a smart pointers that wrap a raw pointer and don't guarantee via a custom invariant that it is valid. Maybe a separate `CoerceUnsizedUnsafe` trait is needed. (see https://github.com/rust-lang/rust/pull/88010#issuecomment-898893209).~~
* Should we make upcasting opt-in in some form to limit vtable size by default? The current inclination of the lang-team is "no", but it would be useful to gather data on how much supporting upcasting contributors to overall binary size.
* ~~Before stabilizing it we should check that libs-api is ok with upcasting for all dyn-allowed traits in the library, since those we can't change.~~ (addressed by https://github.com/rust-lang/rust/issues/65991#issuecomment-1369970129)
* Should we add an *opt-out* mechanism, and extend library stabilization checklist with "do we want to opt-out for now"?

### Implementation history
* Initial attempt: #60900
* Second attempt:
  * [X] Preparation refactoring: #86291
  * [X] Unify vtable building: #86475
  * [x] Update vtable format: #86461
  * [x] Feature gate implementation: #86264
  * [x] Pointer conversion adjustments: #87515
  * [x] Support multiple occurrence of a target trait with different substsdefs: #88135
  * [x] ~~Unsafety checking for raw dyn pointers: #88010 (not prefered approach, likely will need to do nothing here, but need a design meeting discussion with lang-team)~~ Solution: https://rust-lang.zulipchat.com/#narrow/stream/326132-t-types.2Fmeetings/topic/meeting.202022-09-02.20planning/near/296826711, https://github.com/rust-lang/rust/issues/101336
  * [x] Lint for easing migration: https://github.com/rust-lang/rust/issues/89460
  * [x] Reference changes
    * [x] ~~https://github.com/rust-lang/reference/pull/1259~~
    * [ ] https://github.com/rust-lang/reference/pull/1622
  * [x] Mark this feature no longer incomplete and stablize: https://github.com/rust-lang/rust/pull/101718
  * [x] Make trait upcasting work with supertraits with fewer associated types: #114036