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
+4 -1
View File
@@ -7,6 +7,8 @@ defmodule Chesstrainer.Application do
@impl true
def start(_type, _args) do
cache_opts = Application.get_env(:chesstrainer, Chesstrainer.Cache, [])
children = [
ChesstrainerWeb.Telemetry,
Chesstrainer.Repo,
@@ -17,7 +19,8 @@ defmodule Chesstrainer.Application do
# Start to serve requests, typically the last entry
ChesstrainerWeb.Endpoint,
{Registry, keys: :unique, name: Chesstrainer.CacheRegistry},
{Chesstrainer.Cache, :tablebase}
{Task.Supervisor, name: Chesstrainer.Cache.BackupSupervisor},
{Chesstrainer.Cache, {:tablebase, cache_opts}}
]
# See https://elixir.hexdocs.pm/Supervisor.html
+41 -23
View File
@@ -4,9 +4,14 @@ defmodule Chesstrainer.Cache do
Entries are stored in ETS as `{key, value, frequency, last_access}`. Reads bump
the frequency; when the cache is over its maximum size the least frequently
used entry is evicted (ties broken by least recent use). A weekly sweep halves
every frequency so entries that were used heavily once but have not been used
since eventually age out.
used entry *of a rotating bounded sample* is evicted (ties broken by least
recent use). Eviction is therefore an approximation of the global LFU victim,
which keeps each put cheap at the cost of occasionally dropping an entry that
was not quite the coldest. A weekly sweep halves every frequency so entries
that were used heavily once but have not been used since eventually age out.
A daily backup runs off the cache process at a configurable UTC time, so reads
and writes stay responsive while the snapshot is written.
## Examples
@@ -15,11 +20,15 @@ defmodule Chesstrainer.Cache do
use GenServer
@default_max_size 1000
@default_sweep_interval :timer.hours(24 * 7)
@backup_interval_minutes 60
alias Chesstrainer.Cache.BackupSchedule
alias Chesstrainer.Cache.Persist
def start_link(table), do: start_link(table, [])
@default_max_size 100_000
@default_sweep_interval :timer.hours(24 * 7)
def start_link(table) when is_atom(table), do: start_link(table, [])
def start_link({table, opts}), do: start_link(table, opts)
def start_link(table, opts) when is_list(opts) do
GenServer.start_link(__MODULE__, {table, opts}, name: via_tuple(table))
@@ -28,7 +37,7 @@ defmodule Chesstrainer.Cache do
def put(table, key, value), do: GenServer.call(via_tuple(table), {:put, key, value})
def get(table, key), do: GenServer.call(via_tuple(table), {:get, key})
def delete(table, key), do: GenServer.call(via_tuple(table), {:delete, key})
def backup(table), do: GenServer.call(via_tuple(table), :backup)
def backup(table), do: Persist.backup(table)
def sweep(table), do: GenServer.call(via_tuple(table), :sweep)
def show(table) do
@@ -43,18 +52,21 @@ defmodule Chesstrainer.Cache do
state = %{
table: table,
max_size: Keyword.get(opts, :max_size, @default_max_size),
sweep_interval: Keyword.get(opts, :sweep_interval, @default_sweep_interval)
sweep_interval: Keyword.get(opts, :sweep_interval, @default_sweep_interval),
backup_time: BackupSchedule.time!(Keyword.get(opts, :backup_time)),
backup_fun: Keyword.get(opts, :backup_fun, &Persist.backup/1),
backup_timer: nil,
evict_cursor: :start
}
# Create and restore synchronously so the cache is never observed empty
# between `start_link/1` returning and the restore finishing.
create_table(table)
__MODULE__.Persist.restore(table)
__MODULE__.Evict.evict(table, state.max_size)
:timer.send_interval(:timer.minutes(@backup_interval_minutes), :backup)
Persist.restore(table)
evict_cursor = __MODULE__.Evict.evict(table, state.max_size, state.evict_cursor)
:timer.send_interval(state.sweep_interval, :sweep)
{:ok, state}
{:ok, schedule_backup(%{state | evict_cursor: evict_cursor})}
end
@impl true
@@ -62,8 +74,8 @@ defmodule Chesstrainer.Cache do
ensure_table(state.table)
access = System.system_time(:microsecond)
:ets.insert(state.table, {key, value, 1, access})
__MODULE__.Evict.evict(state.table, state.max_size)
{:reply, :ok, state}
evict_cursor = __MODULE__.Evict.evict(state.table, state.max_size, state.evict_cursor)
{:reply, :ok, %{state | evict_cursor: evict_cursor}}
end
@impl true
@@ -87,12 +99,6 @@ defmodule Chesstrainer.Cache do
{:reply, :ok, state}
end
@impl true
def handle_call(:backup, _from, state) do
__MODULE__.Persist.backup(state.table)
{:reply, :ok, state}
end
@impl true
def handle_call(:sweep, _from, state) do
__MODULE__.Sweep.halve_frequencies(state.table)
@@ -101,8 +107,8 @@ defmodule Chesstrainer.Cache do
@impl true
def handle_info(:backup, state) do
__MODULE__.Persist.backup(state.table)
{:noreply, state}
run_backup(state)
{:noreply, schedule_backup(state)}
end
@impl true
@@ -111,6 +117,18 @@ defmodule Chesstrainer.Cache do
{:noreply, state}
end
defp run_backup(state) do
table = state.table
backup_fun = state.backup_fun
Task.Supervisor.start_child(Chesstrainer.Cache.BackupSupervisor, fn -> backup_fun.(table) end)
end
defp schedule_backup(state) do
timer = Process.send_after(self(), :backup, BackupSchedule.next_delay(state.backup_time))
%{state | backup_timer: timer}
end
defp via_tuple(table), do: {:via, Registry, {Chesstrainer.CacheRegistry, table}}
defp ensure_table(table) do
+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")
+5 -6
View File
@@ -1,6 +1,11 @@
defmodule Chesstrainer.Endgames.Tablebase do
@moduledoc """
All endgame tablebase related functions.
The cached value carries only what the trainer reads: `category`,
`checkmate`, and `moves` drive play, while `dtm`/`dtc` are small distance
hedges. Cursed-win/blessed-loss are normalised to `:draw` at parse time, so
the raw `dtw`/`dtz`/`insufficient_material` fields are not kept here.
"""
alias Chesstrainer.Endgames.Tablebase
@@ -12,9 +17,6 @@ defmodule Chesstrainer.Endgames.Tablebase do
checkmate: boolean(),
dtc: integer() | nil,
dtm: integer() | nil,
dtw: integer() | nil,
dtz: integer() | nil,
insufficient_material: boolean(),
moves: [Tablebase.Move.t()]
}
@@ -22,9 +24,6 @@ defmodule Chesstrainer.Endgames.Tablebase do
checkmate: false,
dtc: nil,
dtm: nil,
dtw: nil,
dtz: nil,
insufficient_material: false,
moves: nil
@doc """
+7 -20
View File
@@ -1,41 +1,28 @@
defmodule Chesstrainer.Endgames.Tablebase.Move do
@moduledoc """
Moves struct for the tablebase
Carries only the fields the trainer reads: `category` and `dtz` for grading,
`san`/`uci` for display and matching, and `dtm`/`dtc` as small distance
hedges. Terminal detection is structural (the next position's `checkmate` or
its empty `moves`), so no per-move terminal flags are kept.
"""
@type result :: :win | :draw | :loss | :unknown
@type t :: %__MODULE__{
category: result,
checkmate: boolean(),
conversion: boolean(),
dtc: integer() | nil,
dtm: integer() | nil,
dtw: integer() | nil,
dtz: integer() | nil,
precise_dtz: integer() | nil,
san: String.t() | nil,
stalemate: boolean(),
uci: String.t() | nil,
variant_loss: boolean(),
variant_win: boolean(),
zeroing: boolean(),
insufficient_material: boolean()
uci: String.t() | nil
}
defstruct category: nil,
checkmate: false,
conversion: false,
dtc: nil,
dtm: nil,
dtw: nil,
dtz: nil,
precise_dtz: nil,
san: nil,
stalemate: false,
uci: nil,
variant_loss: false,
variant_win: false,
zeroing: false,
insufficient_material: false
uci: nil
end
+1 -13
View File
@@ -45,9 +45,6 @@ defmodule Chesstrainer.Endgames.Tablebase.Parser do
checkmate: map["checkmate"],
dtc: map["dtc"],
dtm: map["dtm"],
dtw: map["dtw"],
dtz: map["dtz"],
insufficient_material: map["insufficient_material"],
moves: Enum.map(map["moves"], &moves_from_map/1)
}}
end
@@ -55,20 +52,11 @@ defmodule Chesstrainer.Endgames.Tablebase.Parser do
defp moves_from_map(map) do
%Tablebase.Move{
category: Tablebase.normalize_category(map["category"]),
checkmate: map["checkmate"],
conversion: map["conversion"],
dtc: map["dtc"],
dtm: map["dtm"],
dtw: map["dtw"],
dtz: map["dtz"],
insufficient_material: map["insufficient_material"],
precise_dtz: map["precise_dtz"],
san: map["san"],
stalemate: map["stalemate"],
uci: map["uci"],
variant_loss: map["variant_loss"],
variant_win: map["variant_win"],
zeroing: map["zeroing"]
uci: map["uci"]
}
end