The R13B03 release.OTP_R13B03

1 files changed, 217 insertions, 0 deletions

diff --git a/system/doc/design_principles/distributed_applications.xml b/system/doc/design_principles/distributed_applications.xml
new file mode 100644
index 0000000000..39a24b3598
--- /dev/null
+++ b/system/doc/design_principles/distributed_applications.xml
@@ -0,0 +1,217 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>2003</year><year>2009</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+    
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+    
+    </legalnotice>
+
+    <title>Distributed Applications</title>
+    <prepared></prepared>
+    <docno></docno>
+    <date></date>
+    <rev></rev>
+    <file>distributed_applications.xml</file>
+  </header>
+
+  <section>
+    <title>Definition</title>
+    <p>In a distributed system with several Erlang nodes, there may be
+      a need to control applications in a distributed manner. If
+      the node, where a certain application is running, goes down,
+      the application should be restarted at another node.</p>
+    <p>Such an application is called a <em>distributed application</em>.
+      Note that it is the control of the application which is
+      distributed, all applications can of course be distributed in
+      the sense that they, for example, use services on other nodes.</p>
+    <p>Because a distributed application may move between nodes, some
+      addressing mechanism is required to ensure that it can be
+      addressed by other applications, regardless on which node it
+      currently executes. This issue is not addressed here, but the
+      Kernel module <c>global</c> or STDLIB module <c>pg</c> can be
+      used for this purpose.</p>
+  </section>
+
+  <section>
+    <title>Specifying Distributed Applications</title>
+    <p>Distributed applications are controlled by both the application
+      controller and a distributed application controller process,
+      <c>dist_ac</c>. Both these processes are part of the <c>kernel</c>
+      application. Therefore, distributed applications are specified by
+      configuring the <c>kernel</c> application, using the following
+      configuration parameter (see also <c>kernel(6)</c>):</p>
+    <taglist>
+      <tag><c>distributed = [{Application, [Timeout,] NodeDesc}]</c></tag>
+      <item>
+        <p>Specifies where the application <c>Application = atom()</c>
+          may execute. <c>NodeDesc = [Node | {Node,...,Node}]</c> is
+          a list of node names in priority order. The order between
+          nodes in a tuple is undefined.</p>
+        <p><c>Timeout = integer()</c> specifies how many milliseconds to
+          wait before restarting the application at another node.
+          Defaults to 0.</p>
+      </item>
+    </taglist>
+    <p>For distribution of application control to work properly,
+      the nodes where a distributed application may run must contact
+      each other and negotiate where to start the application. This is
+      done using the following <c>kernel</c> configuration parameters:</p>
+    <taglist>
+      <tag><c>sync_nodes_mandatory = [Node]</c></tag>
+      <item>Specifies which other nodes must be started (within
+       the timeout specified by <c>sync_nodes_timeout</c>.</item>
+      <tag><c>sync_nodes_optional = [Node]</c></tag>
+      <item>Specifies which other nodes can be started (within
+       the timeout specified by <c>sync_nodes_timeout</c>.</item>
+      <tag><c>sync_nodes_timeout = integer() | infinity</c></tag>
+      <item>Specifies how many milliseconds to wait for the other nodes
+       to start.</item>
+    </taglist>
+    <p>When started, the node will wait for all nodes specified by
+      <c>sync_nodes_mandatory</c> and <c>sync_nodes_optional</c> to
+      come up. When all nodes have come up, or when all mandatory nodes
+      have come up and the time specified by <c>sync_nodes_timeout</c>
+      has elapsed, all applications will be started. If not all
+      mandatory nodes have come up, the node will terminate.</p>
+    <p>Example: An application <c>myapp</c> should run at the node
+      <c>cp1@cave</c>. If this node goes down, <c>myapp</c> should
+      be restarted at <c>cp2@cave</c> or <c>cp3@cave</c>. A system
+      configuration file <c>cp1.config</c> for <c>cp1@cave</c> could
+      look like:</p>
+    <code type="none">
+[{kernel,
+  [{distributed, [{myapp, 5000, [cp1@cave, {cp2@cave, cp3@cave}]}]},
+   {sync_nodes_mandatory, [cp2@cave, cp3@cave]},
+   {sync_nodes_timeout, 5000}
+  ]
+ }
+].</code>
+    <p>The system configuration files for <c>cp2@cave</c> and
+      <c>cp3@cave</c> are identical, except for the list of mandatory
+      nodes which should be <c>[cp1@cave, cp3@cave]</c> for
+      <c>cp2@cave</c> and <c>[cp1@cave, cp2@cave]</c> for
+      <c>cp3@cave</c>.</p>
+    <note>
+      <p>All involved nodes must have the same value for
+        <c>distributed</c> and <c>sync_nodes_timeout</c>, or
+        the behaviour of the system is undefined.</p>
+    </note>
+  </section>
+
+  <section>
+    <title>Starting and Stopping Distributed Applications</title>
+    <p>When all involved (mandatory) nodes have been started,
+      the distributed application can be started by calling
+      <c>application:start(Application)</c> at <em>all of these nodes.</em></p>
+    <p>It is of course also possible to use a boot script (see
+      <seealso marker="release_structure">Releases</seealso>) which
+      automatically starts the application.</p>
+    <p>The application will be started at the first node, specified
+      by the <c>distributed</c> configuration parameter, which is up
+      and running. The application is started as usual. That is, an
+      application master is created and calls the application callback
+      function:</p>
+    <code type="none">
+Module:start(normal, StartArgs)</code>
+    <p>Example: Continuing the example from the previous section,
+      the three nodes are started, specifying the system configuration
+      file:</p>
+    <pre>
+> <input>erl -sname cp1 -config cp1</input>
+> <input>erl -sname cp2 -config cp2</input>
+> <input>erl -sname cp3 -config cp3</input></pre>
+    <p>When all nodes are up and running, <c>myapp</c> can be started.
+      This is achieved by calling <c>application:start(myapp)</c> at
+      all three nodes. It is then started at <c>cp1</c>, as shown in
+      the figure below.</p>
+    <marker id="dist1"></marker>
+    <image file="../design_principles/dist1.gif">
+      <icaption>Application myapp - Situation 1</icaption>
+    </image>
+    <p>Similarly, the application must be stopped by calling
+      <c>application:stop(Application)</c> at all involved nodes.</p>
+  </section>
+
+  <section>
+    <title>Failover</title>
+    <p>If the node where the application is running goes down,
+      the application is restarted (after the specified timeout) at
+      the first node, specified by the <c>distributed</c> configuration
+      parameter, which is up and running. This is called a
+      <em>failover</em>.</p>
+    <p>The application is started the normal way at the new node,
+      that is, by the application master calling:</p>
+    <code type="none">
+Module:start(normal, StartArgs)</code>
+    <p>Exception: If the application has the <c>start_phases</c> key
+      defined (see <seealso marker="included_applications">Included Applications</seealso>), then the application is instead started
+      by calling:</p>
+    <code type="none">
+Module:start({failover, Node}, StartArgs)</code>
+    <p>where <c>Node</c> is the terminated node.</p>
+    <p>Example: If <c>cp1</c> goes down, the system checks which one of
+      the other nodes, <c>cp2</c> or <c>cp3</c>, has the least number of
+      running applications, but waits for 5 seconds for <c>cp1</c> to
+      restart. If <c>cp1</c> does not restart and <c>cp2</c> runs fewer
+      applications than <c>cp3,</c> then <c>myapp</c> is restarted on
+      <c>cp2</c>.</p>
+    <marker id="dist2"></marker>
+    <image file="../design_principles/dist2.gif">
+      <icaption>Application myapp - Situation 2</icaption>
+    </image>
+    <p>Suppose now that <c>cp2</c> goes down as well and does not
+      restart within 5 seconds. <c>myapp</c> is now restarted on
+      <c>cp3</c>.</p>
+    <marker id="dist3"></marker>
+    <image file="../design_principles/dist3.gif">
+      <icaption>Application myapp - Situation 3</icaption>
+    </image>
+  </section>
+
+  <section>
+    <title>Takeover</title>
+    <p>If a node is started, which has higher priority according
+      to <c>distributed</c>, than the node where a distributed
+      application is currently running, the application will be
+      restarted at the new node and stopped at the old node. This is
+      called a <em>takeover</em>.</p>
+    <p>The application is started by the application master calling:</p>
+    <code type="none">
+Module:start({takeover, Node}, StartArgs)</code>
+    <p>where <c>Node</c> is the old node.</p>
+    <p>Example: If <c>myapp</c> is running at <c>cp3</c>, and if
+      <c>cp2</c> now restarts, it will not restart <c>myapp</c>,
+      because the order between nodes <c>cp2</c> and <c>cp3</c> is
+      undefined.</p>
+    <marker id="dist4"></marker>
+    <image file="../design_principles/dist4.gif">
+      <icaption>Application myapp - Situation 4</icaption>
+    </image>
+    <p>However, if <c>cp1</c> restarts as well, the function
+      <c>application:takeover/2</c> moves <c>myapp</c> to <c>cp1</c>,
+      because <c>cp1</c> has a higher priority than <c>cp3</c> for this
+      application.  In this case,
+      <c>Module:start({takeover, cp3@cave}, StartArgs)</c> is executed
+      at <c>cp1</c> to start the application.</p>
+    <marker id="dist5"></marker>
+    <image file="../design_principles/dist5.gif">
+      <icaption>Application myapp - Situation 5</icaption>
+    </image>
+  </section>
+</chapter>
+