From 01f96ee6197a7b5a2c64353a3b38260994ce5ad5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Thu, 16 Nov 2017 06:10:12 +0100 Subject: Add documentation for the new stacktrace syntax --- system/doc/reference_manual/errors.xml | 47 +++++++++++++++++++++++++++-- system/doc/reference_manual/expressions.xml | 32 ++++++++++++++------ 2 files changed, 67 insertions(+), 12 deletions(-) (limited to 'system/doc') diff --git a/system/doc/reference_manual/errors.xml b/system/doc/reference_manual/errors.xml index b16c5da6eb..16d3e7590e 100644 --- a/system/doc/reference_manual/errors.xml +++ b/system/doc/reference_manual/errors.xml @@ -108,14 +108,55 @@ (see Exit Reason), and a stack trace (which aids in finding the code location of the exception).

-

The stack trace can be retrieved using - erlang:get_stacktrace/0 - from within a try expression, and is returned for +

The stack trace can be be bound to a variable from within + a try expression, and is returned for exceptions of class error from a catch expression.

An exception of class error is also known as a run-time error.

+ +
+ The call-stack back trace (stacktrace) +

The stack back-trace (stacktrace) is a list of + {Module,Function,Arity,Location} + tuples. The field Arity in the first tuple can be the + argument list of that function call instead of an arity integer, + depending on the exception.

+ +

Location is a (possibly empty) list of two-tuples + that can indicate the location in the source code of the + function. The first element is an atom describing the type of + information in the second element. The following items can + occur:

+ + file + The second element of the tuple is a string (list of + characters) representing the filename of the source file + of the function. + + line + The second element of the tuple is the line number + (an integer > 0) in the source file + where the exception occurred or the function was called. + + +

Developers should rely on stacktrace entries only for + debugging purposes.

+

The VM performs tail call optimization, which + does not add new entries to the stacktrace, and also limits stacktraces + to a certain depth. Furthermore, compiler options, optimizations and + future changes may add or remove stacktrace entries, causing any code + that expects the stacktrace to be in a certain order or contain specific + items to fail.

+

The only exception to this rule is the class error with the + reason undef which is guaranteed to include the Module, + Function and Arity of the attempted + function as the first stacktrace entry.

+ +
+ +
Handling of Run-time Errors in Erlang diff --git a/system/doc/reference_manual/expressions.xml b/system/doc/reference_manual/expressions.xml index cf2d5034aa..94e40dd077 100644 --- a/system/doc/reference_manual/expressions.xml +++ b/system/doc/reference_manual/expressions.xml @@ -1340,9 +1340,9 @@ hello try Exprs catch - [Class1:]ExceptionPattern1 [when ExceptionGuardSeq1] -> + Class1:ExceptionPattern1[:Stacktrace] [when ExceptionGuardSeq1] -> ExceptionBody1; - [ClassN:]ExceptionPatternN [when ExceptionGuardSeqN] -> + ClassN:ExceptionPatternN[:Stacktrace] [when ExceptionGuardSeqN] -> ExceptionBodyN end

This is an enhancement of @@ -1362,10 +1362,12 @@ end the evaluation. In that case the exception is caught and the patterns ExceptionPattern with the right exception class Class are sequentially matched against the caught - exception. An omitted Class is shorthand for throw. - If a match succeeds and the optional guard sequence + exception. If a match succeeds and the optional guard sequence ExceptionGuardSeq is true, the corresponding ExceptionBody is evaluated to become the return value.

+

Stacktrace, if specified, must be the name of a variable + (not a pattern). The stack trace is bound to the variable when + the corresponding ExceptionPattern matches.

If an exception occurs during evaluation of Exprs but there is no matching ExceptionPattern of the right Class with a true guard sequence, the exception is passed @@ -1373,6 +1375,18 @@ end expression.

If an exception occurs during evaluation of ExceptionBody, it is not caught.

+

It is allowed to omit Class and Stacktrace. + An omitted Class is shorthand for throw:

+ + +try Exprs +catch + ExceptionPattern1 [when ExceptionGuardSeq1] -> + ExceptionBody1; + ExceptionPatternN [when ExceptionGuardSeqN] -> + ExceptionBodyN +end +

The try expression can have an of section:

@@ -1384,10 +1398,10 @@ try Exprs of PatternN [when GuardSeqN] -> BodyN catch - [Class1:]ExceptionPattern1 [when ExceptionGuardSeq1] -> + Class1:ExceptionPattern1[:Stacktrace] [when ExceptionGuardSeq1] -> ExceptionBody1; ...; - [ClassN:]ExceptionPatternN [when ExceptionGuardSeqN] -> + ClassN:ExceptionPatternN[:Stacktrace] [when ExceptionGuardSeqN] -> ExceptionBodyN end

If the evaluation of Exprs succeeds without an exception, @@ -1408,10 +1422,10 @@ try Exprs of PatternN [when GuardSeqN] -> BodyN catch - [Class1:]ExceptionPattern1 [when ExceptionGuardSeq1] -> + Class1:ExceptionPattern1[:Stacktrace] [when ExceptionGuardSeq1] -> ExceptionBody1; ...; - [ClassN:]ExceptionPatternN [when ExceptionGuardSeqN] -> + ClassN:ExceptionPatternN[:Stacktrace] [when ExceptionGuardSeqN] -> ExceptionBodyN after AfterBody @@ -1470,7 +1484,7 @@ try Expr catch throw:Term -> Term; exit:Reason -> {'EXIT',Reason} - error:Reason -> {'EXIT',{Reason,erlang:get_stacktrace()}} + error:Reason:Stk -> {'EXIT',{Reason,Stk}} end

-- cgit v1.2.3