Support GATs in Rustdoc #94009

compiler-errors · 2022-02-15T03:53:16Z

Implements:

Rendering GATs in trait definitions and impl blocks
Rendering GATs in types (e.g. in the return type of a function)

This is my first rustdoc PR, so I have absolutely no idea how to produce tests for this. Advice from the rustdoc team would be wonderful!

I tested locally and things looked correct:

rust-highfive · 2022-02-15T03:53:18Z

rustdoc-json-types is a public (although nightly-only) API. Consider changing src/librustdoc/json/conversions.rs instead; otherwise, make sure you update format_version.

cc @CraftSpider,@aDotInTheVoid

Some changes occurred in clean/types.rs.

cc @camelid

rust-highfive · 2022-02-15T03:53:20Z

r? @CraftSpider

(rust-highfive has picked a reviewer for you, use r? to override)

src/librustdoc/clean/types.rs

camelid · 2022-02-16T03:33:41Z

Regarding tests, they'll go in src/test/rustdoc (ideally in a new gats subdirectory, or one similarly named). I recommend looking at existing tests in there. (We really need to write docs for how rustdoc's tests work....)

Tests will look like this:

pub trait MyTrait {
    // @has test_name/trait.MyTrait.html '//[@id='associatedtype.Owned']' "type Gat<'a>"
    type Gat<'a>;
}

You can also use snapshot tests for very targeted parts of the page if you want. These work with --bless, unlike the @has style:

pub trait MyTrait {
    // @snapshot MyTrait_decl test_name/trait.MyTrait.html '//pre[@class="type-decl"]'
    type Gat<'a>;
}

aDotInTheVoid · 2022-02-16T10:51:15Z

Additionally, json tests go in src/test/rustdoc-json (also a subdirectory should be used), and run with ./x.py test src/test/rustdoc-json

These use jsonpath to check the output. Check the existing tests for how this works, and also

rust/src/tools/jsondocck/src/main.rs

Line 190 in a240ccd

