defmodule Eternal do
  @moduledoc """
  This module implements bindings around what should be an eternal ETS table,
  or at least until you decide to terminate it. It works by using "bouncing"
  GenServers which come up as needed to provide an heir for the ETS table. It
  operates as follows:

  1. An ETS table is created with the provided name and options.
  2. Two GenServers are started, an `owner` and an `heir`. The ETS table is gifted
    to the `owner`, and has the `heir` set as the heir.
  3. If the `owner` crashes, the `heir` becomes the owner, and a new GenServer
    is started and assigned the role of `heir`.
  4. If an `heir` dies, we attempt to start a new GenServer and notify the `owner`
    so that they may change the assigned `heir`.

  This means that there should always be an `heir` to your table, which should
  ensure that you don't lose anything inside ETS.
  """

  # import guards
  import Eternal.Table
  import Eternal.Priv

  # alias while we're at it
  alias Eternal.Priv
  alias Eternal.Table
  alias Eternal.Supervisor, as: Sup

  # Return values of `start_link` functions
  @type on_start :: { :ok, pid } | :ignore |
                    { :error, { :already_started, pid } | { :shutdown, term } | term }

  @doc """
  Creates a new ETS table using the provided `ets_opts`.

  These options are passed through as-is, with the exception of prepending the
  `:public` and `:named_table` options. Seeing as you can't execute inside the
  GenServers, your table will have to be public to be interacted with.

  ## Options

  You may provide a third parameter containing Eternal options:

  - `:name` - override the default naming scheme and use a custom name for this
    table. Remember to use this name when calling `stop/1`.
  - `:quiet` - by default, Eternal logs debug messages. Setting this to true will
    disable this logging.

  ## Examples

      iex> Eternal.start_link(:table1)
      { :ok, _pid1 }

      iex> Eternal.start_link(:table2, [ :compressed ])
      { :ok, _pid2 }

      iex> Eternal.start_link(:table3, [ ], [ quiet: true ])
      { :ok, _pid3 }

  """
  @spec start_link(name :: atom, ets_opts :: Keyword.t, opts :: Keyword.t) :: on_start
  def start_link(name, ets_opts \\ [], opts \\ []) when is_opts(name, ets_opts, opts) do
    with { :ok, pid, _table } <- create(name, [ :named_table ] ++ ets_opts, opts) do
      { :ok, pid }
    end
  end

  @doc """
  Functionally equivalent to `start_link/3`, except that the link to the starting
  process is removed after the table is started.

  ## Examples

      iex> Eternal.start(:table1)
      { :ok, _pid1 }

      iex> Eternal.start(:table2, [ :compressed ])
      { :ok, _pid2 }

      iex> Eternal.start(:table3, [ ], [ quiet: true ])
      { :ok, _pid3 }

  """
  @spec start(name :: atom, ets_opts :: Keyword.t, opts :: Keyword.t) :: on_start
  def start(name, ets_opts \\ [], opts \\ []) when is_opts(name, ets_opts, opts) do
    with { :ok, pid } = v <- start_link(name, ets_opts, opts) do
      :erlang.unlink(pid) && v
    end
  end

  @doc """
  Returns the heir of a given ETS table.

  ## Examples

      iex> Eternal.heir(:my_table)
      #PID<0.134.0>

  """
  @spec heir(table :: Table.t) :: pid | :undefined
  def heir(table) when is_table(table),
    do: :ets.info(table, :heir)

  @doc """
  Returns the owner of a given ETS table.

  ## Examples

      iex> Eternal.owner(:my_table)
      #PID<0.132.0>

  """
  @spec owner(table :: Table.t) :: pid | :undefined
  def owner(table) when is_table(table),
    do: :ets.info(table, :owner)

  @doc """
  Terminates both servers in charge of a given ETS table.

  Note: this will terminate your ETS table.

  ## Examples

      iex> Eternal.stop(:my_table)
      :ok

  """
  @spec stop(table :: Table.t) :: :ok
  def stop(table) when is_table(table) do
    name = Table.to_name(table)
    proc = GenServer.whereis(name)

    if proc && Process.alive?(proc) do
      Supervisor.stop(proc)
    end

    :ok
  end

  # Creates a table supervisor with the provided options and nominates the children
  # as owner/heir of the ETS table immediately afterwards. We do this by fetching
  # the children of the supervisor and using the process id to nominate.
  defp create(name, ets_opts, opts) do
    with { :ok, pid, table } = res <- Sup.start_link(name, ets_opts, opts) do
      [ proc1, proc2 ] = Supervisor.which_children(pid)

      { _id1, pid1, :worker, [__MODULE__.Server] } = proc1
      { _id2, pid2, :worker, [__MODULE__.Server] } = proc2

      Priv.heir(table, pid2)
      Priv.gift(table, pid1)

      res
    end
  end
end