Struct BuildCache 

pub struct BuildCache { /* private fields */ }

Implementations

impl BuildCache

pub fn new( cache_dir: PathBuf, max_size_mb: usize, expiration_hours: u64, config_fingerprint: &str, ) -> Result<Self>

pub fn cache_dir(&self) -> &Path

The cache directory this cache was constructed with (post config- fingerprint validation/wipe). Callers that persist their own files alongside the document cache – e.g. BuildEnvironment::save’s env.bin – ride the same directory and are therefore covered by the same fingerprint-mismatch wipe.

pub fn config_changed(&self) -> bool

Whether this cache directory’s stored fingerprint disagreed with the configuration it was opened with — the whole directory was then discarded, this build’s documents, doctrees and env.bin included.

A first build counts too (there is no stored fingerprint to agree with), and in that case the effect matches Sphinx’s CONFIG_NEW: nothing carried over from a previous build is usable, so every document is outdated.

The resemblance stops there, and deliberately so. Sphinx’s CONFIG_CHANGED (environment/__init__.py:366-369) fires only for config values whose rebuild class is 'env' and never deletes doctrees, the environment or the intersphinx cache; this crate compares one whole-configuration digest and wipes the directory. The digest is therefore taken over a filtered configuration — see builder::EXCLUDED_FROM_FINGERPRINT — so that operational flags (-W, -n), which Sphinx cannot invalidate on, cannot invalidate here either.

pub fn get_document(&self, file_path: &Path) -> Result<Document>

pub fn get_document_with<T>( &self, file_path: &Path, accept: impl FnOnce(&Document) -> Option<T>, ) -> Option<(Document, T)>

Look up a cached document, letting the caller have the final say.

accept runs only after the entry passed the cache’s own checks (content+mtime hash, expiry). Returning None from it means the caller cannot actually use the entry — because some companion state it needs is missing, say — and the lookup is then counted and reported as a miss, not a hit: a “hit” the build has to redo anyway is not a hit. Anything accept computes from the document (loading that companion state) comes back alongside it, so callers don’t have to do the work twice.

pub fn store_document( &self, file_path: &Path, document: &Document, ) -> Result<()>

pub fn invalidate(&self, file_path: &Path)

pub fn clear(&self) -> Result<()>

Empty the cache, in memory and on disk (-E, --clean).

The fingerprint file is written back immediately: it records which configuration the directory belongs to, and leaving it missing would make the next build mistake this deliberate emptying for a configuration change and throw away everything the build that follows this one is about to cache.

pub fn hit_count(&self) -> usize

pub fn miss_count(&self) -> usize

pub fn hit_ratio(&self) -> f64

pub fn size_mb(&self) -> f64