Add async cache support

[jschfflr]

📝 Summary

Adds full async/await support to marimo's cache decorators (mo.cache, mo.lru_cache, mo.persistent_cache) with automatic task
deduplication to prevent race conditions and duplicate work.

🔍 Description of Changes

What's New

All marimo cache decorators now work seamlessly with both synchronous and asynchronous functions:

@mo.cache
async def fetch_data(url: str, params: dict) -> dict:
    response = await http_client.get(url, params=params)
    return response.json()

@mo.persistent_cache
async def compute_embedding(data: str, model: str) -> np.ndarray:
    response = await llm_client.get_embeddings(data, model)
    return response.embeddings

Key Features

Task Deduplication: When multiple concurrent calls are made to a cached async function with the same arguments, only one execution occurs—the rest await the result. This prevents race conditions and duplicate work.

# All 5 calls execute concurrently, but only one actually runs the function
results = await asyncio.gather(
    expensive_async_compute(42),
    expensive_async_compute(42),
    expensive_async_compute(42),
    expensive_async_compute(42),
    expensive_async_compute(42),
)
# All results are identical, but the function only executed once

Implementation Details

Commit 1: Refactoring (cf47fb0)

• Extracted helper methods _prepare_call_execution() and _finalize_cache_update() from the sync cache implementation
• No functional changes, just preparation for async support

Commit 2: Async Support (e250061)

• Changed to use type(self) instead of _cache_call() in get() for proper subclass dispatch
• Created _cache_call_async subclass that inherits from _cache_call
• Implemented task deduplication using a class-level WeakKeyDictionary to track pending executions per cache instance
• Used WeakKeyDictionary to prevent memory leaks and allow garbage collection of unused cache instances
• Added threading lock to protect shared data structures during concurrent access
• Added 15 comprehensive async cache tests (100% coverage of new code paths)

Commit 3: Documentation (52b6e2c).

• Updated docs/api/caching.md with async examples in tab format
• Added note about async support and task deduplication behavior
• Updated comparison table with functools.cache

Technical Decisions

1. WeakKeyDictionary for instance tracking: Prevents memory leaks by allowing garbage collection of unused cache instances.
2. Strong references for Task objects: While cache instances use weak references, the pending Task objects must be strong references to
   keep them alive while being awaited.
3. Async-only task deduplication: Following the pattern from the async-lru library, only the async variant implements task deduplication
   since sync code doesn't have concurrent execution issues.
4. Deadlock prevention: The lock is released before awaiting existing tasks to prevent deadlocks.

Testing

All existing tests continue to pass (100 sync cache tests), plus 15 new async cache tests covering:

• Basic async caching
• Task deduplication with concurrent calls
• Cache invalidation with different arguments
• Persistent cache with async functions
• LRU cache with async functions
• Error handling and edge cases

📋 Checklist

• I have read the contributor guidelines.
• For large changes, or changes that affect the public API: this change was discussed or approved through an issue, on Discord, or the community discussions (Please provide a link if applicable).
• I have added tests for the changes made.
• I have run the code and verified that it works as expected.

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[vercel]

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

Project	Deployment	Preview	Comments	Updated (UTC)
marimo-docs	Ready	Preview	Comment	Oct 10, 2025 7:13pm

[mscolnick]

super cool! thanks for the PR. we will give this a review this week.

[jschfflr]

I have read the CLA Document and I hereby sign the CLA

[dmadisetti]

Comments are non-blocking. This looks great! Thanks!

[dmadisetti]

Suggested change

	return attempt.meta["return"]
	return attempt.meta.get("return")

[dmadisetti]

🥳

[mscolnick]

don't worry about the failing playwright tests (that is now fixed on main)

[jschfflr]

Thanks for the quick merge!