Expand description
Deciding when to build a summary, and what to do with the one on disk.
crate::index builds one summary from one file’s text. This module is the layer that decides whether to ask
it to: it holds the project root, the compiler configuration and the provider, computes the key the file
currently has, and rebuilds when nothing is stored under it.
§The three things it does, and the one it does not
get(path) the summary for the file as it is *now* — from disk, or freshly built and written
invalidate(path) the work set when a file changes: it, and everything that includes it
stats() how often the disk answered instead of the parserWhat it does not do is watch the filesystem or schedule the work. A caller decides when to ask, which is
what keeps this type testable without a project on disk and free of any opinion about threads — the same
division crate::index::FileIndexer makes about parsing.
§The lookup comes first
Nothing here compares a file against a stored list of what it contained, and — the part that took a design change to get right — nothing has to be understood before the disk is asked either:
1. read the text
2. the key is (hash of that text, compilation context), and both are computable without parsing
3. is a summary stored under it? then that summary is the answer, and nothing was parsed
4. otherwise build it, file it under the key, and write itStep 2 is only possible because the key has no macro-environment part, and crate::SummaryKey records why
leaving it out is sound rather than merely convenient. This is what makes a branch switch cheap: the files come
back with the contents the cache was built from, so their keys come back too, and the summaries are found
without being understood.
The version before this one built the summary first and computed the key from it, because the environment
needed the file’s own #defines. That made every lookup pay for a parse, so the cache saved writes and never
saved the thing it exists to save. StoreStats::rebuilt is the counter that says which of the two versions
is running: on a warm cache it stays at zero.
§The one case that must not be cached
A file that writes an #include whose target was not found says so — resolved: None — and that is a fact
about the filesystem rather than about the text. Storing it would produce an entry that looks valid and goes on
answering “unresolved” after the header appears, with nothing in the key to notice: which candidate paths exist
is deliberately not part of a key that has to stay computable from the text alone. So such a file is built,
returned, and not written; the caller is told through StoreStats::unstored, and the reason is the same one
gives for Unknown being a first-class answer: a wrong entry is worse than a missing
one.
The same reasoning covers the other direction — a header that appears earlier on a search path than the one that resolved — and it is worth stating plainly, because no key of this shape can catch it: what a file’s includes resolve to depends on the filesystem, so a change to which files exist is a change the key does not see. That is a job for the watcher, which knows a file was created or deleted and can invalidate the directory’s includers; until then, an unresolved include simply is never stored, so the common shape of the problem heals on its own.
Structs§
- Include
Budget - How much of a project one walk may index.
- Include
Index - What indexing one file’s includes did.
- NotIndexed
- A file the walk reached but did not index, and why.
- Prepared
- A file read, looked up and — when the disk had nothing — parsed, waiting to be put in the index.
- ReRead
- Served
Refinements - The second pass, planned but not applied — what
SummaryStore::prepare_the_re_readworked out. - Store
Stats - What the store did, so that a caller can see the cache working.
- Summary
Store - A project’s summaries on disk and in memory, and the rule for when each is rebuilt.
- Unresolved
Edge - An
#includethat resolved to nothing, and where it was written.
Enums§
- NotIndexed
Reason - Why a reached file was not opened.