TimeWarp.Coordinator (TimeWarp v0.2.0)

Copy Markdown View Source

GVT computation, fossil-collect trigger, run control and termination.

Mattern's algorithm — the GVT computation in use

The transient-message problem — a message that has left its sender's accounting but not yet entered its receiver's — is what makes GVT hard. Mattern's colored-message algorithm solves it without stopping the world: each message carries the sender's epoch colour, the receiver classifies transience from that colour rather than from its own state, and a round completes once the coloured send and receive counts reconcile. This is the default (gvt_mode: :mattern) and the only algorithm on the steady-state path.

The stop-the-world computation — gvt_mode: :freeze

An earlier, deliberately unclever computation, retained as the test oracle and as the single end-of-run termination confirmation. It is slow — a global barrier per cycle — but incapable of computing GVT too high, which is what makes it useful as a reference:

  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.

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 rather than left to burn wall-clock. Off by default, and note that rollback rate is not a proxy for retained state — see the retention warning on TimeWarp.

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.