EHLS.Server (Elixir HLS v0.1.0)

Copy Markdown View Source

A process that owns an instance, for an application with a supervision tree. definstance declares the circuit; this is the runtime face a program uses to own one, where it wants one (as Ecto.Repo is beside Ecto.Schema):

children = [
  {EHLS.Server, instance: {MyApp, :radio}, name: Radio, topics: [:presses], cpu: [batch: 8192]}
]

EHLS.Server.call(Radio, [samples])        # radio(samples), in the server
EHLS.Server.call(Radio, [:state, :level]) # radio(:state, :level)
EHLS.Server.cast(Radio, [:stop])          # radio(:stop), not waiting for it
EHLS.Server.subscribe(Radio, :presses)    # {:presses, value} to this process too
  • Starting: init/1 stops and starts the instance, so a supervised application starts from the initial state (an instance in the FPGA runs from reset and keeps its state across a program replaced without a reset).
  • Callers queue in the server's mailbox, one call at a time, instead of {:error, :busy} from an end already in use. A call that raises answers {:error, {kind, reason}} and the server goes on; a time-out is counted.
  • Events: with topics: the server subscribes once (EHLS.PubSub.subscribe/2) and hands each event on to any number of processes (subscribe/2), beyond the few subscribers a topic has in the FPGA.
  • A function on the CPU (on: :cpu): with cpu: opts the server starts the drivers between the circuits (instance(:cpu_start, opts)) and stops them when it stops.
  • stats/1: calls, casts, errors, time-outs.

It costs one message more per call: calling the instance directly stays, for what is in a hurry. One server per instance (it is one circuit).

How it differs from a GenServer of your own:

  • You do not write its callbacks. EHLS.Server is the callback module; it is called with call/3 / cast/2, as an Agent is with Agent.get and the like, not with messages of your own.
  • Its state is the circuit's. Read it through the server (EHLS.Server.call(Radio, [:state, :level])); :sys.get_state shows only the server's own bookkeeping.
  • There is one circuit. A second server for the same instance does not make a second state: both drive the one circuit. Two of them are two definstance.
  • A restart starts the circuit from its initial state, as a restarted GenServer loses its state; but while the server is down the circuit goes on running, as it does from reset.
  • The instance can still be called directly (radio(samples)), past the server's queue.

Summary

Functions

The instance called with args in the server: call(s, [x]) is instance(x), call(s, [:value]) instance(:value).

As call/3, not waiting for the result.

Returns a specification to start this module under a supervisor.

Starts a server owning instance: {module, name}; name: registers it.

%{calls:, casts:, errors:, timeouts:} so far.

The events of topic (one of the server's topics:) to this process too, as {topic, value}.

No more events of topic from the server to this process.

instance(:value).

Functions

call(server, args, timeout \\ 5000)

The instance called with args in the server: call(s, [x]) is instance(x), call(s, [:value]) instance(:value).

cast(server, args)

As call/3, not waiting for the result.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

start_link(opts)

Starts a server owning instance: {module, name}; name: registers it.

stats(server)

%{calls:, casts:, errors:, timeouts:} so far.

subscribe(server, topic)

The events of topic (one of the server's topics:) to this process too, as {topic, value}.

unsubscribe(server, topic)

No more events of topic from the server to this process.

value(server)

instance(:value).