pub struct FileSummary {
pub path: PathBuf,
pub key: SummaryKey,
pub declarations: Vec<DeclFact>,
pub macros: Vec<MacroFact>,
pub includes: Vec<IncludeFact>,
pub guards: SummaryGuards,
pub macro_readings: Vec<MacroScopeReading>,
pub use_filter: Vec<u8>,
pub modules: ModuleReading,
}Expand description
Everything the index remembers about one file.
FileSummary::is_empty is not a curiosity: an empty summary is what a file that failed to parse, or a header
with nothing but comments, produces — and a consumer that treats “no facts” as “no declarations exist” is making
a claim the index never made. See Known in crate::symbol for the vocabulary that keeps those apart.
Fields§
§path: PathBufWhere the file is, as the path it was read from.
A path rather than a FileId, and the reason is what survives a restart: a FileId is an index into a
PathInterner that is built fresh every run, so an id written to disk means something different — or
nothing at all — when it is read back. The path is also what a consumer needs anyway: a “go to
definition” in another file opens it by name.
key: SummaryKeyWhat this summary was built from — see SummaryKey. Stored so that a loaded entry can be checked
against the file it claims to describe rather than trusted because it was found.
declarations: Vec<DeclFact>§macros: Vec<MacroFact>§includes: Vec<IncludeFact>§guards: SummaryGuards§macro_readings: Vec<MacroScopeReading>Where a scope in this file came out of a macro’s replacement list — see MacroScopeReading.
Empty for the overwhelming majority of files, and empty is the ordinary answer rather than a failure: a file that writes its own braces has nothing to record here. It is stored because it is the one part of a summary whose evidence is in another file, and a consumer that can ask that file again must be able to.
use_filter: Vec<u8>Every identifier name this file mentions, as a Bloom filter — what turns a references query from “read every file that can see the declaration” into “read the few that contain the name”.
§Why a filter and not the uses themselves
ProjectIndex::symbol_references walks the declaring file and everything that transitively includes it, and
for each one it reads the whole file before it can ask the cheap question (text.contains). The read is
the cost an index removes, and the volume says what removing it costs
(examples/use_index_cost.rs, 126 files of MSVC’s standard library):
identifier uses 299 143
every use as (name id, offset) 2 478 456 bytes 13.4% of the summaries
this filter, 14 bits per distinct name per file ~1% and no offsets, names or orderBoth answer “might this file use this name”. The filter is two orders of magnitude smaller because it is
allowed to be wrong in one direction — and it is: a false positive costs exactly what today’s code costs
for that file, one read and one contains, and nothing more, while a false negative is impossible. That
asymmetry is what makes a filter the right shape here rather than an approximation of the right shape.
Empty means “no information” and is read that way — a summary written before this field existed, or built
by a caller that did not fill it, filters nothing rather than filtering everything out. See
use_filter_might_contain.
modules: ModuleReadingWhat this file declares about modules — see ModuleReading, and plan-units.md §35 for why the
visibility walk needs it in the summary rather than in a lookup beside it.
Implementations§
Source§impl FileSummary
impl FileSummary
Sourcepub fn outline(&self) -> Vec<OutlineSymbol>
pub fn outline(&self) -> Vec<OutlineSymbol>
The file’s declarations as a tree, in source order — what an outline, a breadcrumb bar or a folding range is drawn from.
§Which reading this is, and why it is not the cooked one
The raw reading, deliberately. Every other query in this crate answers from the cooked one where it can, because a compiler’s reading is the truth about what a name means — an outline is a claim about the file, and the two differ in both directions:
- a declaration in a branch nobody takes is in an outline and was never compiled ✓ (this is the one reading that wants the dead branches — a reader editing them is looking at them);
- a type a macro declares is not:
DECLARE_HANDLE(HWND)’sHWND__is in the index and in completions, and an outline ofapi.hthat listed it would be listing a name the file never writes.
§The tree, from the facts themselves
A declaration’s DeclFact::scope is the qualified name of the scope it was written in, so a member’s
parent is the fact whose DeclFact::qualified_name equals it — one map lookup per fact, and a fact whose
parent is not in this file is a root (Widget’s members are in widget.h, not in the file that includes
it). Source order comes from DeclFact::range: a parent begins before everything written inside it, so one
sorted pass places every fact under a parent that is already placed.
Two facts of one qualified name — an overload — keep one entry in the map, so the second one’s children (if it had any) would attach to the first: an overload writes no children of its own, and a name is what a scope’s children are keyed by.
§What is not in it
Locals (DeclFact::local). An outline is the file’s structure and not the inside of every function —
and a summary cannot place a local in the function it belongs to anyway, since a local’s scope is None by
construction (see DeclFact::scope). A consumer that wants them has the file’s own scope tree, which is
what crate::FileView::scopes is for.
Source§impl FileSummary
impl FileSummary
Sourcepub fn heap_bytes(&self) -> usize
pub fn heap_bytes(&self) -> usize
What this summary costs in memory — the struct, its facts, and the strings they own.
The estimate every consumer of crate::MemoryReport is built on: it counts the vectors’ contents, not
their spare capacity, so it is a lower bound. Measured against the resident set, the difference is the
allocator’s slack — which is itself worth seeing, and is why the report prints both.
Source§impl FileSummary
impl FileSummary
Sourcepub fn empty(path: impl Into<PathBuf>, key: SummaryKey) -> Self
pub fn empty(path: impl Into<PathBuf>, key: SummaryKey) -> Self
A summary with no facts, for the file at path, built under key.
pub fn is_empty(&self) -> bool
Sourcepub fn intern_region(&mut self, region: Option<SourceRange>) -> FactGuard
pub fn intern_region(&mut self, region: Option<SourceRange>) -> FactGuard
Put a fact’s guard into the file’s region list, returning the index to store in the fact.
The single entry point for guarding a fact, so that the “many facts, one region” sharing cannot be forgotten at one call site out of five — the same reason the parser’s rules share their predicates.
Sourcepub fn take_the_directives_of(&mut self, directed: FileSummary)
pub fn take_the_directives_of(&mut self, directed: FileSummary)
Complete a summary built from a rendering with the directives of the file’s own text.
A file is read twice, and each reading answers a question the other cannot:
the text lexed, not parsed #define / #include / #if regions — what this file *directs*
the rendering parsed declarations, uses — what a compiler *reads* hereself is the first of those to be built — it came from
FileIndexer::index_rendering — and it is missing exactly the three
fields only the text can answer, because a rendering has no directives in it: they were consumed producing
it. directed is the same file’s text read by the lexer and the directive scanner and by nothing else
(FileIndexer::directive_summary), so no second parse is paid for.
§Why this is not an optimization
The three fields are what every other file’s cook reads out of this one: a header’s #defines are the
bodies its includers expand, and its #includes are the edges the closure walks. A summary that has the
rendering’s declarations and an empty macros therefore does not describe a file that declares things — it
describes a file whose macros have never been defined, and the next file’s rendering comes out with
_STD_BEGIN unexpanded and its declarations at file scope. Measured as a red test three times before this
method existed: a summary built from a rendering alone made std::Widget answer NotDeclaredHere.
§What is taken, and what is kept
Taken: macros, includes, guards, and use_filter. The filter is the text’s for a stated reason — a
rendering has the dead branches deleted, so a name used only inside one would be a false negative of
use_filter_might_contain, whose contract is that a false is certain (see use_filter_of_tokens).
Kept: declarations (the point of the exercise), macro_readings (where a scope came out of a replacement
list — the rendering’s answer, and its ranges are already the file’s), and modules (the imports are still
in the rendering, and [FileIndexer::directive_summary] cannot see them: it has no tree).
Declarations keep their own guards, which a rendering’s parse makes Unconditional — and that is the
reading, not a shortcut: a declaration in a rendering is one the compiler compiles. A caller that hands this a
directive-bearing summary gets its indices translated into the adopted region list rather than left pointing
into a list that is gone.
Sourcepub fn map_into_the_file(&mut self, rendered: &RenderedCooked) -> MapReport
pub fn map_into_the_file(&mut self, rendered: &RenderedCooked) -> MapReport
Turn a summary built from a rendering back into a summary of the file.
A rendering’s offsets are not file offsets — they are positions in text this crate spelled out — so a
summary built by parsing one describes a file that does not exist. This is what makes it usable: every
range it carries is answered for by crate::RenderedCooked::reported_span, which is the place in the file a
reader can act on (the invocation when a macro produced the text, the file’s own span otherwise), and the
facts whose ranges cannot be placed at all are dropped and counted rather than left pointing into a
rendering.
§What is in a rendering’s summary
Only declarations, and that is a property of what a rendering is: the directives are gone, so there are no macros, no includes and no conditional regions to place. The other fields are mapped anyway — the function is about the type, and a caller that hands it a summary from something directive-bearing should get answers for every range rather than silent rendering offsets in one field.
Dropping is the honest answer for a fact whose range cannot be placed: an empty node covers no token, and a
declaration the parser recovered out of nothing has nothing to point at. It is counted so that a caller can
say how much of a reading it could use — see MapReport.
Trait Implementations§
Source§impl Clone for FileSummary
impl Clone for FileSummary
Source§impl Debug for FileSummary
impl Debug for FileSummary
impl Eq for FileSummary
Source§impl PartialEq for FileSummary
impl PartialEq for FileSummary
impl StructuralPartialEq for FileSummary
Auto Trait Implementations§
impl Forget for FileSummary
impl Freeze for FileSummary
impl RefUnwindSafe for FileSummary
impl Send for FileSummary
impl Sync for FileSummary
impl Unpin for FileSummary
impl UnsafeUnpin for FileSummary
impl UnwindSafe for FileSummary
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
Source§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
Source§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
key and return true if they are equal.Source§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read more