Tracking issue for `precise_capturing` syntax #123432

traviscross · 2024-04-03T22:09:44Z

This is a tracking issue for precise capturing of type and lifetime parameters in impl Trait opaque types.

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

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

Implementation history

cc @oli-obk @compiler-errors @rust-lang/style

The text was updated successfully, but these errors were encountered:

…=oli-obk Implement syntax for `impl Trait` to specify its captures explicitly (`feature(precise_capturing)`) Implements `impl use<'a, 'b, T, U> Sized` syntax that allows users to explicitly list the captured parameters for an opaque, rather than inferring it from the opaque's bounds (or capturing *all* lifetimes under 2024-edition capture rules). This allows us to exclude some implicit captures, so this syntax may be used as a migration strategy for changes due to rust-lang#117587. We represent this list of captured params as `PreciseCapturingArg` in AST and HIR, resolving them between `rustc_resolve` and `resolve_bound_vars`. Later on, we validate that the opaques only capture the parameters in this list. We artificially limit the feature to *require* mentioning all type and const parameters, since we don't currently have support for non-lifetime bivariant generics. This can be relaxed in the future. We also may need to limit this to require naming *all* lifetime parameters for RPITIT, since GATs have no variance. I have to investigate this. This can also be relaxed in the future. r? `@oli-obk` Tracking issue: - rust-lang#123432

Implement syntax for `impl Trait` to specify its captures explicitly (`feature(precise_capturing)`) Implements `impl use<'a, 'b, T, U> Sized` syntax that allows users to explicitly list the captured parameters for an opaque, rather than inferring it from the opaque's bounds (or capturing *all* lifetimes under 2024-edition capture rules). This allows us to exclude some implicit captures, so this syntax may be used as a migration strategy for changes due to #117587. We represent this list of captured params as `PreciseCapturingArg` in AST and HIR, resolving them between `rustc_resolve` and `resolve_bound_vars`. Later on, we validate that the opaques only capture the parameters in this list. We artificially limit the feature to *require* mentioning all type and const parameters, since we don't currently have support for non-lifetime bivariant generics. This can be relaxed in the future. We also may need to limit this to require naming *all* lifetime parameters for RPITIT, since GATs have no variance. I have to investigate this. This can also be relaxed in the future. r? `@oli-obk` Tracking issue: - rust-lang/rust#123432

…rustdoc, r=fmease Implement `precise_capturing` support for rustdoc Implements rustdoc (+json) support for local (i.e. non-cross-crate-inlined) RPITs with `use<...>` precise capturing syntax. Tests kinda suck. They're really hard to write 😰 r? `@fmease` or re-roll if you're too busy! also cc `@aDotInTheVoid` for the json side Tracking: * rust-lang#127228 (comment) (not fully fixed for cross-crate-inlined opaques) * rust-lang#123432

Rollup merge of rust-lang#127632 - compiler-errors:precise-capturing-rustdoc, r=fmease Implement `precise_capturing` support for rustdoc Implements rustdoc (+json) support for local (i.e. non-cross-crate-inlined) RPITs with `use<...>` precise capturing syntax. Tests kinda suck. They're really hard to write 😰 r? `@fmease` or re-roll if you're too busy! also cc `@aDotInTheVoid` for the json side Tracking: * rust-lang#127228 (comment) (not fully fixed for cross-crate-inlined opaques) * rust-lang#123432

…better-sugg-apit, r=oli-obk Fix precise capturing suggestion for hidden regions when we have APITs Suggests to turn APITs into type parameters so they can be named in precise capturing syntax for hidden type lifetime errors. We also note that it may change the API. This is currently done via a note *and* a suggestion, which feels a bit redundant, but I wasn't totally sure of a better alternative for the presentation. Code is kind of a mess but there's a lot of cases to consider. Happy to iterate on this if you think the approach is too messy. Based on rust-lang#127619, only the last commit is relevant. r? oli-obk Tracking: - rust-lang#123432

