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
+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