Continue Experimentation with Pin Ergonomics

[nikomatsakis]

Metadata
Point of contact	@frank-king
Team(s)	compiler, lang, types
Goal document	2026/pin-ergonomics

Summary

Continue experimenting with and fleshing out the design and semantics for the pin ergonomics experiment.

Tasks and status

---

Note: we have updated the body to match the 2026 goal. Your original text is preserved below.

Details

Metadata
Point of contact	@frank-king
Team(s)	compiler, lang
Goal document	2025h2/pin-ergonomics

Summary

Continue experimenting with and fleshing out the design and semantics for the pin ergonomics experiment.

Tasks and status

• Implementation (@frank-king)
• Standard reviews (compiler )
• Design meeting (lang )
• Author call for testing blog post (@frank-king)

[nikomatsakis]

This issue is intended for status updates only.

For general questions or comments, please contact the owner(s) directly.

[frank-king]

Status update:

Regarding the TODO list in the next 6 months, here is the current status:

Introduce &pin mut|const place borrowing syntax

• parsing: #135731, merged.
• lowering and borrowck: not started yet.

I've got some primitive ideas about borrowck, and I probably need to confirm with someone who is familiar with MIR/borrowck before starting to implement.

A pinned borrow consists two MIR statements:

1. a borrow statement that creates the mutable reference,
2. and an adt aggregate statement that put the mutable reference into the Pin struct.

I may have to add a new borrow kind so that pinned borrows can be recognized. Then traverse the dataflow graph to make sure that pinned places cannot been moved.

Pattern matching of &pin mut|const T types

In the past few months, I have struggled with the !Unpin stuffs (the original design sketch Alternative A), trying implementing it, refactoring, discussing on zulips, and was constantly confused; luckily, we have finally reached a new agreement of the Alternative B version.

• #139751 under review (reimplemented regarding Alternative B).

Support drop(&pin mut self) for structually pinned types

• adding a new Drop::pin_drop(&pin mut self) method: draft PR #144537

Supporting both Drop::drop(&mut self) and Drop::drop(&pin mut self) seems to introduce method-overloading to Rust, which I think might need some more general ways to handle (maybe by a rustc attribute?). So instead, I'd like to implemenent this via a new method Drop::pin_drop(&pin mut self) first.

Introduce &pin pat pattern syntax

Not started yet (I'd prefer doing that when pattern matching of &pin mut|const T types is ready).

Support &pin mut|const T -> &|&mut T coercion (requires T: Unpin of &pin mut T -> &mut T)

Not started yet. (It's quite independent, probably someone else can help with it)

Support auto borrowing of &pin mut|const place in method calls with &pin mut|const self receivers

Seems to be handled by Autoreborrow traits?

[frank-king]

Status update:

• pattern matching support of &pin const|mut T types, merged.
• &pin pattern and ref pin mut binding mode, merged.
• Drop::pin_drop, waiting for review (new updates since the last review).
  • Unresolved question: the current implementation requires changing the src/docs/book submodule, but the top repo and the sub repo must be changed together to pass the CI tests in both repos. It's because a default body is added to Drop::drop and it becomes a provided method instead of a required method in rustdoc. Is there any way to avoid that? (Possibly keep rustdoc treating Drop::drop as a required method?)
• coercion between &pin const|mut T and &{mut} T, waiting for review (fresh).

[frank-king]

• Key developments: forbid manual impl of Unpin for #[pin_v2] types.

• Blockers: PRs waiting for review:

  • impl Drop::pin_drop (the submodule issue)
  • coercion of &pin mut|const T <-> &[mut] T

• Help wanted: None yet.

[frank-king]

(Just come back from the Spring Festival)

• In development:
  • (locally, no PR yet): design and implement the borrow checking algorithms of &pin
  • Add Drop::pin_drop for pinned drops rust#144537, reviewed, to update the submodule book
  • Implement coercions between &pin (mut|const) T and &(mut) T when T: Unpin rust#149130, reviewed, to do some refactors according to the reviewed messages.

[frank-king]

• Key developments:
  • Implement coercions between &pin (mut|const) T and &(mut) T when T: Unpin rust#149130, coercion support of &pin T types, merged.
  • Implement borrowck for &pin mut|const $place rust#153693, borrow check of &pin place borrows, draft PR opened. The implementation needs to be refined and self-reviewed before the community reviews.
• Help wanted:
  • Add Drop::pin_drop for pinned drops rust#144537. I failed to reproduce the CI errors locally. Hopefully, someone can help explain where (in which file) the links break

reference/print.html:42240: broken link fragment `#tymethod.drop` pointing to `core/ops/drop/trait.Drop.html`
reference/destructors.html:201: broken link fragment `#tymethod.drop` pointing to `core/ops/drop/trait.Drop.html`

[frank-king]

• Key developments:
  • Implement borrowck for &pin mut|const $place rust#153693, self-reviewed, and found that the current approach of handling pinned borrows may be incorrect, as it failed to distinguish a pinned borrow from a coercion of a normal-to-pinned reference. The latter doesn't prevent a T: Unpin type from being moved, but the former does, which breaks the pin coercion test.
• Help wanted: same as last month.