mathieu/os-rust
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Auto merge of #93815 - camsteffen:intravisit-docs, r=cjgillot

Browse source 
Update intravisit docs

Follow-up to #90986.

r? `@cjgillot`
This commit is contained in:
bors 2022-04-30 21:24:53 +00:00
commit 2c858a7c3f
2 changed files with 35 additions and 35 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

60
compiler/rustc_hir/src/intravisit.rs
View file

@ -163,10 +163,15 @@ impl<'hir> Map<'hir> for ! {
pub mod nested_filter {
use super::Map;
/// Specifies what nested things a visitor wants to visit. The most
/// common choice is `OnlyBodies`, which will cause the visitor to
/// visit fn bodies for fns that it encounters, but skip over nested
/// item-like things.
/// Specifies what nested things a visitor wants to visit. By "nested
/// things", we are referring to bits of HIR that are not directly embedded
/// within one another but rather indirectly, through a table in the crate.
/// This is done to control dependencies during incremental compilation: the
/// non-inline bits of HIR can be tracked and hashed separately.
///
/// The most common choice is `OnlyBodies`, which will cause the visitor to
/// visit fn bodies for fns that it encounters, and closure bodies, but
/// skip over nested item-like things.
///
/// See the comments on `ItemLikeVisitor` for more details on the overall
/// visit strategy.
@ -217,27 +222,23 @@ use nested_filter::NestedFilter;
pub trait Visitor<'v>: Sized {
// this type should not be overridden, it exists for convenient usage as `Self::Map`
type Map: Map<'v> = <Self::NestedFilter as NestedFilter<'v>>::Map;
type NestedFilter: NestedFilter<'v> = nested_filter::None;
///////////////////////////////////////////////////////////////////////////
// Nested items.
/// The default versions of the `visit_nested_XXX` routines invoke
/// this method to get a map to use. By selecting an enum variant,
/// you control which kinds of nested HIR are visited; see
/// `NestedVisitorMap` for details. By "nested HIR", we are
/// referring to bits of HIR that are not directly embedded within
/// one another but rather indirectly, through a table in the
/// crate. This is done to control dependencies during incremental
/// compilation: the non-inline bits of HIR can be tracked and
/// hashed separately.
/// Override this type to control which nested HIR are visited; see
/// [`NestedFilter`] for details. If you override this type, you
/// must also override [`nested_visit_map`](Self::nested_visit_map).
///
/// **If for some reason you want the nested behavior, but don't
/// have a `Map` at your disposal:** then you should override the
/// `visit_nested_XXX` methods, and override this method to
/// `panic!()`. This way, if a new `visit_nested_XXX` variant is
/// added in the future, we will see the panic in your code and
/// fix it appropriately.
/// have a `Map` at your disposal:** then override the
/// `visit_nested_XXX` methods. If a new `visit_nested_XXX` variant is
/// added in the future, it will cause a panic which can be detected
/// and fixed appropriately.
type NestedFilter: NestedFilter<'v> = nested_filter::None;
/// If `type NestedFilter` is set to visit nested items, this method
/// must also be overridden to provide a map to retrieve nested items.
fn nested_visit_map(&mut self) -> Self::Map {
panic!(
"nested_visit_map must be implemented or consider using \
@ -245,14 +246,14 @@ pub trait Visitor<'v>: Sized {
);
}
/// Invoked when a nested item is encountered. By default does
/// nothing unless you override `nested_visit_map` to return other than
/// `None`, in which case it will walk the item. **You probably
/// don't want to override this method** -- instead, override
/// `nested_visit_map` or use the "shallow" or "deep" visit
/// patterns described on `itemlikevisit::ItemLikeVisitor`. The only
/// reason to override this method is if you want a nested pattern
/// but cannot supply a `Map`; see `nested_visit_map` for advice.
/// Invoked when a nested item is encountered. By default, when
/// `Self::NestedFilter` is `nested_filter::None`, this method does
/// nothing. **You probably don't want to override this method** --
/// instead, override [`Self::NestedFilter`] or use the "shallow" or
/// "deep" visit patterns described on
/// `itemlikevisit::ItemLikeVisitor`. The only reason to override
/// this method is if you want a nested pattern but cannot supply a
/// [`Map`]; see `nested_visit_map` for advice.
fn visit_nested_item(&mut self, id: ItemId) {
if Self::NestedFilter::INTER {
let item = self.nested_visit_map().item(id);
@ -291,9 +292,8 @@ pub trait Visitor<'v>: Sized {
}
/// Invoked to visit the body of a function, method or closure. Like
/// visit_nested_item, does nothing by default unless you override
/// `nested_visit_map` to return other than `None`, in which case it will walk
/// the body.
/// `visit_nested_item`, does nothing by default unless you override
/// `Self::NestedFilter`.
fn visit_nested_body(&mut self, id: BodyId) {
if Self::NestedFilter::INTRA {
let body = self.nested_visit_map().body(id);

10
compiler/rustc_hir/src/itemlikevisit.rs
View file

@ -17,8 +17,8 @@ use super::{ForeignItem, ImplItem, Item, TraitItem};
/// 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 the `nested_visit_map()` method
/// to return `NestedVisitorMap::OnlyBodies` and use
/// - How: Implement `intravisit::Visitor` and override the `NestedFilter` type to
/// `nested_filter::OnlyBodies` (and implement `nested_visit_map`), and use
/// `tcx.hir().visit_all_item_likes(&mut visitor.as_deep_visitor())`. Within your
/// `intravisit::Visitor` impl, implement methods like `visit_expr()` (don't forget to invoke
/// `intravisit::walk_expr()` to keep walking the subparts).
@ -29,9 +29,9 @@ use super::{ForeignItem, ImplItem, Item, TraitItem};
/// 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 the `nested_visit_map()` method
/// to return `NestedVisitorMap::All`. Walk your crate with `intravisit::walk_crate()`
/// invoked on `tcx.hir().krate()`.
/// - How: Implement `intravisit::Visitor` and override the `NestedFilter` type to
/// `nested_filter::All` (and implement `nested_visit_map`). Walk your crate with
/// `tcx.hir().walk_toplevel_module(visitor)` invoked on `tcx.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.