From 029c7f7462be59866def12e191e413a00fe5e30a Mon Sep 17 00:00:00 2001 From: nils <48135649+Nilstrieb@users.noreply.github.com> Date: Fri, 14 Oct 2022 17:22:44 +0200 Subject: [PATCH 1/3] Update query.md - queries always need a description - `QueryDescription` isn't just for descriptions (it's actually not for descriptions at all now) and always implemented by the macro - queries are not grouped into categories --- src/query.md | 34 ++++++++-------------------------- 1 file changed, 8 insertions(+), 26 deletions(-) diff --git a/src/query.md b/src/query.md index 3d60059bd..f7ead4130 100644 --- a/src/query.md +++ b/src/query.md @@ -180,20 +180,14 @@ the big macro invocation in ```rust,ignore rustc_queries! { - Other { - /// Records the type of every item. - query type_of(key: DefId) -> Ty<'tcx> { - cache { key.is_local() } - } + /// Records the type of every item. + query type_of(key: DefId) -> Ty<'tcx> { + cache { key.is_local() } } - ... } ``` -Queries are grouped into categories (`Other`, `Codegen`, `TypeChecking`, etc.). -Each group contains one or more queries. - A query definition has the following form: ```rust,ignore @@ -260,26 +254,16 @@ impl<'tcx> QueryConfig for type_of<'tcx> { } ``` -There is an additional trait that you may wish to implement called -[`self::config::QueryDescription`][QueryDescription]. This trait is -used during cycle errors to give a "human readable" name for the query, -so that we can summarize what was happening when the cycle occurred. -Implementing this trait is optional if the query key is `DefId`, but -if you *don't* implement it, you get a pretty generic error ("processing `foo`..."). -You can put new impls into the `config` module. They look something like this: +There is an additional trait with more methods called +[`self::config::QueryDescription`][QueryDescription]. This trait contains a few +extra methods which are used by the query system. [QueryConfig]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_query_system/query/config/trait.QueryConfig.html [QueryDescription]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_query_system/query/config/trait.QueryDescription.html -```rust,ignore -impl<'tcx> QueryDescription for queries::type_of<'tcx> { - fn describe(tcx: TyCtxt, key: DefId) -> String { - format!("computing the type of `{}`", tcx.def_path_str(key)) - } -} -``` -Another option is to add `desc` modifier: +Queries also have a description, which is specified using the `desc` modifier. +This description is shown to the user when cycle errors happen. ```rust,ignore rustc_queries! { @@ -292,8 +276,6 @@ rustc_queries! { } ``` -`rustc_queries` macro will generate an appropriate `impl` automatically. - ## External links Related design ideas, and tracking issues: From 60013af2c6e8d3cd0dd352755cd34744b1e5eb2b Mon Sep 17 00:00:00 2001 From: Nilstrieb <48135649+Nilstrieb@users.noreply.github.com> Date: Sat, 5 Nov 2022 15:47:05 +0100 Subject: [PATCH 2/3] Update some more things and improve wording --- src/query.md | 30 ++++++++++-------------------- 1 file changed, 10 insertions(+), 20 deletions(-) diff --git a/src/query.md b/src/query.md index f7ead4130..8ff6acd8f 100644 --- a/src/query.md +++ b/src/query.md @@ -169,12 +169,16 @@ they define both a `provide` and a `provide_extern` function, through How do you add a new query? Defining a query takes place in two steps: -1. Specify the query name and its arguments. +1. Declare the query name, its arguments and description. 2. Supply query providers where needed. -To specify the query name and arguments, you simply add an entry to -the big macro invocation in -[`compiler/rustc_middle/src/query/mod.rs`][query-mod], which looks something like: +To declare the query name and arguments, you simply add an entry to +the big macro invocation in [`compiler/rustc_middle/src/query/mod.rs`][query-mod]. +Then you need to add a documentation comment to it with some _internal_ description. +Then, provide the `desc` attribute which contains a short description of the query. +This description is shown to the user in query cycles. + +This looks something like: [query-mod]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/query/index.html @@ -182,7 +186,8 @@ the big macro invocation in rustc_queries! { /// Records the type of every item. query type_of(key: DefId) -> Ty<'tcx> { - cache { key.is_local() } + cache_on_disk_if { key.is_local() } + desc { |tcx| "computing the type of `{}`", tcx.def_path_str(key) } } ... } @@ -261,21 +266,6 @@ extra methods which are used by the query system. [QueryConfig]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_query_system/query/config/trait.QueryConfig.html [QueryDescription]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_query_system/query/config/trait.QueryDescription.html - -Queries also have a description, which is specified using the `desc` modifier. -This description is shown to the user when cycle errors happen. - -```rust,ignore -rustc_queries! { - Other { - /// Records the type of every item. - query type_of(key: DefId) -> Ty<'tcx> { - desc { |tcx| "computing the type of `{}`", tcx.def_path_str(key) } - } - } -} -``` - ## External links Related design ideas, and tracking issues: From 552de587a740d388a48726fe427b9c690927c79c Mon Sep 17 00:00:00 2001 From: Nilstrieb <48135649+Nilstrieb@users.noreply.github.com> Date: Sat, 5 Nov 2022 16:22:37 +0100 Subject: [PATCH 3/3] Remove implementation details --- src/query.md | 33 ++------------------------------- 1 file changed, 2 insertions(+), 31 deletions(-) diff --git a/src/query.md b/src/query.md index 8ff6acd8f..268a56558 100644 --- a/src/query.md +++ b/src/query.md @@ -175,8 +175,8 @@ Defining a query takes place in two steps: To declare the query name and arguments, you simply add an entry to the big macro invocation in [`compiler/rustc_middle/src/query/mod.rs`][query-mod]. Then you need to add a documentation comment to it with some _internal_ description. -Then, provide the `desc` attribute which contains a short description of the query. -This description is shown to the user in query cycles. +Then, provide the `desc` attribute which contains a _user-facing_ description of the query. +The `desc` attribute is shown to the user in query cycles. This looks something like: @@ -237,35 +237,6 @@ 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" -named after the query. This struct is a kind of placeholder -describing the query. Each query struct implements the -[`self::config::QueryConfig`][QueryConfig] trait, which has associated types for the -key/value of that particular query. Basically the code generated looks something -like this: - -```rust,ignore -// Dummy struct representing a particular kind of query: -pub struct type_of<'tcx> { data: PhantomData<&'tcx ()> } - -impl<'tcx> QueryConfig for type_of<'tcx> { - type Key = DefId; - type Value = Ty<'tcx>; - - const NAME: QueryName = QueryName::type_of; - const CATEGORY: ProfileCategory = ProfileCategory::Other; -} -``` - -There is an additional trait with more methods called -[`self::config::QueryDescription`][QueryDescription]. This trait contains a few -extra methods which are used by the query system. - -[QueryConfig]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_query_system/query/config/trait.QueryConfig.html -[QueryDescription]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_query_system/query/config/trait.QueryDescription.html - ## External links Related design ideas, and tracking issues: