Files
chess-endgame-trainer/lib/chesstrainer/cache.ex
T
owenrees a5bb1cb670 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
2026-11-02 23:02:01 +01:00

147 lines
4.5 KiB
Elixir

defmodule Chesstrainer.Cache do
@moduledoc """
Generic LFU cache with a periodic frequency-decay sweep.
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 *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
iex> start_link(:tablebase)
"""
use GenServer
alias Chesstrainer.Cache.BackupSchedule
alias Chesstrainer.Cache.Persist
@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))
end
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: Persist.backup(table)
def sweep(table), do: GenServer.call(via_tuple(table), :sweep)
def show(table) do
ensure_table(table)
:ets.tab2list(table)
end
def size(table), do: :ets.info(table, :size)
@impl true
def init({table, opts}) do
state = %{
table: table,
max_size: Keyword.get(opts, :max_size, @default_max_size),
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)
Persist.restore(table)
evict_cursor = __MODULE__.Evict.evict(table, state.max_size, state.evict_cursor)
:timer.send_interval(state.sweep_interval, :sweep)
{:ok, schedule_backup(%{state | evict_cursor: evict_cursor})}
end
@impl true
def handle_call({:put, key, value}, _from, state) do
ensure_table(state.table)
access = System.system_time(:microsecond)
:ets.insert(state.table, {key, value, 1, access})
evict_cursor = __MODULE__.Evict.evict(state.table, state.max_size, state.evict_cursor)
{:reply, :ok, %{state | evict_cursor: evict_cursor}}
end
@impl true
def handle_call({:get, key}, _from, state) do
ensure_table(state.table)
case :ets.lookup(state.table, key) do
[{^key, value, frequency, _old_access}] ->
access = System.system_time(:microsecond)
:ets.insert(state.table, {key, value, frequency + 1, access})
{:reply, {:ok, value}, state}
[] ->
{:reply, :error, state}
end
end
@impl true
def handle_call({:delete, key}, _from, state) do
:ets.delete(state.table, key)
{:reply, :ok, state}
end
@impl true
def handle_call(:sweep, _from, state) do
__MODULE__.Sweep.halve_frequencies(state.table)
{:reply, :ok, state}
end
@impl true
def handle_info(:backup, state) do
run_backup(state)
{:noreply, schedule_backup(state)}
end
@impl true
def handle_info(:sweep, state) do
__MODULE__.Sweep.halve_frequencies(state.table)
{: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
case :ets.whereis(table) do
:undefined -> create_table(table)
_ -> :ok
end
end
defp create_table(table) do
:ets.new(table, [:named_table, :public, :set])
rescue
ArgumentError -> table
end
end