mirror of
https://github.com/TheRealOwenRees/chess-endgame-trainer.git
synced 2026-11-18 11:42:07 +00:00
* Slim the cached tablebase value to the fields the trainer reads (#20) * Sample for LFU eviction instead of scanning the cache (#21) * Make cache size configurable and back up daily off-peak (#22) * Document the cache design in the glossary and an ADR (#23) * Address cache-scaling code review findings
28 lines
1.9 KiB
Markdown
28 lines
1.9 KiB
Markdown
# Cache only the graded tablebase outcome, at ~100k entries with sampled eviction and daily best-effort backups
|
|
|
|
The cached value keeps only what the trainer reads: the position's category,
|
|
checkmate flag and moves (each with category, `dtz`, `san` and `uci`), plus
|
|
`dtm`/`dtc` as a small, deliberate hedge for a future "mate in N" or
|
|
distance-to-conversion feature. The rest of the API response — `dtw`, precise
|
|
DTZ, per-move terminal and variant flags, material flags — is dropped: it is
|
|
never read, and slimming each entry from ~10 KB to ~4 KB keeps the working set
|
|
in memory. Cursed-win and blessed-loss are normalised to a draw at parse time,
|
|
so the variant and `dtw` fields mean nothing here. The cost is that a richer
|
|
trainer would need a cache shape (and DETS format) change and a refill;
|
|
`dtm`/`dtc` keep the most likely such feature cheap.
|
|
|
|
The cache holds 100k entries by default and is configurable. At ~4 KB per entry
|
|
that is roughly 400 MB of BEAM memory per node — accepted because the cache is a
|
|
warm, per-node optimization rather than the source of truth, and the cap is
|
|
configurable for smaller deployments. That is large enough that the recurring
|
|
working set rarely evicts, and at capacity eviction samples ~64 entries and
|
|
drops the least-frequently-used of those rather than scanning the whole table
|
|
for the exact victim: a cache that re-fetches on a miss only needs *a* cold
|
|
entry, and the O(n) scan per put was what stopped the cache scaling past ~100k.
|
|
The weekly frequency-halving sweep stays, because it is time-based aging rather
|
|
than victim selection. The cache is warm state — the
|
|
API is the source of truth — so a daily backup at 03:00 UTC, written off the
|
|
cache process to a temporary file and atomically renamed, is the right
|
|
durability level: a crash can lose up to a day of cache, costing rate-limited
|
|
re-fetches rather than data, and a torn write can never replace a good backup.
|