A port for observing what an instrumented process does.

The virtual clock and the server wrappers know how to hand an event to an observer and nothing about what the observer does with it. That separation is the point: measuring a system — counters, traces, diagrams — is a different concern from controlling its time, and a library that owns the clock should not have to know what a counter is.

An observer is installed per process:

• with the :instrumentation option of VirtualTimeGenServer.start_link/3, which instruments the started server, and enables on_send/2 for the messages that server sends itself;
• with VirtualTimeGenServer.instrument/1 around code that sends messages through VirtualTimeGenServer.call/3 or VirtualTimeGenServer.cast/2.

Callbacks run inside the observed process, so keeping state is the observer's own business: one observer keeps counters in the process dictionary, another forwards events to a collector process, a third does nothing. The library never inspects that state; it only hands it back from VirtualTimeGenServer.snapshot/1 if the observer produced it.

An observer that raises raises in the process running it, like any other code running there. The library does not swallow the error.

Example

defmodule MessageCounter do
  @behaviour VirtualTimeGenServer.Instrumentation

  @impl true
  def on_receive({_kind, _message}, _meta) do
    Process.put(:received, Process.get(:received, 0) + 1)
    :ok
  end

  @impl true
  def on_send({_kind, _message}, _meta) do
    Process.put(:sent, Process.get(:sent, 0) + 1)
    :ok
  end

  @impl true
  def snapshot(_context) do
    %{sent: Process.get(:sent, 0), received: Process.get(:received, 0)}
  end
end

{:ok, clock} = VirtualClock.start_link()

{:ok, server} =
  VirtualTimeGenServer.start_link(MyServer, :ok,
    virtual_clock: clock,
    instrumentation: MessageCounter
  )

{:ok, %{received: 1}} = VirtualTimeGenServer.snapshot(server)