Cache Invalidation Plan

Status: Proposal

$/!\$ This is a speculative project and does not represent any firm decisions on future behavior.

This plan provides a systematic way to invalidate caches when unsupported operations occur. It supersedes the pre-existing adhoc mechanisms like verification using comparing (tip revision, tip node) or keeping a truncated node to compare with revlog.

Goal

A Mercurial repository has a number of persistent caches like the rev-branch-cache or the branchmap. Some caches are managed by extension modules like evolve's stablerange. There are a number of cases when a repository is modified in a way that would corrupt the caches. Most common case is strip, especially when the cache depends on an extension that is currently loaded or requires a different Mercurial version. This plan adds a requirement and descriptor for caches, so that problematic operations result in the automatic removal of the cache.

Detailed description

A new requirement cache-invalidation signals a repository using this plan. It also prevents older clients from breaking the cache assumption.

A new store file (.hg/store/cache-invalidation) lists all registered cache files and either either that a specific operation does not invalidate the store or that the cache file depends on a different file. The latter is meant for cases like the Sqlite journal or the branch name part of the rev-branch-cache. The current set of operations is:

register-changeset
strip-changeset
phase-transition
new-obsolete
strip-obsolete

This is implemented by transaction providing a hook for caches to register as actively handled and using the transaction changes to decide which operations have been applied. A cache file is removed (with its dependents) if at least one of the operations is not listed.

CategoryDeveloper