rework and vastly expand the MIR section #67

nikomatsakis · 2018-02-25T02:49:12Z

This isn't done, but we now explain a lot more about MIR. These are all topics I've explained in the last few days, so they're on my mind.

cc @sgrif -- this includes a pretty detailed writeup of skolemization

mark-i-m

Thanks @nikomatsakis ! I learned a lot.

Sorry for assaulting you with so many comments 🤕

There are a lot of places where things should be placed in triple-backticks to format properly but aren't, especially in the regionck chapter.

Do you happen to know what READMEs are subsumed by this chapter? It would be good to mark them off in #2, and in rust-lang/rust#48479.

mark-i-m · 2018-02-25T21:59:36Z

src/glossary.md

@@ -18,12 +18,14 @@ HIR Map                 |  The HIR map, accessible via tcx.hir, allows you to qu
 generics                |  the set of generic type parameters defined on a type or item
 ICE                     |  internal compiler error. When the compiler crashes.
 ICH                     |  incremental compilation hash. ICHs are used as fingerprints for things such as HIR and crate metadata, to check if changes have been made. This is useful in incremental compilation to see if part of a crate has changed and should be recompiled.
+inference variable      |  when doing type or region inference, an "inference variable" is a kind of special type/region that represents value you are trying to find. Think of `X` in algebra.


Perhaps something like

when doing type or region inference, an "inference variable" is a kind of special type/region that represents what you are trying to infer. Think of X in algebra. For example, if we are trying to infer the type of a variable in a program, we create an inference variable to represent that unknown type.

mark-i-m · 2018-02-25T22:01:34Z

src/background.md

@@ -0,0 +1,122 @@
+# Background topics


I think it would be good to add all of these topics to the glossary in brief form with links to the right spot in this chapter.

mark-i-m · 2018-02-25T22:02:11Z

src/background.md

+connected by edges. The key idea of a basic block is that it is a set
+of statements that execute "together" -- that is, whenever you branch
+to a basic block, you start at the first statement and then execute
+all the remainder. Only at the end of the is there the possibility of


"Only at the end of the block"

mark-i-m · 2018-02-25T22:03:44Z

src/background.md

+
+<a name=variance>
+
+## What is co- and contra-variance?


I think there is content from the nomicon that could be borrowed here...

mark-i-m · 2018-02-25T22:04:39Z

src/background.md

+  refer to local variables that are defined *outside* of the
+  expression. We say that those variables **appear free** in the
+  expression. To see why this term makes sense, consider the next
+  example.


Missing example here?

just poor phrasing, fixed

mark-i-m · 2018-02-25T23:24:09Z

src/mir.md

+  leading underscore, like `_1`. There is also a special "local"
+  (`_0`) allocated to store the return value.
+- **Places:** expressions that identify a location in memory, like `_1` or `_1.f`.
+- **Rvalues:** expressions that product a value. The "R" stands for


"that produce"

mark-i-m · 2018-02-25T23:24:48Z

src/mir.md

+    constant (like `22`) or a place (like `_1`).
+
+You can get a feeling for how MIR is structed by translating simple
+programs into MIR and ready the pretty printed output. In fact, the


"and reading"

mark-i-m · 2018-02-25T23:27:00Z

src/mir.md

+like `_0` or `_1`.  We also intermingle the user's variables (e.g.,
+`_1`) with temporary values (e.g., `_2` or `_3`). You can tell the
+difference between user-defined variables have a comment that gives
+you their original name (`// "vec" in scope 1...`).


What are the "scope" blocks?

mark-i-m · 2018-02-25T23:32:10Z

src/mir.md

+
+<a name=promoted>
+
+### Promoted constants


Perhaps add "promoted constants" to the glossary?

done, I wonder if we should have some kind of "index" where we can define these "in situ" and then have a another pass that adds them to the glossary

That would be pretty nifty... I was kind of banking on people requesting things be added as they came across them 😛

mark-i-m · 2018-02-25T23:35:05Z

src/mir.md

+- **Rvalues** are represented by the enum `Rvalue`.
+- **Operands** are represented by the enum `Operand`.
+
+## MIR Visitor


