Incorporating StackTraces into Base.

Tests and documentation for stacktraces.
Updated NEWS.md with stacktraces functionality.
Refactored, doctests, show_stacktrace is now show.
Added doctests to the manual.
Removed show_stacktrace in favour of show(x::StackFrame).
Removed format_stacktrace and format_stackframe.
Additional test cases (which currently fail due to difficult to track down line number issues)
Test for invalid frame. Removed failing Win32 test.
Reintroduced UNKNOWN constant stack frame from profile.jl.
Added test case for looking up an invalid stack frame.
Selectively removed some tests that consistently fail in Appveyor's 32-bit Windows LVM.

Author: spurll

NEWS.md

@@ -99,6 +99,8 @@ Library improvements
 
     * Improve performance of `quantile` ([#14413]).
 
+  * The new `Base.StackTraces` module makes stack traces easier to use programmatically. ([#14469])
+
 Deprecated or removed
 ---------------------
 
@@ -1779,3 +1781,4 @@ Too numerous to mention.
 [#14424]: https://github.com/JuliaLang/julia/issues/14424
 [#14759]: https://github.com/JuliaLang/julia/issues/14759
 [#14114]: https://github.com/JuliaLang/julia/issues/14114
+[#14469]: https://github.com/JuliaLang/julia/issues/14469

base/exports.jl

@@ -9,6 +9,7 @@ export
     Pkg,
     Git,
     LibGit2,
+    StackTraces,
     Profile,
     Dates,
     Sys,
@@ -1046,6 +1047,12 @@ export
     rethrow,
     systemerror,
 
+# stack traces
+    StackTrace,
+    StackFrame,
+    stacktrace,
+    catch_stacktrace,
+
 # types
     convert,
     fieldoffset,

base/profile.jl

@@ -2,7 +2,8 @@
 
 module Profile
 
-import Base: hash, ==, show_spec_linfo
+import Base: show_spec_linfo
+import Base.StackTraces: lookup, UNKNOWN
 
 export @profile
 
@@ -117,7 +118,7 @@ end
 
 function getdict(data::Vector{UInt})
     uip = unique(data)
-    Dict{UInt, LineInfo}([ip=>lookup(ip) for ip in uip])
+    Dict{UInt, StackFrame}([ip=>lookup(ip) for ip in uip])
 end
 
 # TODO update signature in docstring.
@@ -165,37 +166,6 @@ Julia, and examine the resulting `*.mem` files.
 """
 clear_malloc_data() = ccall(:jl_clear_malloc_data, Void, ())
 
-
-####
-#### Internal interface
-####
-immutable LineInfo
-    func::ByteString
-    inlined_file::ByteString
-    inlined_line::Int
-    file::ByteString
-    line::Int
-    outer_linfo::Nullable{LambdaStaticData}
-    fromC::Bool
-    ip::Int64 # large enough that this struct can be losslessly read on any machine (32 or 64 bit)
-end
-
-const UNKNOWN = LineInfo("?", "?", -1, "?", -1, Nullable{LambdaStaticData}(), true, 0)
-
-#
-# If the LineInfo has function and line information, we consider two of them the same
-# if they share the same function/line information. For unknown functions, line==ip
-# so we never actually need to consider the .ip field.
-#
-==(a::LineInfo, b::LineInfo) = a.line == b.line && a.fromC == b.fromC && a.func == b.func && a.file == b.file
-
-function hash(li::LineInfo, h::UInt)
-    h += 0xf4fbda67fe20ce88 % UInt
-    h = hash(li.line, h)
-    h = hash(li.file, h)
-    h = hash(li.func, h)
-end
-
 # C wrappers
 start_timer() = ccall(:jl_profile_start_timer, Cint, ())
 
@@ -209,24 +179,6 @@ len_data() = convert(Int, ccall(:jl_profile_len_data, Csize_t, ()))
 
 maxlen_data() = convert(Int, ccall(:jl_profile_maxlen_data, Csize_t, ()))
 
-const empty_sym = Symbol("")
-function lookup(ip::Ptr{Void})
-    info = ccall(:jl_lookup_code_address, Any, (Ptr{Void},Cint), ip, false)
-    if length(info) == 8
-        is_inlined = (info[4] !== empty_sym)
-        return LineInfo(string(info[1]),
-            is_inlined ? string(info[2]) : "",
-            is_inlined ? Int(info[3]) : -1,
-            string(is_inlined ? info[4] : info[2]),
-            Int(is_inlined ? info[5] : info[3]),
-            info[6] === nothing ? Nullable{LambdaStaticData}() : Nullable{LambdaStaticData}(info[6]),
-            info[7], Int64(info[8]))
-    else
-        return UNKNOWN
-    end
-end
-lookup(ip::UInt) = lookup(convert(Ptr{Void},ip))
-
 error_codes = Dict{Int,ASCIIString}(
     -1=>"cannot specify signal action for profiling",
     -2=>"cannot create the timer for profiling",
@@ -291,7 +243,7 @@ function parse_flat(iplist, n, lidict, C::Bool)
     # The ones with no line number might appear multiple times in a single
     # backtrace, giving the wrong impression about the total number of backtraces.
     # Delete them too.
-    keep = !Bool[x == UNKNOWN || x.line == 0 || (x.fromC && !C) for x in lilist]
+    keep = !Bool[x == UNKNOWN || x.line == 0 || (x.from_c && !C) for x in lilist]
     n = n[keep]
     lilist = lilist[keep]
     lilist, n
@@ -310,7 +262,7 @@ function flat{T<:Unsigned}(io::IO, data::Vector{T}, lidict::Dict, C::Bool, combi
     print_flat(io, lilist, n, combine, cols, sortedby)
 end
 
-function print_flat(io::IO, lilist::Vector{LineInfo}, n::Vector{Int}, combine::Bool, cols::Integer, sortedby)
+function print_flat(io::IO, lilist::Vector{StackFrame}, n::Vector{Int}, combine::Bool, cols::Integer, sortedby)
     p = liperm(lilist)
     lilist = lilist[p]
     n = n[p]
@@ -339,8 +291,8 @@ function print_flat(io::IO, lilist::Vector{LineInfo}, n::Vector{Int}, combine::B
     maxfunc = 10
     for li in lilist
         maxline = max(maxline, li.line)
-        maxfile = max(maxfile, length(li.file))
-        maxfunc = max(maxfunc, length(li.func))
+        maxfile = max(maxfile, length(string(li.file)))
+        maxfunc = max(maxfunc, length(string(li.func)))
     end
     wline = max(5, ndigits(maxline))
     ntext = cols - wcounts - wline - 3
@@ -389,9 +341,9 @@ function tree_aggregate{T<:Unsigned}(data::Vector{T})
     bt, counts
 end
 
-tree_format_linewidth(x::LineInfo) = ndigits(x.line)+6
+tree_format_linewidth(x::StackFrame) = ndigits(x.line)+6
 
-function tree_format(lilist::Vector{LineInfo}, counts::Vector{Int}, level::Int, cols::Integer)
+function tree_format(lilist::Vector{StackFrame}, counts::Vector{Int}, level::Int, cols::Integer)
     nindent = min(cols>>1, level)
     ndigcounts = ndigits(maximum(counts))
     ndigline = maximum([tree_format_linewidth(x) for x in lilist])
@@ -412,20 +364,22 @@ function tree_format(lilist::Vector{LineInfo}, counts::Vector{Int}, level::Int,
             if showextra
                 base = string(base, "+", nextra, " ")
             end
-            if li.line == li.ip
+            if li.line == li.pointer
                 strs[i] = string(base,
                           rpad(string(counts[i]), ndigcounts, " "),
-                          " ","unknown function (ip: 0x",hex(li.ip,2*sizeof(Ptr{Void})),
+                          " ",
+                          "unknown function (pointer: 0x",
+                          hex(li.pointer,2*sizeof(Ptr{Void})),
                           ")")
             else
-                fname = li.func
+                fname = string(li.func)
                 if !li.fromC && !isnull(li.outer_linfo)
                     fname = sprint(show_spec_linfo, Symbol(li.func), get(li.outer_linfo))
                 end
                 strs[i] = string(base,
                               rpad(string(counts[i]), ndigcounts, " "),
                               " ",
-                              rtruncto(li.file, widthfile),
+                              rtruncto(string(li.file), widthfile),
                               ":",
                               li.line == -1 ? "?" : string(li.line),
                               "; ",
@@ -446,7 +400,7 @@ function tree{T<:Unsigned}(io::IO, bt::Vector{Vector{T}}, counts::Vector{Int}, l
     # Organize backtraces into groups that are identical up to this level
     if combine
         # Combine based on the line information
-        d = Dict{LineInfo,Vector{Int}}()
+        d = Dict{StackFrame,Vector{Int}}()
         for i = 1:length(bt)
             ip = bt[i][level+1]
             key = lidict[ip]
@@ -459,7 +413,7 @@ function tree{T<:Unsigned}(io::IO, bt::Vector{Vector{T}}, counts::Vector{Int}, l
         end
         # Generate counts
         dlen = length(d)
-        lilist = Array(LineInfo, dlen)
+        lilist = Array(StackFrame, dlen)
         group = Array(Vector{Int}, dlen)
         n = Array(Int, dlen)
         i = 1
@@ -483,7 +437,7 @@ function tree{T<:Unsigned}(io::IO, bt::Vector{Vector{T}}, counts::Vector{Int}, l
         end
         # Generate counts, and do the code lookup
         dlen = length(d)
-        lilist = Array(LineInfo, dlen)
+        lilist = Array(StackFrame, dlen)
         group = Array(Vector{Int}, dlen)
         n = Array(Int, dlen)
         i = 1
@@ -534,7 +488,7 @@ function tree{T<:Unsigned}(io::IO, data::Vector{T}, lidict::Dict, C::Bool, combi
 end
 
 function callersf(matchfunc::Function, bt::Vector{UInt}, lidict)
-    counts = Dict{LineInfo, Int}()
+    counts = Dict{StackFrame, Int}()
     lastmatched = false
     for id in bt
         if id == 0
@@ -574,8 +528,10 @@ function ltruncto(str::ByteString, w::Int)
 end
 
 
+truncto(str::Symbol, w::Int) = truncto(string(str), w)
+
 # Order alphabetically (file, function) and then by line number
-function liperm(lilist::Vector{LineInfo})
+function liperm(lilist::Vector{StackFrame})
     comb = Array(ByteString, length(lilist))
     for i = 1:length(lilist)
         li = lilist[i]
@@ -594,7 +550,7 @@ warning_empty() = warn("""
             Profile.init().""")
 
 function purgeC(data, lidict)
-    keep = Bool[d == 0 || lidict[d].fromC == false for d in data]
+    keep = Bool[d == 0 || lidict[d].from_c == false for d in data]
     data[keep]
 end
 

base/stacktraces.jl

@@ -0,0 +1,154 @@
+# This file is a part of Julia. License is MIT: http://julialang.org/license
+
+module StackTraces
+
+
+import Base: hash, ==, show
+
+export StackTrace, StackFrame, stacktrace, catch_stacktrace
+
+"""
+    StackFrame
+
+Stack information representing execution context.
+"""
+immutable StackFrame
+    "the name of the function containing the execution context"
+    func::Symbol
+    "the LambdaStaticData for the the execution context"
+    outer_linfo::Nullable{LambdaStaticData}
+    "the path to the file containing the execution context"
+    file::Symbol
+    "the line number in the file containing the execution context"
+    line::Int
+    "the path to the file containing the context for code inlined into the execution context"
+    inlined_file::Symbol
+    "the line number in the file containing the context for code inlined into the execution context"
+    inlined_line::Int
+    "true if the code is from C"
+    from_c::Bool
+    "representation of the pointer to the execution context as returned by `backtrace`"
+    pointer::Int64  # Large enough to be read losslessly on 32- and 64-bit machines.
+end
+
+StackFrame(func, file, line) = StackFrame(func, file, line, symbol(""), -1, false, 0)
+
+"""
+    StackTrace
+
+An alias for `Vector{StackFrame}` provided for convenience; returned by calls to
+`stacktrace` and `catch_stacktrace`.
+"""
+typealias StackTrace Vector{StackFrame}
+
+const empty_symbol = symbol("")
+const unk_symbol = symbol("???")
+const UNKNOWN = StackFrame(unk_symbol, Nullable{LambdaStaticData}(), unk_symbol, 0, empty_symbol, -1, true, 0)
+
+
+#=
+If the StackFrame has function and line information, we consider two of them the same if
+they share the same function/line information. For unknown functions, line == pointer, so we
+never actually need to consider the pointer field.
+=#
+function ==(a::StackFrame, b::StackFrame)
+    a.line == b.line && a.from_c == b.from_c && a.func == b.func && a.file == b.file
+end
+
+function hash(frame::StackFrame, h::UInt)
+    h += 0xf4fbda67fe20ce88 % UInt
+    h = hash(frame.line, h)
+    h = hash(frame.file, h)
+    h = hash(frame.func, h)
+end
+
+
+"""
+    lookup(pointer::Union{Ptr{Void}, UInt}) -> StackFrame
+
+Given a pointer to an execution context (usually generated by a call to `backtrace`), looks
+up stack frame context information.
+"""
+function lookup(pointer::Ptr{Void})
+    info = ccall(:jl_lookup_code_address, Any, (Ptr{Void}, Cint), ip, false)
+    if length(info) == 8
+        is_inlined = (info[4] !== empty_sym)
+        return LineInfo(string(info[1]),
+            info[6] === nothing ? Nullable{LambdaStaticData}() : Nullable{LambdaStaticData}(info[6]),
+            is_inlined ? info[4] : info[2],
+            Int(is_inlined ? info[5] : info[3]),
+            is_inlined ? info[2] : "",
+            is_inlined ? Int(info[3]) : -1,
+            info[7], Int64(info[8]))
+    else
+        return UNKNOWN
+    end
+end
+
+lookup(pointer::UInt) = lookup(convert(Ptr{Void}, pointer))
+
+"""
+    stacktrace([trace::Vector{Ptr{Void}},] [c_funcs::Bool=false]) -> StackTrace
+
+Returns a stack trace in the form of a vector of `StackFrame`s. (By default stacktrace
+doesn't return C functions, but this can be enabled.) When called without specifying a
+trace, `stacktrace` first calls `backtrace`.
+"""
+function stacktrace(trace::Vector{Ptr{Void}}, c_funcs::Bool=false)
+    stack = map(lookup, trace)::StackTrace
+
+    # Remove frames that come from C calls.
+    if !c_funcs
+        filter!(frame -> !frame.from_c, stack)
+    end
+
+    # Remove frame for this function (and any functions called by this function).
+    remove_frames!(stack, :stacktrace)
+end
+
+stacktrace(c_funcs::Bool=false) = stacktrace(backtrace(), c_funcs)
+
+"""
+    catch_stacktrace([c_funcs::Bool=false]) -> StackTrace
+
+Returns the stack trace for the most recent error thrown, rather than the current execution
+context.
+"""
+catch_stacktrace(c_funcs::Bool=false) = stacktrace(catch_backtrace(), c_funcs)
+
+"""
+    remove_frames!(stack::StackTrace, name::Symbol)
+
+Takes a `StackTrace` (a vector of `StackFrames`) and a function name (a `Symbol`) and
+removes the `StackFrame` specified by the function name from the `StackTrace` (also removing
+all frames above the specified function). Primarily used to remove `StackTraces` functions
+from the `StackTrace` prior to returning it.
+"""
+function remove_frames!(stack::StackTrace, name::Symbol)
+    splice!(stack, 1:findlast(frame -> frame.func == name, stack))
+    return stack
+end
+
+function remove_frames!(stack::StackTrace, names::Vector{Symbol})
+    splice!(stack, 1:findlast(frame -> frame.func in names, stack))
+    return stack
+end
+
+function show(io::IO, frame::StackFrame; full_path::Bool=false)
+    file_info = "$(full_path ? frame.file : basename(string(frame.file))):$(frame.line)"
+
+    if frame.inlined_file != Symbol("")
+        inline_info = string("[inlined code from ", file_info, "] ")
+        file_info = string(
+            full_path ? frame.inlined_file : basename(string(frame.inlined_file)),
+            ":", frame.inlined_line
+        )
+    else
+        inline_info = ""
+    end
+
+    print(io, string(inline_info, frame.func != "" ? frame.func : "?", " at ", file_info))
+end
+
+
+end