net_kernel - Erlang Networking Kernel

The net kernel is a system process, registered as net_kernel, 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 monitoring of the network.

An Erlang node is started using the command line flag -name or -sname:

$erl -sname foobar

It is also possible to call net_kernel:start([foobar]) directly from the normal Erlang shell prompt:

1>net_kernel:start([foobar, shortnames]).

{ok,<0.64.0>} (foobar@gringotts)2>

If the node is started with the command line flag -sname, the node name will be foobar@Host, where Host is the short name of the host (not the fully qualified domain name). If started with the -name flag, Host is the fully qualified domain name. See erl(1).

Normally, connections are established automatically when another node is referenced. This functionality can be disabled by setting the Kernel configuration parameter dist_auto_connect to false, see kernel(6). In this case, connections must be established explicitly by calling net_kernel:connect_node/1.

allow(N) -> ok | error

Types

Nodes = [node()]

Limits access to the specified set of nodes. Any access attempts made from (or to) nodes not in Nodes will be rejected.

Returns error if any element in Nodes is not an atom.

connect_node(N) -> true | false | ignored

Types

Node = node()

Establishes a connection to Node. Returns true if successful, false if not, and ignored if the local node is not alive.

monitor_nodes(Flag) -> ok | ignored | Error

monitor_nodes(Flag, Options) -> ok | ignored | Error

Types

Flag = true | false

Options = [Option]

 Option -- see below

Error = error | {error, term()}

The calling process subscribes or unsubcscribes to node status change messages. A nodeup message is delivered to all subscribing process 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.

The format of the node status change messages depends on Options. If Options is [], which is the default, the format is:

{nodeup, Node} | {nodedown, Node}
  Node = node()

If Options /= [], the format is:

{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 nodes/0, are monitored.

Option can be any of the following:

{node_type, NodeType}: Currently valid values for NodeType are:

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 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: Net tick timeout.

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.

get_net_ticktime() -> Res

Types

Res = NetTicktime | {ongoing_change_to, NetTicktime}

 NetTicktime = int()

Gets net_ticktime (see kernel(6)).

Currently defined return values (Res):

NetTicktime: net_ticktime is NetTicktime seconds.

{ongoing_change_to, NetTicktime}: net_kernel is currently changing net_ticktime to NetTicktime seconds.

set_net_ticktime(N) -> Res

set_net_ticktime(NetTicktime, TransitionPeriod) -> Res

Types

NetTicktime = int() > 0

TransitionPeriod = int() >= 0

Res = unchanged | change_initiated | {ongoing_change_to, NewNetTicktime}

 NewNetTicktime = int() > 0

Sets net_ticktime (see kernel(6)) to NetTicktime seconds. TransitionPeriod defaults to 60.

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/2 (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, net_kernel will ensure that there will be outgoing traffic on all connections at least every MTTI millisecond.

Note:

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