Syntropy.Receipts.Tracker (syntropy v0.3.0)

Copy Markdown

Tracks the OS processes of running checks so code-review runs can be cancelled mid-suite.

Killing the runner task (Task.shutdown/2) closes the check's port but does not kill the external process — a test suite mid-compute survives its port. The tracker closes that gap with a tombstone protocol:

  • register_check/2 — the execution layer registers the check's OS pid right after spawn. If the run was already aborted it returns :cancelled and the caller must kill its own process and stop, which closes the race between an abort and the next check spawning.
  • abort/1 — writes the run's tombstone, SIGTERMs the currently registered OS pid synchronously (milliseconds), and hands SIGKILL escalation to a fire-and-forget supervised task so callers (the scheduler's cancel path) never sleep.
  • release/1 — purges the run's tombstone and entry; the scheduler calls it after the runner task is fully shut down.

Registrant processes are monitored, so entries are purged even when a runner dies without completing its checks.

Summary

Functions

Aborts run_id: tombstones it and kills its currently running check.

Returns a specification to start this module under a supervisor.

Marks the current check of run_id finished (its process has exited).

The OS pid of the currently running check for run_id, or nil.

Registers the OS pid of the currently running check for run_id.

Clears the tombstone and any entry for run_id.

Functions

abort(server \\ __MODULE__, run_id)

@spec abort(GenServer.server(), String.t()) :: :ok

Aborts run_id: tombstones it and kills its currently running check.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

complete_check(server \\ __MODULE__, run_id)

@spec complete_check(GenServer.server(), String.t()) :: :ok

Marks the current check of run_id finished (its process has exited).

current_os_pid(server \\ __MODULE__, run_id)

@spec current_os_pid(GenServer.server(), String.t()) :: pos_integer() | nil

The OS pid of the currently running check for run_id, or nil.

register_check(server \\ __MODULE__, run_id, os_pid)

@spec register_check(GenServer.server(), String.t(), pos_integer() | nil) ::
  :ok | :cancelled

Registers the OS pid of the currently running check for run_id.

Returns :cancelled when the run has been aborted — the caller must kill the process it just spawned and stop executing checks.

A nil os_pid consults the tombstone without registering anything: the check process already exited, so there is nothing to kill later.

release(server \\ __MODULE__, run_id)

@spec release(GenServer.server(), String.t()) :: :ok

Clears the tombstone and any entry for run_id.

start_link(opts)