MutagenEx.BeamCache (mutagen_ex v0.2.0)

Copy Markdown View Source

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 per run/1 call, opened with :ets.new(:beam_cache, [:set, :public, read_concurrency: true]). :public access is required because per-site tasks spawned under Task.Supervisor.async_stream_nolink/4 perform restore from worker processes that are not the table's owner.
  • cfg.code_server — a module implementing MutagenEx.Test.CodeServerFacade. Production callers default to MutagenEx.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

entry()

@type entry() :: {module(), charlist(), binary()}

Snapshot entry stored in the table.

restore_error()

@type restore_error() :: {:not_snapshotted, module()} | {:code_server, term()}

Reasons restore/3 can fail.

table()

@type table() :: :ets.tab()

Per-run ETS table identifier returned by :ets.new/2.

Functions

delete(table)

@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).

new()

@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.

restore(table, module, code_server)

@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 for module — a programmer error since the pre-pass is contracted to populate every scoped module before any site runs.
  • {:error, {:code_server, reason}} when the code_server returned {:error, reason} from load_binary/3. The runner threads this through restore/3's contract so the existing :unrecoverable_restore_failure surfacing 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.

snapshot(table, module, code_server)

@spec snapshot(table(), module(), module()) :: :ok | {:error, :unavailable}

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.