rustc_middle/query/
modifiers.rs

1//! This contains documentation which is linked from query modifiers used in the `rustc_queries!`
2//! proc macro.
3//!
4//! The dummy items in this module are used to enable hover documentation for
5//! modifier names in the query list, and to allow find-all-references to list
6//! all queries that use a particular modifier.
7#![allow(unused, non_camel_case_types)]
8
9// tidy-alphabetical-start
10//
11/// # `arena_cache` query modifier
12///
13/// Query return values must impl `Copy` and be small, but some queries must return values that
14/// don't meet those criteria. Queries marked with this modifier have their values allocated in
15/// an arena and the query returns a reference to the value. There are three cases.
16/// - If the provider function returns `T` then the query will return `&'tcx T`.
17/// - If the provider function returns `Option<T>` then the query will return `Option<&'tcx T>`.
18/// - If the provider function returns `Result<T, ErrorGuaranteed>` then the query will return
19///   `Result<&'tcx T, ErrorGuaranteed>`.
20///
21/// The query plumbing takes care of the arenas and the type manipulations.
22pub(crate) struct arena_cache;
23
24/// # `cache_on_disk` query modifier
25///
26/// The query's return values are cached to disk, and can be loaded by subsequent
27/// sessions if the corresponding dep node is green.
28///
29/// If the [`separate_provide_extern`] modifier is also present, values will only
30/// be cached to disk for "local" keys, because values for external crates should
31/// be loadable from crate metadata instead.
32pub(crate) struct cache_on_disk;
33
34/// # `depth_limit` query modifier
35///
36/// Impose a recursion call depth limit on the query to prevent stack overflow.
37pub(crate) struct depth_limit;
38
39/// # `desc { ... }` query modifier
40///
41/// The human-readable description of the query, for diagnostics and profiling. Required for every
42/// query. The block should contain a `format!`-style string literal followed by optional
43/// arguments. The query key identifier is available for use within the block, as is `tcx`.
44pub(crate) struct desc;
45
46/// # `eval_always` query modifier
47///
48/// Queries with this modifier do not track their dependencies, and are treated as always having a
49/// red (dirty) dependency instead. This is necessary for queries that interact with state that
50/// isn't tracked by the query system.
51///
52/// It can also improve performance for queries that are so likely to be dirtied by any change that
53/// it's not worth tracking their actual dependencies at all.
54///
55/// As with all queries, the return value is still cached in memory for the rest of the compiler
56/// session.
57pub(crate) struct eval_always;
58
59/// # `feedable` query modifier
60///
61/// Generate a `feed` method to set the query's value from another query.
62pub(crate) struct feedable;
63
64/// # `handle_cycle_error` query modifier
65///
66/// The default behaviour for a query cycle is to emit a cycle error and halt
67/// compilation. Queries with this modifier will instead use a custom handler,
68/// which must be provided at `rustc_query_impl::handle_cycle_error::$name`,
69/// where `$name` is the query name.
70pub(crate) struct handle_cycle_error;
71
72/// # `no_force` query modifier
73///
74/// Dep nodes of queries with this modifier will never be "forced" when trying
75/// to mark their dependents green, even if their key is recoverable from the
76/// key fingerprint.
77///
78/// Used by some queries with custom cycle-handlers to ensure that if a cycle
79/// occurs, all of the relevant query calls will be on the query stack.
80pub(crate) struct no_force;
81
82/// # `no_hash` query modifier
83///
84/// Do not hash the query's return value for incremental compilation. If the value needs to be
85/// recomputed, always mark its node as red (dirty).
86pub(crate) struct no_hash;
87
88/// # `separate_provide_extern` query modifier
89///
90/// Use separate query provider functions for local and extern crates.
91///
92/// Also affects the [`cache_on_disk`] modifier.
93pub(crate) struct separate_provide_extern;
94
95// tidy-alphabetical-end
rustc_middle/query/modifiers.rs

rustc_middle/query/
modifiers.rs
