Tracking issue for pin ergonomics

This is a tracking issue for work on pin ergonomics.

The feature gate for the issue is #![feature(pin_ergonomics)].

Design sketch

The basic pin projection rules that we're working toward are:

Alternative B:

• If T: Unpin, &pin mut T and &mut T coerce to each other.
• If a struct, enum, or union(?) defining a type T is annotated with #[pin_v2] (todo bikeshedding), then:
  • Projection of &pin mut T to &pin mut T.U is allowed.
  • If T: Drop , the Drop impl must use fn drop(&pin mut self).
  • No manual impls of Unpin are allowed on T.
  • The user must ensure that, given a pinned reference to T, the pinning contract is upheld for all ?Unpin fields of T.

(The rules apply likewise for &pin const T.)

Beyond pin projection, the basic overall idea of pin ergonomics is that &pin mut T (and &pin const T) should be integrated in the same sense as &mut T, in that reborrowing works, autoref works, corresponding binding modes exist, and that the borrow checker will track and ensure that once a &pin mut T is taken (even if no longer live) that we can't later get a &mut T or move T.

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

• Approve as lang experiment.
  • We accepted this experiment in the 2024-09-18 lang triage meeting.
• Accept an RFC.
• Implement pin reborrowing in nightly.
  • https://github.com/rust-lang/rust/pull/130526
  • https://github.com/rust-lang/rust/pull/130633
• Implement pin autoref in nightly.
• Implement &pin const / &pin mut constructor syntax in nightly.
  • https://github.com/rust-lang/rust/pull/135731
• Implement &pin const / &pin mut type syntax in nightly.
  • https://github.com/rust-lang/rust/pull/130635
• Implement &pin const self / &pin mut self argument syntax in nightly.
  • https://github.com/rust-lang/rust/pull/135733
• Implement pin projection in pattern matching in nightly.
  • https://github.com/rust-lang/rust/pull/139751
• Implement fn drop(&pin mut self).
• Require fn drop(&pin mut self) when T: Drop + !Unpin.
• Implement coercions between &pin (mut|const) T and &(mut) T when T: Unpin.
• Add ForceUnpin<T> type.
• Investigate affordances for unsafe parts of the Pin API.
• Add documentation to the dev guide.
  • See the instructions.
• Add documentation to the reference.
  • See the instructions.
• Add formatting for new syntax to the style guide.
  • See the nightly style procedure.
• Stabilize.
  • See the instructions.

Unresolved Questions

• Apparently this gives special semantics to the Unpin trait (at least, the compiler uses is_unpin checks in &pin handling). That is a safe trait and hence cannot be deeply semantically meaningful. Is this coherent?

Related

TODO.

cc @eholk @rust-lang/lang