Merge pull request #85 from mark-i-m/typeck

Add the contents of the typeck READMEs

Author: nikomatsakis

src/SUMMARY.md

@@ -35,6 +35,8 @@
     - [The SLG solver](./traits-slg.md)
     - [Bibliography](./traits-bibliography.md)
 - [Type checking](./type-checking.md)
+    - [Method Lookup](./method-lookup.md)
+    - [Variance](./variance.md)
 - [The MIR (Mid-level IR)](./mir.md)
     - [MIR construction](./mir-construction.md)
     - [MIR visitor and traversal](./mir-visitor.md)

src/appendix-background.md

@@ -91,6 +91,9 @@ cycle.
 Check out the subtyping chapter from the
 [Rust Nomicon](https://doc.rust-lang.org/nomicon/subtyping.html).
 
+See the [variance](./variance.html) chapter of this guide for more info on how
+the type checker handles variance.
+
 <a name=free-vs-bound>
 
 ## What is a "free region" or a "free variable"? What about "bound region"?

src/appendix-code-index.md

@@ -14,9 +14,11 @@ Item            |  Kind    | Short description           | Chapter            |
 `Session` | struct | The data associated with a compilation session | [the Parser], [The Rustc Driver] | [src/librustc/session/mod.html](https://github.com/rust-lang/rust/blob/master/src/librustc/session/mod.rs)
 `StringReader` | struct | This is the lexer used during parsing. It consumes characters from the raw source code being compiled and produces a series of tokens for use by the rest of the parser | [The parser] |  [src/libsyntax/parse/lexer/mod.rs](https://github.com/rust-lang/rust/blob/master/src/libsyntax/parse/lexer/mod.rs)
 `TraitDef` | struct | This struct contains a trait's definition with type information | [The `ty` modules] |  [src/librustc/ty/trait_def.rs](https://github.com/rust-lang/rust/blob/master/src/librustc/ty/trait_def.rs)
+`Ty<'tcx>` | struct | This is the internal representation of a type used for type checking | [Type checking] | [src/librustc/ty/mod.rs](https://github.com/rust-lang/rust/blob/master/src/librustc/ty/mod.rs)
 `TyCtxt<'cx, 'tcx, 'tcx>` | type | The "typing context". This is the central data structure in the compiler. It is the context that you use to perform all manner of queries. | [The `ty` modules] | [src/librustc/ty/context.rs](https://github.com/rust-lang/rust/blob/master/src/librustc/ty/context.rs)
 
 [The HIR]: hir.html
 [The parser]: the-parser.html
 [The Rustc Driver]: rustc-driver.html
+[Type checking]: type-checking.html
 [The `ty` modules]: ty.html

src/appendix-glossary.md

@@ -56,7 +56,8 @@ token                   |  the smallest unit of parsing. Tokens are produced aft
 trans                   |  the code to translate MIR into LLVM IR.
 trait reference         |  a trait and values for its type parameters ([see more](ty.html)).
 ty                      |  the internal representation of a type ([see more](ty.html)).
-variance                |  variance determines how changes to a generic type/lifetime parameter affect subtyping; for example, if `T` is a subtype of `U`, then `Vec<T>` is a subtype `Vec<U>` because `Vec` is *covariant* in its generic parameter. See [the background chapter for more](./appendix-background.html#variance).
+UFCS                    |  Universal Function Call Syntax. An unambiguous syntax for calling a method ([see more](type-checking.html)).
+variance                |  variance determines how changes to a generic type/lifetime parameter affect subtyping; for example, if `T` is a subtype of `U`, then `Vec<T>` is a subtype `Vec<U>` because `Vec` is *covariant* in its generic parameter. See [the background chapter](./appendix-background.html#variance) for a more general explanation. See the [variance chapter](./variance.html) for an explanation of how type checking handles variance.
 
 [LLVM]: https://llvm.org/
 [lto]: https://llvm.org/docs/LinkTimeOptimization.html

src/method-lookup.md

@@ -0,0 +1,119 @@
+# Method lookup
+
+Method lookup can be rather complex due to the interaction of a number
+of factors, such as self types, autoderef, trait lookup, etc. This
+file provides an overview of the process. More detailed notes are in
+the code itself, naturally.
+
+One way to think of method lookup is that we convert an expression of
+the form:
+
+```rust
+receiver.method(...)
+```
+
+into a more explicit UFCS form:
+
+```rust
+Trait::method(ADJ(receiver), ...) // for a trait call
+ReceiverType::method(ADJ(receiver), ...) // for an inherent method call
+```
+
+Here `ADJ` is some kind of adjustment, which is typically a series of
+autoderefs and then possibly an autoref (e.g., `&**receiver`). However
+we sometimes do other adjustments and coercions along the way, in
+particular unsizing (e.g., converting from `[T; n]` to `[T]`).
+
+Method lookup is divided into two major phases: 
+
+1. Probing ([`probe.rs`][probe]). The probe phase is when we decide what method
+   to call and how to adjust the receiver.
+2. Confirmation ([`confirm.rs`][confirm]). The confirmation phase "applies"
+   this selection, updating the side-tables, unifying type variables, and
+   otherwise doing side-effectful things.
+
+One reason for this division is to be more amenable to caching.  The
+probe phase produces a "pick" (`probe::Pick`), which is designed to be
+cacheable across method-call sites. Therefore, it does not include
+inference variables or other information.
+
+[probe]: https://github.com/rust-lang/rust/blob/master/src/librustc_typeck/check/method/probe.rs
+[confirm]: https://github.com/rust-lang/rust/blob/master/src/librustc_typeck/check/method/confirm.rs
+
+## The Probe phase
+
+### Steps
+
+The first thing that the probe phase does is to create a series of
+*steps*. This is done by progressively dereferencing the receiver type
+until it cannot be deref'd anymore, as well as applying an optional
+"unsize" step. So if the receiver has type `Rc<Box<[T; 3]>>`, this
+might yield:
+
+```rust
+Rc<Box<[T; 3]>>
+Box<[T; 3]>
+[T; 3]
+[T]
+```
+
+### Candidate assembly
+
+We then search along those steps to create a list of *candidates*. A
+`Candidate` is a method item that might plausibly be the method being
+invoked. For each candidate, we'll derive a "transformed self type"
+that takes into account explicit self.
+
+Candidates are grouped into two kinds, inherent and extension.
+
+**Inherent candidates** are those that are derived from the
+type of the receiver itself.  So, if you have a receiver of some
+nominal type `Foo` (e.g., a struct), any methods defined within an
+impl like `impl Foo` are inherent methods.  Nothing needs to be
+imported to use an inherent method, they are associated with the type
+itself (note that inherent impls can only be defined in the same
+module as the type itself).
+
+FIXME: Inherent candidates are not always derived from impls.  If you
+have a trait object, such as a value of type `Box<ToString>`, then the
+trait methods (`to_string()`, in this case) are inherently associated
+with it. Another case is type parameters, in which case the methods of
+their bounds are inherent. However, this part of the rules is subject
+to change: when DST's "impl Trait for Trait" is complete, trait object
+dispatch could be subsumed into trait matching, and the type parameter
+behavior should be reconsidered in light of where clauses.
+
+TODO: Is this FIXME still accurate?
+
+**Extension candidates** are derived from imported traits.  If I have
+the trait `ToString` imported, and I call `to_string()` on a value of
+type `T`, then we will go off to find out whether there is an impl of
+`ToString` for `T`.  These kinds of method calls are called "extension
+methods".  They can be defined in any module, not only the one that
+defined `T`.  Furthermore, you must import the trait to call such a
+method.
+
+So, let's continue our example. Imagine that we were calling a method
+`foo` with the receiver `Rc<Box<[T; 3]>>` and there is a trait `Foo`
+that defines it with `&self` for the type `Rc<U>` as well as a method
+on the type `Box` that defines `Foo` but with `&mut self`. Then we
+might have two candidates:
+
+    &Rc<Box<[T; 3]>> from the impl of `Foo` for `Rc<U>` where `U=Box<T; 3]>
+    &mut Box<[T; 3]>> from the inherent impl on `Box<U>` where `U=[T; 3]`
+
+### Candidate search
+
+Finally, to actually pick the method, we will search down the steps,
+trying to match the receiver type against the candidate types. At
+each step, we also consider an auto-ref and auto-mut-ref to see whether
+that makes any of the candidates match. We pick the first step where
+we find a match.
+
+In the case of our example, the first step is `Rc<Box<[T; 3]>>`,
+which does not itself match any candidate. But when we autoref it, we
+get the type `&Rc<Box<[T; 3]>>` which does match. We would then
+recursively consider all where-clauses that appear on the impl: if
+those match (or we cannot rule out that they do), then this is the
+method we would pick. Otherwise, we would continue down the series of
+steps.

src/type-checking.md

@@ -1 +1,44 @@
 # Type checking
+
+The [`rustc_typeck`][typeck] crate contains the source for "type collection"
+and "type checking", as well as a few other bits of related functionality. (It
+draws heavily on the [type inference] and [trait solving].)
+
+[typeck]: https://github.com/rust-lang/rust/tree/master/src/librustc_typeck
+[type inference]: type-inference.html
+[trait solving]: trait-resolution.html
+
+## Type collection
+
+Type "collection" is the process of converting the types found in the HIR
+(`hir::Ty`), which represent the syntactic things that the user wrote, into the
+**internal representation** used by the compiler (`Ty<'tcx>`) -- we also do
+similar conversions for where-clauses and other bits of the function signature.
+
+To try and get a sense for the difference, consider this function:
+
+```rust
+struct Foo { }
+fn foo(x: Foo, y: self::Foo) { .. }
+//        ^^^     ^^^^^^^^^
+```
+
+Those two parameters `x` and `y` each have the same type: but they will have
+distinct `hir::Ty` nodes. Those nodes will have different spans, and of course
+they encode the path somewhat differently. But once they are "collected" into
+`Ty<'tcx>` nodes, they will be represented by the exact same internal type.
+
+Collection is defined as a bundle of [queries] for computing information about
+the various functions, traits, and other items in the crate being compiled.
+Note that each of these queries is concerned with *interprocedural* things --
+for example, for a function definition, collection will figure out the type and
+signature of the function, but it will not visit the *body* of the function in
+any way, nor examine type annotations on local variables (that's the job of
+type *checking*).
+
+For more details, see the [`collect`][collect] module.
+
+[queries]: query.html
+[collect]: https://github.com/rust-lang/rust/blob/master/src/librustc_typeck/collect.rs
+
+**TODO**: actually talk about type checking...