Skip to content

Commit 5c6d66e

Browse files
authored
Demonstrate rethrow() as best practice in try/catch docs (#59729)
Currently, exception type filtering is missing from the `try` keyword docstrings, and proper demonstration of `rethrow` is missing from the Control Flow manual page. This PR addresses these oversights.
1 parent 232f6dd commit 5c6d66e

File tree

2 files changed

+27
-1
lines changed

2 files changed

+27
-1
lines changed

base/docs/basedocs.jl

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1063,6 +1063,20 @@ end
10631063
The syntax `catch e` (where `e` is any variable) assigns the thrown
10641064
exception object to the given variable within the `catch` block.
10651065
1066+
```julia
1067+
try
1068+
a_dangerous_operation()
1069+
catch e
1070+
if isa(e, EOFError)
1071+
@warn "The operation failed - EOF."
1072+
elseif isa(e, OutOfMemoryError)
1073+
@warn "The operation failed - OOM."
1074+
else
1075+
rethrow() # ensure other exceptions can bubble up the call stack
1076+
end
1077+
end
1078+
```
1079+
10661080
The power of the `try`/`catch` construct lies in the ability to unwind a deeply
10671081
nested computation immediately to a much higher level in the stack of calling functions.
10681082

doc/src/manual/control-flow.md

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -785,6 +785,8 @@ julia> sqrt_second(x) = try
785785
sqrt(complex(x[2], 0))
786786
elseif isa(y, BoundsError)
787787
sqrt(x)
788+
else
789+
rethrow() # ensure other exceptions can bubble up the call stack
788790
end
789791
end
790792
sqrt_second (generic function with 1 method)
@@ -803,8 +805,18 @@ ERROR: DomainError with -9.0:
803805
sqrt was called with a negative real argument but will only return a complex result if called with a complex argument. Try sqrt(Complex(x)).
804806
Stacktrace:
805807
[...]
808+
809+
julia> sqrt_second([1 nothing])
810+
ERROR: MethodError: no method matching sqrt(::Nothing)
811+
The function `sqrt` exists, but no method is defined for this combination of argument types.
812+
[...]
806813
```
807814

815+
Use [`rethrow`](@ref) as above to continue unwinding the stack with the original exception so that
816+
higher-level exception handlers can deal with the exception. When filtering by exception type
817+
as above, it is often important to include `else rethrow()` so that other types of exceptions
818+
are not hidden from the caller.
819+
808820
Note that the symbol following `catch` will always be interpreted as a name for the exception,
809821
so care is needed when writing `try/catch` expressions on a single line. The following code will
810822
*not* work to return the value of `x` in case of an error:
@@ -827,7 +839,7 @@ end
827839
The power of the `try/catch` construct lies in the ability to unwind a deeply nested computation
828840
immediately to a much higher level in the stack of calling functions. There are situations where
829841
no error has occurred, but the ability to unwind the stack and pass a value to a higher level
830-
is desirable. Julia provides the [`rethrow`](@ref), [`backtrace`](@ref), [`catch_backtrace`](@ref)
842+
is desirable. Julia provides the [`backtrace`](@ref), [`catch_backtrace`](@ref)
831843
and [`current_exceptions`](@ref) functions for more advanced error handling.
832844

833845
### `else` Clauses

0 commit comments

Comments
 (0)