Skip to main content

FileSummary

Struct FileSummary 

Source
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: PathBuf

Where 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: SummaryKey

What 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 order

Both 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: ModuleReading

What 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

Source

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)’s HWND__ is in the index and in completions, and an outline of api.h that 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

Source

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

Source

pub fn empty(path: impl Into<PathBuf>, key: SummaryKey) -> Self

A summary with no facts, for the file at path, built under key.

Source

pub fn is_empty(&self) -> bool

Source

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.

Source

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* here

self 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.

Source

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

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for FileSummary

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Eq for FileSummary

Source§

impl PartialEq for FileSummary

Source§

fn eq(&self, other: &Self) -> bool

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
Source§

impl StructuralPartialEq for FileSummary

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

Source§

fn equivalent(&self, key: &K) -> bool

Checks if this value is equivalent to the given key. Read more
Source§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

Source§

fn equivalent(&self, key: &K) -> bool

Compare self to key and return true if they are equal.
Source§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

Source§

fn equivalent(&self, key: &K) -> bool

Checks if this value is equivalent to the given key. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ

Converts 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 more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

Converts 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
Source§

impl<T> Pointable for T

Source§

const ALIGN: usize

The alignment of pointer.
Source§

type Init = T

The type for initializers.
Source§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
Source§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
Source§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
Source§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.