Implement pin-project in pattern matching for &pin mut|const T

[frank-king]

This PR implements part of #130494. It supports pin-project in pattern matching for &pin mut|const T.

Pin-projection by field access (i.e. &pin mut|const place.field) is not fully supported yet since pinned-borrow is not ready (#135731).

CC @traviscross

[rustbot]

r? @compiler-errors

rustbot has assigned @compiler-errors.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[bors]

☔ The latest upstream changes (presumably #139996) made this pull request unmergeable. Please resolve the merge conflicts.

[rustbot]

Some changes occurred to the CTFE machinery

cc @RalfJung, @oli-obk, @lcnr

Some changes occurred in match checking

cc @Nadrieril

Some changes occurred in compiler/rustc_codegen_ssa

cc @WaffleLapkin

Some changes occurred in src/tools/clippy

cc @rust-lang/clippy

Some changes occurred to MIR optimizations

cc @rust-lang/wg-mir-opt

The Miri subtree was changed

cc @rust-lang/miri

Some changes occurred in compiler/rustc_monomorphize/src/partitioning/autodiff.rs

cc @ZuseZ4

rust-analyzer is developed in its own repository. If possible, consider making this change to rust-lang/rust-analyzer instead.

cc @rust-lang/rust-analyzer

Some changes occurred in exhaustiveness checking

cc @Nadrieril

Some changes occurred in match lowering

cc @Nadrieril

Some changes occurred to the CTFE / Miri interpreter

cc @rust-lang/miri

Some changes occurred in compiler/rustc_codegen_cranelift

cc @bjorn3

[Nadrieril]

It seems like you're implementing a sort of match ergonomics through &pin? What stage is this feature at?

I think pinnedness should be part of the binding mode instead of a separate notion. I haven't looked deeply yet but presumably this will raise questions similar to deref patterns and the recent match ergonomics changes.

cc @dianne

[dianne]

+1 to representing pinnedness as part of the binding mode.

Regarding match ergonomics interactions, I think we'll either want explicit &pin patterns too or logic for using & to match on pinned refs (sorry if that's planned already! I couldn't find it). Writing out the &s leading up to a binding enables making by-value bindings of Copy types; there's not a general way to do that in the pattern without explicit & patterns. Likewise, some patterns (such as bindings) don't automatically peel references from the scrutinee, so &pin could be useful there too.
The diagnostic pretty-printing for exhaustiveness checking uses the &pin const and &pin mut syntax in patterns; without explicit &pin const and &pin mut patterns, those might need adjusting.

Regarding deref patterns interactions, we'll probably also want pin ergonomics for deref patterns eventually. I don't think that'll be a problem, if I understand what Pin<Ptr> means (morally, their pointee's address not changing means calling Deref::deref on a Pin<Ptr> returns a reference that could be wrapped in a pin, right? I'm not too familiar with pinning). Edit: I did a bit more reading; that invariant does seem to exist, so pin-projection ergonomics for deref patterns should be fine conceptually (I think). Not sure how it'd look implementation-wise, since DerefMut wouldn't always work. We'd morally want something more like matching through Pin::as_deref_mut than matching through DerefMut::deref_mut. I'm thinking we could call <Ptr as DerefMut>::deref_mut(&mut pin.pinned) and trust that pinnedness in binding modes will keep everything safe.

[dianne]

Another ergonomics question: is there a way to get a non-pinned by-shared-ref binding when matching through &pin const T or &pin mut T if no intervening types implement Unpin? If I understand correctly, this PR would always result in &pin const bindings in that case. I'm not sure this is an issue (at least not one that needs to be designed around) but I think that's the one case where the binding could be either &pin const or &, so there's a slight awkwardness when the user wants a reference and has to use &* or Pin::get_ref.

[frank-king]

Regarding match ergonomics interactions, I think we'll either want explicit &pin patterns too or logic for using & to match on pinned refs

Does "match ergonomics" refer to rfcs#2005? I see it has been stabilized in 2018, and I'm not quite familiar with "ancient" Rust before (I started to learn Rust in 2021).

My intuition is just based on the crate pin_project. Take an example from its doc:

use std::pin::Pin;
use pin_project::pin_project;

#[pin_project(project = EnumProj)]
enum Enum<T, U> {
    Pinned(#[pin] T),
    Unpinned(U),
}

impl<T, U> Enum<T, U> {
    fn method(self: Pin<&mut Self>) {
        match self.project() {
            EnumProj::Pinned(x) => {
                let _: Pin<&mut T> = x;
            }
            EnumProj::Unpinned(y) = {
                let _: &mut U = y;
            }
        }
    }
}

It uses the #[pin] attribute to determine whether to project a field to a pinned reference Pin<&{mut} T> or a normal reference &{mut} T. That's because the proc-macro doesn't know whether such a field is Unpin. However, rustc knows it (from the U: Unpin trait bound, I think), so we can leverage such information to determine whether to project to a pinned reference or a normal reference. (That may conflict with your words "expected might not be inferred at this point; it's often not known until unifying it with the pattern's type" in #139751 (comment), and please correct me if I'm wrong)

With pin_ergonomics enabled, I expect it to be:

#![feature(pin_ergonomics)]

enum Enum<T, U> {
    // `#[pin]` is no longer needed, as we can infer from the trait bound whether `T` is `Unpin`.
    Pinned(T),
    Unpinned(U),
}

// `U: Unpin` is needed to inform the compiler that `U` can be projected to a normal reference.
impl<T, U: Unpin> Enum<T, U> {
    fn method(&pin mut self) {
        // `self.projection()` is no longer needed, as the compiler
       // would understand how to project a `&pin mut Enum<T, U>`
        match self {
            // `EnumProj` is no longer needed
            Enum::Pinned(x) => {
                // for `T: ?Unpin`, it is projected to `&pin mut T`
                let _: &pin mut T = x;
            }
            Enum::Unpinned(y) = {
                // for `U: Unpin`, it is projected to `&mut U`
                let _: &mut U = y;
            }
        }
    } 
}

That's how I implemented this PR.

[dianne]

Does "match ergonomics" refer to rfcs#2005? I see it has been stabilized in 2018, and I'm not quite familiar with "ancient" Rust before (I started to learn Rust in 2021).

That RFC is indeed pretty old, and isn't quite what's implemented in Rust 2024¹. I'm using "match ergonomics" loosely to mean a couple things (sorry for the jargon!):

• The ability to omit explicit reference patterns when matching on reference types; this allows binding by reference without explicit binding mode annotations. As I understand it, that is what this PR implements (with the addition of by-pinned-reference bindings).
• The ability to add explicit reference patterns to bind Copy types by-value. Currently in Rust 2024, this requires explicitly writing out all reference patterns leading up to a binding. Tracking Issue for match ergonomics 2024 (RFC 3627) #123076 is tracking changes to allow more flexibility with where reference patterns are written, for more "ergonomic" control of the binding mode.

From what I could tell, this PR supports the former of these but not the latter; for consistency with how matching on normal references works, I'd expect to be able to use explicit reference patterns to match on &pin (const|mut) T as well. Plus, that syntax is used (I think) by the match exhaustiveness diagnostics this PR implements for pinned refs, and I'd expect any patterns it outputs to be writable by users too.

However, rustc knows it (from the U: Unpin trait bound, I think), so we can leverage such information to determine whether to project to a pinned reference or a normal reference. (That may conflict with your words "expected might not be inferred at this point; it's often not known until unifying it with the pattern's type" in #139751 (comment), and please correct me if I'm wrong)

It should indeed be possible to utilize the U: Unpin trait bound, and at least as far as I can tell, that does seem like the smoothest way to do it from a user-facing perspective². The tricky thing I was referring to is if you're matching on something that doesn't have a fully specified type at the point you're matching on it, rust's type-checker will try to infer the type from the patterns you use. However, it doesn't know what type the pattern has until the big match on the pattern's kind field. In this case, expected will be an unknown "inference variable" (or have inference variables in it) at the point you ask whether it's Unpin, which (in this specific case of expected being uninferred) will always conservatively return false even if you'll later learn that expected is Unpin once you learn the pattern's type.

There might be additional subtleties/complications I'm not aware of, of course. I'm not deeply familiar with the trait solver, so I'm not totally sure how unambiguous you can guarantee its results to be. Hence my suggestion to raise an error when there's ambiguities.

Footnotes

1. Rust 2024's current match ergonomics for references is specified in Tracking issue for Rust 2024: Match ergonomics rules 1C/2C #131414 (edit: also the edition guide as pointed out below). This was designed to be future-compatible with Tracking Issue for match ergonomics 2024 (RFC 3627) #123076 but easier to stabilize in time for the edition. ↩

2. The one gotcha I can think of besides what I said before is that if you have a type parameter T, you have to assume it's not Unpin when type-checking, but if you perform automatic source code transformations to substitute in a type that is Unpin, it can result in changes in the pinnedness of bindings, which can cause type errors. Thus substituting in a specific type for a type parameter at the source code level would no longer be a well-typedness-preserving operation. But I'm not sure there's really a way around that other than requiring explicit annotations. Tracking Issue for match ergonomics 2024 (RFC 3627) #123076 has a similar issue when trying to get it working on pre-2024 Editions in a backwards-compatible way. ↩

[traviscross]

2. The one gotcha I can think of besides what I said before is that if you have a type parameter T, you have to assume it's not Unpin when type-checking, but if you perform automatic source code transformations to substitute in a type that is Unpin, it can result in changes in the pinnedness of bindings, which can cause type errors. Thus substituting in a specific type for a type parameter at the source code level would no longer be a well-typedness-preserving operation.

This already isn't true of Rust due to the behavior of method resolution. E.g.:

Playground link

[frank-king]

• The ability to add explicit reference patterns to bind Copy types by-value.

Do you mean something like this?

fn f<T: Unpin + Copy>(x: &pin mut T, y: &mut T) {
    let &pin mut _x = x; // gets `_x: T`
    let &mut _y = y; // like this, which gets `_y: T`
}

I think that could be possible and could be implemented in the next PRs (it's an independent feature and requires introducing extra syntax).

Plus, that syntax is used (I think) by the match exhaustiveness diagnostics this PR implements for pinned refs, and I'd expect any patterns it outputs to be writable by users too.

If you mind this inconsistency, I can revert this diagnostic syntax and reintroduce it later if any following PRs implement that feature.

[dianne]

• The ability to add explicit reference patterns to bind Copy types by-value.

Do you mean something like this?

Exactly, yeah! I imagine it'd work just like normal reference patterns in terms of where they can be used and how they affect binding by-ref, and it'd work just like implicitly matching on pinned refs in terms of how they affect pinnedness. Though I don't think it'd need an Unpin bound to copy out even for &pin mut, since it'd only need immutable access; morally it'd be like using Deref::deref. If Match Ergonomics 2024 (#123076) stabilizes, it might be worth allowing a bit more freedom with the syntax, but that's not something to worry about yet¹. &pin mut and &pin const patterns to match the syntax for pinned borrow seems good to me.

Plus, that syntax is used (I think) by the match exhaustiveness diagnostics this PR implements for pinned refs, and I'd expect any patterns it outputs to be writable by users too.

If you mind this inconsistency, I can revert this diagnostic syntax and reintroduce it later if any following PRs implement that feature.

I don't personally mind temporary diagnostic inconsistencies for in-development features (but I'm also not a compiler team member, so take whatever I say with a grain of salt). Either way, a // FIXME(pin_ergonomics) reminder comment on print_witness_pat could be helpful to make sure it's addressed later.

Speaking of exhaustiveness, could you add tests for that? Maybe one for non-exhaustive patterns, one for unreachable patterns, and one featuring matches with both pin ergonomics and Pin { .. } constructor patterns to make sure the special-casing to treat them the same works. In particular, I'm a bit worried that using the Ref constructor for both (rather than the Struct constructor, like box patterns currently do to handle Box { .. }) will cause some fallout in places where Ref is assumed to have a field (which isn't present for Pin { .. }). I'll make an inline review comment to elaborate on this.

Oh, and speaking of tests, could you add some for closures that implicitly match on pinned refs as well? In particular, if you move away from allowing builtin derefs on pinned refs, there'll need to be special handling in expr_use_visitor::cat_pattern to deref pinned refs (i.e. it should work the same as the MIR lowering), so that'll need testing too.

Footnotes

1. e.g., Match Ergonomics 2024 would allow using & patterns to match on &mut references. In a future with both features, I think it'd be most consistent (and substantially less typing for users) to figure out shorthand for matching on pinned references too. ↩

[dianne]

For pin to appear in a PatKind::Deref, I think pin_ergonomics would have to be enabled, so perhaps this should (debug) assert that it's enabled rather than check it. That said, if you're not using built-in derefs, I think patterns on pinned refs shouldn't be represented by PatKind::Deref. If you haven't already made this change, I think a PatKind::Leaf pattern with a PatKind::Deref field might make things work, both here and in MIR lowering? Though there may be a reason I haven't thought of to introduce a new PatKind.
Per #139751 (comment), if you decide to represent derefs of pinned refs like deref patterns, giving it the same representation in THIR as Pin { .. } patterns won't work; I'd suggest making a new PatKind (or at least adding a distinguishing field to PatKind::Deref so there's not a "gotcha" if you forget to check the pointer type when figuring out how to interpret a deref; my personal preference would be a new PatKind, but I could be convinced otherwise).

[frank-king]

Now this code seems to be unreachable because &pin becomes PatKind::RefPin instead of PatKind::Deref.

[bors]

☔ The latest upstream changes (presumably #137940) made this pull request unmergeable. Please resolve the merge conflicts.

[frank-king]

Thanks @RalfJung, @dianne, @Nadrieril, and @traviscross for your helpful review!

I try to summarise your suggestions before adjusting my implementation, ensuring that I don't make any mistakes or miss anything important (and pls correct me or complete me if that happens).

1. Making builtin_deref depend on tcx.features() can be problematic if behaviours differ across crates¹. This can be avoided by turning place_builder.deref() to place_builder.field(FieldIdx(0), ref_ty).deref()².
2. Pinnedness should be part of the binding mode³⁴. (P.S., I didn't put pinnedness into part of the binding mode because it may affect a lot of codes, see also Parse pinned local variable declarations #135631 for those code changes.)
3. pin automatically swapped out when T: Unpin is unergonomic. &pin references should always be bonded to &pin references, and the unpinned references should only be obtained by coercion⁵, or via a deref pattern⁶ (though not merged and not sharable yet).
4. Pin should not be a Ref(Pinnedness::Pinned) constructor, but should be a Struct constructor instead⁷⁸.
5. The pinned ref pattern cannot bind Copy types by value⁹. This will be planned in the next PRs.
6. The inconsistency that &pin syntax is used in match exhaustiveness diagnostics but cannot be written by users¹⁰. I will add a // FIXME comment and implement that later.
7. More tests: closures that implicitly match on pinned refs¹¹, and it seems that I also have to add some match exhaustiveness checks when Pin { .. } and the inner struct pattern are used mixedly¹².
8. For pin to appear in PatKind::Deref, pin_ergonomics would have to be enabled, and thus this feature should be (debug) assert instead of checked¹³.

Footnotes

1. https://github.com/rust-lang/rust/pull/139751#discussion_r2053808204 ↩

2. https://github.com/rust-lang/rust/pull/139751#discussion_r2057975095 ↩

3. https://github.com/rust-lang/rust/pull/139751#issuecomment-2825761371 ↩

4. https://github.com/rust-lang/rust/pull/139751#issuecomment-2825950996 ↩

5. https://github.com/rust-lang/rust/pull/139751#discussion_r2061229541 ↩

6. https://github.com/rust-lang/rust/pull/139751#discussion_r2062626644 ↩

7. https://github.com/rust-lang/rust/pull/139751#discussion_r2062347490 ↩

8. https://github.com/rust-lang/rust/pull/139751#discussion_r2062626644 ↩

9. https://github.com/rust-lang/rust/pull/139751#issuecomment-2831822361 ↩

10. https://github.com/rust-lang/rust/pull/139751#issuecomment-2831822361 ↩

11. https://github.com/rust-lang/rust/pull/139751#issuecomment-2831822361 ↩

12. https://github.com/rust-lang/rust/pull/139751#discussion_r2062608043 ↩

13. https://github.com/rust-lang/rust/pull/139751#discussion_r2062359722 ↩

[dianne]

Making builtin_deref depend on tcx.features() can be problematic if behaviours differ across crates. This can be avoided by turning place_builder.deref() to place_builder.field(FieldIdx(0), ref_ty).deref().

One note here, just to clarify in case I didn't give enough context: this is specifically referring to MatchPairTree::for_pattern, assuming place_builder represents the place of the Pin being matched through. This only applies if you have a THIR pattern kind corresponding to matching through a pinned ref¹. If in THIR you instead use a Leaf and Deref pattern together (a field access followed by a builtin deref), you won't need to add anything new to MatchPairTree::for_pattern. But on account of #139751 (comment), I think it'd probably be best to have a single distinct PatKind for matching through pinned refs, rather than using the same representation as Pin { .. } constructors².

Either way, you'll also need to adjust ExprUseVisitor::cat_pattern to also get the right place when matching through a pinned ref. And you'll probably want to add a new variant to PatAdjust to represent matching through pinned refs, since it's handled differently from both deref patterns and builtin derefs.

P.S., I didn't put pinnedness into part of the binding mode because it may affect a lot of codes, see also Parse pinned local variable declarations #135631 for those code changes.

I'm not sure how the final version of this should look, but would it make sense just to have TypeckResults's pat_binding_modes table contain both a BindingMode and a Pinnedness rather than only a BindingMode? That'd require fewer changes to existing code than changing BindingMode itself, but wouldn't require introducing a new table that'd need checking/updating when dealing with bindings.

pin automatically swapped out when T: Unpin is unergonomic. &pin references should always be bonded to &pin references, and the unpinned references should only be obtained by coercion, or via a deref pattern.

Pin should not be a Ref(Pinnedness::Pinned) constructor, but should be a Struct constructor instead.

My suggestion regarding deref patterns is that matching through pinned refs could be represented in exhaustiveness analysis with a DerefPattern(_) constructor (i.e. not a Struct constructor; see #139751 (comment) for why I was wrong about that suggestion). I don't think they should be the way to get unpinned references. Sorry for the confusion! I agree with TC about getting unpinned references through coercion.

Footnotes

1. This applies to the PR as it is currently, since thir::PatKind::Deref is used to represent matching through a pinned ref. I'm unsure about overloading PatKind::Deref to mean both builtin derefs and derefs through pinned refs, though. It feels like it could be a bit of a hazard for code that assumes it'll always do a builtin deref. So I'd encourage adding your own PatKind variant (but I'm not sure what the preferences of anyone on T-compiler would be). ↩

2. This is so that exhaustiveness analysis can tell "matching through a pinned ref" apart from uses of Pin { .. } constructor patterns. They should be treated distinctly because Pin's field is private. ↩

[traviscross]

2. Pinnedness should be part of the binding mode34. (P.S., I didn't put pinnedness into part of the binding mode because it may affect a lot of codes, see also Parse pinned local variable declarations #135631 for those code changes.)

Note that what caused us to NAK that PR is that it implemented this behavior:

fn f() {
    let pin mut x = ();
    let _: () = x;
}

More likely than not, we're not going to want that. What we do likely want, though, is:

fn f() {
    let ref pin mut x = ();
    let _: &pin mut () = x;
}

[rustbot]

Some changes occurred in src/tools/rustfmt

cc @rust-lang/rustfmt

[frank-king]

I have adjusted my implementation according to my summary and @dianne's feedback, but I'm still confused about the pattern analysis part.

I got some basic knowledge from Pattern and Exhaustiveness Checking in rustc-dev-guide and Match exhaustiveness and redundancy algorithm from the in-crate docs, but I'm not sure if adding a Constructor::RefPin and ConstructorSet::RefPin could make sense.

I still feel that &pin is quite similar to the &(Ref) in terms of PatKind or Constructor in my current implementation, and that is why I added a Pinnedness field to the Constructor::Ref in my last implementation.

The only difference I can tell is the case when Pin { .. } and &pin patterns appeared at the same time, like that in deref patterns (in #140106):

struct Foo<T, U>(T, U);
fn f<T, U>(foo: &pin mut Foo) {
    match foo {
        // This is lowered to `&pin Foo(ref pin mut x, ref pin mut y)` in THIR,
        // which (I think) is consistent with match ergonomics in edition 2024.
        Foo(x, y) => {},
        // This directly matches the `Pin` struct, which should be reported as
        // mixed usage of deref pattern ctors like in #140106.
        Pin { .. } => {},
    }
}

@traviscross @dianne @Nadrieril Do you have any comments or other ideas about the current implementation of the pattern analysis? (I marked this PR as draft in order not to disturb too many people, since there are still some works, like testing, to complete.)

[frank-king]

Now this code seems to be unreachable because &pin becomes PatKind::RefPin instead of PatKind::Deref.

[compiler-errors]

r? nadrieril perhaps