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

1"""Bounded value caches and the process-local cache family. 

2 

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""" 

8 

9from __future__ import annotations 

10 

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 

16 

17from .core import AutoRegisterMeta, RegistryConfig, RegistryDict 

18 

19CacheKey = TypeVar("CacheKey") 

20CachedValue = TypeVar("CachedValue") 

21_ProcessCacheT = TypeVar("_ProcessCacheT", bound="ProcessLocalBoundedCache[Any, Any]") 

22 

23 

24@dataclass(slots=True) 

25class BoundedCache(Generic[CacheKey, CachedValue]): 

26 """Bounded LRU values with lifetime supplied by their owning consumer.""" 

27 

28 max_entries: int = 4096 

29 entries: OrderedDict[CacheKey, CachedValue] = field(default_factory=OrderedDict) 

30 

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 

37 

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 

44 

45 def clear(self) -> None: 

46 """Discard all values retained by this cache instance.""" 

47 self.entries.clear() 

48 

49 

50@dataclass 

51class SynchronizedBoundedCache(BoundedCache[CacheKey, CachedValue]): 

52 """Bounded storage whose individual mutations share one instance lock.""" 

53 

54 _lock: LockType = field(default_factory=Lock, init=False, repr=False, compare=False) 

55 

56 def cached_value(self, key: CacheKey) -> CachedValue | None: 

57 with self._lock: 

58 return super().cached_value(key) 

59 

60 def store_value(self, key: CacheKey, value: CachedValue) -> CachedValue: 

61 with self._lock: 

62 return super().store_value(key, value) 

63 

64 def clear(self) -> None: 

65 with self._lock: 

66 super().clear() 

67 

68 

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}" 

73 

74 

75_PROCESS_CACHE_FAMILY: RegistryDict = {} 

76 

77 

78@dataclass(slots=True) 

79class ProcessLocalBoundedCache( 

80 BoundedCache[CacheKey, CachedValue], 

81 metaclass=AutoRegisterMeta, 

82): 

83 """Bounded values with one process-local singleton per class. 

84 

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 """ 

89 

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 

98 

99 process_cache_key: ClassVar[str | None] = None 

100 _process_cache: ClassVar[ProcessLocalBoundedCache[Any, Any] | None] = None 

101 _process_cache_lock: ClassVar[LockType] = Lock() 

102 

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 

109 

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) 

121 

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() 

128 

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() 

135 

136 

137class IdentityBoundProcessCache(ProcessLocalBoundedCache[int, tuple[object, Any]]): 

138 """Process-local values bound to an owner object, protected against ``id`` reuse.""" 

139 

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 

150 

151 def put_bound(self, owner: object, value: Any) -> Any: 

152 return self.store_value(id(owner), (owner, value))[1]