WIP

Author: BoxyUwU

src/SUMMARY.md

@@ -156,7 +156,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)
-- [Normalization and Aliases](./normalization/normalization.md)
+- [Normalization and Aliases](./normalization.md)
 - [Typing/Param Envs](./typing_parameter_envs.md)
 - [Type inference](./type-inference.md)
 - [Trait solving](./traits/resolution.md)

src/normalization/normalization.md renamed to src/normalization.md

@@ -4,9 +4,9 @@
 
 ## What is normalization
 
-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`). Alias types are represented by the [`TyKind::Alias`][tykind_alias] variant, with the kind of aliases tracked by the [`AliasTyKind`][aliaskind] enum.
+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 determining the underlying type that they are equal to. For example given some type alias `type Foo = u32`, normalizing `Foo` would give `u32`.
+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`.
 
 [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
@@ -17,19 +17,19 @@ When interfacing with the type system it will often be the case that it's necess
 
 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.
+Here is a rough overview of the different entry points to normalization in the compiler:
 - `infcx.at.normalize`
 - `tcx.normalize_erasing_regions`
 - `infcx.query_normalize`
 - `traits::normalize_with_depth(_to)`
 
 ### `infcx.at.normalize/deeply_normalize/structurally_normalize`
 
-[`normalize`][normalize]/[`deeply_normalize`][deeply_normalize]/[`structurally_normalize`][structurally_normalize] are the main normalization entry points for normalizing during various analysis' such as type checking, impl wellformedness checking, collecting the types of RPITITs, etc. It's able to handle inference variables during normalization and will return any nested goals required for the normalization to hold. 
+[`normalize`][normalize]/[`deeply_normalize`][deeply_normalize]/[`structurally_normalize`][structurally_normalize] are the main normalization entry points for normalizing during various analysis' such as type checking, impl wellformedness checking, collecting the types of RPITITs, etc. They are able to handle inference variables during normalization and will return any nested goals required for the normalization to hold. 
 
 These normalization functions are often mirrored on other contexts that wrap an [`InferCtxt`][infcx], such as [`FnCtxt`][fcx] or [`ObligationCtxt`][ocx]. They behave largely the same except that these wrappers can either handle providing some of the arguments to the normalize functions or handle the returned goals itself.
 
-Due to the new normalization approach of the new solver the `normalize` method is a no-op under the new solver and is slated for removal once the new solver is stabilized. Under the new solver the intention is to delay normalization up until matching on the type is actually required, at which point `structurally_normalize` should be called. In some rare cases it is still desirable to eagerly normalize a whole value ahead of time and so `deeply_normalize` exists.
+The `normalize` function is a no-op under the new solver, and will be removed once the new solver is stabilized. It is intended to be used in cases where normalization is not required under the new solver, in cases where normalization is required with bother solvers the `structurally_normalize` function can be used.
 
 When matching on types during HIR typeck we would like to emit an error if the type is an inference variable as we do not know what type it will wind up being inferred to. The `FnCtxt` type (used during HIR typeck) has a method for this, [`fcx.structurally_resolve`][structurally_resolve], when the new solver is enabled it will *also* attempt to normalize the type via `structurally_normalize`.
 
@@ -59,27 +59,85 @@ In practice `query_normalize` is used for normalization in the borrow checker, a
 
 ### `traits::normalize_with_depth(_to)`
 
-[`traits::normalize_with_depth(_to)`][norm_with_depth] is only used by the internals of the old trait solver. It is effectively calling into the internals of how normalization is implemented by the old solver. Other normalization entry points cannot be used from within the internals of the old trait solver as it would result in handling goal cycles and recursion depth incorrectly.
+[`traits::normalize_with_depth(_to)`][norm_with_depth] is only used by the internals of the old trait solver. It is effectively a raw entry point to the internals of how normalization is implemented by the old solver. Other normalization entry points cannot be used from within the internals of the old trait solver as it would result in incorrectly handling goal cycles and recursion depth.
 
-When the new solver is stabilized, the old solver and its implementation of normalization will be removed (of which this function is part of).
+This should not be used outside of the implementation of the old solver. When the new solver is stabilized, the old solver and its implementation of normalization (of which this function is part of) will be removed .
 
 [norm_with_depth]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_trait_selection/traits/normalize/fn.normalize_with_depth.html
 
 # Alias handling
 
-> FIXME: This section is somewhat incomplete and could do with expansion
+> NOTE: This section is somewhat incomplete and could do with expansion
 
-## Ambiguous vs Rigid Aliases
+## Rigid, Ambiguous and Unnormalized Aliases
 
-Aliases can either be "ambiguous" or "rigid". 
+Aliases can either be "rigid", "ambiguous", or simply unnormalized.
 
-When an alias cannot yet be normalized due to containing inference variables, such as `<_ as Iterator>::Item`, we consider it to be an "ambiguous" alias where "ambiguous" refers to the fact that it is not clear what type implements `Iterator` yet.
+We generally 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`.
 
-On the other hand if we can determine the source for how the self type (`_` in the previous example) implements the trait (e.g. `Iterator`) but the source does not determine the underlying type of the associated type (e.g. `Item`) then it is considered a "rigid" alias.
+Aliases are rigid when we know that we will never be able to normalize them furthur. A concrete example of a *rigid* alias would be `<T as Iterator>::Item` in an environemnt 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;
+}
 
-We generally 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`.
+fn bar<T: Iterator<Item = u32>>() {
+    // This alias is *not* rigid as it can be normalized to `u32`
+    let _: <T as Iterator>::Item;
+}
+```
+
+This definition also imples that illformed aliases can be considered rigid. For example the type `<u32 as Iterator>::Item` is a rigid alias as it can never be normalized as there is no `u32: Iterator` impl (ignoring `feature(trivial_bounds)`).
+
+When an alias can't yet be normalized but may eventually wind up normalizeable 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 how `_: 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.
+
+---
 
-If an alias is not ambiguous and also is not rigid then it is either not well formed (the self type does not implement the trait), or it can simply be normalized to its underlying type.
+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:
+```rust
+#![feature(inherent_associated_types)]
+
+trait Trait {}
+
+impl Trait for u32 {}
+impl Trait for u64 {}
+
+struct Foo<T>(T);
+
+impl<T: Trait> Foo<T> {
+    type Inherent = u32;
+}
+
+fn ret_alias<T: Trait>(_: T) -> Foo<T>::Inherent {
+    10_u32
+}
+
+fn main() {
+    // `t` has type `?x`
+    let mut t = Default::default();
+    // `ret_alias` returns a value of type `Foo<?x>::Inherent`
+    t = ret_alias(t);
+    
+    // we have equated `?x` with `Foo<?x>::Inherent` this can
+    // only succeed if we're able to normalize inherent aliases
+    // with ambiguous where clauses on the impl.
+    //
+    // Or, put another way, it is *not* an ambiguous alias.
+}
+```
 
 ## Alias Equality