Skip to content

Edit "Queries" chapter #1301

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

Merged
merged 11 commits into from
Feb 17, 2022
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Rename and move footnotes
  • Loading branch information
pierwill committed Feb 17, 2022
commit 171f7ac1e525b2cae7a8ca6cd2302bfba6081be3
21 changes: 11 additions & 10 deletions src/query.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ query, it will go do the computation, but the next time, the result is
returned from a hashtable. Moreover, query execution fits nicely into
*incremental computation*; the idea is roughly that, when you invoke a
query, the result *may* be returned to you by loading stored data
from disk.[^1]
from disk.[^incr-comp-detail]

Eventually, we want the entire compiler
control-flow to be query driven. There will effectively be one
Expand All @@ -39,6 +39,10 @@ will in turn demand information about that crate, starting from the
Although this vision is not fully realized, large sections of the
compiler (for example, generating [MIR](./mir/)) currently work exactly like this.

[^incr-comp-detail]: The ["Incremental Compilation in Detail](queries/incremental-compilation-in-detail.md) chapter gives a more
in-depth description of what queries are and how they work.
If you intend to write a query of your own, this is a good read.

### Invoking queries

Invoking a query is simple. The [`TyCtxt`] ("type context") struct offers a method
Expand Down Expand Up @@ -216,7 +220,7 @@ Let's go over these elements one by one:
- **Result type of query:** the type produced by this query. This type
should (a) not use `RefCell` or other interior mutability and (b) be
cheaply cloneable. Interning or using `Rc` or `Arc` is recommended for
non-trivial data types.[^2]
non-trivial data types.[^steal]
- **Query modifiers:** various flags and options that customize how the
query is processed (mostly with respect to [incremental compilation][incrcomp]).

Expand All @@ -229,6 +233,11 @@ So, to add a query:
- Link the provider by modifying the appropriate `provide` method;
or add a new one if needed and ensure that `rustc_driver` is invoking it.

[^steal]: The one exception to those rules is the `ty::steal::Steal` type,
which is used to cheaply modify MIR in place. See the definition
of `Steal` for more details. New uses of `Steal` should **not** be
added without alerting `@rust-lang/compiler`.

#### Query structs and descriptions

For each query, the `rustc_queries` macro will generate a "query struct"
Expand Down Expand Up @@ -304,11 +313,3 @@ More discussion and issues:
[Incremental Compilation Beta]: https://internals.rust-lang.org/t/incremental-compilation-beta/4721
[Incremental Compilation Announcement]: https://blog.rust-lang.org/2016/09/08/incremental.html

[^1]: The ["Incremental Compilation in Detail](queries/incremental-compilation-in-detail.md) chapter gives a more
in-depth description of what queries are and how they work.
If you intend to write a query of your own, this is a good read.

[^2]: The one exception to those rules is the `ty::steal::Steal` type,
which is used to cheaply modify MIR in place. See the definition
of `Steal` for more details. New uses of `Steal` should **not** be
added without alerting `@rust-lang/compiler`.