kvgit 0.4.1__tar.gz → 0.4.2__tar.gz

{kvgit-0.4.1 → kvgit-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kvgit
-Version: 0.4.1
+Version: 0.4.2
 Summary: Versioned key-value store with git-like commit, branch, and merge semantics.
 Author: ashenfad
 License: MIT

{kvgit-0.4.1 → kvgit-0.4.2}/kvgit/_open.py

@@ -3,6 +3,7 @@
 from typing import Literal
 
 from ._codec import CodecSpec
+from .cache import DEFAULT_CACHE_BYTES
 from .kv.base import KVStore
 from .kv.memory import Memory
 from .repo import Repo
@@ -39,6 +40,7 @@ def open(
     db_name: str = "kvgit",
     branch: str = "main",
     codec: CodecSpec = "pickle",
+    cache_bytes: int = DEFAULT_CACHE_BYTES,
 ) -> Worktree:
     """Open (or create) a store, and a worktree on ``branch`` of it.
 
@@ -57,6 +59,10 @@ def open(
         db_name: The IndexedDB database name, for ``kind="indexeddb"``.
         branch: The branch to check out (default ``"main"``).
         codec: How values are stored; see :class:`Repo`.
+        cache_bytes: Memory for what the store never changes; see
+            :class:`Repo`.
     """
     backend = _make_backend(kind, path=path, db_name=db_name)
-    return Repo(backend, codec=codec).worktree(branch, create=True)
+    return Repo(backend, codec=codec, cache_bytes=cache_bytes).worktree(
+        branch, create=True
+    )

kvgit-0.4.2/kvgit/cache.py

@@ -0,0 +1,283 @@
+"""A repository's memory of what its store can never change.
+
+Tree nodes and a commit's records — its parents, their generations,
+its time and its info — are written once, under keys named by content
+or by commit, and never rewritten. A read of one can be answered from
+memory for as long as the store still holds it, which saves the round
+trip to a networked backend that most reads of them are.
+
+What the cache must not outlive is a deletion. Only a sweep deletes
+these keys, and every sweep rewrites the GC lease record, which each
+commit reads before it builds. So the cache remembers the record it
+last saw and empties itself when a read of the lease finds another:
+the sweep of any process on any host is noticed before this process
+builds on what it may have removed. A sweep run through this process's
+own store evicts what it removes as it removes it.
+
+A commit's root is never cached. It is the store's answer to whether a
+commit exists — what ``snapshot(commit=)`` and a tag's ``dangling``
+ask — so it is always read, and whatever is reached through a root the
+store still holds is safe to answer from here. Absence is never cached
+either: a key missing now may be written by the next commit.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections import OrderedDict
+from collections.abc import Iterable, Mapping
+from typing import Any
+
+from .kv.base import KVStore
+from .versioned.keyset import Keyset
+from .versioned.kv import (
+    COMMIT_TIME,
+    GC_LEASE_KEY,
+    INFO_KEY,
+    PARENT_COMMIT,
+    PARENT_GENS,
+)
+
+DEFAULT_CACHE_BYTES = 32 * 1024 * 1024
+"""The default budget: tens of thousands of tree nodes."""
+
+_CACHEABLE_PREFIXES = (
+    Keyset.DEFAULT_PREFIX,
+    PARENT_COMMIT.replace("%s", ""),
+    PARENT_GENS.replace("%s", ""),
+    COMMIT_TIME.replace("%s", ""),
+    INFO_KEY.replace("%s", ""),
+)
+
+# What an entry costs beyond its bytes: the key, the dict slot, the
+# object headers. An estimate, so the budget bounds memory rather than
+# just payload.
+_ENTRY_OVERHEAD = 96
+
+_UNSEEN: Any = object()
+
+
+def cacheable(key: str) -> bool:
+    """Whether ``key`` is one the store never rewrites."""
+    return key.startswith(_CACHEABLE_PREFIXES)
+
+
+class ContentCache:
+    """Least-recently-used memory of write-once keys, bounded in bytes.
+
+    Shared by every worktree and snapshot of one :class:`~kvgit.Repo`,
+    and safe to use from several threads.
+    """
+
+    def __init__(self, max_bytes: int = DEFAULT_CACHE_BYTES) -> None:
+        if max_bytes <= 0:
+            raise ValueError(f"max_bytes must be positive, got {max_bytes}")
+        self.max_bytes = max_bytes
+        self._entries: OrderedDict[str, bytes] = OrderedDict()
+        self._bytes = 0
+        self._lock = threading.Lock()
+        self._lease: Any = _UNSEEN
+        self.hits = 0
+        """Reads answered from memory."""
+        self.misses = 0
+        """Reads of cacheable keys that went to the store."""
+        self.clears = 0
+        """How often a sweep emptied the cache."""
+
+    def __repr__(self) -> str:
+        return (
+            f"ContentCache({len(self._entries)} entries, "
+            f"{self._bytes}/{self.max_bytes} bytes)"
+        )
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+    @property
+    def size_bytes(self) -> int:
+        """What the entries held now cost, by the budget's estimate."""
+        return self._bytes
+
+    def clear(self) -> None:
+        with self._lock:
+            self._clear()
+
+    def _clear(self) -> None:
+        self._entries.clear()
+        self._bytes = 0
+
+    def lookup(self, keys: Iterable[str]) -> dict[str, bytes]:
+        """The cached values of those ``keys`` held here."""
+        found: dict[str, bytes] = {}
+        with self._lock:
+            for key in keys:
+                value = self._entries.get(key)
+                if value is not None:
+                    self._entries.move_to_end(key)
+                    found[key] = value
+        return found
+
+    def count(self, hits: int, misses: int) -> None:
+        with self._lock:
+            self.hits += hits
+            self.misses += misses
+
+    def remember(self, items: Mapping[str, bytes]) -> None:
+        """Hold these values, evicting the least recently used to fit."""
+        with self._lock:
+            for key, value in items.items():
+                if not isinstance(value, bytes | bytearray | memoryview):
+                    continue
+                cost = len(value) + len(key) + _ENTRY_OVERHEAD
+                if cost > self.max_bytes:
+                    continue
+                old = self._entries.pop(key, None)
+                if old is not None:
+                    self._bytes -= len(old) + len(key) + _ENTRY_OVERHEAD
+                self._entries[key] = bytes(value)
+                self._bytes += cost
+            while self._bytes > self.max_bytes and self._entries:
+                key, value = self._entries.popitem(last=False)
+                self._bytes -= len(value) + len(key) + _ENTRY_OVERHEAD
+
+    def forget(self, keys: Iterable[str]) -> None:
+        with self._lock:
+            for key in keys:
+                value = self._entries.pop(key, None)
+                if value is not None:
+                    self._bytes -= len(value) + len(key) + _ENTRY_OVERHEAD
+
+    def saw_lease(self, record: bytes | None) -> None:
+        """Note the GC lease record a read found; a different one than
+        last time means a sweep has run, and what it removed may be
+        held here."""
+        with self._lock:
+            if self._lease is not _UNSEEN and record != self._lease:
+                self._clear()
+                self.clears += 1
+            self._lease = record
+
+
+class CachedStore(KVStore):
+    """A backend seen through a :class:`ContentCache`.
+
+    Reads of write-once keys are answered from the cache where it can
+    and remembered where it cannot; everything else passes through
+    untouched. Successful writes of write-once keys are remembered too,
+    so a commit's next read of its own tree is a hit, and removals
+    evict. Anything else the backend offers (``close``, ``drop``, ...)
+    is reached through this object as it would be on the backend.
+    """
+
+    def __init__(self, backend: KVStore, cache: ContentCache) -> None:
+        self.backend = backend
+        self.cache = cache
+
+    def __repr__(self) -> str:
+        return f"CachedStore({self.backend!r})"
+
+    def __getattr__(self, name: str) -> Any:
+        if name.startswith("__") or name in ("backend", "cache"):
+            raise AttributeError(name)
+        return getattr(self.backend, name)
+
+    # -- reads -----------------------------------------------------------
+
+    def get(self, key: str) -> bytes | None:
+        if cacheable(key):
+            held = self.cache.lookup((key,))
+            if key in held:
+                self.cache.count(1, 0)
+                return held[key]
+            value = self.backend.get(key)
+            self.cache.count(0, 1)
+            if value is not None:
+                self.cache.remember({key: value})
+            return value
+        value = self.backend.get(key)
+        if key == GC_LEASE_KEY:
+            self.cache.saw_lease(value)
+        return value
+
+    def get_many(self, *args) -> Mapping[str, bytes]:
+        keys = list(dict.fromkeys(self._normalize_keys(args)))
+        wanted = [k for k in keys if cacheable(k)]
+        if GC_LEASE_KEY in keys:
+            # A read of the lease may reveal a sweep, and nothing the
+            # cache held before it may be answered beside it: the whole
+            # call goes to the store, and the record is noted before
+            # anything it brought back is remembered.
+            held: dict[str, bytes] = {}
+            found = dict(self.backend.get_many(keys))
+            self.cache.saw_lease(found.get(GC_LEASE_KEY))
+        else:
+            held = self.cache.lookup(wanted) if wanted else {}
+            rest = [k for k in keys if k not in held]
+            found = dict(self.backend.get_many(rest)) if rest else {}
+        fetched = {k: v for k, v in found.items() if cacheable(k)}
+        if wanted:
+            self.cache.count(len(held), len(wanted) - len(held))
+        if fetched:
+            self.cache.remember(fetched)
+        found.update(held)
+        return found
+
+    def items(self) -> Iterable[tuple[str, bytes]]:
+        return self.backend.items()
+
+    def keys(self, prefix: str = "") -> Iterable[str]:
+        return self.backend.keys(prefix)
+
+    def __contains__(self, key: str) -> bool:
+        if cacheable(key) and self.cache.lookup((key,)):
+            return True
+        return key in self.backend
+
+    # -- writes ----------------------------------------------------------
+
+    def set(self, key: str, value: bytes) -> None:
+        self.backend.set(key, value)
+        self._wrote({key: value}, ())
+
+    def set_many(
+        self, items: Mapping[str, bytes] | None = None, /, **kwargs: bytes
+    ) -> None:
+        items = dict(self._normalize_items(items, kwargs))
+        self.backend.set_many(items)
+        self._wrote(items, ())
+
+    def remove(self, key: str) -> None:
+        self.backend.remove(key)
+        self._wrote({}, (key,))
+
+    def remove_many(self, *args) -> None:
+        keys = list(self._normalize_keys(args))
+        self.backend.remove_many(keys)
+        self._wrote({}, keys)
+
+    def cas_many(
+        self,
+        expected: Mapping[str, bytes | None],
+        writes: Mapping[str, bytes],
+        removes: Iterable[str] = (),
+    ) -> bool:
+        removes = list(removes)
+        if not self.backend.cas_many(expected, writes, removes):
+            return False
+        self._wrote(writes, removes)
+        return True
+
+    def clear(self) -> None:
+        self.backend.clear()
+        self.cache.clear()
+
+    def _wrote(self, writes: Mapping[str, bytes], removes: Iterable[str]) -> None:
+        gone = [k for k in removes if cacheable(k)]
+        if gone:
+            self.cache.forget(gone)
+        landed = {k: v for k, v in writes.items() if cacheable(k)}
+        if landed:
+            self.cache.remember(landed)
+        if GC_LEASE_KEY in writes:
+            # This process's own sweep taking or releasing the lease.
+            self.cache.saw_lease(writes[GC_LEASE_KEY])

{kvgit-0.4.1 → kvgit-0.4.2}/kvgit/refs.py

@@ -35,10 +35,15 @@ class Branches(Mapping[str, str]):
         return f"Branches({list(self)!r})"
 
     def __getitem__(self, name: str) -> str:
+        return self._resolve(name)
+
+    def _resolve(self, name: str, roots: dict[str, str] | None = None) -> str:
+        """The branch's head, recording its root in ``roots`` when given
+        (see :meth:`Repo._resolve_ref`)."""
         _kv._reject_reserved_branch(name)
-        store = self._repo.store
+        store = self._repo._store
         commit = _kv._resolve_head(
-            store, name, recover_from_corrupt_head=self._repo._recover
+            store, name, recover_from_corrupt_head=self._repo._recover, roots=roots
         )
         if commit is not None:
             return commit
@@ -47,13 +52,13 @@ class Branches(Mapping[str, str]):
         raise UnknownBranchError(f"Branch '{name}' does not exist")
 
     def __contains__(self, name: object) -> bool:
-        return isinstance(name, str) and VersionedKV.exists(self._repo.store, name)
+        return isinstance(name, str) and VersionedKV.exists(self._repo._store, name)
 
     def __iter__(self) -> Iterator[str]:
-        return iter(VersionedKV.branches(self._repo.store))
+        return iter(VersionedKV.branches(self._repo._store))
 
     def __len__(self) -> int:
-        return len(VersionedKV.branches(self._repo.store))
+        return len(VersionedKV.branches(self._repo._store))
 
     def create(self, name: str, at: str | None = None) -> str:
         """Create branch ``name`` at commit ``at`` (default: the empty root
@@ -64,7 +69,7 @@ class Branches(Mapping[str, str]):
             UnknownCommitError: if ``at`` is not in the store.
         """
         target = at or ROOT_COMMIT
-        _kv.create_branch(self._repo.store, name, target)
+        _kv.create_branch(self._repo._store, name, target)
         return target
 
     def delete(self, name: str) -> None:
@@ -75,7 +80,7 @@ class Branches(Mapping[str, str]):
         Raises:
             UnknownBranchError: if there is no such branch.
         """
-        _kv.delete_branch(self._repo.store, name)
+        _kv.delete_branch(self._repo._store, name)
 
 
 class Tags(Mapping[str, str]):
@@ -95,7 +100,7 @@ class Tags(Mapping[str, str]):
         return f"Tags({list(self)!r})"
 
     def __getitem__(self, name: str) -> str:
-        commit = _kv._resolve_tag(self._repo.store, name)
+        commit = _kv._resolve_tag(self._repo._store, name)
         if commit is None:
             raise UnknownTagError(f"Tag '{name}' does not exist")
         return commit
@@ -103,14 +108,14 @@ class Tags(Mapping[str, str]):
     def __contains__(self, name: object) -> bool:
         return (
             isinstance(name, str)
-            and _kv._resolve_tag(self._repo.store, name) is not None
+            and _kv._resolve_tag(self._repo._store, name) is not None
         )
 
     def __iter__(self) -> Iterator[str]:
-        return iter(_kv.tags(self._repo.store))
+        return iter(_kv.tags(self._repo._store))
 
     def __len__(self) -> int:
-        return len(_kv.tags(self._repo.store))
+        return len(_kv.tags(self._repo._store))
 
     def items(self) -> ItemsView[str, str]:
         """Every tag and its commit: a live view, like the mapping, that
@@ -125,7 +130,7 @@ class Tags(Mapping[str, str]):
             TagExistsError: if the name is taken.
             UnknownCommitError: if ``commit`` is not in the store.
         """
-        _kv.create_tag(self._repo.store, name, commit, info)
+        _kv.create_tag(self._repo._store, name, commit, info)
 
     def delete(self, name: str) -> None:
         """Delete a tag. A commit it alone kept alive becomes collectable
@@ -134,7 +139,7 @@ class Tags(Mapping[str, str]):
         Raises:
             UnknownTagError: if there is no such tag.
         """
-        _kv.delete_tag(self._repo.store, name)
+        _kv.delete_tag(self._repo._store, name)
 
     def info(self, name: str) -> TagInfo:
         """A tag's commit, creation time, info, and whether its commit is
@@ -143,7 +148,7 @@ class Tags(Mapping[str, str]):
         Raises:
             UnknownTagError: if there is no such tag.
         """
-        found = _kv.tag_info(self._repo.store, name)
+        found = _kv.tag_info(self._repo._store, name)
         if found is None:
             raise UnknownTagError(f"Tag '{name}' does not exist")
         return found

{kvgit-0.4.1 → kvgit-0.4.2}/kvgit/repo.py

@@ -7,6 +7,7 @@ from dataclasses import dataclass
 from typing import Any
 
 from ._codec import Codec, CodecSpec
+from .cache import DEFAULT_CACHE_BYTES, CachedStore, ContentCache
 from .content_types import MergeFn
 from .encoding import loads, safe_loads
 from .errors import (
@@ -69,6 +70,11 @@ class Repo:
         default_merge: The merge rule for keys no other rule covers.
         recover_from_corrupt_head: Last-resort recovery for a HEAD that is
             damaged and has no usable backup; see the API reference.
+        cache_bytes: Memory for tree nodes and commit records read from
+            the store, which never change once written (32 MB by
+            default; ``0`` turns the cache off). A sweep by any process
+            empties it before this one builds on what the sweep removed;
+            see :class:`~kvgit.cache.ContentCache`.
 
     Raises:
         StorageVersionError: if the store is stamped with a layout this
@@ -84,9 +90,22 @@ class Repo:
         merge_prefixes: dict[str, MergeRule] | None = None,
         default_merge: MergeRule | None = None,
         recover_from_corrupt_head: CorruptHeadRecoverer | None = None,
+        cache_bytes: int = DEFAULT_CACHE_BYTES,
     ) -> None:
         _kv._check_storage_version(backend)
-        self._store = backend
+        self._backend = backend
+        # 0 turns the cache off; anything else is a budget, and
+        # ContentCache refuses one that is negative.
+        self.cache: ContentCache | None = (
+            ContentCache(cache_bytes) if cache_bytes != 0 else None
+        )
+        """What this repository remembers of its store, with its hit and
+        miss counts; ``None`` with ``cache_bytes=0``."""
+        # Everything the repository reads goes through the cache; the
+        # backend itself stays what ``store`` hands out.
+        self._store: KVStore = (
+            CachedStore(backend, self.cache) if self.cache is not None else backend
+        )
         self._codec = Codec(codec, backend)
         self._merge_fns = dict(merge_fns or {})
         self._merge_prefixes = dict(merge_prefixes or {})
@@ -100,16 +119,22 @@ class Repo:
         ``delete`` and ``info``."""
 
     def __repr__(self) -> str:
-        return f"Repo({type(self._store).__name__})"
+        return f"Repo({type(self._backend).__name__})"
 
     @property
     def store(self) -> KVStore:
-        """The backend."""
-        return self._store
+        """The backend.
+
+        Reads made straight through it bypass the repository's cache,
+        and so do removals: a key deleted here, rather than by
+        :meth:`gc`, may still be answered from memory until the next
+        sweep.
+        """
+        return self._backend
 
     def close(self) -> None:
         """Close the backend, if it has anything to close."""
-        close = getattr(self._store, "close", None)
+        close = getattr(self._backend, "close", None)
         if callable(close):
             close()
 
@@ -255,7 +280,9 @@ class Repo:
         Name exactly one. The snapshot is pinned to the commit resolved
         now: a branch that moves later does not move it.
         """
-        return Snapshot(self, self._resolve_ref(commit=commit, branch=branch, tag=tag))
+        roots: dict[str, str] = {}
+        target = self._resolve_ref(commit=commit, branch=branch, tag=tag, roots=roots)
+        return Snapshot(self, target, root=roots.get(target))
 
     # -- Maintenance --
 
@@ -287,13 +314,18 @@ class Repo:
         commit: str | None = None,
         branch: str | None = None,
         tag: str | None = None,
+        roots: dict[str, str] | None = None,
     ) -> str:
-        """The commit a ref names; exactly one must be given."""
+        """The commit a ref names; exactly one must be given.
+
+        Checking that the commit exists reads its keyset root; ``roots``,
+        when given, keeps it, for a caller about to open that tree.
+        """
         given = [ref for ref in (commit, branch, tag) if ref is not None]
         if len(given) != 1:
             raise ValueError("name exactly one of commit, branch or tag")
         if branch is not None:
-            return self.branches[branch]
+            return self.branches._resolve(branch, roots)
         if tag is not None:
             tagged = _kv._resolve_tag(self._store, tag)
             if tagged is None:
@@ -301,7 +333,7 @@ class Repo:
             target = tagged
         else:
             target = commit  # type: ignore[assignment]
-        if self._store.get(COMMIT_ROOT % target) is None:
+        if not _kv._has_root(self._store, target, roots):
             raise UnknownCommitError(f"Commit '{target}' does not exist")
         return target
 
@@ -313,9 +345,11 @@ class Snapshot(Mapping[str, Any]):
     is the same state as stored bytes, whatever the codec.
     """
 
-    def __init__(self, repo: Repo, commit: str) -> None:
+    def __init__(self, repo: Repo, commit: str, *, root: str | None = None) -> None:
         self._repo = repo
         self.commit = commit
+        # The keyset root, when whoever made this snapshot already read it.
+        self._root = root
         self._keyset: Keyset | None = None
         # The whole keyset as key -> blob pointer, once something iterates
         # it; until then, reads look keys up in the tree one batch at a
@@ -328,10 +362,13 @@ class Snapshot(Mapping[str, Any]):
 
     def _tree(self) -> Keyset:
         if self._keyset is None:
-            root_raw = self._repo.store.get(COMMIT_ROOT % self.commit)
-            if root_raw is None:
-                raise UnknownCommitError(f"Commit '{self.commit}' does not exist")
-            self._keyset = Keyset(self._repo.store, root=loads(root_raw))
+            root = self._root
+            if root is None:
+                root_raw = self._repo._store.get(COMMIT_ROOT % self.commit)
+                if root_raw is None:
+                    raise UnknownCommitError(f"Commit '{self.commit}' does not exist")
+                root = loads(root_raw)
+            self._keyset = Keyset(self._repo._store, root=root)
         return self._keyset
 
     def _index(self) -> dict[str, str]:
@@ -369,7 +406,7 @@ class Snapshot(Mapping[str, Any]):
             wanted.setdefault(pointer, []).append(key)
         if not wanted:
             return {}
-        found = self._repo.store.get_many(wanted.keys())
+        found = self._repo._store.get_many(wanted.keys())
         return {key: raw for pointer, raw in found.items() for key in wanted[pointer]}
 
     def __getitem__(self, key: str) -> Any: