Merge pull request #26960 from Liozou/outlining

Update stacktraces docs

Author: Keno

doc/src/manual/stacktraces.md

@@ -8,12 +8,13 @@ easy to use programmatically.
 The primary function used to obtain a stack trace is [`stacktrace`](@ref):
 
 ```julia-repl
-julia> stacktrace()
-4-element Array{StackFrame,1}:
- eval(::Module, ::Any) at boot.jl:236
- eval_user_input(::Any, ::Base.REPL.REPLBackend) at REPL.jl:66
- macro expansion at REPL.jl:97 [inlined]
- (::Base.REPL.##1#2{Base.REPL.REPLBackend})() at event.jl:73
+6-element Array{Base.StackTraces.StackFrame,1}:
+ top-level scope
+ eval at boot.jl:317 [inlined]
+ eval(::Module, ::Expr) at REPL.jl:5
+ eval_user_input(::Any, ::REPL.REPLBackend) at REPL.jl:85
+ macro expansion at REPL.jl:116 [inlined]
+ (::getfield(REPL, Symbol("##28#29")){REPL.REPLBackend})() at event.jl:92
 ```
 
 Calling [`stacktrace()`](@ref) returns a vector of [`StackTraces.StackFrame`](@ref) s. For ease of use, the
@@ -25,9 +26,10 @@ julia> example() = stacktrace()
 example (generic function with 1 method)
 
 julia> example()
-5-element Array{StackFrame,1}:
+7-element Array{Base.StackTraces.StackFrame,1}:
  example() at REPL[1]:1
- eval(::Module, ::Any) at boot.jl:236
+ top-level scope
+ eval at boot.jl:317 [inlined]
 [...]
 
 julia> @noinline child() = stacktrace()
@@ -40,14 +42,14 @@ julia> grandparent() = parent()
 grandparent (generic function with 1 method)
 
 julia> grandparent()
-7-element Array{StackFrame,1}:
+9-element Array{Base.StackTraces.StackFrame,1}:
  child() at REPL[3]:1
  parent() at REPL[4]:1
  grandparent() at REPL[5]:1
 [...]
 ```
 
-Note that when calling [`stacktrace()`](@ref) you'll typically see a frame with `eval(...) at boot.jl`.
+Note that when calling [`stacktrace()`](@ref) you'll typically see a frame with `eval at boot.jl`.
 When calling [`stacktrace()`](@ref) from the REPL you'll also have a few extra frames in the stack
 from `REPL.jl`, usually looking something like this:
 
@@ -56,12 +58,14 @@ julia> example() = stacktrace()
 example (generic function with 1 method)
 
 julia> example()
-5-element Array{StackFrame,1}:
+7-element Array{Base.StackTraces.StackFrame,1}:
  example() at REPL[1]:1
- eval(::Module, ::Any) at boot.jl:236
- eval_user_input(::Any, ::Base.REPL.REPLBackend) at REPL.jl:66
- macro expansion at REPL.jl:97 [inlined]
- (::Base.REPL.##1#2{Base.REPL.REPLBackend})() at event.jl:73
+ top-level scope
+ eval at boot.jl:317 [inlined]
+ eval(::Module, ::Expr) at REPL.jl:5
+ eval_user_input(::Any, ::REPL.REPLBackend) at REPL.jl:85
+ macro expansion at REPL.jl:116 [inlined]
+ (::getfield(REPL, Symbol("##28#29")){REPL.REPLBackend})() at event.jl:92
 ```
 
 ## Extracting useful information
@@ -72,17 +76,17 @@ default C functions do not appear in the stack trace), and an integer representa
 returned by [`backtrace`](@ref):
 
 ```julia-repl
-julia> top_frame = stacktrace()[1]
-eval(::Module, ::Expr) at REPL.jl:3
+julia> frame = stacktrace()[3]
+eval(::Module, ::Expr) at REPL.jl:5
 
-julia> top_frame.func
+julia> frame.func
 :eval
 
-julia> top_frame.file
-Symbol("./boot.jl")
+julia> frame.file
+Symbol("~/julia/usr/share/julia/stdlib/v0.7/REPL/src/REPL.jl")
 
-julia> top_frame.line
-236
+julia> frame.line
+5
 
 julia> top_frame.linfo
 MethodInstance for eval(::Module, ::Expr)
@@ -96,7 +100,7 @@ false
 
 ```julia-repl
 julia> top_frame.pointer
-0x00007f390d152a59
+0x00007f92d6293171
 ```
 
 This makes stack trace information available programmatically for logging, error handling, and
@@ -119,9 +123,10 @@ julia> @noinline example() = try
 example (generic function with 1 method)
 
 julia> example()
-5-element Array{StackFrame,1}:
+7-element Array{Base.StackTraces.StackFrame,1}:
  example() at REPL[2]:4
- eval(::Module, ::Any) at boot.jl:236
+ top-level scope
+ eval at boot.jl:317 [inlined]
 [...]
 ```
 
@@ -147,7 +152,7 @@ julia> @noinline example() = try
 example (generic function with 1 method)
 
 julia> example()
-6-element Array{StackFrame,1}:
+8-element Array{Base.StackTraces.StackFrame,1}:
  bad_function() at REPL[1]:1
  example() at REPL[2]:2
 [...]
@@ -174,7 +179,8 @@ grandparent (generic function with 1 method)
 
 julia> grandparent()
 ERROR: Whoops!
-7-element Array{StackFrame,1}:
+10-element Array{Base.StackTraces.StackFrame,1}:
+ error at error.jl:33 [inlined]
  child() at REPL[1]:1
  parent() at REPL[2]:1
  grandparent() at REPL[3]:3
@@ -183,77 +189,63 @@ ERROR: Whoops!
 
 ## Comparison with [`backtrace`](@ref)
 
-A call to [`backtrace`](@ref) returns a vector of `Ptr{Cvoid}`, which may then be passed into
+A call to [`backtrace`](@ref) returns a vector of `Union{Ptr{Nothing}, Base.InterpreterIP}`, which may then be passed into
 [`stacktrace`](@ref) for translation:
 
 ```julia-repl
 julia> trace = backtrace()
-21-element Array{Ptr{Cvoid},1}:
- Ptr{Cvoid} @0x00007f10049d5b2f
- Ptr{Cvoid} @0x00007f0ffeb4d29c
- Ptr{Cvoid} @0x00007f0ffeb4d2a9
- Ptr{Cvoid} @0x00007f1004993fe7
- Ptr{Cvoid} @0x00007f10049a92be
- Ptr{Cvoid} @0x00007f10049a823a
- Ptr{Cvoid} @0x00007f10049a9fb0
- Ptr{Cvoid} @0x00007f10049aa718
- Ptr{Cvoid} @0x00007f10049c0d5e
- Ptr{Cvoid} @0x00007f10049a3286
- Ptr{Cvoid} @0x00007f0ffe9ba3ba
- Ptr{Cvoid} @0x00007f0ffe9ba3d0
- Ptr{Cvoid} @0x00007f1004993fe7
- Ptr{Cvoid} @0x00007f0ded34583d
- Ptr{Cvoid} @0x00007f0ded345a87
- Ptr{Cvoid} @0x00007f1004993fe7
- Ptr{Cvoid} @0x00007f0ded34308f
- Ptr{Cvoid} @0x00007f0ded343320
- Ptr{Cvoid} @0x00007f1004993fe7
- Ptr{Cvoid} @0x00007f10049aeb67
- Ptr{Cvoid} @0x0000000000000000
+18-element Array{Union{Ptr{Nothing}, Base.InterpreterIP},1}:
+ Ptr{Nothing} @0x00007fd8734c6209
+ Ptr{Nothing} @0x00007fd87362b342
+ Ptr{Nothing} @0x00007fd87362c136
+ Ptr{Nothing} @0x00007fd87362c986
+ Ptr{Nothing} @0x00007fd87362d089
+ Base.InterpreterIP(CodeInfo(:(begin
+      Core.SSAValue(0) = backtrace()
+      trace = Core.SSAValue(0)
+      return Core.SSAValue(0)
+  end)), 0x0000000000000000)
+ Ptr{Nothing} @0x00007fd87362e4cf
+[...]
 
 julia> stacktrace(trace)
-5-element Array{StackFrame,1}:
- backtrace() at error.jl:46
- eval(::Module, ::Any) at boot.jl:236
- eval_user_input(::Any, ::Base.REPL.REPLBackend) at REPL.jl:66
- macro expansion at REPL.jl:97 [inlined]
- (::Base.REPL.##1#2{Base.REPL.REPLBackend})() at event.jl:73
+6-element Array{Base.StackTraces.StackFrame,1}:
+ top-level scope
+ eval at boot.jl:317 [inlined]
+ eval(::Module, ::Expr) at REPL.jl:5
+ eval_user_input(::Any, ::REPL.REPLBackend) at REPL.jl:85
+ macro expansion at REPL.jl:116 [inlined]
+ (::getfield(REPL, Symbol("##28#29")){REPL.REPLBackend})() at event.jl:92
 ```
 
