Module query

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.
• fatal_cycle: 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 via tcx.ensure_ok(), return Result<(), 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 returning Result<_, 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 (and 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.

Re-exports

pub use plumbing::IntoQueryParam;

pub use plumbing::TyCtxtAt;

pub use plumbing::TyCtxtEnsureDone;

pub use plumbing::TyCtxtEnsureOk;

Modules

arena_cached 🔒

cached

descs

erase

keys 🔒

Defines the set of legal keys that can be used in queries.

on_disk_cache

plumbing

queries

Macros

rustc_feedable_queries 🔒

Structs

DynamicQueries

ExternProviders

LocalCrate

Placeholder for CrateNum’s “local” counterpart

Providers

QueryArenas

QueryCaches

QueryEngine

QueryStates

Traits

AsLocalKey

Key

The Key trait controls what types can legally be used as the key for a query.