mirror of
https://github.com/TheRealOwenRees/chess-endgame-trainer.git
synced 2026-11-18 03:32:06 +00:00
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:
@@ -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
@@ -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
@@ -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
|
||||
Vendored
+63
-29
@@ -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
|
||||
|
||||
Vendored
+54
-7
@@ -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")
|
||||
|
||||
@@ -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 """
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user