diff --git a/NEWS.md b/NEWS.md index 82eabe62f81b2..2833e53cb3f43 100644 --- a/NEWS.md +++ b/NEWS.md @@ -4,7 +4,9 @@ Julia v1.1 Release Notes New language features --------------------- - * An *exception stack* is maintained on each task to make exception handling more robust and enable root cause analysis using `catch_stack` ([#28878]). + * An *exception stack* is maintained on each task to make exception handling + more robust and enable root cause analysis. The stack may be accessed using + the experimental function `Base.catch_stack` ([#28878]). * The experimental macro `Base.@locals` returns a dictionary of current local variable names and values ([#29733]). diff --git a/base/error.jl b/base/error.jl index 488ddc6867386..ff13dbef2ec35 100644 --- a/base/error.jl +++ b/base/error.jl @@ -105,7 +105,8 @@ arbitrary task. This is useful for inspecting tasks which have failed due to uncaught exceptions. !!! compat "Julia 1.1" - This function requires at least 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). """ function catch_stack(task=current_task(); include_bt=true) raw = ccall(:jl_get_excstack, Any, (Any,Cint,Cint), task, include_bt, typemax(Cint)) diff --git a/base/exports.jl b/base/exports.jl index d9c3812b5aebf..3163d4914d3dc 100644 --- a/base/exports.jl +++ b/base/exports.jl @@ -682,7 +682,6 @@ export # errors backtrace, catch_backtrace, - catch_stack, error, rethrow, retry, diff --git a/doc/src/manual/control-flow.md b/doc/src/manual/control-flow.md index 9de3b8206c8a7..6d4cf729d502d 100644 --- a/doc/src/manual/control-flow.md +++ b/doc/src/manual/control-flow.md @@ -794,7 +794,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 [`catch_stack`](@ref) functions for more advanced error handling. +and [`Base.catch_stack`](@ref) functions for more advanced error handling. ### `finally` Clauses diff --git a/doc/src/manual/stacktraces.md b/doc/src/manual/stacktraces.md index 01a3417d33031..8deff082140f1 100644 --- a/doc/src/manual/stacktraces.md +++ b/doc/src/manual/stacktraces.md @@ -187,7 +187,7 @@ ERROR: Whoops! [...] ``` -## Exception stacks and [`catch_stack`](@ref) +## Exception stacks and `catch_stack` !!! compat "Julia 1.1" Exception stacks requires at least Julia 1.1. @@ -197,7 +197,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 [`catch_stack`](@ref) function. For example, +The stack of current exceptions can be accessed using the experimental [`Base.catch_stack`](@ref) function. For example, ```julia-repl julia> try @@ -206,7 +206,7 @@ julia> try try error("(B) An exception while handling the exception") catch - for (exc, bt) in catch_stack() + for (exc, bt) in Base.catch_stack() showerror(stdout, exc, bt) println() end diff --git a/test/exceptions.jl b/test/exceptions.jl index 6bbeebd88e4c5..e1a415a2c6c0d 100644 --- a/test/exceptions.jl +++ b/test/exceptions.jl @@ -1,4 +1,5 @@ using Test +using Base: catch_stack @testset "Basic exception stack handling" begin # Exiting the catch block normally pops the exception