TimeWarp.Coordinator (TimeWarp v0.1.0)

Copy Markdown View Source

GVT computation, fossil-collect trigger, run control and termination (spec §3.1, §6).

Phase 0 GVT — stop-the-world, safe by construction (spec §6.2, §15)

The transient-message problem (a message that has left its sender's accounting but not entered its receiver's, §6.1) is what makes GVT hard. Phase 0 sidesteps the cleverness of Mattern's algorithm for something obviously safe:

  1. Broadcast :freeze. Frozen LPs stop processing — and therefore stop sending — but keep draining their mailbox into their queues, counting every receive.
  2. Poll all LPs for {local_min, sent, recv}. Because no frozen LP sends, total sent is static and total recv climbs to meet it. Re-poll until Σsent + injected == Σrecv: quiescence, with zero transient messages.
  3. GVT = min(local_min) over all LPs — a true lower bound, since at quiescence every sent event sits in some LP's queue and is counted.
  4. Broadcast the new GVT; LPs fossil-collect and resume.

Slow (a global barrier per cycle) but incapable of computing GVT too high. Mattern's colored-message algorithm replaces this in Phase 1.

Mitigation 2 — thrash circuit breaker

Each poll returns per-LP rollback counts. The Coordinator differences them across cycles to get a rollback rate; if it stays above thrash_guard's threshold, the run is halted (§11.1) rather than left to burn wall-clock.

Summary

Functions

Returns a specification to start this module under a supervisor.

Start a run. Returns {:ok, coordinator_pid} used as the sim handle.

Cancel the active run: tear down its LPs and return the coordinator to idle.

Functions

await(sim)

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

report(sim)

start_link(_)

start_run(config)

Start a run. Returns {:ok, coordinator_pid} used as the sim handle.

stop_run(sim)

Cancel the active run: tear down its LPs and return the coordinator to idle.

For a run that never reaches a terminal state on its own — e.g. an unbounded horizon deliberately held open. The Coordinator is a singleton, so this resets it in place (the process lives on, ready for the next start_run) rather than being killed and restarted by its supervisor, which would race the next run.