aboutsummaryrefslogtreecommitdiffstats
path: root/erts/doc/src/erlang.xml
diff options
context:
space:
mode:
authorBjörn Gustavsson <[email protected]>2017-05-02 05:41:17 +0200
committerBjörn Gustavsson <[email protected]>2017-05-12 10:32:03 +0200
commit7b169140b2d37f43996b9d1a94877926a471d97d (patch)
tree8b5c4039533567a4704f9cab3e38a2434bdd8e6f /erts/doc/src/erlang.xml
parentc3a81d86c0ad0245cd47ff17aee70dc816c07e39 (diff)
downloadotp-7b169140b2d37f43996b9d1a94877926a471d97d.tar.gz
otp-7b169140b2d37f43996b9d1a94877926a471d97d.tar.bz2
otp-7b169140b2d37f43996b9d1a94877926a471d97d.zip
Warn for potentially unsafe use of get_stacktrace/0
erlang:get_stacktrace/0 returns the stacktrace for the latest exception. The problem is that the stacktrace is kept until the next exception occurs. If the last exception was a 'function_clause' or a 'badarg', the arguments for the call are also kept forever. The arguments can be terms of any size (potentially huge). In a future release, we would like to only allow erlang:get_stacktrace/0 from within a 'try' expression. That would make it possible to clear the stacktrace when the 'try' expression is exited. The 'catch' expression has no natural end where the stacktrace could be cleared. The stacktrace could be cleared at the end of the function that the 'catch' occurs in, but that would cause problems in the following scenario (from real life, but simplified): try ... catch _:_ -> io:format(...), io:format("~p\n", [erlang:get_stacktrace()]) end. %% In io.erl. format(Fmt, Args) -> Res = case ... of SomePattern -> catch... ...; SomeOtherPattern -> %% Output the formatted string here ... end, clear_stacktrace(), %% Inserted by compiler. Res. The call to io:format() would always clear the stacktrace before it could be retrieved. That problem could be solved by tightning the scope in which the stacktrace is kept, but the rules for how long erlang:get_stacktrace/0 would work would become complicated. Therefore, the solution we suggest for a future major release of OTP is that erlang:get_stacktrace/0 will return [] if it is called outside the 'catch' part of a 'try' expression. To help users prepare, introduce a warning when it is likely that erlang:get_stacktrace/0 will always return an empty list, for example in this code: catch error(foo), Stk = erlang:get_stacktrace() or in this code: try Expr catch _:_ -> ok end, Stk = erlang:get_stacktrace()
Diffstat (limited to 'erts/doc/src/erlang.xml')
-rw-r--r--erts/doc/src/erlang.xml28
1 files changed, 26 insertions, 2 deletions
diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index 6f70ae4a52..6d165e9eff 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -1813,8 +1813,9 @@ true</pre>
<fsummary>Get the call stack back-trace of the last exception.</fsummary>
<type name="stack_item"/>
<desc>
- <p>Gets the call stack back-trace (<em>stacktrace</em>) of the
- last exception in the calling process as a list of
+ <p>Gets the call stack back-trace (<em>stacktrace</em>) for an
+ exception that has just been caught
+ in the calling process as a list of
<c>{<anno>Module</anno>,<anno>Function</anno>,<anno>Arity</anno>,<anno>Location</anno>}</c>
tuples. Field <c><anno>Arity</anno></c> in the first tuple can be the
argument list of that function call instead of an arity integer,
@@ -1822,6 +1823,29 @@ true</pre>
<p>If there has not been any exceptions in a process, the
stacktrace is <c>[]</c>. After a code change for the process,
the stacktrace can also be reset to <c>[]</c>.</p>
+ <p><c>erlang:get_stacktrace/0</c> is only guaranteed to return
+ a stacktrace if called (directly or indirectly) from within the
+ scope of a <c>try</c> expression. That is, the following call works:</p>
+<pre>
+try Expr
+catch
+ C:R ->
+ {C,R,erlang:get_stacktrace()}
+end</pre>
+ <p>As does this call:</p>
+<pre>
+try Expr
+catch
+ C:R ->
+ {C,R,helper()}
+end
+
+helper() ->
+ erlang:get_stacktrace().</pre>
+
+ <warning><p>In a future release,
+ <c>erlang:get_stacktrace/0</c> will return <c>[]</c> if called
+ from outside a <c>try</c> expression.</p></warning>
<p>The stacktrace is the same data as operator <c>catch</c>
returns, for example:</p>
<pre>