sworm v0.5.9 Sworm

Sworm takes the accessible API from Swarm, and combines it with the robustness of Horde.

It strives to be a combination of a global, distributed process registry and supervisor, accessible through a friendly API.

Usage

The concept behind Sworm is that there can be multiple, distinct "sworms" living inside a cluster of BEAM nodes. To define a Sworm, you define a module like this:

defmodule MyProcesses do
  use Sworm
end

Now, the MyProcesses module must be added to your application's supervison tree.

When you now start the application, you can use the functions from the Sworm module inside your MyProcesses module:

{:ok, pid} = MyProcesses.register_name("my worker", MyWorker, :start_link, [arg1, arg2])

Link to this section Summary

Functions

Create a child specification for adding a new Sworm to the supervisor tree.

Joins a process to a group.

Removes a process from a group

Gets all the members of a group within the sworm.

Registers the given name to the given process. Names registered this way will not be shifted when the cluster topology changes, and are not restarted by Sworm.

Register a name in the given Sworm. This function takes a module/function/args triplet, and starts the process, registers the pid with the given name, and handles cluster topology changes by restarting the process on its new node using the given MFA.

Gets a list of all registered names and their pids within a sworm

Start and link a Sworm in a standalone fashion.

Unregisters the given name from the sworm.

Get the pid of a registered name within a sworm.

Either finds the named process in the sworm or registers it using the register/4 function.

Link to this section Functions

Link to this function

child_spec(sworm, opts \\ [])

child_spec(sworm :: atom(), opts :: [term()]) :: Supervisor.child_spec()

Create a child specification for adding a new Sworm to the supervisor tree.

Link to this function

join(sworm, group, pid \\ self())

join(sworm :: atom(), term(), pid()) :: :ok | {:error, :not_found}

Joins a process to a group.

Returns an error when the given process is not part of the sworm.

Link to this function

leave(sworm, group, pid \\ self())

leave(sworm :: atom(), term(), pid()) :: :ok | {:error, :not_found}

Removes a process from a group

Returns an error when the given process is not part of the sworm.

Link to this function

members(sworm, group)

members(sworm :: atom(), term()) :: [pid()]

Gets all the members of a group within the sworm.

Returns a list of pids.

Link to this function

register_name(sworm, name, pid \\ self())

register_name(sworm :: atom(), name :: term(), pid :: pid()) :: :yes | :no

Registers the given name to the given process. Names registered this way will not be shifted when the cluster topology changes, and are not restarted by Sworm.

If no pid is given, self() is used for the registration.

Link to this function

register_name(sworm, name, m, f, a)

register_name(
  sworm :: atom(),
  name :: term(),
  module :: atom(),
  function :: atom(),
  args :: [term()]
) :: {:ok, pid()} | {:error, term()}

Register a name in the given Sworm. This function takes a module/function/args triplet, and starts the process, registers the pid with the given name, and handles cluster topology changes by restarting the process on its new node using the given MFA.

Processes that are started this way are added to the Sworm's dynamic Horde supervisor, distributed over the members of the Horde according to its cluster strategy, and restarted when they crash.

When the node on which the process is spawned exits, the processes are restarted on one of the other nodes in the cluster.

Link to this function

registered(sworm)

registered(sworm :: atom()) :: [{name :: term(), pid()}]

Gets a list of all registered names and their pids within a sworm

Link to this function

start_link(sworm, opts \\ [])

start_link(sworm :: atom(), opts :: [term()]) :: {:ok, pid()}

Start and link a Sworm in a standalone fashion.

You almost will never need this function, as it is more usual to start a Sworm directly in a supervisor tree, using the provided child_spec function.

Link to this function

unregister_name(sworm, name)

unregister_name(sworm :: atom(), name :: term()) :: :ok

Unregisters the given name from the sworm.

Link to this function

whereis_name(sworm, name)

whereis_name(sworm :: atom(), name :: term()) :: pid() | nil

Get the pid of a registered name within a sworm.

Link to this function

whereis_or_register_name(sworm, name, m, f, a)

whereis_or_register_name(
  sworm :: atom(),
  name :: term(),
  module :: atom(),
  function :: atom(),
  args :: [term()]
) :: {:ok, pid()} | {:error, term()}

Either finds the named process in the sworm or registers it using the register/4 function.