# `Tempo.Supervisor`
[🔗](https://github.com/elixir-tempo/tempo/blob/v2.5.0/lib/tempo/supervisor.ex#L1)

Tempo's supervision tree: every process Tempo runs is started under it.

As it starts, it reads the time zone database the application configures
(`Tempo.time_zone_database/0`) and builds the table of every zone the
database lists the changes of, once, in `:persistent_term`: through 2100
for `tz`, whose rule-made changes are listed with its compiled ones, in
about 40 ms. The database is Tempo's for as long as the tree runs: a
database configured or updated afterwards is Tempo's once it is
restarted.

A question past the end of a zone's table, of a zone the database lists no
changes for, or of a database that lists none, is answered by a table
built from the database on the first such question and grown where a
question reaches past it. Those tables are kept in an ETS table owned by
the tree's one process.

### Supervision

Tempo's application starts this supervisor, so an application that adds
`:ex_tempo` to its dependencies and does nothing more has Tempo's processes
running:

    def deps do
      [{:ex_tempo, "~> 2.5"}]
    end

An application that supervises Tempo itself sets `runtime: false`, so that
Tempo's application does not start, and lists `Tempo.Supervisor` in its own
supervision tree. Tempo's application would have started Localize,
Calendrical and Astro, so the host starts them: listing `:calendrical`
starts Localize and Astro before it, as Calendrical's calendars read the
ephemeris Astro loads.

    def deps do
      [{:ex_tempo, "~> 2.5", runtime: false}]
    end

    def application do
      [extra_applications: [:logger, :calendrical]]
    end

    children = [
      Tempo.Supervisor
    ]

Without them, formatting fails because Localize's locale loader is not
running, and a day that begins at sunset cannot be placed because Astro's
ephemeris is not loaded.

The supervisor takes no options. Tempo's own processes depend on no other
application having been started. Where they are not running, Tempo still
answers every question of a zone, reading the zone's changes from the
database each time: correctly, but tens of microseconds a question, and
tens of milliseconds for a date past the end of the database's listed
changes (2100 for `tz`).

# `child_spec`

```elixir
@spec child_spec(keyword()) :: Supervisor.child_spec()
```

The child specification by which a host lists Tempo's supervision tree in
its own, as `Tempo.Supervisor` or `{Tempo.Supervisor, []}`.

### Arguments

* `options` is a keyword list, unused: the supervisor takes no options.

### Returns

* A `t:Supervisor.child_spec/0` that starts the tree with `start_link/1`.

### Examples

    iex> Tempo.Supervisor.child_spec([])
    %{id: Tempo.Supervisor, start: {Tempo.Supervisor, :start_link, [[]]}, type: :supervisor}

# `running?`

```elixir
@spec running?() :: boolean()
```

Whether Tempo's processes are running, so that a zone's table is kept
between questions of it.

### Returns

* `true` or `false`.

### Examples

    iex> Tempo.Supervisor.running?()
    true

# `start_link`

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

Starts Tempo's supervision tree.

### Arguments

* `options` is a keyword list, unused, accepted so that the supervisor can
  be listed as `Tempo.Supervisor` or `{Tempo.Supervisor, []}` in a
  supervision tree.

### Returns

* `{:ok, pid}`, or

* `{:error, {:already_started, pid}}` when Tempo's supervision tree is
  already running, as it is when Tempo's application has started.

### Examples

    iex> {:error, {:already_started, _pid}} = Tempo.Supervisor.start_link([])

---

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