# `Hassock.RegistryCache`
[🔗](https://github.com/bbangert/hassock/blob/v0.3.0/lib/hassock/registry_cache.ex#L1)

Optional ETS-backed cache of Home Assistant's floor, area, device, entity
and label registries.

On every `:connected` (the first and each reconnect) it subscribes to the
five `*_registry_updated` events (once; the connection restores them after
a reconnect) and lists all five registries. When an update event arrives it
re-lists that registry, debounced (default 500 ms) so a burst of updates,
such as an integration adding fifty entities, costs one list. Failed loads
and re-lists are retried while connected.

It doesn't take ownership of the connection (it uses
`Hassock.Connection.watch/1`), so it runs beside a `Hassock.Cache` or any
other controller. Lists run in a linked task, so the cache stays
responsive (and stops promptly) while a large registry loads.

The controlling process (default: the caller of `start_link/1`) receives:

  * `{:hassock_registry, cache, :ready}` - after all five registries are
    loaded, again after each reconnect
  * `{:hassock_registry, cache, {:changed, kind}}` - after a registry was
    re-listed because it changed

Reads (`list/2`, `get/3`) go to ETS directly, with no GenServer call.
Data is kept while disconnected.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `controlling_process`

```elixir
@spec controlling_process(GenServer.server(), pid()) ::
  :ok | {:error, :not_owner | :not_alive}
```

Transfer cache ownership. Only the current controller may transfer, or
anyone once the controller has exited.

# `get`

```elixir
@spec get(GenServer.server(), Hassock.Registries.kind(), String.t()) :: struct() | nil
```

One cached item by kind and id, or `nil`.

# `list`

```elixir
@spec list(GenServer.server(), Hassock.Registries.kind()) :: [struct()]
```

All cached items of one registry (`Hassock.Registries.kinds/0`), sorted by id.

# `start_link`

```elixir
@spec start_link(keyword()) :: GenServer.on_start()
```

Start a registry cache for a connection.

Options:

  * `:connection` - pid or registered name of a `Hassock.Connection` (required)
  * `:controlling_pid` - receiver of registry messages (default: caller)
  * `:name` - register the cache under this name (optional)
  * `:debounce` - ms to wait after an update event before re-listing
    (default 500)
  * `:retry` - ms before retrying a failed load or re-list (default 5000)

---

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