The calling process subscribes or unsubscribes to node
status change messages. A nodeup message is delivered
to all subscribing processes when a new node is connected, and
a nodedown message is delivered when a node is
disconnected.
If Flag is true, a new subscription is
started. If Flag is false, all previous
subscriptions started with the same Options
are stopped. Two
option lists are considered the same if they contain the same
set of options.
Delivery guarantees of nodeup/nodedown messages:
nodeup messages are delivered before delivery
of any signals from the remote node through the newly
established connection.
-
nodedown messages are delivered after all
the signals from the remote node over the connection
have been delivered.
nodeup messages are delivered after the
corresponding node appears in results from
erlang:nodes().
-
nodedown messages are delivered after the
corresponding node has disappeared in results from
erlang:nodes().
As of OTP 23.0, a nodedown message for a
connection being taken down will be delivered before a
nodeup message due to a new connection to the
same node. Prior to OTP 23.0, this was not
guaranteed to be the case.
The format of the node status change messages depends on
Options. If Options is
the empty list or if net_kernel:monitor_nodes/1 is called,
the format is as follows:
{nodeup, Node} | {nodedown, Node}
Node = node()
When Options is the empty map or empty
list, the caller will only subscribe for status change messages
for visible nodes. That is, only nodes that appear in the
result of
erlang:nodes/0.
If Options equals anything other than the
empty list, the format of the status change messages is as follows:
{nodeup, Node, Info} | {nodedown, Node, Info}
Node = node()
Info = #{Tag => Val} | [{Tag, Val}]
Info is either a map or a list of 2-tuples. Its content
depends on Options. If Options
is a map, Info will also be a map. If Options
is a list, Info will also be a list.
When Options is a map, currently
the following associations are allowed:
- connection_id => boolean()
-
If the value of the association equals true, a
connection_id => ConnectionId association will be
included in the Info map where ConnectionId
is the connection identifier of the connection coming up
or going down. For more info about this connection
identifier see the documentation of
erlang:nodes/2.
- node_type => NodeType
-
Valid values for NodeType:
- visible
Subscribe to node status change messages for visible
nodes only. The association node_type => visible will
be included in the Info map.
- hidden
Subscribe to node status change messages for hidden
nodes only. The association node_type => hidden will
be included in the Info map.
- all
Subscribe to node status change messages for both
visible and hidden nodes. The association
node_type => visible | hidden will be included in
the Info map.
If no node_type => NodeType association
is included in the Options map, the
caller will subscribe for status change messages for visible
nodes only, but no node_type => visible
association will be included in the Info map.
- nodedown_reason => boolean()
-
If the value of the association equals true, a
nodedown_reason => Reason association will be
included in the Info map for nodedown
messages.
Reason can, depending on which
distribution module or process that is used, be any term,
but for the standard TCP distribution module it is
one of the following:
- connection_setup_failed
The connection setup failed (after nodeup
messages were sent).
- no_network
No network is available.
- net_kernel_terminated
The net_kernel process terminated.
- shutdown
Unspecified connection shutdown.
- connection_closed
The connection was closed.
- disconnect
The connection was disconnected (forced from the
current node).
- net_tick_timeout
Net tick time-out.
- send_net_tick_failed
Failed to send net tick over the connection.
- get_status_failed
Status information retrieval from the Port
holding the connection failed.
When Options is a list, currently
ListOption can be one of the following:
- connection_id
-
A {connection_id, ConnectionId} tuple will be
included in Info where ConnectionId is the
connection identifier of the connection coming up or
going down. For more info about this connection identifier
see the documentation of
erlang:nodes/2.
- {node_type, NodeType}
-
Valid values for NodeType:
- visible
Subscribe to node status change messages for visible
nodes only. The tuple {node_type, visible} will be
included in the Info list.
- hidden
Subscribe to node status change messages for hidden
nodes only. The tuple {node_type, hidden} will be
included in the Info list.
- all
Subscribe to node status change messages for both
visible and hidden nodes. The tuple
{node_type, visible | hidden} will be included in
the Info list.
If no {node_type, NodeType} option
has been given. The caller will subscribe for status
change messages for visible nodes only, but no
{node_type, visible} tuple will be included in the
Info list.
- nodedown_reason
-
The tuple {nodedown_reason, Reason} will be included
in the Info list for nodedown messages.
See the documentation of the
nodedown_reason
=> boolean() association above for information
about possible Reason values.
Example:
(a@localhost)1> net_kernel:monitor_nodes(true, #{connection_id=>true, node_type=>all, nodedown_reason=>true}).
ok
(a@localhost)2> flush().
Shell got {nodeup,b@localhost,
#{connection_id => 3067552,node_type => visible}}
Shell got {nodeup,c@localhost,
#{connection_id => 13892107,node_type => hidden}}
Shell got {nodedown,b@localhost,
#{connection_id => 3067552,node_type => visible,
nodedown_reason => connection_closed}}
Shell got {nodedown,c@localhost,
#{connection_id => 13892107,node_type => hidden,
nodedown_reason => net_tick_timeout}}
Shell got {nodeup,b@localhost,
#{connection_id => 3067553,node_type => visible}}
ok
(a@localhost)3>