Skip to main content

Module store

Module store 

Source
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 parser

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

Step 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§

IncludeBudget
How much of a project one walk may index.
IncludeIndex
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
ServedRefinements
The second pass, planned but not applied — what SummaryStore::prepare_the_re_read worked out.
StoreStats
What the store did, so that a caller can see the cache working.
SummaryStore
A project’s summaries on disk and in memory, and the rule for when each is rebuilt.
UnresolvedEdge
An #include that resolved to nothing, and where it was written.

Enums§

NotIndexedReason
Why a reached file was not opened.