-
Notifications
You must be signed in to change notification settings - Fork 520
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
rework and vastly expand the MIR section #67
Merged
Merged
Changes from all commits
Commits
Show all changes
4 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,122 @@ | ||
# Background topics | ||
|
||
This section covers a numbers of common compiler terms that arise in | ||
this guide. We try to give the general definition while providing some | ||
Rust-specific context. | ||
|
||
<a name=cfg> | ||
|
||
## What is a control-flow graph? | ||
|
||
A control-flow graph is a common term from compilers. If you've ever | ||
used a flow-chart, then the concept of a control-flow graph will be | ||
pretty familiar to you. It's a representation of your program that | ||
exposes the underlying control flow in a very clear way. | ||
|
||
A control-flow graph is structured as a set of **basic blocks** | ||
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 block is there the | ||
possibility of branching to more than one place (in MIR, we call that | ||
final statement the **terminator**): | ||
|
||
``` | ||
bb0: { | ||
statement0; | ||
statement1; | ||
statement2; | ||
... | ||
terminator; | ||
} | ||
``` | ||
|
||
Many expressions that you are used to in Rust compile down to multiple | ||
basic blocks. For example, consider an if statement: | ||
|
||
```rust | ||
a = 1; | ||
if some_variable { | ||
b = 1; | ||
} else { | ||
c = 1; | ||
} | ||
d = 1; | ||
``` | ||
|
||
This would compile into four basic blocks: | ||
|
||
``` | ||
BB0: { | ||
a = 1; | ||
if some_variable { goto BB1 } else { goto BB2 } | ||
} | ||
|
||
BB1: { | ||
b = 1; | ||
goto BB3; | ||
} | ||
|
||
BB2: { | ||
c = 1; | ||
goto BB3; | ||
} | ||
|
||
BB3: { | ||
d = 1; | ||
...; | ||
} | ||
``` | ||
|
||
When using a control-flow graph, a loop simply appears as a cycle in | ||
the graph, and the `break` keyword translates into a path out of that | ||
cycle. | ||
|
||
<a name=dataflow> | ||
|
||
## What is a dataflow analysis? | ||
|
||
*to be written* | ||
|
||
<a name=quantified> | ||
|
||
## What is "universally quantified"? What about "existentially quantified"? | ||
|
||
*to be written* | ||
|
||
<a name=variance> | ||
|
||
## What is co- and contra-variance? | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think there is content from the nomicon that could be borrowed here... |
||
|
||
Check out the subtyping chapter from the | ||
[Rust Nomicon](https://doc.rust-lang.org/nomicon/subtyping.html). | ||
|
||
<a name=free-vs-bound> | ||
|
||
## What is a "free region" or a "free variable"? What about "bound region"? | ||
|
||
Let's describe the concepts of free vs bound in terms of program | ||
variables, since that's the thing we're most familiar with. | ||
|
||
- Consider this expression, which creates a closure: `|a, | ||
b| a + b`. Here, the `a` and `b` in `a + b` refer to the arguments | ||
that the closure will be given when it is called. We say that the | ||
`a` and `b` there are **bound** to the closure, and that the closure | ||
signature `|a, b|` is a **binder** for the names `a` and `b` | ||
(because any references to `a` or `b` within refer to the variables | ||
that it introduces). | ||
- Consider this expression: `a + b`. In this expression, `a` and `b` | ||
refer to local variables that are defined *outside* of the | ||
expression. We say that those variables **appear free** in the | ||
expression (i.e., they are **free**, not **bound** (tied up)). | ||
|
||
So there you have it: a variable "appears free" in some | ||
expression/statement/whatever if it refers to something defined | ||
outside of that expressions/statement/whatever. Equivalently, we can | ||
then refer to the "free variables" of an expression -- which is just | ||
the set of variables that "appear free". | ||
|
||
So what does this have to do with regions? Well, we can apply the | ||
analogous concept to type and regions. For example, in the type `&'a | ||
u32`, `'a` appears free. But in the type `for<'a> fn(&'a u32)`, it | ||
does not. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1,56 @@ | ||
# MIR borrowck | ||
# MIR borrow check | ||
|
||
The borrow check is Rust's "secret sauce" -- it is tasked with | ||
enforcing a number of properties: | ||
|
||
- That all variables are initialized before they are used. | ||
- That you can't move the same value twice. | ||
- That you can't move a value while it is borrowed. | ||
- That you can't access a place while it is mutably borrowed (except through the reference). | ||
- That you can't mutate a place while it is shared borrowed. | ||
- etc | ||
|
||
At the time of this writing, the code is in a state of transition. The | ||
"main" borrow checker still works by processing [the HIR](hir.html), | ||
but that is being phased out in favor of the MIR-based borrow checker. | ||
Doing borrow checking on MIR has two key advantages: | ||
|
||
- The MIR is *far* less complex than the HIR; the radical desugaring | ||
helps prevent bugs in the borrow checker. (If you're curious, you | ||
can see | ||
[a list of bugs that the MIR-based borrow checker fixes here][47366].) | ||
- Even more importantly, using the MIR enables ["non-lexical lifetimes"][nll], | ||
which are regions derived from the control-flow graph. | ||
|
||
[47366]: https://github.com/rust-lang/rust/issues/47366 | ||
[nll]: http://rust-lang.github.io/rfcs/2094-nll.html | ||
|
||
### Major phases of the borrow checker | ||
|
||
The borrow checker source is found in | ||
[the `rustc_mir::borrow_check` module][b_c]. The main entry point is | ||
the `mir_borrowck` query. At the time of this writing, MIR borrowck can operate | ||
in several modes, but this text will describe only the mode when NLL is enabled | ||
(what you get with `#![feature(nll)]`). | ||
|
||
[b_c]: https://github.com/rust-lang/rust/tree/master/src/librustc_mir/borrow_check | ||
|
||
The overall flow of the borrow checker is as follows: | ||
|
||
- We first create a **local copy** C of the MIR. In the coming steps, | ||
we will modify this copy in place to modify the types and things to | ||
include references to the new regions that we are computing. | ||
- We then invoke `nll::replace_regions_in_mir` to modify this copy C. | ||
Among other things, this function will replace all of the regions in | ||
the MIR with fresh [inference variables](glossary.html). | ||
- (More details can be found in [the regionck section](./mir-regionck.html).) | ||
- Next, we perform a number of [dataflow analyses](./background.html#dataflow) | ||
that compute what data is moved and when. The results of these analyses | ||
are needed to do both borrow checking and region inference. | ||
- Using the move data, we can then compute the values of all the regions in the MIR. | ||
- (More details can be found in [the NLL section](./mir-regionck.html).) | ||
- Finally, the borrow checker itself runs, taking as input (a) the | ||
results of move analysis and (b) the regions computed by the region | ||
checker. This allows us to figure out which loans are still in scope | ||
at any particular point. | ||
|
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.