Coverage for src/metaclass_registry/caches.py: 100%
88 statements
« prev ^ index » next coverage.py v7.17.3, created at 2026-11-17 00:39 +0000
« prev ^ index » next coverage.py v7.17.3, created at 2026-11-17 00:39 +0000
1"""Bounded value caches and the process-local cache family.
3``BoundedCache`` is a plain LRU whose lifetime belongs to whoever holds it.
4``ProcessLocalBoundedCache`` is a registered family: every subclass is a member by
5inheritance and owns one process-local singleton, so a whole family (or any
6subfamily) can be cleared without a roster of cache types.
7"""
9from __future__ import annotations
11from _thread import LockType
12from collections import OrderedDict
13from dataclasses import dataclass, field
14from threading import Lock
15from typing import Any, ClassVar, Generic, TypeVar, cast
17from .core import AutoRegisterMeta, RegistryConfig, RegistryDict
19CacheKey = TypeVar("CacheKey")
20CachedValue = TypeVar("CachedValue")
21_ProcessCacheT = TypeVar("_ProcessCacheT", bound="ProcessLocalBoundedCache[Any, Any]")
24@dataclass(slots=True)
25class BoundedCache(Generic[CacheKey, CachedValue]):
26 """Bounded LRU values with lifetime supplied by their owning consumer."""
28 max_entries: int = 4096
29 entries: OrderedDict[CacheKey, CachedValue] = field(default_factory=OrderedDict)
31 def cached_value(self, key: CacheKey) -> CachedValue | None:
32 if key not in self.entries:
33 return None
34 value = self.entries[key]
35 self.entries.move_to_end(key)
36 return value
38 def store_value(self, key: CacheKey, value: CachedValue) -> CachedValue:
39 self.entries[key] = value
40 self.entries.move_to_end(key)
41 while len(self.entries) > self.max_entries:
42 self.entries.popitem(last=False)
43 return value
45 def clear(self) -> None:
46 """Discard all values retained by this cache instance."""
47 self.entries.clear()
50@dataclass
51class SynchronizedBoundedCache(BoundedCache[CacheKey, CachedValue]):
52 """Bounded storage whose individual mutations share one instance lock."""
54 _lock: LockType = field(default_factory=Lock, init=False, repr=False, compare=False)
56 def cached_value(self, key: CacheKey) -> CachedValue | None:
57 with self._lock:
58 return super().cached_value(key)
60 def store_value(self, key: CacheKey, value: CachedValue) -> CachedValue:
61 with self._lock:
62 return super().store_value(key, value)
64 def clear(self) -> None:
65 with self._lock:
66 super().clear()
69def _module_class_name(name: str, cls: type) -> str:
70 # ``dataclass(slots=True)`` rebuilds a class before restoring its ``__qualname__``,
71 # so the key uses ``__name__`` and the rebuilt class replaces its predecessor.
72 return f"{cls.__module__}.{name}"
75_PROCESS_CACHE_FAMILY: RegistryDict = {}
78@dataclass(slots=True)
79class ProcessLocalBoundedCache(
80 BoundedCache[CacheKey, CachedValue],
81 metaclass=AutoRegisterMeta,
82):
83 """Bounded values with one process-local singleton per class.
85 Subclassing is membership: each subclass registers under ``module.ClassName``
86 and gets its own singleton and lock, so a warmed parent never becomes a
87 child's singleton and ``clear_process_caches`` reaches every member.
88 """
90 __registry_config__: ClassVar[RegistryConfig] = RegistryConfig(
91 registry_dict=_PROCESS_CACHE_FAMILY,
92 key_attribute="process_cache_key",
93 key_extractor=_module_class_name,
94 registry_name="process-local cache",
95 log_registration=False,
96 )
97 __registry__: ClassVar[RegistryDict] = _PROCESS_CACHE_FAMILY
99 process_cache_key: ClassVar[str | None] = None
100 _process_cache: ClassVar[ProcessLocalBoundedCache[Any, Any] | None] = None
101 _process_cache_lock: ClassVar[LockType] = Lock()
103 def __init_subclass__(cls, **kwargs: Any) -> None:
104 # slots=True replaces the class; name the final class for cooperative super.
105 super(ProcessLocalBoundedCache, cls).__init_subclass__(**kwargs)
106 cls._process_cache = None
107 cls._process_cache_lock = Lock()
108 cls.process_cache_key = None
110 @classmethod
111 def process_cache(cls: type[_ProcessCacheT]) -> _ProcessCacheT:
112 """Return this class's process-local singleton, creating it once."""
113 cache = cls._process_cache
114 if cache is None:
115 with cls._process_cache_lock:
116 cache = cls._process_cache
117 if cache is None:
118 cache = cls()
119 cls._process_cache = cache
120 return cast(_ProcessCacheT, cache)
122 @classmethod
123 def clear_process_cache(cls) -> None:
124 """Discard the values held by this class's singleton, keeping the singleton."""
125 cache = cls._process_cache
126 if cache is not None:
127 cache.clear()
129 @classmethod
130 def clear_process_caches(cls) -> None:
131 """Clear the singleton of every registered member that subclasses ``cls``."""
132 for cache_type in tuple(cls.__registry__.values()):
133 if issubclass(cache_type, cls):
134 cache_type.clear_process_cache()
137class IdentityBoundProcessCache(ProcessLocalBoundedCache[int, tuple[object, Any]]):
138 """Process-local values bound to an owner object, protected against ``id`` reuse."""
140 def get_bound(self, owner: object) -> Any | None:
141 cache_key = id(owner)
142 cached = self.cached_value(cache_key)
143 if cached is None:
144 return None
145 cached_owner, value = cached
146 if cached_owner is not owner:
147 del self.entries[cache_key]
148 return None
149 return value
151 def put_bound(self, owner: object, value: Any) -> Any:
152 return self.store_value(id(owner), (owner, value))[1]