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
.
Which nodes are allowed to communicate with each other is handled by the magic cookie system, see Distributed Erlang in the Erlang Reference Manual.
Functions
allow(Nodes) -> ok | error
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(Node) -> true | false | ignored
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 | Error
monitor_nodes(Flag, Options) -> ok | Error
Flag = true | false
Options = [Option]
Option -- see below
Error = error | {error, term()}
The calling process subscribes or unsubscribes 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.
As of kernel
version 2.11.4, and erts
version
5.5.4, the following is guaranteed:
nodeup
messages will be delivered before delivery of any message from the remote node passed through the newly established connection.nodedown
messages will not be delivered until all messages from the remote node that have been passed through the connection have been delivered.
Note, that this is not guaranteed for kernel
versions before 2.11.4.
As of kernel
version 2.11.4 subscriptions can also be
made before the net_kernel
server has been started,
i.e., net_kernel:monitor_nodes/[1,2]
does not return
ignored
.
As of kernel
version 2.13, and erts
version
5.7, the following is guaranteed:
nodeup
messages will be delivered after the corresponding node appears in results fromerlang:nodes/X
.nodedown
messages will be delivered after the corresponding node has disappeared in results fromerlang:nodes/X
.
Note, 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:
{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 inInfoList
. hidden
- Subscribe to node status change messages for hidden
nodes only. The tuple
{node_type, hidden}
is included inInfoList
. all
- Subscribe to node status change messages for both
visible and hidden nodes. The tuple
{node_type, visible | hidden}
is included inInfoList
.
nodedown_reason
-
The tuple
{nodedown_reason, Reason}
is included inInfoList
innodedown
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
Res = NetTicktime | {ongoing_change_to, NetTicktime}
NetTicktime = int()
Gets net_ticktime
(see
kernel(6)).
Currently defined return values (Res
):
NetTicktime
-
net_ticktime
isNetTicktime
seconds. {ongoing_change_to, NetTicktime}
-
net_kernel
is currently changingnet_ticktime
toNetTicktime
seconds.
set_net_ticktime(NetTicktime) -> Res
set_net_ticktime(NetTicktime, TransitionPeriod) -> Res
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
MTTI
s to coverTransitionPeriod
seconds following the call toset_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!
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.
Returns one of the following:
unchanged
-
net_ticktime
already had the value ofNetTicktime
and was left unchanged. change_initiated
-
net_kernel
has initiated the change ofnet_ticktime
toNetTicktime
seconds. {ongoing_change_to, NewNetTicktime}
-
The request was ignored; because,
net_kernel
was busy changingnet_ticktime
toNewTicktime
seconds.
start([Name]) -> {ok, pid()} | {error, Reason}
start([Name, NameType]) -> {ok, pid()} | {error, Reason}
start([Name, NameType, Ticktime]) -> {ok, pid()} | {error, Reason}
Name = atom()
NameType = shortnames | longnames
Reason = {already_started, pid()} | term()
Note that the argument is a list with exactly one, two or
three arguments. NameType
defaults to longnames
and Ticktime
to 15000.
Turns a non-distributed node into a distributed node by
starting net_kernel
and other necessary processes.
stop() -> ok | {error, not_allowed | not_found}
Turns a distributed node into a non-distributed node. For
other nodes in the network, this is the same as the node
going down. Only possible when the net kernel was started
using start/1
, otherwise returns
{error, not_allowed}
. Returns {error, not_found}
if the local node is not alive.