A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
perf: mechanism for parallel read/write in mo.persistent_cache (#8805)
Dylan Madisettif47c3ff6518c
diff --git a/marimo/_save/cache.py b/marimo/_save/cache.pyindex f61bce8e25..6e990e4d01 100644--- a/marimo/_save/cache.py+++ b/marimo/_save/cache.py@@ -17,6 +17,7 @@ from marimo._save.stubs import (CustomStub,FunctionStub,ModuleStub,+ ReferenceStub,UIElementStub,maybe_register_stub,)@@ -106,7 +107,7 @@ class HashMemoCleanup(CellLifecycleItem):ValidCacheSha = namedtuple("ValidCacheSha", ("sha", "cache_type"))-MetaKey = Literal["return", "version", "runtime"]+MetaKey = Literal["return", "version", "runtime", "variable_hashes"]# Matches functoolsCacheInfo = namedtuple("CacheInfo", ["hits", "misses", "maxsize", "currsize", "time_saved"]@@ -220,6 +221,8 @@ class Cache:value.clear()value.update(result)result = value+ elif isinstance(value, ReferenceStub):+ result = value.load(scope)elif isinstance(value, CustomStub):# CustomStub is a placeholder for a custom type, which cannot be# restored directly.diff --git a/marimo/_save/loaders/__init__.py b/marimo/_save/loaders/__init__.pyindex 6170ca1807..3c85d994d8 100644--- a/marimo/_save/loaders/__init__.py+++ b/marimo/_save/loaders/__init__.py@@ -4,6 +4,7 @@ from __future__ import annotationsfrom typing import Literalfrom marimo._save.loaders.json import JsonLoader+from marimo._save.loaders.lazy import LazyLoaderfrom marimo._save.loaders.loader import (BasePersistenceLoader,Loader,@@ -13,16 +14,18 @@ from marimo._save.loaders.loader import (from marimo._save.loaders.memory import MemoryLoaderfrom marimo._save.loaders.pickle import PickleLoader-LoaderKey = Literal["memory", "pickle", "json"]+LoaderKey = Literal["memory", "pickle", "json", "lazy"]PERSISTENT_LOADERS: dict[LoaderKey, LoaderType] = {"pickle": PickleLoader,"json": JsonLoader,+ "lazy": LazyLoader,}__all__ = ["BasePersistenceLoader","JsonLoader",+ "LazyLoader","Loader","LoaderKey","LoaderPartial",diff --git a/marimo/_save/loaders/lazy.py b/marimo/_save/loaders/lazy.pynew file mode 100644index 0000000000..5ce3ff9fcb--- /dev/null+++ b/marimo/_save/loaders/lazy.py@@ -0,0 +1,288 @@+# Copyright 2026 Marimo. All rights reserved.+from __future__ import annotations++import pickle+import queue+import threading+from pathlib import Path+from typing import Any, Optional++import msgspec++from marimo import _loggers+from marimo._save.cache import (+ MARIMO_CACHE_VERSION,+ Cache,+)+from marimo._save.hash import HashKey+from marimo._save.loaders.loader import BasePersistenceLoader+from marimo._save.stores import FileStore, Store+from marimo._save.stubs import (+ LAZY_STUB_LOOKUP,+ FunctionStub,+ ModuleStub,+)+from marimo._save.stubs.lazy_stub import (+ Cache as CacheSchema,+ CacheType,+ ImmediateReferenceStub,+ Item,+ Meta,+ ReferenceStub,+)++LOGGER = _loggers.marimo_logger()+++def to_item(+ path: Path,+ value: Optional[Any],+ var_name: str = "",+ loader: Optional[str] = None,+ hash: Optional[str] = "", # noqa: A002+) -> Item:+ if value is None:+ return Item()++ if loader is None:+ loader = LAZY_STUB_LOOKUP.get(type(value), "pickle")++ if loader == "pickle":+ return Item(+ reference=(path / f"{var_name}.pickle").as_posix(), hash=hash+ )+ if loader == "ui":+ return Item(reference=(path / "ui.pickle").as_posix())+ if isinstance(value, FunctionStub):+ return Item(function=value.dump())+ if isinstance(value, ModuleStub):+ return Item(module=value.name)+ if isinstance(value, (int, str, float, bool, bytes, type(None))):+ return Item(primitive=value)++ return Item(reference=(path / f"{var_name}.pickle").as_posix(), hash=hash)+++def from_item(item: Item) -> Any:+ if item.reference is not None:+ return ImmediateReferenceStub(+ ReferenceStub(item.reference, hash_value=item.hash or "")+ )+ if item.module is not None:+ mod_stub = ModuleStub.__new__(ModuleStub)+ mod_stub.name = item.module+ return mod_stub+ if item.function is not None:+ fn_stub = FunctionStub.__new__(FunctionStub)+ fn_stub.code, fn_stub.filename, fn_stub.lineno = item.function+ return fn_stub+ if item.primitive is not None:+ return item.primitive+ return None+++class LazyStore(FileStore): ...+++class LazyLoader(BasePersistenceLoader):+ def __init__(+ self,+ name: str,+ store: Optional[Store] = None,+ ) -> None:+ if store is None:+ store = LazyStore()+ super().__init__(name, "jsonl", store)+ self._pending: list[threading.Thread] = []++ def flush(self) -> None:+ """Wait for all pending background writes to complete."""+ for t in self._pending:+ t.join()+ self._pending.clear()++ def load_cache(self, key: HashKey) -> Optional[Cache]:+ try:+ blob: Optional[bytes] = self.store.get(str(self.build_path(key)))+ if not blob:+ return None+ return self.restore_cache(key, blob)+ except Exception as e:+ LOGGER.warning("Failed to restore lazy cache: %s", e)+ return None++ def restore_cache(self, _key: HashKey, blob: bytes) -> Cache:+ cache_data = msgspec.json.decode(blob, type=CacheSchema)+ base = Path(self.name) / cache_data.hash++ # Collect references to load+ ref_vars: dict[str, str] = {}+ variable_hashes: dict[str, str] = {}+ for var_name, item in cache_data.defs.items():+ if var_name in cache_data.ui_defs:+ ref_vars[var_name] = (base / "ui.pickle").as_posix()+ elif item.reference is not None:+ ref_vars[var_name] = item.reference+ if item.hash:+ variable_hashes[var_name] = item.hash++ # Eagerly resolve return value reference alongside defs+ return_ref: Optional[str] = None+ if (+ cache_data.meta.return_value+ and cache_data.meta.return_value.reference+ ):+ return_ref = cache_data.meta.return_value.reference++ # Read + unpickle in parallel, stream results via queue+ results: queue.Queue[tuple[str, Any]] = queue.Queue()+ unique_keys = set(ref_vars.values())+ if return_ref:+ unique_keys.add(return_ref)++ def _load_and_unpickle(key: str) -> None:+ data = self.store.get(key)+ if data:+ results.put((key, pickle.loads(data)))++ threads = [+ threading.Thread(target=_load_and_unpickle, args=(key,))+ for key in unique_keys+ ]+ for t in threads:+ t.start()++ # Stream results as they arrive+ unpickled: dict[str, Any] = {}+ for _ in unique_keys:+ try:+ key, val = results.get(timeout=30)+ unpickled[key] = val+ except queue.Empty:+ break++ for t in threads:+ t.join()++ if len(unpickled) < len(unique_keys):+ raise FileNotFoundError("Incomplete cache: missing blobs")++ # Distribute to defs+ defs: dict[str, Any] = {}+ for var_name, item in cache_data.defs.items():+ if var_name in ref_vars:+ ref_key = ref_vars[var_name]+ val = unpickled.get(ref_key)+ if var_name in cache_data.ui_defs and isinstance(val, dict):+ defs[var_name] = val[var_name]+ else:+ defs[var_name] = val+ else:+ defs[var_name] = from_item(item)++ if return_ref and return_ref in unpickled:+ return_item = unpickled[return_ref]+ elif cache_data.meta.return_value:+ return_item = from_item(cache_data.meta.return_value)+ else:+ return_item = None++ return Cache(+ hash=cache_data.hash,+ cache_type=cache_data.cache_type.value,+ stateful_refs=set(cache_data.stateful_refs),+ defs=defs,+ meta={+ "version": cache_data.meta.version or MARIMO_CACHE_VERSION,+ "return": return_item,+ "variable_hashes": variable_hashes,+ },+ hit=True,+ )++ def save_cache(self, cache: Cache) -> bool:+ # Reap completed threads+ self._pending = [t for t in self._pending if t.is_alive()]++ path = Path(self.name) / cache.hash+ variable_hashes = cache.meta.get("variable_hashes", {})+ return_item = to_item(+ path, cache.meta.get("return", None), var_name="return"+ )+ if return_item.reference:+ return_item.reference = (path / "return.pickle").as_posix()++ try:+ cache_type_enum = CacheType(cache.cache_type)+ except ValueError:+ cache_type_enum = CacheType.UNKNOWN++ pickle_vars: dict[str, Any] = {}+ ui_vars: dict[str, Any] = {}+ defs_dict: dict[str, Item] = {}+ ui_defs_list: list[str] = []++ for var, obj in cache.defs.items():+ loader = LAZY_STUB_LOOKUP.get(type(obj), "pickle")+ if loader == "pickle":+ pickle_vars[var] = obj+ elif loader == "ui":+ ui_vars[var] = obj+ ui_defs_list.append(var)+ defs_dict[var] = to_item(+ path,+ obj,+ var_name=var,+ loader=loader,+ hash=variable_hashes.get(var, ""),+ )++ manifest = msgspec.json.encode(+ CacheSchema(+ hash=cache.hash,+ cache_type=cache_type_enum,+ stateful_refs=list(cache.stateful_refs),+ defs=defs_dict,+ meta=Meta(+ version=cache.meta.get("version", MARIMO_CACHE_VERSION),+ return_value=return_item,+ ),+ ui_defs=ui_defs_list,+ )+ )++ # Capture values for the background thread+ store = self.store+ return_ref = return_item.reference+ return_value = cache.meta.get("return", None)+ manifest_key = str(self.build_path(cache.key))++ def _serialize_and_write() -> None:+ """Serialize and write all blobs + manifest in background."""+ try:+ if return_ref:+ store.put(return_ref, pickle.dumps(return_value))+ if ui_vars:+ store.put(+ (path / "ui.pickle").as_posix(),+ pickle.dumps(ui_vars),+ )+ for var, obj in pickle_vars.items():+ store.put(+ (path / f"{var}.pickle").as_posix(),+ pickle.dumps(obj),+ )+ # Manifest last — readers check for it to detect complete writes+ store.put(manifest_key, manifest)+ except Exception:+ LOGGER.exception("Failed to write cache blobs for %s", path)++ t = threading.Thread(target=_serialize_and_write, daemon=False)+ t.start()+ self._pending.append(t)+ return True++ def to_blob(self, cache: Cache) -> Optional[bytes]:+ # Not used — save_cache is overridden. Kept for interface compliance.+ del cache+ return Nonediff --git a/marimo/_save/save.py b/marimo/_save/save.pyindex c63256921a..feee77f5c4 100644--- a/marimo/_save/save.py+++ b/marimo/_save/save.py@@ -615,7 +615,7 @@ class _cache_call_async(_cache_call[P, R]):try:if attempt.hit:attempt.restore(scope)- return attempt.meta["return"]+ return attempt.meta.get("return")start_time = time.time()# Await the coroutine to get the actual resultdiff --git a/marimo/_save/stubs/__init__.py b/marimo/_save/stubs/__init__.pyindex c15943f379..7ad242c467 100644--- a/marimo/_save/stubs/__init__.py+++ b/marimo/_save/stubs/__init__.py@@ -6,6 +6,7 @@ from __future__ import annotationsfrom typing import Any, Callablefrom marimo._save.stubs.function_stub import FunctionStub+from marimo._save.stubs.lazy_stub import ReferenceStubfrom marimo._save.stubs.module_stub import ModuleStubfrom marimo._save.stubs.pydantic_stub import PydanticStubfrom marimo._save.stubs.stubs import (@@ -23,6 +24,18 @@ STUB_REGISTRATIONS: dict[str, Callable[[Any], None]] = {"pydantic.main.BaseModel": PydanticStub.register,}+LAZY_STUB_LOOKUP: dict[type, str] = {+ int: "inline",+ str: "inline",+ float: "inline",+ bool: "inline",+ bytes: "inline",+ type(None): "inline",+ FunctionStub: "inline",+ ModuleStub: "inline",+ UIElementStub: "ui",+}+def maybe_register_stub(value: Any) -> bool:"""Lazily register a stub for a value's type if not already registered.@@ -85,9 +98,11 @@ __all__ = ["CUSTOM_STUBS","CustomStub","FunctionStub",+ "LAZY_STUB_LOOKUP","ModuleStub",+ "ReferenceStub","UIElementStub",- "maybe_register_stub","maybe_get_custom_stub",+ "maybe_register_stub","register_stub",]diff --git a/marimo/_save/stubs/function_stub.py b/marimo/_save/stubs/function_stub.pyindex 1a55a6d8b4..8f0a820751 100644--- a/marimo/_save/stubs/function_stub.py+++ b/marimo/_save/stubs/function_stub.py@@ -2,6 +2,7 @@from __future__ import annotationsimport inspect+import linecacheimport textwrapfrom typing import Any@@ -13,13 +14,31 @@ class FunctionStub:def __init__(self, function: Any) -> None:self.code = textwrap.dedent(inspect.getsource(function))+ self.filename = f"<{function.__name__}>"+ self.lineno = 1++ try:+ self.filename = inspect.getfile(function)+ _, self.lineno = inspect.getsourcelines(function)+ except (TypeError, OSError):+ passdef load(self, glbls: dict[str, Any]) -> Any:"""Reconstruct the function by executing its source code."""- # TODO: Fix line cache and associate with the correct module.- code_obj = compile(self.code, "<string>", "exec")+ if self.filename.startswith("<"):+ linecache.cache[self.filename] = (+ len(self.code),+ None,+ [line + "\n" for line in self.code.splitlines()],+ self.filename,+ )++ code_obj = compile(self.code, self.filename, "exec")lcls: dict[str, Any] = {}exec(code_obj, glbls, lcls)- # Update the global scope with the function.for value in lcls.values():return value++ def dump(self) -> tuple[str, str, int]:+ """Dump stored source code and metadata for lazy serialization."""+ return self.code, self.filename, self.linenodiff --git a/marimo/_save/stubs/lazy_stub.py b/marimo/_save/stubs/lazy_stub.pynew file mode 100644index 0000000000..26152a2aeb--- /dev/null+++ b/marimo/_save/stubs/lazy_stub.py@@ -0,0 +1,103 @@+# Copyright 2026 Marimo. All rights reserved.+"""msgspec schemas for lazy cache serialization."""++from __future__ import annotations++import pickle+from enum import Enum+from typing import Any, Optional++import msgspec++from marimo._save.stores import get_store+from marimo._save.stubs.stubs import CustomStub+++class CacheType(Enum):+ CONTEXT_EXECUTION_PATH = "ContextExecutionPath"+ CONTENT_ADDRESSED = "ContentAddressed"+ EXECUTION_PATH = "ExecutionPath"+ PURE = "Pure"+ DEFERRED = "Deferred"+ UNKNOWN = "Unknown"+++class Item(msgspec.Struct):+ """Represents a cached item with different value types.++ Only one of the value fields should be set (oneof semantics).+ """++ primitive: Optional[Any] = None+ reference: Optional[str] = None+ module: Optional[str] = None+ # (code, filename, linenumber)+ function: Optional[tuple[str, str, int]] = None+ hash: Optional[str] = None++ def __post_init__(self) -> None:+ fields_set = sum(+ 1+ for field in [+ self.primitive,+ self.reference,+ self.module,+ self.function,+ ]+ if field is not None+ )+ if fields_set > 1:+ raise ValueError("Item can only have one value field set")+++class Meta(msgspec.Struct):+ version: int+ return_value: Optional[Item] = None+++class Cache(msgspec.Struct):+ hash: str+ cache_type: CacheType+ defs: dict[str, Item]+ stateful_refs: list[str]+ meta: Meta+ ui_defs: list[str] = msgspec.field(default_factory=list)+++class ReferenceStub:+ """Deferred blob reference — loads from store on access."""++ def __init__(+ self, name: str, loader: str | None = None, hash_value: str = ""+ ) -> None:+ self.name = name+ self.loader = loader+ self.hash = hash_value++ def load(self, glbls: dict[str, Any]) -> Any:+ del glbls+ blob = self.to_bytes()+ if not blob:+ raise ValueError(f"Reference {self.name} not found in store.")+ return pickle.loads(blob)++ def to_bytes(self) -> bytes:+ maybe_bytes = get_store().get(self.name)+ return maybe_bytes if maybe_bytes else b""+++class ImmediateReferenceStub(CustomStub):+ """Wraps a ReferenceStub for immediate return-value restoration."""++ def __init__(self, reference: ReferenceStub) -> None:+ self.reference = reference++ def load(self, glbls: dict[str, Any]) -> Any:+ return self.reference.load(glbls)++ @staticmethod+ def get_type() -> type:+ return ReferenceStub++ def to_bytes(self) -> bytes:+ return self.reference.to_bytes()diff --git a/marimo/_save/stubs/module_stub.py b/marimo/_save/stubs/module_stub.pyindex 6d8641a5ef..caa04e34d0 100644--- a/marimo/_save/stubs/module_stub.py+++ b/marimo/_save/stubs/module_stub.py@@ -10,8 +10,9 @@ __all__ = ["ModuleStub"]class ModuleStub:"""Stub for module objects, storing only the module name."""- def __init__(self, module: Any) -> None:+ def __init__(self, module: Any, hash: str = "") -> None: # noqa: A002self.name = module.__name__+ self.hash = hashdef load(self) -> Any:"""Reload the module by name."""diff --git a/marimo/_smoke_tests/cache_lazy_benchmark.py b/marimo/_smoke_tests/cache_lazy_benchmark.pynew file mode 100644index 0000000000..34048e257a--- /dev/null+++ b/marimo/_smoke_tests/cache_lazy_benchmark.py@@ -0,0 +1,68 @@+import marimo++__generated_with = "0.15.5"+app = marimo.App(width="medium")+++def _():+ import marimo as mo++ return (mo,)+++def _():+ import os+ import time++ import numpy as np++ # Warm up numpy random so neither benchmark pays init cost+ np.random.rand(1)++ # Default small for CI smoke tests; override for real benchmarks:+ # MARIMO_BENCH_ARRAY_SIZE=125000000 python cache_lazy_benchmark.py+ ARRAY_SIZE = int(os.environ.get("MARIMO_BENCH_ARRAY_SIZE", "100000"))+ return ARRAY_SIZE, np, time+++def _(ARRAY_SIZE, mo, np, time):+ _start = time.perf_counter()+ with mo.persistent_cache(name="bench_pickle", method="pickle"):+ pickle_a = np.random.rand(ARRAY_SIZE)+ pickle_b = np.random.rand(ARRAY_SIZE)+ pickle_c = np.random.rand(ARRAY_SIZE)+ pickle_d = np.random.rand(ARRAY_SIZE)+ pickle_e = np.random.rand(ARRAY_SIZE)+ pickle_time = time.perf_counter() - _start++ print(f"PickleLoader (5 x {ARRAY_SIZE} numpy): {pickle_time * 1000:.1f}ms")+ return (pickle_time,)+++def _(ARRAY_SIZE, mo, np, time):+ _start = time.perf_counter()+ with mo.persistent_cache(name="bench_lazy", method="lazy"):+ lazy_a = np.random.rand(ARRAY_SIZE)+ lazy_b = np.random.rand(ARRAY_SIZE)+ lazy_c = np.random.rand(ARRAY_SIZE)+ lazy_d = np.random.rand(ARRAY_SIZE)+ lazy_e = np.random.rand(ARRAY_SIZE)+ lazy_time = time.perf_counter() - _start++ print(f"LazyLoader (5 x {ARRAY_SIZE} numpy): {lazy_time * 1000:.1f}ms")+ return (lazy_time,)+++def _(ARRAY_SIZE, lazy_time, pickle_time):+ print(f"\nArray size: {ARRAY_SIZE} ({ARRAY_SIZE * 8 / 1e6:.1f}MB each)")+ print(f"Pickle: {pickle_time * 1000:.1f}ms | Lazy: {lazy_time * 1000:.1f}ms")+ return+++if __name__ == "__main__":+ app.run()diff --git a/tests/_save/loaders/test_loader.py b/tests/_save/loaders/test_loader.pyindex b216d26939..7b2f8caf1c 100644--- a/tests/_save/loaders/test_loader.py+++ b/tests/_save/loaders/test_loader.py@@ -7,17 +7,29 @@ import tempfilefrom abc import ABC, abstractmethodfrom pathlib import Path+import msgspecimport pytest-from marimo._save.cache import Cache+from marimo._save.cache import MARIMO_CACHE_VERSION, Cachefrom marimo._save.hash import HashKey-from marimo._save.loaders import JsonLoader, MemoryLoader, PickleLoader+from marimo._save.loaders import (+ JsonLoader,+ LazyLoader,+ MemoryLoader,+ PickleLoader,+)from marimo._save.loaders.loader import (BasePersistenceLoader,Loader,LoaderPartial,)from marimo._save.stores.file import FileStore+from marimo._save.stubs.lazy_stub import (+ Cache as CacheSchema,+ CacheType,+ Item,+ Meta,+)from tests._save.loaders.mocks import MockLoader@@ -188,3 +200,90 @@ class TestPickleLoader(ABCTestLoader):)self.store.put(str(cache_path), pickle.dumps(cache))+++class TestLazyLoader(ABCTestLoader):+ suffix = "jsonl"++ def _instance(self) -> Loader:+ return LazyLoader("test", store=self.store)++ def teardown_method(self) -> None:+ if self.value and hasattr(self.value, "flush"):+ self.value.flush()+ super().teardown_method()++ def seed_cache(self) -> None:+ loader = self.instance()+ cache_path = loader.build_path(key("hash1", "Pure"))+ base = Path("test") / "hash1"++ # Write the pickle blob for var1+ var_ref = (base / "var1.pickle").as_posix()+ self.store.put(var_ref, pickle.dumps("value1"))++ # Write the manifest+ manifest = msgspec.json.encode(+ CacheSchema(+ hash="hash1",+ cache_type=CacheType("Pure"),+ defs={"var1": Item(reference=var_ref)},+ stateful_refs=[],+ meta=Meta(version=MARIMO_CACHE_VERSION),+ )+ )+ self.store.put(str(cache_path), manifest)++ def test_round_trip(self) -> None:+ """Test save_cache -> flush -> load_cache round-trip."""+ loader = self.instance()++ cache = Cache(+ defs={"x": 42, "y": "hello", "z": [1, 2, 3]},+ hash="round_trip_hash",+ cache_type="Pure",+ stateful_refs=set(),+ hit=False,+ meta={"version": MARIMO_CACHE_VERSION},+ )+ assert loader.save_cache(cache)+ loader.flush()++ loaded = loader.load_cache(key("round_trip_hash", "Pure"))+ assert loaded is not None+ assert loaded.hash == "round_trip_hash"+ assert loaded.defs["x"] == 42+ assert loaded.defs["y"] == "hello"+ assert loaded.defs["z"] == [1, 2, 3]++ def test_corrupt_cache_returns_none(self) -> None:+ """Corrupt manifest triggers cache miss, not crash."""+ loader = self.instance()+ cache_path = loader.build_path(key("bad", "Pure"))+ self.store.put(str(cache_path), b"not valid json")++ result = loader.load_cache(key("bad", "Pure"))+ assert result is None++ def test_missing_blob_returns_none(self) -> None:+ """Missing pickle blob triggers cache miss."""+ loader = self.instance()+ cache_path = loader.build_path(key("missing", "Pure"))+ base = Path("test") / "missing"++ # Manifest references a blob that doesn't exist+ manifest = msgspec.json.encode(+ CacheSchema(+ hash="missing",+ cache_type=CacheType("Pure"),+ defs={+ "var1": Item(reference=(base / "var1.pickle").as_posix())+ },+ stateful_refs=[],+ meta=Meta(version=MARIMO_CACHE_VERSION),+ )+ )+ self.store.put(str(cache_path), manifest)++ result = loader.load_cache(key("missing", "Pure"))+ assert result is None