-Notice that the vector returned by [`backtrace`](@ref) had 21 pointers, while the vector returned
-by [`stacktrace`](@ref) only has 5. This is because, by default, [`stacktrace`](@ref) removes
+Notice that the vector returned by [`backtrace`](@ref) had 18 elements, while the vector returned
+by [`stacktrace`](@ref) only has 6. This is because, by default, [`stacktrace`](@ref) removes
 any lower-level C functions from the stack. If you want to include stack frames from C calls,
 you can do it like this:
 
 ```julia-repl
 julia> stacktrace(trace, true)
-27-element Array{StackFrame,1}:
- jl_backtrace_from_here at stackwalk.c:103
- backtrace() at error.jl:46
- backtrace() at sys.so:?
- jl_call_method_internal at julia_internal.h:248 [inlined]
- jl_apply_generic at gf.c:2215
- do_call at interpreter.c:75
- eval at interpreter.c:215
- eval_body at interpreter.c:519
- jl_interpret_toplevel_thunk at interpreter.c:664
- jl_toplevel_eval_flex at toplevel.c:592
- jl_toplevel_eval_in at builtins.c:614
- eval(::Module, ::Any) at boot.jl:236
- eval(::Module, ::Any) at sys.so:?
- jl_call_method_internal at julia_internal.h:248 [inlined]
- jl_apply_generic at gf.c:2215
- eval_user_input(::Any, ::Base.REPL.REPLBackend) at REPL.jl:66
- ip:0x7f1c707f1846
- jl_call_method_internal at julia_internal.h:248 [inlined]
- jl_apply_generic at gf.c:2215
- macro expansion at REPL.jl:97 [inlined]
- (::Base.REPL.##1#2{Base.REPL.REPLBackend})() at event.jl:73
- ip:0x7f1c707ea1ef
- jl_call_method_internal at julia_internal.h:248 [inlined]
- jl_apply_generic at gf.c:2215
- jl_apply at julia.h:1411 [inlined]
- start_task at task.c:261
+21-element Array{Base.StackTraces.StackFrame,1}:
+ jl_apply_generic at gf.c:2167
+ do_call at interpreter.c:324
+ eval_value at interpreter.c:416
+ eval_body at interpreter.c:559
+ jl_interpret_toplevel_thunk_callback at interpreter.c:798
+ top-level scope
+ jl_interpret_toplevel_thunk at interpreter.c:807
+ jl_toplevel_eval_flex at toplevel.c:856
+ jl_toplevel_eval_in at builtins.c:624
+ eval at boot.jl:317 [inlined]
+ eval(::Module, ::Expr) at REPL.jl:5
+ jl_apply_generic at gf.c:2167
+ eval_user_input(::Any, ::REPL.REPLBackend) at REPL.jl:85
+ jl_apply_generic at gf.c:2167
+ macro expansion at REPL.jl:116 [inlined]
+ (::getfield(REPL, Symbol("##28#29")){REPL.REPLBackend})() at event.jl:92
+ jl_fptr_trampoline at gf.c:1838
+ jl_apply_generic at gf.c:2167
+ jl_apply at julia.h:1540 [inlined]
+ start_task at task.c:268
  ip:0xffffffffffffffff
 ```
 
@@ -264,9 +256,10 @@ s by passing them into [`StackTraces.lookup`](@ref):
 julia> pointer = backtrace()[1];
 
 julia> frame = StackTraces.lookup(pointer)
-1-element Array{StackFrame,1}:
- jl_backtrace_from_here at stackwalk.c:103
+1-element Array{Base.StackTraces.StackFrame,1}:
+ jl_apply_generic at gf.c:2167
 
 julia> println("The top frame is from $(frame[1].func)!")
-The top frame is from jl_backtrace_from_here!
+The top frame is from jl_apply_generic!
 ```
+