perf(cache): build restored shapes on first use; compress the cell cache

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
NiJingzhe
2026-10-20 23:45:59 +08:00
parent 999439d939
commit 3f5ee25e1c
7 changed files with 254 additions and 8 deletions
+4
View File
@@ -14,6 +14,10 @@ user-facing notes live in [`docs/updates/`](docs/updates/) (English and
once). The cache no longer stores a cell's private (`_name`) variables, and the geometry
bytes in a pickle are compressed (zlib, level 1); entries written before are still read.
On the desktop-arm benchmark a no-change run drops from 23.6 s to 7.0 s.
- Cache: a restored shape is built when something first uses it (a cached value that no
running cell reads is never built, and pickling it again hands back what it was restored
from), and the cell cache compresses what it writes (zlib level 1; entries written before
are still read). The desktop-arm cache drops from 1.2 GB to 96 MB.
- Cache: a cell that does `from lib.dims import A` now depends on the definition of `A` (and
what it reads, across local modules), not on the whole file. Editing another name of
`lib/dims.py`, a comment, or the formatting leaves the cell cached. A module the analysis
+96 -6
View File
@@ -19,6 +19,7 @@ from __future__ import annotations
import io
import re
import threading
import zlib
from dataclasses import dataclass
from typing import TYPE_CHECKING, Any, Dict, List, Mapping, Set, Tuple
@@ -295,19 +296,108 @@ def reduce_shape(wrapper: "AnyShape") -> Tuple[Any, Tuple[Any, ...]]:
return (restore_shape, (type(wrapper).__name__, payload, _capture_states(wrapper)))
_PENDING = "_pending_restore"
"""The ``__dict__`` key under which a restored shape that is not built yet
keeps what it needs to be: ``(payload, states)``."""
_build_lock = threading.RLock()
_building = threading.local()
_lazy_classes: Dict[type, type] = {}
class _PendingShape:
"""Behaviour of a restored shape that has not been built yet.
The instance is empty. Its first attribute read or write builds it (the
kernel shape from its bytes, the wrapper tree, the saved state) and puts
its real class back, after which none of this is in the way. Pickling it
again hands back what it was restored from.
"""
def __getattr__(self, name: str) -> Any:
if not name.startswith("__"):
_build(self)
try:
return object.__getattribute__(self, name)
except AttributeError:
pass
raise AttributeError(f"{type(self).__name__!r} object has no attribute {name!r}")
def __setattr__(self, name: str, value: Any) -> None:
_build(self)
object.__setattr__(self, name, value)
def __reduce__(self) -> Tuple[Any, Tuple[Any, ...]]:
pending = self.__dict__.get(_PENDING)
if pending is None:
_build(self)
return type(self).__reduce__(self)
return (restore_shape, (_real_class(type(self)).__name__, *pending))
def _real_class(cls: type) -> type:
return cls.__mro__[2] if _PendingShape in cls.__mro__ else cls
def _lazy_class(wrapper_type: type) -> type:
lazy = _lazy_classes.get(wrapper_type)
if lazy is None:
# Same name as the real class, so a repr or a ``type(x).__name__``
# does not tell the two apart.
lazy = _lazy_classes[wrapper_type] = type(
wrapper_type.__name__, (_PendingShape, wrapper_type), {"__module__": wrapper_type.__module__}
)
return lazy
def is_pending(wrapper: "AnyShape") -> bool:
"""Whether *wrapper* was restored and nothing has used it yet."""
return _PENDING in wrapper.__dict__
def _build(wrapper: Any) -> None:
"""Build a pending shape; a no-op for one already built (or being built
by this thread: its own constructor reads its attributes)."""
if _PENDING not in wrapper.__dict__:
return
with _build_lock:
pending = wrapper.__dict__.get(_PENDING)
building = _building.__dict__.setdefault("ids", set())
if pending is None or id(wrapper) in building:
return
building.add(id(wrapper))
try:
payload, states = pending
payload = _unpack(payload)
real = _real_class(type(wrapper))
real.__init__(wrapper, _read_shape(payload))
remember_source_bytes(wrapper, payload)
_apply_states(wrapper, states)
del wrapper.__dict__[_PENDING]
wrapper.__class__ = real
finally:
building.discard(id(wrapper))
def restore_shape(
class_name: str, payload: bytes, states: Tuple[_EntityState, ...]
) -> "AnyShape":
"""Unpickle target: rebuild the wrapper and re-apply entity state."""
"""Unpickle target: a shape that is built when it is first used.
Most values a cell cache restores are never read by the cells that run
(they are only there so that the cell counts as done), and building one
(decoding the kernel shape, the wrapper tree, the saved state) is most of
the time restoring costs.
"""
from .. import core
wrapper_type = getattr(core, class_name)
payload = _unpack(payload)
wrapper = wrapper_type(_read_shape(payload))
remember_source_bytes(wrapper, payload)
_apply_states(wrapper, states)
wrapper = wrapper_type.__new__(_lazy_class(wrapper_type))
object.__setattr__(wrapper, "__dict__", {_PENDING: (payload, states)})
return wrapper
__all__ = ["reduce_shape", "remember_source_bytes", "restore_shape", "source_bytes"]
__all__ = ["is_pending", "reduce_shape", "remember_source_bytes", "restore_shape", "source_bytes"]
+31 -1
View File
@@ -24,6 +24,7 @@ from __future__ import annotations
import hashlib
import json
import shutil
import zlib
from collections.abc import Callable, Mapping
from pathlib import Path
from typing import Any
@@ -65,6 +66,35 @@ def cache_root(config: NotebookConfig) -> Path:
return state_dir(config) / "cache"
_PACKED = b"SCZ2"
"""Starts an entry written compressed; one without it was written before
compression existed and is read as it is."""
_MIN_PACKED = 1024
class CompressedFileStore(FileStore):
"""marimo's file store, compressing what it writes.
A cell's value carries the definitions of the parts in it (archives and
JSON documents, written uncompressed) and the geometry: an assembly is a
hundred megabytes of pickle that shrinks ten-fold at zlib level 1, and
reading less is most of what a restore costs. Decompressing happens on
the loader's reader threads, where zlib lets go of the interpreter lock.
"""
def get(self, key: str) -> bytes | None:
data = super().get(key)
if data is not None and data.startswith(_PACKED):
return zlib.decompress(data[len(_PACKED) :])
return data
def put(self, key: str, value: bytes) -> bool:
if len(value) >= _MIN_PACKED:
value = _PACKED + zlib.compress(value, 1)
return super().put(key, value)
class CellDigests:
"""The digest of each cell of a notebook, from what it depends on.
@@ -162,7 +192,7 @@ class CellCache(CachedLifecycle):
def _store(self, digest: str) -> LazyLoader:
if digest not in self._stores:
self._stores[digest] = LazyLoader(
name=_CELLS, store=LazyStore(FileStore(str(self._root / digest)))
name=_CELLS, store=LazyStore(CompressedFileStore(str(self._root / digest)))
)
return self._stores[digest]
+56
View File
@@ -0,0 +1,56 @@
"""What the cell cache puts on disk: compressed, and still reading what it
wrote before it compressed."""
from __future__ import annotations
import zlib
from simplecadapi.runtime import run_notebook
from simplecadapi.runtime.deps import state_dir
from test_notebook_runtime import NotebookTestCase, cell, notebook_text
DRILLED = notebook_text(
cell(
"""
plate = scad.make_box_rsolid(60.0, 40.0, 6.0)
for _i in range(24):
_hole = scad.make_cylinder_rsolid(
radius=1.5, height=20.0, bottom_face_center=(5.0 + _i % 6 * 9, 5.0 + _i // 6 * 9, -5.0)
)
plate = scad.cut_rsolid(plate, _hole)
""",
returns="plate",
),
cell("part = scad.Part(part_id='drilled', body=plate)", reads="plate", returns="part"),
table='id = "drilled"',
)
class TestCellCacheStore(NotebookTestCase):
def setUp(self) -> None:
super().setUp()
self.nb = self.write("drilled.py", DRILLED)
def entries(self, run):
return [item for item in (state_dir(run.config) / "cache").rglob("*") if item.is_file() and item.name != "_runs.json"]
def test_entries_are_stored_compressed(self) -> None:
run = run_notebook(self.nb)
stored = sum(item.stat().st_size for item in self.entries(run))
plain = 0
for item in self.entries(run):
data = item.read_bytes()
plain += len(zlib.decompress(data[4:])) if data.startswith(b"SCZ2") else len(data)
self.assertGreater(plain, 100_000)
self.assertLess(stored, plain // 2)
def test_entries_written_before_compression_are_still_hit(self) -> None:
first = run_notebook(self.nb)
for item in self.entries(first):
data = item.read_bytes()
if data.startswith(b"SCZ2"):
item.write_bytes(zlib.decompress(data[4:]))
second = run_notebook(self.nb)
self.assertEqual(self.statuses(second), ["ran", "cached", "cached"])
self.assertEqual(first.definition.content_hash, second.definition.content_hash)
+55
View File
@@ -105,3 +105,58 @@ class TestShapePayload(unittest.TestCase):
self.assertEqual(effective_tags(legacy), before)
self.assertAlmostEqual(legacy.get_volume(), shape.get_volume(), places=6)
class TestLazyRestore(unittest.TestCase):
"""A restored shape is built when something first uses it: most cached
values are never read by the cells that run."""
def test_a_restored_shape_is_built_on_first_use(self) -> None:
from simplecadapi._internal.shape_pickle import is_pending
shape = drilled_plate()
restored = pickle.loads(pickle.dumps(shape))
self.assertIsInstance(restored, scad.Solid)
self.assertTrue(is_pending(restored))
self.assertAlmostEqual(restored.get_volume(), shape.get_volume(), places=6)
self.assertFalse(is_pending(restored))
self.assertEqual(effective_tags(restored), effective_tags(shape))
def test_pickling_a_shape_nobody_used_does_not_build_it(self) -> None:
from simplecadapi._internal.shape_pickle import is_pending
shape = drilled_plate()
restored = pickle.loads(pickle.dumps(shape))
again = pickle.loads(pickle.dumps(restored))
self.assertTrue(is_pending(restored))
self.assertTrue(is_pending(again))
self.assertAlmostEqual(again.get_volume(), shape.get_volume(), places=6)
def test_a_missing_attribute_is_still_an_attribute_error(self) -> None:
restored = pickle.loads(pickle.dumps(drilled_plate()))
self.assertFalse(hasattr(restored, "no_such_attribute"))
self.assertTrue(hasattr(restored, "wrapped"))
def test_two_threads_first_using_a_shape_build_it_once(self) -> None:
import threading
from simplecadapi._internal import shape_pickle
restored = pickle.loads(pickle.dumps(drilled_plate()))
reads = 0
original = shape_pickle._read_shape
def counted(payload):
nonlocal reads
reads += 1
return original(payload)
shape_pickle._read_shape = counted
try:
volumes: list[float] = []
threads = [threading.Thread(target=lambda: volumes.append(restored.get_volume())) for _ in range(4)]
[thread.start() for thread in threads]
[thread.join() for thread in threads]
finally:
shape_pickle._read_shape = original
self.assertEqual(reads, 1)
self.assertEqual(len(set(volumes)), 1)
+7
View File
@@ -26,6 +26,13 @@ CASE = Path(__file__).resolve().parent.parent / "sandbox-envs" / "desktop_arm_so
def main() -> None:
import os
if os.environ.get("SCA_NO_PACK"): # A/B: write cache entries uncompressed
from simplecadapi.runtime import cache
cache._MIN_PACKED = 1 << 60
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
parser.add_argument("--keep", type=Path, help="copy the case here and keep it")
args = parser.parse_args()
+5 -1
View File
@@ -149,9 +149,13 @@ def scenario(title: str, top: Path) -> float:
_rows.clear()
start = time.perf_counter()
cpu = time.process_time()
runner.run_notebook(top)
total = time.perf_counter() - start
print(f"\n== {title}: {total:.2f}s")
cpu = time.process_time() - cpu
# CPU seconds (all threads of this process) stay comparable between runs
# when the machine is busy; wall seconds do not.
print(f"\n== {title}: {total:.2f}s wall, {cpu:.2f}s cpu")
for depth, name, seconds, ran, cached in _rows:
mark = "" if ran == 0 else f" <- {ran} cell(s) ran"
print(f" {' ' * depth}{name:<14} {seconds:6.2f}s ran {ran:>2} cached {cached:>2}{mark}")