Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Some comments and documentation for name resolution crate #48693

Merged
merged 2 commits into from
Mar 26, 2018
Merged

Some comments and documentation for name resolution crate #48693

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
68d6edd
Some comments and documentation for name resolution crate
vorner Feb 18, 2018
433a03e
fixup! Some comments and documentation for name resolution crate
vorner Mar 24, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 42 additions & 3 deletions src/librustc_resolve/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -162,6 +162,10 @@ enum ResolutionError<'a> {
ForwardDeclaredTyParam,
}

/// Combines an error with provided span and emits it
///
/// This takes the error provided, combines it with the span and any additional spans inside the
/// error and emits it.
fn resolve_error<'sess, 'a>(resolver: &'sess Resolver,
span: Span,
resolution_error: ResolutionError<'a>) {
Expand Down Expand Up @@ -364,7 +368,7 @@ struct BindingInfo {
binding_mode: BindingMode,
}

// Map from the name in a pattern to its binding mode.
/// Map from the name in a pattern to its binding mode.
type BindingMap = FxHashMap<Ident, BindingInfo>;

#[derive(Copy, Clone, PartialEq, Eq, Debug)]
Expand Down Expand Up @@ -559,13 +563,17 @@ impl<'a> PathSource<'a> {
}
}

/// Different kinds of symbols don't influence each other.
///
/// Therefore, they have a separate universe (namespace).
#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)]
pub enum Namespace {
TypeNS,
ValueNS,
MacroNS,
}

/// Just a helper ‒ separate structure for each namespace.
#[derive(Clone, Default, Debug)]
pub struct PerNS<T> {
value_ns: T,
Expand Down Expand Up @@ -662,6 +670,7 @@ impl<'tcx> Visitor<'tcx> for UsePlacementFinder {
}
}

/// This thing walks the whole crate in DFS manner, visiting each item, resolving names as it goes.
impl<'a, 'tcx> Visitor<'tcx> for Resolver<'a> {
fn visit_item(&mut self, item: &'tcx Item) {
self.resolve_item(item);
Expand Down Expand Up @@ -788,7 +797,9 @@ impl<'a, 'tcx> Visitor<'tcx> for Resolver<'a> {
fn visit_generics(&mut self, generics: &'tcx Generics) {
// For type parameter defaults, we have to ban access
// to following type parameters, as the Substs can only
// provide previous type parameters as they're built.
// provide previous type parameters as they're built. We
// put all the parameters on the ban list and then remove
// them one by one as they are processed and become available.
let mut default_ban_rib = Rib::new(ForwardTyParamBanRibKind);
default_ban_rib.bindings.extend(generics.params.iter()
.filter_map(|p| if let GenericParam::Type(ref tp) = *p { Some(tp) } else { None })
Expand Down Expand Up @@ -864,6 +875,16 @@ enum RibKind<'a> {
}

/// One local scope.
///
/// A rib represents a scope names can live in. Note that these appear in many places, not just
/// around braces. At any place where the list of accessible names (of the given namespace)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's probably better to say it more explicitly - the list of accessible names changes or new restrictions on name accessibility are added.

/// changes, a new rib is put onto a stack. This may be, for example, a `let` statement (because it
/// introduces variables), a macro, etc.
///
/// Different [rib kinds](enum.RibKind) are transparent for different names.
///
/// The resolution keeps a separate stack of ribs as it traverses the AST for each namespace. When
/// resolving, the name is looked up from inside out.
#[derive(Debug)]
struct Rib<'a> {
bindings: FxHashMap<Ident, Def>,
Expand All @@ -879,6 +900,11 @@ impl<'a> Rib<'a> {
}
}

/// An intermediate resolution result.
///
/// This refers to the thing referred by a name. The difference between `Def` and `Item` is that
/// items are visible in their whole block, while defs only from the place they are defined
/// forward.
enum LexicalScopeBinding<'a> {
Item(&'a NameBinding<'a>),
Def(Def),
Expand Down Expand Up @@ -909,7 +935,11 @@ enum PathResult<'a> {
}

enum ModuleKind {
/// Inline `mod something { ... }`.
Copy link
Contributor

@jseyfried jseyfried Mar 12, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ModuleKind::Block is an anonymous module, i.e. a block:

fn main() {
    fn f() {} // (1)
    {
        f(); // This resolves to (2)
        fn f() {} // (2)
    }
}

Whether a module is inline or not has no effect on name resolution.

Block(NodeId),
/// Module from another file.
///
/// Also called a normal module in the following code.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A normal module is a mod module (inline or not). ModuleKind::Def could also be a trait or an enum.

Def(Def, Name),
}

Expand Down Expand Up @@ -1194,6 +1224,9 @@ impl<'a> NameBinding<'a> {
}

/// Interns the names of the primitive types.
///
/// All other types are defined somewhere and possibly imported, but the primitive ones need
/// special handling, since they have no place of origin.
struct PrimitiveTypeTable {
primitive_types: FxHashMap<Name, PrimTy>,
}
Expand Down Expand Up @@ -1228,6 +1261,8 @@ impl PrimitiveTypeTable {
}

/// The main resolver class.
///
/// This is the visitor that walks the whole crate.
pub struct Resolver<'a> {
session: &'a Session,
cstore: &'a CrateStore,
Expand Down Expand Up @@ -1359,6 +1394,7 @@ pub struct Resolver<'a> {
injected_crate: Option<Module<'a>>,
}

/// Nothing really interesting here, it just provides memory for the rest of the crate.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: memory -> arenas

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it is obvious it contains arenas, my point was that these arenas are there to allocate memory. Should I still change it?

pub struct ResolverArenas<'a> {
modules: arena::TypedArena<ModuleData<'a>>,
local_modules: RefCell<Vec<Module<'a>>>,
Expand Down Expand Up @@ -1404,10 +1440,12 @@ impl<'a, 'b: 'a> ty::DefIdTree for &'a Resolver<'b> {
match id.krate {
LOCAL_CRATE => self.definitions.def_key(id.index).parent,
_ => self.cstore.def_key(id).parent,
}.map(|index| DefId { index: index, ..id })
}.map(|index| DefId { index, ..id })
}
}

/// This is the interface through which the rest of the compiler asks about name resolution after
/// the whole AST has been indexed.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hir::lowering::Resolver is used to resolve HIR paths generated due to desugaring during AST->HIR lowering, and to look up the resolution AST paths during lowering (get_resolution). After lowering, resolution information is embedded in the HIR; this is what the rest of the compiler uses. The Resolver is destroyed shortly after lowering.

impl<'a> hir::lowering::Resolver for Resolver<'a> {
fn resolve_hir_path(&mut self, path: &mut hir::Path, is_value: bool) {
self.resolve_hir_path_cb(path, is_value,
Expand Down Expand Up @@ -1630,6 +1668,7 @@ impl<'a> Resolver<'a> {
}
}

/// Runs the function on each namespace.
fn per_ns<T, F: FnMut(&mut Self, Namespace) -> T>(&mut self, mut f: F) -> PerNS<T> {
PerNS {
type_ns: f(self, TypeNS),
Expand Down