Per-run .beam snapshot store for MutagenEx.MutationRunner.
Per mutagen.decision.per_run_beam_cache,
this module is stateless: it operates on an ETS table whose lifetime
is owned by MutationRunner.run/1. The table is created at the start of
run/1 and deleted in the after clause; there is no GenServer, no
supervisor child, and no global state.
The table holds one entry per scoped module:
{module(), beam_filename :: charlist(), binary :: binary()}Inserted via :ets.insert_new/2 so a snapshot pre-pass that runs
concurrently with the per-site loop cannot accidentally overwrite an
existing entry — insert_new/2 is the canonical TOCTOU-free guard.
Interaction shape
The runner threads two pieces of state through cfg:
cfg.beam_cache_table— the per-run ETS table reference. Created once perrun/1call, opened with:ets.new(:beam_cache, [:set, :public, read_concurrency: true]).:publicaccess is required because per-site tasks spawned underTask.Supervisor.async_stream_nolink/4perform restore from worker processes that are not the table's owner.cfg.code_server— a module implementingMutagenEx.Test.CodeServerFacade. Production callers default toMutagenEx.Test.CodeServer(delegates to:code); tests inject a recording stub.
Snapshot ordering invariant
snapshot/3 MUST run AFTER :cover.compile_directory/1 has
instrumented the scoped modules. The runner's pre-pass executes in
MutationRunner.run/1 after CoverageRunner has already returned, so
the binary captured here is the cover-instrumented binary. Restoring
from this snapshot therefore preserves coverage instrumentation across
the per-site mutation cycle. If the snapshot were taken before cover
instrumented, restore would swap in the uninstrumented binary and the
next site's coverage analysis would report nothing for that module.
Restore semantics
restore/3 is the hot path called once per per-site cycle (and once on
the :compile_error defensive branch). It assumes the snapshot
pre-pass has populated the table; a missing entry is a programmer
error and surfaces as {:error, :not_snapshotted, module}.
Successful restore returns {:ok, module}. Restore failure (the
code_server returned {:error, reason}) returns {:error, reason}
so the caller can fold the result into MutationRunner's existing
restore-failure surfacing path
({:error, :unrecoverable_restore_failure, ...}).
There is no Code.compile_quoted/2 call in this module. The restore
contract is "swap the cached binary back via :code.load_binary/3";
the AST never participates.
Summary
Types
Snapshot entry stored in the table.
Reasons restore/3 can fail.
Per-run ETS table identifier returned by :ets.new/2.
Functions
Delete the per-run ETS table.
Open a new per-run ETS table with the documented options.
Look up module's snapshot in table and reload it via
code_server.load_binary/3.
Capture module's current .beam and store it in table.
Types
Snapshot entry stored in the table.
Reasons restore/3 can fail.
@type table() :: :ets.tab()
Per-run ETS table identifier returned by :ets.new/2.
Functions
@spec delete(table()) :: :ok
Delete the per-run ETS table.
Called from MutationRunner.run/1's try/after so the table is
cleaned up on every exit path (success, {:error, _, _} return,
raise/throw/exit). Safe to call with a nonexistent table (a defensive
:ets.info/1 check guards against double-delete in the
try/after after a clean tear-down).
@spec new() :: table()
Open a new per-run ETS table with the documented options.
This helper exists so the runner's run/1 and tests both use exactly
one option list. Returns the table reference, which the caller passes
through cfg.beam_cache_table.
@spec restore(table(), module(), module()) :: {:ok, module()} | {:error, restore_error()}
Look up module's snapshot in table and reload it via
code_server.load_binary/3.
Returns:
{:ok, module}on success.{:error, {:not_snapshotted, module}}when the table has no entry formodule— a programmer error since the pre-pass is contracted to populate every scoped module before any site runs.{:error, {:code_server, reason}}when thecode_serverreturned{:error, reason}fromload_binary/3. The runner threads this throughrestore/3's contract so the existing:unrecoverable_restore_failuresurfacing path lights up.
The returned {:ok, module} tuple matches :code.load_binary/3's
success shape so callers can pattern-match either against this
function's result or the underlying call.
Capture module's current .beam and store it in table.
Idempotent: a second call with the same module is a no-op. The
underlying :ets.insert_new/2 returns false on the second call;
this function normalises both outcomes to :ok so callers do not
need to distinguish first-touch from repeated-touch.
Returns {:error, :unavailable} when the code_server returns
:error for module — this indicates the module is not loaded or
has no .beam accessible to the code server. The pre-pass should
not encounter this for modules in the scope set (they are by
definition compiled and loaded), but the error is surfaced rather
than silently absorbed so the caller can decide whether to abort or
continue.