xtr-cache 1.2.0__py3-none-any.whl

xtr_cache/adapter/array_adapter.py

@@ -0,0 +1,165 @@
+"""A pool in this process's memory."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast, final
+
+from typing_extensions import override
+
+from xtr_cache.exception import InvalidArgumentError, MarshallingError
+from xtr_cache.marshaller.default_marshaller import DefaultMarshaller
+
+from .abstract_adapter import AbstractAdapter
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
+    from xtr_clock import ClockInterface
+
+    from xtr_cache.marshaller.marshaller_interface import MarshallerInterface
+
+__all__ = ["ArrayAdapter"]
+
+
+@final
+class ArrayAdapter(AbstractAdapter):
+    """Keeps values in a dictionary, for tests and for caching within one process.
+
+    Values are stored serialized by default, so what a caller gets back is a
+    copy: changing it does not change what is cached, exactly as with any
+    other backend. Turn that off to store the objects themselves, faster but
+    shared.
+
+    Every method completes without awaiting, so tasks on one event loop never
+    see it half-updated. Two instances share nothing.
+    """
+
+    _values: dict[str, tuple[object, float | None]]
+    _store_serialized: bool
+    _max_lifetime: float
+    _max_items: int
+    _marshaller: MarshallerInterface
+
+    def __init__(  # noqa: PLR0913 — every option past the lifetime is keyword-only.
+        self,
+        default_lifetime: float = 0.0,
+        *,
+        store_serialized: bool = True,
+        max_lifetime: float = 0.0,
+        max_items: int = 0,
+        marshaller: MarshallerInterface | None = None,
+        clock: ClockInterface | None = None,
+    ) -> None:
+        """Keep values in memory.
+
+        Args:
+            default_lifetime: Seconds a value lives when its item sets no
+                expiry; ``0`` for no limit.
+            store_serialized: Store a serialized copy rather than the object.
+            max_lifetime: Seconds no value outlives, whatever its item says;
+                ``0`` for no cap.
+            max_items: How many values to keep, dropping the least recently
+                used beyond; ``0`` for no limit.
+            marshaller: What serializes values when ``store_serialized``.
+                Pickle when omitted.
+            clock: What lifetimes are counted from. ``None`` reads the clock
+                in force.
+
+        Raises:
+            InvalidArgumentError: When ``max_lifetime`` or ``max_items`` is negative.
+        """
+        if max_lifetime < 0:
+            raise InvalidArgumentError(f"max_lifetime must not be negative, got {max_lifetime}.")
+        if max_items < 0:
+            raise InvalidArgumentError(f"max_items must not be negative, got {max_items}.")
+
+        super().__init__("", default_lifetime, clock=clock)
+        self._values = {}
+        self._store_serialized = store_serialized
+        self._max_lifetime = max_lifetime
+        self._max_items = max_items
+        self._marshaller = marshaller if marshaller is not None else DefaultMarshaller()
+
+    def values(self) -> dict[str, object]:
+        """Return every live value by identifier, as stored; for tests."""
+        now = self._clock.now().timestamp()
+        return {
+            id_: stored
+            for id_, (stored, expiry) in self._values.items()
+            if expiry is None or expiry > now
+        }
+
+    @override
+    async def _do_fetch(self, ids: Sequence[str]) -> Mapping[str, object]:
+        now = self._clock.now().timestamp()
+        found: dict[str, object] = {}
+        for id_ in ids:
+            entry = self._values.get(id_)
+            if entry is None:
+                continue
+            stored, expiry = entry
+            if expiry is not None and expiry <= now:
+                del self._values[id_]
+                continue
+            if self._max_items:
+                # Most recently used last, so eviction takes from the front.
+                self._values[id_] = self._values.pop(id_)
+            if not self._store_serialized:
+                found[id_] = stored
+                continue
+            try:
+                # Stored serialized, so what is stored is the marshaller's bytes.
+                found[id_] = self._marshaller.unmarshall(cast("bytes", stored))
+            except MarshallingError as error:
+                del self._values[id_]
+                self._log('Failed to read key "{key}": {reason}', error, key=id_)
+
+        return found
+
+    @override
+    async def _do_have(self, id_: str) -> bool:
+        entry = self._values.get(id_)
+        if entry is None:
+            return False
+        expiry = entry[1]
+        return expiry is None or expiry > self._clock.now().timestamp()
+
+    @override
+    async def _do_clear(self, namespace: str) -> bool:
+        if not namespace:
+            self._values.clear()
+        else:
+            for id_ in [id_ for id_ in self._values if id_.startswith(namespace)]:
+                del self._values[id_]
+        return True
+
+    @override
+    async def _do_delete(self, ids: Sequence[str]) -> bool:
+        for id_ in ids:
+            _ = self._values.pop(id_, None)
+        return True
+
+    @override
+    async def _do_save(self, values: Mapping[str, object], lifetime: float) -> bool | Sequence[str]:
+        if self._max_lifetime and (not lifetime or lifetime > self._max_lifetime):
+            lifetime = self._max_lifetime
+        expiry = self._clock.now().timestamp() + lifetime if lifetime else None
+
+        failed: list[str] = []
+        stored: Mapping[str, object] = values
+        if self._store_serialized:
+            stored, failed = self._marshaller.marshall(values)
+
+        for id_, value in stored.items():
+            _ = self._values.pop(id_, None)
+            self._values[id_] = (value, expiry)
+
+        if self._max_items:
+            while len(self._values) > self._max_items:
+                del self._values[next(iter(self._values))]
+
+        return failed or True
+
+    @override
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self._default_lifetime!r})"

xtr_cache/adapter/chain_adapter.py

@@ -0,0 +1,185 @@
+"""Several pools in front of one another, the fastest first."""
+
+from __future__ import annotations
+
+import copy
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Self, final
+
+from typing_extensions import override
+from xtr_cache_contracts import InvalidArgumentError, NamespacedPoolInterface
+
+from xtr_cache.cache_item import CacheItem
+from xtr_cache.pruneable_interface import PruneableInterface
+
+from .adapter_interface import AdapterInterface
+from .contracts_mixin import ContractsMixin
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Mapping, Sequence
+
+    from xtr_cache_contracts import ItemInterface
+    from xtr_clock import ClockInterface
+
+__all__ = ["ChainAdapter"]
+
+
+@final
+class ChainAdapter(ContractsMixin, AdapterInterface, NamespacedPoolInterface, PruneableInterface):
+    """Reads from the first pool that has a value, and fills the faster ones with it.
+
+    Typically memory in front of Redis: a hit in memory costs nothing, a miss
+    there asks Redis, and a value found in Redis is copied into memory for
+    the next read — with what is left of its lifetime, when it was stored
+    with one, or ``default_lifetime`` otherwise. Writes, deletes and clears
+    go to every pool.
+    """
+
+    _adapters: tuple[AdapterInterface, ...]
+    _default_lifetime: float
+
+    def __init__(
+        self,
+        adapters: Sequence[AdapterInterface],
+        default_lifetime: float = 0.0,
+        *,
+        clock: ClockInterface | None = None,
+    ) -> None:
+        """Chain ``adapters``, the fastest first.
+
+        Args:
+            adapters: The pools, in the order they are read.
+            default_lifetime: Seconds a value copied into a faster pool lives,
+                when it was stored without an expiry; ``0`` leaves it to that
+                pool's own default.
+            clock: What lifetimes are counted from. ``None`` reads the clock
+                in force.
+
+        Raises:
+            InvalidArgumentError: When ``adapters`` is empty.
+        """
+        if not adapters:
+            raise InvalidArgumentError("A chain needs at least one cache pool.")
+
+        self._adapters = tuple(adapters)
+        self._default_lifetime = default_lifetime
+        if clock is not None:
+            self._clock = clock
+
+    @property
+    def adapters(self) -> tuple[AdapterInterface, ...]:
+        """The pools, in the order they are read."""
+        return self._adapters
+
+    @override
+    async def get_item(self, key: str, /) -> CacheItem:
+        missed: list[AdapterInterface] = []
+        for adapter in self._adapters:
+            item = await adapter.get_item(key)
+            if item.is_hit():
+                for faster in missed:
+                    _ = await faster.save(self._copy(item))
+                return item
+            missed.append(adapter)
+
+        return CacheItem(key, clock=self._clock)
+
+    @override
+    async def get_items(self, keys: Iterable[str], /) -> Mapping[str, CacheItem]:
+        wanted = list(dict.fromkeys(keys))
+        found: dict[str, CacheItem] = {}
+        missing = wanted
+        missed: list[AdapterInterface] = []
+        for adapter in self._adapters:
+            if not missing:
+                break
+            items = await adapter.get_items(missing)
+            for key, item in items.items():
+                if item.is_hit():
+                    found[key] = item
+                    for faster in missed:
+                        _ = await faster.save_deferred(self._copy(item))
+            missing = [key for key in missing if key not in found]
+            missed.append(adapter)
+
+        for faster in missed:
+            _ = await faster.commit()
+
+        return {key: found.get(key) or CacheItem(key, clock=self._clock) for key in wanted}
+
+    @override
+    async def has_item(self, key: str, /) -> bool:
+        for adapter in self._adapters:
+            if await adapter.has_item(key):
+                return True
+        return False
+
+    @override
+    async def clear(self, prefix: str = "") -> bool:
+        return all([await adapter.clear(prefix) for adapter in self._adapters])
+
+    @override
+    async def delete_item(self, key: str, /) -> bool:
+        return all([await adapter.delete_item(key) for adapter in self._adapters])
+
+    @override
+    async def delete_items(self, keys: Iterable[str], /) -> bool:
+        wanted = list(keys)
+        return all([await adapter.delete_items(wanted) for adapter in self._adapters])
+
+    @override
+    async def save(self, item: ItemInterface, /) -> bool:
+        return all([await adapter.save(item) for adapter in self._adapters])
+
+    @override
+    async def save_deferred(self, item: ItemInterface, /) -> bool:
+        return all([await adapter.save_deferred(item) for adapter in self._adapters])
+
+    @override
+    async def commit(self) -> bool:
+        return all([await adapter.commit() for adapter in self._adapters])
+
+    @override
+    async def prune(self) -> bool:
+        return all(
+            [
+                await adapter.prune()
+                for adapter in self._adapters
+                if isinstance(adapter, PruneableInterface)
+            ],
+        )
+
+    @override
+    async def reset(self) -> None:
+        for adapter in self._adapters:
+            await adapter.reset()
+
+    @override
+    def with_sub_namespace(self, namespace: str, /) -> Self:
+        clone = copy.copy(self)
+        clone._adapters = tuple(  # noqa: SLF001 — a copy of this very class.
+            adapter.with_sub_namespace(namespace)
+            if isinstance(adapter, NamespacedPoolInterface)
+            else adapter
+            for adapter in self._adapters
+        )
+        return clone
+
+    @override
+    def _scope(self) -> str:
+        first = self._adapters[0]
+        return first._scope() if isinstance(first, ContractsMixin) else ""  # noqa: SLF001 — a pool of this library.
+
+    @override
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({list(self._adapters)!r}, {self._default_lifetime!r})"
+
+    def _copy(self, item: CacheItem) -> CacheItem:
+        """Return an item taking ``item``'s value into a faster pool, with the life it has left."""
+        carried = CacheItem(item.key, item.get(), clock=self._clock).carry_metadata(item.metadata)
+        expiry = item.metadata.get("expiry")
+        if expiry is not None:
+            return carried.expires_at(datetime.fromtimestamp(expiry, UTC))
+        if self._default_lifetime:
+            return carried.expires_after(self._default_lifetime)
+        return carried

