44//! modifier names in the query list, and to allow find-all-references to list
55//! all queries that use a particular modifier.
66#![ allow( unused, non_camel_case_types) ]
7- // FIXME: Update and clarify documentation for these modifiers.
87
98// tidy-alphabetical-start
109//
1110/// # `anon` query modifier
1211///
13- /// Generate a dep node based on the dependencies of the query
12+ /// Generate a dep node based not on the query key, but on the query's dependencies.
1413pub ( crate ) struct anon ;
1514
1615/// # `arena_cache` query modifier
1716///
18- /// Use this type for the in-memory cache.
17+ /// Query return values must impl `Copy` and be small, but some queries must return values that
18+ /// doesn't meet those criteria. Queries marked with this modifier have their values allocated in
19+ /// an arena and the query returns a reference to the value. There are two cases.
20+ /// - If the provider function returns `T` then the query will return `&'tcx T`.
21+ /// - If the provider function returns `Option<T>` then the query will return `Option<&'tcx T>`.
22+ ///
23+ /// The query plumbing takes care of the arenas and the type manipulations.
1924pub ( crate ) struct arena_cache ;
2025
21- /// # `cache_on_disk_if` query modifier
26+ /// # `cache_on_disk_if { ... } ` query modifier
2227///
23- /// Cache the query to disk if the `Block` returns true.
28+ /// Cache the query result to disk if the provided block evaluates to true. The query key
29+ /// identifier is available for use within the block, as is `tcx`.
2430pub ( crate ) struct cache_on_disk_if ;
2531
2632/// # `cycle_delay_bug` query modifier
2733///
28- /// A cycle error results in a delay_bug call
34+ /// If a dependency cycle is detected, emit a delayed bug instead of a normal error.
2935pub ( crate ) struct cycle_delay_bug ;
3036
3137/// # `depth_limit` query modifier
3238///
33- /// Whether the query has a call depth limit
39+ /// Impose a recursion call depth limit on the query to prevent stack overflow.
3440pub ( crate ) struct depth_limit ;
3541
36- /// # `desc` query modifier
42+ /// # `desc { ... } ` query modifier
3743///
38- /// The description of the query. This modifier is required on every query.
44+ /// The human-readable description of the query, for diagnostics and profiling. Required for every
45+ /// query. The block should contain a `format!`-style string literal followed by optional
46+ /// arguments. The query key identifier is available for use within the block, as is `tcx`.
3947pub ( crate ) struct desc ;
4048
4149/// # `eval_always` query modifier
4250///
43- /// Always evaluate the query, ignoring its dependencies
51+ /// Queries with this modifier do not track their dependencies, and are treated as always having a
52+ /// red (dirty) dependency instead. This is necessary for queries that interact with state that
53+ /// isn't tracked by the query system.
54+ ///
55+ /// It can also improve performance for queries that are so likely to be dirtied by any change that
56+ /// it's not worth tracking their actual dependencies at all.
57+ ///
58+ /// As with all queries, the return value is still cached in memory for the rest of the compiler
59+ /// session.
4460pub ( crate ) struct eval_always ;
4561
4662/// # `feedable` query modifier
@@ -50,12 +66,13 @@ pub(crate) struct feedable;
5066
5167/// # `no_hash` query modifier
5268///
53- /// Don't hash the result, instead just mark a query red if it runs
69+ /// Do not hash the query's return value for incremental compilation. If the value needs to be
70+ /// recomputed, always mark its node as red (dirty).
5471pub ( crate ) struct no_hash ;
5572
5673/// # `separate_provide_extern` query modifier
5774///
58- /// Use a separate query provider for local and extern crates
75+ /// Use separate query provider functions for local and extern crates.
5976pub ( crate ) struct separate_provide_extern ;
6077
6178// tidy-alphabetical-end
0 commit comments