Exception stack API refinements (JuliaLang#29901)

* Rename the non-exported `catch_stack()` to the more descriptive name
  `current_exceptions()`. Keep the old name available but deprecated.

* Introduce an ExceptionStack as the return type for the function, which
  (as an AbstractVector) is API-compatible with the previous type
  returned by `catch_stack()`

Having ExceptionStack gives us a place to integrate exception printing
in a natural way. In the same way this should be useful for dispatch in
other areas of the ecosystem which want to dispatch on exception stacks.

Author: c42f

NEWS.md

@@ -87,6 +87,7 @@ Standard library changes
   ```
   ([#39322])
 * `@lock` is now exported from Base ([#39588]).
+* The experimental function `Base.catch_stack()` has been renamed to `current_exceptions()`, exported from Base and given a more specific return type ([#29901])
 
 #### Package Manager
 

base/client.jl

@@ -98,13 +98,13 @@ function display_error(io::IO, er, bt)
     showerror(IOContext(io, :limit => true), er, bt, backtrace = bt!==nothing)
     println(io)
 end
-function display_error(io::IO, stack::Vector)
+function display_error(io::IO, stack::ExceptionStack)
     printstyled(io, "ERROR: "; bold=true, color=Base.error_color())
     bt = Any[ (x[1], scrub_repl_backtrace(x[2])) for x in stack ]
     show_exception_stack(IOContext(io, :limit => true), bt)
     println(io)
 end
-display_error(stack::Vector) = display_error(stderr, stack)
+display_error(stack::ExceptionStack) = display_error(stderr, stack)
 display_error(er, bt=nothing) = display_error(stderr, er, bt)
 
 function eval_user_input(errio, @nospecialize(ast), show_value::Bool)
@@ -143,7 +143,7 @@ function eval_user_input(errio, @nospecialize(ast), show_value::Bool)
                 @error "SYSTEM: display_error(errio, lasterr) caused an error"
             end
             errcount += 1
-            lasterr = catch_stack()
+            lasterr = current_exceptions()
             if errcount > 2
                 @error "It is likely that something important is broken, and Julia will not be able to continue normally" errcount
                 break
@@ -257,7 +257,7 @@ function exec_options(opts)
         try
             load_julia_startup()
         catch
-            invokelatest(display_error, catch_stack())
+            invokelatest(display_error, current_exceptions())
             !(repl || is_interactive) && exit(1)
         end
     end
@@ -291,7 +291,7 @@ function exec_options(opts)
         try
             include(Main, PROGRAM_FILE)
         catch
-            invokelatest(display_error, catch_stack())
+            invokelatest(display_error, current_exceptions())
             if !is_interactive::Bool
                 exit(1)
             end
@@ -494,7 +494,7 @@ function _start()
     try
         exec_options(JLOptions())
     catch
-        invokelatest(display_error, catch_stack())
+        invokelatest(display_error, current_exceptions())
         exit(1)
     end
     if is_interactive && get(stdout, :color, false)

base/deprecated.jl

@@ -250,4 +250,7 @@ cat_shape(dims, shape::Tuple{}) = () # make sure `cat_shape(dims, ())` do not re
     return getfield(x, s)
 end
 
+# This function was marked as experimental and not exported.
+@deprecate catch_stack(task=current_task(); include_bt=true) current_exceptions(task; backtrace=include_bt) false
+
 # END 1.7 deprecations

base/error.jl

@@ -54,7 +54,7 @@ exception will continue propagation as if it had not been caught.
     the program state at the time of the error so you're encouraged to instead
     throw a new exception using `throw(e)`. In Julia 1.1 and above, using
     `throw(e)` will preserve the root cause exception on the stack, as
-    described in [`catch_stack`](@ref).
+    described in [`current_exceptions`](@ref).
 """
 rethrow() = ccall(:jl_rethrow, Bottom, ())
 rethrow(@nospecialize(e)) = ccall(:jl_rethrow_other, Bottom, (Any,), e)
@@ -123,32 +123,38 @@ function catch_backtrace()
     return _reformat_bt(bt::Vector{Ptr{Cvoid}}, bt2::Vector{Any})
 end
 
+struct ExceptionStack <: AbstractArray{Any,1}
+    stack
+end
+
 """
-    catch_stack(task=current_task(); [inclue_bt=true])
+    current_exceptions(task=current_task(); [inclue_bt=true])
 
 Get the stack of exceptions currently being handled. For nested catch blocks
 there may be more than one current exception in which case the most recently
-thrown exception is last in the stack. The stack is returned as a Vector of
-`(exception,backtrace)` pairs, or a Vector of exceptions if `include_bt` is
-false.
+thrown exception is last in the stack. The stack is returned as an
+`ExceptionStack` which is an AbstractVector of named tuples
+`(exception,backtrace)`. If `backtrace` is false, the backtrace in each pair
+will be set to `nothing`.
 
 Explicitly passing `task` will return the current exception stack on an
 arbitrary task. This is useful for inspecting tasks which have failed due to
 uncaught exceptions.
 
-!!! compat "Julia 1.1"
-    This function is experimental in Julia 1.1 and will likely be renamed in a
-    future release (see https://github.com/JuliaLang/julia/pull/29901).
+!!! compat "Julia 1.7"
+    This function went by the experiemental name `catch_stack()` in Julia
+    1.1–1.6, and had a plain Vector-of-tuples as a return type.
 """
-function catch_stack(task=current_task(); include_bt=true)
-    raw = ccall(:jl_get_excstack, Any, (Any,Cint,Cint), task, include_bt, typemax(Cint))::Vector{Any}
+function current_exceptions(task=current_task(); backtrace=true)
+    raw = ccall(:jl_get_excstack, Any, (Any,Cint,Cint), task, backtrace, typemax(Cint))::Vector{Any}
     formatted = Any[]
-    stride = include_bt ? 3 : 1
+    stride = backtrace ? 3 : 1
     for i = reverse(1:stride:length(raw))
-        e = raw[i]
-        push!(formatted, include_bt ? (e,Base._reformat_bt(raw[i+1],raw[i+2])) : e)
+        exc = raw[i]
+        bt = backtrace ? Base._reformat_bt(raw[i+1],raw[i+2]) : nothing
+        push!(formatted, (exception=exc,backtrace=bt))
     end
-    formatted
+    ExceptionStack(formatted)
 end
 
 ## keyword arg lowering generates calls to this ##

base/errorshow.jl

@@ -849,7 +849,7 @@ function process_backtrace(t::Vector, limit::Int=typemax(Int); skipC = true)
     return _simplify_include_frames(ret)
 end
 
-function show_exception_stack(io::IO, stack::Vector)
+function show_exception_stack(io::IO, stack)
     # Display exception stack with the top of the stack first.  This ordering
     # means that the user doesn't have to scroll up in the REPL to discover the
     # root cause.
@@ -886,3 +886,15 @@ function noncallable_number_hint_handler(io, ex, arg_types, kwargs)
 end
 
 Experimental.register_error_hint(noncallable_number_hint_handler, MethodError)
+
+# ExceptionStack implementation
+size(s::ExceptionStack) = size(s.stack)
+getindex(s::ExceptionStack, i::Int) = s.stack[i]
+
+function show(io::IO, ::MIME"text/plain", stack::ExceptionStack)
+    nexc = length(stack)
+    printstyled(io, nexc, "-element ExceptionStack", nexc == 0 ? "" : ":\n")
+    show_exception_stack(io, stack)
+end
+show(io::IO, stack::ExceptionStack) = show(io, MIME("text/plain"), stack)
+

base/exports.jl

@@ -716,6 +716,7 @@ export
 # errors
     backtrace,
     catch_backtrace,
+    current_exceptions,
     error,
     rethrow,
     retry,

base/task.jl

@@ -77,7 +77,7 @@ function showerror(io::IO, ex::TaskFailedException, bt = nothing; backtrace=true
 end
 
 function show_task_exception(io::IO, t::Task; indent = true)
-    stack = catch_stack(t)
+    stack = current_exceptions(t)
     b = IOBuffer()
     if isempty(stack)
         # exception stack buffer not available; probably a serialized task
@@ -162,7 +162,7 @@ end
         end
     elseif field === :backtrace
         # TODO: this field name should be deprecated in 2.0
-        return catch_stack(t)[end][2]
+        return current_exceptions(t)[end][2]
     elseif field === :exception
         # TODO: this field name should be deprecated in 2.0
         return t._isexception ? t.result : nothing
@@ -434,18 +434,18 @@ function errormonitor(t::Task)
             try # try to display the failure atomically
                 errio = IOContext(PipeBuffer(), errs::IO)
                 emphasize(errio, "Unhandled Task ")
-                display_error(errio, catch_stack(t))
+                display_error(errio, current_exceptions(t))
                 write(errs, errio)
             catch
                 try # try to display the secondary error atomically
                     errio = IOContext(PipeBuffer(), errs::IO)
                     print(errio, "\nSYSTEM: caught exception while trying to print a failed Task notice: ")
-                    display_error(errio, catch_stack())
+                    display_error(errio, current_exceptions())
                     write(errs, errio)
                     flush(errs)
                     # and then the actual error, as best we can
                     Core.print(Core.stderr, "while handling: ")
-                    Core.println(Core.stderr, catch_stack(t)[end][1])
+                    Core.println(Core.stderr, current_exceptions(t)[end][1])
                 catch e
                     # give up
                     Core.print(Core.stderr, "\nSYSTEM: caught exception of type ", typeof(e).name.name,

doc/src/base/base.md

@@ -354,7 +354,7 @@ Core.throw
 Base.rethrow
 Base.backtrace
 Base.catch_backtrace
-Base.catch_stack
+Base.current_exceptions
 Base.@assert
 Base.Experimental.register_error_hint
 Base.Experimental.show_error_hints

doc/src/manual/control-flow.md

@@ -817,7 +817,7 @@ The power of the `try/catch` construct lies in the ability to unwind a deeply ne
 immediately to a much higher level in the stack of calling functions. There are situations where
 no error has occurred, but the ability to unwind the stack and pass a value to a higher level
 is desirable. Julia provides the [`rethrow`](@ref), [`backtrace`](@ref), [`catch_backtrace`](@ref)
-and [`Base.catch_stack`](@ref) functions for more advanced error handling.
+and [`current_exceptions`](@ref) functions for more advanced error handling.
 
 ### `finally` Clauses
 

doc/src/manual/stacktraces.md

@@ -185,7 +185,7 @@ ERROR: Whoops!
 [...]
 ```
 
-## Exception stacks and `catch_stack`
+## Exception stacks and [`current_exceptions`](@ref)
 
 !!! compat "Julia 1.1"
     Exception stacks requires at least Julia 1.1.
@@ -195,7 +195,7 @@ identify the root cause of a problem. The julia runtime supports this by pushing
 *exception stack* as it occurs. When the code exits a `catch` normally, any exceptions which were pushed onto the stack
 in the associated `try` are considered to be successfully handled and are removed from the stack.
 
-The stack of current exceptions can be accessed using the experimental [`Base.catch_stack`](@ref) function. For example,
+The stack of current exceptions can be accessed using the [`current_exceptions`](@ref) function. For example,
 
 ```julia-repl
 julia> try
@@ -204,7 +204,7 @@ julia> try
            try
                error("(B) An exception while handling the exception")
            catch
-               for (exc, bt) in Base.catch_stack()
+               for (exc, bt) in current_exceptions()
                    showerror(stdout, exc, bt)
                    println(stdout)
                end
@@ -233,7 +233,7 @@ exiting both catch blocks normally (i.e., without throwing a further exception)
 and are no longer accessible.
 
 The exception stack is stored on the `Task` where the exceptions occurred. When a task fails with uncaught exceptions,
-`catch_stack(task)` may be used to inspect the exception stack for that task.
+`current_exceptions(task)` may be used to inspect the exception stack for that task.
 
 ## Comparison with [`backtrace`](@ref)
 

src/stackwalk.c

@@ -335,7 +335,7 @@ JL_DLLEXPORT jl_value_t *jl_get_backtrace(void)
 // interleaved.
 JL_DLLEXPORT jl_value_t *jl_get_excstack(jl_task_t* task, int include_bt, int max_entries)
 {
-    JL_TYPECHK(catch_stack, task, (jl_value_t*)task);
+    JL_TYPECHK(current_exceptions, task, (jl_value_t*)task);
     jl_ptls_t ptls = jl_get_ptls_states();
     if (task != ptls->current_task && task->_state == JL_TASK_STATE_RUNNABLE) {
         jl_error("Inspecting the exception stack of a task which might "

stdlib/REPL/src/REPL.jl

@@ -29,8 +29,7 @@ import Base:
     display,
     show,
     AnyDict,
-    ==,
-    catch_stack
+    ==
 
 _displaysize(io::IO) = displaysize(io)::Tuple{Int,Int}
 
@@ -160,7 +159,7 @@ function eval_user_input(@nospecialize(ast), backend::REPLBackend)
                 println("SYSTEM ERROR: Failed to report error to REPL frontend")
                 println(err)
             end
-            lasterr = catch_stack()
+            lasterr = current_exceptions()
         end
     end
     Base.sigatomic_end()
@@ -301,7 +300,7 @@ function print_response(errio::IO, response, show_value::Bool, have_color::Bool,
                 println(errio) # an error during printing is likely to leave us mid-line
                 println(errio, "SYSTEM (REPL): showing an error caused an error")
                 try
-                    Base.invokelatest(Base.display_error, errio, catch_stack())
+                    Base.invokelatest(Base.display_error, errio, current_exceptions())
                 catch e
                     # at this point, only print the name of the type as a Symbol to
                     # minimize the possibility of further errors.
@@ -311,7 +310,7 @@ function print_response(errio::IO, response, show_value::Bool, have_color::Bool,
                 end
                 break
             end
-            val = catch_stack()
+            val = current_exceptions()
             iserr = true
         end
     end
@@ -835,7 +834,7 @@ function respond(f, repl, main; pass_empty::Bool = false, suppress_on_semicolon:
                 ast = Base.invokelatest(f, line)
                 response = eval_with_backend(ast, backend(repl))
             catch
-                response = Pair{Any, Bool}(catch_stack(), true)
+                response = Pair{Any, Bool}(current_exceptions(), true)
             end
             hide_output = suppress_on_semicolon && ends_with_semicolon(line)
             print_response(repl, response, !hide_output, hascolor(repl))
@@ -987,7 +986,7 @@ function setup_interface(
             hist_from_file(hp, hist_path)
         catch
             # use REPL.hascolor to avoid using the local variable with the same name
-            print_response(repl, Pair{Any, Bool}(catch_stack(), true), true, REPL.hascolor(repl))
+            print_response(repl, Pair{Any, Bool}(current_exceptions(), true), true, REPL.hascolor(repl))
             println(outstream(repl))
             @info "Disabling history file for this session"
             repl.history_file = false

stdlib/REPL/test/repl.jl

@@ -877,7 +877,7 @@ mutable struct Error19864 <: Exception; end
 function test19864()
     @eval Base.showerror(io::IO, e::Error19864) = print(io, "correct19864")
     buf = IOBuffer()
-    fake_response = (Any[(Error19864(), Ptr{Cvoid}[])], true)
+    fake_response = (Base.ExceptionStack([(exception=Error19864(),backtrace=Ptr{Cvoid}[])]),true)
     REPL.print_response(buf, fake_response, false, false, nothing)
     return String(take!(buf))
 end

stdlib/Serialization/src/Serialization.jl

@@ -462,11 +462,11 @@ function serialize(s::AbstractSerializer, t::Task)
     serialize(s, t.code)
     serialize(s, t.storage)
     serialize(s, t.state)
-    if t._isexception && (stk = Base.catch_stack(t); !isempty(stk))
+    if t._isexception && (stk = Base.current_exceptions(t); !isempty(stk))
         # the exception stack field is hidden inside the task, so if there
         # is any information there make a CapturedException from it instead.
         # TODO: Handle full exception chain, not just the first one.
-        serialize(s, CapturedException(stk[1][1], stk[1][2]))
+        serialize(s, CapturedException(stk[1].exception, stk[1].backtrace))
     else
         serialize(s, t.result)
     end

stdlib/Test/src/Test.jl

@@ -589,7 +589,7 @@ function get_test_result(ex, source)
             $testret
         catch _e
             _e isa InterruptException && rethrow()
-            Threw(_e, Base.catch_stack(), $(QuoteNode(source)))
+            Threw(_e, Base.current_exceptions(), $(QuoteNode(source)))
         end
     end
     Base.remove_linenums!(result)
@@ -1272,7 +1272,7 @@ function testset_beginend(args, tests, source)
             err isa InterruptException && rethrow()
             # something in the test block threw an error. Count that as an
             # error in this test set
-            record(ts, Error(:nontest_error, Expr(:tuple), err, Base.catch_stack(), $(QuoteNode(source))))
+            record(ts, Error(:nontest_error, Expr(:tuple), err, Base.current_exceptions(), $(QuoteNode(source))))
         finally
             copy!(RNG, oldrng)
             pop_testset()
@@ -1346,7 +1346,7 @@ function testset_forloop(args, testloop, source)
             err isa InterruptException && rethrow()
             # Something in the test block threw an error. Count that as an
             # error in this test set
-            record(ts, Error(:nontest_error, Expr(:tuple), err, Base.catch_stack(), $(QuoteNode(source))))
+            record(ts, Error(:nontest_error, Expr(:tuple), err, Base.current_exceptions(), $(QuoteNode(source))))
         end
     end
     quote

stdlib/Test/src/logging.jl

@@ -184,7 +184,7 @@ macro test_logs(exs...)
                                              $(QuoteNode(exs[1:end-1])), logs)
                 end
             catch e
-                testres = Error(:test_error, $orig_expr, e, Base.catch_stack(), $sourceloc)
+                testres = Error(:test_error, $orig_expr, e, Base.current_exceptions(), $sourceloc)
             end
             Test.record(Test.get_testset(), testres)
             value