aboutsummaryrefslogtreecommitdiffstats
path: root/system/doc/design_principles/spec_proc.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/spec_proc.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/spec_proc.xml')
-rw-r--r--system/doc/design_principles/spec_proc.xml214
1 files changed, 103 insertions, 111 deletions
diff --git a/system/doc/design_principles/spec_proc.xml b/system/doc/design_principles/spec_proc.xml
index e849388a38..aceb5ba99e 100644
--- a/system/doc/design_principles/spec_proc.xml
+++ b/system/doc/design_principles/spec_proc.xml
@@ -21,30 +21,31 @@
</legalnotice>
- <title>Sys and Proc_Lib</title>
+ <title>sys and proc_lib</title>
<prepared></prepared>
<docno></docno>
<date></date>
<rev></rev>
<file>spec_proc.xml</file>
</header>
- <p>The module <c>sys</c> contains functions for simple debugging of
- processes implemented using behaviours.</p>
- <p>There are also functions that, together with functions in
- the module <c>proc_lib</c>, can be used to implement a
- <em>special process</em>, a process which comply to the OTP design
- principles without making use of a standard behaviour. They can
- also be used to implement user defined (non-standard) behaviours.</p>
- <p>Both <c>sys</c> and <c>proc_lib</c> belong to the STDLIB
- application.</p>
+ <marker id="sys and proc_lib"></marker>
+ <p>The <c>sys</c> module has functions for simple debugging of
+ processes implemented using behaviours. It also has functions that,
+ together with functions in the <c>proc_lib</c> module, can be used
+ to implement a <em>special process</em> that complies to the OTP
+ design principles without using a standard behaviour. These
+ functions can also be used to implement user-defined (non-standard)
+ behaviours.</p>
+ <p>Both <c>sys</c> and <c>proc_lib</c> belong to the STDLIB
+ application.</p>
<section>
<title>Simple Debugging</title>
- <p>The module <c>sys</c> contains some functions for simple debugging
- of processes implemented using behaviours. We use the
- <c>code_lock</c> example from
- the <seealso marker="fsm#ex">gen_fsm</seealso> chapter to
- illustrate this:</p>
+ <p>The <c>sys</c> module has functions for simple debugging of
+ processes implemented using behaviours. The <c>code_lock</c>
+ example from
+ <seealso marker="fsm#ex">gen_fsm Behaviour</seealso>
+ is used to illustrate this:</p>
<pre>
% <input>erl</input>
Erlang (BEAM) emulator version 5.2.3.6 [hipe] [threads:0]
@@ -102,16 +103,18 @@ ok
<section>
<title>Special Processes</title>
- <p>This section describes how to write a process which comply to
- the OTP design principles, without making use of a standard
- behaviour. Such a process should:</p>
+ <p>This section describes how to write a process that complies to
+ the OTP design principles, without using a standard behaviour.
+ Such a process is to:</p>
<list type="bulleted">
- <item>be started in a way that makes the process fit into a
- supervision tree,</item>
- <item>support the <c>sys</c> <seealso marker="#debug">debug facilities</seealso>, and</item>
- <item>take care of <seealso marker="#msg">system messages</seealso>.</item>
+ <item>Be started in a way that makes the process fit into a
+ supervision tree</item>
+ <item>Support the <c>sys</c>
+ <seealso marker="#debug">debug facilities</seealso></item>
+ <item>Take care of
+ <seealso marker="#msg">system messages</seealso>.</item>
</list>
- <p>System messages are messages with special meaning, used in
+ <p>System messages are messages with a special meaning, used in
the supervision tree. Typical system messages are requests for
trace output, and requests to suspend or resume process execution
(used during release handling). Processes implemented using
@@ -120,9 +123,9 @@ ok
<section>
<title>Example</title>
<p>The simple server from
- the <seealso marker="des_princ#ch1">Overview</seealso> chapter,
- implemented using <c>sys</c> and <c>proc_lib</c> so it fits into
- a supervision tree:</p>
+ <seealso marker="des_princ#ch1">Overview</seealso>,
+ implemented using <c>sys</c> and <c>proc_lib</c> so it fits into a
+ supervision tree:</p>
<marker id="ex"></marker>
<pre>
-module(ch4).
@@ -190,8 +193,8 @@ system_replace_state(StateFun, Chs) ->
write_debug(Dev, Event, Name) ->
io:format(Dev, "~p event = ~p~n", [Name, Event]).</pre>
- <p>Example on how the simple debugging functions in <c>sys</c> can
- be used for <c>ch4</c> as well:</p>
+ <p>Example on how the simple debugging functions in the <c>sys</c>
+ module can also be used for <c>ch4</c>:</p>
<pre>
% <input>erl</input>
Erlang (BEAM) emulator version 5.2.3.6 [hipe] [threads:0]
@@ -230,31 +233,32 @@ ok
<section>
<title>Starting the Process</title>
- <p>A function in the <c>proc_lib</c> module should be used to
- start the process. There are several possible functions, for
- example <c>spawn_link/3,4</c> for asynchronous start and
+ <p>A function in the <c>proc_lib</c> module is to be used to
+ start the process. Several functions are available, for
+ example, <c>spawn_link/3,4</c> for asynchronous start and
<c>start_link/3,4,5</c> for synchronous start.</p>
- <p>A process started using one of these functions will store
- information that is needed for a process in a supervision tree,
- for example about the ancestors and initial call.</p>
- <p>Also, if the process terminates with another reason than
- <c>normal</c> or <c>shutdown</c>, a crash report (see SASL
- User's Guide) is generated.</p>
- <p>In the example, synchronous start is used. The process is
- started by calling <c>ch4:start_link()</c>:</p>
+ <p>A process started using one of these functions stores
+ information (for example, about the ancestors and initial call)
+ that is needed for a process in a supervision tree.</p>
+ <p>If the process terminates with another reason than
+ <c>normal</c> or <c>shutdown</c>, a crash report is generated.
+ For more information about the crash report, see the SASL
+ User's Guide.</p>
+ <p>In the example, synchronous start is used. The process
+ starts by calling <c>ch4:start_link()</c>:</p>
<code type="none">
start_link() ->
proc_lib:start_link(ch4, init, [self()]).</code>
<p><c>ch4:start_link</c> calls the function
<c>proc_lib:start_link</c>. This function takes a module name,
- a function name and an argument list as arguments and spawns
+ a function name, and an argument list as arguments, spawns,
and links to a new process. The new process starts by executing
- the given function, in this case <c>ch4:init(Pid)</c>, where
- <c>Pid</c> is the pid (<c>self()</c>) of the first process, that
- is the parent process.</p>
- <p>In <c>init</c>, all initialization including name registration
- is done. The new process must also acknowledge that it has been
- started to the parent:</p>
+ the given function, here <c>ch4:init(Pid)</c>, where
+ <c>Pid</c> is the pid (<c>self()</c>) of the first process,
+ which is the parent process.</p>
+ <p>All initialization, including name registration, is done in
+ <c>init</c>. The new process must also acknowledge that it has
+ been started to the parent:</p>
<code type="none">
init(Parent) ->
...
@@ -267,8 +271,8 @@ init(Parent) ->
<section>
<marker id="debug"></marker>
<title>Debugging</title>
- <p>To support the debug facilites in <c>sys</c>, we need a
- <em>debug structure</em>, a term <c>Deb</c> which is
+ <p>To support the debug facilites in <c>sys</c>, a
+ <em>debug structure</em> is needed. The <c>Deb</c> term is
initialized using <c>sys:debug_options/1</c>:</p>
<code type="none">
init(Parent) ->
@@ -278,50 +282,41 @@ init(Parent) ->
loop(Chs, Parent, Deb).</code>
<p><c>sys:debug_options/1</c> takes a list of options as argument.
Here the list is empty, which means no debugging is enabled
- initially. See <c>sys(3)</c> for information about possible
- options.</p>
- <p>Then for each <em>system event</em> that we want to be logged
- or traced, the following function should be called.</p>
+ initially. For information about the possible options, see the
+ <c>sys(3)</c> manual page in STDLIB.</p>
+ <p>Then, for each <em>system event</em> to be logged
+ or traced, the following function is to be called.</p>
<code type="none">
sys:handle_debug(Deb, Func, Info, Event) => Deb1</code>
+<p>Here:</p>
<list type="bulleted">
- <item>
- <p><c>Deb</c> is the debug structure.</p>
- </item>
- <item>
- <p><c>Func</c> is a fun specifying
- a (user defined) function used to format
+ <item><c>Deb</c> is the debug structure.</item>
+ <item><c>Func</c> is a fun specifying
+ a (user-defined) function used to format
trace output. For each system event, the format function is
- called as <c>Func(Dev, Event, Info)</c>, where:</p>
+ called as <c>Func(Dev, Event, Info)</c>, where:
<list type="bulleted">
- <item>
- <p><c>Dev</c> is the IO device to which the output should
- be printed. See <c>io(3)</c>.</p>
- </item>
- <item>
- <p><c>Event</c> and <c>Info</c> are passed as-is from
- <c>handle_debug</c>.</p>
- </item>
+ <item><c>Dev</c> is the I/O device to which the output is to
+ be printed. See the <c>io(3)</c> manual page in
+ STDLIB.</item>
+ <item><c>Event</c> and <c>Info</c> are passed as is from
+ <c>handle_debug</c>.</item>
</list>
</item>
- <item>
- <p><c>Info</c> is used to pass additional information to
- <c>Func</c>, it can be any term and is passed as-is.</p>
- </item>
- <item>
- <p><c>Event</c> is the system event. It is up to the user to
- define what a system event is and how it should be
- represented, but typically at least incoming and outgoing
+ <item><c>Info</c> is used to pass more information to
+ <c>Func</c>. It can be any term and is passed as is.</item>
+ <item><c>Event</c> is the system event. It is up to the user to
+ define what a system event is and how it is to be
+ represented. Typically at least incoming and outgoing
messages are considered system events and represented by
the tuples <c>{in,Msg[,From]}</c> and <c>{out,Msg,To}</c>,
- respectively.</p>
- </item>
+ respectively.</item>
</list>
<p><c>handle_debug</c> returns an updated debug structure
<c>Deb1</c>.</p>
<p>In the example, <c>handle_debug</c> is called for each incoming
and outgoing message. The format function <c>Func</c> is
- the function <c>ch4:write_debug/3</c> which prints the message
+ the function <c>ch4:write_debug/3</c>, which prints the message
using <c>io:format/3</c>.</p>
<code type="none">
loop(Chs, Parent, Deb) ->
@@ -354,22 +349,22 @@ write_debug(Dev, Event, Name) ->
{system, From, Request}</code>
<p>The content and meaning of these messages do not need to be
interpreted by the process. Instead the following function
- should be called:</p>
+ is to be called:</p>
<code type="none">
sys:handle_system_msg(Request, From, Parent, Module, Deb, State)</code>
- <p>This function does not return. It will handle the system
- message and then call:</p>
+ <p>This function does not return. It handles the system
+ message and then either calls the following if process execution is
+ to continue:</p>
<code type="none">
Module:system_continue(Parent, Deb, State)</code>
- <p>if process execution should continue, or:</p>
+ <p>Or calls the following if the process is to terminate:</p>
<code type="none">
Module:system_terminate(Reason, Parent, Deb, State)</code>
- <p>if the process should terminate. Note that a process in a
- supervision tree is expected to terminate with the same reason as
- its parent.</p>
+ <p>A process in a supervision tree is expected to terminate with
+ the same reason as its parent.</p>
<list type="bulleted">
- <item><c>Request</c> and <c>From</c> should be passed as-is from
- the system message to the call to <c>handle_system_msg</c>.</item>
+ <item><c>Request</c> and <c>From</c> are to be passed as is from
+ the system message to the call to <c>handle_system_msg</c>.</item>
<item><c>Parent</c> is the pid of the parent.</item>
<item><c>Module</c> is the name of the module.</item>
<item><c>Deb</c> is the debug structure.</item>
@@ -377,10 +372,12 @@ Module:system_terminate(Reason, Parent, Deb, State)</code>
is passed to <c>system_continue</c>/<c>system_terminate</c>/
<c>system_get_state</c>/<c>system_replace_state</c>.</item>
</list>
- <p>If the process should return its state <c>handle_system_msg</c> will call:</p>
+ <p>If the process is to return its state, <c>handle_system_msg</c>
+ calls:</p>
<code type="none">
Module:system_get_state(State)</code>
- <p>or if the process should replace its state using the fun <c>StateFun</c>:</p>
+ <p>If the process is to replace its state using the fun <c>StateFun</c>,
+ <c>handle_system_msg</c> calls:</p>
<code type="none">
Module:system_replace_state(StateFun, State)</code>
<p>In the example:</p>
@@ -407,9 +404,9 @@ system_replace_state(StateFun, Chs) ->
NChs = StateFun(Chs),
{ok, NChs, NChs}.
</code>
- <p>If the special process is set to trap exits, note that if
- the parent process terminates, the expected behavior is to
- terminate with the same reason:</p>
+ <p>If the special process is set to trap exits and if the parent
+ process terminates, the expected behavior is to terminate with
+ the same reason:</p>
<code type="none">
init(...) ->
...,
@@ -431,28 +428,23 @@ loop(...) ->
<section>
<title>User-Defined Behaviours</title>
-
<p><marker id="behaviours"/>To implement a user-defined behaviour,
- write code similar to code for a special process but calling
- functions in a callback module for handling specific tasks.</p>
- <p>If it is desired that the compiler should warn for missing
- callback functions, as it does for the OTP behaviours, add
- <c>-callback</c> attributes in the behaviour module to describe
- the expected callback functions:</p>
-
+ write code similar to
+ code for a special process, but call functions in a callback
+ module for handling specific tasks.</p>
+ <p>If the compiler is to warn for missing callback functions, as it
+ does for the OTP behaviours, add <c>-callback</c> attributes in the
+ behaviour module to describe the expected callbacks:</p>
<code type="none">
-callback Name1(Arg1_1, Arg1_2, ..., Arg1_N1) -> Res1.
-callback Name2(Arg2_1, Arg2_2, ..., Arg2_N2) -> Res2.
...
-callback NameM(ArgM_1, ArgM_2, ..., ArgM_NM) -> ResM.</code>
-
- <p>where each <c>Name</c> is the name of a callback function and
- <c>Arg</c> and <c>Res</c> are types as described in
- Specifications for functions in <seealso
- marker="../reference_manual/typespec">Types and Function
- Specifications</seealso>. The whole syntax of the
- <c>-spec</c> attribute is supported by <c>-callback</c>
- attribute.</p>
+ <p><c>NameX</c> are the names of the expected callbacks.
+ <c>ArgX_Y</c> and <c>ResX</c> are types as they are described in
+ <seealso marker="../reference_manual/typespec">Types and
+ Function Specifications</seealso>. The whole syntax of the <c>-spec</c>
+ attribute is supported by the <c>-callback</c> attribute.</p>
<p>Callback functions that are optional for the user of the
behaviour to implement are specified by use of the
<c>-optional_callbacks</c> attribute:</p>
@@ -487,10 +479,10 @@ behaviour_info(callbacks) ->
generated by the compiler using the <c>-callback</c>
attributes.</p>
<p>When the compiler encounters the module attribute
- <c>-behaviour(Behaviour).</c> in a module <c>Mod</c>, it will
- call <c>Behaviour:behaviour_info(callbacks)</c> and compare the
+ <c>-behaviour(Behaviour).</c> in a module <c>Mod</c>, it
+ calls <c>Behaviour:behaviour_info(callbacks)</c> and compares the
result with the set of functions actually exported from
- <c>Mod</c>, and issue a warning if any callback function is
+ <c>Mod</c>, and issues a warning if any callback function is
missing.</p>
<p>Example:</p>
<code type="none">