Source code for pyop3.cache

# Copyright (c) 2026, Imperial College London and others.
# Please see the AUTHORS file in the main source directory for
# a full list of copyright holders. All rights reserved.

"""Provides common base classes for cached objects."""

import abc
import atexit
import collections
import contextlib
import functools
import gc
import hashlib
import itertools
import os
import pickle
import re
import weakref
from collections import defaultdict
from collections.abc import Callable, Hashable, Mapping, MutableMapping
from typing import Self
from pathlib import Path
from tempfile import mkstemp
from typing import Any
from warnings import warn  # noqa F401

import cachetools
from cachetools import LRUCache  # noqa: F401
from petsc4py import PETSc

import pyop3.collections
import pyop3.config
import pyop3.constants
from pyop3 import utils
from pyop3.mpi import MPI, comm_cache_keyval, temp_internal_comm

_CACHE_CIDX = itertools.count()
_KNOWN_CACHES = []


# TODO: This should live in utils.py but there is a (bad) import of pyop3.cache
# that prohibits this for now.
[docs] class gc_disabled(contextlib.ContextDecorator): """Context manager for temporarily disabling the garbage collector. It may also be used as a function decorator. """ def __init__(self): # Track GC status using a stack because recursive uses as a function # decorator will reuse the same object self._was_enabled = [] def __enter__(self): self._was_enabled.append(gc.isenabled()) gc.disable() def __exit__(self, *args, **kwargs): if self._was_enabled.pop(-1): gc.enable()
[docs] def cached_on(get_obj, get_key: Callable = cachetools.keys.hashkey, *, multi: bool = False, make_cache: Callable[[], Mapping] = dict, get_version: Callable = lambda obj: None): """Decorator that caches function results on an object. Parameters ---------- get_obj : Callable Function returning the object that holds the cache. get_key : Callable Function returning the cache key. multi : bool Does ``get_obj`` return multiple objects? Default is `False`. make_cache : Callable Function called to create a new cache. get_version : Callable Function returning the cache 'version'. If this changes then previous caches are discarded. Default is to return `None`. """ def decorator(func): @functools.wraps(func) def wrapper(*args, **kwargs): obj = get_obj(*args, **kwargs) if multi: objs = obj else: objs = (obj,) # Handle the case where we have multiple objects: a cached value is only # valid for the versions of all the objects that is cached on # Need to make versions part of the key so that values computed for different combinations # of versions don't collide versions = tuple(get_version(obj) for obj in objs) key = (versions, get_key(*args, **kwargs)) caches = [] # Create any missing caches for obj, version in zip(objs, versions): if not hasattr(obj, "_pyop3_cache"): # Use object.__setattr__ to get around frozen dataclasses object.__setattr__(obj, "_pyop3_cache", collections.defaultdict(dict)) stored_version, cache = obj._pyop3_cache.get(func.__qualname__, (pyop3.constants.NOTHING, None)) if stored_version != version: # Invalidate the cache stored on this object only # TODO: need to think about the case where we can have multiple meshes hence multiple versions # how do we avoid retaining stale cached values? cache = make_cache() obj._pyop3_cache[func.__qualname__] = (version, cache) caches.append(cache) value = pyop3.constants.NOTHING for cache in caches: if key in cache: value = cache[key] break if value is pyop3.constants.NOTHING: value = func(*args, **kwargs) for cache in caches: cache.setdefault(key, value) return value return wrapper return decorator
[docs] def default_hashkey(*args, **kwargs) -> tuple[Hashable, ...]: args_key = tuple(utils.freeze(a) for a in args) kwargs_key = tuple((key, utils.freeze(value)) for key, value in kwargs.items()) return (args_key, kwargs_key)
[docs] def get_method_cache(obj: Any, func, cache_id, make_cache: Callable[[], Mapping]) -> None: cache_name = f"_pyop3_method_cache_{func.__name__}" if not hasattr(obj, cache_name): # Use object.__setattr__ to get around frozen dataclasses cache = make_cache() icache = _InstrumentedCache(cache_id, obj.comm, func, cache) object.__setattr__(obj, cache_name, icache) return getattr(obj, cache_name)
[docs] def cached_method(key=default_hashkey, make_cache: Callable[[], Mapping] = dict) -> Callable: """TODO""" # Store a unique integer for each 'cached_method' decorator. This # identifier is different between ranks but that is fine as it is only # used locally. cache_id = next(_CACHE_CIDX) # Since this is a cache for an instance we ignore the 'self' argument def method_cache_key(self, *args, **kwargs): return key(*args, **kwargs) def wrapper(func): return cachetools.cachedmethod( lambda self: get_method_cache(self, func, cache_id, make_cache), method_cache_key )(func) return wrapper
[docs] def cache_filter(comm=None, comm_name=None, alive=False, function=None, cache_type=None): """ Filter PyOP2 caches based on communicator, function or cache type. """ caches = _KNOWN_CACHES if comm is not None: with temp_internal_comm(comm) as icomm: cache_collection = icomm.Get_attr(comm_cache_keyval) if cache_collection is None: print(f"Communicator {icomm.name} has no associated caches") comm_name = icomm.name if comm_name is not None: caches = filter(lambda c: c.comm_name == comm_name, caches) if alive: caches = filter(lambda c: not isinstance(c, _DeadInstrumentedCache), caches) if function is not None: if isinstance(function, str): caches = filter(lambda c: function in c.func_name, caches) else: caches = filter(lambda c: c.func is function, caches) if cache_type is not None: if isinstance(cache_type, str): caches = filter(lambda c: cache_type in c.cache_name, caches) else: caches = filter(lambda c: c.cache_name == cache_type.__class__.__qualname__, caches) return [*caches]
[docs] def get_comm_caches(comm: MPI.Comm) -> dict[Hashable, Mapping]: """Return the collection of caches that are stored on a comm. If a cache stash has not already been created then a new `dict` is created and stored. Parameters ---------- comm : The communicator to get the caches from. Returns ------- dict : The collection of caches. """ comm_caches = comm.Get_attr(comm_cache_keyval) if comm_caches is None: comm_caches = {} comm.Set_attr(comm_cache_keyval, comm_caches) return comm_caches
[docs] def cached_property_until(key: Callable[[Self], Hashable]): """Decorator for a property that is cached until some value changes. For example, the ``expensive_property`` below will be cached until ``self.value`` changes, and will be recomputed with the new ``self.value`` and cached when accessed again. .. code-block:: python class MyClass: def __init__(self, value): self.value = value @cached_property_until(lambda self: self.value) def expensive_property(self): # Some expensive computation that depends on self.value ... """ def decorator(func): @property @functools.wraps(func) def wrapper(self): cache_attribute = f"_{func.__name__}_cache" current_value = key(self) cached_value = getattr(self, cache_attribute, None) if cached_value is None or cached_value[0] != current_value: result = func(self) setattr(self, cache_attribute, (current_value, result)) return result return cached_value[1] return wrapper return decorator
[docs] def cached_method_until(key: Callable[[Self], Hashable]): """Decorator for a method whose results are cached until some value changes. This is the counterpart of `cached_property_until` but for methods. When a decorated method is called, its results are cached against the set of arguments it was called with. All cached results are discarded when the value of the key changes. """ def decorator(func): @functools.wraps(func) def wrapper(self, *args, **kwargs): cache_attribute = f"_{func.__qualname__}_cache" current_key_value = key(self) cached_state = getattr(self, cache_attribute, None) if cached_state is None or cached_state[0] != current_key_value: cached_state = (current_key_value, {}) setattr(self, cache_attribute, cached_state) results = cached_state[1] args_key = default_hashkey(*args, **kwargs) if args_key not in results: results[args_key] = func(self, *args, **kwargs) return results[args_key] return wrapper return decorator
class _AbstractInstrumentedCache(abc.ABC): def __init__(self, cidx, comm_name, func): self.cidx = cidx self.comm_name = comm_name self.func = func self.func_module = func.__module__ self.func_name = func.__qualname__ self.known_cache_index = len(_KNOWN_CACHES) _KNOWN_CACHES.append(weakref.proxy(self)) @property @abc.abstractmethod def size(self) -> int: ... @property @abc.abstractmethod def maxsize(self) -> int: ... class _InstrumentedCache(_AbstractInstrumentedCache): def __init__(self, cidx, comm, func, cache): with pyop3.mpi.temp_internal_comm(comm) as icomm: comm_name = icomm.Get_name() self.cache = cache self.cache_name = cache.__class__.__qualname__ try: self.cache_loc = cache.cachedir except AttributeError: self.cache_loc = "Memory" self.hit = 0 self.miss = 0 super().__init__(cidx, comm_name, func) def __str__(self) -> str: return f"{type(self.cache).__name__}({self.func_name})" def __del__(self): _KNOWN_CACHES[self.known_cache_index] = _DeadInstrumentedCache(self.cidx, self.cache_name, self.cache_loc, self.comm_name, self.func, self.hit, self.miss, self.size, self.maxsize) def __getitem__(self, key): try: value = self.cache[key] except KeyError as e: self.miss += 1 raise e else: self.hit += 1 return value def __setitem__(self, key, value) -> None: self.cache[key] = value def __len__(self): return len(self.cache) def get(self, key, default=None): try: value = self[key] except KeyError: self.miss += 1 return default else: self.hit += 1 return value # TODO: singledispatch @property def size(self) -> int: # TODO: quite ick here, why is this happening? try: return len(self.cache) except: # noqa: E722 return self.miss # TODO: singledispatch @property def maxsize(self) -> int: if isinstance(self.cache, cachetools.Cache): return self.cache.maxsize else: return -1 class _DeadInstrumentedCache(_AbstractInstrumentedCache): def __init__(self, cidx, cache_name, cache_loc, comm, func, nhit, nmiss, size, maxsize): self.cache_name = cache_name self.cache_loc = cache_loc self.hit = nhit self.miss = nmiss self._size = size self._maxsize = maxsize super().__init__(cidx, comm, func) @property def size(self) -> int: return self._size @property def maxsize(self) -> int: return self._maxsize if pyop3.config.print_cache_stats: atexit.register(print_cache_stats) class _CacheMiss: pass CACHE_MISS = _CacheMiss() _obj_address_regex = re.compile(r"<.+ object at 0x[0-9a-f]+>")
[docs] @functools.cache def as_hexdigest(*args) -> str: """Return ``args`` as a hash string. Notes ----- This function is relatively expensive to compute so one should avoid calling it wherever possible. """ fodder = str(args) utils.debug_assert( lambda: re.search(_obj_address_regex, fodder) is None, f"Key '{fodder}' contains a memory address so cannot be cached to disk", ) return hashlib.md5(fodder.encode()).hexdigest()
[docs] class DictLikeDiskAccess(MutableMapping): """ A Dictionary like interface for storing and retrieving objects from a disk cache. """ def __init__(self, cachedir, extension=".pickle"): """ :arg cachedir: The cache directory. :arg extension: Optional extension to use for written files. """ self.cachedir = cachedir self.extension = extension
[docs] def __getitem__(self, key: Hashable) -> Any: """Retrieve a value from the disk cache.""" key = as_hexdigest(key) filepath = Path(self.cachedir, key[:2], key[2:]) try: with self.open(filepath.with_suffix(self.extension), mode="rb") as fh: value = self.read(fh) except FileNotFoundError: raise KeyError("File not on disk, cache miss") return value
def __setitem__(self, key: Hashable, value: Any) -> None: """Store a new value in the disk cache.""" key = as_hexdigest(key) k1, k2 = key[:2], key[2:] basedir = Path(self.cachedir, k1) basedir.mkdir(parents=True, exist_ok=True) # Care must be taken here to ensure that the file is created safely as # the filesystem may be network based. `mkstemp` does so securely without # race conditions: # https://docs.python.org/3/library/tempfile.html#tempfile.mkstemp # The file descriptor must also be closed after use with `os.close()`. fd, tempfile = mkstemp(suffix=".tmp", prefix=k2, dir=basedir, text=False) tempfile = Path(tempfile) # Open using `tempfile` (the filename) rather than the file descriptor # to allow redefining `self.open` with self.open(tempfile, mode="wb") as fh: self.write(fh, value) os.close(fd) # Renaming (moving) the file is guaranteed by any POSIX compliant # filesystem to be atomic. This may fail if somehow the destination is # on another filesystem, but that shouldn't happen here. filepath = basedir.joinpath(k2) tempfile.rename(filepath.with_suffix(self.extension)) def __delitem__(self, key): raise NotImplementedError(f"Cannot remove items from {self.__class__.__name__}") def __iter__(self): raise NotImplementedError(f"Cannot iterate over keys in {self.__class__.__name__}") def __len__(self): raise NotImplementedError(f"Cannot query length of {self.__class__.__name__}") def __repr__(self): return f"{self.__class__.__name__}(cachedir={self.cachedir}, extension={self.extension})" def __eq__(self, other): # Instances are the same if they have the same cachedir return (self.cachedir == other.cachedir and self.extension == other.extension)
[docs] def open(self, *args, **kwargs): return open(*args, **kwargs)
[docs] def read(self, filehandle): return pickle.load(filehandle)
[docs] def write(self, filehandle, value): pickle.dump(value, filehandle)
[docs] def default_get_comm(*args, **kwargs): """ A sensible default comm fetcher for use with `parallel_cache`. """ comms = filter( lambda arg: isinstance(arg, MPI.Comm), args + tuple(kwargs.values()) ) try: comm = next(comms) except StopIteration: raise TypeError("No comms found in args or kwargs") return comm
[docs] def default_parallel_hashkey(*args, **kwargs) -> Hashable: """ A sensible default hash key for use with `parallel_cache`.""" # We now want to actively remove any comms from args and kwargs to get # the same disk cache key. hash_args = tuple(filter( lambda arg: not isinstance(arg, MPI.Comm), args )) hash_kwargs = dict(filter( lambda arg: not isinstance(arg[1], MPI.Comm), kwargs.items() )) return default_hashkey(*hash_args, **hash_kwargs)
[docs] class DEFAULT_CACHE(dict): pass
# TODO: One day should use the compilation comm to do the bcast
[docs] def parallel_cache( hashkey=default_parallel_hashkey, get_comm: Callable = default_get_comm, make_cache: Callable[[], Mapping] = lambda: DEFAULT_CACHE(), bcast=False, heavy: bool = False, ): """Parallel cache decorator. Parameters ---------- hashkey : Callable taking ``*args`` and ``**kwargs`` and returning a hash. get_comm : Callable taking ``*args`` and ``**kwargs`` and returning the appropriate communicator. make_cache : Callable that will build a new cache (if one does not exist). This will be called every time the decorated function is called, and must return an instance of the same type every time it is called. bcast : If `True`, then generate the new cache value on one rank and broadcast to the others. If `False` then values are generated on all ranks. This option can only be `True` if the operation can be executed in serial; else it will deadlock. heavy : Do the objects stored in the cache have a large memory footprint? If yes then this cache is only used when a 'heavy' cache is set (see the `heavy_cache` context manager) and the lifetime of the objects in the cache are tied to the lifetime of the cache. """ # Store a unique integer for each 'parallel_cache' decorator so we can # identify the different caches when we wrap a function in multiple of # them (this happens for memory and disk caches for example). This # identifier is different between ranks but that is fine as it is only # used locally. cache_id = next(_CACHE_CIDX) def decorator(func): @PETSc.Log.EventDecorator(f"pyop2.caching.parallel_cache.wrapper({func.__qualname__})") @functools.wraps(func) def wrapper(*args, **kwargs): if heavy and len(_heavy_caches) == 0: pyop3.log.debug( f"{func.__qualname__} is heavy cached but no heavy cache has been set" ) with temp_internal_comm(get_comm(*args, **kwargs)) as comm: # Filter the heavy caches to only use those valid for the # provided comm. # As an illustrative example, say we are calling this function # with COMM_SELF. That means that we are only logically # collective on this rank - we have no idea what other ranks are # doing. It is therefore not safe to use a heavy cache (like # the mesh) that has broader parallel semantics (i.e. a larger comm). valid_heavy_caches = [ c for c in _heavy_caches if pyop3.mpi.comm_is_subset(c.comm, comm) ] if heavy and not valid_heavy_caches: caches = (pyop3.collections.AlwaysEmptyDict(),) cache_type = pyop3.collections.AlwaysEmptyDict value = CACHE_MISS else: def make_instrumented_cache(): cache = make_cache() return _InstrumentedCache(cache_id, comm, func, cache) comm_caches = get_comm_caches(comm) if heavy: if cache_id not in comm_caches: # This must be a weak key dictionary, where the keys are the # lifetime objects, to ensure that it does not explode comm_caches[cache_id] = WeakHeavyObjectCacheStore() caches = [] cache_type = None for lifetime_obj in valid_heavy_caches: assert lifetime_obj.comm.size <= comm.size if pyop3.config.spmd_strict: # cache access must be collective over lifetime objects lifetime_obj.comm.barrier() try: cache = comm_caches[cache_id][lifetime_obj] except KeyError: cache = make_instrumented_cache() comm_caches[cache_id][lifetime_obj] = cache if cache_type is None: cache_type = type(cache.cache) caches.append(cache) caches = tuple(caches) assert cache_type is not None assert not issubclass(cache_type, DictLikeDiskAccess), "Disk caches cannot be heavy" else: try: cache = comm_caches[cache_id] except KeyError: cache = make_instrumented_cache() comm_caches[cache_id] = cache caches = (cache,) cache_type = type(cache.cache) key = hashkey(*args, **kwargs) if heavy: for cache_idx, cache in enumerate(caches): try: value = cache[key] break except KeyError: pass else: cache_idx = None value = CACHE_MISS # In-memory caches are stashed on the comm and so must always agree # on their contents. if pyop3.config.spmd_strict: # If we are heavy also send the cache index to assert that # we are getting a cache hit from the same lifetime object check_val = (cache_idx, value is not CACHE_MISS) if not utils.is_single_valued(comm.allgather(check_val)): raise ValueError("Inconsistent cache hit behaviour") if value is CACHE_MISS: value = func(*args, **kwargs) # Insert the result into all of the caches for i, cache in enumerate(caches): if i != cache_idx: # don't insert if we already hit cache[key] = value else: # We only get multiple caches if 'heavy' is true value = cache.get(key, CACHE_MISS) if issubclass(cache_type, DictLikeDiskAccess): if bcast: # Since disk caches share state between ranks there are extra # opportunities for mismatching hit/miss results and hence # deadlocks. These include: # # 1. Race conditions # # On CI or with ensemble parallelism other processes not in this # comm may write to disk, so load imbalances on the current comm # may result in a hit on some ranks but not others. # # 2. Eager writing to disk on rank 0 # # Since broadcasting is non-blocking for the sending rank (rank 0) # it is possible for it to have written to disk before other ranks # begin the cache lookup. These ranks register a cache hit. # # If ranks disagree on whether it was a hit or miss then some ranks # will do a broadcast and others will not, ruining MPI synchronisation. # To fix this we check to see if any ranks have hit cache and, if so, # nominate that rank as the root of the subsequent broadcast. root = comm.rank if value is not CACHE_MISS else -1 root = comm.allreduce(root, op=MPI.MAX) if root >= 0: # Found a rank with a cache hit, broadcast 'value' from it value = comm.bcast(value, root=root) if value is CACHE_MISS: value = func(*args, **kwargs) if comm.rank == 0 else None value = comm.bcast(value, root=0) cache[key] = value else: if value is CACHE_MISS: value = func(*args, **kwargs) cache[key] = value else: # In-memory caches are stashed on the comm and so must always agree # on their contents. if pyop3.config.spmd_strict: check_val = value is not CACHE_MISS if not utils.is_single_valued(comm.allgather(check_val)): raise ValueError("Inconsistent cache hit behaviour") if value is CACHE_MISS: value = func(*args, **kwargs) cache[key] = value return value return wrapper return decorator
[docs] def clear_memory_cache(comm): """ Completely remove all PyOP2 caches on a given communicator. """ with temp_internal_comm(comm) as icomm: if icomm.Get_attr(comm_cache_keyval) is not None: icomm.Set_attr(comm_cache_keyval, {})
# A small collection of default simple caches memory_cache = parallel_cache
[docs] def serial_cache(hashkey=cachetools.keys.hashkey, cache_factory=lambda: DEFAULT_CACHE()): return cachetools.cached(key=hashkey, cache=cache_factory())
[docs] def disk_only_cache(*args, cachedir=pyop3.config.cache_dir, **kwargs): return parallel_cache(*args, **kwargs, make_cache=lambda: DictLikeDiskAccess(cachedir))
[docs] def memory_and_disk_cache(*args, cachedir=pyop3.config.cache_dir, **kwargs): def decorator(func): return memory_cache(*args, **kwargs)(disk_only_cache(*args, cachedir=cachedir, **kwargs)(func)) return decorator
# NOTE: It is safe to reference the object because it is only accessible # via a context manager that pops the reference after use. _heavy_caches = pyop3.collections.OrderedSet() _alive_heavy_caches = weakref.WeakSet() """The heavy caches that we have used that haven't yet been cleaned up. This attribute is useful for debugging possible memory leaks. If its size grows over time then references to the heavy cache objects are surviving. The recommended way to debug such issues is to use objgraph: objgraph.get_backrefs(item_in_cache) """
[docs] class heavy_caches: """Context manager that pushes and pops lifetime objects. For this to be parallel safe, the contract here is that, by using this decorator, you are guaranteeing that all operations within the context manager are at most collective to the level of the the communicator of the lifetime objects. """ counter = itertools.count() def __init__(self, objs: Any) -> None: objs = pyop3.collections.as_tuple(objs) objs = tuple( obj for obj in objs if not isinstance(obj, weakref.ReferenceType) ) for obj in objs: if not hasattr(obj, "_pyop3_heavy_cache_id"): object.__setattr__( obj, "_pyop3_heavy_cache_id", next(self.counter) ) for obj in objs: _alive_heavy_caches.add(obj) self._objs = objs # keep track of the objects we inserted ourselves, if they were already # there then we don't want to remove them! self._added_objs = pyop3.collections.OrderedSet() def __enter__(self) -> None: for obj in self._objs: if obj not in _heavy_caches: _heavy_caches.add(obj) self._added_objs.add(obj) def __exit__(self, *args) -> None: for obj in self._added_objs: _heavy_caches.remove(obj) self._added_objs.clear()
[docs] def with_heavy_caches(get_obj: Callable) -> Callable: """Function decorator that pushes and pops lifetime objects.""" def decorator(func): @functools.wraps(func) def wrapper(*args, **kwargs): obj = get_obj(*args, **kwargs) assert pyop3.collections.is_ordered_sequence(obj) with heavy_caches(obj): return func(*args, **kwargs) return wrapper return decorator
with_self_heavy_cache = with_heavy_caches(lambda self, *a, **kw: (self,)) """Method decorator that sets ``self`` as a heavy cache."""
[docs] class WeakHeavyObjectCacheStore: """ Keys are heavy cache objects, values are caches. If the heavy object dies then the cache must die too. WeakKeyDictionary doesn't work because of hashing obj1 = myfunc() obj2 = myfunc() obj1 == obj2 # True hash(obj1) == hash(obj2) # True obj1 is obj2 # False weakref.ref(obj1) == weakref.ref(obj2) # True hash(weakref.ref(obj1)) == hash(weakref.ref(obj2)) # True!!! We need a cache that truly works on identity hashing. """ def __init__(self): self._data = {}
[docs] def __getitem__(self, obj): assert hasattr(obj, "_pyop3_heavy_cache_id") obj_id = obj._pyop3_heavy_cache_id return self._data[obj_id]
def __setitem__(self, obj, value): assert hasattr(obj, "_pyop3_heavy_cache_id") obj_id = obj._pyop3_heavy_cache_id self._data[obj_id] = value # When obj dies remove the corresponding cache entry weakref.finalize(obj, self._drop, obj_id) def _drop(self, obj_id): self._data.pop(obj_id, None)