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/1stops 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): withcpu: optsthe 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.Serveris the callback module; it is called withcall/3/cast/2, as anAgentis withAgent.getand 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_stateshows 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
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.
See 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).