This module provides an orphan MonadCatch instance for Proxy of the form:

instance (MonadCatch m, MonadIO m) => MonadCatch (Proxy a' a b' b m) where

... so you can throw and catch exceptions within pipes using all MonadCatch operations.

This module also provides generalized versions of some MonadCatch operations so that you can also protect against premature termination of connected components. For example, if you protect a readFile computation using bracket from this module:

-- readFile.hs
import Pipes
import qualified Pipes.Prelude as P
import Pipes.Safe
import qualified System.IO as IO
import Prelude hiding (readFile)

readFile :: FilePath -> Producer' String (SafeT IO) ()
readFile file = bracket
    (do h <- IO.openFile file IO.ReadMode
        putStrLn $ "{" ++ file ++ " open}"
        return h )
    (\h -> do
        IO.hClose h
        putStrLn $ "{" ++ file ++ " closed}" )
    P.fromHandle

... then this generalized bracket will guard against both exceptions and premature termination of other pipes:

>>> runSafeT $ runEffect $ readFile "readFile.hs" >-> P.take 4 >-> P.stdoutLn
{readFile.hs open}
-- readFile.hs
import Pipes
import qualified Pipes.Prelude as P
import Pipes.Safe
{readFile.hs closed}

Note that the MonadCatch instance for Proxy provides weaker versions of mask and uninterruptibleMask that do not completely prevent asynchronous exceptions. Instead, they provide a weaker guarantee that asynchronous exceptions will only occur during awaits or yields and nowhere else. For example, if you write:

mask_ $ do
    x <- await
    lift $ print x
    lift $ print x

... then you may receive an asynchronous exception during the await, but you will not receive an asynchronous exception during or in between the two print statements. This weaker guarantee suffices to provide asynchronous exception safety.

These utilities let you supply a finalizer that runs in the Base monad (i.e. the monad directly beneath SafeT). If you don't need to use the full power of the Base monad and you only need to use to use IO, then just wrap the finalizer in liftIO, like this:

myAction `finally` (liftIO myFinalizer)

This will lead to a simple inferred type with a single MonadSafe constraint:

(MonadSafe m) => ...

For examples of this, see the utilities in Pipes.Safe.Prelude.

If you omit the liftIO, the compiler will infer the following constraint instead:

(MonadSafe m, Base m ~ IO) => ...

This means that this function would require IO directly beneath the SafeT monad transformer, which might not be what you want.

Control.Monad.Catch re-exports all functions except for the ones that conflict with the generalized versions provided here (i.e. bracket, finally, etc.).

Control.Exception re-exports Exception and SomeException.