swarm v2.0.1 Swarm

This is the public Elixir API for :swarm.

Summary

Functions

Joins a process to a group

Removes a process from a group

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

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

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

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

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}

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 it’s new node using the given MFA

Gets a list of all registered names and their pids

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

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

Unregisters the given name from the registry

Get the pid of a registered name

Functions

join(group, pid)

Specs

join(term, pid) :: :ok

Joins a process to a group

leave(group, pid)

Specs

leave(term, pid) :: :ok

Removes a process from a group

members(group)

Specs

members(term) :: [pid]

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

multi_call(group, msg)

Specs

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.

multi_call(group, msg, timeout)

Specs

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.

publish(group, msg)

Specs

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.

register_name(name, pid)

Specs

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

register_name(name, m, f, a)

Specs

register_name(term, atom, atom, [term]) ::
  {: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 it’s 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.

registered()

Specs

registered :: [{name :: term, pid}]

Gets a list of all registered names and their pids

send(name, msg)

Specs

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.

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)

Specs

unregister_name(term) :: :ok

Unregisters the given name from the registry.

whereis_name(name)

Specs

whereis_name(term) :: pid | :undefined

Get the pid of a registered name.