DistributedSupervisor (distributed_supervisor v0.5.4)

View Source

DistributedSupervisor is exactly what its name says. It’s a DynamicSupervisor working transparently in a distributed environment.

Example

iex|🌢|n1@am|1> DistributedSupervisor.start_link(name: DS, cache_children?: true)
{:ok, #PID<0.307.0>}
iex|🌢|n1@am|2> DistributedSupervisor.start_child(DS, {MyGenServer, name: MGS})
{:ok, #PID<0.311.0>, MGS}
iex|🌢|n1@am|3> DistributedSupervisor.children(DS)
%{MGS => {#PID<0.311.0>, %{id: }}}

Summary

Types

The id of the child process within the instance of the distributed supervisor. Might be whatever. If not passed explicitly to the DistributedSupervisor.start_child/2, the reference will be created automatically and returned as a third element of the {:ok, pid, child_name} success tuple.

The name of the instance of this distributed supervisor. Unlike GenServer.name/0, it must be an atom.

Functions

A syntactic sugar for GenServer.call/3 allowing to call a dynamically supervised GenServer by registry name and key.

A syntactic sugar for GenServer.cast/2 allowing to call a dynamically supervised GenServer by registry name and key.

Returns a specification to start this module under a supervisor.

Returns a map with registered names as keys and pids as values for the instance of the registry with a name name.

Returns a list of pids of local children

Returns true if called from a node assigned to this key, false otherwise

Returns the node for the key given according to a HashRing

Returns the list of nodes operated by a registered ring

A syntactic sugar for Kernel.send/2 allowing to send a message to a dynamically supervised GenServer identified by registry name and key.

Dynamically adds a child specification to supervisor and starts that child.

Terminates the given child identified by pid.

Returns a fully qualified name to use with a standard library functions, accepting {:via, Registry, key} as a GenServer name.

Returns a t:pid() for the instance of the registry with a name name by key.

Returns a registered name by a t:pid() given.

Types

id()

@type id() :: term()

The id of the child process within the instance of the distributed supervisor. Might be whatever. If not passed explicitly to the DistributedSupervisor.start_child/2, the reference will be created automatically and returned as a third element of the {:ok, pid, child_name} success tuple.

name()

@type name() :: atom()

The name of the instance of this distributed supervisor. Unlike GenServer.name/0, it must be an atom.

Functions

call(name, child, msg, timeout \\ 5000)

@spec call(name(), id(), msg, timeout()) :: result when msg: term(), result: term()

A syntactic sugar for GenServer.call/3 allowing to call a dynamically supervised GenServer by registry name and key.

cast(name, child, msg)

@spec cast(name(), id(), msg) :: :ok when msg: term()

A syntactic sugar for GenServer.cast/2 allowing to call a dynamically supervised GenServer by registry name and key.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

children(name)

@spec children(name()) ::
  %{optional(term()) => {pid(), Supervisor.child_spec()}}
  | [
      {:undefined, pid() | :restarting, :worker | :supervisor,
       [module()] | :dynamic}
    ]

Returns a map with registered names as keys and pids as values for the instance of the registry with a name name.

local_children(name)

@spec local_children(name()) :: [pid()]

Returns a list of pids of local children

mine?(name, key)

Returns true if called from a node assigned to this key, false otherwise

node_for(name, key)

Returns the node for the key given according to a HashRing

nodes(name)

Returns the list of nodes operated by a registered ring

send(name, child, msg)

@spec send(name(), id(), msg) :: msg | nil when msg: term()

A syntactic sugar for Kernel.send/2 allowing to send a message to a dynamically supervised GenServer identified by registry name and key.

start_child(name, spec, node \\ nil)

@spec start_child(name(), Supervisor.child_spec() | {module(), term()}, node() | nil) ::
  DynamicSupervisor.on_start_child()

Dynamically adds a child specification to supervisor and starts that child.

child_spec should be a valid child specification as detailed in the “Child specification” section of the documentation for Supervisor expressed as a Supervisor.child_spec/0 or as a tuple {module, start_link_arg}.

The child process will be started as defined in the child specification. The core difference from DynamicSupervisor is that the process must be named. The name might be any term, passed through name: option in a call to this function. If name option is not passed, it gets assigned randomly and returned in the third element of the tuple from start_child/2.

This function accepts an optional third argument node. If it’s passed, the process will be started on that node; the node will be chosed according to a keyring otherwise.

See: DynamicSupervisor.start_child/2

start_link(opts \\ [])

Starts the DistributedSupervisor.

  • :name (atom/0) - Required. The unique ID of this DistributedSupervisor, that will be used to address it, similar to DynamicSupervisor.name()

  • :cache_children? (boolean/0) - If true, Registry will cache children as a map of %{name => %{pid() => initial_params}}, setting this to false would block the functionañity of restarting a process on another node when any node goes down The default value is true.

  • :nodes (list of atom/0) - The hardcoded list of nodes to spread children across, if not passed, all connected nodes will be used The default value is [].

  • :monitor_nodes (atom/0) - If not false, the HashRing will be automatically updated when nodes are changed in the cluster The default value is false.

  • :listeners - The implementation of DistributedSupervisor.Listener to receive notifications upon process restarts The default value is [].

terminate_child(name, pid)

@spec terminate_child(name(), pid() | nil) :: :ok | {:error, :not_found}

Terminates the given child identified by pid.

If successful, this function returns :ok. If there is no process with the given PID, this function returns {:error, :not_found}.

See: DynamicSupervisor.terminate_child/2

via_name(name, id)

@spec via_name(name(), id()) :: {:via, module(), {name(), id()}}

Returns a fully qualified name to use with a standard library functions, accepting {:via, Registry, key} as a GenServer name.

whereis(name, child)

@spec whereis(name(), id()) :: pid() | nil

Returns a t:pid() for the instance of the registry with a name name by key.

See: DistributedSupervisor.children/1

whois(name, pid)

@spec whois(name(), pid()) :: name() | nil

Returns a registered name by a t:pid() given.

See: DistributedSupervisor.children/1