Skip to content

Commit 8f3ff38

Browse files
authored
Add Usage section to the README
Explains how to use this package in three scenarios: 1. as a library author of a wrapped exception type 2. In client code, as a user of a potentially wrapped exception (e.g. any concurrent code) 3. In tests of potentially wrapped exceptions
1 parent 17c27ff commit 8f3ff38

File tree

1 file changed

+28
-0
lines changed

1 file changed

+28
-0
lines changed

README.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,34 @@ that caused that Task to fail. Another example is the exception types in
2424

2525
- `unwrap_exception_to_root(normal_exception) -> normal_exception`
2626

27+
## Usage
28+
29+
If your library provides a wrapped exception type, you should register it
30+
with this package by simply adding a method to `unwrap_exception`:
31+
```julia
32+
ExceptionUnwrapping.unwrap_exception(e::MyWrappedException) = e.exception
33+
```
34+
35+
In client code, you should use `has_wrapped_exception` and `unwrap_exception_until`
36+
in catch blocks:
37+
```julia
38+
try
39+
...
40+
catch e
41+
if has_wrapped_exception(e, BoundsError)
42+
be = unwrap_exception_until(e, BoundsError)
43+
# ...Use BoundsError...
44+
else
45+
rethrow()
46+
end
47+
end
48+
```
49+
50+
Finally, you can improve robustness in client tests via `@test_throws_wrapped`:
51+
```julia
52+
@test_throws_wrapped AssertionError my_possibly_multithreaded_function()
53+
```
54+
2755
## Motivating Example: Stable Exception Handling
2856
### A Problem: Adding Concurrency to a Library Can Break Users' Exception Handling
2957
As we all start using concurrency more, exception handling can get a bit weird. Julia's

0 commit comments

Comments
 (0)