Scale the tablebase cache to ~100k entries (#24)

* 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
This commit is contained in:
2026-11-02 23:02:01 +01:00
committed by GitHub
parent fa71783e55
commit a5bb1cb670
16 changed files with 695 additions and 120 deletions
+70
View File
@@ -0,0 +1,70 @@
defmodule Chesstrainer.Cache.BackupSchedule do
@moduledoc """
Daily off-peak schedule for cache backups.
The cache backs up once a day at a configurable UTC time (03:00 by default).
The delay is computed from the wall clock, so restarts and clock drift do not
shift the run towards peak hours the way a fixed interval from boot would.
This module only computes the schedule; writing the backup is
`Chesstrainer.Cache.Persist.backup/1`.
"""
@default_time {3, 0}
@doc """
Parses a backup time given as `{hour, minute}` or an `"HH:MM"` string.
"""
def parse_time({hour, minute}) when hour in 0..23 and minute in 0..59,
do: {:ok, {hour, minute}}
def parse_time(value) when is_binary(value) do
with [hour, minute] <- String.split(value, ":"),
{hour, ""} <- Integer.parse(hour),
{minute, ""} <- Integer.parse(minute),
true <- hour in 0..23 and minute in 0..59 do
{:ok, {hour, minute}}
else
_ -> :error
end
end
def parse_time(_value), do: :error
@doc """
Normalises a backup time, falling back to #{inspect(@default_time)} UTC when
no time is configured.
"""
def time!(nil), do: @default_time
def time!(value) do
case parse_time(value) do
{:ok, time} ->
time
:error ->
raise ArgumentError, "invalid cache backup time: #{inspect(value)}"
end
end
@doc """
Milliseconds from `now` until the next occurrence of `time`, in UTC.
When `now` is exactly the scheduled time the next run is a full day away, so
a run always re-arms the following day rather than firing twice.
"""
def next_delay(time, now \\ DateTime.utc_now()) do
{hour, minute} = time!(time)
today = DateTime.new!(DateTime.to_date(now), Time.new!(hour, minute, 0))
next_run =
if DateTime.compare(today, now) == :gt do
today
else
DateTime.add(today, 1, :day)
end
DateTime.diff(next_run, now, :millisecond)
end
end
+63 -29
View File
@@ -1,44 +1,78 @@
defmodule Chesstrainer.Cache.Evict do
@moduledoc """
Eviction for the LFU cache.
Eviction is deliberately approximate. Folding over the whole table to find the
exact least-frequently-used entry costs O(n) on every put once the cache is at
capacity, which stops the cache scaling past ~100k entries. Instead each pass
samples a bounded number of entries and evicts the coldest of those: a cache
that re-fetches on a miss only needs "a cold entry", not the coldest one.
The sample walks the table through an `:ets.select/3` continuation, so
successive passes look at different slices instead of rescanning the same
first few entries. Over many puts every entry gets a turn to be considered,
while each pass still costs the same bounded amount.
"""
@sample_size 64
@match_spec [{{:"$1", :_, :"$2", :"$3"}, [], [{{:"$1", :"$2", :"$3"}}]}]
@typedoc """
Position in the table's select traversal.
`:start` begins a new pass; any other value resumes the pass where the
previous eviction left off.
"""
@type cursor :: :start | term()
@doc """
Evicts least-frequently-used entries until `table` holds at most `max_size`
rows. Ties in frequency are broken by least recent use (`last_access`).
"""
def evict(table, max_size) do
if :ets.info(table, :size) > max_size do
case find_least_used_entry(table) do
{key, _frequency, _last_access} ->
:ets.delete(table, key)
evict(table, max_size)
Evicts entries until `table` holds at most `max_size` rows, returning the
cursor to pass to the next call.
nil ->
:ok
Each pass samples at most #{@sample_size} entries and deletes the least
frequently used one of them, then resumes from the advanced cursor. Ties in
frequency are broken by least recent use (`last_access`).
"""
@spec evict(:ets.table(), non_neg_integer(), cursor()) :: cursor()
def evict(table, max_size, cursor \\ :start) do
if :ets.info(table, :size) > max_size do
case sample(table, cursor) do
{[], :start} ->
# End of the table: wrap and keep evicting. If we were already at the
# start there is nothing left to sample (an empty table), so stop.
if cursor == :start, do: :start, else: evict(table, max_size, :start)
{entries, next} ->
{key, _frequency, _last_access} =
Enum.min_by(entries, fn {_key, frequency, last_access} ->
{frequency, last_access}
end)
:ets.delete(table, key)
evict(table, max_size, next)
end
else
:ok
cursor
end
end
defp find_least_used_entry(table) do
:ets.foldl(
fn {k, _v, frequency, last_access}, acc ->
case acc do
nil ->
{k, frequency, last_access}
defp sample(table, :start) do
case :ets.select(table, @match_spec, @sample_size) do
{entries, continuation} -> {entries, continuation}
:"$end_of_table" -> {[], :start}
end
end
{_k, best_frequency, best_access}
when {frequency, last_access} < {best_frequency, best_access} ->
{k, frequency, last_access}
_ ->
acc
end
end,
nil,
table
)
defp sample(table, cursor) do
case :ets.select(cursor) do
{entries, next} -> {entries, next}
:"$end_of_table" -> {[], :start}
end
rescue
# A continuation is only valid for the table instance that produced it.
# A deleted and recreated table, or a restore, invalidates it, so restart
# the rotation instead of crashing the cache.
ArgumentError -> sample(table, :start)
end
end
+54 -7
View File
@@ -1,25 +1,38 @@
defmodule Chesstrainer.Cache.Persist do
@moduledoc """
Persistence for the cache. Backup and restore functions.
A backup is written to a temporary DETS file in the same directory and then
atomically renamed into place. A crash during the write therefore leaves the
previous backup untouched instead of a truncated file that fails to restore.
"""
@backup_path "priv/static/backups"
@format_version "v2"
@doc """
Writes the `table` to its backup file. Returns `:ok` or `{:error, reason}`.
"""
def backup(table) do
File.mkdir_p!(@backup_path)
name = backup_filename(table) |> String.to_charlist()
{:ok, dets_table} = :dets.open_file(name, type: :set)
:ets.to_dets(table, dets_table)
:dets.sync(dets_table)
:dets.close(dets_table)
path = backup_path(table)
:global.trans(
{__MODULE__, table},
fn -> write(table, path <> ".tmp", path) end,
[node()],
:infinity
)
end
@doc """
Restores the backup file for `table`, if a readable one exists.
"""
def restore(table) do
File.mkdir_p!(@backup_path)
drop_legacy_backup(table)
path = backup_filename(table)
path = backup_path(table)
if File.exists?(path) do
name = String.to_charlist(path)
@@ -49,7 +62,41 @@ defmodule Chesstrainer.Cache.Persist do
:ok
end
defp backup_filename(table), do: Path.join(@backup_path, "#{table}.#{@format_version}.det")
@doc """
The path of the backup file for `table`.
"""
def backup_path(table), do: Path.join(@backup_path, "#{table}.#{@format_version}.det")
defp write(table, temp, path) do
# Remove a stale temporary file left by an earlier crash; if the path is
# unusable the open below fails and the existing backup stays in place.
_ = File.rm(temp)
result =
with {:ok, dets_table} <- :dets.open_file(String.to_charlist(temp), type: :set) do
try do
_ = :ets.to_dets(table, dets_table)
:dets.sync(dets_table)
after
:dets.close(dets_table)
end
end
case result do
:ok ->
case File.rename(temp, path) do
:ok ->
:ok
{:error, reason} ->
_ = File.rm(temp)
{:error, reason}
end
{:error, reason} ->
{:error, reason}
end
end
defp drop_legacy_backup(table) do
legacy = Path.join(@backup_path, "#{table}.det")