fn check_command(command: Command, cache: &mut Cache) -> Result<(), CkError> {

for all the forms of tests allowed

Some advice: no_core lets you make the output much smaller, so you can manually review it.

#![feature(no_core)]
#![no_core]
#![feature(lang_items)]

#[lang = "sized"]
pub trait Sized {}

Additionally, oj is a much better prity printer than anything else I know. Invocation looks like oj -p 80 build/x86_64-unknown-linux-gnu/test/rustdoc-json/type/variance/variance.json > variance.json

Finaly, you should bump format_version in src/rustdoc-json-types/lib.rs.

Thanks for working on this, and if you have any questions about json, feel free to ping me here or on rust-lang#rustdoc discord (@aDotInTheVoid).

aDotInTheVoid · 2022-02-16T11:01:55Z

@rustbot modify labels: +A-rustdoc-json

compiler-errors · 2022-02-20T03:37:18Z

Added some tests, they kinda suck so feel free to suggest ways to improve...

camelid · 2022-02-20T22:13:34Z

Finaly, you should bump format_version in src/rustdoc-json-types/lib.rs.

bump rustdoc format-version since we changed how projections are printed

I thought this PR would only change the display of GATs, not existing projections. Is that incorrect?

compiler-errors · 2022-02-20T22:18:41Z

@camelid, so it adds an args field to the QualifiedPath type so we can print a GAT's own generics... that technically changes existing projections' JSON representation, right?

camelid · 2022-02-20T23:14:44Z

Ah, yes. By "printed", I thought you meant that the visual HTML output would change for existing projections.

src/librustdoc/html/format.rs

camelid · 2022-02-20T23:16:02Z

Let's check perf.

@bors try @rust-timer queue

rust-timer · 2022-02-20T23:16:04Z

Awaiting bors try build completion.

@rustbot label: +S-waiting-on-perf

bors · 2022-02-20T23:16:10Z

⌛ Trying commit e17bfb6fda8f9802a524287f0638410fa7a54d5c with merge 9d4556cda05f1c9993d11017df815c12e29b1562...

src/test/rustdoc-json/generic-associated-types/gats.rs

src/rustdoc-json-types/lib.rs

bors · 2022-02-21T00:51:26Z

☀️ Try build successful - checks-actions
Build commit: 9d4556cda05f1c9993d11017df815c12e29b1562 (9d4556cda05f1c9993d11017df815c12e29b1562)

rust-timer · 2022-02-21T00:51:27Z

Queued 9d4556cda05f1c9993d11017df815c12e29b1562 with parent 523a1b1, future comparison URL.

GuillaumeGomez · 2022-03-03T21:04:58Z

Thanks! This time we're good to go.

@bors: r+

bors · 2022-03-03T21:05:00Z

📌 Commit 0e57a16 has been approved by GuillaumeGomez

bors · 2022-03-04T00:27:27Z

⌛ Testing commit 0e57a16 with merge 6d76841...

bors · 2022-03-04T02:53:33Z

☀️ Test successful - checks-actions
Approved by: GuillaumeGomez
Pushing 6d76841 to master...

rust-timer · 2022-03-04T08:24:31Z

Finished benchmarking commit (6d76841): comparison url.

Summary: This benchmark run shows 41 relevant regressions 😿 to instruction counts.

Arithmetic mean of relevant regressions: 0.8%
Largest regression in instruction counts: 1.1% on full builds of ctfe-stress-4 doc

If you disagree with this performance assessment, please file an issue in rust-lang/rustc-perf.

Next Steps: If you can justify the regressions found in this perf run, please indicate this with @rustbot label: +perf-regression-triaged along with sufficient written justification. If you cannot justify the regressions please open an issue or create a new PR that fixes the regressions, add a comment linking to the newly created issue or PR, and then add the perf-regression-triaged label to this PR.

@rustbot label: +perf-regression

camelid · 2022-03-04T19:33:34Z

We judged these regressions (note that max-rss regressed as well) as acceptable, at least for now, since this change makes rustdoc track more data, which inevitably leads to perf regressions.

@rustbot label: +perf-regression-triaged

…er-errors Stabilize generic associated types Closes rust-lang#44265 r? `@nikomatsakis` # ⚡ Status of the discussion ⚡ * [x] There have been several serious concerns raised, [summarized here](rust-lang#96709 (comment)). * [x] There has also been a [deep-dive comment](rust-lang#96709 (comment)) explaining some of the "patterns of code" that are enabled by GATs, based on use-cases posted to this thread or on the tracking issue. * [x] We have modeled some aspects of GATs in [a-mir-formality](https://github.com/nikomatsakis/a-mir-formality) to give better confidence in how they will be resolved in the future. [You can read a write-up here](https://github.com/rust-lang/types-team/blob/master/minutes/2022-07-08-implied-bounds-and-wf-checking.md). * [x] The major points of the discussion have been [summarized on the GAT initiative repository](https://rust-lang.github.io/generic-associated-types-initiative/mvp.html). * [x] [FCP has been proposed](rust-lang#96709 (comment)) and we are awaiting final decisions and discussion amidst the relevant team members. # Stabilization proposal This PR proposes the stabilization of `#![feature(generic_associated_types)]`. While there a number of future additions to be made and bugs to be fixed (both discussed below), properly doing these will require significant language design and will ultimately likely be backwards-compatible. Given the overwhelming desire to have some form of generic associated types (GATs) available on stable and the stability of the "simple" uses, stabilizing the current subset of GAT features is almost certainly the correct next step. Tracking issue: rust-lang#44265 Initiative: https://rust-lang.github.io/generic-associated-types-initiative/ RFC: https://github.com/rust-lang/rfcs/blob/master/text/1598-generic_associated_types.md Version: 1.65 (2022-08-22 => beta, 2022-11-03 => stable). ## Motivation There are a myriad of potential use cases for GATs. Stabilization unblocks probable future language features (e.g. async functions in traits), potential future standard library features (e.g. a `LendingIterator` or some form of `Iterator` with a lifetime generic), and a plethora of user use cases (some of which can be seen just by scrolling through the tracking issue and looking at all the issues linking to it). There are a myriad of potential use cases for GATs. First, there are many users that have chosen to not use GATs primarily because they are not stable (some of which can be seen just by scrolling through the tracking issue and looking at all the issues linking to it). Second, while language feature desugaring isn't *blocked* on stabilization, it gives more confidence on using the feature. Likewise, library features like `LendingIterator` are not necessarily blocked on stabilization to be implemented unstably; however few, if any, public-facing APIs actually use unstable features. This feature has a long history of design, discussion, and developement - the RFC was first introduced roughly 6 years ago. While there are still a number of features left to implement and bugs left to fix, it's clear that it's unlikely those will have backwards-incompatibility concerns. Additionally, the bugs that do exist do not strongly impede the most-common use cases. ## What is stabilized The primary language feature stabilized here is the ability to have generics on associated types, as so. Additionally, where clauses on associated types will now be accepted, regardless if the associated type is generic or not. ```rust trait ATraitWithGATs { type Assoc<'a, T> where T: 'a; } trait ATraitWithoutGATs<'a, T> { type Assoc where T: 'a; } ``` When adding an impl for a trait with generic associated types, the generics for the associated type are copied as well. Note that where clauses are allowed both after the specified type and before the equals sign; however, the latter is a warn-by-default deprecation. ```rust struct X; struct Y; impl ATraitWithGATs for X { type Assoc<'a, T> = &'a T where T: 'a; } impl ATraitWithGATs for Y { type Assoc<'a, T> where T: 'a = &'a T; } ``` To use a GAT in a function, generics are specified on the associated type, as if it was a struct or enum. GATs can also be specified in trait bounds: ```rust fn accepts_gat<'a, T>(t: &'a T) -> T::Assoc<'a, T> where for<'x> T: ATraitWithGATs<Assoc<'a, T> = &'a T> { ... } ``` GATs can also appear in trait methods. However, depending on how they are used, they may confer where clauses on the associated type definition. More information can be found [here](rust-lang#87479). Briefly, where clauses are required when those bounds can be proven in the methods that *construct* the GAT or other associated types that use the GAT in the trait. This allows impls to have maximum flexibility in the types defined for the associated type. To take a relatively simple example: ```rust trait Iterable { type Item<'a>; type Iterator<'a>: Iterator<Item = Self::Item<'a>>; fn iter<'x>(&'x self) -> Self::Iterator<'x>; //^ We know that `Self: 'a` for `Iterator<'a>`, so we require that bound on `Iterator` // `Iterator` uses `Self::Item`, so we also require a `Self: 'a` on `Item` too } ``` A couple well-explained examples are available in a previous [blog post](https://blog.rust-lang.org/2021/08/03/GATs-stabilization-push.html). ## What isn't stabilized/implemented ### Universal type/const quantification Currently, you can write a bound like `X: for<'a> Trait<Assoc<'a> = &'a ()>`. However, you cannot currently write `for<T> X: Trait<Assoc<T> = T>` or `for<const N> X: Trait<Assoc<N> = [usize; N]>`. Here is an example where this is needed: ```rust trait Foo {} trait Trait { type Assoc<F: Foo>; } trait Trait2: Sized { fn foo<F: Foo, T: Trait<Assoc<F> = F>>(_t: T); } ``` In the above example, the *caller* must specify `F`, which is likely not what is desired. ### Object-safe GATs Unlike non-generic associated types, traits with GATs are not currently object-safe. In other words the following are not allowed: ```rust trait Trait { type Assoc<'a>; } fn foo(t: &dyn for<'a> Trait<Assoc<'a> = &'a ()>) {} //^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ not allowed let ty: Box<dyn for<'a> Trait<Assoc<'a> = &'a ()>>; //^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ not allowed ``` ### Higher-kinded types You cannot write currently (and there are no current plans to implement this): ```rust struct Struct<'a> {} fn foo(s: for<'a> Struct<'a>) {} ``` ## Tests There are many tests covering GATs that can be found in `src/test/ui/generic-associated-types`. Here, I'll list (in alphanumeric order) tests highlight some important behavior or contain important patterns. - `./parse/*`: Parsing of GATs in traits and impls, and the trait path with GATs - `./collections-project-default.rs`: Interaction with associated type defaults - `./collections.rs`: The `Collection` pattern - `./const-generics-gat-in-trait-return-type-*.rs`: Const parameters - `./constraint-assoc-type-suggestion.rs`: Emit correct syntax in suggestion - `./cross-crate-bounds.rs`: Ensure we handles bounds across crates the same - `./elided-in-expr-position.rs`: Disallow lifetime elision in return position - `./gat-in-trait-path-undeclared-lifetime.rs`: Ensure we error on undeclared lifetime in trait path - `./gat-in-trait-path.rs`: Base trait path case - `./gat-trait-path-generic-type-arg.rs`: Don't allow shadowing of parameters - `./gat-trait-path-parenthesised-args.rs`: Don't allow paranthesized args in trait path - `./generic-associated-types-where.rs`: Ensure that we require where clauses from trait to be met on impl - `./impl_bounds.rs`: Check that the bounds on GATs in an impl are checked - `./issue-76826.rs`: `Windows` pattern - `./issue-78113-lifetime-mismatch-dyn-trait-box.rs`: Implicit 'static diagnostics - `./issue-84931.rs`: Ensure that we have a where clause on GAT to ensure trait parameter lives long enough - `./issue-87258_a.rs`: Unconstrained opaque type with TAITs - `./issue-87429-2.rs`: Ensure we can use bound vars in the bounds - `./issue-87429-associated-type-default.rs`: Ensure bounds hold with associated type defaults, for both trait and impl - `./issue-87429-specialization.rs`: Check that bounds hold under specialization - `./issue-88595.rs`: Under the outlives lint, we require a bound for both trait and GAT lifetime when trait lifetime is used in function - `./issue-90014.rs`: Lifetime bounds are checked with TAITs - `./issue-91139.rs`: Under migrate mode, but not NLL, we don't capture implied bounds from HRTB lifetimes used in a function and GATs - `./issue-91762.rs`: We used to too eagerly pick param env candidates when normalizing with GATs. We now require explicit parameters specified. - `./issue-95305.rs`: Disallow lifetime elision in trait paths - `./iterable.rs`: `Iterable` pattern - `./method-unsatified-assoc-type-predicate.rs`: Print predicates with GATs correctly in method resolve error - `./missing_lifetime_const.rs`: Ensure we must specify lifetime args (not elidable) - `./missing-where-clause-on-trait.rs`: Ensure we don't allow stricter bounds on impl than trait - `./parameter_number_and_kind_impl.rs`: Ensure paramters on GAT in impl match GAT in trait - `./pointer_family.rs`: `PointerFamily` pattern - `./projection-bound-cycle.rs`: Don't allow invalid cycles to prove bounds - `./self-outlives-lint.rs`: Ensures that an e.g. `Self: 'a` is written on the traits GAT if that bound can be implied from the GAT usage in the trait - `./shadowing.rs`: Don't allow lifetime shadowing in params - `./streaming_iterator.rs`: `StreamingIterator`(`LendingIterator`) pattern - `./trait-objects.rs`: Disallow trait objects for traits with GATs - `./variance_constraints.rs`: Require that GAT substs be invariant ## Remaining bugs and open issues A full list of remaining open issues can be found at: https://github.com/rust-lang/rust/labels/F-generic_associated_types There are some `known-bug` tests in-tree at `src/test/ui/generic-associated-types/bugs`. Here I'll categorize most of those that GAT bugs (or involve a pattern found more with GATs), but not those that include GATs but not a GAT issue in and of itself. (I also won't include issues directly for things listed elsewhere here.) Using the concrete type of a GAT instead of the projection type can give errors, since lifetimes are chosen to be early-bound vs late-bound. - rust-lang#85533 - rust-lang#87803 In certain cases, we can run into cycle or overflow errors. This is more generally a problem with associated types. - rust-lang#87755 - rust-lang#87758 Bounds on an associatd type need to be proven by an impl, but where clauses need to be proven by the usage. This can lead to confusion when users write one when they mean the other. - rust-lang#87831 - rust-lang#90573 We sometimes can't normalize closure signatures fully. Really an asociated types issue, but might happen a bit more frequently with GATs, since more obvious place for HRTB lifetimes. - rust-lang#88382 When calling a function, we assign types to parameters "too late", after we already try (and fail) to normalize projections. Another associated types issue that might pop up more with GATs. - rust-lang#88460 - rust-lang#96230 We don't fully have implied bounds for lifetimes appearing in GAT trait paths, which can lead to unconstrained type errors. - rust-lang#88526 Suggestion for adding lifetime bounds can suggest unhelpful fixes (`T: 'a` instead of `Self: 'a`), but the next compiler error after making the suggested change is helpful. - rust-lang#90816 - rust-lang#92096 - rust-lang#95268 We can end up requiring that `for<'a> I: 'a` when we really want `for<'a where I: 'a> I: 'a`. This can leave unhelpful errors than effectively can't be satisfied unless `I: 'static`. Requires bigger changes and not only GATs. - rust-lang#91693 Unlike with non-generic associated types, we don't eagerly normalize with param env candidates. This is intended behavior (for now), to avoid accidentaly stabilizing picking arbitrary impls. - rust-lang#91762 Some Iterator adapter patterns (namely `filter`) require Polonius or unsafe to work. - rust-lang#92985 ## Potential Future work ### Universal type/const quantification No work has been done to implement this. There are also some questions around implied bounds. ### Object-safe GATs The intention is to make traits with GATs object-safe. There are some design work to be done around well-formedness rules and general implementation. ### GATified std lib types It would be helpful to either introduce new std lib traits (like `LendingIterator`) or to modify existing ones (adding a `'a` generic to `Iterator::Item`). There also a number of other candidates, like `Index`/`IndexMut` and `Fn`/`FnMut`/`FnOnce`. ### Reduce the need for `for<'a>` Seen [here](rust-lang/rfcs#1598 (comment)). One possible syntax: ```rust trait Iterable { type Iter<'a>: Iterator<Item = Self::Item<'a>>; } fn foo<T>() where T: Iterable, T::Item<let 'a>: Display { } //note the `let`! ``` ### Better implied bounds on higher-ranked things Currently if we have a `type Item<'a> where self: 'a`, and a `for<'a> T: Iterator<Item<'a> = &'a ()`, this requires `for<'a> Self: 'a`. Really, we want `for<'a where T: 'a> ...` There was some mentions of this all the back in the RFC thread [here](rust-lang/rfcs#1598 (comment)). ## Alternatives ### Make generics on associated type in bounds a binder Imagine the bound `for<'a> T: Trait<Item<'a>= &'a ()>`. It might be that `for<'a>` is "too large" and it should instead be `T: Trait<for<'a> Item<'a>= &'a ()>`. Brought up in RFC thread [here](rust-lang/rfcs#1598 (comment)) and in a few places since. Another related question: Is `for<'a>` the right syntax? Maybe `where<'a>`? Also originally found in RFC thread [here](rust-lang/rfcs#1598 (comment)). ### Stabilize lifetime GATs first This has been brought up a few times. The idea is to only allow GATs with lifetime parameters to in initial stabilization. This was probably most useful prior to actual implementation. At this point, lifetimes, types, and consts are all implemented and work. It feels like an arbitrary split without strong reason. ## History * On 2016-04-30, [RFC opened](rust-lang/rfcs#1598) * On 2017-09-02, RFC merged and [tracking issue opened](rust-lang#44265) * On 2017-10-23, [Move Generics from MethodSig to TraitItem and ImplItem](rust-lang#44766) * On 2017-12-01, [Generic Associated Types Parsing & Name Resolution](rust-lang#45904) * On 2017-12-15, [rust-lang#46706 * On 2018-04-23, [Feature gate where clauses on associated types](rust-lang#49368) * On 2018-05-10, [Extend tests for RFC1598 (GAT)](rust-lang#49423) * On 2018-05-24, [Finish implementing GATs (Chalk)](rust-lang/chalk#134) * On 2019-12-21, [Make GATs less ICE-prone](rust-lang#67160) * On 2020-02-13, [fix lifetime shadowing check in GATs](rust-lang#68938) * On 2020-06-20, [Projection bound validation](rust-lang#72788) * On 2020-10-06, [Separate projection bounds and predicates](rust-lang#73905) * On 2021-02-05, [Generic associated types in trait paths](rust-lang#79554) * On 2021-02-06, [Trait objects do not work with generic associated types](rust-lang#81823) * On 2021-04-28, [Make traits with GATs not object safe](rust-lang#84622) * On 2021-05-11, [Improve diagnostics for GATs](rust-lang#82272) * On 2021-07-16, [Make GATs no longer an incomplete feature](rust-lang#84623) * On 2021-07-16, [Replace associated item bound vars with placeholders when projecting](rust-lang#86993) * On 2021-07-26, [GATs: Decide whether to have defaults for `where Self: 'a`](rust-lang#87479) * On 2021-08-25, [Normalize projections under binders](rust-lang#85499) * On 2021-08-03, [The push for GATs stabilization](https://blog.rust-lang.org/2021/08/03/GATs-stabilization-push.html) * On 2021-08-12, [Detect stricter constraints on gats where clauses in impls vs trait](rust-lang#88336) * On 2021-09-20, [Proposal: Change syntax of where clauses on type aliases](rust-lang#89122) * On 2021-11-06, [Implementation of GATs outlives lint](rust-lang#89970) * On 2021-12-29. [Parse and suggest moving where clauses after equals for type aliases](rust-lang#92118) * On 2022-01-15, [Ignore static lifetimes for GATs outlives lint](rust-lang#92865) * On 2022-02-08, [Don't constrain projection predicates with inference vars in GAT substs](rust-lang#92917) * On 2022-02-15, [Rework GAT where clause check](rust-lang#93820) * On 2022-02-19, [Only mark projection as ambiguous if GAT substs are constrained](rust-lang#93892) * On 2022-03-03, [Support GATs in Rustdoc](rust-lang#94009) * On 2022-03-06, [Change location of where clause on GATs](rust-lang#90076) * On 2022-05-04, [A shiny future with GATs blog post](https://jackh726.github.io/rust/2022/05/04/a-shiny-future-with-gats.html) * On 2022-05-04, [Stabilization PR](rust-lang#96709)

Stabilize generic associated types Closes #44265 r? `@nikomatsakis` # ⚡ Status of the discussion ⚡ * [x] There have been several serious concerns raised, [summarized here](rust-lang/rust#96709 (comment)). * [x] There has also been a [deep-dive comment](rust-lang/rust#96709 (comment)) explaining some of the "patterns of code" that are enabled by GATs, based on use-cases posted to this thread or on the tracking issue. * [x] We have modeled some aspects of GATs in [a-mir-formality](https://github.com/nikomatsakis/a-mir-formality) to give better confidence in how they will be resolved in the future. [You can read a write-up here](https://github.com/rust-lang/types-team/blob/master/minutes/2022-07-08-implied-bounds-and-wf-checking.md). * [x] The major points of the discussion have been [summarized on the GAT initiative repository](https://rust-lang.github.io/generic-associated-types-initiative/mvp.html). * [x] [FCP has been proposed](rust-lang/rust#96709 (comment)) and we are awaiting final decisions and discussion amidst the relevant team members. # Stabilization proposal This PR proposes the stabilization of `#![feature(generic_associated_types)]`. While there a number of future additions to be made and bugs to be fixed (both discussed below), properly doing these will require significant language design and will ultimately likely be backwards-compatible. Given the overwhelming desire to have some form of generic associated types (GATs) available on stable and the stability of the "simple" uses, stabilizing the current subset of GAT features is almost certainly the correct next step. Tracking issue: #44265 Initiative: https://rust-lang.github.io/generic-associated-types-initiative/ RFC: https://github.com/rust-lang/rfcs/blob/master/text/1598-generic_associated_types.md Version: 1.65 (2022-08-22 => beta, 2022-11-03 => stable). ## Motivation There are a myriad of potential use cases for GATs. Stabilization unblocks probable future language features (e.g. async functions in traits), potential future standard library features (e.g. a `LendingIterator` or some form of `Iterator` with a lifetime generic), and a plethora of user use cases (some of which can be seen just by scrolling through the tracking issue and looking at all the issues linking to it). There are a myriad of potential use cases for GATs. First, there are many users that have chosen to not use GATs primarily because they are not stable (some of which can be seen just by scrolling through the tracking issue and looking at all the issues linking to it). Second, while language feature desugaring isn't *blocked* on stabilization, it gives more confidence on using the feature. Likewise, library features like `LendingIterator` are not necessarily blocked on stabilization to be implemented unstably; however few, if any, public-facing APIs actually use unstable features. This feature has a long history of design, discussion, and developement - the RFC was first introduced roughly 6 years ago. While there are still a number of features left to implement and bugs left to fix, it's clear that it's unlikely those will have backwards-incompatibility concerns. Additionally, the bugs that do exist do not strongly impede the most-common use cases. ## What is stabilized The primary language feature stabilized here is the ability to have generics on associated types, as so. Additionally, where clauses on associated types will now be accepted, regardless if the associated type is generic or not. ```rust trait ATraitWithGATs { type Assoc<'a, T> where T: 'a; } trait ATraitWithoutGATs<'a, T> { type Assoc where T: 'a; } ``` When adding an impl for a trait with generic associated types, the generics for the associated type are copied as well. Note that where clauses are allowed both after the specified type and before the equals sign; however, the latter is a warn-by-default deprecation. ```rust struct X; struct Y; impl ATraitWithGATs for X { type Assoc<'a, T> = &'a T where T: 'a; } impl ATraitWithGATs for Y { type Assoc<'a, T> where T: 'a = &'a T; } ``` To use a GAT in a function, generics are specified on the associated type, as if it was a struct or enum. GATs can also be specified in trait bounds: ```rust fn accepts_gat<'a, T>(t: &'a T) -> T::Assoc<'a, T> where for<'x> T: ATraitWithGATs<Assoc<'a, T> = &'a T> { ... } ``` GATs can also appear in trait methods. However, depending on how they are used, they may confer where clauses on the associated type definition. More information can be found [here](rust-lang/rust#87479). Briefly, where clauses are required when those bounds can be proven in the methods that *construct* the GAT or other associated types that use the GAT in the trait. This allows impls to have maximum flexibility in the types defined for the associated type. To take a relatively simple example: ```rust trait Iterable { type Item<'a>; type Iterator<'a>: Iterator<Item = Self::Item<'a>>; fn iter<'x>(&'x self) -> Self::Iterator<'x>; //^ We know that `Self: 'a` for `Iterator<'a>`, so we require that bound on `Iterator` // `Iterator` uses `Self::Item`, so we also require a `Self: 'a` on `Item` too } ``` A couple well-explained examples are available in a previous [blog post](https://blog.rust-lang.org/2021/08/03/GATs-stabilization-push.html). ## What isn't stabilized/implemented ### Universal type/const quantification Currently, you can write a bound like `X: for<'a> Trait<Assoc<'a> = &'a ()>`. However, you cannot currently write `for<T> X: Trait<Assoc<T> = T>` or `for<const N> X: Trait<Assoc<N> = [usize; N]>`. Here is an example where this is needed: ```rust trait Foo {} trait Trait { type Assoc<F: Foo>; } trait Trait2: Sized { fn foo<F: Foo, T: Trait<Assoc<F> = F>>(_t: T); } ``` In the above example, the *caller* must specify `F`, which is likely not what is desired. ### Object-safe GATs Unlike non-generic associated types, traits with GATs are not currently object-safe. In other words the following are not allowed: ```rust trait Trait { type Assoc<'a>; } fn foo(t: &dyn for<'a> Trait<Assoc<'a> = &'a ()>) {} //^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ not allowed let ty: Box<dyn for<'a> Trait<Assoc<'a> = &'a ()>>; //^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ not allowed ``` ### Higher-kinded types You cannot write currently (and there are no current plans to implement this): ```rust struct Struct<'a> {} fn foo(s: for<'a> Struct<'a>) {} ``` ## Tests There are many tests covering GATs that can be found in `src/test/ui/generic-associated-types`. Here, I'll list (in alphanumeric order) tests highlight some important behavior or contain important patterns. - `./parse/*`: Parsing of GATs in traits and impls, and the trait path with GATs - `./collections-project-default.rs`: Interaction with associated type defaults - `./collections.rs`: The `Collection` pattern - `./const-generics-gat-in-trait-return-type-*.rs`: Const parameters - `./constraint-assoc-type-suggestion.rs`: Emit correct syntax in suggestion - `./cross-crate-bounds.rs`: Ensure we handles bounds across crates the same - `./elided-in-expr-position.rs`: Disallow lifetime elision in return position - `./gat-in-trait-path-undeclared-lifetime.rs`: Ensure we error on undeclared lifetime in trait path - `./gat-in-trait-path.rs`: Base trait path case - `./gat-trait-path-generic-type-arg.rs`: Don't allow shadowing of parameters - `./gat-trait-path-parenthesised-args.rs`: Don't allow paranthesized args in trait path - `./generic-associated-types-where.rs`: Ensure that we require where clauses from trait to be met on impl - `./impl_bounds.rs`: Check that the bounds on GATs in an impl are checked - `./issue-76826.rs`: `Windows` pattern - `./issue-78113-lifetime-mismatch-dyn-trait-box.rs`: Implicit 'static diagnostics - `./issue-84931.rs`: Ensure that we have a where clause on GAT to ensure trait parameter lives long enough - `./issue-87258_a.rs`: Unconstrained opaque type with TAITs - `./issue-87429-2.rs`: Ensure we can use bound vars in the bounds - `./issue-87429-associated-type-default.rs`: Ensure bounds hold with associated type defaults, for both trait and impl - `./issue-87429-specialization.rs`: Check that bounds hold under specialization - `./issue-88595.rs`: Under the outlives lint, we require a bound for both trait and GAT lifetime when trait lifetime is used in function - `./issue-90014.rs`: Lifetime bounds are checked with TAITs - `./issue-91139.rs`: Under migrate mode, but not NLL, we don't capture implied bounds from HRTB lifetimes used in a function and GATs - `./issue-91762.rs`: We used to too eagerly pick param env candidates when normalizing with GATs. We now require explicit parameters specified. - `./issue-95305.rs`: Disallow lifetime elision in trait paths - `./iterable.rs`: `Iterable` pattern - `./method-unsatified-assoc-type-predicate.rs`: Print predicates with GATs correctly in method resolve error - `./missing_lifetime_const.rs`: Ensure we must specify lifetime args (not elidable) - `./missing-where-clause-on-trait.rs`: Ensure we don't allow stricter bounds on impl than trait - `./parameter_number_and_kind_impl.rs`: Ensure paramters on GAT in impl match GAT in trait - `./pointer_family.rs`: `PointerFamily` pattern - `./projection-bound-cycle.rs`: Don't allow invalid cycles to prove bounds - `./self-outlives-lint.rs`: Ensures that an e.g. `Self: 'a` is written on the traits GAT if that bound can be implied from the GAT usage in the trait - `./shadowing.rs`: Don't allow lifetime shadowing in params - `./streaming_iterator.rs`: `StreamingIterator`(`LendingIterator`) pattern - `./trait-objects.rs`: Disallow trait objects for traits with GATs - `./variance_constraints.rs`: Require that GAT substs be invariant ## Remaining bugs and open issues A full list of remaining open issues can be found at: https://github.com/rust-lang/rust/labels/F-generic_associated_types There are some `known-bug` tests in-tree at `src/test/ui/generic-associated-types/bugs`. Here I'll categorize most of those that GAT bugs (or involve a pattern found more with GATs), but not those that include GATs but not a GAT issue in and of itself. (I also won't include issues directly for things listed elsewhere here.) Using the concrete type of a GAT instead of the projection type can give errors, since lifetimes are chosen to be early-bound vs late-bound. - #85533 - #87803 In certain cases, we can run into cycle or overflow errors. This is more generally a problem with associated types. - #87755 - #87758 Bounds on an associatd type need to be proven by an impl, but where clauses need to be proven by the usage. This can lead to confusion when users write one when they mean the other. - #87831 - #90573 We sometimes can't normalize closure signatures fully. Really an asociated types issue, but might happen a bit more frequently with GATs, since more obvious place for HRTB lifetimes. - #88382 When calling a function, we assign types to parameters "too late", after we already try (and fail) to normalize projections. Another associated types issue that might pop up more with GATs. - #88460 - #96230 We don't fully have implied bounds for lifetimes appearing in GAT trait paths, which can lead to unconstrained type errors. - #88526 Suggestion for adding lifetime bounds can suggest unhelpful fixes (`T: 'a` instead of `Self: 'a`), but the next compiler error after making the suggested change is helpful. - #90816 - #92096 - #95268 We can end up requiring that `for<'a> I: 'a` when we really want `for<'a where I: 'a> I: 'a`. This can leave unhelpful errors than effectively can't be satisfied unless `I: 'static`. Requires bigger changes and not only GATs. - #91693 Unlike with non-generic associated types, we don't eagerly normalize with param env candidates. This is intended behavior (for now), to avoid accidentaly stabilizing picking arbitrary impls. - #91762 Some Iterator adapter patterns (namely `filter`) require Polonius or unsafe to work. - #92985 ## Potential Future work ### Universal type/const quantification No work has been done to implement this. There are also some questions around implied bounds. ### Object-safe GATs The intention is to make traits with GATs object-safe. There are some design work to be done around well-formedness rules and general implementation. ### GATified std lib types It would be helpful to either introduce new std lib traits (like `LendingIterator`) or to modify existing ones (adding a `'a` generic to `Iterator::Item`). There also a number of other candidates, like `Index`/`IndexMut` and `Fn`/`FnMut`/`FnOnce`. ### Reduce the need for `for<'a>` Seen [here](rust-lang/rfcs#1598 (comment)). One possible syntax: ```rust trait Iterable { type Iter<'a>: Iterator<Item = Self::Item<'a>>; } fn foo<T>() where T: Iterable, T::Item<let 'a>: Display { } //note the `let`! ``` ### Better implied bounds on higher-ranked things Currently if we have a `type Item<'a> where self: 'a`, and a `for<'a> T: Iterator<Item<'a> = &'a ()`, this requires `for<'a> Self: 'a`. Really, we want `for<'a where T: 'a> ...` There was some mentions of this all the back in the RFC thread [here](rust-lang/rfcs#1598 (comment)). ## Alternatives ### Make generics on associated type in bounds a binder Imagine the bound `for<'a> T: Trait<Item<'a>= &'a ()>`. It might be that `for<'a>` is "too large" and it should instead be `T: Trait<for<'a> Item<'a>= &'a ()>`. Brought up in RFC thread [here](rust-lang/rfcs#1598 (comment)) and in a few places since. Another related question: Is `for<'a>` the right syntax? Maybe `where<'a>`? Also originally found in RFC thread [here](rust-lang/rfcs#1598 (comment)). ### Stabilize lifetime GATs first This has been brought up a few times. The idea is to only allow GATs with lifetime parameters to in initial stabilization. This was probably most useful prior to actual implementation. At this point, lifetimes, types, and consts are all implemented and work. It feels like an arbitrary split without strong reason. ## History * On 2016-04-30, [RFC opened](rust-lang/rfcs#1598) * On 2017-09-02, RFC merged and [tracking issue opened](rust-lang/rust#44265) * On 2017-10-23, [Move Generics from MethodSig to TraitItem and ImplItem](rust-lang/rust#44766) * On 2017-12-01, [Generic Associated Types Parsing & Name Resolution](rust-lang/rust#45904) * On 2017-12-15, [rust-lang/rust#46706 * On 2018-04-23, [Feature gate where clauses on associated types](rust-lang/rust#49368) * On 2018-05-10, [Extend tests for RFC1598 (GAT)](rust-lang/rust#49423) * On 2018-05-24, [Finish implementing GATs (Chalk)](rust-lang/chalk#134) * On 2019-12-21, [Make GATs less ICE-prone](rust-lang/rust#67160) * On 2020-02-13, [fix lifetime shadowing check in GATs](rust-lang/rust#68938) * On 2020-06-20, [Projection bound validation](rust-lang/rust#72788) * On 2020-10-06, [Separate projection bounds and predicates](rust-lang/rust#73905) * On 2021-02-05, [Generic associated types in trait paths](rust-lang/rust#79554) * On 2021-02-06, [Trait objects do not work with generic associated types](rust-lang/rust#81823) * On 2021-04-28, [Make traits with GATs not object safe](rust-lang/rust#84622) * On 2021-05-11, [Improve diagnostics for GATs](rust-lang/rust#82272) * On 2021-07-16, [Make GATs no longer an incomplete feature](rust-lang/rust#84623) * On 2021-07-16, [Replace associated item bound vars with placeholders when projecting](rust-lang/rust#86993) * On 2021-07-26, [GATs: Decide whether to have defaults for `where Self: 'a`](rust-lang/rust#87479) * On 2021-08-25, [Normalize projections under binders](rust-lang/rust#85499) * On 2021-08-03, [The push for GATs stabilization](https://blog.rust-lang.org/2021/08/03/GATs-stabilization-push.html) * On 2021-08-12, [Detect stricter constraints on gats where clauses in impls vs trait](rust-lang/rust#88336) * On 2021-09-20, [Proposal: Change syntax of where clauses on type aliases](rust-lang/rust#89122) * On 2021-11-06, [Implementation of GATs outlives lint](rust-lang/rust#89970) * On 2021-12-29. [Parse and suggest moving where clauses after equals for type aliases](rust-lang/rust#92118) * On 2022-01-15, [Ignore static lifetimes for GATs outlives lint](rust-lang/rust#92865) * On 2022-02-08, [Don't constrain projection predicates with inference vars in GAT substs](rust-lang/rust#92917) * On 2022-02-15, [Rework GAT where clause check](rust-lang/rust#93820) * On 2022-02-19, [Only mark projection as ambiguous if GAT substs are constrained](rust-lang/rust#93892) * On 2022-03-03, [Support GATs in Rustdoc](rust-lang/rust#94009) * On 2022-03-06, [Change location of where clause on GATs](rust-lang/rust#90076) * On 2022-05-04, [A shiny future with GATs blog post](https://jackh726.github.io/rust/2022/05/04/a-shiny-future-with-gats.html) * On 2022-05-04, [Stabilization PR](rust-lang/rust#96709)

rustbot added the T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. label Feb 15, 2022

rust-highfive assigned CraftSpider Feb 15, 2022

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Feb 15, 2022

This comment has been minimized.

Sign in to view

compiler-errors force-pushed the gat-rustdoc branch from ab00d5d to 500081a Compare February 15, 2022 04:10

camelid self-assigned this Feb 16, 2022

camelid reviewed Feb 16, 2022

View reviewed changes

src/librustdoc/clean/types.rs Outdated Show resolved Hide resolved

rustbot added the A-rustdoc-json Area: Rustdoc JSON backend label Feb 16, 2022

compiler-errors force-pushed the gat-rustdoc branch from 500081a to 5e4638c Compare February 20, 2022 03:36

This comment has been minimized.

Sign in to view

compiler-errors force-pushed the gat-rustdoc branch from 5e4638c to e17bfb6 Compare February 20, 2022 03:48

camelid reviewed Feb 20, 2022

View reviewed changes

src/librustdoc/html/format.rs Outdated Show resolved Hide resolved

rustbot added the S-waiting-on-perf Status: Waiting on a perf run to be completed. label Feb 20, 2022

bors mentioned this pull request Feb 21, 2022

Rollup of 6 pull requests #94199

Closed

aDotInTheVoid requested changes Feb 21, 2022

View reviewed changes

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Mar 3, 2022

bors added the merged-by-bors This PR was explicitly merged by bors. label Mar 4, 2022

bors merged commit 6d76841 into rust-lang:master Mar 4, 2022

rustbot added this to the 1.61.0 milestone Mar 4, 2022

rustbot added the perf-regression-triaged The performance regression has been triaged. label Mar 4, 2022

MingweiSamuel mentioned this pull request Mar 6, 2022

ICE: rustdoc unwrap None when documenting dependency with GATs #94009 #94683

Closed

compiler-errors deleted the gat-rustdoc branch April 7, 2022 04:33

jackh726 mentioned this pull request May 4, 2022

Stabilize generic associated types #96709

Merged

5 tasks

megakorre mentioned this pull request Feb 28, 2023

ICE: rustdoc: Could not find associated const on trait #106079

Closed

fmease mentioned this pull request Jun 22, 2023

rustdoc: render the body of associated types before the where-clause #112906

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Support GATs in Rustdoc #94009

Support GATs in Rustdoc #94009

compiler-errors commented Feb 15, 2022

rust-highfive commented Feb 15, 2022

rust-highfive commented Feb 15, 2022

This comment has been minimized.

camelid commented Feb 16, 2022

aDotInTheVoid commented Feb 16, 2022

aDotInTheVoid commented Feb 16, 2022

compiler-errors commented Feb 20, 2022

This comment has been minimized.

camelid commented Feb 20, 2022

compiler-errors commented Feb 20, 2022

camelid commented Feb 20, 2022

camelid commented Feb 20, 2022

rust-timer commented Feb 20, 2022

bors commented Feb 20, 2022

bors commented Feb 21, 2022

rust-timer commented Feb 21, 2022

GuillaumeGomez commented Mar 3, 2022

bors commented Mar 3, 2022

bors commented Mar 4, 2022

bors commented Mar 4, 2022

rust-timer commented Mar 4, 2022

camelid commented Mar 4, 2022

Support GATs in Rustdoc #94009

Support GATs in Rustdoc #94009

Conversation

compiler-errors commented Feb 15, 2022

rust-highfive commented Feb 15, 2022

rust-highfive commented Feb 15, 2022

This comment has been minimized.

camelid commented Feb 16, 2022

aDotInTheVoid commented Feb 16, 2022

aDotInTheVoid commented Feb 16, 2022

compiler-errors commented Feb 20, 2022

This comment has been minimized.

camelid commented Feb 20, 2022

compiler-errors commented Feb 20, 2022

camelid commented Feb 20, 2022

camelid commented Feb 20, 2022

rust-timer commented Feb 20, 2022

bors commented Feb 20, 2022

bors commented Feb 21, 2022

rust-timer commented Feb 21, 2022

GuillaumeGomez commented Mar 3, 2022

bors commented Mar 3, 2022

bors commented Mar 4, 2022

bors commented Mar 4, 2022

rust-timer commented Mar 4, 2022

camelid commented Mar 4, 2022