Sworm (sworm v0.5.13)
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
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
child_spec(sworm, opts \\ [])
@spec child_spec(sworm :: atom(), opts :: [term()]) :: Supervisor.child_spec()
Create a child specification for adding a new Sworm to the supervisor tree.
join(sworm, group, pid \\ self())
Joins a process to a group.
Returns an error when the given process is not part of the sworm.
leave(sworm, group, pid \\ self())
Removes a process from a group
Returns an error when the given process is not part of the sworm.
members(sworm, group)
Gets all the members of a group within the sworm.
Returns a list of pids.
register_name(sworm, name, pid \\ self())
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.
register_name(sworm, name, m, f, a)
@spec 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.
registered(sworm)
Gets a list of all registered names and their pids within a sworm
start_link(sworm, opts \\ [])
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.
unregister_name(sworm, name)
Unregisters the given name from the sworm.
whereis_name(sworm, name)
Get the pid of a registered name within a sworm.
whereis_or_register_name(sworm, name, m, f, a)
@spec 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.