# Distribunator

Utilities supporting process distribution across nodes and node connections.

## Installation

The package can be installed by adding `distribunator` to your list of
dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:distribunator, "~> 0.1.0"}
  ]
end
```

## Use

Distribunator consists of two components: The `Distribunator.Manager` GenServer
and the `Distribunator.Distributed` utility module.

### Manager

The manager GenServer is optional. Its job is to maintain a list of nodes that
will be `Node.connect()`ed and  `Node.monitor()`ed. If any of those goes down,
the manager will periodically (5 seconds) try to reconnect.

### Utility Module

The utility module contains functions and macros that allow low-friction
node-agnostic pid lookup, call, and cast functionality.

### Example Usage

Starting the manager from a module-based supervisor:
```elixir
defmodule MySupervisor  do
  @moduledoc """
  Supervisor some stuff
  """
  use Supervisor

  def start_link(args), do: Supervisor.start_link(__MODULE__, [args], name: __MODULE__)

  def init([args]) do
    Distributed.register()
    children_list = children()
    Supervisor.init(children_list, [strategy: :one_for_one])
  end

  def children do
    distributed_node_list = [String.to_atom("app1@remote_node1"), String.to_atom("app2@remote_node2")]
    [
      Supervisor.child_spec({Distribunator.Manager, distributed_node_list}, restart: :transient),
    ]
  end
end
```

A GenServer that is Distribunated
```elixir
defmodule MyWorker do
  @moduledoc """
  Do some work.
  """
  use GenServer
  require Distributed

  ##############################
  # API
  ##############################

  @doc """
  Do some foo-ing. Calling this API will lookup the first pid registered with
  the MyWorker module and perform a GenServer.call on it, returning the result.
  """
  def foo, do: Distributed.call(:foo)

  def start_link(:ok) do
    GenServer.start_link(__MODULE__, :ok, [name: __MODULE__])
  end

  defmodule State do
    @moduledoc false
    defstruct [
    ]
  end

  ##############################
  # GenServer Callbacks
  ##############################

  @impl true
  def init(:ok) do
    # Register this module and pid with Distribunator so it can be called from anywhere
    Distributed.register()
    {:ok, %State{}}
  end

  @impl true
  def handle_call(:foo, _from, state) do
    {:reply, :ok, state}
  end
```

Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
be found at [https://hexdocs.pm/distribunator](https://hexdocs.pm/distribunator).