Start the cookbook

Author: snoyberg

Diff for: COOKBOOK.md

@@ -0,0 +1,53 @@
+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_.

Diff for: README.md

@@ -68,11 +68,9 @@ correctly.
     * `bracketOnError`
     * `bracketOnError_`
 
-Hopefully this will be able to get you up-and-running quickly.
-
-_Request to readers_: if there are specific workflows that you're
-unsure of how to accomplish with this library, please ask so we can
-develop a more full-fledged cookbook as a companion to this file.
+Hopefully this will be able to get you up-and-running quickly. You may
+also be interested in
+[browsing through the cookbook](https://github.com/fpco/safe-exceptions/blob/master/COOKBOOK.md).
 
 ## Terminology
 

Diff for: safe-exceptions.cabal

@@ -10,7 +10,7 @@ maintainer:          [email protected]
 copyright:           2016 FP Complete
 category:            Control
 build-type:          Simple
-extra-source-files:  README.md ChangeLog.md
+extra-source-files:  README.md ChangeLog.md COOKBOOK.md
 cabal-version:       >=1.10
 
 library