Rollup merge of rust-lang#127664 - compiler-errors:precise-capturing-better-sugg-apit, r=oli-obk Fix precise capturing suggestion for hidden regions when we have APITs Suggests to turn APITs into type parameters so they can be named in precise capturing syntax for hidden type lifetime errors. We also note that it may change the API. This is currently done via a note *and* a suggestion, which feels a bit redundant, but I wasn't totally sure of a better alternative for the presentation. Code is kind of a mess but there's a lot of cases to consider. Happy to iterate on this if you think the approach is too messy. Based on rust-lang#127619, only the last commit is relevant. r? oli-obk Tracking: - rust-lang#123432

…stdoc-cross, r=fmease Add cross-crate precise capturing support to rustdoc Follow-up to rust-lang#127632. Fixes rust-lang#127228. r? `@fmease` Tracking: * rust-lang#123432

…ss, r=fmease Add cross-crate precise capturing support to rustdoc Follow-up to #127632. Fixes #127228. r? `@fmease` Tracking: * rust-lang/rust#123432

The Reference didn't include any description of capturing or capturing behavior for `impl Trait` opaque types. Let's describe briefly what capturing is and what the currently-stable automatic capturing rules are. Then let's describe the syntax and behavior of RFC 3617 precise capturing. Precise capturing is currently undergoing stabilization in: - rust-lang/rust#127672 Tracking issue: - rust-lang/rust#123432

