From bb2bafb606cb38f0a9ec8bb44693c149ba4288cd Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Thu, 20 Dec 2018 13:47:32 +0300 Subject: [PATCH] docs for input queries --- ARCHITECTURE.md | 4 ++- Cargo.lock | 6 ++-- crates/ra_analysis/src/imp.rs | 3 -- crates/ra_db/src/input.rs | 56 ++++++++++++++++++++++++++++------- 4 files changed, 51 insertions(+), 18 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 3b200bbc85..823db0034b 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -91,7 +91,9 @@ We use [salsa][https://github.com/salsa-rs/salsa] crate for incremental and on-demand computation. Roughly, you can think of salsa as a key-value store, but it also can compute derived values using specified functions. The `ra_db` crate provides a basic infrastructure for interracting with salsa. Crucially, it -defines most of the "input" queries: facts supplied by the client of the analyzer. +defines most of the "input" queries: facts supplied by the client of the +analyzer. Reading the docs of the `ra_db::input` module should be useful: +everithing else is strictly derived from thouse inputs. ### `crates/ra_hir` diff --git a/Cargo.lock b/Cargo.lock index 7ebe6e67f9..5e5db84c33 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -546,7 +546,7 @@ name = "parking_lot" version = "0.7.0" source = "registry+https://github.com/rust-lang/crates.io-index" dependencies = [ - "lock_api 0.1.4 (registry+https://github.com/rust-lang/crates.io-index)", + "lock_api 0.1.5 (registry+https://github.com/rust-lang/crates.io-index)", "parking_lot_core 0.4.0 (registry+https://github.com/rust-lang/crates.io-index)", ] @@ -567,10 +567,10 @@ name = "parking_lot_core" version = "0.4.0" source = "registry+https://github.com/rust-lang/crates.io-index" dependencies = [ - "libc 0.2.43 (registry+https://github.com/rust-lang/crates.io-index)", + "libc 0.2.45 (registry+https://github.com/rust-lang/crates.io-index)", "rand 0.6.1 (registry+https://github.com/rust-lang/crates.io-index)", "rustc_version 0.2.3 (registry+https://github.com/rust-lang/crates.io-index)", - "smallvec 0.6.5 (registry+https://github.com/rust-lang/crates.io-index)", + "smallvec 0.6.7 (registry+https://github.com/rust-lang/crates.io-index)", "winapi 0.3.6 (registry+https://github.com/rust-lang/crates.io-index)", ] diff --git a/crates/ra_analysis/src/imp.rs b/crates/ra_analysis/src/imp.rs index c4291885aa..b44d9297a9 100644 --- a/crates/ra_analysis/src/imp.rs +++ b/crates/ra_analysis/src/imp.rs @@ -105,9 +105,6 @@ impl AnalysisHostImpl { self.db .query_mut(ra_db::FileTextQuery) .set(remove_file.file_id, Default::default()); - self.db - .query_mut(ra_db::FileRelativePathQuery) - .set(remove_file.file_id, Default::default()); source_root.files.remove(&remove_file.path); } self.db diff --git a/crates/ra_db/src/input.rs b/crates/ra_db/src/input.rs index cccf37cc28..0957305211 100644 --- a/crates/ra_db/src/input.rs +++ b/crates/ra_db/src/input.rs @@ -1,3 +1,6 @@ +/// This modules specifies the input to rust-analyzer. In some sense, this is +/// **the** most important module, because all other fancy stuff is strickly +/// derived from this input. use std::sync::Arc; use rustc_hash::{FxHashMap}; @@ -5,20 +8,48 @@ use relative_path::RelativePathBuf; use ra_syntax::SmolStr; use salsa; -#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)] -pub struct SourceRootId(pub u32); - +/// `FileId` is an integer which uniquely identifies a file. File paths are +/// messy and system-dependent, so most of the code should work directly with +/// `FileId`, without inspecting the path. The mapping between `FileId` and path +/// and `SourceRoot` is constant. File rename is represented as a pair of +/// deletion/creation. #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)] pub struct FileId(pub u32); -#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)] -pub struct CrateId(pub u32); +/// Files are grouped into source roots. A source root is a directory on the +/// file systems which is watched for changes. Typically it corresponds to a +/// Cargo package. Source roots *might* be nested: in this case, file belongs to +/// the nearest enclosing source root. Path to files are always relative to a +/// source root, and analyzer does not know the root path of the source root at +/// all. So, a file from one source root can't refere a file in another source +/// root by path. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)] +pub struct SourceRootId(pub u32); +#[derive(Default, Clone, Debug, PartialEq, Eq)] +pub struct SourceRoot { + pub files: FxHashMap, +} + +/// `CrateGraph` is a bit of information which turns a set of text files into a +/// number of Rust crates. Each Crate is the `FileId` of it's root module, the +/// set of cfg flags (not yet implemented) and the set of dependencies. Note +/// that, due to cfg's, there might be several crates for a single `FileId`! As +/// in the rust-lang proper, a crate does not have a name. Instead, names are +/// specified on dependency edges. That is, a crate might be known under +/// different names in different dependant crates. +/// +/// Note that `CrateGraph` is build-system agnostic: it's a concept of the Rust +/// langauge proper, not a concept of the build system. In practice, we get +/// `CrateGraph` by lowering `cargo metadata` output. #[derive(Debug, Clone, Default, PartialEq, Eq)] pub struct CrateGraph { arena: FxHashMap, } +#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)] +pub struct CrateId(pub u32); + #[derive(Debug, Clone, PartialEq, Eq)] struct CrateData { file_id: FileId, @@ -57,7 +88,7 @@ impl CrateGraph { assert!(prev.is_none()); crate_id } - //FIXME: check that we don't have cycles here. + // FIXME: check that we don't have cycles here. // Just a simple depth first search from `to` should work, // the graph is small. pub fn add_dep(&mut self, from: CrateId, name: SmolStr, to: CrateId) { @@ -83,6 +114,7 @@ impl CrateGraph { salsa::query_group! { pub trait FilesDatabase: salsa::Database { + /// Text of the file. fn file_text(file_id: FileId) -> Arc { type FileTextQuery; storage input; @@ -92,30 +124,32 @@ salsa::query_group! { type FileRelativePathQuery; storage input; } + /// Source root of the file. fn file_source_root(file_id: FileId) -> SourceRootId { type FileSourceRootQuery; storage input; } + /// Contents of the source root. fn source_root(id: SourceRootId) -> Arc { type SourceRootQuery; storage input; } + /// The set of "local" (that is, from the current workspace) roots. + /// Files in local roots are assumed to change frequently. fn local_roots() -> Arc> { type LocalRootsQuery; storage input; } + /// The set of roots for crates.io libraries. + /// Files in libraries are assumed to never change. fn library_roots() -> Arc> { type LibraryRootsQuery; storage input; } + /// The crate graph. fn crate_graph() -> Arc { type CrateGraphQuery; storage input; } } } - -#[derive(Default, Clone, Debug, PartialEq, Eq)] -pub struct SourceRoot { - pub files: FxHashMap, -}