swarm

v3.4.0

swarm v3.4.0 Swarm

This is the public Elixir API for :swarm.

Link to this section Summary

Functions

join(group, pid)

Joins a process to a group

leave(group, pid)

Removes a process from a group

members(group)

Gets all the members of a group. Returns a list of pids

multi_call(group, msg)

Calls each process in a group, and collects the results into a list. The order of the results is not guaranteed. Calls are made via GenServer.call/2, so process will need to handle a message in that format

multi_call(group, msg, timeout)

Same as multi_call/2, except allows for a configurable timeout. The timeout is per-call, but since all calls are done in parallel, this is effectively the absolute timeout as well

publish(group, msg)

Publishes a message to a group. This is done via Kernel.send/2, so GenServers and the like will receive it via handle_info/2

register_name(name, pid)

Registers the given name to the given pid, however names registered this way will not be shifted when the cluster topology changes, but this allows you to use :swarm as a distributed process registry, including registering names with {:via, :swarm, name}

register_name(name, m, f, a, timeout \\ :infinity)

Similar to register_name/2, except this version takes module/function/args parameters, 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

registered()

Gets a list of all registered names and their pids

send(name, msg)

This is primarily here for use by the standard library facilities for sending messages to a process, e.g. by GenServer.cast/2. It sends a message to a process by name, using Kernel.send/2

start(type, args)

Starts the Swarm application. You should not need to do this unless you are manually handling Swarm’s application lifecycle

unregister_name(name)

Unregisters the given name from the registry

whereis_name(name)

Get the pid of a registered name

whereis_or_register_name(name, m, f, a, timeout \\ :infinity)

Either finds the named process in the swarm or registers it using the register function

Link to this section Functions

Link to this function join(group, pid) 
join(term(), pid()) :: :ok

Joins a process to a group

Link to this function leave(group, pid) 
leave(term(), pid()) :: :ok

Removes a process from a group

Link to this function members(group) 
members(term()) :: [pid()]

Gets all the members of a group. Returns a list of pids.

Link to this function multi_call(group, msg) 
multi_call(term(), term()) :: [any()]

Calls each process in a group, and collects the results into a list. The order of the results is not guaranteed. Calls are made via GenServer.call/2, so process will need to handle a message in that format.

Link to this function multi_call(group, msg, timeout) 
multi_call(term(), term(), pos_integer()) :: [any()]

Same as multi_call/2, except allows for a configurable timeout. The timeout is per-call, but since all calls are done in parallel, this is effectively the absolute timeout as well.

Link to this function publish(group, msg) 
publish(term(), term()) :: :ok

Publishes a message to a group. This is done via Kernel.send/2, so GenServers and the like will receive it via handle_info/2.

Link to this function register_name(name, pid) 
register_name(term(), pid()) :: :yes | :no

Registers the given name to the given pid, however names registered this way will not be shifted when the cluster topology changes, but this allows you to use :swarm as a distributed process registry, including registering names with {:via, :swarm, name}.

Link to this function register_name(name, m, f, a, timeout \\ :infinity) 
register_name(term(), atom(), atom(), [term()], non_neg_integer() | :infinity) ::
  {:ok, pid()} | {:error, term()}

Similar to register_name/2, except this version takes module/function/args parameters, 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.

This version also returns an ok tuple with the pid if it registers successfully, or an error tuple if registration fails. You cannot use this with processes which are already started, it must be started by :swarm.

A call to Swarm.register_name/5 will return {:error, :no_node_available} when the configured distribution strategy returns :undefined as the node to host the named process. This indicates that there are too few nodes available to start a process. You can retry the name registration while waiting for nodes to join the cluster.

Provide an optional :timeout value to limit the duration of register name calls. The default value is :infinity to block indefinitely.

Link to this function registered() 
registered() :: [{name :: term(), pid()}]

Gets a list of all registered names and their pids

Link to this function send(name, msg) 
send(term(), term()) :: :ok

This is primarily here for use by the standard library facilities for sending messages to a process, e.g. by GenServer.cast/2. It sends a message to a process by name, using Kernel.send/2.

Link to this function start(type, args)

Starts the Swarm application. You should not need to do this unless you are manually handling Swarm’s application lifecycle.

Link to this function unregister_name(name) 
unregister_name(term()) :: :ok

Unregisters the given name from the registry.

Link to this function whereis_name(name) 
whereis_name(term()) :: pid() | :undefined

Get the pid of a registered name.

Link to this function whereis_or_register_name(name, m, f, a, timeout \\ :infinity) 
whereis_or_register_name(
  term(),
  atom(),
  atom(),
  [term()],
  non_neg_integer() | :infinity
) :: {:ok, pid()} | {:error, term()}

Either finds the named process in the swarm or registers it using the register function.