diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 772ae3ec9..2fbbb187d 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -134,17 +134,14 @@ - [Prologue](./part-4-intro.md) - [Generic parameter definitions](./generic_parameters_summary.md) - - [What is `ty::Generics`](./what_is_ty_generics.md) - - [Early vs Late bound parameters](./early-late-bound-params/early-late-bound-summary.md) - - [Implementation nuances of early/late bound parameters](./early-late-bound-params/early-late-bound-implementation-nuances.md) - - [Interactions with turbofishing](./early-late-bound-params/turbofishing-and-early-late-bound.md) + - [Implementation nuances of early/late bound parameters](./early-late-bound-params/early-late-bound-implementation-nuances.md) + - [Interactions with turbofishing](./early-late-bound-params/turbofishing-and-early-late-bound.md) - [The `ty` module: representing types](./ty.md) - [ADTs and Generic Arguments](./ty_module/generic_arguments.md) - [Parameter types/consts/regions](./ty_module/param_ty_const_regions.md) - [`EarlyBinder` and instantiating parameters](./ty_module/early_binder.md) - [`Binder` and Higher ranked regions](./ty_module/binders.md) - [Instantiating binders](./ty_module/instantiating_binders.md) - - [Constants in the type system](./constants.md) - [`TypeFolder` and `TypeFoldable`](./ty-fold.md) - [Parameter Environments](./param_env/param_env_summary.md) - [What is it?](./param_env/param_env_what_is_it.md) diff --git a/src/constants.md b/src/constants.md deleted file mode 100644 index d51cffcaf..000000000 --- a/src/constants.md +++ /dev/null @@ -1,82 +0,0 @@ -# Constants in the type system - -Constants used in the type system are represented as [`ty::Const`]. -The variants of their [`const_kind::ConstKind`] mostly mirror the variants of [`ty_kind::TyKind`] -with the two *additional* variants being `ConstKind::Value` and `ConstKind::Unevaluated`. - -## `WithOptConstParam` and dealing with the query system - -To typecheck constants used in the type system, we have to know their expected type. -For const arguments in type dependent paths, e.g. `x.foo::<{ 3 + 4 }>()`, we don't know -the expected type for `{ 3 + 4 }` until we are typechecking the containing function. - -As we may however have to evaluate that constant during this typecheck, we would get a cycle error. -For more details, you can look at [this document](https://hackmd.io/@rust-const-generics/Bk5GHW-Iq). - -## Unevaluated constants - -*This section talks about what's happening with `feature(generic_const_exprs)` enabled. -On stable we do not yet supply any generic parameters to anonymous constants, -avoiding most of the issues mentioned here.* - -Unless a constant is either a simple literal, e.g. `[u8; 3]` or `foo::<{ 'c' }>()`, -or a generic parameter, e.g. `[u8; N]`, converting a constant to its [`ty::Const`] representation -returns an unevaluated constant. Even fully concrete constants which do not depend on -generic parameters are not evaluated right away. - -Anonymous constants are typechecked separately from their containing item, e.g. -```rust -fn foo() -> [u8; N + 1] { - [0; N + 1] -} -``` -is treated as -```rust -const ANON_CONST_1 = N + 1; -const ANON_CONST_2 = N + 1; -fn foo() -> [u8; ANON_CONST_1::] { - [0; ANON_CONST_2::] -} -``` - -### Unifying constants - -For the compiler, `ANON_CONST_1` and `ANON_CONST_2` are completely different, so -we have to somehow look into unevaluated constants to check whether they should -unify. - -For this we use [InferCtxt::try_unify_abstract_consts](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_infer/infer/struct.InferCtxt.html#method.try_unify_abstract_consts). -This builds a custom AST for the two inputs from their THIR. This is then used for -the actual comparison. - -### Lazy normalization for constants - -We do not eagerly evaluate constant as they can be used in the `where`-clauses of their -parent item, for example: - -```rust -#[feature(generic_const_exprs)] -fn foo() -where - [u8; ::ASSOC + 1]: SomeOtherTrait, -{} -``` - -The constant `::ASSOC + 1` depends on the `T: Trait` bound of -its parents caller bounds, but is also part of another bound itself. -If we were to eagerly evaluate this constant while computing its parents bounds -this would cause a query cycle. - -### Unused generic arguments of anonymous constants - -Anonymous constants inherit the generic parameters of their parent, which is -why the array length in `foo() -> [u8; N + 1]` can use `N`. - -Without any manual adjustments, this causes us to include parameters even if -the constant doesn't use them in any way. This can cause -[some interesting errors][pcg-unused-substs] and breaks some already stable code. - -[`ty::Const`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.Const.html -[`const_kind::ConstKind`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_type_ir/const_kind/enum.ConstKind.html -[`ty_kind::TyKind`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_type_ir/ty_kind/enum.TyKind.html -[pcg-unused-substs]: https://github.com/rust-lang/project-const-generics/issues/33 diff --git a/src/early-late-bound-params/early-late-bound-implementation-nuances.md b/src/early-late-bound-params/early-late-bound-implementation-nuances.md index e1507f429..01569e8dc 100644 --- a/src/early-late-bound-params/early-late-bound-implementation-nuances.md +++ b/src/early-late-bound-params/early-late-bound-implementation-nuances.md @@ -1,5 +1,9 @@ # Early and Late Bound Parameter Implementation Nuances +> Note: this chapter makes reference to information discussed later on in the [representing types][ch_representing_types] chapter. Specifically, it uses concise notation to represent some more complex kinds of types that have not yet been discussed, such as inference variables. + +[ch_representing_types]: ../ty.md + Understanding this page likely requires a rudimentary understanding of higher ranked trait bounds/`for<'a>`and also what types such as `dyn for<'a> Trait<'a>` and `for<'a> fn(&'a u32)` mean. Reading [the nomincon chapter](https://doc.rust-lang.org/nomicon/hrtb.html) @@ -41,13 +45,13 @@ fn foo_late<'a, T>(_: &'a u32, _: T) {} fn accepts_hr_func Fn(&'a u32, u32)>(_: F) {} fn main() { - // doesn't work, the substituted bound is `for<'a> FnDef<'?0>: Fn(&'a u32, u32)` + // doesn't work, the instantiated bound is `for<'a> FnDef<'?0>: Fn(&'a u32, u32)` // `foo_early` only implements `for<'a> FnDef<'a>: Fn(&'a u32, u32)`- the lifetime // of the borrow in the function argument must be the same as the lifetime // on the `FnDef`. accepts_hr_func(foo_early); - // works, the substituted bound is `for<'a> FnDef: Fn(&'a u32, u32)` + // works, the instantiated bound is `for<'a> FnDef: Fn(&'a u32, u32)` accepts_hr_func(foo_late); } diff --git a/src/early-late-bound-params/early-late-bound-summary.md b/src/early-late-bound-params/early-late-bound-summary.md deleted file mode 100644 index a4d823e66..000000000 --- a/src/early-late-bound-params/early-late-bound-summary.md +++ /dev/null @@ -1,35 +0,0 @@ -# Early/Late bound parameters - -This section discusses what it means for generic parameters to be early or late bound. - -```rust -fn foo<'a, T>(b: &'a T) -> &'a T { b } -// ^^ ^early bound -// ^^ -// ^^late bound -``` - -Generally when referring to an item with generic parameters you must specify a list of generic arguments corresponding to the item's generic parameters. In -some cases it is permitted to elide these arguments but still, implicitly, a set of arguments are provided (i.e. `Vec::default()` desugars to `Vec::<_>::default()`). - -For functions this is not necessarily the case, for example if we take the function `foo` from the example above and write the following code: -```rust -fn main() { - let f = foo::<_>; - - let b = String::new(); - let c = String::new(); - - f(&b); - drop(b); - f(&c); -} -``` - -This code compiles perfectly fine even though there is no single lifetime that could possibly be specified in `foo::<_>` that would allow for both -the `&b` and `&c` borrows to be used as arguments (note: the `drop(b)` line forces the `&b` borrow to be shorter than the `&c` borrow). This works because -the `'a` lifetime is _late bound_. - -A generic parameter being late bound means that when we write `foo::<_>` we do not actually provide an argument for that parameter, instead we wait until _calling_ the function to provide the generic argument. In the above example this means that we are doing something like `f::<'_>(&b);` and `f::<'_>(&c);` (although in practice we do not actually support turbofishing late bound parameters in this manner) - -It may be helpful to think of "early bound parameter" or "late bound parameter" as meaning "early provided parameter" and "late provided parameter", i.e. we provide the argument to the parameter either early (when naming the function) or late (when calling it). \ No newline at end of file diff --git a/src/early-late-bound-params/turbofishing-and-early-late-bound.md b/src/early-late-bound-params/turbofishing-and-early-late-bound.md index 648f28079..6fc30c676 100644 --- a/src/early-late-bound-params/turbofishing-and-early-late-bound.md +++ b/src/early-late-bound-params/turbofishing-and-early-late-bound.md @@ -1,5 +1,9 @@ # Turbofishing's interactions with early/late bound parameters +> Note: this chapter makes reference to information discussed later on in the [representing types][ch_representing_types] chapter. Specifically, it uses concise notation to represent some more complex kinds of types that have not yet been discussed, such as inference variables. + +[ch_representing_types]: ../ty.md + The early/late bound parameter distinction on functions introduces some complications when providing generic arguments to functions. This document discusses what those are and how they might interact with future changes to make more things late bound. @@ -36,7 +40,7 @@ fn main() { ``` The justification for this is that late bound parameters are not present on the -`FnDef` so the arguments to late bound parameters can't be present in the substs +`FnDef` so the arguments to late bound parameters can't be present in the generic arguments for the type. i.e. the `late` function in the above code snippet would not have any generic parameters on the `FnDef` zst: ```rust @@ -52,7 +56,7 @@ The cause for some situations giving future compat lints and others giving hard is a little arbitrary but explainable: - It's always a hard error for method calls - It's only a hard error on paths to free functions if there is no unambiguous way to -create the substs for the fndef from the lifetime arguments. (i.e. the amount of +create the generic arguments for the fndef from the lifetime arguments. (i.e. the amount of lifetimes provided must be exactly equal to the amount of early bound lifetimes or else it's a hard error) @@ -107,8 +111,9 @@ fn late<'a, 'b>(_: &'a (), _: &'b ()) {} fn accepts_fn(_: impl for<'a> Fn(&'a (), &'static ())) {} fn main() { - // a naive implementation would have a `ReInfer` as the subst for `'a` parameter - // no longer allowing the FnDef to satisfy the `for<'a> Fn(&'a ()` bound + // a naive implementation would have an inference variable as + // the argument to the `'a` parameter no longer allowing the `FnDef` + // to satisfy the bound `for<'a> Fn(&'a ())` let f = late::<'_, 'static>; accepts_fn(f); } diff --git a/src/generic_parameters_summary.md b/src/generic_parameters_summary.md index ee2b3b893..3403c9f29 100644 --- a/src/generic_parameters_summary.md +++ b/src/generic_parameters_summary.md @@ -1,7 +1,66 @@ # Generic parameter definitions -This chapter will discuss how rustc tracks what generic parameters are introduced by an item. For example given some struct defined via `struct Foo` how does rustc track that `Foo` defines some type parameter `T` and nothing else? +This chapter will discuss how rustc tracks what generic parameters are introduced. For example given some `struct Foo` how does rustc track that `Foo` defines some type parameter `T` (and no other generic parameters). -This will *not* cover how we track generic parameters introduced via `for<'a>` syntax (i.e. in where clauses or `fn` types), which is covered elsewhere in the [chapter on `Binder`s ][ch_binders]. +This will *not* cover how we track generic parameters introduced via `for<'a>` syntax (e.g. in where clauses or `fn` types), which is covered elsewhere in the [chapter on `Binder`s ][ch_binders]. +# `ty::Generics` + +The generic parameters introduced by an item are tracked by the [`ty::Generics`] struct. Sometimes items allow usage of generics defined on parent items, this is accomplished via the `ty::Generics` struct having an optional field to specify a parent item to inherit generic parameters of. For example given the following code: + +```rust,ignore +trait Trait { + fn foo(&self); +} +``` + +The `ty::Generics` used for `foo` would contain `[U]` and a parent of `Some(Trait)`. `Trait` would have a `ty::Generics` containing `[Self, T]` with a parent of `None`. + +The [`GenericParamDef`] struct is used to represent each individual generic parameter in a `ty::Generics` listing. The `GenericParamDef` struct contains information about the generic parameter, for example its name, defid, what kind of parameter it is (i.e. type, const, lifetime). + +`GenericParamDef` also contains a `u32` index representing what position the parameter is (starting from the outermost parent), this is the value used to represent usages of generic parameters (more on this in the [chapter on representing types][ch_representing_types]). + +Interestingly, `ty::Generics` does not currently contain _every_ generic parameter defined on an item. In the case of functions it only contains the _early bound_ parameters. + +[ch_representing_types]: ./ty.md +[`ty::Generics`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.Generics.html +[`GenericParamDef`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/generics/struct.GenericParamDef.html + +# Early vs Late bound parameters + + +```rust +fn foo<'a, T>(b: &'a T) -> &'a T { b } +// ^^ ^early bound +// ^^ +// ^^late bound +``` + +Generally when referring to an item with generic parameters you must specify a list of generic arguments corresponding to the item's generic parameters. In some cases it is permitted to elide these arguments but still, implicitly, a set of arguments are provided (e.g. `Vec::default()` desugars to `Vec::<_>::default()`). + +For functions this is not necessarily the case, for example if we take the function `foo` from the example above and write the following code: +```rust +fn main() { + let f = foo::<_>; + + let b = String::new(); + let c = String::new(); + + f(&b); + drop(b); + f(&c); +} +``` + +This code compiles perfectly fine even though there is no single lifetime that could possibly be specified in `foo::<_>` that would allow for both +the `&b` and `&c` borrows to be used as arguments (note: the `drop(b)` line forces the `&b` borrow to be shorter than the `&c` borrow). This works because the `'a` lifetime is _late bound_. + +A generic parameter being late bound means that when we write `foo::<_>` we do not actually provide an argument for that parameter, instead we wait until _calling_ the function to provide the generic argument. In the above example this means that we are doing something like `f::<'_>(&b);` and `f::<'_>(&c);` (although in practice we do not actually support turbofishing late bound parameters in this manner) + +It may be helpful to think of "early bound parameter" or "late bound parameter" as meaning "early provided parameter" and "late provided parameter", i.e. we provide the argument to the parameter either early (when naming the function) or late (when calling it). + +Late bound parameters on functions are tracked with a [`Binder`] when accessing the signature of the function, this can be done with the [`fn_sig`] query. For more information of binders see the [chapter on `Binder`s ][ch_binders]. + +[`Binder`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_type_ir/binder/struct.Binder.html +[`fn_sig`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/context/struct.TyCtxt.html#method.fn_sig [ch_binders]: ./ty_module/binders.md \ No newline at end of file diff --git a/src/ty.md b/src/ty.md index 9a256a34b..b33d54035 100644 --- a/src/ty.md +++ b/src/ty.md @@ -314,3 +314,13 @@ a redundant delayed bug. [terr]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.Ty.html#method.new_error [terrmsg]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.Ty.html#method.new_error_with_message + + +## `TyKind` variant shorthand syntax + +When looking at the debug output of `Ty` or simply talking about different types in the compiler, you may encounter syntax that is not valid rust but is used to concisely represent internal information about types. Below is a quick reference cheat sheet to tell what the various syntax actually means, these should be covered in more depth in later chapters. + +- Generic parameters: `{name}/#{index}` e.g. `T/#0`, where `index` corresponds to its position in the list of generic parameters +- Inference variables: `?{id}` e.g. `?x`/`?0`, where `id` identifies the inference variable +- Variables from binders: `^{binder}_{index}` e.g. `^0_x`/`^0_2`, where `binder` and `index` identify which variable from which binder is being referred to +- Placeholders: `!{id}` or `!{id}_{universe}` e.g. `!x`/`!0`/`!x_2`/`!0_2`, representing some unique type in the specified universe. The universe is often elided when it is `0` \ No newline at end of file diff --git a/src/what_is_ty_generics.md b/src/what_is_ty_generics.md deleted file mode 100644 index 6a3532d71..000000000 --- a/src/what_is_ty_generics.md +++ /dev/null @@ -1,21 +0,0 @@ -# What is `ty::Generics` - -The generic parameters introduced by an item are tracked the [`ty::Generics`] struct. Sometimes items allows usage of generics of parent items inside of them, this is accomplished via the `ty::Generics` struct having an optional field to specify a parent item to inherit generic parameters of. For example given the following code: - -```rust,ignore -trait Trait { - fn foo(&self); -} -``` - -The `ty::Generics` used for `foo` would contain `[U]` and a parent of `Some(Trait)`. `Trait` would have a `ty::Generics` containing `[Self, T]` with a parent of `None`. - -The [`GenericParamDef`] struct is used to represent each individual generic parameter in a `ty::Generics` listing. The `GenericParamDef` struct contains information about the generic parameter, for example its name, defid, what kind of parameter it is (i.e. type, const, lifetime). - -`GenericParamDef` also contains a `u32` index representing what position the parameter is (starting from the outermost parent), this is the value used to represent usages of generic parameters (more on this in the [chapter on representing types][ch_representing_types]). - -Interestingly, `ty::Generics` does not currently contain _every_ generic parameter defined on an item. In the case of functions it only contains the _early bound_ lifetime parameters. See the next chapter for information on what "early bound" and "late bound" parameters are. - -[ch_representing_types]: ./ty.md -[`ty::Generics`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.Generics.html -[`GenericParamDef`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/generics/struct.GenericParamDef.html \ No newline at end of file