Module rustc_hir::intravisit
source · Expand description
HIR walker for walking the contents of nodes.
Here are the three available patterns for the visitor strategy, in roughly the order of desirability:
- Shallow visit: Get a simple callback for every item (or item-like thing) in the HIR.
- Example: find all items with a
#[foo]
attribute on them. - How: Use the
hir_crate_items
orhir_module_items
query to traverse over item-like ids (ItemId, TraitItemId, etc.) and use tcx.def_kind andtcx.hir().item*(id)
to filter and access actual item-like thing, respectively. - Pro: Efficient; just walks the lists of item ids and gives users control whether to access the hir_owners themselves or not.
- Con: Don’t get information about nesting
- Con: Don’t have methods for specific bits of HIR, like “on every expr, do this”.
- Example: find all items with a
- Deep visit: Want to scan for specific kinds of HIR nodes within
an item, but don’t care about how item-like things are nested
within one another.
- Example: Examine each expression to look for its type and do some check or other.
- How: Implement
intravisit::Visitor
and override theNestedFilter
type tonested_filter::OnlyBodies
(and implementnested_visit_map
), and usetcx.hir().visit_all_item_likes_in_crate(&mut visitor)
. Within yourintravisit::Visitor
impl, implement methods likevisit_expr()
(don’t forget to invokeintravisit::walk_expr()
to keep walking the subparts). - Pro: Visitor methods for any kind of HIR node, not just item-like things.
- Pro: Integrates well into dependency tracking.
- Con: Don’t get information about nesting between items
- Nested visit: Want to visit the whole HIR and you care about the nesting between
item-like things.
- Example: Lifetime resolution, which wants to bring lifetimes declared on the impl into scope while visiting the impl-items, and then back out again.
- How: Implement
intravisit::Visitor
and override theNestedFilter
type tonested_filter::All
(and implementnested_visit_map
). Walk your crate withtcx.hir().walk_toplevel_module(visitor)
invoked ontcx.hir().krate()
. - Pro: Visitor methods for any kind of HIR node, not just item-like things.
- Pro: Preserves nesting information
- Con: Does not integrate well into dependency tracking.
If you have decided to use this visitor, here are some general notes on how to do so:
Each overridden visit method has full control over what
happens with its node, it can do its own traversal of the node’s children,
call intravisit::walk_*
to apply the default traversal algorithm, or prevent
deeper traversal by doing nothing.
When visiting the HIR, the contents of nested items are NOT visited
by default. This is different from the AST visitor, which does a deep walk.
Hence this module is called intravisit
; see the method visit_nested_item
for more details.
Note: it is an important invariant that the default visitor walks the body of a function in “execution order” - more concretely, if we consider the reverse post-order (RPO) of the CFG implied by the HIR, then a pre-order traversal of the HIR is consistent with the CFG RPO on the initial CFG point of each HIR node, while a post-order traversal of the HIR is consistent with the CFG RPO on each final CFG point of each CFG node.
One thing that follows is that if HIR node A always starts/ends executing before HIR node B, then A appears in traversal pre/postorder before B, respectively. (This follows from RPO respecting CFG domination).
This order consistency is required in a few places in rustc, for example generator inference, and possibly also HIR borrowck.
Modules
Enums
Traits
- An abstract representation of the HIR
rustc_middle::hir::map::Map
. - Each method of the Visitor trait is a hook to be potentially overridden. Each method’s default implementation recursively visits the substructure of the input via the corresponding
walk
method; e.g., thevisit_mod
method by default callsintravisit::walk_mod
.