net_kernel(3)

MODULE
net_kernel - Erlang Networking Kernel

DESCRIPTION

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).

EXPORTS

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

    Types
        Flag = true | false
        OptionList = [Option]
        Option = atom() | {atom(), term()}
        Error = error | {error, term()}

    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.

monitor_nodes(Flag) -> ok | ignored | Error

    Types
        Flag = atom()
        Error = error | {error, term()}

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

allow(NodeList)

    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.

connect_node(Node)

    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).

set_net_ticktime(NetTicktime, TransitionPeriod) -> Res

    Types
        NetTicktime = integer() (> 0)
        TransitionPeriod = integer() (>= 0)
        Res = atom() | {atom(), integer()}

    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.

  Note:

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.

set_net_ticktime(NetTicktime) -> Res

    Types
        NetTicktime = integer()
        Res = atom() | {atom(), integer()}

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

get_net_ticktime() -> Res

    Types
        Res = integer() | {atom(), integer()}

    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.

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