memory: bound cache admission and eviction - #2
Open
ravi-pplx wants to merge 1 commit into
Open
Conversation
ravi-pplx
marked this pull request as ready for review
August 31, 2026 20:37
ravi-pplx
force-pushed
the
ravi/bound-cachew-memory-eviction
branch
from
September 1, 2026 04:38
2aa97c3 to
5a43c73
Compare
Replace the process-wide quadratic eviction path with sharded, fixed-work CLOCK admission. Revalidate planned victims with hit generations so competing planners cannot erase a recent reference. Account retained entries, incomplete writers, and reader-pinned generations against one configured ceiling. Grow writer buffers lazily and reserve only net capacity so declared lengths cannot allocate memory before body data and streaming chunk boundaries do not change admission. Reject invalid limit conversions and stop cancelled eviction plans before committing victims. Decline only the optional memory copy when bounded admission cannot obtain capacity, preserving authoritative-tier and client delivery. Cover replacement, cancellation, concurrent admission, tier fallback, accounting transitions, shutdown, and writer growth. Add cardinality and configured-path benchmarks that distinguish successful admissions from bounded declines. Verification: bin/just fmt; bin/just lint; bin/just test.
ravi-pplx
force-pushed
the
ravi/bound-cachew-memory-eviction
branch
from
September 1, 2026 05:12
5a43c73 to
cb06519
Compare
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.
Problem
The old memory tier evicted at capacity by collecting and selection-sorting
every cached object while holding one process-wide write lock. Admission cost
grew quadratically with cache cardinality, so a miss burst could block unrelated
hits. Incomplete writers and reader-pinned generations also did not share one
enforceable memory budget.
Change
reader-pinned generations against one ceiling.
trigger its declared allocation.
of write chunk boundaries.
them as unlimited.
room. Authoritative-tier writes and client delivery continue.
Capacity semantics
limit-mbbounds Cachew's accounted memory, not process RSS. Accounted memoryincludes retained buffers, estimated entry metadata, and retired buffers still
pinned by readers. Go runtime and allocator overhead remain outside this value.
inflight-limit-mbdefaults to zero for compatibility. When positive, it is asub-limit inside
limit-mb, not extra capacity. Withlimit-mb = 32768andinflight-limit-mb = 1024, retained data is trimmed toward 31 GiB and retainedplus incomplete-writer accounting cannot exceed 32 GiB. Publishing transfers
the writer reservation to retained accounting without a double charge.
Growing a writer transfers its reservation from the old capacity to the new
capacity before copying. The allocator can briefly retain both buffers, so RSS
may transiently exceed accounted memory by at most the old buffer capacity. For
the production 1 GiB inflight sub-limit, that overage is bounded within the
existing process-memory headroom.
Before and after
Measured on an Apple M4 Max (
darwin/arm64). The comparison runs the samepublic
Create+ 16 KiBWrite+Closebenchmark against pre-PR commit410ebdfand final headcb06519; values are medians of three one-second runs.The old path grows quadratically with entry count. The replacement stays near
3.5 us/op and near 19 KiB allocated per configured write across this range.
Final-head cardinality checks:
Create+Write+CloseParallel hot hits remain approximately 0.27 us/op with six allocations per
operation. Saturated parallel admission completes in approximately 0.50 us per
attempt and accepts 56.4% of optional memory copies; bounded declines do not
shed client requests.
Correctness coverage
delete, reader-pinned retirement, and shutdown.
tier.