← Back to branch summary

~ubuntu-branches/debian/squeeze/erlang/squeeze

« back to all changes in this revision

Viewing changes to system/doc/reference_manual/processes.xml

  • Committer: Bazaar Package Importer
  • Author(s): Sergei Golovan
  • Date: 2010-03-09 17:34:57 UTC
  • mfrom: (10.1.2 sid)
  • Revision ID: james.westby@ubuntu.com-20100309173457-4yd6hlcb2osfhx31
Tags: 1:13.b.4-dfsg-3
Manpages in section 1 are needed even if only arch-dependent packages are
built. So, re-enabled them.

Show diffs side-by-side

added added

removed removed

Lines of Context:
system/doc/reference_manual/processes.xml
 
1
<?xml version="1.0" encoding="latin1" ?>
 
2
<!DOCTYPE chapter SYSTEM "chapter.dtd">
 
3
 
 
4
<chapter>
 
5
  <header>
 
6
    <copyright>
 
7
      <year>2003</year><year>2009</year>
 
8
      <holder>Ericsson AB. All Rights Reserved.</holder>
 
9
    </copyright>
 
10
    <legalnotice>
 
11
      The contents of this file are subject to the Erlang Public License,
 
12
      Version 1.1, (the "License"); you may not use this file except in
 
13
      compliance with the License. You should have received a copy of the
 
14
      Erlang Public License along with this software. If not, it can be
 
15
      retrieved online at http://www.erlang.org/.
 
16
    
 
17
      Software distributed under the License is distributed on an "AS IS"
 
18
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 
19
      the License for the specific language governing rights and limitations
 
20
      under the License.
 
21
    
 
22
    </legalnotice>
 
23
 
 
24
    <title>Processes</title>
 
25
    <prepared></prepared>
 
26
    <docno></docno>
 
27
    <date></date>
 
28
    <rev></rev>
 
29
    <file>processes.xml</file>
 
30
  </header>
 
31
 
 
32
  <section>
 
33
    <title>Processes</title>
 
34
    <p>Erlang is designed for massive concurrency. Erlang processes are
 
35
      light-weight (grow and shrink dynamically) with small memory
 
36
      footprint, fast to create and terminate and the scheduling
 
37
      overhead is low.</p>
 
38
  </section>
 
39
 
 
40
  <section>
 
41
    <title>Process Creation</title>
 
42
    <p>A process is created by calling <c>spawn</c>:</p>
 
43
    <pre>
 
44
spawn(Module, Name, Args) -> pid()
 
45
  Module = Name = atom()
 
46
  Args = [Arg1,...,ArgN]
 
47
    ArgI = term()</pre>
 
48
    <p><c>spawn</c> creates a new process and returns the pid.</p>
 
49
    <p>The new process will start executing in
 
50
      <c>Module:Name(Arg1,...,ArgN)</c> where the arguments is
 
51
      the elements of the (possible empty) <c>Args</c> argument list.</p>
 
52
    <p>There exist a number of other <c>spawn</c> BIFs, for example
 
53
      <c>spawn/4</c> for spawning a process at another node.</p>
 
54
  </section>
 
55
 
 
56
  <section>
 
57
    <title>Registered Processes</title>
 
58
    <p>Besides addressing a process by using its pid, there are also
 
59
      BIFs for registering a process under a name. The name must be an
 
60
      atom and is automatically unregistered if the process terminates:</p>
 
61
    <table>
 
62
      <row>
 
63
        <cell align="left" valign="middle"><c>register(Name, Pid)</c></cell>
 
64
        <cell align="left" valign="middle">Associates the name <c>Name</c>, an atom, with the process <c>Pid</c>.</cell>
 
65
      </row>
 
66
      <row>
 
67
        <cell align="left" valign="middle"><c>registered()</c></cell>
 
68
        <cell align="left" valign="middle">Returns a list of names which have been registered using<c>register/2</c>.</cell>
 
69
      </row>
 
70
      <row>
 
71
        <cell align="left" valign="middle"><c>whereis(Name)</c></cell>
 
72
        <cell align="left" valign="middle">Returns the pid registered under <c>Name</c>, or<c>undefined</c>if the name is not registered.</cell>
 
73
      </row>
 
74
      <tcaption>Name Registration BIFs.</tcaption>
 
75
    </table>
 
76
  </section>
 
77
 
 
78
  <section>
 
79
    <marker id="term"></marker>
 
80
    <title>Process Termination</title>
 
81
    <p>When a process terminates, it always terminates with an
 
82
      <em>exit reason</em>. The reason may be any term.</p>
 
83
    <p>A process is said to terminate <em>normally</em>, if the exit
 
84
      reason is the atom <c>normal</c>. A process with no more code to
 
85
      execute terminates normally.</p>
 
86
    <p>A process terminates with exit reason <c>{Reason,Stack}</c>
 
87
      when a run-time error occurs. See
 
88
      <seealso marker="errors#exit_reasons">Error and Error Handling</seealso>.</p>
 
89
    <p>A process can terminate itself by calling one of the BIFs
 
90
      <c>exit(Reason)</c>, 
 
91
      <c>erlang:error(Reason)</c>, <c>erlang:error(Reason, Args)</c>,
 
92
      <c>erlang:fault(Reason)</c> or <c>erlang:fault(Reason, Args)</c>. 
 
93
      The process then terminates with reason <c>Reason</c> for
 
94
      <c>exit/1</c> or <c>{Reason,Stack} for the others</c>.</p>
 
95
    <p>A process may also be terminated if it receives an exit signal
 
96
      with another exit reason than <c>normal</c>, see
 
97
      <seealso marker="#errors">Error Handling</seealso> below.</p>
 
