diff options
Diffstat (limited to 'system/doc/getting_started/robustness.xml')
| -rw-r--r-- | system/doc/getting_started/robustness.xml | 174 |
1 files changed, 90 insertions, 84 deletions
diff --git a/system/doc/getting_started/robustness.xml b/system/doc/getting_started/robustness.xml index c141530fe0..6932f0ca0f 100644 --- a/system/doc/getting_started/robustness.xml +++ b/system/doc/getting_started/robustness.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> <header> <copyright> - <year>2003</year><year>2010</year> + <year>2003</year><year>2016</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. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> @@ -28,27 +29,27 @@ <rev></rev> <file>robustness.xml</file> </header> - <p>There are several things which are wrong with - the <seealso marker="conc_prog#ex">messenger example</seealso> from - the previous chapter. For example if a node where a user is logged - on goes down without doing a log off, the user will remain in - the server's <c>User_List</c> but the client will disappear thus - making it impossible for the user to log on again as the server - thinks the user already logged on.</p> + <p>Several things are wrong with the messenger example in + <seealso marker="conc_prog#ex">A Larger Example</seealso>. + For example, if a node where a user is logged + on goes down without doing a logoff, the user remains in + the server's <c>User_List</c>, but the client disappears. This + makes it impossible for the user to log on again as the server + thinks the user already is logged on.</p> <p>Or what happens if the server goes down in the middle of sending a - message leaving the sending client hanging for ever in + message, leaving the sending client hanging forever in the <c>await_result</c> function?</p> <section> - <title>Timeouts</title> - <p>Before improving the messenger program we will look into some + <title>Time-outs</title> + <p>Before improving the messenger program, let us look at some general principles, using the ping pong program as an example. Recall that when "ping" finishes, it tells "pong" that it has done so by sending the atom <c>finished</c> as a message to "pong" - so that "pong" could also finish. Another way to let "pong" - finish, is to make "pong" exit if it does not receive a message - from ping within a certain time, this can be done by adding a - <em>timeout</em> to <c>pong</c> as shown in the following example:</p> + so that "pong" can also finish. Another way to let "pong" + finish is to make "pong" exit if it does not receive a message + from ping within a certain time. This can be done by adding a + <em>time-out</em> to <c>pong</c> as shown in the following example:</p> <code type="none"> -module(tut19). @@ -80,9 +81,9 @@ start_pong() -> start_ping(Pong_Node) -> spawn(tut19, ping, [3, Pong_Node]).</code> - <p>After we have compiled this and copied the <c>tut19.beam</c> - file to the necessary directories:</p> - <p>On (pong@kosken):</p> + <p>After this is compiled and the file <c>tut19.beam</c> + is copied to the necessary directories, the following is seen + on (pong@kosken): </p> <pre> (pong@kosken)1> <input>tut19:start_pong().</input> true @@ -90,7 +91,7 @@ Pong received ping Pong received ping Pong received ping Pong timed out</pre> - <p>On (ping@gollum):</p> + <p>And the following is seen on (ping@gollum):</p> <pre> (ping@gollum)1> <input>tut19:start_ping(pong@kosken).</input> <0.36.0> @@ -98,7 +99,7 @@ Ping received pong Ping received pong Ping received pong ping finished </pre> - <p>(The timeout is set in:</p> + <p>The time-out is set in:</p> <code type="none"> pong() -> receive @@ -109,35 +110,36 @@ pong() -> after 5000 -> io:format("Pong timed out~n", []) end.</code> - <p>We start the timeout (<c>after 5000</c>) when we enter - <c>receive</c>. The timeout is canceled if <c>{ping,Ping_PID}</c> + <p>The time-out (<c>after 5000</c>) is started when + <c>receive</c> is entered. + The time-out is canceled if <c>{ping,Ping_PID}</c> is received. If <c>{ping,Ping_PID}</c> is not received, - the actions following the timeout will be done after 5000 + the actions following the time-out are done after 5000 milliseconds. <c>after</c> must be last in the <c>receive</c>, - i.e. preceded by all other message reception specifications in - the <c>receive</c>. Of course we could also call a function which - returned an integer for the timeout:</p> + that is, preceded by all other message reception specifications in + the <c>receive</c>. It is also possible to call a function that + returned an integer for the time-out:</p> <code type="none"> after pong_timeout() -></code> - <p>In general, there are better ways than using timeouts to - supervise parts of a distributed Erlang system. Timeouts are - usually appropriate to supervise external events, for example if + <p>In general, there are better ways than using time-outs to + supervise parts of a distributed Erlang system. Time-outs are + usually appropriate to supervise external events, for example, if you have expected a message from some external system within a - specified time. For example, we could use a timeout to log a user - out of the messenger system if they have not accessed it, for - example, in ten minutes.</p> + specified time. For example, a time-out can be used to log a user + out of the messenger system if they have not accessed it for, + say, ten minutes.</p> </section> <section> <title>Error Handling</title> - <p>Before we go into details of the supervision and error handling - in an Erlang system, we need see how Erlang processes terminate, + <p>Before going into details of the supervision and error handling + in an Erlang system, let us see how Erlang processes terminate, or in Erlang terminology, <em>exit</em>.</p> <p>A process which executes <c>exit(normal)</c> or simply runs out of things to do has a <em>normal</em> exit.</p> - <p>A process which encounters a runtime error (e.g. divide by zero, - bad match, trying to call a function which doesn't exist etc) - exits with an error, i.e. has an <em>abnormal</em> exit. A + <p>A process which encounters a runtime error (for example, divide by zero, + bad match, trying to call a function that does not exist and so on) + exits with an error, that is, has an <em>abnormal</em> exit. A process which executes <seealso marker="erts:erlang#exit/1">exit(Reason)</seealso> where <c>Reason</c> is any Erlang term except the atom @@ -151,18 +153,23 @@ after pong_timeout() -></code> links to.</p> <p>The signal carries information about the pid it was sent from and the exit reason.</p> - <p>The default behaviour of a process which receives a normal exit + <p>The default behaviour of a process that receives a normal exit is to ignore the signal.</p> - <p>The default behaviour in the two other cases (i.e. abnormal exit) - above is to bypass all messages to the receiving process and to - kill it and to propagate the same error signal to the killed - process' links. In this way you can connect all processes in a - transaction together using links and if one of the processes - exits abnormally, all the processes in the transaction will be - killed. As we often want to create a process and link to it at + <p>The default behaviour in the two other cases (that is, abnormal exit) + above is to:</p> + <list type="bulleted"> + <item>Bypass all messages to the receiving process.</item> + <item>Kill the receiving process.</item> + <item>Propagate the same error signal to the links of the + killed process.</item> + </list> + <p>In this way you can connect all processes in a + transaction together using links. If one of the processes + exits abnormally, all the processes in the transaction are + killed. As it is often wanted to create a process and link to it at the same time, there is a special BIF, <seealso marker="erts:erlang#spawn_link/1">spawn_link</seealso> - which does the same as <c>spawn</c>, but also creates a link to + that does the same as <c>spawn</c>, but also creates a link to the spawned process.</p> <p>Now an example of the ping pong example using links to terminate "pong":</p> @@ -208,23 +215,23 @@ Pong received ping Ping received pong</pre> <p>This is a slight modification of the ping pong program where both processes are spawned from the same <c>start/1</c> function, - where the "ping" process can be spawned on a separate node. Note + and the "ping" process can be spawned on a separate node. Notice the use of the <c>link</c> BIF. "Ping" calls - <c>exit(ping)</c> when it finishes and this will cause an exit - signal to be sent to "pong" which will also terminate.</p> + <c>exit(ping)</c> when it finishes and this causes an exit + signal to be sent to "pong", which also terminates.</p> <p>It is possible to modify the default behaviour of a process so that it does not get killed when it receives abnormal exit - signals, but all signals will be turned into normal messages on + signals. Instead, all signals are turned into normal messages on the format <c>{'EXIT',FromPID,Reason}</c> and added to the end of - the receiving processes message queue. This behaviour is set by:</p> + the receiving process' message queue. This behaviour is set by:</p> <code type="none"> process_flag(trap_exit, true)</code> <p>There are several other process flags, see <seealso marker="erts:erlang#process_flag/2">erlang(3)</seealso>. Changing the default behaviour of a process in this way is usually not done in standard user programs, but is left to - the supervisory programs in OTP (but that's another tutorial). - However we will modify the ping pong program to illustrate exit + the supervisory programs in OTP. + However, the ping pong program is modified to illustrate exit trapping.</p> <code type="none"> -module(tut21). @@ -277,7 +284,7 @@ pong exiting, got {'EXIT',<3820.39.0>,ping}</pre> <section> <title>The Larger Example with Robustness Added</title> - <p>Now we return to the messenger program and add changes which + <p>Let us return to the messenger program and add changes to make it more robust:</p> <code type="none"> %%% Message passing utility. @@ -289,7 +296,7 @@ pong exiting, got {'EXIT',<3820.39.0>,ping}</pre> %%% already logged in at the same node, login will be rejected %%% with a suitable error message. %%% logoff() -%%% Logs off anybody at at node +%%% Logs off anybody at that node %%% message(ToName, Message) %%% sends Message to ToName. Error messages if the user of this %%% function is not logged on or if ToName is not logged on at @@ -449,35 +456,34 @@ await_result() -> io:format("No response from server~n", []), exit(timeout) end.</code> - <p>We have added the following changes:</p> + <p>The following changes are added:</p> <p>The messenger server traps exits. If it receives an exit signal, - <c>{'EXIT',From,Reason}</c> this means that a client process has - terminated or is unreachable because:</p> + <c>{'EXIT',From,Reason}</c>, this means that a client process has + terminated or is unreachable for one of the following reasons:</p> <list type="bulleted"> - <item>the user has logged off (we have removed the "logoff" - message),</item> - <item>the network connection to the client is broken,</item> - <item>the node on which the client process resides has gone down, - or</item> - <item>the client processes has done some illegal operation.</item> + <item>The user has logged off (the "logoff" + message is removed).</item> + <item>The network connection to the client is broken.</item> + <item>The node on which the client process resides has gone down.</item> + <item>The client processes has done some illegal operation.</item> </list> - <p>If we receive an exit signal as above, we delete the tuple, - <c>{From,Name}</c> from the servers <c>User_List</c> using + <p>If an exit signal is received as above, the tuple + <c>{From,Name}</c> is deleted from the servers <c>User_List</c> using the <c>server_logoff</c> function. If the node on which the server runs goes down, an exit signal (automatically generated by - the system), will be sent to all of the client processes: + the system) is sent to all of the client processes: <c>{'EXIT',MessengerPID,noconnection}</c> causing all the client processes to terminate.</p> - <p>We have also introduced a timeout of five seconds in - the <c>await_result</c> function. I.e. if the server does not + <p>Also, a time-out of five seconds has been introduced in + the <c>await_result</c> function. That is, if the server does not reply within five seconds (5000 ms), the client terminates. This - is really only needed in the logon sequence before the client and + is only needed in the logon sequence before the client and the server are linked.</p> - <p>An interesting case is if the client was to terminate before + <p>An interesting case is if the client terminates before the server links to it. This is taken care of because linking to a non-existent process causes an exit signal, - <c>{'EXIT',From,noproc}</c>, to be automatically generated as if - the process terminated immediately after the link operation.</p> + <c>{'EXIT',From,noproc}</c>, to be automatically generated. This is + as if the process terminated immediately after the link operation.</p> </section> </chapter> |