SvPortSim.Transport behaviour (SvPortSim v0.1.0)

Behaviour for simulator transports owned by SvPortSim.

A transport is the boundary between the public SvPortSim GenServer and a concrete simulator runtime. The default implementation, SvPortSim.Transport.Port, owns an Erlang port connected to an external C++ wrapper process. Tests may implement this behaviour in pure Elixir.

Transport callbacks are invoked synchronously and serially by the owning SvPortSim GenServer. A transport should not expose its state to callers.

Summary

Types

envelope()

Protocol envelope map as documented by SvPortSim.Protocol.

state()

Opaque state owned by the transport implementation.

timeout_ms()

Command timeout in milliseconds or :infinity.

Callbacks

close(state)

Closes or releases the transport resource.

open(keyword)

Opens the simulator transport for one SvPortSim instance.

request(envelope, state, timeout_ms)

Sends one request envelope and returns the matching response envelope.

Types

envelope()

@type envelope() :: %{required(String.t()) => term()}

Protocol envelope map as documented by SvPortSim.Protocol.

state()

@type state() :: term()

Opaque state owned by the transport implementation.

timeout_ms()

@type timeout_ms() :: pos_integer() | :infinity

Command timeout in milliseconds or :infinity.

Callbacks

close(state)

@callback close(state()) :: :ok | {:error, term()}

Closes or releases the transport resource.

open(keyword)

@callback open(keyword()) :: {:ok, state()} | {:error, term()}

Opens the simulator transport for one SvPortSim instance.

The callback receives the normalized transport options selected by SvPortSim.start/1 or SvPortSim.start_link/1.

request(envelope, state, timeout_ms)

@callback request(envelope(), state(), timeout_ms()) ::
  {:ok, envelope(), state()}
  | {:error, map(), state()}
  | {:error, term(), state()}
  | {:error, term()}

Sends one request envelope and returns the matching response envelope.

The returned envelope may have "kind" => "response" or "kind" => "error". Transports may also return {:error, error_body, state} for Elixir-side runtime failures that are already normalized to the protocol error-body shape.