GeneralManager 0.45.0__tar.gz → 0.46.1__tar.gz

{generalmanager-0.45.0/src/GeneralManager.egg-info → generalmanager-0.46.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.45.0
+Version: 0.46.1
 Summary: Modular Django-based data management framework with ORM, GraphQL, fine-grained permissions, rule validation, calculations and caching.
 Author-email: Tim Kleindick <tkleindick@yahoo.de>
 License: MIT License

{generalmanager-0.45.0 → generalmanager-0.46.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "GeneralManager"
-version = "0.45.0"
+version = "0.46.1"
 description = "Modular Django-based data management framework with ORM, GraphQL, fine-grained permissions, rule validation, calculations and caching."
 readme = "README.md"
 authors = [{ name = "Tim Kleindick", email = "tkleindick@yahoo.de" }]

{generalmanager-0.45.0 → generalmanager-0.46.1/src/GeneralManager.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.45.0
+Version: 0.46.1
 Summary: Modular Django-based data management framework with ORM, GraphQL, fine-grained permissions, rule validation, calculations and caching.
 Author-email: Tim Kleindick <tkleindick@yahoo.de>
 License: MIT License

{generalmanager-0.45.0 → generalmanager-0.46.1}/src/GeneralManager.egg-info/SOURCES.txt

@@ -51,7 +51,9 @@ src/general_manager/bucket/request_bucket.py
 src/general_manager/cache/__init__.py
 src/general_manager/cache/cache_decorator.py
 src/general_manager/cache/cache_tracker.py
+src/general_manager/cache/dependency_cache.py
 src/general_manager/cache/dependency_index.py
+src/general_manager/cache/dependency_publish.py
 src/general_manager/cache/model_dependency_collector.py
 src/general_manager/cache/run_context.py
 src/general_manager/cache/signals.py

{generalmanager-0.45.0 → generalmanager-0.46.1}/src/general_manager/cache/cache_decorator.py

@@ -1,12 +1,38 @@
 """Helpers for caching GeneralManager computations with dependency tracking."""
 
 from functools import wraps
-from typing import Any, Callable, Literal, Optional, Protocol, Set, TypeVar, cast
+from typing import (
+    Any,
+    Callable,
+    Iterable,
+    Literal,
+    Optional,
+    Protocol,
+    Set,
+    TypeVar,
+    cast,
+)
 
 from django.core.cache import cache as django_cache
 
 from general_manager.cache.cache_tracker import DependencyTracker
-from general_manager.cache.dependency_index import Dependency, record_dependencies
+from general_manager.cache.dependency_cache import (
+    DependencyCacheHit,
+    read_dependency_cache_hit,
+    replay_dependency_cache_hit,
+)
+from general_manager.cache.dependency_index import (
+    Dependency,
+    get_dependency_generation,
+    record_dependencies,
+)
+from general_manager.cache.dependency_publish import (
+    CachePublishAborted,
+    acquire_compute_lease,
+    publish_dependency_cache_entry,
+    release_compute_lease,
+    wait_for_cached_dependency_hit,
+)
 from general_manager.cache.run_context import ensure_calculation_run_context
 from general_manager.cache.model_dependency_collector import ModelDependencyCollector
 from general_manager.logging import get_logger
@@ -158,34 +184,83 @@ def cached(
                 )
                 return result
 
-            deps_key = f"{key}:deps"
-
-            cached_result = cache_backend.get(key, _SENTINEL)
-            if cached_result is not _SENTINEL:
-                # saved dependencies are added to the current tracker
-                cached_deps = cache_backend.get(deps_key)
-                if cached_deps:
-                    for class_name, operation, identifier in cached_deps:
-                        DependencyTracker.track(class_name, operation, identifier)
+            def return_cached_hit(hit: DependencyCacheHit, message: str) -> object:
+                replay_dependency_cache_hit(hit)
                 logger.debug(
-                    "cache hit",
+                    message,
                     context={
                         "function": func.__qualname__,
                         "key": key,
-                        "dependency_count": len(cached_deps) if cached_deps else 0,
+                        "scope": scope,
                     },
                 )
-                return cached_result
+                return hit.value
 
-            with DependencyTracker() as dependencies:
-                result = func(*args, **kwargs)
-                ModelDependencyCollector.add_args(dependencies, args, kwargs)
-
-                cache_backend.set(key, result, timeout)
-                cache_backend.set(deps_key, dependencies, timeout)
+            cached_hit = read_dependency_cache_hit(
+                cache_backend,
+                key,
+                sentinel=_SENTINEL,
+            )
+            if cached_hit is not _SENTINEL:
+                return return_cached_hit(cached_hit, "cache hit")
+
+            lease = acquire_compute_lease(key)
+            while lease is None:
+                cached_hit = wait_for_cached_dependency_hit(
+                    cache_backend,
+                    key,
+                    sentinel=_SENTINEL,
+                )
+                if cached_hit is not _SENTINEL:
+                    return return_cached_hit(
+                        cached_hit,
+                        "cache hit after waiting for dependency publish",
+                    )
+                lease = acquire_compute_lease(key)
 
-                if dependencies and timeout is None:
-                    record_fn(key, dependencies)
+            try:
+                cached_hit = read_dependency_cache_hit(
+                    cache_backend,
+                    key,
+                    sentinel=_SENTINEL,
+                )
+                if cached_hit is not _SENTINEL:
+                    return return_cached_hit(cached_hit, "cache hit")
+
+                started_generation = get_dependency_generation()
+                with DependencyTracker() as dependencies:
+                    result = func(*args, **kwargs)
+                    ModelDependencyCollector.add_args(dependencies, args, kwargs)
+
+                def record_many(
+                    entries: Iterable[tuple[str, Iterable[Dependency]]],
+                ) -> None:
+                    for entry_key, entry_dependencies in entries:
+                        record_fn(entry_key, set(entry_dependencies))
+
+                try:
+                    publish_dependency_cache_entry(
+                        cache_key=key,
+                        result=result,
+                        dependencies=dependencies,
+                        cache_backend=cache_backend,
+                        timeout=timeout,
+                        started_generation=started_generation,
+                        record_many_fn=(
+                            None if record_fn is record_dependencies else record_many
+                        ),
+                    )
+                except CachePublishAborted:
+                    logger.debug(
+                        "dependency cache publish aborted",
+                        context={
+                            "function": func.__qualname__,
+                            "key": key,
+                            "scope": scope,
+                        },
+                    )
+            finally:
+                release_compute_lease(lease)
 
             logger.debug(
                 "cache miss recorded",

generalmanager-0.46.1/src/general_manager/cache/dependency_cache.py

@@ -0,0 +1,154 @@
+"""Internal helpers for dependency-scoped cache entry reads."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Iterable, Mapping, Protocol, TypeGuard
+
+from general_manager.cache.cache_tracker import DependencyTracker
+from general_manager.cache.dependency_index import Dependency
+
+DEPENDENCY_CACHE_ENTRY_VERSION = 1
+_MISSING = object()
+
+
+@dataclass(frozen=True, slots=True)
+class DependencyCacheEntry:
+    """Persisted dependency-cache payload stored at the main cache key."""
+
+    version: int
+    value: Any
+    dependencies: frozenset[Dependency]
+
+
+@dataclass(frozen=True, slots=True)
+class DependencyCacheHit:
+    """In-memory representation of a dependency-cache hit."""
+
+    value: Any
+    dependencies: frozenset[Dependency]
+
+
+class DependencyCacheBackend(Protocol):
+    def get(self, key: str, default: Any = None) -> Any:
+        """Return a cached value or *default* when absent."""
+        ...
+
+    def set(self, key: str, value: Any, timeout: int | None = None) -> None:
+        """Store a cached value."""
+        ...
+
+
+class DependencyCacheGetManyBackend(DependencyCacheBackend, Protocol):
+    def get_many(self, keys: Iterable[str]) -> Mapping[str, Any]:
+        """Return cached values for all found keys."""
+        ...
+
+
+def make_dependency_cache_entry(
+    value: Any,
+    dependencies: Iterable[Dependency],
+) -> DependencyCacheEntry:
+    """Build the current persisted dependency-cache payload."""
+    return DependencyCacheEntry(
+        version=DEPENDENCY_CACHE_ENTRY_VERSION,
+        value=value,
+        dependencies=frozenset(dependencies),
+    )
+
+
+def read_dependency_cache_hit(
+    cache_backend: DependencyCacheBackend,
+    cache_key: str,
+    *,
+    sentinel: Any = _MISSING,
+) -> DependencyCacheHit | Any:
+    """Read one dependency-cache entry, including legacy split entries."""
+    payload = cache_backend.get(cache_key, sentinel)
+    if payload is sentinel:
+        return sentinel
+    combined_hit = _combined_payload_to_hit(payload)
+    if combined_hit is _MISSING:
+        return sentinel
+    if combined_hit is not None:
+        return combined_hit
+    dependency_payload = cache_backend.get(_legacy_deps_key(cache_key), ())
+    return DependencyCacheHit(
+        value=payload,
+        dependencies=frozenset(dependency_payload or ()),
+    )
+
+
+def read_many_dependency_cache_hits(
+    cache_backend: DependencyCacheBackend,
+    cache_keys: Iterable[str],
+) -> dict[str, DependencyCacheHit]:
+    """Bulk-read dependency-cache hits for known keys."""
+    keys = tuple(dict.fromkeys(cache_keys))
+    if not keys:
+        return {}
+    if not _supports_get_many(cache_backend):
+        return _read_many_without_get_many(cache_backend, keys)
+
+    payloads = cache_backend.get_many(keys)
+    hits: dict[str, DependencyCacheHit] = {}
+    legacy_keys: list[str] = []
+    for key in keys:
+        if key not in payloads:
+            continue
+        combined_hit = _combined_payload_to_hit(payloads[key])
+        if combined_hit is _MISSING:
+            continue
+        if isinstance(combined_hit, DependencyCacheHit):
+            hits[key] = combined_hit
+            continue
+        legacy_keys.append(key)
+
+    if legacy_keys:
+        deps_keys = {_legacy_deps_key(key): key for key in legacy_keys}
+        legacy_deps = cache_backend.get_many(deps_keys.keys())
+        for deps_key, key in deps_keys.items():
+            hits[key] = DependencyCacheHit(
+                value=payloads[key],
+                dependencies=frozenset(legacy_deps.get(deps_key, ()) or ()),
+            )
+    return hits
+
+
+def replay_dependency_cache_hit(hit: DependencyCacheHit) -> None:
+    """Replay cached dependencies into active dependency tracking scopes."""
+    for class_name, operation, identifier in hit.dependencies:
+        DependencyTracker.track(class_name, operation, identifier)
+
+
+def _legacy_deps_key(cache_key: str) -> str:
+    return f"{cache_key}:deps"
+
+
+def _combined_payload_to_hit(payload: Any) -> DependencyCacheHit | None | object:
+    if not isinstance(payload, DependencyCacheEntry):
+        return None
+    if payload.version != DEPENDENCY_CACHE_ENTRY_VERSION:
+        return _MISSING
+    return DependencyCacheHit(
+        value=payload.value,
+        dependencies=payload.dependencies,
+    )
+
+
+def _supports_get_many(
+    cache_backend: DependencyCacheBackend,
+) -> TypeGuard[DependencyCacheGetManyBackend]:
+    return callable(getattr(cache_backend, "get_many", None))
+
+
+def _read_many_without_get_many(
+    cache_backend: DependencyCacheBackend,
+    cache_keys: tuple[str, ...],
+) -> dict[str, DependencyCacheHit]:
+    hits: dict[str, DependencyCacheHit] = {}
+    for key in cache_keys:
+        hit = read_dependency_cache_hit(cache_backend, key, sentinel=_MISSING)
+        if hit is not _MISSING:
+            hits[key] = hit
+    return hits