From 42a0387e886ddbf60b0e2cb977758e2ca74954ae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Thu, 12 Mar 2015 15:35:13 +0100 Subject: Update Design Principles MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Language cleaned up by the technical writers xsipewe and tmanevik from Combitech. Proofreading and corrections by Björn Gustavsson. --- system/doc/design_principles/des_princ.xml | 113 +++++++++++++++-------------- 1 file changed, 59 insertions(+), 54 deletions(-) (limited to 'system/doc/design_principles/des_princ.xml') 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 @@ des_princ.xml -

The OTP Design Principles is a set of principles for how - to structure Erlang code in terms of processes, modules and - directories.

+ +

The OTP design principles define how to + structure Erlang code in terms of processes, modules, + and directories.

Supervision Trees

A basic concept in Erlang/OTP is the supervision tree. This is a process structuring model based on the idea of - workers and supervisors.

+ workers and supervisors:

- Workers are processes which perform computations, that is, + Workers are processes that perform computations, that is, they do the actual work. - Supervisors are processes which monitor the behaviour of + Supervisors are processes that monitor the behaviour of workers. A supervisor can restart a worker if something goes wrong. 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. +

In the following figure, square boxes represents supervisors and + circles represent workers:

Supervision Tree -

In the figure above, square boxes represents supervisors and - circles represent workers.

Behaviours

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.

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

Behaviours 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 callback module).

+ (a behaviour module) and a specific part (a + callback module).

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 callback functions.

-

An example to illustrate how code can be divided into a generic - and a specific part: Consider the following code (written in +

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 alloc/0 and free/1, @@ -149,7 +151,7 @@ loop(Mod, State) -> State2 = Mod:handle_cast(Req, State), loop(Mod, State2) end. -

and a callback module ch2.erl:

+

And a callback module ch2.erl:

-module(ch2). -export([start/0]). @@ -173,27 +175,27 @@ handle_call(alloc, Chs) -> handle_cast({free, Ch}, Chs) -> free(Ch, Chs). % => Chs2 -

Note the following:

+

Notice the following:

- The code in server can be re-used to build many + The code in server can be reused to build many different servers. - The name of the server, in this example the atom - ch2, is hidden from the users of the client functions. - This means the name can be changed without affecting them. + The server name, in this example the atom + ch2, is hidden from the users of the client functions. This + means that the name can be changed without affecting them. 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. - We can extend the functionality of server, without + The functionality of server can be extended without having to change ch2 or any other callback module. -

(In ch1.erl and ch2.erl above, the implementation - of channels/0, alloc/1 and free/2 has been +

In ch1.erl and ch2.erl above, the implementation + of channels/0, alloc/1, and free/2 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.)

+ of channels to allocate, and so on.

channels() -> {_Allocated = [], _Free = lists:seq(1,100)}. @@ -208,30 +210,30 @@ free(Ch, {Alloc, Free} = Channels) -> false -> Channels end. -

Code written without making use of behaviours may be more - efficient, but the increased efficiency will be at the expense of +

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.

+ in a consistent manner is important.

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.

-

The module server corresponds, greatly simplified, +

The server module corresponds, greatly simplified, to the Erlang/OTP behaviour gen_server.

The standard Erlang/OTP behaviours are:

- - gen_server - For implementing the server of a client-server relation. - gen_fsm - For implementing finite state machines. - gen_event - For implementing event handling functionality. - supervisor - For implementing a supervisor in a supervision tree. - + +

gen_server

+

For implementing the server of a client-server relation

 +

gen_fsm

+

For implementing finite-state machines

 +

gen_event

+

For implementing event handling functionality

 +

supervisor

+

For implementing a supervisor in a supervision tree

 +

The compiler understands the module attribute -behaviour(Behaviour) and issues warnings about - missing callback functions. Example:

+ missing callback functions, for example:

-module(chs3). -behaviour(gen_server). @@ -248,13 +250,17 @@ free(Ch, {Alloc, Free} = Channels) -> some specific functionality. Components are with Erlang/OTP terminology called applications. 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.

+ 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:

+ + Kernel - Functionality necessary to run Erlang + STDLIB - Erlang standard libraries +

The application concept applies both to program structure (processes) and directory structure (modules).

-

The simplest kind of application does not have any processes, - but consists of a collection of functional modules. Such an +

The simplest applications do not have any processes, + but consist of a collection of functional modules. Such an application is called a library application. An example of a library application is STDLIB.

An application with processes is easiest implemented as a @@ -266,12 +272,11 @@ free(Ch, {Alloc, Free} = Channels) ->

Releases

A release is a complete system made out from a subset of - the Erlang/OTP applications and a set of user-specific - applications.

+ Erlang/OTP applications and a set of user-specific applications.

How to program releases is described in Releases.

How to install a release in a target environment is described - in the chapter about Target Systems in System Principles.

+ in the section about target systems in Section 2 System Principles.

-- cgit v1.2.3