arjan / singleton

Global, supervised singleton processes for Elixir

Singleton

Convenience wrapper library around Erlang's global module to ensure a single instance of a process is kept running on a cluster of nodes.

Installation

The package can be installed as:

1. Add singleton to your list of dependencies in mix.exs:

def deps do
  [{:singleton, "~> 1.0"}]
end

2. Ensure Singleton.Supervisor is added to your application's supervision tree:

If your application includes a supervision tree in application.ex, you can simply add Singleton.Supervisor to the list of children.

children = [
  # ...,
  {Singleton.Supervisor, name: MyApp.Singleton}
]

supervisor = Supervisor.start_link(children, opts)

Usage

Use Singleton.start_child/4 to start a unique GenServer process.

Singleton.start_child(MyApp.Singleton, MyServer, [1], {:myserver, 1})

Execute this command on all nodes. The MyServer GenServer is now globally registered under the name {:global, {:myserver, 1}}.

As soon as you connect nodes together, you'll see logger messages like:

04:56:29.003 [info]  global: Name conflict terminating {MyServer, #PID<12501.68.0>}

When you now stop (or disconnect) the node on which the singleton process runs, you'll see it get started on one of the other nodes.

Troubleshooting

More than 3 singleton processes [info] Application singleton exited: shutdown

In case you run more than 3 singleton you'll need to increase the max_restarts of DynamicSupervisor.

config :singleton,
  dynamic_supervisor: [max_restarts: 100]

or add max_restarts to your singleton supervisor spec:

  {Singleton.Supervisor, name: MyApp.Singleton, max_restarts: 100}

singleton's Issues

Killing parent process?

Hi there,

This library seems like what I'm looking for, but I'm seeing similar behaviour to what is described in the announcement post on Elixir Forums >> https://elixirforum.com/t/singleton-global-supervised-singleton-processes-for-elixir/2175/3

When a 2nd node joins the cluster, I do see:

23:24:54.246 [info] global: Name conflict terminating {:singleton, #PID<18487.303.0>}
But what is unexpected is that not only the singleton process is terminated, but the whole application on one of the nodes:

23:25:47.517 [info] Application wpc5_singleton exited: killed
And one of the nodes basically is left in a state where my own application is not running, only the “libraries” continue running.

I have a Phoenix application running across multiple nodes, and I want this Singleton process to run on a single node and be used by all nodes. However, I see that the only node that says running is the one running the Singleton process.

defmodule Pento.Application do
  use Application
  @impl true
  def start(_type, _args) do
    children = [
      PentoWeb.Telemetry,
      Pento.Repo,
      {DNSCluster, query: Application.get_env(:pento, :dns_cluster_query) || :ignore},
      {Phoenix.PubSub, name: Pento.PubSub},
      # Start the Finch HTTP client for sending emails
      {Finch, name: Pento.Finch},
      {Singleton.Supervisor, name: Pento.Singleton},
      # Start to serve requests, typically the last entry
      PentoWeb.Endpoint,
    ]

    opts = [strategy: :one_for_one, name: Pento.Supervisor]
    Supervisor.start_link(children, opts)

    # start singleton service for the global click counter
    Singleton.start_child(Pento.Singleton, Pento.Guesses.CounterServer, [], Pento.Guesses.CounterServer)

  end

...
end

Is it possible to use with GenStage?

As I noticed, this library works with only GenServer. But is it possible to use it for GenStag? https://hexdocs.pm/gen_stage/GenStage.html

Possible change in manager process

It is possible that this line

singleton/lib/singleton/manager.ex

Line 18 in ae3d0dd

use GenServer, restart: :transient

is the one that make managers process not to be restarted, when normal shutdown of process used in singleton?

when scaling down one service, my single process gets down and doesn't get up in remaining nodes of service... I think is because it gets detected as normal shutdown instead of abruptly

https://hexdocs.pm/elixir/Supervisor.html#module-restart-values-restart

If so, would be nice to pass the restart value by config, when starting the singleton

The `max_restarts` option that is used to troubleshoot more than 3 singletons, doesn't work

Because it is set to be used as a DynamicSupervisor regular option, but as stated in elixir-lang/elixir#13675, the max_restarts option only works as an init option

Incompatibility with Elixir 1.10.0 – Singleton.start_child uses deprecated args

Using singleton 1.2.0, In the latest stable elixir release, 1.10.0, Supervisor.start_child/2 doesn't expect a list as a second arg: elixir-lang/elixir@98e60a8

In the code I call Singleton.start_child, dialyzer fails:

  # {{…}}
  def start_link(_opts) do
    Singleton.start_child(__MODULE__, [], __MODULE__)
  end
  # {{…}}

lib/{{…}}/scheduler.ex:7:no_return
Function start_link/1 has no local return.
________________________________________________________________________________
done (warnings were emitted)
Halting VM with exit status 2

Ability to execute custom start_link

https://github.com/arjan/singleton/blob/master/lib/singleton/manager.ex#L58

  defp restart(state) do
    start_result =
      GenServer.start_link(state.mod, state.args, name: {:global, state.name})

    pid =
      case start_result do
        {:ok, pid} ->
          pid

        {:error, {:already_started, pid}} ->
          state.on_conflict && state.on_conflict.()
          pid
      end

    Process.monitor(pid)
    %State{state | pid: pid}
  end

It would be nice if GenServer.start_link/3 here could be replaced by state.mod.start_link/3. That would allow for starting a process which depends on custom code within the start_link/3 function.