salvus.flow.acta.store.stat_cache
salvus.flow.acta.store.stat_cache salvus flow acta store stat_cache File digests cached by path and filesystem metadata.
Reuse digests when size, timestamps, and inode match. Shared caches require consistent paths and metadata across hosts; host and device IDs are not part of the key. Backend failures warn once and fall back to hashing.
Files with timestamps less than one second old are always rehashed and do not seed the cache. Hashing checks metadata before and after reading. Metadata reuse still assumes the filesystem reports changes reliably and the caller keeps input files stable during a run; it cannot detect writes that restore all metadata or happen within an older timestamp collision.
Functions
default_stat_cache()
default_stat_cache()def default_stat_cache(
on_hash: Callable[[str, str], None] | None = None,
) -> StatCacheBase: ...Build the stat cache a session uses when none was passed.
Use ACTA_STAT_CACHE_URL when set, otherwise the Salvus user data
directory.
Shared caches require consistent input paths and metadata across hosts.
on_hashCallable[[str, str], None] | None — Forwarded to the backend (seeStatCacheBase).
resolve_stat_cache_url()
resolve_stat_cache_url()def resolve_stat_cache_url() -> str | None: ...Resolve the stat cache URL from the environment.
ACTA_STAT_CACHE_URL when set; an empty string disables caching. None when unset, indicating the default location.stat_cache_from_url()
stat_cache_from_url()def stat_cache_from_url(
url: str | None, on_hash: Callable[[str, str], None] | None = None
) -> StatCacheBase: ...Construct a stat cache backend from a URL.
urlstr | None —sqlite:///abs/path/to/stat-cache.sqlitefor the shared on-disk cache,memory://for a process-local one, ornull://(equivalentlyNoneor an empty string) for no cache at all.on_hashCallable[[str, str], None] | None — Forwarded to the backend (seeStatCacheBase).
StatCacheBase instance for the requested scheme.Classes
InMemoryStatCache
InMemoryStatCacheclass InMemoryStatCache(salvus.flow.acta.store.stat_cache.StatCacheBase):
def __init__(
self, on_hash: Callable[[str, str], None] | None = None
) -> None: ...In-memory file-digest cache.
on_hashCallable[[str, str], None] | None — SeeStatCacheBase.
degraded bool
degraded boolReturn whether the backend has been disabled for this run.
close()
close()def close(self) -> None: ...Release backend resources, if any.
digest()
digest()def digest(self, path: pathlib.Path | str) -> str: ...Return the content digest of the file at path.
Reuse a digest on a settled stat match; otherwise hash the file and
check its metadata again. Recent files do not seed the cache.
Invalid paths raise FileIdentityError; cache failures fall back
to hashing.
pathpathlib.Path | str — The file to identify. Made absolute but not resolved (seeStatKey).
NullStatCache
NullStatCacheclass NullStatCache(salvus.flow.acta.store.stat_cache.StatCacheBase):
def __init__(
self, on_hash: Callable[[str, str], None] | None = None
) -> None: ...File-digest cache that always rehashes.
Used for Session(stat_cache=False) or an empty ACTA_STAT_CACHE_URL.
on_hashCallable[[str, str], None] | None — SeeStatCacheBase.
degraded bool
degraded boolReturn whether the backend has been disabled for this run.
close()
close()def close(self) -> None: ...Release backend resources, if any.
digest()
digest()def digest(self, path: pathlib.Path | str) -> str: ...Return the content digest of the file at path.
Reuse a digest on a settled stat match; otherwise hash the file and
check its metadata again. Recent files do not seed the cache.
Invalid paths raise FileIdentityError; cache failures fall back
to hashing.
pathpathlib.Path | str — The file to identify. Made absolute but not resolved (seeStatKey).
SqliteStatCache
SqliteStatCacheclass SqliteStatCache(salvus.flow.acta.store.stat_cache.StatCacheBase):
def __init__(
self,
db_path: pathlib.Path | str,
on_hash: Callable[[str, str], None] | None = None,
busy_timeout_ms: int = 30000,
) -> None: ...SQLite file-digest cache for local or shared filesystems.
Open connections lazily. Request WAL mode when available; failures fall back to hashing.
Call close() to release the current connection; later use opens a new
one. Abandoned caches also close their connections automatically.
db_pathpathlib.Path | str — Path to the SQLite file. Created along with its parent directory on first use.on_hashCallable[[str, str], None] | None — SeeStatCacheBase.busy_timeout_msint — How long SQLite waits on a locked database before giving up (and, here, degrading).
degraded bool
degraded boolReturn whether the backend has been disabled for this run.
close()
close()def close(self) -> None: ...Close the SQLite connection, if one is open.
digest()
digest()def digest(self, path: pathlib.Path | str) -> str: ...Return the content digest of the file at path.
Reuse a digest on a settled stat match; otherwise hash the file and
check its metadata again. Recent files do not seed the cache.
Invalid paths raise FileIdentityError; cache failures fall back
to hashing.
pathpathlib.Path | str — The file to identify. Made absolute but not resolved (seeStatKey).
StatCacheBase
StatCacheBaseclass StatCacheBase(abc.ABC):
def __init__(
self, on_hash: Callable[[str, str], None] | None = None
) -> None: ...Cache file digests using filesystem metadata.
Subclasses implement _get and _put. Backend failures disable caching
and fall back to hashing.
on_hashCallable[[str, str], None] | None — Optional(digest, path)callback after hashing a file. Not called on cache hits.
degraded bool
degraded boolReturn whether the backend has been disabled for this run.
close()
close()def close(self) -> None: ...Release backend resources, if any.
digest()
digest()def digest(self, path: pathlib.Path | str) -> str: ...Return the content digest of the file at path.
Reuse a digest on a settled stat match; otherwise hash the file and
check its metadata again. Recent files do not seed the cache.
Invalid paths raise FileIdentityError; cache failures fall back
to hashing.
pathpathlib.Path | str — The file to identify. Made absolute but not resolved (seeStatKey).
StatKey
StatKeyclass StatKey(builtins.object):
def __init__(
self, path: str, size: int, mtime_ns: int, ctime_ns: int, inode: int
) -> None: ...Path and filesystem metadata identifying a cached file digest.
pathstr — Absolute path, without resolving symlinks.sizeint — File size in bytes (st_size).mtime_nsint — Modification time in nanoseconds (st_mtime_ns).ctime_nsint — Metadata change time in nanoseconds (native ChangeTime on Windows,st_ctime_nselsewhere).inodeint — File inode (st_ino).
Exceptions
FileIdentityError
FileIdentityErrorRaised when a file is inaccessible, invalid, or has changed contents.