I think the content of this subsection can be moved to the other subchapter.

nikomatsakis · 2018-02-26T01:46:29Z

Sorry for assaulting you with so many comments 🤕

💯 keep 'em comin'

nikomatsakis · 2018-02-26T01:47:44Z

There are a lot of places where things should be placed in triple-backticks to format properly but aren't, especially in the regionck chapter.

Do backticks format differently from "4-space indent"?

nikomatsakis · 2018-02-26T01:48:02Z

Do you happen to know what READMEs are subsumed by this chapter?

I'll take a look.

nikomatsakis · 2018-02-26T01:59:32Z

Haha, at first I only saw a few comments... then I realized GH was hiding 28 of them from me =)

mark-i-m · 2018-02-26T02:16:30Z

Do backticks format differently from "4-space indent"?

Oh, apparently GH renders them the same. Do you know if mdbook will do the same? I didn't know you could do that.

I'll take a look.

I updated #2 with my best guesses. Let me know what you think.

mark-i-m · 2018-02-26T02:24:54Z

src/glossary.md

 DefId                   |  an index identifying a definition (see `librustc/hir/def_id.rs`). Uniquely identifies a `DefPath`.
 HIR                     |  the High-level IR, created by lowering and desugaring the AST ([see more](hir.html))
 HirId                   |  identifies a particular node in the HIR by combining a def-id with an "intra-definition offset".
 HIR Map                 |  The HIR map, accessible via tcx.hir, allows you to quickly navigate the HIR and convert between various forms of identifiers.
