Files
chess-endgame-trainer/lib/chesstrainer/cache.ex
T
owenrees 202b9b1f6a Add structured production logging (#105, #107) (#141)
* Update README.md

* Add structured JSON production logging (#105)

* Log requests and background failures (#107)

* Document production logging and the VPS runbook
2026-11-10 22:00:05 +01:00

161 lines
4.8 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. Failures are logged
rather than lost.
## Examples
iex> start_link(:tablebase)
"""
use GenServer
require Logger
alias Chesstrainer.Background
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 = fn ->
Background.run("cache backup", [table: table], fn -> backup_fun.(table) end)
end
case Task.Supervisor.start_child(Chesstrainer.Cache.BackupSupervisor, task) do
{:ok, _pid} ->
:ok
{:error, reason} ->
Logger.error("cache backup could not start", table: table, reason: reason)
:ok
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