# `EHLS.Server`
[🔗](https://github.com/elixir-hls/elixir-hls/blob/v0.1.0/lib/ehls/server.ex#L1)

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.

# `call`

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

# `cast`

As `call/3`, not waiting for the result.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `start_link`

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

# `stats`

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

# `subscribe`

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

# `unsubscribe`

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

# `value`

`instance(:value)`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
