Budgeted cache generator (queue refill)¶
Scope of this diagram. This chart covers the background loop that keeps each region's location cache warm: the periodic SelectionAPI.compute() pulse, the region-by-region budget enforcement (queueLen / maxBiasedAttempts), the hand-off to LocationGenerator, and the insertion of successful results into the cache that diagram 01 pops from. Under ADR-110 (purpose-gated live loads), background cache refill runs strictly under LoadPurpose.SPECULATIVE: it reads resident cache and Anvil region files off-tick (getChunkIfReadable), acquires pins via LiveLoadGate up to activeChunkCap on disk misses, and defers candidate attempts when HeapPressureMonitor signals memory pressure, ensuring speculative refills never steal native load permits or induce tick starvation.
Related-but-separate behavior paths are intentionally out of scope here:
- What happens inside one candidate attempt — see diagram 08 (location selection per attempt); SpawnWorker in this chart expands into that flowchart.
- How a waiting /rtp consumes the cache — see diagram 01 (QueryCache / QueueWait).
- Chunk ticket book-keeping — see diagram 03; every generated candidate reserves a ticket via ChunkReservation.
- Purpose-gated live loads and on-demand chunk resolution — see diagram 15.
Companion walkthrough:
CODE_TOUR.mdsection 3 — Budgeted cache generator.
stateDiagram-v2
PulseTrigger : selectionAPI.compute() [Async]
[*] --> PulseTrigger
%% 1. Define State Containers (Strict Parser Syntax)
state Budgeted_Task_Pipeline {
InitBudget : Initialize Execution Budget
CheckBudget : Budget Remaining? (Time or Count)
CheckPeriod : Is Region Due? (Based on 'period')
ExecuteRegion : region.execute() [Platform Scheduler]
YieldTask : Yield to next tick/pulse
}
state Cache_Refill_State {
SpawnWorker : Spawn Async LocationSearchWorker (LoadPurpose.SPECULATIVE)
GateCheck : LiveLoadGate & HeapPressureMonitor (ADR-110)
PushQueue : Add Valid Location to Cache (keptLocations)
WakePlayer : Un-stall Public Queue
}
%% 2. Map Transitions
PulseTrigger --> InitBudget
%% Budget Loop
InitBudget --> CheckBudget
CheckBudget --> CheckPeriod : Yes (Budget Available)
%% Period Rotation Gating
CheckPeriod --> ExecuteRegion : Turn Reached (Execute)
CheckPeriod --> CheckBudget : Not Due (Skip to Next Region)
ExecuteRegion --> CheckBudget : Loop Next Region
CheckBudget --> YieldTask : No (Budget Exhausted)
%% Fulfillment Branch
ExecuteRegion --> SpawnWorker : Region Needs Locations
SpawnWorker --> GateCheck : Read-Only First / Pin Bounding
GateCheck --> PushQueue : Candidate Verified Safe
GateCheck --> CheckBudget : Deferred (Heap / Pin Cap)
PushQueue --> WakePlayer : (If players waiting)
%% Terminations
WakePlayer --> [*]
YieldTask --> [*]
%% Color legend: green = cache successfully grew / consumer woken, blue = async worker / scheduler pulse, yellow = cache touchpoint, grey = yield
classDef success fill:#b7e4b7,stroke:#1f6b1f,stroke-width:2px,color:#0b2a0b;
classDef async fill:#cfe2ff,stroke:#1f4e8a,color:#0b1f3a;
classDef data fill:#fff2b3,stroke:#8a6d1f,color:#3a2f0b;
classDef cleanup fill:#e2e2e2,stroke:#555555,color:#111111;
class PushQueue,WakePlayer success
class PulseTrigger,SpawnWorker,ExecuteRegion async
class InitBudget,CheckBudget,CheckPeriod,GateCheck data
class YieldTask cleanup
Architectural Notes & Invariants¶
- Speculative load purpose (
LoadPurpose.SPECULATIVE): Background cache refill workers never initiate unconstrained native chunk loads. Candidates evaluate read-only against resident memory or region files (RTPWorld.getChunkIfReadable). - Admission bounds (
LiveLoadGate): When candidate terrain is missing from disk,LiveLoadGate.tryAcquirePin()permits live generation only if active pinned chunks remain underactiveChunkCap. Unpinned cold generation populatesunkeptLocationswithout holding active tickets. - Heap backpressure (
HeapPressureMonitor): When JVM heap usage exceedsmaxHeapPercent, speculative attempts defer (completeDeferred) immediately, shedding background load to protect active server workloads. - Fair queue wake-up: Adding a verified location to
keptLocationsunblocks the public queue (QueueWaitin diagram 01) immediately, minimizing waiting disutility for pending players.
Related documentation:
- Teleport execution pipeline: docs/architecture/01-teleport-execution-pipeline.md.
- Candidate selection per attempt: docs/architecture/08-location-selection-per-attempt.md.
- Cost-governed chunk resolution and native admission: docs/architecture/15-cost-governed-chunk-reads-and-native-admission.md.
- Governing ADRs: leafrtp-ADR-004, leafrtp-ADR-011, anvil-api-ADR-001, leafrtp-ADR-059, leafrtp-ADR-068, leafrtp-ADR-085.