…=spastorino Stabilize opaque type precise capturing (RFC 3617) This PR partially stabilizes opaque type *precise capturing*, which was specified in [RFC 3617](rust-lang/rfcs#3617), and whose syntax was amended by FCP in [rust-lang#125836](rust-lang#125836). This feature, as stabilized here, gives us a way to explicitly specify the generic lifetime parameters that an RPIT-like opaque type captures. This solves the problem of overcapturing, for lifetime parameters in these opaque types, and will allow the Lifetime Capture Rules 2024 ([RFC 3498](rust-lang/rfcs#3498)) to be fully stabilized for RPIT in Rust 2024. ### What are we stabilizing? This PR stabilizes the use of a `use<'a, T>` bound in return-position impl Trait opaque types. Such a bound fully specifies the set of generic parameters captured by the RPIT opaque type, entirely overriding the implicit default behavior. E.g.: ```rust fn does_not_capture<'a, 'b>() -> impl Sized + use<'a> {} // ~~~~~~~~~~~~~~~~~~~~ // This RPIT opaque type does not capture `'b`. ``` The way we would suggest thinking of `impl Trait` types *without* an explicit `use<..>` bound is that the `use<..>` bound has been *elided*, and that the bound is filled in automatically by the compiler according to the edition-specific capture rules. All non-`'static` lifetime parameters, named (i.e. non-APIT) type parameters, and const parameters in scope are valid to name, including an elided lifetime if such a lifetime would also be valid in an outlives bound, e.g.: ```rust fn elided(x: &u8) -> impl Sized + use<'_> { x } ``` Lifetimes must be listed before type and const parameters, but otherwise the ordering is not relevant to the `use<..>` bound. Captured parameters may not be duplicated. For now, only one `use<..>` bound may appear in a bounds list. It may appear anywhere within the bounds list. ### How does this differ from the RFC? This stabilization differs from the RFC in one respect: the RFC originally specified `use<'a, T>` as syntactically part of the RPIT type itself, e.g.: ```rust fn capture<'a>() -> impl use<'a> Sized {} ``` However, settling on the final syntax was left as an open question. T-lang later decided via FCP in [rust-lang#125836](rust-lang#125836) to treat `use<..>` as a syntactic bound instead, e.g.: ```rust fn capture<'a>() -> impl Sized + use<'a> {} ``` ### What aren't we stabilizing? The key goal of this PR is to stabilize the parts of *precise capturing* that are needed to enable the migration to Rust 2024. There are some capabilities of *precise capturing* that the RFC specifies but that we're not stabilizing here, as these require further work on the type system. We hope to lift these limitations later. The limitations that are part of this PR were specified in the [RFC's stabilization strategy](https://rust-lang.github.io/rfcs/3617-precise-capturing.html#stabilization-strategy). #### Not capturing type or const parameters The RFC addresses the overcapturing of type and const parameters; that is, it allows for them to not be captured in opaque types. We're not stabilizing that in this PR. Since all in scope generic type and const parameters are implicitly captured in all editions, this is not needed for the migration to Rust 2024. For now, when using `use<..>`, all in scope type and const parameters must be nameable (i.e., APIT cannot be used) and included as arguments. For example, this is an error because `T` is in scope and not included as an argument: ```rust fn test<T>() -> impl Sized + use<> {} //~^ ERROR `impl Trait` must mention all type parameters in scope in `use<...>` ``` This is due to certain current limitations in the type system related to how generic parameters are represented as captured (i.e. bivariance) and how inference operates. We hope to relax this in the future, and this stabilization is forward compatible with doing so. #### Precise capturing for return-position impl Trait **in trait** (RPITIT) The RFC specifies precise capturing for RPITIT. We're not stabilizing that in this PR. Since RPITIT already adheres to the Lifetime Capture Rules 2024, this isn't needed for the migration to Rust 2024. The effect of this is that the anonymous associated types created by RPITITs must continue to capture all of the lifetime parameters in scope, e.g.: ```rust trait Foo<'a> { fn test() -> impl Sized + use<Self>; //~^ ERROR `use<...>` precise capturing syntax is currently not allowed in return-position `impl Trait` in traits } ``` To allow this involves a meaningful amount of type system work related to adding variance to GATs or reworking how generics are represented in RPITITs. We plan to do this work separately from the stabilization. See: - rust-lang#124029 Supporting precise capturing for RPITIT will also require us to implement a new algorithm for detecting refining capture behavior. This may involve looking through type parameters to detect cases where the impl Trait type in an implementation captures fewer lifetimes than the corresponding RPITIT in the trait definition, e.g.: ```rust trait Foo { fn rpit() -> impl Sized + use<Self>; } impl<'a> Foo for &'a () { // This is "refining" due to not capturing `'a` which // is implied by the trait's `use<Self>`. fn rpit() -> impl Sized + use<>; // This is not "refining". fn rpit() -> impl Sized + use<'a>; } ``` This stabilization is forward compatible with adding support for this later. ### The technical details This bound is purely syntactical and does not lower to a [`Clause`](https://doc.rust-lang.org/1.79.0/nightly-rustc/rustc_middle/ty/type.ClauseKind.html) in the type system. For the purposes of the type system (and for the types team's curiosity regarding this stabilization), we have no current need to represent this as a `ClauseKind`. Since opaques already capture a variable set of lifetimes depending on edition and their syntactical position (e.g. RPIT vs RPITIT), a `use<..>` bound is just a way to explicitly rather than implicitly specify that set of lifetimes, and this only affects opaque type lowering from AST to HIR. ### FCP plan While there's much discussion of the type system here, the feature in this PR is implemented internally as a transformation that happens before lowering to the type system layer. We already support impl Trait types partially capturing the in scope lifetimes; we just currently only expose that implicitly. So, in my (errs's) view as a types team member, there's nothing for types to weigh in on here with respect to the implementation being stabilized, and I'd suggest a lang-only proposed FCP (though we'll of course CC the team below). ### Authorship and acknowledgments This stabilization report was coauthored by compiler-errors and TC. TC would like to acknowledge the outstanding and speedy work that compiler-errors has done to make this feature happen. compiler-errors thanks TC for authoring the RFC, for all of his involvement in this feature's development, and pushing the Rust 2024 edition forward. ### Open items We're doing some things in parallel here. In signaling the intention to stabilize, we want to uncover any latent issues so we can be sure they get addressed. We want to give the maximum time for discussion here to happen by starting it while other remaining miscellaneous work proceeds. That work includes: - [x] Look into `syn` support. - dtolnay/syn#1677 - dtolnay/syn#1707 - [x] Look into `rustfmt` support. - rust-lang#126754 - [x] Look into `rust-analyzer` support. - rust-lang/rust-analyzer#17598 - rust-lang/rust-analyzer#17676 - [x] Look into `rustdoc` support. - rust-lang#127228 - rust-lang#127632 - rust-lang#127658 - [x] Suggest this feature to RfL (a known nightly user). - [x] Add a chapter to the edition guide. - rust-lang/edition-guide#316 - [x] Update the Reference. - rust-lang/reference#1577 ### (Selected) implementation history * rust-lang/rfcs#3498 * rust-lang/rfcs#3617 * rust-lang#123468 * rust-lang#125836 * rust-lang#126049 * rust-lang#126753 Closes rust-lang#123432. cc `@rust-lang/lang` `@rust-lang/types` `@rustbot` labels +T-lang +I-lang-nominated +A-impl-trait +F-precise_capturing Tracking: - rust-lang#123432 ---- For the compiler reviewer, I'll leave some inline comments about diagnostics fallout :^) r? compiler

Stabilize opaque type precise capturing (RFC 3617) This PR partially stabilizes opaque type *precise capturing*, which was specified in [RFC 3617](rust-lang/rfcs#3617), and whose syntax was amended by FCP in [#125836](rust-lang/rust#125836). This feature, as stabilized here, gives us a way to explicitly specify the generic lifetime parameters that an RPIT-like opaque type captures. This solves the problem of overcapturing, for lifetime parameters in these opaque types, and will allow the Lifetime Capture Rules 2024 ([RFC 3498](rust-lang/rfcs#3498)) to be fully stabilized for RPIT in Rust 2024. ### What are we stabilizing? This PR stabilizes the use of a `use<'a, T>` bound in return-position impl Trait opaque types. Such a bound fully specifies the set of generic parameters captured by the RPIT opaque type, entirely overriding the implicit default behavior. E.g.: ```rust fn does_not_capture<'a, 'b>() -> impl Sized + use<'a> {} // ~~~~~~~~~~~~~~~~~~~~ // This RPIT opaque type does not capture `'b`. ``` The way we would suggest thinking of `impl Trait` types *without* an explicit `use<..>` bound is that the `use<..>` bound has been *elided*, and that the bound is filled in automatically by the compiler according to the edition-specific capture rules. All non-`'static` lifetime parameters, named (i.e. non-APIT) type parameters, and const parameters in scope are valid to name, including an elided lifetime if such a lifetime would also be valid in an outlives bound, e.g.: ```rust fn elided(x: &u8) -> impl Sized + use<'_> { x } ``` Lifetimes must be listed before type and const parameters, but otherwise the ordering is not relevant to the `use<..>` bound. Captured parameters may not be duplicated. For now, only one `use<..>` bound may appear in a bounds list. It may appear anywhere within the bounds list. ### How does this differ from the RFC? This stabilization differs from the RFC in one respect: the RFC originally specified `use<'a, T>` as syntactically part of the RPIT type itself, e.g.: ```rust fn capture<'a>() -> impl use<'a> Sized {} ``` However, settling on the final syntax was left as an open question. T-lang later decided via FCP in [#125836](rust-lang/rust#125836) to treat `use<..>` as a syntactic bound instead, e.g.: ```rust fn capture<'a>() -> impl Sized + use<'a> {} ``` ### What aren't we stabilizing? The key goal of this PR is to stabilize the parts of *precise capturing* that are needed to enable the migration to Rust 2024. There are some capabilities of *precise capturing* that the RFC specifies but that we're not stabilizing here, as these require further work on the type system. We hope to lift these limitations later. The limitations that are part of this PR were specified in the [RFC's stabilization strategy](https://rust-lang.github.io/rfcs/3617-precise-capturing.html#stabilization-strategy). #### Not capturing type or const parameters The RFC addresses the overcapturing of type and const parameters; that is, it allows for them to not be captured in opaque types. We're not stabilizing that in this PR. Since all in scope generic type and const parameters are implicitly captured in all editions, this is not needed for the migration to Rust 2024. For now, when using `use<..>`, all in scope type and const parameters must be nameable (i.e., APIT cannot be used) and included as arguments. For example, this is an error because `T` is in scope and not included as an argument: ```rust fn test<T>() -> impl Sized + use<> {} //~^ ERROR `impl Trait` must mention all type parameters in scope in `use<...>` ``` This is due to certain current limitations in the type system related to how generic parameters are represented as captured (i.e. bivariance) and how inference operates. We hope to relax this in the future, and this stabilization is forward compatible with doing so. #### Precise capturing for return-position impl Trait **in trait** (RPITIT) The RFC specifies precise capturing for RPITIT. We're not stabilizing that in this PR. Since RPITIT already adheres to the Lifetime Capture Rules 2024, this isn't needed for the migration to Rust 2024. The effect of this is that the anonymous associated types created by RPITITs must continue to capture all of the lifetime parameters in scope, e.g.: ```rust trait Foo<'a> { fn test() -> impl Sized + use<Self>; //~^ ERROR `use<...>` precise capturing syntax is currently not allowed in return-position `impl Trait` in traits } ``` To allow this involves a meaningful amount of type system work related to adding variance to GATs or reworking how generics are represented in RPITITs. We plan to do this work separately from the stabilization. See: - rust-lang/rust#124029 Supporting precise capturing for RPITIT will also require us to implement a new algorithm for detecting refining capture behavior. This may involve looking through type parameters to detect cases where the impl Trait type in an implementation captures fewer lifetimes than the corresponding RPITIT in the trait definition, e.g.: ```rust trait Foo { fn rpit() -> impl Sized + use<Self>; } impl<'a> Foo for &'a () { // This is "refining" due to not capturing `'a` which // is implied by the trait's `use<Self>`. fn rpit() -> impl Sized + use<>; // This is not "refining". fn rpit() -> impl Sized + use<'a>; } ``` This stabilization is forward compatible with adding support for this later. ### The technical details This bound is purely syntactical and does not lower to a [`Clause`](https://doc.rust-lang.org/1.79.0/nightly-rustc/rustc_middle/ty/type.ClauseKind.html) in the type system. For the purposes of the type system (and for the types team's curiosity regarding this stabilization), we have no current need to represent this as a `ClauseKind`. Since opaques already capture a variable set of lifetimes depending on edition and their syntactical position (e.g. RPIT vs RPITIT), a `use<..>` bound is just a way to explicitly rather than implicitly specify that set of lifetimes, and this only affects opaque type lowering from AST to HIR. ### FCP plan While there's much discussion of the type system here, the feature in this PR is implemented internally as a transformation that happens before lowering to the type system layer. We already support impl Trait types partially capturing the in scope lifetimes; we just currently only expose that implicitly. So, in my (errs's) view as a types team member, there's nothing for types to weigh in on here with respect to the implementation being stabilized, and I'd suggest a lang-only proposed FCP (though we'll of course CC the team below). ### Authorship and acknowledgments This stabilization report was coauthored by compiler-errors and TC. TC would like to acknowledge the outstanding and speedy work that compiler-errors has done to make this feature happen. compiler-errors thanks TC for authoring the RFC, for all of his involvement in this feature's development, and pushing the Rust 2024 edition forward. ### Open items We're doing some things in parallel here. In signaling the intention to stabilize, we want to uncover any latent issues so we can be sure they get addressed. We want to give the maximum time for discussion here to happen by starting it while other remaining miscellaneous work proceeds. That work includes: - [x] Look into `syn` support. - dtolnay/syn#1677 - dtolnay/syn#1707 - [x] Look into `rustfmt` support. - rust-lang/rust#126754 - [x] Look into `rust-analyzer` support. - rust-lang/rust-analyzer#17598 - rust-lang/rust-analyzer#17676 - [x] Look into `rustdoc` support. - rust-lang/rust#127228 - rust-lang/rust#127632 - rust-lang/rust#127658 - [x] Suggest this feature to RfL (a known nightly user). - [x] Add a chapter to the edition guide. - rust-lang/edition-guide#316 - [x] Update the Reference. - rust-lang/reference#1577 ### (Selected) implementation history * rust-lang/rfcs#3498 * rust-lang/rfcs#3617 * rust-lang/rust#123468 * rust-lang/rust#125836 * rust-lang/rust#126049 * rust-lang/rust#126753 Closes #123432. cc `@rust-lang/lang` `@rust-lang/types` `@rustbot` labels +T-lang +I-lang-nominated +A-impl-trait +F-precise_capturing Tracking: - rust-lang/rust#123432 ---- For the compiler reviewer, I'll leave some inline comments about diagnostics fallout :^) r? compiler

traviscross added C-tracking-issue Category: An issue tracking the progress of sth. like the implementation of an RFC T-lang Relevant to the language team, which will review and decide on the PR/issue. labels Apr 3, 2024

compiler-errors self-assigned this Apr 3, 2024

fmease added B-experimental Blocker: In-tree experiment; RFC pending, not yet approved or unneeded. S-tracking-unimplemented Status: The feature has not been implemented. S-tracking-needs-design-proposal Status: This needs a clear design proposal and then a meeting with the team. labels Apr 3, 2024

traviscross changed the title ~~Tracking Issue for precise_capturing~~ Tracking Issue for precise_captures Apr 4, 2024

traviscross changed the title ~~Tracking Issue for precise_captures~~ Tracking Issue for precise_capturing Apr 4, 2024

traviscross added the F-precise_capturing `#![feature(precise_capturing)]` label Apr 4, 2024

traviscross mentioned this issue Apr 4, 2024

Implement syntax for impl Trait to specify its captures explicitly (feature(precise_capturing)) #123468

Merged

compiler-errors removed their assignment Apr 8, 2024

fmease added S-tracking-unimplemented Status: The feature has not been implemented. and removed S-tracking-unimplemented Status: The feature has not been implemented. labels Apr 10, 2024

traviscross added the A-edition-2024 Area: The 2024 edition label Apr 10, 2024

traviscross self-assigned this Apr 12, 2024

compiler-errors removed the S-tracking-unimplemented Status: The feature has not been implemented. label Apr 21, 2024

jackh726 mentioned this issue Apr 25, 2024

Precise capturing rust-lang/rfcs#3617

Merged

traviscross added B-RFC-approved Blocker: Approved by a merged RFC but not yet implemented. and removed B-experimental Blocker: In-tree experiment; RFC pending, not yet approved or unneeded. labels May 6, 2024

jwong101 mentioned this issue May 20, 2024

returning a future from a function with an impl Trait argument references that argument even if not used in the future, causing lifetime errors #125341

Closed

traviscross mentioned this issue Jun 1, 2024

Syntax for precise capturing: impl Trait + use<..> #125836

Closed

This was referenced Jul 13, 2024

Stabilize opaque type precise capturing (RFC 3617) #127672

Merged

Parse use<'a, T> precise capturing bounds as verbatim dtolnay/syn#1707

Merged

This was referenced Jul 14, 2024

Fix precise capturing suggestion for hidden regions when we have APITs #127664

Merged

Suggest using precise capturing for hidden type that captures region #127619

Merged

Support for + use<..> precise_capturing syntax rust-lang/rust-analyzer#17598

Closed

traviscross mentioned this issue Aug 5, 2024

Add chapter for Lifetime Capture Rules 2024 rust-lang/edition-guide#316

Merged

traviscross changed the title ~~Tracking Issue for precise_capturing~~ Tracking issue for precise_capturing Aug 16, 2024

traviscross mentioned this issue Aug 16, 2024

Add capturing and precise capturing rules rust-lang/reference#1577

Merged

bors closed this as completed in a971212 Aug 20, 2024

traviscross changed the title ~~Tracking issue for precise_capturing~~ Tracking issue for precise_capturing syntax Sep 6, 2024

This was referenced Sep 6, 2024

Tracking issue for RFC 3617 precise capturing of types #130043

Open

Tracking issue for RFC 3617 precise capturing in traits #130044

Open

This was referenced Sep 17, 2024

Rust 2024 Edition rust-lang/rust-project-goals#117

Open

Tracking Issue for RFC 3501: Edition 2024 #117258

Open

ehuss mentioned this issue Oct 3, 2024

Add support for use bounds rust-lang/rust-enhanced#533

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Tracking issue for `precise_capturing` syntax #123432

Tracking issue for `precise_capturing` syntax #123432

traviscross commented Apr 3, 2024 •

edited

Loading

Tracking issue for precise_capturing syntax #123432

Tracking issue for precise_capturing syntax #123432

Comments

traviscross commented Apr 3, 2024 • edited Loading

About tracking issues

Steps

Related

Implementation history

Tracking issue for `precise_capturing` syntax #123432

Tracking issue for `precise_capturing` syntax #123432

traviscross commented Apr 3, 2024 •

edited

Loading