Expand description
§The rustc Query System: Query Definitions and Modifiers
The core processes in rustc are shipped as queries. Each query is a demand-driven function from some key to a value. The execution result of the function is cached and directly read during the next request, thereby improving compilation efficiency. Some results are saved locally and directly read during the next compilation, which are core of incremental compilation.
§How to Read This Module
Each query block in this file defines a single query, specifying its key and value types, along with various modifiers.
These query definitions are processed by the rustc_macros, which expands them into the necessary boilerplate code
for the query system—including the Providers struct (a function table for all query implementations, where each field is
a function pointer to the actual provider), caching, and dependency graph integration.
Note: The Providers struct is not a Rust trait, but a struct generated by the rustc_macros to hold all provider functions.
The rustc_macros also supports a set of query modifiers (see below) that control the behavior of each query.
The actual provider functions are implemented in various modules and registered into the Providers struct
during compiler initialization (see rustc_interface::passes::DEFAULT_QUERY_PROVIDERS).
§Query Modifiers
Query modifiers are special flags that alter the behavior of a query. They are parsed and processed by the rustc_macros
The main modifiers are:
desc { ... }: Sets the human-readable description for diagnostics and profiling. Required for every query.arena_cache: Use an arena for in-memory caching of the query result.cache_on_disk_if { ... }: Cache the query result to disk if the provided block evaluates to true.cycle_fatal: If a dependency cycle is detected, abort compilation with a fatal error.cycle_delay_bug: If a dependency cycle is detected, emit a delayed bug instead of aborting immediately.cycle_stash: If a dependency cycle is detected, stash the error for later handling.no_hash: Do not hash the query result for incremental compilation; just mark as dirty if recomputed.anon: Make the query anonymous in the dependency graph (no dep node is created).eval_always: Always evaluate the query, ignoring its dependencies and cached results.depth_limit: Impose a recursion depth limit on the query to prevent stack overflows.separate_provide_extern: Use separate provider functions for local and external crates.feedable: Allow the query result to be set from another query (“fed” externally).return_result_from_ensure_ok: When called viatcx.ensure_ok(), returnResult<(), ErrorGuaranteed>instead of(). If the query needs to be executed and returns an error, the error is returned to the caller. Only valid for queries returningResult<_, ErrorGuaranteed>.
For the up-to-date list, see the QueryModifiers struct in
rustc_macros/src/query.rs
and for more details in incremental compilation, see the
Query modifiers in incremental compilation section of the rustc-dev-guide.
§Query Expansion and Code Generation
The rustc_macros::rustc_queries macro expands each query definition into:
- A method on
TyCtxt(andcrate::query::TyCtxtAt) for invoking the query. - Provider traits and structs for supplying the query’s value.
- Caching and dependency graph integration.
- Support for incremental compilation, disk caching, and arena allocation as controlled by the modifiers.
The macro-based approach allows the query system to be highly flexible and maintainable, while minimizing boilerplate.
For more details, see the rustc-dev-guide.
Modules§
- _analyzer_
hints 🔒 - _cache_
on_ disk_ if_ fns - _description_
fns - Functions that format a human-readable description of each query
and its key, as specified by the
descquery modifier. - adt_
async_ destructor - adt_
async_ drop_ tys - adt_def
- adt_
destructor - adt_
drop_ tys - adt_
dtorck_ constraint - adt_
significant_ drop_ tys - adt_
sizedness_ constraint - all_
diagnostic_ items - all_
local_ trait_ impls - alloc_
error_ handler_ kind - allocator_
kind - analysis
- anon_
const_ kind - asm_
target_ features - associated_
item - associated_
item_ def_ ids - associated_
items - associated_
types_ for_ impl_ traits_ in_ trait_ or_ impl - assumed_
wf_ types - assumed_
wf_ types_ for_ rpitit - asyncness
- attrs_
for_ def - backend_
optimization_ level - check_
coroutine_ obligations - check_
expectations - check_
externally_ implementable_ items - check_
liveness - check_
match - check_
mod_ attrs - check_
mod_ deathness - check_
mod_ privacy - check_
mod_ unstable_ api_ usage - check_
mono_ item - check_
potentially_ region_ dependent_ goals - check_
private_ in_ public - check_
tail_ calls - check_
transmutes - check_
type_ wf - check_
unsafety - check_
unused_ traits - check_
validity_ requirement - check_
well_ formed - clashing_
extern_ declarations - closure_
saved_ names_ of_ captured_ variables - closure_
typeinfo - codegen_
fn_ attrs - codegen_
select_ candidate - codegen_
unit - coerce_
unsized_ info - coherent_
trait - collect_
and_ partition_ mono_ items - collect_
return_ position_ impl_ trait_ in_ trait_ tys - compare_
impl_ item - const_
conditions - const_
of_ item - const_
param_ default - constness
- coroutine_
by_ move_ body_ def_ id - coroutine_
for_ closure - coroutine_
hidden_ types - coroutine_
kind - coverage_
attr_ on - coverage_
ids_ info - crate_
extern_ paths - crate_
for_ resolver - crate_
hash - crate_
host_ hash - crate_
incoherent_ impls - crate_
inherent_ impls - crate_
inherent_ impls_ overlap_ check - crate_
inherent_ impls_ validity_ check - crate_
name - crate_
variances - crates
- cross_
crate_ inlinable - debugger_
visualizers - deduced_
param_ attrs - def_
ident_ span - def_
kind - def_
span - default_
field - defaultness
- defined_
lang_ items - dep_
kind - dependency_
formats - derive_
macro_ expansion - diagnostic_
hir_ wf_ check - diagnostic_
items - doc_
link_ resolutions - doc_
link_ traits_ in_ scope - dropck_
outlives - duplicate_
crate_ names - dylib_
dependency_ formats - dyn_
compatibility_ violations - early_
lint_ checks - effective_
visibilities - enforce_
impl_ non_ lifetime_ params_ are_ constrained - entry_
fn - env_
var_ os - erase_
and_ anonymize_ regions_ ty - eval_
static_ initializer - eval_
to_ allocation_ raw - eval_
to_ const_ value_ raw - eval_
to_ valtree - evaluate_
obligation - evaluate_
root_ goal_ for_ proof_ tree_ raw - explicit_
implied_ const_ bounds - explicit_
implied_ predicates_ of - explicit_
item_ bounds - explicit_
item_ self_ bounds - explicit_
predicates_ of - explicit_
super_ predicates_ of - explicit_
supertraits_ containing_ assoc_ item - expn_
that_ defined - exportable_
items - exported_
generic_ symbols - exported_
non_ generic_ symbols - extern_
crate - externally_
implementable_ items - extra_
filename - features_
query - first_
method_ vtable_ slot - fn_
abi_ of_ fn_ ptr - fn_
abi_ of_ instance - fn_
arg_ idents - fn_sig
- foreign_
modules - generics_
of - generics_
require_ sized_ self - get_
lang_ items - global_
backend_ features - has_
alloc_ error_ handler - has_
ffi_ unwind_ calls - has_
global_ allocator - has_
panic_ handler - has_
significant_ drop_ raw - has_
structural_ eq_ impl - hir_
attr_ map - hir_
crate - hir_
crate_ items - hir_
module_ items - hir_
owner_ parent_ q - impl_
item_ implementor_ ids - impl_
parent - impl_
self_ is_ guaranteed_ unsized - impl_
super_ outlives - impl_
trait_ header - implementations_
of_ trait - implied_
outlives_ bounds - implied_
target_ features - in_
scope_ traits_ map - incoherent_
impls - inferred_
outlives_ crate - inferred_
outlives_ of - inhabited_
predicate_ adt - inhabited_
predicate_ type - inherent_
impls - inherit_
sig_ for_ delegation_ item - inherited_
align - instantiate_
and_ check_ impossible_ predicates - intrinsic_
raw - is_
async_ drop_ raw - is_
codegened_ item - is_
compiler_ builtins - is_
copy_ raw - is_
doc_ hidden - is_
doc_ notable_ trait - is_
dyn_ compatible - is_
freeze_ raw - is_
impossible_ associated_ item - is_
late_ bound_ map - is_
mir_ available - is_
no_ builtins - is_
panic_ runtime - is_
private_ dep - is_
profiler_ runtime - is_
promotable_ const_ fn - is_
reachable_ non_ generic - is_
rhs_ type_ const - is_
sized_ raw - is_
unpin_ raw - is_
unreachable_ local_ definition - is_
use_ cloned_ raw - item_
bounds - item_
non_ self_ bounds - item_
self_ bounds - items_
of_ instance - late_
bound_ vars_ map - layout_
of - lib_
features - limits
- lint_
expectations - lint_
mod - lints_
that_ dont_ need_ to_ run - list_
significant_ drop_ tys - lit_
to_ const - live_
symbols_ and_ ignored_ derived_ traits - local_
def_ id_ to_ hir_ id - local_
trait_ impls - lookup_
const_ stability - lookup_
default_ body_ stability - lookup_
deprecation_ entry - lookup_
stability - method_
autoderef_ steps - mir_
borrowck - mir_
built - mir_
callgraph_ cyclic - mir_
const_ qualif - mir_
coroutine_ witnesses - mir_
drops_ elaborated_ and_ const_ checked - mir_
for_ ctfe - mir_
inliner_ callees - mir_
keys - mir_
promoted - mir_
shims - missing_
extern_ crate_ item - missing_
lang_ items - module_
children - named_
variable_ map - native_
libraries - native_
library - needs_
async_ drop_ raw - needs_
drop_ raw - nested_
bodies_ within - normalize_
canonicalized_ free_ alias - normalize_
canonicalized_ inherent_ projection - normalize_
canonicalized_ projection - num_
extern_ def_ ids - object_
lifetime_ default - opaque_
captured_ lifetimes - opaque_
ty_ origin - opaque_
types_ defined_ by - opt_
ast_ lowering_ delayed_ lints - opt_
hir_ owner_ nodes - optimized_
mir - orphan_
check_ impl - output_
filenames - own_
existential_ vtable_ entries - panic_
in_ drop_ strategy - param_
env - params_
in_ repr - postorder_
cnums - predicates_
of - proc_
macro_ decls_ static - promoted_
mir - reachable_
non_ generics - reachable_
set - region_
scope_ tree - registered_
tools - rendered_
const - rendered_
precise_ capturing_ args - representability
- representability_
adt_ ty - required_
panic_ strategy - resolutions
- resolve_
bound_ vars - resolve_
instance_ raw - resolver_
for_ lowering_ raw - reveal_
opaque_ types_ in_ bounds - rust_
target_ features - sanitizer_
settings_ for - shallow_
lint_ levels_ on - should_
inherit_ track_ caller - size_
estimate - skip_
move_ check_ fns - source_
span - specialization_
enabled_ in - specialization_
graph_ of - specializes
- stability_
implications - stable_
order_ of_ exportable_ impls - stripped_
cfg_ items - supertrait_
vtable_ slot - symbol_
mangling_ version - symbol_
name - tag_
for_ variant - thir_
abstract_ const - thir_
body - trait_
def - trait_
explicit_ predicates_ and_ bounds - trait_
impls_ in_ crate - trait_
impls_ of - traits
- trigger_
delayed_ bug - trimmed_
def_ paths - trivial_
const - try_
normalize_ generic_ arg_ after_ erasing_ regions - ty_span
- type_
alias_ is_ lazy - type_of
- type_
of_ opaque - type_
of_ opaque_ hir_ typeck - type_
op_ ascribe_ user_ type - type_
op_ normalize_ clause - type_
op_ normalize_ fn_ sig - type_
op_ normalize_ poly_ fn_ sig - type_
op_ normalize_ ty - type_
op_ prove_ predicate - type_
param_ predicates - typeck
- typing_
env_ normalized_ for_ post_ analysis - unsizing_
params_ for_ adt - upstream_
async_ drop_ glue_ for - upstream_
drop_ glue_ for - upstream_
monomorphizations - upstream_
monomorphizations_ for - upvars_
mentioned - used_
crate_ source - used_
crates - used_
trait_ imports - valtree_
to_ const_ val - variances_
of - visibility
- visible_
parent_ map - vtable_
allocation - vtable_
entries - wasm_
import_ module_ map
Macros§
Structs§
- Extern
Providers - PerQueryV
Tables - Holds a
QueryVTablefor each query. - Providers
- Query
Arenas - Holds per-query arenas for queries with the
arena_cachemodifier. - Query
Caches - Query
Engine - Query
States