From 3d70cee4034e4da37d125679345aa2a10c58cb34 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Tue, 14 Apr 2015 23:21:36 +0200 Subject: Update Kernel documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Language cleaned up by technical writers from Combitech. Proofreading and corrections by Björn Gustavsson and Hans Bolinder. --- lib/kernel/doc/src/net_kernel.xml | 277 ++++++++++++++++++++------------------ 1 file changed, 143 insertions(+), 134 deletions(-) (limited to 'lib/kernel/doc/src/net_kernel.xml') diff --git a/lib/kernel/doc/src/net_kernel.xml b/lib/kernel/doc/src/net_kernel.xml index 311e0d8ea4..2d52adc2eb 100644 --- a/lib/kernel/doc/src/net_kernel.xml +++ b/lib/kernel/doc/src/net_kernel.xml @@ -25,41 +25,47 @@ net_kernel Claes Wikstrom 1 - 96-09-10 + 1996-09-10 A net_kernel - Erlang Networking Kernel + Erlang networking kernel.

The net kernel is a system process, registered as - net_kernel, which must be running for distributed Erlang + net_kernel, which must be operational 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 +

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

-
$ erl -sname foobar
+ 
+$ 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]).
+    
+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
+    
If the node is started with command-line flag -sname,
+      the node name is 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).

+      If started with flag -name, the node name is foobar@Host,
+      where Host is the fully qualified domain name.
+      For more information, see
+      erl.

     
Normally, connections are established automatically when
       another node is referenced. This functionality can be disabled
-      by setting the Kernel configuration parameter
+      by setting Kernel configuration parameter
       dist_auto_connect to false, see
-      kernel(6). In this case,
+      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.

+      connect_node/1.

+    
Which nodes that are allowed to communicate with each other is handled
+      by the magic cookie system, see section
+      Distributed Erlang
+      in the Erlang Reference Manual.

   
+
   
     
       
@@ -77,237 +83,240 @@
           an atom.

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

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

+      
+    
+
+    
+      
+      Get net_ticktime.
+      
+        
Gets net_ticktime (see
+          kernel(6)).

+        
Defined return values (Res):

+        
+          NetTicktime
+          
net_ticktime is NetTicktime
+            seconds.

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

+          ignored
+          
The local node is not alive.

+        
       
     
+
     
       
       
-      Subscribe to node status change messages
+      Subscribe to node status change messages.
       
         
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
+          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
+        
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
+        
As from 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.
+          
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.

         
-        
Note, that this is not guaranteed for kernel
+        
Notice 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
+        
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 of kernel version 2.13, and erts version
+        
As from 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 from
-	  erlang:nodes/X.
-          nodedown messages will be delivered after the
-	  corresponding node has disappeared in results from
-	  erlang:nodes/X.
+          
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.

         
-        
Note, that this is not guaranteed for kernel
+        
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:

+          Options. If Options is
+          [], which is the default, the format is as follows:

         
 {nodeup, Node} | {nodedown, Node}
   Node = node()
-        
If Options /= [], the format is:

+        
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
+        
Also, when OptionList == [], only visible nodes, that
           is, nodes that appear in the result of
-          nodes/0, are
-          monitored.

+          erlang:nodes/0,
+          are monitored.

         
Option can be any of the following:

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

+            
Valid values for NodeType:

             
               visible
-              Subscribe to node status change messages for visible
+              
Subscribe to node status change messages for visible
                nodes only. The tuple {node_type, visible} is
-               included in InfoList.
+               included in InfoList.

               hidden
-              Subscribe to node status change messages for hidden
+              
Subscribe to node status change messages for hidden
                nodes only. The tuple {node_type, hidden} is
-               included in InfoList.
+               included in InfoList.

               all
-              Subscribe to node status change messages for both
+              
Subscribe to node status change messages for both
                visible and hidden nodes. The tuple
-              {node_type, visible | hidden} is included in
-              InfoList.
+               {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:

+              InfoList in nodedown messages.

+            
Reason can be any of the following:

             
               connection_setup_failed
-              The connection setup failed (after nodeup
-               messages had been sent).
+              
The connection setup failed (after nodeup
+                messages were sent).

               no_network
-              No network available.
+              
No network is available.

               net_kernel_terminated
-              The net_kernel process terminated.
+              
The net_kernel process terminated.

               shutdown
-              Unspecified connection shutdown.
+              
Unspecified connection shutdown.

               connection_closed
-              The connection was closed.
+              
The connection was closed.

               disconnect
-              The connection was disconnected (forced from the
-               current node).
+              
The connection was disconnected (forced from the
+                current node).

               net_tick_timeout
-              Net tick timeout.
+              
Net tick time-out.

               send_net_tick_failed
-              Failed to send net tick over the connection.
+              
Failed to send net tick over the connection.

               get_status_failed
-              Status information retrieval from the Port
-               holding the connection failed.
+              
Status information retrieval from the Port
+                holding the connection failed.

             
           
         
       
     
-    
-      
-      Get net_ticktime
-      
-        
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.

-          
-          ignored
-          
-            
The local node is not alive.

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

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

-          
+          Minimum transition traffic interval (MTTI)
+          
minimum(NetTicktime,
+            PreviousNetTicktime)*1000 div 4 milliseconds.

+          Transition period
+          
The time of the least number of consecutive MTTIs
+            to cover TransitionPeriod seconds following
+            the call to set_net_ticktime/2 (that is,
+            ((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
+        
If
+          ,
+          the net_ticktime change is done at the end of
+          the transition period; otherwise at the beginning. During
+          the transition period, net_kernel ensures that
+          there is outgoing traffic on all connections at least
           every MTTI millisecond.

         
-          
The net_ticktime changes have to be initiated on all
+          
The net_ticktime changes must 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.

+            otherwise connections can erroneously be disconnected.

         
         
Returns one of the following:

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

+            
net_ticktime already has the value of
+              NetTicktime and is left unchanged.

           
           change_initiated
           
-            
net_kernel has initiated the change of
-              net_ticktime to NetTicktime seconds.

+            
net_kernel initiated the change of
+              net_ticktime to NetTicktime
+              seconds.

           
           {ongoing_change_to, NewNetTicktime}
           
-            
The request was ignored; because,
-              net_kernel was busy changing net_ticktime to
+            
The request is ignored because
+              net_kernel is busy changing net_ticktime to
               NewNetTicktime seconds.

           
         
       
     
+
     
       start([Name]) -> {ok, pid()} | {error, Reason}
       start([Name, NameType]) -> {ok, pid()} | {error, Reason}
       start([Name, NameType, Ticktime]) -> {ok, pid()} | {error, Reason}
-      Turn an Erlang runtime system into a distributed node
+      Turn an Erlang runtime system into a distributed node.
       
         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.

+        
Notice that the argument is a list with exactly one, two, or
+          three arguments. NameType defaults to longnames
+          and Ticktime to 15000.

       
     
+
     
       
-      Turn a node into a non-distributed Erlang runtime system
+      Turn a node into a non-distributed Erlang runtime system.
       
         
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.

+          going down. Only possible when the net kernel was started using
+          start/1,
+          otherwise {error, not_allowed} is returned. Returns
+          {error, not_found} if the local node is not alive.

       
     
   
-- 
cgit v1.2.3