aboutsummaryrefslogtreecommitdiffstats
path: root/system/doc/design_principles/des_princ.xml
diff options
context:
space:
mode:
authorBjörn Gustavsson <[email protected]>2015-03-12 15:35:13 +0100
committerBjörn Gustavsson <[email protected]>2015-03-12 15:35:13 +0100
commit42a0387e886ddbf60b0e2cb977758e2ca74954ae (patch)
tree2dc50aa0b66626e4e162111a046929763394374a /system/doc/design_principles/des_princ.xml
parentd1aeabb317811c203c08194c3dab464a48ec1dd3 (diff)
downloadotp-42a0387e886ddbf60b0e2cb977758e2ca74954ae.tar.gz
otp-42a0387e886ddbf60b0e2cb977758e2ca74954ae.tar.bz2
otp-42a0387e886ddbf60b0e2cb977758e2ca74954ae.zip
Update Design Principles
Language cleaned up by the technical writers xsipewe and tmanevik from Combitech. Proofreading and corrections by Björn Gustavsson.
Diffstat (limited to 'system/doc/design_principles/des_princ.xml')
-rw-r--r--system/doc/design_principles/des_princ.xml113
1 files changed, 59 insertions, 54 deletions
diff --git a/system/doc/design_principles/des_princ.xml b/system/doc/design_principles/des_princ.xml
index e8f289b905..77c61eafb0 100644
--- a/system/doc/design_principles/des_princ.xml
+++ b/system/doc/design_principles/des_princ.xml
@@ -28,50 +28,52 @@
<rev></rev>
<file>des_princ.xml</file>
</header>
- <p>The <em>OTP Design Principles</em> is a set of principles for how
- to structure Erlang code in terms of processes, modules and
- directories.</p>
+ <marker id="otp design principles"></marker>
+ <p>The <em>OTP design principles</em> define how to
+ structure Erlang code in terms of processes, modules,
+ and directories.</p>
<section>
<title>Supervision Trees</title>
<p>A basic concept in Erlang/OTP is the <em>supervision tree</em>.
This is a process structuring model based on the idea of
- <em>workers</em> and <em>supervisors</em>.</p>
+ <em>workers</em> and <em>supervisors</em>:</p>
<list type="bulleted">
- <item>Workers are processes which perform computations, that is,
+ <item>Workers are processes that perform computations, that is,
they do the actual work.</item>
- <item>Supervisors are processes which monitor the behaviour of
+ <item>Supervisors are processes that monitor the behaviour of
workers. A supervisor can restart a worker if something goes
wrong.</item>
<item>The supervision tree is a hierarchical arrangement of
- code into supervisors and workers, making it possible to
+ code into supervisors and workers, which makes it possible to
design and program fault-tolerant software.</item>
</list>
+ <p>In the following figure, square boxes represents supervisors and
+ circles represent workers:</p>
<marker id="sup6"></marker>
<image file="../design_principles/sup6.gif">
<icaption>Supervision Tree</icaption>
</image>
- <p>In the figure above, square boxes represents supervisors and
- circles represent workers.</p>
</section>
<section>
<title>Behaviours</title>
<p>In a supervision tree, many of the processes have similar
structures, they follow similar patterns. For example,
- the supervisors are very similar in structure. The only difference
- between them is which child processes they supervise. Also, many
- of the workers are servers in a server-client relation, finite
- state machines, or event handlers such as error loggers.</p>
+ the supervisors are similar in structure. The only difference
+ between them is which child processes they supervise. Many
+ of the workers are servers in a server-client relation,
+ finite-state machines, or event handlers such as error loggers.</p>
<p><em>Behaviours</em> are formalizations of these common patterns.
The idea is to divide the code for a process in a generic part
- (a behaviour module) and a specific part (a <em>callback module</em>).</p>
+ (a behaviour module) and a specific part (a
+ <em>callback module</em>).</p>
<p>The behaviour module is part of Erlang/OTP. To implement a
process such as a supervisor, the user only has to implement
- the callback module which should export a pre-defined set of
+ the callback module which is to export a pre-defined set of
functions, the <em>callback functions</em>.</p>
- <p>An example to illustrate how code can be divided into a generic
- and a specific part: Consider the following code (written in
+ <p>The following example illustrate how code can be divided into a
+ generic and a specific part. Consider the following code (written in
plain Erlang) for a simple server, which keeps track of a number
of "channels". Other processes can allocate and free the channels
by calling the functions <c>alloc/0</c> and <c>free/1</c>,
@@ -149,7 +151,7 @@ loop(Mod, State) ->
State2 = Mod:handle_cast(Req, State),
loop(Mod, State2)
end.</code>
- <p>and a callback module <c>ch2.erl</c>:</p>
+ <p>And a callback module <c>ch2.erl</c>:</p>
<code type="none">
-module(ch2).
-export([start/0]).
@@ -173,27 +175,27 @@ handle_call(alloc, Chs) ->
handle_cast({free, Ch}, Chs) ->
free(Ch, Chs). % => Chs2</code>
- <p>Note the following:</p>
+ <p>Notice the following:</p>
<list type="bulleted">
- <item>The code in <c>server</c> can be re-used to build many
+ <item>The code in <c>server</c> can be reused to build many
different servers.</item>
- <item>The name of the server, in this example the atom
- <c>ch2</c>, is hidden from the users of the client functions.
- This means the name can be changed without affecting them.</item>
+ <item>The server name, in this example the atom
+ <c>ch2</c>, is hidden from the users of the client functions. This
+ means that the name can be changed without affecting them.</item>
<item>The protcol (messages sent to and received from the server)
- is hidden as well. This is good programming practice and allows
- us to change the protocol without making changes to code using
+ is also hidden. This is good programming practice and allows
+ one to change the protocol without changing the code using
the interface functions.</item>
- <item>We can extend the functionality of <c>server</c>, without
+ <item>The functionality of <c>server</c> can be extended without
having to change <c>ch2</c> or any other callback module.</item>
</list>
- <p>(In <c>ch1.erl</c> and <c>ch2.erl</c> above, the implementation
- of <c>channels/0</c>, <c>alloc/1</c> and <c>free/2</c> has been
+ <p>In <c>ch1.erl</c> and <c>ch2.erl</c> above, the implementation
+ of <c>channels/0</c>, <c>alloc/1</c>, and <c>free/2</c> has been
intentionally left out, as it is not relevant to the example.
For completeness, one way to write these functions are given
- below. Note that this is an example only, a realistic
+ below. This is an example only, a realistic
implementation must be able to handle situations like running out
- of channels to allocate etc.)</p>
+ of channels to allocate, and so on.</p>
<code type="none">
channels() ->
{_Allocated = [], _Free = lists:seq(1,100)}.
@@ -208,30 +210,30 @@ free(Ch, {Alloc, Free} = Channels) ->
false ->
Channels
end. </code>
- <p>Code written without making use of behaviours may be more
- efficient, but the increased efficiency will be at the expense of
+ <p>Code written without using behaviours can be more
+ efficient, but the increased efficiency is at the expense of
generality. The ability to manage all applications in the system
- in a consistent manner is very important.</p>
+ in a consistent manner is important.</p>
<p>Using behaviours also makes it easier to read and understand
- code written by other programmers. Ad hoc programming structures,
+ code written by other programmers. Improvised programming structures,
while possibly more efficient, are always more difficult to
understand.</p>
- <p>The module <c>server</c> corresponds, greatly simplified,
+ <p>The <c>server</c> module corresponds, greatly simplified,
to the Erlang/OTP behaviour <c>gen_server</c>.</p>
<p>The standard Erlang/OTP behaviours are:</p>
- <taglist>
- <tag><seealso marker="gen_server_concepts">gen_server</seealso></tag>
- <item>For implementing the server of a client-server relation.</item>
- <tag><seealso marker="fsm">gen_fsm</seealso></tag>
- <item>For implementing finite state machines.</item>
- <tag><seealso marker="events">gen_event</seealso></tag>
- <item>For implementing event handling functionality.</item>
- <tag><seealso marker="sup_princ">supervisor</seealso></tag>
- <item>For implementing a supervisor in a supervision tree.</item>
- </taglist>
+ <list type="bulleted">
+ <item><p><seealso marker="gen_server_concepts">gen_server</seealso></p>
+ <p>For implementing the server of a client-server relation</p></item>
+ <item><p><seealso marker="fsm">gen_fsm</seealso></p>
+ <p>For implementing finite-state machines</p></item>
+ <item><p><seealso marker="events">gen_event</seealso></p>
+ <p>For implementing event handling functionality</p></item>
+ <item><p><seealso marker="sup_princ">supervisor</seealso></p>
+ <p>For implementing a supervisor in a supervision tree</p></item>
+ </list>
<p>The compiler understands the module attribute
<c>-behaviour(Behaviour)</c> and issues warnings about
- missing callback functions. Example:</p>
+ missing callback functions, for example:</p>
<code type="none">
-module(chs3).
-behaviour(gen_server).
@@ -248,13 +250,17 @@ free(Ch, {Alloc, Free} = Channels) ->
some specific functionality. Components are with Erlang/OTP
terminology called <em>applications</em>. Examples of Erlang/OTP
applications are Mnesia, which has everything needed for
- programming database services, and Debugger which is used to
- debug Erlang programs. The minimal system based on Erlang/OTP
- consists of the applications Kernel and STDLIB.</p>
+ programming database services, and Debugger, which is used
+ to debug Erlang programs. The minimal system based on Erlang/OTP
+ consists of the following two applications:</p>
+ <list type="bulleted">
+ <item>Kernel - Functionality necessary to run Erlang</item>
+ <item>STDLIB - Erlang standard libraries</item>
+ </list>
<p>The application concept applies both to program structure
(processes) and directory structure (modules).</p>
- <p>The simplest kind of application does not have any processes,
- but consists of a collection of functional modules. Such an
+ <p>The simplest applications do not have any processes,
+ but consist of a collection of functional modules. Such an
application is called a <em>library application</em>. An example
of a library application is STDLIB.</p>
<p>An application with processes is easiest implemented as a
@@ -266,12 +272,11 @@ free(Ch, {Alloc, Free} = Channels) ->
<section>
<title>Releases</title>
<p>A <em>release</em> is a complete system made out from a subset of
- the Erlang/OTP applications and a set of user-specific
- applications.</p>
+ Erlang/OTP applications and a set of user-specific applications.</p>
<p>How to program releases is described in
<seealso marker="release_structure">Releases</seealso>.</p>
<p>How to install a release in a target environment is described
- in the chapter about Target Systems in System Principles.</p>
+ in the section about target systems in Section 2 System Principles.</p>
</section>
<section>