xtr_cache/adapter/contracts_mixin.py

@@ -0,0 +1,190 @@
+"""Fetch-or-compute on a pool of :class:`CacheItem`: one computation per key, timed."""
+
+from __future__ import annotations
+
+import asyncio
+import math
+from abc import ABC, abstractmethod
+from contextvars import ContextVar
+from typing import TYPE_CHECKING, Final, TypeVar, cast
+
+from typing_extensions import override
+from xtr_cache_contracts import CacheMixin
+from xtr_clock import Clock
+from xtr_logging_contracts import LoggerAware
+
+if TYPE_CHECKING:
+    from xtr_cache_contracts import Callback, ItemInterface, Metadata
+    from xtr_clock import ClockInterface
+
+    from xtr_cache.cache_item import CacheItem
+    from xtr_cache.lock_registry import LockRegistry
+
+__all__ = ["ContractsMixin"]
+
+_T = TypeVar("_T")
+
+_CLOCK_IN_FORCE: Final = Clock()
+
+_COMPUTING: ContextVar[frozenset[tuple[int, str]]] = ContextVar(
+    "xtr_cache_computing",
+    default=frozenset(),
+)
+"""The computations the running task is inside of: its flight registry, and the scoped key."""
+
+_FAILED: Final = object()
+"""What a shared computation resolves to when its owner failed or was cancelled."""
+
+
+class ContractsMixin(CacheMixin, LoggerAware, ABC):
+    """Fetch-or-compute on a pool of :class:`~xtr_cache.cache_item.CacheItem`.
+
+    Built on :class:`~xtr_cache_contracts.CacheMixin`'s template, adjusting how
+    a missing value is computed:
+
+    - It is saved with how long it took, which — with its expiry — is what
+      makes early recomputation possible on a later read.
+    - Concurrent misses on one key in this process share one computation. If
+      it fails or is cancelled, each of the others computes for itself.
+    - With a :class:`~xtr_cache.lock_registry.LockRegistry`, misses in every
+      process sharing its locks share one computation too.
+    - A callback reading its own key — directly or through what it calls —
+      computes without saving, instead of waiting on itself.
+
+    Computations are keyed by :meth:`_scope` and the key, so pools on one
+    backend under different namespaces never wait on each other.
+    """
+
+    _lock_registry: LockRegistry | None = None
+    _clock: ClockInterface = _CLOCK_IN_FORCE
+    _in_flight: dict[str, asyncio.Future[object]]
+
+    @abstractmethod
+    @override
+    async def get_item(self, key: str, /) -> CacheItem:
+        """Return the item for ``key``, a hit or a miss."""
+
+    def set_lock_registry(self, registry: LockRegistry | None) -> None:
+        """Compute missing values under ``registry``'s locks; ``None`` for this process alone."""
+        self._lock_registry = registry
+
+    @abstractmethod
+    def _scope(self) -> str:
+        """Return what sets this pool's keys apart from another's on the same backend."""
+
+    @override
+    def _now(self) -> float:
+        return self._clock.now().timestamp()
+
+    @override
+    def _on_elected(self, item: ItemInterface, remaining: float) -> None:
+        self.logger.info(
+            'Item "{key}" elected for early recomputation {delta}s before its expiration',
+            {"key": item.key, "delta": f"{remaining:.1f}"},
+        )
+
+    @override
+    async def _compute(
+        self,
+        item: ItemInterface,
+        callback: Callback[_T],
+        beta: float,
+        metadata: Metadata | None,
+    ) -> _T:
+        """Compute the value once for every concurrent caller, under the lock registry if any."""
+        # The template hands back what get_item returned, which here is always a CacheItem.
+        item = cast("CacheItem", item)
+        flights = self._flights()
+        scoped = self._scope() + item.key
+        if (id(flights), scoped) in _COMPUTING.get():
+            value = await callback(item)
+            _ = item.set(value)
+            return value
+
+        shared = flights.get(scoped)
+        if shared is not None:
+            result = await asyncio.shield(shared)
+            if result is not _FAILED:
+                # Computed by the same kind of callback for the same key: the caller's promise.
+                return cast("_T", result)
+            # Queueing behind another attempt would make every caller wait for every failure.
+            return await self._compute_and_save(item, callback, metadata, scoped)
+
+        future: asyncio.Future[object] = asyncio.get_running_loop().create_future()
+        flights[scoped] = future
+        try:
+            value = await self._compute_locked(item, callback, beta, metadata, scoped)
+        except BaseException:
+            future.set_result(_FAILED)
+            raise
+        else:
+            future.set_result(value)
+            return value
+        finally:
+            if flights.get(scoped) is future:
+                del flights[scoped]
+
+    async def _compute_locked(
+        self,
+        item: CacheItem,
+        callback: Callback[_T],
+        beta: float,
+        metadata: Metadata | None,
+        scoped: str,
+    ) -> _T:
+        """Compute under the lock registry's slot for ``scoped``, when there is a registry."""
+        if self._lock_registry is None:
+            return await self._compute_and_save(item, callback, metadata, scoped)
+
+        async def compute() -> _T:
+            return await self._compute_and_save(item, callback, metadata, scoped)
+
+        async def read() -> ItemInterface:
+            return await self.get_item(item.key)
+
+        return await self._lock_registry.compute(scoped, compute, read, force=math.isinf(beta))
+
+    async def _compute_and_save(
+        self,
+        item: CacheItem,
+        callback: Callback[_T],
+        metadata: Metadata | None,
+        scoped: str,
+    ) -> _T:
+        """Run ``callback``, record how long it took, save the value, and report it."""
+        token = _COMPUTING.set(_COMPUTING.get() | {(id(self._flights()), scoped)})
+        started = self._now()
+        try:
+            value = await callback(item)
+        finally:
+            _COMPUTING.reset(token)
+
+        ctime = math.ceil(1000 * (self._now() - started))
+        _ = item.set(value).record_computation(ctime)
+        if metadata is not None:
+            _report(metadata, item, ctime)
+        if not await self.save(item) and metadata is not None:
+            metadata["save_failed"] = True
+
+        return value
+
+    def _flights(self) -> dict[str, asyncio.Future[object]]:
+        """Return the computations in progress, by scoped key; views of this pool share them."""
+        try:
+            return self._in_flight
+        except AttributeError:
+            self._in_flight = {}
+            return self._in_flight
+
+
+def _report(metadata: Metadata, item: CacheItem, ctime: int) -> None:
+    """Tell the caller what the computed value is stored with, dropping what no longer holds."""
+    metadata["ctime"] = ctime
+    if item.expiry is not None:
+        metadata["expiry"] = item.expiry
+    else:
+        _ = metadata.pop("expiry", None)
+    if item.pending_tags:
+        metadata["tags"] = item.pending_tags
+    else:
+        _ = metadata.pop("tags", None)

