fix: create the routing cache per router instance so apps can be garbage collected#4930
Merged
provinzkraut merged 2 commits intoJul 15, 2026
Conversation
5715259 to
9efe83d
Compare
ASGIRouter.handle_routing was decorated with a class-level lru_cache, which acts as a garbage collection root: every router instance (and, through it, every Litestar app with all of its state) stayed strongly referenced by the cache forever, so apps were never garbage collected. Long-running processes that create many app instances (e.g. test suites) accumulated them all. Bind the cache per instance in __init__ instead (self.handle_routing = lru_cache(1024)(self._handle_routing)). The cache then only participates in a self-referential cycle that the garbage collector can reclaim once the app is no longer referenced. The call surface is unchanged, including cache_clear()/cache_info() on the bound cache. Fixes litestar-org#4876
9efe83d to
7e64206
Compare
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #4930 +/- ##
=======================================
Coverage ? 67.30%
=======================================
Files ? 293
Lines ? 15230
Branches ? 1728
=======================================
Hits ? 10251
Misses ? 4832
Partials ? 147 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
provinzkraut
approved these changes
Jul 15, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
ASGIRouter.handle_routingwas decorated with a class-level@lru_cache(1024). A class-level cache is a garbage-collection root: every router instance — and, throughrouter.app, everyLitestarapp with all of its state — stayed strongly referenced by the cache forever. Long-running processes that create many app instances (most notably test suites) accumulated every app ever created, as reported with a gc-based MCVE in the issue.This PR binds the cache per instance in
__init__:The cache then only participates in a self-referential cycle (
router → cache → bound method → router) that the garbage collector reclaims once the app is no longer externally referenced. Details:self.handle_routing(path=..., method=...)works as before, andcache_clear()/cache_info()remain available on the per-instance bound cache (the workaround from the issue keeps working).handle_routingis added to__slots__; the uncached implementation lives on as_handle_routing.lru_cachewrapper as before.Verified with the issue's MCVE: on
main, oneLitestarinstance survivesdel app; gc.collect(); with this change, zero survive. Addedtest_routing_cache_does_not_prevent_garbage_collection, which fails onmainand passes here; the fulltests/unit/test_asgi/test_asgi_router.pysuite passes (14 passed).Disclosure per the contribution guidelines: this fix was developed with AI assistance (Claude Code), with the leak and fix verified locally as described above.
Closes
Closes #4876
📚 Documentation preview 📚: https://litestar-org.github.io/litestar-docs-preview/4930