1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.3 -->
<HTML>
<HEAD>
<TITLE>Errors and Error Handling</TITLE>
<SCRIPT type="text/javascript" src="../../doc/erlresolvelinks.js">
</SCRIPT>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
ALINK="#FF0000">
<CENTER>
<A HREF="http://www.erlang.se"><IMG BORDER=0 ALT="[Ericsson AB]" SRC="min_head.gif"></A>
</CENTER>
<A NAME="9"><!-- Empty --></A>
<H2>9 Errors and Error Handling</H2>
<A NAME="9.1"><!-- Empty --></A>
<H3>9.1 Terminology</H3>
<P>Errors can roughly be divided into four different types:
<P>
<UL>
<LI>
Compile-time errors
</LI>
<LI>
Logical errors
</LI>
<LI>
Run-time errors
</LI>
<LI>
Generated errors
</LI>
</UL>
<P>A compile-time error, for example a syntax error, should not
cause much trouble as it is caught by the compiler.
<P>A logical error is when a program does not behave as intended,
but does not crash. An example could be that nothing happens when
a button in a graphical user interface is clicked.
<P>A run-time error is when a crash occurs. An example could be
when an operator is applied to arguments of the wrong type.
The Erlang programming language has built-in features for
handling of run-time errors.
<P>A run-time error can also be emulated by calling
<CODE>erlang:error(Reason)</CODE>, <CODE>erlang:error(Reason, Args)</CODE>
(those appeared in Erlang 5.4/OTP-R10),
<CODE>erlang:fault(Reason)</CODE> or <CODE>erlang:fault(Reason, Args)</CODE>
(old equivalents).
<P>A run-time error is another name for an exception
of class <CODE>error</CODE>.
<P>A generated error is when the code itself calls
<CODE>exit/1</CODE> or <CODE>throw/1</CODE>. Note that emulated run-time
errors are not denoted as generated errors here.
<P>Generated errors are exceptions of classes <CODE>exit</CODE> and
<CODE>throw</CODE>.
<P>When a run-time error or generated error occurs in Erlang,
execution for the process which evaluated
the erroneous expression is stopped.
This is referred to as a <STRONG>failure</STRONG>, that execution or
evaluation <STRONG>fails</STRONG>, or that the process <STRONG>fails</STRONG>,
<STRONG>terminates</STRONG> or <STRONG>exits</STRONG>. Note that a process may
terminate/exit for other reasons than a failure.
<P>A process that terminates will emit an <STRONG>exit signal</STRONG> with
an <STRONG>exit reason</STRONG> that says something about which error
has occurred. Normally, some information about the error will
be printed to the terminal.<A NAME="9.2"><!-- Empty --></A>
<H3>9.2 Exceptions</H3>
<P>Exceptions are run-time errors or generated errors and
are of three different classes, with different origins. The
<A HREF="expressions.html#try">try</A> expression
(appeared in Erlang 5.4/OTP-R10B)
can distinguish between the different classes, whereas the
<A HREF="expressions.html#catch">catch</A>
expression can not. They are described in the Expressions chapter.
<P>
<CENTER>
<TABLE CELLSPACING=0 CELLPADDING=2 BORDER=1>
<CAPTION ALIGN=BOTTOM><EM>Exception Classes.</EM></CAPTION>
<TR>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<STRONG>Class</STRONG>
</TD>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<STRONG>Origin</STRONG>
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>error</CODE>
</TD>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
Run-time error for example <CODE>1+a</CODE>, or
the process called <CODE>erlang:error/1,2</CODE>
(appeared in Erlang 5.4/OTP-R10B) or
<CODE>erlang:fault/1,2</CODE> (old equivalent)
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>exit</CODE>
</TD>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
The process called <CODE>exit/1</CODE>
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>throw</CODE>
</TD>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
The process called <CODE>throw/1</CODE>
</TD>
</TR>
</TABLE>
</CENTER>
<P>An exception consists of its class, an exit reason
(the <A HREF="#exit_reasons">Exit Reason</A>),
and a stack trace (that aids in finding the code location of
the exception).
<P>The stack trace can be retreived using
<CODE>erlang:get_stacktrace/0</CODE> (new in Erlang 5.4/OTP-R10B
from within a <CODE>try</CODE> expression, and is returned for
exceptions of class <CODE>error</CODE> from a <CODE>catch</CODE> expression.
<P>An exception of class <CODE>error</CODE> is also known as a run-time
error.
<A NAME="9.3"><!-- Empty --></A>
<H3>9.3 Handling of Run-Time Errors in Erlang</H3>
<A NAME="9.3.1"><!-- Empty --></A>
<H4>9.3.1 Error Handling Within Processes</H4>
<P>It is possible to prevent run-time errors and other
exceptions from causing
the process to terminate by using <CODE>catch</CODE> or
<CODE>try</CODE>, see the Expressions chapter about
<A HREF="expressions.html#catch">Catch</A>
and <A HREF="expressions.html#try">Try</A>.<A NAME="9.3.2"><!-- Empty --></A>
<H4>9.3.2 Error Handling Between Processes</H4>
<P>Processes can monitor other processes and detect process
terminations, see
the <A HREF="processes.html#errors">Processes</A>
chapter.<A NAME="exit_reasons"><!-- Empty --></A><A NAME="9.4"><!-- Empty --></A>
<H3>9.4 Exit Reasons</H3>
<P>When a run-time error occurs,
that is an exception of class <CODE>error</CODE>,
the exit reason is a tuple <CODE>{Reason,Stack}</CODE>.
<CODE>Reason</CODE> is a term indicating the type of error:
<P>
<CENTER>
<TABLE CELLSPACING=0 CELLPADDING=2 BORDER=1>
<CAPTION ALIGN=BOTTOM><EM>Exit Reasons.</EM></CAPTION>
<TR>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<STRONG>Reason</STRONG>
</TD>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<STRONG>Type of error</STRONG>
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>badarg</CODE>
</TD>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
Argument is of wrong type.
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>badarith</CODE>
</TD>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
Argument is of wrong type in an arithmetic expression.
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>{badmatch,V}</CODE>
</TD>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
Evaluation of a match expression failed.
The value <CODE>V</CODE> did not match.
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>function_clause</CODE>
</TD>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
No matching function clause is found when evaluating a
function call.
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>{case_clause,V}</CODE>
</TD>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
No matching branch is found when evaluating a <CODE>case</CODE>
expression. The value <CODE>V</CODE> did not match.
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>if_clause</CODE>
</TD>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
No true branch is found when evaluating an <CODE>if</CODE>
expression.
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>{try_clause,V}</CODE>
</TD>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
No matching branch is found when evaluating the
of-section of a a <CODE>try</CODE>
expression. The value <CODE>V</CODE> did not match.
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>undef</CODE>
</TD>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
The function cannot be found when evaluating a function
call.
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>{badfun,F}</CODE>
</TD>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
There is something wrong with a fun <CODE>F</CODE>.
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>{badarity,F}</CODE>
</TD>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
A fun is applied to the wrong number of arguments.
<CODE>F</CODE> describes the fun and the arguments.
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>timeout_value</CODE>
</TD>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
The timeout value in a <CODE>receive..after</CODE> expression is
evaluated to something else than an integer or
<CODE>infinity</CODE>.
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>noproc</CODE>
</TD>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
Trying to link to a non-existing process.
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>{nocatch,V}</CODE>
</TD>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
Trying to evaluate a <CODE>throw</CODE> outside a <CODE>catch</CODE>.
<CODE>V</CODE> is the throw term.
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>system_limit</CODE>
</TD>
<TD ALIGN="LEFT" VALIGN="MIDDLE">
A system limit has been reached. See Efficiency Guide for
information about system limits.
</TD>
</TR>
</TABLE>
</CENTER>
<P><CODE>Stack</CODE> is the stack of function calls being evaluated
when the error occurred, given as a list of tuples
<CODE>{Module,Name,Arity}</CODE> with the most recent function call
first. The most recent function call tuple may in some
cases be <CODE>{Moule,Name,[Arg]}</CODE>.<CENTER>
<HR>
<SMALL>
Copyright © 1991-2006
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>
|
