File Cache

Directory-level cache with pluggable eviction policies and storage backends.

Why

Large-scale engineering simulations produce files that are expensive to parse and process. When a server extracts visualization data or structural metadata from these files, caching the results on disk avoids redundant computation — especially when multiple users access the same data. The extracted data consists of large numerical arrays that are not practical to store in a database, so a directory-level file cache is the natural fit. A pluggable storage backend allows the same cache to work on local disk (on-premise) or S3 (cloud).

Overview

vcti-file-cache manages a collection of cached model directories. Each directory is tracked via lightweight metadata (access count and size). A background thread periodically computes directory sizes and evicts directories when the total exceeds a configured threshold, using a pluggable eviction policy (LRU, LFU, or size-weighted LRU).

The cache and model directories are accessed through context managers that handle directory creation, access tracking, and cleanup automatically. Storage is abstracted behind a CacheStorage protocol — the built-in LocalStorage backend uses the local filesystem; other backends (e.g. S3) can be added by implementing the same protocol. No external dependencies.

Installation

pip install vcti-file-cache>=1.0.0

Quick Start

from pathlib import Path
from vcti.filecache import FileCache, CacheManagerConfig

config = CacheManagerConfig(evict_above=50 * 1024**3)  # 50 GB

# root= is shorthand for LocalStorage
with FileCache(root=Path("/data/cache"), config=config) as cache:

    # model() returns a context manager — creates the directory,
    # tracks access count and timestamps automatically
    with cache.model("ab/cd/model_abc123") as model:
        save_mesh(Path(model.path) / "mesh.vtu")
        save_result(Path(model.path) / "result.h5")

    # Same call for read access — access time updates automatically
    with cache.model("ab/cd/model_abc123") as model:
        data = load(Path(model.path) / "result.h5")

    # Manual eviction (background thread also runs automatically)
    cache.evict()

Explicit storage backend

from vcti.filecache import FileCache, CacheManagerConfig, LocalStorage

storage = LocalStorage(root=Path("/data/cache"))
config = CacheManagerConfig(evict_above=50 * 1024**3)

with FileCache(storage=storage, config=config) as cache:
    ...

Custom eviction policy

from vcti.filecache import FileCache, CacheManagerConfig, LfuPolicy

config = CacheManagerConfig(
    evict_above=50 * 1024**3,
    policy=LfuPolicy(),   # evict least frequently accessed first
    interval=120.0,        # background cycle every 2 minutes
)

with FileCache(root=Path("/data/cache"), config=config) as cache:
    ...

Observer for lifecycle events

from vcti.filecache import LoggingObserver, CacheManagerConfig, FileCache

# Built-in LoggingObserver uses stdlib logging
config = CacheManagerConfig(
    evict_above=50 * 1024**3,
    observer=LoggingObserver(),
)

with FileCache(root=Path("/data/cache"), config=config) as cache:
    ...

Or subclass CacheObserver for custom behavior:

from vcti.filecache import CacheObserver

class MyObserver(CacheObserver):
    def on_evict(self, path: str) -> None:
        print(f"Evicted: {path}")

    def on_error(self, error: Exception, context: str) -> None:
        print(f"Error in {context}: {error}")

Core API

FileCache

CacheManagerConfig

CacheStorage

Protocol for storage backends. Implement this to add a new backend. LocalStorage is the built-in implementation for local filesystem.

ModelDir

Eviction Policies

CacheManager

Starts automatically when a FileCache enters its context. Runs as a daemon thread that periodically scans model directories, updates their sizes, and evicts when total size exceeds the threshold. Singleton per storage root — multiple FileCache instances sharing the same storage share one manager.

Dependencies

None. Standard library only.