+free variable           |  a "free variable" is one that is not bound within an expression or term; see [the background chapter for more](./background.html#free-vs-bound)


Sorry, could you actually move this after DefId? The glossary is a bit out of order at the moment. This is fixed in #56...

nikomatsakis · 2018-02-26T02:52:01Z

Oh, apparently GH renders them the same. Do you know if mdbook will do the same? I didn't know you could do that.

I assume so, 4-space indent was the "original markdown" technique, triple-backticks were added later. I've never quite kicked the habit of 4-space indent...

UPDATE: seems to look fine

nikomatsakis · 2018-02-26T02:54:55Z

@mark-i-m I added some notes to #2

nikomatsakis · 2018-02-26T03:04:42Z

@mark-i-m rebased, fixed the order of glossary. The alphabet is hard.

mark-i-m · 2018-02-26T03:07:22Z

The alphabet is hard.

Lol, tell me about it... I've gotten this wrong for a few PR cycles now 😛

mark-i-m · 2018-02-26T03:08:09Z

Thanks @nikomatsakis!

I need to run now, but I think I should come around to this tomorrow

davidtwco

Was just reading through this to see if I could pick anything up from it, noticed a small typo.

davidtwco · 2018-02-27T17:20:40Z

src/mir-regionck.md

+    regions are the results of lexical region inference and hence are
+    not of much interest. The intention is that -- eventually -- they
+    will be "erased regions" (i.e., no information at all), since we
+    don't be doing lexical region inference at all.


since we don't be doing -> since we won't be doing?

mark-i-m

Thanks for all the effort @nikomatsakis ! This is a great chapter! I found a few more typos.

The universes section clears up a lot of things 👍

mark-i-m · 2018-02-27T22:09:28Z

src/glossary.md

 query                   |  perhaps some sub-computation during compilation ([see more](query.html))
 region                  |  another term for "lifetime" often used in the literature and in the borrow checker.
 sess                    |  the compiler session, which stores global data used throughout compilation
 side tables             |  because the AST and HIR are immutable once created, we often carry extra information about them in the form of hashtables, indexed by the id of a particular node.
 sigil                   |  like a keyword but composed entirely of non-alphanumeric tokens. For example, `&` is a sigil for references.
+skolemization           |  a way of handling subtyping around "for-all" types (e.g., `for<'a> fn(&'a u32)` as well as solving higher-ranked trait bounds (e.g., `for<'a> T: Trait<'a>`). See [the chapter on skolemization and universes](./mir-regionck.html#skol) for more details.


I think you are missing a closing paren after the first example...

mark-i-m · 2018-02-27T22:22:22Z

src/mir-regionck.md

-    [appear free][fvb] in the function body.
+  - First, it finds the set of regions that appear within the
+    signature of the function (e.g., `'a` in `fn foo<'a>(&'a u32) {
+    ... }`. These are called the "universal" or "free" regions -- in


I think you are missing a closing paren after the example

mark-i-m · 2018-02-27T22:27:21Z

src/mir-regionck.md

@@ -154,6 +155,118 @@ outlives `'static`. Now, this *might* be true -- after all, `'!1`
 could be `'static` -- but we don't *know* that it's true. So this
 should yield up an error (eventually).

+### What is a universe


This is a really useful section. It might be worthwhile to note that the root universe is not unique in some sense, IIUC. There is a root universe for every "instance" of regionck, right? Otherwise, you would have generics in your universe from other items, right?

mark-i-m · 2018-02-27T22:28:16Z

src/mir-regionck.md

+}
+```
+
+Here, the root universe would consider of the lifetimes `'static` and


"would consider of" -> "would consist of"

mark-i-m · 2018-02-27T22:30:38Z

src/mir-regionck.md

+```
+
+When we enter *this* type, we will again create a new universe, which
+let's call `U2`. It's parent will be the root universe, and U1 will be


"which we'll"

mark-i-m · 2018-02-27T22:35:21Z

src/mir-regionck.md

+in common. And because everything in U1 is scoped to just U1 and its
+children, that inference variable X would have to be in U0. And since
+X is in U0, it cannot name anything from U1 (or U2). This is perhaps easiest
+to see by using a kind of generic "logic" example:


Woah. That's really cool. Mind blown. 💥

nikomatsakis · 2018-02-28T20:28:26Z

@mark-i-m ok I addressed those changes I believe

mark-i-m

🎉

nikomatsakis force-pushed the mir-nll branch from 1fdf778 to c442e27 Compare February 25, 2018 02:49

nikomatsakis mentioned this pull request Feb 25, 2018

master tracking issue #6

Closed

20 tasks

mark-i-m suggested changes Feb 25, 2018

View reviewed changes

nikomatsakis mentioned this pull request Feb 25, 2018

move over the rustc README #2

Closed

19 tasks

mark-i-m reviewed Feb 26, 2018

View reviewed changes

nikomatsakis force-pushed the mir-nll branch from 3a5a38f to 419f1d6 Compare February 26, 2018 02:48

rework the MIR intro section, breaking out passes and visitors

95bab3e

nikomatsakis force-pushed the mir-nll branch from 29c74da to fe632f2 Compare February 26, 2018 03:04

apply mark-i-m's suggestions

fe632f2

mark-i-m mentioned this pull request Feb 26, 2018

Glossary #48

Closed

27 tasks

davidtwco requested changes Feb 27, 2018

View reviewed changes

fix typo

55f75dc

mark-i-m suggested changes Feb 27, 2018

View reviewed changes

address nits

f45d419

mark-i-m approved these changes Feb 28, 2018

View reviewed changes

mark-i-m merged commit 03044a3 into rust-lang:master Feb 28, 2018

rework and vastly expand the MIR section #67

rework and vastly expand the MIR section #67

Conversation

nikomatsakis commented Feb 25, 2018

mark-i-m left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nikomatsakis commented Feb 26, 2018

nikomatsakis commented Feb 26, 2018

nikomatsakis commented Feb 26, 2018

nikomatsakis commented Feb 26, 2018

mark-i-m commented Feb 26, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nikomatsakis commented Feb 26, 2018 • edited

nikomatsakis commented Feb 26, 2018

nikomatsakis commented Feb 26, 2018

mark-i-m commented Feb 26, 2018

mark-i-m commented Feb 26, 2018

davidtwco left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mark-i-m left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nikomatsakis commented Feb 28, 2018

mark-i-m left a comment

Choose a reason for hiding this comment

nikomatsakis commented Feb 26, 2018 •

edited