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.
As from Kernel version 2.11.4, and ERTS version 5.5.4, the following is guaranteed:
nodeup
messages are delivered before delivery of any message from the remote node passed through the newly established connection.
nodedown
messages are not delivered until all messages from the remote node that have been passed through the connection have been delivered.
Notice that this is not guaranteed for Kernel versions before 2.11.4.
As from Kernel version 2.11.4, subscriptions can also be made before the net_kernel
server is started, that is, net_kernel:monitor_nodes/[1,2]
does not return ignored
.
As from Kernel version 2.13, and ERTS version 5.7, the following is guaranteed:
nodeup
messages are delivered after the corresponding node appears in results from erlang:nodes/X
.
nodedown
messages are delivered after the corresponding node has disappeared in results from erlang:nodes/X
.
Notice that this is not guaranteed for Kernel versions before 2.13.
The format of the node status change messages depends on Options
. If Options
is []
, which is the default, the format is as follows:
{nodeup, Node} | {nodedown, Node}
Node = node()
If Options
is not []
, the format is as follows:
{nodeup, Node, InfoList} | {nodedown, Node, InfoList}
Node = node()
InfoList = [{Tag, Val}]
InfoList
is a list of tuples. Its contents depends on Options
, see below.
Also, when OptionList == []
, only visible nodes, that is, nodes that appear in the result of erlang:nodes/0
, are monitored.
Option
can be any of the following:
-
{node_type, NodeType}
-
Valid values for NodeType
:
-
visible
-
Subscribe to node status change messages for visible nodes only. The tuple {node_type, visible}
is included in InfoList
.
-
hidden
-
Subscribe to node status change messages for hidden nodes only. The tuple {node_type, hidden}
is included in InfoList
.
-
all
-
Subscribe to node status change messages for both visible and hidden nodes. The tuple {node_type, visible | hidden}
is included in InfoList
.
-
nodedown_reason
-
The tuple {nodedown_reason, Reason}
is included in InfoList
in 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 any 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.