xtr_cache/adapter/deferred_items_mixin.py

@@ -0,0 +1,78 @@
+"""The queue of items saved as deferred, for a pool that commits them in one batch."""
+
+from __future__ import annotations
+
+import copy
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Self
+
+from typing_extensions import override
+from xtr_cache_contracts import CacheItemPoolInterface
+
+from xtr_cache.cache_item import CacheItem
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from xtr_cache_contracts import ItemInterface
+
+__all__ = ["DeferredItemsMixin"]
+
+
+class DeferredItemsMixin(CacheItemPoolInterface, ABC):
+    """Queues saved items until :meth:`commit`, which the pool implements.
+
+    :meth:`save` is a deferred save committed at once, so a pool writes in one
+    place only. What is queued is the pool's to drop when the keys are
+    deleted or cleared, and to commit before a queued key is read.
+    """
+
+    _deferred: dict[str, CacheItem]
+
+    @abstractmethod
+    @override
+    async def commit(self) -> bool:
+        """Store every queued item."""
+
+    @override
+    async def save(self, item: ItemInterface, /) -> bool:
+        if not isinstance(item, CacheItem):
+            return False
+
+        self._deferred[item.key] = item
+        return await self.commit()
+
+    @override
+    async def save_deferred(self, item: ItemInterface, /) -> bool:
+        if not isinstance(item, CacheItem):
+            return False
+
+        self._deferred[item.key] = item
+        return True
+
+    async def reset(self) -> None:
+        """Commit what was queued, so it does not wait for a commit nothing will call."""
+        if self._deferred:
+            _ = await self.commit()
+
+    async def _commit_if_queued(self, keys: Iterable[str]) -> None:
+        """Commit first when any of ``keys`` is queued, so a read never misses what was saved."""
+        if any(key in self._deferred for key in keys):
+            _ = await self.commit()
+
+    def _forget_deferred(self, keys: Iterable[str]) -> None:
+        """Drop the queued items of ``keys``, which are being deleted."""
+        for key in keys:
+            _ = self._deferred.pop(key, None)
+
+    def _drop_deferred(self, prefix: str) -> None:
+        """Drop the queued items whose key starts with ``prefix``, which are being cleared."""
+        self._deferred = {
+            key: item for key, item in self._deferred.items() if not key.startswith(prefix)
+        }
+
+    def _unqueued_copy(self) -> Self:
+        """Return a shallow copy of this pool with nothing queued, for a sub-namespace view."""
+        clone = copy.copy(self)
+        clone._deferred = {}  # noqa: SLF001 — a copy of this very class.
+        return clone