net_kernel

net_kernel

Erlang Networking Kernel

The net kernel is a system process which must be running for distributed Erlang to work. The purpose of this process is to implement parts of the BIFs spawn/4 and spawn_link/4, and to provide authentication and monitoring of the network.

An Erlang runtime system can be started from the UNIX command line as follows:

      % erl -name foobar
    

With this command line, the net_kernel is started as net_kernel:start([foobar]). See erl(1).

This is done by the system itself, but the start([Name]) function can also be called directly from the normal Erlang shell prompt, and a normal Erlang runtime system is then converted to a node. The kernel can be shut down with the function stop(), but only if the kernel was not started by the system itself. The node is then converted into a normal Erlang runtime system. All other nodes on the network will regard this as a total node crash.

If the system is started as % erl -sname foobar, the node name of the node will be foobar@Host, where Host is the short name of the host (not the fully qualified domain name). The -name flag gives a node with the fully qualified domain name. See erl(1).

The system can be started with the flag -dist_auto_connect to control automatic connection of remote nodes. See connect_node/1 below and erl(1).

Types:

The process evaluating monitor_nodes/2 subscribes or unsubscribes for nodeup/nodedown messages. nodeup messages are delivered to all processes that have subscribed for nodeup/nodedown messages when a new node is connected, and nodedown messages are delivered when a node is disconnected.

If Flag is true, a new subscription is made. If Flag is false, all previous subscriptions with the same OptionList are unsubscribed. Two option lists are considered the same if lists:usort/1 on the two lists evaluates to terms that are equal.

If OptionList == [] when subscribing, {nodeup, Node}, and {nodedown, Node} messages will be delivered; otherwise, {nodeup, Node, InfoList}, and {nodedown, Node, InfoList} messages will be delivered. Where:

• Node = atom() (the nodename)
• InfoList = [{atom(), term()}]

Also, when OptionList == [] only visible nodes, i.e. nodes that appear in the result of nodes/0 and the current node, are monitored.

Currently the following Options are valid:

{node_type, NodeType}

Currently valid NodeTypes are:

visible

nodeup and nodedown messages will be delivered when visible nodes connect/disconnect. A {node_type, visible} tuple will be part of the InfoList element.

hidden

nodeup and nodedown messages will be delivered when hidden nodes connect/disconnect. A {node_type, hidden} tuple will be part of the InfoList element.

all

nodeup and nodedown messages will be delivered when a node connect/disconnect. A {node_type, visible} tuple will be part of the InfoList element when the node is visible, and a {node_type, hidden} tuple will be part of the InfoList element when the node is hidden.

nodedown_reason

A {nodedown_reason, Reason} tuple will be part of the InfoList element in nodedown messages. Reason can currently be:

connection_setup_failed

The connection setup failed (after nodeup messages had been sent).

no_network

No network 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

No traffic from the connected node during net_ticktime seconds.

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.

Types:

The same as evaluating net_kernel:monitor_nodes(Flag, []).

In a simple way, this function limits access to a node from a specific number of named nodes. A node which evaluates this function can only be accessed from nodes listed in the NodeList variable. Any access attempts made from nodes not listed in NodeList are rejected.

Explicitly establishes a connection to the node specified by the atom Node. Returns true if successful, false if not, and ignored if net_kernel is not started.

This function is only necessary if the system is started with the flag -dist_auto_connect. See erl(1).

Types:

Sets net_ticktime (see kernel(6)) to NetTicktime seconds.

Some definitions:

The minimum transition traffic interval (MTTI)

minimum(NetTicktime, PreviousNetTicktime)*1000 div 4 milliseconds.

The transition period

The time of the least number of consecutive MTTIs to cover TransitionPeriod seconds following the call to set_net_ticktime() (i.e. ((TransitionPeriod*1000 - 1) div MTTI + 1)*MTTI milliseconds).

If NetTicktime < PreviousNetTicktime, the actual net_ticktime change will be done at the end of the transition period; otherwise, at the beginning. During the transition period the net_kernel will ensure that there will be outgoing traffic on all connections at least every MTTI millisecond.

The net_ticktime changes have to be initiated on all nodes in the network (with the same NetTicktime) before the end of any transition period on any node; otherwise, connections may erroneously be disconnected.

Currently defined return values (Res):

unchanged

The net_ticktime already had the value of NetTicktime and was left unchanged.

change_initiated

The net_kernel has initiated the change of the net_ticktime to NetTicktime seconds.

{ongoing_change_to, NewNetTicktime}

The request was ignored; because, the net_kernel was busy changing the net_ticktime to NewTicktime seconds.

Types:

The same as the call set_net_ticktime(NetTicktime, 60).

Types:

Gets the net_ticktime.

Currently defined return values (Res):

NetTicktime

The net_ticktime is NetTicktime seconds.

{ongoing_change_to, NetTicktime}

The net_kernel is currently changing the net_ticktime to NetTicktime seconds.

Claes Wikstrom - support@erlang.ericsson.se
Rickard Green - support@erlang.ericsson.se