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
+153 -6
View File
@@ -5,8 +5,9 @@ defmodule Chesstrainer.CacheTest do
setup context do
table = :"test_#{System.unique_integer([:positive])}"
{:ok, pid} = Cache.start_link(table, Map.get(context, :cache_opts, []))
on_exit(fn -> if Process.alive?(pid), do: GenServer.stop(pid) end)
opts = Map.get(context, :cache_opts, [])
pid = start_supervised!(Supervisor.child_spec({Cache, {table, opts}}, id: table))
{:ok, %{pid: pid, table: table}}
end
@@ -37,6 +38,32 @@ defmodule Chesstrainer.CacheTest do
end
end
describe "configuration" do
test "defaults to a max size of 100_000", %{pid: pid} do
assert :sys.get_state(pid).max_size == 100_000
end
test "starts from a {table, opts} child spec argument" do
table = :"test_child_spec_#{System.unique_integer([:positive])}"
pid =
start_supervised!(Supervisor.child_spec({Cache, {table, max_size: 3}}, id: table))
assert :sys.get_state(pid).max_size == 3
end
test "the application starts the tablebase cache with the configured options" do
config = Application.get_env(:chesstrainer, Chesstrainer.Cache, [])
pid = GenServer.whereis({:via, Registry, {Chesstrainer.CacheRegistry, :tablebase}})
state = :sys.get_state(pid)
assert state.max_size == Keyword.get(config, :max_size, 100_000)
assert state.backup_time ==
Chesstrainer.Cache.BackupSchedule.time!(Keyword.get(config, :backup_time))
end
end
describe "frequency tracking" do
test "get/2 increments the entry frequency", %{table: table} do
Cache.put(table, "key", "value")
@@ -77,6 +104,26 @@ defmodule Chesstrainer.CacheTest do
end
end
describe "eviction on a cache larger than the sample" do
@describetag cache_opts: [max_size: 100]
test "stays at the maximum size under churn", %{table: table} do
for i <- 1..500, do: Cache.put(table, i, i)
assert Cache.size(table) == 100
end
test "a frequently used entry survives churn from cold entries", %{table: table} do
Cache.put(table, :hot, "value")
for _ <- 1..50, do: Cache.get(table, :hot)
for i <- 1..500, do: Cache.put(table, i, i)
assert Cache.size(table) == 100
assert {:ok, "value"} = Cache.get(table, :hot)
end
end
describe "weekly sweep" do
test "halves every entry frequency", %{table: table} do
Cache.put(table, "busy", "value")
@@ -92,23 +139,123 @@ defmodule Chesstrainer.CacheTest do
end
end
describe "backup" do
test "runs off the cache process so reads and writes stay responsive" do
table = :"test_async_backup_#{System.unique_integer([:positive])}"
parent = self()
ref = make_ref()
backup_fun = fn _table ->
send(parent, {:backup_started, ref, self()})
receive do
{:finish_backup, ^ref} -> :ok
end
end
pid =
start_supervised!(
Supervisor.child_spec({Cache, {table, [backup_fun: backup_fun]}}, id: table)
)
assert :ok = Cache.put(table, "key", "value")
send(pid, :backup)
assert_receive {:backup_started, ^ref, backup_pid}, 1_000
backup_monitor = Process.monitor(backup_pid)
assert {:ok, "value"} = Cache.get(table, "key")
assert :ok = Cache.put(table, "other", "value")
send(backup_pid, {:finish_backup, ref})
assert_receive {:DOWN, ^backup_monitor, :process, ^backup_pid, :normal}, 1_000
end
test "re-arms the daily backup after each run" do
table = :"test_rearm_#{System.unique_integer([:positive])}"
pid =
start_supervised!(
Supervisor.child_spec(
{Cache, {table, [backup_fun: fn _table -> :ok end, backup_time: "04:30"]}},
id: table
)
)
send(pid, :backup)
state = :sys.get_state(pid)
assert state.backup_time == {4, 30}
assert is_reference(state.backup_timer)
assert :erlang.read_timer(state.backup_timer) > 0
end
end
describe "persistence" do
test "writes the backup atomically, leaving no temporary file" do
table = :"test_atomic_#{System.unique_integer([:positive])}"
backup = Path.join("priv/static/backups", "#{table}.v2.det")
on_exit(fn ->
File.rm_rf(backup <> ".tmp")
File.rm(backup)
end)
start_supervised!(Supervisor.child_spec({Cache, table}, id: table))
Cache.put(table, "key", "value")
assert :ok = Cache.backup(table)
assert File.exists?(backup)
refute File.exists?(backup <> ".tmp")
end
test "a failed backup leaves the previous backup intact" do
table = :"test_failed_backup_#{System.unique_integer([:positive])}"
backup = Path.join("priv/static/backups", "#{table}.v2.det")
temp = backup <> ".tmp"
on_exit(fn ->
File.rm_rf(temp)
File.rm(backup)
end)
start_supervised!(Supervisor.child_spec({Cache, table}, id: table))
Cache.put(table, "key", "value")
assert :ok = Cache.backup(table)
# A directory at the temporary path makes the write fail before the rename.
File.mkdir_p!(temp)
Cache.put(table, "another", "value")
assert {:error, _reason} = Cache.Persist.backup(table)
assert File.exists?(backup)
assert :ok = stop_supervised(table)
start_supervised!(Supervisor.child_spec({Cache, table}, id: table))
assert {:ok, "value"} = Cache.get(table, "key")
assert :error = Cache.get(table, "another")
end
test "backup and restore preserve frequencies" do
table = :"test_persist_#{System.unique_integer([:positive])}"
backup = Path.join("priv/static/backups", "#{table}.v2.det")
on_exit(fn -> File.rm(backup) end)
{:ok, pid} = Cache.start_link(table)
start_supervised!(Supervisor.child_spec({Cache, table}, id: table))
Cache.put(table, "key", "value")
Cache.get(table, "key")
Cache.get(table, "key")
assert :ok = Cache.backup(table)
assert :ok = GenServer.stop(pid)
assert :ok = stop_supervised(table)
{:ok, restored_pid} = Cache.start_link(table)
on_exit(fn -> if Process.alive?(restored_pid), do: GenServer.stop(restored_pid) end)
start_supervised!(Supervisor.child_spec({Cache, table}, id: table))
assert [{"key", "value", frequency, _last_access}] = Cache.show(table)
assert frequency == 3