Auto merge of #140565 - GuillaumeGomez:rollup-gv4ed14, r=GuillaumeGomez
Rollup of 12 pull requests Successful merges: - #138703 (chore: remove redundant words in comment) - #139186 (Refactor `diy_float`) - #139780 (docs: Add example to `Iterator::take` with `by_ref`) - #139802 (Fix some grammar errors and hyperlinks in doc for `trait Allocator`) - #140034 (simd_select_bitmask: the 'padding' bits in the mask are just ignored) - #140062 (std: mention `remove_dir_all` can emit `DirectoryNotEmpty` when concurrently written into) - #140420 (rustdoc: Fix doctest heuristic for main fn wrapping) - #140460 (Fix handling of LoongArch target features not supported by LLVM 19) - #140538 (rustc-dev-guide subtree update) - #140544 (Clean up "const" situation in format_args!(). ) - #140552 (allow `#[rustc_std_internal_symbol]` in combination with `#[naked]`) - #140556 (Improve error output in case `nodejs` or `npm` is not installed for rustdoc-gui test suite) r? `@ghost` `@rustbot` modify labels: rollup
This commit is contained in:
bors
commit
4530187fd4
|
|
@ -14,7 +14,7 @@ jobs:
|
|||
if: github.repository == 'rust-lang/rustc-dev-guide'
|
||||
runs-on: ubuntu-latest
|
||||
env:
|
||||
MDBOOK_VERSION: 0.4.21
|
||||
MDBOOK_VERSION: 0.4.48
|
||||
MDBOOK_LINKCHECK2_VERSION: 0.9.1
|
||||
MDBOOK_MERMAID_VERSION: 0.12.6
|
||||
MDBOOK_TOC_VERSION: 0.11.2
|
||||
|
|
|
|||
|
|
@ -194,7 +194,7 @@ impl GitSync {
|
|||
);
|
||||
println!(
|
||||
// Open PR with `subtree update` title to silence the `no-merges` triagebot check
|
||||
" https://github.com/{UPSTREAM_REPO}/compare/{github_user}:{branch}?quick_pull=1&title=Rustc+dev+guide+subtree+update&body=r?+@ghost"
|
||||
" https://github.com/{UPSTREAM_REPO}/compare/{github_user}:{branch}?quick_pull=1&title=rustc-dev-guide+subtree+update&body=r?+@ghost"
|
||||
);
|
||||
|
||||
drop(josh);
|
||||
|
|
|
|||
|
|
@ -1 +1 @@
|
|||
deb947971c8748f5c6203548ce4af9022f21eaf0
|
||||
0c33fe2c3d3eecadd17a84b110bb067288a64f1c
|
||||
|
|
|
|||
|
|
@ -157,6 +157,7 @@
|
|||
- [ADTs and Generic Arguments](./ty_module/generic_arguments.md)
|
||||
- [Parameter types/consts/regions](./ty_module/param_ty_const_regions.md)
|
||||
- [`TypeFolder` and `TypeFoldable`](./ty-fold.md)
|
||||
- [Aliases and Normalization](./normalization.md)
|
||||
- [Typing/Param Envs](./typing_parameter_envs.md)
|
||||
- [Type inference](./type-inference.md)
|
||||
- [Trait solving](./traits/resolution.md)
|
||||
|
|
@ -176,7 +177,6 @@
|
|||
- [Coinduction](./solve/coinduction.md)
|
||||
- [Caching](./solve/caching.md)
|
||||
- [Proof trees](./solve/proof-trees.md)
|
||||
- [Normalization](./solve/normalization.md)
|
||||
- [Opaque types](./solve/opaque-types.md)
|
||||
- [Significant changes and quirks](./solve/significant-changes.md)
|
||||
- [`Unsize` and `CoerceUnsized` traits](./traits/unsize.md)
|
||||
|
|
|
|||
|
|
@ -6,8 +6,8 @@ of the same compiler.
|
|||
|
||||
This raises a chicken-and-egg paradox: where did the first compiler come from?
|
||||
It must have been written in a different language. In Rust's case it was
|
||||
[written in OCaml][ocaml-compiler]. However it was abandoned long ago and the
|
||||
only way to build a modern version of rustc is a slightly less modern
|
||||
[written in OCaml][ocaml-compiler]. However, it was abandoned long ago, and the
|
||||
only way to build a modern version of rustc is with a slightly less modern
|
||||
version.
|
||||
|
||||
This is exactly how `x.py` works: it downloads the current beta release of
|
||||
|
|
|
|||
|
|
@ -8,8 +8,8 @@ the same compiler.
|
|||
|
||||
This raises a chicken-and-egg paradox: where did the first compiler come from?
|
||||
It must have been written in a different language. In Rust's case it was
|
||||
[written in OCaml][ocaml-compiler]. However it was abandoned long ago and the
|
||||
only way to build a modern version of `rustc` is a slightly less modern version.
|
||||
[written in OCaml][ocaml-compiler]. However, it was abandoned long ago, and the
|
||||
only way to build a modern version of `rustc` is with a slightly less modern version.
|
||||
|
||||
This is exactly how [`./x.py`] works: it downloads the current beta release of
|
||||
`rustc`, then uses it to compile the new compiler.
|
||||
|
|
|
|||
|
|
@ -62,21 +62,20 @@ huge. There is also the `rustc` crate which is the actual binary (i.e. the
|
|||
[`rustc_driver`] crate, which drives the various parts of compilation in other
|
||||
crates.
|
||||
|
||||
The dependency structure of these crates is complex, but roughly it is
|
||||
The dependency order of these crates is complex, but roughly it is
|
||||
something like this:
|
||||
|
||||
- `rustc` (the binary) calls [`rustc_driver::main`][main].
|
||||
- [`rustc_driver`] depends on a lot of other crates, but the main one is
|
||||
1. `rustc` (the binary) calls [`rustc_driver::main`][main].
|
||||
1. [`rustc_driver`] depends on a lot of other crates, but the main one is
|
||||
[`rustc_interface`].
|
||||
- [`rustc_interface`] depends on most of the other compiler crates. It
|
||||
is a fairly generic interface for driving the whole compilation.
|
||||
- Most of the other `rustc_*` crates depend on [`rustc_middle`],
|
||||
which defines a lot of central data structures in the compiler.
|
||||
- [`rustc_middle`] and most of the other crates depend on a
|
||||
handful of crates representing the early parts of the
|
||||
compiler (e.g. the parser), fundamental data structures (e.g.
|
||||
[`Span`]), or error reporting: [`rustc_data_structures`],
|
||||
[`rustc_span`], [`rustc_errors`], etc.
|
||||
1. [`rustc_interface`] depends on most of the other compiler crates. It is a
|
||||
fairly generic interface for driving the whole compilation.
|
||||
1. Most of the other `rustc_*` crates depend on [`rustc_middle`], which defines
|
||||
a lot of central data structures in the compiler.
|
||||
1. [`rustc_middle`] and most of the other crates depend on a handful of crates
|
||||
representing the early parts of the compiler (e.g. the parser), fundamental
|
||||
data structures (e.g. [`Span`]), or error reporting:
|
||||
[`rustc_data_structures`], [`rustc_span`], [`rustc_errors`], etc.
|
||||
|
||||
[`rustc_data_structures`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_data_structures/index.html
|
||||
[`rustc_driver`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/index.html
|
||||
|
|
@ -87,8 +86,12 @@ something like this:
|
|||
[`Span`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_span/struct.Span.html
|
||||
[main]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/fn.main.html
|
||||
|
||||
You can see the exact dependencies by reading the [`Cargo.toml`] for the various
|
||||
crates, just like a normal Rust crate.
|
||||
You can see the exact dependencies by running `cargo tree`,
|
||||
just like you would for any other Rust package:
|
||||
|
||||
```console
|
||||
cargo tree --package rustc_driver
|
||||
```
|
||||
|
||||
One final thing: [`src/llvm-project`] is a submodule for our fork of LLVM.
|
||||
During bootstrapping, LLVM is built and the [`compiler/rustc_llvm`] crate
|
||||
|
|
|
|||
|
|
@ -193,6 +193,23 @@ When a user runs `cargo fix --edition`, cargo will pass the `--force-warn rust-2
|
|||
flag to force all of these lints to appear during the edition migration.
|
||||
Cargo also passes `--cap-lints=allow` so that no other lints interfere with the edition migration.
|
||||
|
||||
Make sure that the example code sets the correct edition. The example should illustrate the previous edition, and show what the migration warning would look like. For example, this lint for a 2024 migration shows an example in 2021:
|
||||
|
||||
```rust,ignore
|
||||
declare_lint! {
|
||||
/// The `keyword_idents_2024` lint detects ...
|
||||
///
|
||||
/// ### Example
|
||||
///
|
||||
/// ```rust,edition2021
|
||||
/// #![warn(keyword_idents_2024)]
|
||||
/// fn gen() {}
|
||||
/// ```
|
||||
///
|
||||
/// {{produces}}
|
||||
}
|
||||
```
|
||||
|
||||
Migration lints can be either `Allow` or `Warn` by default.
|
||||
If it is `Allow`, users usually won't see this warning unless they are doing an edition migration
|
||||
manually or there is a problem during the migration.
|
||||
|
|
@ -334,3 +351,40 @@ In general it is recommended to avoid these special cases except for very high v
|
|||
[into-iter]: https://doc.rust-lang.org/nightly/edition-guide/rust-2021/IntoIterator-for-arrays.html
|
||||
[panic-macro]: https://doc.rust-lang.org/nightly/edition-guide/rust-2021/panic-macro-consistency.html
|
||||
[`non_fmt_panics`]: https://doc.rust-lang.org/nightly/rustc/lints/listing/warn-by-default.html#non-fmt-panics
|
||||
|
||||
### Migrating the standard library edition
|
||||
|
||||
Updating the edition of the standard library itself roughly involves the following process:
|
||||
|
||||
- Wait until the newly stabilized edition has reached beta and the bootstrap compiler has been updated.
|
||||
- Apply migration lints. This can be an involved process since some code is in external submodules[^std-submodules], and the standard library makes heavy use of conditional compilation. Also, running `cargo fix --edition` can be impractical on the standard library itself. One approach is to individually add `#![warn(...)]` at the top of each crate for each lint, run `./x check library`, apply the migrations, remove the `#![warn(...)]` and commit each migration separately. You'll likely need to run `./x check` with `--target` for many different targets to get full coverage (otherwise you'll likely spend days or weeks getting CI to pass)[^ed-docker]. See also the [advanced migration guide] for more tips.
|
||||
- Apply migrations to [`backtrace-rs`]. [Example for 2024](https://github.com/rust-lang/backtrace-rs/pull/700). Note that this doesn't update the edition of the crate itself because that is published independently on crates.io, and that would otherwise restrict the minimum Rust version. Consider adding some `#![deny()]` attributes to avoid regressions until its edition gets updated.
|
||||
- Apply migrations to [`stdarch`], and update its edition, and formatting. [Example for 2024](https://github.com/rust-lang/stdarch/pull/1710).
|
||||
- Post PRs to update the backtrace and stdarch submodules, and wait for those to land.
|
||||
- Apply migration lints to the standard library crates, and update their edition. I recommend working one crate at a time starting with `core`. [Example for 2024](https://github.com/rust-lang/rust/pull/138162).
|
||||
|
||||
[^std-submodules]: This will hopefully change in the future to pull these submodules into `rust-lang/rust`.
|
||||
[^ed-docker]: You'll also likely need to do a lot of testing for different targets, and this is where [docker testing](../tests/docker.md) comes in handy.
|
||||
|
||||
[advanced migration guide]: https://doc.rust-lang.org/nightly/edition-guide/editions/advanced-migrations.html
|
||||
[`backtrace-rs`]: https://github.com/rust-lang/backtrace-rs/
|
||||
[`stdarch`]: https://github.com/rust-lang/stdarch/
|
||||
|
||||
## Stabilizing an edition
|
||||
|
||||
After the edition team has given the go-ahead, the process for stabilizing an edition is roughly:
|
||||
|
||||
- Update [`LATEST_STABLE_EDITION`].
|
||||
- Update [`Edition::is_stable`].
|
||||
- Hunt and find any document that refers to edition by number, and update it:
|
||||
- [`--edition` flag](https://github.com/rust-lang/rust/blob/master/src/doc/rustc/src/command-line-arguments.md#--edition-specify-the-edition-to-use)
|
||||
- [Rustdoc attributes](https://github.com/rust-lang/rust/blob/master/src/doc/rustdoc/src/write-documentation/documentation-tests.md#attributes)
|
||||
- Clean up any tests that use the `//@ edition` header to remove the `-Zunstable-options` flag to ensure they are indeed stable. Note: Ideally this should be automated, see [#133582].
|
||||
- Bless any tests that change.
|
||||
- Update `lint-docs` to default to the new edition.
|
||||
|
||||
See [example for 2024](https://github.com/rust-lang/rust/pull/133349).
|
||||
|
||||
[`LATEST_STABLE_EDITION`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_span/edition/constant.LATEST_STABLE_EDITION.html
|
||||
[`Edition::is_stable`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_span/edition/enum.Edition.html#method.is_stable
|
||||
[#133582]: https://github.com/rust-lang/rust/issues/133582
|
||||
|
|
|
|||
|
|
@ -0,0 +1,309 @@
|
|||
# Aliases and Normalization
|
||||
|
||||
<!-- toc -->
|
||||
|
||||
## Aliases
|
||||
|
||||
In Rust there are a number of types that are considered equal to some "underlying" type, for example inherent associated types, trait associated types, free type aliases (`type Foo = u32`), and opaque types (`-> impl RPIT`). We consider such types to be "aliases", alias types are represented by the [`TyKind::Alias`][tykind_alias] variant, with the kind of alias tracked by the [`AliasTyKind`][aliaskind] enum.
|
||||
|
||||
Normalization is the process of taking these alias types and replacing them with the underlying type that they are equal to. For example given some type alias `type Foo = u32`, normalizing `Foo` would give `u32`.
|
||||
|
||||
The concept of an alias is not unique to *types* and the concept also applies to constants/const generics. However, right now in the compiler we don't really treat const aliases as a "first class concept" so this chapter mostly discusses things in the context of types (even though the concepts transfer just fine).
|
||||
|
||||
[tykind_alias]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_type_ir/enum.TyKind.html#variant.Alias
|
||||
[aliaskind]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_type_ir/enum.AliasTyKind.html
|
||||
|
||||
### Rigid, Ambiguous and Unnormalized Aliases
|
||||
|
||||
Aliases can either be "rigid", "ambiguous", or simply unnormalized.
|
||||
|
||||
We consider types to be rigid if their "shape" isn't going to change, for example `Box` is rigid as no amount of normalization can turn a `Box` into a `u32`, whereas `<vec::IntoIter<u32> as Iterator>::Item` is not rigid as it can be normalized to `u32`.
|
||||
|
||||
Aliases are rigid when we will never be able to normalize them further. A concrete example of a *rigid* alias would be `<T as Iterator>::Item` in an environment where there is no `T: Iterator<Item = ...>` bound, only a `T: Iterator` bound:
|
||||
```rust
|
||||
fn foo<T: Iterator>() {
|
||||
// This alias is *rigid*
|
||||
let _: <T as Iterator>::Item;
|
||||
}
|
||||
|
||||
fn bar<T: Iterator<Item = u32>>() {
|
||||
// This alias is *not* rigid as it can be normalized to `u32`
|
||||
let _: <T as Iterator>::Item;
|
||||
}
|
||||
```
|
||||
|
||||
When an alias can't yet be normalized but may wind up normalizable in the [current environment](./typing_parameter_envs.md), we consider it to be an "ambiguous" alias. This can occur when an alias contains inference variables which prevent being able to determine how the trait is implemented:
|
||||
```rust
|
||||
fn foo<T: Iterator, U: Iterator>() {
|
||||
// This alias is considered to be "ambiguous"
|
||||
let _: <_ as Iterator>::Item;
|
||||
}
|
||||
```
|
||||
|
||||
The reason we call them "ambiguous" aliases is because its *ambiguous* whether this is a rigid alias or not.
|
||||
|
||||
The source of the `_: Iterator` trait impl is *ambiguous* (i.e. unknown), it could be some `impl Iterator for u32` or it could be some `T: Iterator` trait bound, we don't know yet. Depending on why `_: Iterator` holds the alias could be an unnormalized alias or it could be a rigid alias; it's *ambiguous* what kind of alias this is.
|
||||
|
||||
Finally, an alias can just be unnormalized, `<Vec<u32> as IntoIterator>::Iter` is an unnormalized alias as it can already be normalized to `std::vec::IntoIter<u32>`, it just hasn't been done yet.
|
||||
|
||||
---
|
||||
|
||||
It is worth noting that Free and Inherent aliases cannot be rigid or ambiguous as naming them also implies having resolved the definition of the alias, which specifies the underlying type of the alias.
|
||||
|
||||
### Diverging Aliases
|
||||
|
||||
An alias is considered to "diverge" if its definition does not specify an underlying non-alias type to normalize to. A concrete example of diverging aliases:
|
||||
```rust
|
||||
type Diverges = Diverges;
|
||||
|
||||
trait Trait {
|
||||
type DivergingAssoc;
|
||||
}
|
||||
impl Trait for () {
|
||||
type DivergingAssoc = <() as Trait>::DivergingAssoc;
|
||||
}
|
||||
```
|
||||
In this example both `Diverges` and `DivergingAssoc` are "trivial" cases of diverging type aliases where they have been defined as being equal to themselves. There is no underlying type that `Diverges` can ever be normalized to.
|
||||
|
||||
We generally try to error when diverging aliases are defined, but this is entirely a "best effort" check. In the previous example the definitions are "simple enough" to be detected and so errors are emitted. However, in more complex cases, or cases where only some instantiations of generic parameters would result in a diverging alias, we don't emit an error:
|
||||
```rust
|
||||
trait Trait {
|
||||
type DivergingAssoc<U: Trait>;
|
||||
}
|
||||
impl<T: ?Sized> Trait for T {
|
||||
// This alias always diverges but we don't emit an error because
|
||||
// the compiler can't "see" that.
|
||||
type DivergingAssoc<U: Trait> = <U as Trait>::DivergingAssoc<U>;
|
||||
}
|
||||
```
|
||||
|
||||
Ultimately this means that we have no guarantee that aliases in the type system are non-diverging. As aliases may only diverge for some specific generic arguments, it also means that we only know whether an alias diverges once it is fully concrete. This means that codegen/const-evaluation also has to handle diverging aliases:
|
||||
```rust
|
||||
trait Trait {
|
||||
type Diverges<U: Trait>;
|
||||
}
|
||||
impl<T: ?Sized> Trait for T {
|
||||
type Diverges<U: Trait> = <U as Trait>::Diverges<U>;
|
||||
}
|
||||
|
||||
fn foo<T: Trait>() {
|
||||
let a: T::Diverges<T>;
|
||||
}
|
||||
|
||||
fn main() {
|
||||
foo::<()>();
|
||||
}
|
||||
```
|
||||
In this example we only encounter an error from the diverging alias during codegen of `foo::<()>`, if the call to `foo` is removed then no compilation error will be emitted.
|
||||
|
||||
### Opaque Types
|
||||
|
||||
Opaque types are a relatively special kind of alias, and are covered in their own chapter: [Opaque types](./opaque-types-type-alias-impl-trait.md).
|
||||
|
||||
### Const Aliases
|
||||
|
||||
Unlike type aliases, const aliases are not represented directly in the type system, instead const aliases are always an anonymous body containing a path expression to a const item. This means that the only "const alias" in the type system is an anonymous unevaluated const body.
|
||||
|
||||
As such there is no `ConstKind::Alias(AliasCtKind::Projection/Inherent/Free, _)`, instead we only have `ConstKind::Unevaluated` which is used for representing anonymous constants.
|
||||
|
||||
```rust
|
||||
fn foo<const N: usize>() {}
|
||||
|
||||
const FREE_CONST: usize = 1 + 1;
|
||||
|
||||
fn bar() {
|
||||
foo::<{ FREE_CONST }>();
|
||||
// The const arg is represented with some anonymous constant:
|
||||
// ```pseudo-rust
|
||||
// const ANON: usize = FREE_CONST;
|
||||
// foo::<ConstKind::Unevaluated(DefId(ANON), [])>();
|
||||
// ```
|
||||
}
|
||||
```
|
||||
|
||||
This is likely to change as const generics functionality is improved, for example `feature(associated_const_equality)` and `feature(min_generic_const_args)` both require handling const aliases similarly to types (without an anonymous constant wrapping all const args).
|
||||
|
||||
## What is Normalization
|
||||
|
||||
### Structural vs Deep normalization
|
||||
|
||||
There are two forms of normalization, structural (sometimes called *shallow*) and deep. Structural normalization should be thought of as only normalizing the "outermost" part of a type. On the other hand deep normalization will normalize *all* aliases in a type.
|
||||
|
||||
In practice structural normalization can result in more than just the outer layer of the type being normalized, but this behaviour should not be relied upon. Unnormalizable non-rigid aliases making use of bound variables (`for<'a>`) cannot be normalized by either kind of normalization.
|
||||
|
||||
As an example: conceptually, structurally normalizing the type `Vec<<u8 as Identity>::Assoc>` would be a no-op, whereas deeply normalizing would give `Vec<u8>`. In practice even structural normalization would give `Vec<u8>`, though, again, this should not be relied upon.
|
||||
|
||||
Changing the alias to use bound variables will result in different behaviour; `Vec<for<'a> fn(<&'a u8 as Identity>::Assoc)>` would result in no change when structurally normalized, but would result in `Vec<for<'a> fn(&'a u8)>` when deeply normalized.
|
||||
|
||||
### Core normalization logic
|
||||
|
||||
Structurally normalizing aliases is a little bit more nuanced than replacing the alias with whatever it is defined as being equal to in its definition; the result of normalizing an alias should either be a rigid type or an inference variable (which will later be inferred to a rigid type). To accomplish this we do two things:
|
||||
|
||||
First, when normalizing an ambiguous alias it is normalized to an inference variable instead of leaving it as-is, this has two main effects:
|
||||
- Even though an inference variable is not a rigid type, it will always wind up inferred *to* a rigid type so we ensure that the result of normalization will not need to be normalized again
|
||||
- Inference variables are used in all cases where a type is non-rigid, allowing the rest of the compiler to not have to deal with *both* ambiguous aliases *and* inference variables
|
||||
|
||||
Secondly, instead of having normalization directly return the type specified in the definition of the alias, we normalize the type first before returning it[^1]. We do this so that normalization is idempotent/callers do not need to run it in a loop.
|
||||
|
||||
```rust
|
||||
#![feature(lazy_type_alias)]
|
||||
|
||||
type Foo<T: Iterator> = Bar<T>;
|
||||
type Bar<T: Iterator> = <T as Iterator>::Item;
|
||||
|
||||
fn foo() {
|
||||
let a_: Foo<_>;
|
||||
}
|
||||
```
|
||||
|
||||
In this example:
|
||||
- Normalizing `Foo<?x>` would result in `Bar<?x>`, except we want to normalize aliases in the type `Foo` is defined as equal to
|
||||
- Normalizing `Bar<?x>` would result in `<?x as Iterator>::Item`, except, again, we want to normalize aliases in the type `Bar` is defined as equal to
|
||||
- Normalizing `<?x as Iterator>::Item` results in some new inference variable `?y`, as `<?x as Iterator>::Item` is an ambiguous alias
|
||||
- The final result is that normalizing `Foo<?x>` results in `?y`
|
||||
|
||||
## How to normalize
|
||||
|
||||
When interfacing with the type system it will often be the case that it's necessary to request a type be normalized. There are a number of different entry points to the underlying normalization logic and each entry point should only be used in specific parts of the compiler.
|
||||
|
||||
An additional complication is that the compiler is currently undergoing a transition from the old trait solver to the new trait solver. As part of this transition our approach to normalization in the compiler has changed somewhat significantly, resulting in some normalization entry points being "old solver only" slated for removal in the long-term once the new solver has stabilized.
|
||||
|
||||
Here is a rough overview of the different entry points to normalization in the compiler:
|
||||
- `infcx.at.structurally_normalize`
|
||||
- `infcx.at.(deeply_)?normalize`
|
||||
- `infcx.query_normalize`
|
||||
- `tcx.normalize_erasing_regions`
|
||||
- `traits::normalize_with_depth(_to)`
|
||||
- `EvalCtxt::structurally_normalize`
|
||||
|
||||
### Outside of the trait solver
|
||||
|
||||
The [`InferCtxt`][infcx] type exposes the "main" ways to normalize during analysis: [`normalize`][normalize], [`deeply_normalize`][deeply_normalize] and [`structurally_normalize`][structurally_normalize]. These functions are often wrapped and re-exposed on various `InferCtxt` wrapper types, such as [`FnCtxt`][fcx] or [`ObligationCtxt`][ocx] with minor API tweaks to handle some arguments or parts of the return type automatically.
|
||||
|
||||
#### Structural `InferCtxt` normalization
|
||||
|
||||
[`infcx.at.structurally_normalize`][structurally_normalize] exposes structural normalization that is able to handle inference variables and regions. It should generally be used whenever inspecting the kind of a type.
|
||||
|
||||
Inside of HIR Typeck there is a related method of normalization- [`fcx.structurally_resolve`][structurally_resolve], which will error if the type being resolved is an unresolved inference variable. When the new solver is enabled it will also attempt to structurally normalize the type.
|
||||
|
||||
Due to this there is a pattern in HIR typeck where a type is first normalized via `normalize` (only normalizing in the old solver), and then `structurally_resolve`'d (only normalizing in the new solver). This pattern should be preferred over calling `structurally_normalize` during HIR typeck as `structurally_resolve` will attempt to make inference progress by evaluating goals whereas `structurally_normalize` does not.
|
||||
|
||||
#### Deep `InferCtxt` normalization
|
||||
|
||||
##### `infcx.at.(deeply_)?normalize`
|
||||
|
||||
There are two ways to deeply normalize with an `InferCtxt`, `normalize` and `deeply_normalize`. The reason for this is that `normalize` is a "legacy" normalization entry point used only by the old solver, whereas `deeply_normalize` is intended to be the long term way to deeply normalize. Both of these methods can handle regions.
|
||||
|
||||
When the new solver is stabilized the `infcx.at.normalize` function will be removed and everything will have been migrated to the new deep or structural normalization methods. For this reason the `normalize` function is a no-op under the new solver, making it suitable only when the old solver needs normalization but the new solver does not.
|
||||
|
||||
Using `deeply_normalize` will result in errors being emitted when encountering ambiguous aliases[^2] as it is not possible to support normalizing *all* ambiguous aliases to inference variables[^3]. `deeply_normalize` should generally only be used in cases where we do not expect to encounter ambiguous aliases, for example when working with types from item signatures.
|
||||
|
||||
##### `infcx.query_normalize`
|
||||
|
||||
[`infcx.query_normalize`][query_norm] is very rarely used, it has almost all the same restrictions as `normalize_erasing_regions` (cannot handle inference variables, no diagnostics support) with the main difference being that it retains lifetime information. For this reason `normalize_erasing_regions` is the better choice in almost all circumstances as it is more efficient due to caching lifetime-erased queries.
|
||||
|
||||
In practice `query_normalize` is used for normalization in the borrow checker, and elsewhere as a performance optimization over `infcx.normalize`. Once the new solver is stabilized it is expected that `query_normalize` can be removed from the compiler as the new solvers normalization implementation should be performant enough for it to not be a performance regression.
|
||||
|
||||
##### `tcx.normalize_erasing_regions`
|
||||
|
||||
[`normalize_erasing_regions`][norm_erasing_regions] is generally used by parts of the compiler that are not doing type system analysis. This normalization entry point does not handle inference variables, lifetimes, or any diagnostics. Lints and codegen make heavy use of this entry point as they typically are working with fully inferred aliases that can be assumed to be well formed (or at least, are not responsible for erroring on).
|
||||
|
||||
[query_norm]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_trait_selection/infer/at/struct.At.html#method.query_normalize
|
||||
[norm_erasing_regions]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.TyCtxt.html#method.normalize_erasing_regions
|
||||
[normalize]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_trait_selection/infer/at/struct.At.html#method.normalize
|
||||
[deeply_normalize]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_trait_selection/traits/normalize/trait.NormalizeExt.html#tymethod.deeply_normalize
|
||||
[structurally_normalize]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_trait_selection/traits/trait.StructurallyNormalizeExt.html#tymethod.structurally_normalize_ty
|
||||
[infcx]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_trait_selection/infer/struct.InferCtxt.html
|
||||
[fcx]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_typeck/fn_ctxt/struct.FnCtxt.html
|
||||
[ocx]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_trait_selection/traits/struct.ObligationCtxt.html
|
||||
[structurally_resolve]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_typeck/fn_ctxt/struct.FnCtxt.html#method.structurally_resolve_type
|
||||
|
||||
### Inside of the trait solver
|
||||
|
||||
[`traits::normalize_with_depth(_to)`][norm_with_depth] and [`EvalCtxt::structurally_normalize`][eval_ctxt_structural_norm] are only used by the internals of the trait solvers (old and new respectively). It is effectively a raw entry point to the internals of how normalization is implemented by each trait solver. Other normalization entry points cannot be used from within the internals of trait solving as it wouldn't handle goal cycles and recursion depth correctly.
|
||||
|
||||
[norm_with_depth]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_trait_selection/traits/normalize/fn.normalize_with_depth.html
|
||||
[eval_ctxt_structural_norm]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_next_trait_solver/solve/struct.EvalCtxt.html#method.structurally_normalize_term
|
||||
|
||||
## When/Where to normalize (Old vs New solver)
|
||||
|
||||
One of the big changes between the old and new solver is our approach to when we expect aliases to be normalized.
|
||||
|
||||
### Old solver
|
||||
|
||||
All types are expected to be normalized as soon as possible, so that all types encountered in the type system are either rigid or an inference variable (which will later be inferred to a rigid term).
|
||||
|
||||
As a concrete example: equality of aliases is implemented by assuming they're rigid and recursively equating the generic arguments of the alias.
|
||||
|
||||
### New solver
|
||||
|
||||
It's expected that all types potentially contain ambiguous or unnormalized aliases. Whenever an operation is performed that requires aliases to be normalized, it's the responsibility of that logic to normalize the alias (this means that matching on `ty.kind()` pretty much always has to structurally normalize first).
|
||||
|
||||
As a concrete example: equality of aliases is implemented by a custom goal kind ([`PredicateKind::AliasRelate`][aliasrelate]) so that it can handle normalization of the aliases itself instead of assuming all alias types being equated are rigid.
|
||||
|
||||
Despite this approach we still deeply normalize during [writeback][writeback] for performance/simplicity, so that types in the MIR can still be assumed to have been deeply normalized.
|
||||
|
||||
[aliasrelate]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/type.PredicateKind.html#variant.AliasRelate
|
||||
[writeback]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_typeck/writeback/index.html
|
||||
|
||||
---
|
||||
|
||||
There were a few main issues with the old solver's approach to normalization that motivated changing things in the new solver:
|
||||
|
||||
### Missing normalization calls
|
||||
|
||||
It was a frequent occurrence that normalization calls would be missing, resulting in passing unnormalized types to APIs expecting everything to already be normalized. Treating ambiguous or unnormalized aliases as rigid would result in all sorts of weird errors from aliases not being considered equal to one another, or surprising inference guidance from equating unnormalized aliases' generic arguments.
|
||||
|
||||
### Normalizing parameter environments
|
||||
|
||||
Another problem was that it was not possible to normalize `ParamEnv`s correctly in the old solver as normalization itself would expect a normalized `ParamEnv` in order to give correct results. See the chapter on `ParamEnv`s for more information: [`Typing/ParamEnv`s: Normalizing all bounds](./typing_parameter_envs.md#normalizing-all-bounds)
|
||||
|
||||
### Unnormalizable non-rigid aliases in higher ranked types
|
||||
|
||||
Given a type such as `for<'a> fn(<?x as Trait<'a>::Assoc>)`, it is not possible to correctly handle this with the old solver's approach to normalization.
|
||||
|
||||
If we were to normalize it to `for<'a> fn(?y)` and register a goal to normalize `for<'a> <?x as Trait<'a>>::Assoc -> ?y`, this would result in errors in cases where `<?x as Trait<'a>>::Assoc` normalized to `&'a u32`. The inference variable `?y` would be in a lower [universe][universes] than the placeholders made when instantiating the `for<'a>` binder.
|
||||
|
||||
Leaving the alias unnormalized would also be wrong as the old solver expects all aliases to be rigid. This was a soundness bug before the new solver was stabilized in coherence: [relating projection substs is unsound during coherence](https://github.com/rust-lang/rust/issues/102048).
|
||||
|
||||
Ultimately this means that it is not always possible to ensure all aliases inside of a value are rigid.
|
||||
|
||||
[universes]: https://rustc-dev-guide.rust-lang.org/borrow_check/region_inference/placeholders_and_universes.html#what-is-a-universe
|
||||
[deeply_normalize]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_trait_selection/traits/normalize/trait.NormalizeExt.html#tymethod.deeply_normalize
|
||||
|
||||
## Handling uses of diverging aliases
|
||||
|
||||
Diverging aliases, like ambiguous aliases, are normalized to inference variables. As normalizing diverging aliases results in trait solver cycles, it always results in an error in the old solver. In the new solver it only results in an error if we wind up requiring all goals to hold in the current context. E.g. normalizing diverging aliases during HIR typeck will result in an error in both solvers.
|
||||
|
||||
Alias well formedness doesn't require that the alias doesn't diverge[^4], this means that checking an alias is well formed isn't sufficient to cause an error to be emitted for diverging aliases; actually attempting to normalize the alias is required.
|
||||
|
||||
Erroring on diverging aliases being a side effect of normalization means that it is very *arbitrary* whether we actually emit an error, it also differs between the old and new solver as we now normalize in less places.
|
||||
|
||||
An example of the ad-hoc nature of erroring on diverging aliases causing "problems":
|
||||
```rust
|
||||
trait Trait {
|
||||
type Diverges<D: Trait>;
|
||||
}
|
||||
|
||||
impl<T> Trait for T {
|
||||
type Diverges<D: Trait> = D::Diverges<D>;
|
||||
}
|
||||
|
||||
struct Bar<T: ?Sized = <u8 as Trait>::Diverges<u8>>(Box<T>);
|
||||
```
|
||||
|
||||
In this example a diverging alias is used but we happen to not emit an error as we never explicitly normalize the defaults of generic parameters. If the `?Sized` opt out is removed then an error is emitted because we wind up happening to normalize a `<u8 as Trait>::Diverges<u8>: Sized` goal which as a side effect results in erroring about the diverging alias.
|
||||
|
||||
Const aliases differ from type aliases a bit here; well formedness of const aliases requires that they can be successfully evaluated (via [`ConstEvaluatable`][const_evaluatable] goals). This means that simply checking well formedness of const arguments is sufficient to error if they would fail to evaluate. It is somewhat unclear whether it would make sense to adopt this for type aliases too or if const aliases should stop requiring this for well formedness[^5].
|
||||
|
||||
[^1]: In the new solver this is done implicitly
|
||||
|
||||
[^2]: There is a subtle difference in how ambiguous aliases in binders are handled between old and new solver. In the old solver we fail to error on some ambiguous aliases inside of higher ranked types whereas the new solver correctly errors.
|
||||
|
||||
[^3]: Ambiguous aliases inside of binders cannot be normalized to inference variables, this will be covered more later.
|
||||
|
||||
[^4]: As checking aliases are non-diverging cannot be done until they are fully concrete, this would either imply that we cant check aliases are well formed before codegen/const-evaluation or that aliases would go from being well-formed to not well-formed after monomorphization.
|
||||
|
||||
[^5]: Const aliases certainly wouldn't be *less* sound than type aliases if we stopped doing this
|
||||
|
||||
[const_evaluatable]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/type.ClauseKind.html#variant.ConstEvaluatable
|
||||
|
|
@ -1,127 +0,0 @@
|
|||
# Normalization in the new solver
|
||||
|
||||
> FIXME: Normalization has been changed significantly since this chapter was written.
|
||||
|
||||
With the new solver we've made some fairly significant changes to normalization when compared
|
||||
to the existing implementation.
|
||||
|
||||
We now differentiate between "one-step normalization", "structural normalization" and
|
||||
"deep normalization".
|
||||
|
||||
## One-step normalization
|
||||
|
||||
One-step normalization is implemented via `NormalizesTo` goals. Unlike other goals
|
||||
in the trait solver, `NormalizesTo` always expects the term to be an unconstrained
|
||||
inference variable[^opaques]. Think of it as a function, taking an alias as input
|
||||
and returning its underlying value. If the alias is rigid, `NormalizesTo` fails and
|
||||
returns `NoSolution`. This is the case for `<T as Trait>::Assoc` if there's a `T: Trait`
|
||||
where-bound and for opaque types with `Reveal::UserFacing` unless they are in the
|
||||
defining scope. We must not treat any aliases as rigid in coherence.
|
||||
|
||||
The underlying value may itself be an unnormalized alias, e.g.
|
||||
`NormalizesTo(<<() as Id>::This as Id>::This)` only returns `<() as Id>::This`,
|
||||
even though that alias can be further normalized to `()`. As the term is
|
||||
always an unconstrained inference variable, the expected term cannot influence
|
||||
normalization, see [trait-system-refactor-initiative#22] for more.
|
||||
|
||||
Only ever computing `NormalizesTo` goals with an unconstrained inference variable
|
||||
requires special solver support. It is only used by `AliasRelate` goals and pending
|
||||
`NormalizesTo` goals are tracked separately from other goals: [source][try-eval-norm].
|
||||
As the expected term is always erased in `NormalizesTo`, we have to return its
|
||||
ambiguous nested goals to its caller as not doing so weakens inference. See
|
||||
[#122687] for more details.
|
||||
|
||||
[trait-system-refactor-initiative#22]: https://github.com/rust-lang/trait-system-refactor-initiative/issues/22
|
||||
[try-eval-norm]: https://github.com/rust-lang/rust/blob/2627e9f3012a97d3136b3e11bf6bd0853c38a534/compiler/rustc_trait_selection/src/solve/eval_ctxt/mod.rs#L523-L537
|
||||
[#122687]: https://github.com/rust-lang/rust/pull/122687
|
||||
|
||||
## `AliasRelate` and structural normalization
|
||||
|
||||
We structurally normalize an alias by applying one-step normalization until
|
||||
we end up with a rigid alias, ambiguity, or overflow. This is done by repeatedly
|
||||
evaluating `NormalizesTo` goals inside of a snapshot: [source][structural_norm].
|
||||
|
||||
`AliasRelate(lhs, rhs)` is implemented by first structurally normalizing both the
|
||||
`lhs` and the `rhs` and then relating the resulting rigid types (or inference
|
||||
variables). Importantly, if `lhs` or `rhs` ends up as an alias, this alias can
|
||||
now be treated as rigid and gets unified without emitting a nested `AliasRelate`
|
||||
goal: [source][structural-relate].
|
||||
|
||||
This means that `AliasRelate` with an unconstrained `rhs` ends up functioning
|
||||
similar to `NormalizesTo`, acting as a function which fully normalizes `lhs`
|
||||
before assigning the resulting rigid type to an inference variable. This is used by
|
||||
`fn structurally_normalize_ty` both [inside] and [outside] of the trait solver.
|
||||
This has to be used whenever we match on the value of some type, both inside
|
||||
and outside of the trait solver.
|
||||
|
||||
<!--
|
||||
FIXME: structure, maybe we should have an "alias handling" chapter instead as
|
||||
talking about normalization without explaining that doesn't make too much
|
||||
sense.
|
||||
|
||||
FIXME: it is likely that this will subtly change again by mostly moving structural
|
||||
normalization into `NormalizesTo`.
|
||||
-->
|
||||
|
||||
[structural_norm]: https://github.com/rust-lang/rust/blob/2627e9f3012a97d3136b3e11bf6bd0853c38a534/compiler/rustc_trait_selection/src/solve/alias_relate.rs#L140-L175
|
||||
[structural-relate]: https://github.com/rust-lang/rust/blob/a0569fa8f91b5271e92d2f73fd252de7d3d05b9c/compiler/rustc_trait_selection/src/solve/alias_relate.rs#L88-L107
|
||||
[inside]: https://github.com/rust-lang/rust/blob/a0569fa8f91b5271e92d2f73fd252de7d3d05b9c/compiler/rustc_trait_selection/src/solve/mod.rs#L278-L299
|
||||
[outside]: https://github.com/rust-lang/rust/blob/a0569fa8f91b5271e92d2f73fd252de7d3d05b9c/compiler/rustc_trait_selection/src/traits/structural_normalize.rs#L17-L48
|
||||
|
||||
## Deep normalization
|
||||
|
||||
By walking over a type, and using `fn structurally_normalize_ty` for each encountered
|
||||
alias, it is possible to deeply normalize a type, normalizing all aliases as much as
|
||||
possible. However, this only works for aliases referencing bound variables if they are
|
||||
not ambiguous as we're unable to replace the alias with a corresponding inference
|
||||
variable without leaking universes.
|
||||
|
||||
<!--
|
||||
FIXME: we previously had to also be careful about instantiating the new inference
|
||||
variable with another normalizeable alias. Due to our recent changes to generalization,
|
||||
this should not be the case anymore. Equating an inference variable with an alias
|
||||
now always uses `AliasRelate` to fully normalize the alias before instantiating the
|
||||
inference variable: [source][generalize-no-alias]
|
||||
-->
|
||||
|
||||
[generalize-no-alias]: https://github.com/rust-lang/rust/blob/a0569fa8f91b5271e92d2f73fd252de7d3d05b9c/compiler/rustc_infer/src/infer/relate/generalize.rs#L353-L358
|
||||
|
||||
## Outside of the trait solver
|
||||
|
||||
The core type system - relating types and trait solving - will not need deep
|
||||
normalization with the new solver. There are still some areas which depend on it.
|
||||
For these areas there is the function `At::deeply_normalize`. Without additional
|
||||
trait solver support deep normalization does not always work in case of ambiguity.
|
||||
Luckily deep normalization is currently only necessary in places where there is no ambiguity.
|
||||
`At::deeply_normalize` immediately fails if there's ambiguity.
|
||||
|
||||
If we only care about the outermost layer of types, we instead use
|
||||
`At::structurally_normalize` or `FnCtxt::(try_)structurally_resolve_type`.
|
||||
Unlike `At::deeply_normalize`, structural normalization is also used in cases where we
|
||||
have to handle ambiguity.
|
||||
|
||||
Because this may result in behavior changes depending on how the trait solver handles
|
||||
ambiguity, it is safer to also require full normalization there. This happens in
|
||||
`FnCtxt::structurally_resolve_type` which always emits a hard error if the self type ends
|
||||
up as an inference variable. There are some existing places which have a fallback for
|
||||
inference variables instead. These places use `try_structurally_resolve_type` instead.
|
||||
|
||||
## Why deep normalization with ambiguity is hard
|
||||
|
||||
Fully correct deep normalization is very challenging, especially with the new solver
|
||||
given that we do not want to deeply normalize inside of the solver. Mostly deeply normalizing
|
||||
but sometimes failing to do so is bound to cause very hard to minimize and understand bugs.
|
||||
If possible, avoiding any reliance on deep normalization entirely therefore feels preferable.
|
||||
|
||||
If the solver itself does not deeply normalize, any inference constraints returned by the
|
||||
solver would require normalization. Handling this correctly is ugly. This also means that
|
||||
we change goals we provide to the trait solver by "normalizing away" some projections.
|
||||
|
||||
The way we (mostly) guarantee deep normalization with the old solver is by eagerly replacing
|
||||
the projection with an inference variable and emitting a nested `Projection` goal. This works
|
||||
as `Projection` goals in the old solver deeply normalize. Unless we add another `PredicateKind`
|
||||
for deep normalization to the new solver we cannot emulate this behavior. This does not work
|
||||
for projections with bound variables, sometimes leaving them unnormalized. An approach which
|
||||
also supports projections with bound variables will be even more involved.
|
||||
|
||||
[^opaques]: opaque types are currently handled a bit differently. this may change in the future
|
||||
|
|
@ -106,4 +106,4 @@ their ambiguous nested goals are returned to the caller which then evaluates the
|
|||
See [#122687] for more details.
|
||||
|
||||
[#122687]: https://github.com/rust-lang/rust/pull/122687
|
||||
[normalization]: ./normalization.md
|
||||
[normalization]: ../normalization.md
|
||||
|
|
|
|||
|
|
@ -13,3 +13,6 @@ allow-unauthenticated = [
|
|||
|
||||
# Automatically close and reopen PRs made by bots to run CI on them
|
||||
[bot-pull-requests]
|
||||
|
||||
[behind-upstream]
|
||||
days-threshold = 7
|
||||
Loading…
Reference in New Issue