This is a cookbook for the usage of `safe-exceptions`. You should
start off by
[reading the README](https://github.com/fpco/safe-exceptions#readme),
or at least
[the quickstart section](https://github.com/fpco/safe-exceptions#quickstart).
_Request to readers_: if there are specific workflows that you're
unsure of how to accomplish with this library, please ask so we can
add them here. Issues and pull requests very much welcome!
## User-defined async exceptions
In order to define an async exception, you must leverage the
extensible exception machinery, as demonstrated below. Try running the
program, and then comment out the implementation of `toException` and
`fromException` to see the difference in behavior.
```haskell
#!/usr/bin/env stack
-- stack --resolver lts-6.4 runghc --package safe-exceptions-0.1.0.0
import Control.Concurrent (forkIO, newEmptyMVar, putMVar, takeMVar,
threadDelay)
import Control.Exception.Safe
import Data.Typeable (Typeable, cast)
data MyAsyncException = MyAsyncException
deriving (Show, Typeable)
instance Exception MyAsyncException where
toException = toException . SomeAsyncException
fromException se = do
SomeAsyncException e <- fromException se
cast e
main :: IO ()
main = do
baton <- newEmptyMVar -- give the handler a chance to run
tid <- forkIO $ threadDelay maxBound
`withException`
(\e -> print ("Inside withException", e :: MyAsyncException))
`finally` putMVar baton ()
throwTo tid MyAsyncException
takeMVar baton
putStrLn "Done!"
```
The reason the `Inside withException` message isn't printed without
the implementation of `toException` and `fromException` given above is
that `throwTo` wraps `MyAsyncException` inside a different async
exception type, which foils the exception handler from firing.
*NOTE*: The above code is _not_ recommended concurrency code. If you
have to do something like this, _please use the async package_.