https://github.com/arjan/singleton

Global, supervised singleton processes for Elixir
https://github.com/arjan/singleton

elixir-lang

Last synced: about 1 year ago
JSON representation

Global, supervised singleton processes for Elixir

• Host: GitHub
• URL: https://github.com/arjan/singleton
• Owner: arjan
• License: mit
• Created: 2016-10-30T04:03:47.000Z (over 9 years ago)
• Default Branch: master
• Last Pushed: 2024-06-20T10:03:27.000Z (almost 2 years ago)
• Last Synced: 2025-03-29T01:05:26.096Z (about 1 year ago)
• Topics: elixir-lang
• Language: Elixir
• Size: 58.6 KB
• Stars: 108
• Watchers: 2
• Forks: 21
• Open Issues: 5
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

• awesome - arjan/singleton - Global, supervised singleton processes for Elixir (<a name="Elixir"></a>Elixir)

README

          
# Singleton

[![Build Status](https://github.com/arjan/singleton/workflows/test/badge.svg)](https://github.com/arjan/singleton)

[![Module Version](https://img.shields.io/hexpm/v/singleton.svg)](https://hex.pm/packages/singleton)

[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/singleton/)

[![Total Download](https://img.shields.io/hexpm/dt/singleton.svg)](https://hex.pm/packages/singleton)

[![License](https://img.shields.io/hexpm/l/singleton.svg)](https://github.com/arjan/singleton/blob/master/LICENSE)

[![Last Updated](https://img.shields.io/github/last-commit/arjan/singleton.svg)](https://github.com/arjan/singleton/commits/master)

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`:

```elixir

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.

```elixir

children = [

  # ...,

  {Singleton.Supervisor, name: MyApp.Singleton}

]

supervisor = Supervisor.start_link(children, opts)

```

## Usage

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

```elixir

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`.

```elixir

config :singleton,

  dynamic_supervisor: [max_restarts: 100]

```

or add `max_restarts` to your singleton supervisor spec:

```

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

```