perf: mechanism for parallel read/write in mo.persistent_cache

[dmadisetti]

📝 Summary

In response to reported performance issues in mo.persistent_cache, this PR examines disk serialization in a non-blocking way. The associated smoke_test writes 1GB of memory to disk utilizing the existing PickleStore and the new LazyStore, which avoids rewrites of existing values and has non-blocking deserialization.

┌─────────────────────────┬─────────────┬────────────┬──────────┐
│                         │ pypi Pickle │ Our Pickle │ Our Lazy │
├─────────────────────────┼─────────────┼────────────┼──────────┤
│ Miss (run 1)            │ 2489ms      │ 2443ms     │ 1473ms   │
├─────────────────────────┼─────────────┼────────────┼──────────┤
│ Hit (steady, runs 3-10) │ ~740ms      │ ~645ms     │ ~330ms   │
└─────────────────────────┴─────────────┴────────────┴──────────┘

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
marimo-docs	Ready	Preview, Comment	Mar 25, 2026 9:41pm

[Copilot]

Pull request overview

This PR introduces a new persistent cache loader (method="lazy") intended to improve mo.persistent_cache performance by parallelizing disk read/write and storing a lightweight manifest for cached values.

Changes:

• Added LazyLoader (manifest-based persistence + parallel blob loading/writing) and registered it under persistent loader keys.
• Introduced msgspec schemas and stubs (lazy_stub.py) to represent cached items and deferred references.
• Adjusted cache/stub behavior (UIElement handling in cache update, FunctionStub metadata/linecache behavior, ModuleStub metadata).

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 15 comments.

Show a summary per file

File	Description
marimo/_save/loaders/lazy.py	Adds the new LazyLoader implementation and manifest/blob IO behavior.
marimo/_save/loaders/init.py	Registers "lazy" as a supported persistent loader key.
marimo/_save/stubs/lazy_stub.py	Adds msgspec schemas and a reference stub for lazy cache restoration.
marimo/_save/stubs/init.py	Exposes ReferenceStub and adds LAZY_STUB_LOOKUP mapping.
marimo/_save/stubs/function_stub.py	Captures filename/lineno metadata and primes linecache for better tracebacks.
marimo/_save/stubs/module_stub.py	Extends ModuleStub to carry a hash field.
marimo/_save/cache.py	Updates restore/update behavior (notably UIElement storage and ReferenceStub restoration).
marimo/_save/save.py	Makes cached-return lookup more defensive (meta.get("return")).
marimo/_smoke_tests/cache_lazy_benchmark.py	Adds a benchmark notebook for comparing pickle vs lazy persistence.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

🚀 Development release published. You may be able to view the changes at https://marimo.app?v=0.21.2-dev61