98
  </section>
 
99
 
 
100
  <section>
 
101
    <title>Message Sending</title>
 
102
    <p>Processes communicate by sending and receiving messages.
 
103
      Messages are sent by using
 
104
      the <seealso marker="expressions#send">send operator !</seealso>
 
105
      and received by calling
 
106
      <seealso marker="expressions#receive">receive</seealso>.</p>
 
107
    <p>Message sending is asynchronous and safe, the message is
 
108
      guaranteed to eventually reach the recipient, provided that
 
109
      the recipient exists.</p>
 
110
  </section>
 
111
 
 
112
  <section>
 
113
    <title>Links</title>
 
114
    <p>Two processes can be <em>linked</em> to each other. A link
 
115
      between two processes <c>Pid1</c> and <c>Pid2</c> is created
 
116
      by <c>Pid1</c> calling the BIF <c>link(Pid2)</c> (or vice versa).
 
117
      There also exists a number a <c>spawn_link</c> BIFs, which spawns
 
118
      and links to a process in one operation.</p>
 
119
    <p>Links are bidirectional and there can only be one link between
 
120
      two processes. Repeated calls to <c>link(Pid)</c> have no effect.</p>
 
121
    <p>A link can be removed by calling the BIF <c>unlink(Pid)</c>.</p>
 
122
    <p>Links are used to monitor the behaviour of other processes, see
 
123
      <seealso marker="#errors">Error Handling</seealso> below.</p>
 
124
  </section>
 
125
 
 
126
  <section>
 
127
    <marker id="errors"></marker>
 
128
    <title>Error Handling</title>
 
129
    <p>Erlang has a built-in feature for error handling between
 
130
      processes. Terminating processes will emit exit signals to all
 
131
      linked processes, which may terminate as well or handle the exit
 
132
      in some way. This feature can be used to build hierarchical
 
133
      program structures where some processes are supervising other
 
134
      processes, for example restarting them if they terminate
 
135
      abnormally.</p>
 
136
    <p>Refer to OTP Design Principles for more information about
 
137
      OTP supervision trees, which uses this feature.</p>
 
138
 
 
139
    <section>
 
140
      <title>Emitting Exit Signals</title>
 
141
      <p>When a process terminates, it will terminate with an <em>exit reason</em> as explained in <seealso marker="#term">Process Termination</seealso> above. This exit reason is emitted in
 
142
        an <em>exit signal</em> to all linked processes.</p>
 
143
      <p>A process can also call the function <c>exit(Pid,Reason)</c>.
 
144
        This will result in an exit signal with exit reason
 
145
        <c>Reason</c> being emitted to <c>Pid</c>, but does not affect
 
146
        the calling process.</p>
 
147
    </section>
 
148
 
 
149
    <section>
 
150
      <title>Receiving Exit Signals</title>
 
151
      <p>The default behaviour when a process receives an exit signal
 
152
        with an exit reason other than <c>normal</c>, is to terminate
 
153
        and in turn emit exit signals with the same exit reason to its
 
154
        linked processes. An exit signal with reason <c>normal</c> is
 
155
        ignored.</p>
 
156
      <p>A process can be set to trap exit signals by calling:</p>
 
157
      <pre>
 
158
process_flag(trap_exit, true)</pre>
 
159
      <p>When a process is trapping exits, it will not terminate when
 
160
        an exit signal is received. Instead, the signal is transformed
 
161
        into a message <c>{'EXIT',FromPid,Reason}</c> which is put into
 
162
        the mailbox of the process just like a regular message.</p>
 
163
      <p>An exception to the above is if the exit reason is <c>kill</c>,
 
164
        that is if <c>exit(Pid,kill)</c> has been called. This will
 
165
        unconditionally terminate the process, regardless of if it is
 
166
        trapping exit signals or not.</p>
 
167
    </section>
 
168
  </section>
 
169
 
 
170
  <section>
 
171
    <title>Monitors</title>
 
172
    <p>An alternative to links are <em>monitors</em>. A process
 
173
      <c>Pid1</c> can create a monitor for <c>Pid2</c> by calling
 
174
      the BIF <c>erlang:monitor(process, Pid2)</c>. The function returns
 
175
      a reference <c>Ref</c>.</p>
 
176
    <p>If <c>Pid2</c> terminates with exit reason <c>Reason</c>, a
 
177
      'DOWN' message is sent to <c>Pid1</c>:</p>
 
178
    <code type="none">
 
179
{'DOWN', Ref, process, Pid2, Reason}</code>
 
180
    <p>If <c>Pid2</c> does not exist, the 'DOWN' message is sent
 
181
      immediately with <c>Reason</c> set to <c>noproc</c>.</p>
 
182
    <p>Monitors are unidirectional. Repeated calls to
 
183
      <c>erlang:monitor(process, Pid)</c> will create several,
 
184
      independent monitors and each one will send a 'DOWN' message when
 
185
      <c>Pid</c> terminates.</p>
 
186
    <p>A monitor can be removed by calling
 
187
      <c>erlang:demonitor(Ref)</c>.</p>
 
188
    <p>It is possible to create monitors for processes with registered
 
189
      names, also at other nodes.</p>
 
190
  </section>
 
191
 
 
192
  <section>
 
193
    <title>Process Dictionary</title>
 
194
    <p>Each process has its own process dictionary, accessed by calling
 
195
      the following BIFs:</p>
 
196
    <pre>
 
197
put(Key, Value)
 
198
get(Key)
 
199
get()
 
200
get_keys(Value)
 
201
erase(Key)
 
202
erase()</pre>
 
203
  </section>
 
204
</chapter>
 
205