pipes-safe-2.3.1: Safety for the pipes ecosystem

Safe Haskell | Trustworthy
Language | Haskell98

Pipes.Safe

Contents

- SafeT
- MonadSafe
- Utilities
- Re-exports
- Orphan instances

Description

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 `await`s or `yield`s 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.

Synopsis

- data SafeT m r
- runSafeT :: (MonadMask m, MonadIO m) => SafeT m r -> m r
- runSafeP :: (MonadMask m, MonadIO m) => Effect (SafeT m) r -> Effect' m r
- data ReleaseKey
- class (MonadCatch m, MonadMask m, MonadIO m, MonadIO (Base m)) => MonadSafe m where
  - type Base (m :: * -> *) :: * -> *
  - liftBase :: Base m r -> m r
  - register :: Base m () -> m ReleaseKey
  - release :: ReleaseKey -> m ()
- onException :: MonadSafe m => m a -> Base m b -> m a
- tryP :: (MonadSafe m, Exception e) => Proxy a' a b' b m r -> Proxy a' a b' b m (Either e r)
- catchP :: (MonadSafe m, Exception e) => Proxy a' a b' b m r -> (e -> Proxy a' a b' b m r) -> Proxy a' a b' b m r
- finally :: MonadSafe m => m a -> Base m b -> m a
- bracket :: MonadSafe m => Base m a -> (a -> Base m b) -> (a -> m c) -> m c
- bracket_ :: MonadSafe m => Base m a -> Base m b -> m c -> m c
- bracketOnError :: MonadSafe m => Base m a -> (a -> Base m b) -> (a -> m c) -> m c
- class (Typeable e, Show e) => Exception e where
  - toException :: e -> SomeException
  - fromException :: SomeException -> Maybe e
  - displayException :: e -> String
- data SomeException
- catches :: (Foldable f, MonadCatch m) => m a -> f (Handler m a) -> m a
- tryJust :: (MonadCatch m, Exception e) => (e -> Maybe b) -> m a -> m (Either b a)
- handleJust :: (MonadCatch m, Exception e) => (e -> Maybe b) -> (b -> m a) -> m a -> m a
- handleIf :: (MonadCatch m, Exception e) => (e -> Bool) -> (e -> m a) -> m a -> m a
- handleAll :: MonadCatch m => (SomeException -> m a) -> m a -> m a
- handleIOError :: MonadCatch m => (IOError -> m a) -> m a -> m a
- handle :: (MonadCatch m, Exception e) => (e -> m a) -> m a -> m a
- catchJust :: (MonadCatch m, Exception e) => (e -> Maybe b) -> m a -> (b -> m a) -> m a
- catchIf :: (MonadCatch m, Exception e) => (e -> Bool) -> m a -> (e -> m a) -> m a
- catchIOError :: MonadCatch m => m a -> (IOError -> m a) -> m a
- catchAll :: MonadCatch m => m a -> (SomeException -> m a) -> m a
- uninterruptibleMask_ :: MonadMask m => m a -> m a
- mask_ :: MonadMask m => m a -> m a
- class Monad m => MonadThrow (m :: Type -> Type) where
  - throwM :: Exception e => e -> m a
- class MonadThrow m => MonadCatch (m :: Type -> Type) where
  - catch :: Exception e => m a -> (e -> m a) -> m a
- class MonadCatch m => MonadMask (m :: Type -> Type) where
  - mask :: ((forall a. m a -> m a) -> m b) -> m b
  - uninterruptibleMask :: ((forall a. m a -> m a) -> m b) -> m b
  - generalBracket :: m a -> (a -> ExitCase b -> m c) -> (a -> m b) -> m (b, c)
- data ExitCase a
  - = ExitCaseSuccess a
  - | ExitCaseException SomeException
  - | ExitCaseAbort
- data Handler (m :: Type -> Type) a where
  - Handler :: forall (m :: Type -> Type) a e. Exception e => (e -> m a) -> Handler m a
- class (Typeable e, Show e) => Exception e where
  - toException :: e -> SomeException
  - fromException :: SomeException -> Maybe e
  - displayException :: e -> String
- data SomeException where
  - SomeException :: forall e. Exception e => e -> SomeException

# SafeT

data SafeT m r Source #

`SafeT` is a monad transformer that extends the base monad with the ability to `register` and `release` finalizers.

All unreleased finalizers are called at the end of the `SafeT` block, even in the event of exceptions.

Instances

MonadTrans SafeT Source # |
Instance details Defined in Pipes.Safe Methods lift :: Monad m => m a -> SafeT m a Source #
MonadBase b m => MonadBase b (SafeT m) Source # |
Instance details Defined in Pipes.Safe Methods liftBase :: b α -> SafeT m α Source #
MonadBaseControl b m => MonadBaseControl b (SafeT m) Source # |
Instance details Defined in Pipes.Safe Associated Types type StM (SafeT m) a :: Type Source # Methods liftBaseWith :: (RunInBase (SafeT m) b -> b a) -> SafeT m a Source # restoreM :: StM (SafeT m) a -> SafeT m a Source #
MonadWriter w m => MonadWriter w (SafeT m) Source # |
Instance details Defined in Pipes.Safe Methods writer :: (a, w) -> SafeT m a Source # tell :: w -> SafeT m () Source # listen :: SafeT m a -> SafeT m (a, w) Source # pass :: SafeT m (a, w -> w) -> SafeT m a Source #
MonadState s m => MonadState s (SafeT m) Source # |
Instance details Defined in Pipes.Safe Methods get :: SafeT m s Source # put :: s -> SafeT m () Source # state :: (s -> (a, s)) -> SafeT m a Source #
MonadError e m => MonadError e (SafeT m) Source # |
Instance details Defined in Pipes.Safe Methods throwError :: e -> SafeT m a Source # catchError :: SafeT m a -> (e -> SafeT m a) -> SafeT m a Source #
Monad m => Monad (SafeT m) Source # |
Instance details Defined in Pipes.Safe Methods (>>=) :: SafeT m a -> (a -> SafeT m b) -> SafeT m b Source # (>>) :: SafeT m a -> SafeT m b -> SafeT m b Source # return :: a -> SafeT m a Source # fail :: String -> SafeT m a Source #
Functor m => Functor (SafeT m) Source # |
Instance details Defined in Pipes.Safe Methods fmap :: (a -> b) -> SafeT m a -> SafeT m b Source # (<$) :: a -> SafeT m b -> SafeT m a Source #
MonadFix m => MonadFix (SafeT m) Source # |
Instance details Defined in Pipes.Safe Methods mfix :: (a -> SafeT m a) -> SafeT m a Source #
MonadFail m => MonadFail (SafeT m) Source # |
Instance details Defined in Pipes.Safe Methods fail :: String -> SafeT m a Source #
Applicative m => Applicative (SafeT m) Source # |
Instance details Defined in Pipes.Safe Methods pure :: a -> SafeT m a Source # (<*>) :: SafeT m (a -> b) -> SafeT m a -> SafeT m b Source # liftA2 :: (a -> b -> c) -> SafeT m a -> SafeT m b -> SafeT m c Source # (*>) :: SafeT m a -> SafeT m b -> SafeT m b Source # (<*) :: SafeT m a -> SafeT m b -> SafeT m a Source #
MonadIO m => MonadIO (SafeT m) Source # |
Instance details Defined in Pipes.Safe Methods liftIO :: IO a -> SafeT m a Source #
Alternative m => Alternative (SafeT m) Source # |
Instance details Defined in Pipes.Safe Methods empty :: SafeT m a Source # (<|>) :: SafeT m a -> SafeT m a -> SafeT m a Source # some :: SafeT m a -> SafeT m [a] Source # many :: SafeT m a -> SafeT m [a] Source #
MonadPlus m => MonadPlus (SafeT m) Source # |
Instance details Defined in Pipes.Safe Methods mzero :: SafeT m a Source # mplus :: SafeT m a -> SafeT m a -> SafeT m a Source #
MonadThrow m => MonadThrow (SafeT m) Source # |
Instance details Defined in Pipes.Safe Methods throwM :: Exception e => e -> SafeT m a Source #
MonadCatch m => MonadCatch (SafeT m) Source # |
Instance details Defined in Pipes.Safe Methods catch :: Exception e => SafeT m a -> (e -> SafeT m a) -> SafeT m a Source #
MonadMask m => MonadMask (SafeT m) Source # |
Instance details Defined in Pipes.Safe Methods mask :: ((forall a. SafeT m a -> SafeT m a) -> SafeT m b) -> SafeT m b Source # uninterruptibleMask :: ((forall a. SafeT m a -> SafeT m a) -> SafeT m b) -> SafeT m b Source # generalBracket :: SafeT m a -> (a -> ExitCase b -> SafeT m c) -> (a -> SafeT m b) -> SafeT m (b, c) Source #
MonadCont m => MonadCont (SafeT m) Source # |
Instance details Defined in Pipes.Safe Methods callCC :: ((a -> SafeT m b) -> SafeT m a) -> SafeT m a Source #
PrimMonad m => PrimMonad (SafeT m) Source # |
Instance details Defined in Pipes.Safe Associated Types type PrimState (SafeT m) :: Type Source # Methods primitive :: (State# (PrimState (SafeT m)) -> (#State# (PrimState (SafeT m)), a#)) -> SafeT m a Source #
(MonadIO m, MonadCatch m, MonadMask m) => MonadSafe (SafeT m) Source # |
Instance details Defined in Pipes.Safe Associated Types type Base (SafeT m) :: Type -> Type Source # Methods liftBase :: Base (SafeT m) r -> SafeT m r Source # register :: Base (SafeT m) () -> SafeT m ReleaseKey Source # release :: ReleaseKey -> SafeT m () Source #
type PrimState (SafeT m) Source # |
Instance details Defined in Pipes.Safe type PrimState (SafeT m) = PrimState m
type Base (SafeT m) Source # |
Instance details Defined in Pipes.Safe type Base (SafeT m) = m
type StM (SafeT m) a Source # |
Instance details Defined in Pipes.Safe type StM (SafeT m) a = StM m a

runSafeT :: (MonadMask m, MonadIO m) => SafeT m r -> m r Source #

Run the `SafeT` monad transformer, executing all unreleased finalizers at the end of the computation

runSafeP :: (MonadMask m, MonadIO m) => Effect (SafeT m) r -> Effect' m r Source #

Run `SafeT` in the base monad, executing all unreleased finalizers at the end of the computation

Use `runSafeP` to safely flush all unreleased finalizers and ensure prompt finalization without exiting the `Proxy` monad.

# MonadSafe

data ReleaseKey Source #

Token used to `release` a previously `register`ed finalizer

class (MonadCatch m, MonadMask m, MonadIO m, MonadIO (Base m)) => MonadSafe m where Source #

`MonadSafe` lets you `register` and `release` finalizers that execute in a `Base` monad

Associated Types

type Base (m :: * -> *) :: * -> * Source #

The monad used to run resource management actions, corresponding to the monad directly beneath `SafeT`

Methods

liftBase :: Base m r -> m r Source #

Lift an action from the `Base` monad

register :: Base m () -> m ReleaseKey Source #

`register` a finalizer, ensuring that the finalizer gets called if the finalizer is not `release`d before the end of the surrounding `SafeT` block.

release :: ReleaseKey -> m () Source #

`release` a registered finalizer

You can safely call `release` more than once on the same `ReleaseKey`. Every `release` after the first one does nothing.

Instances

MonadSafe m => MonadSafe (CatchT m) Source # |
Instance details Defined in Pipes.Safe Associated Types type Base (CatchT m) :: Type -> Type Source # Methods liftBase :: Base (CatchT m) r -> CatchT m r Source # register :: Base (CatchT m) () -> CatchT m ReleaseKey Source # release :: ReleaseKey -> CatchT m () Source #
(MonadIO m, MonadCatch m, MonadMask m) => MonadSafe (SafeT m) Source # |
Instance details Defined in Pipes.Safe Associated Types type Base (SafeT m) :: Type -> Type Source # Methods liftBase :: Base (SafeT m) r -> SafeT m r Source # register :: Base (SafeT m) () -> SafeT m ReleaseKey Source # release :: ReleaseKey -> SafeT m () Source #
(MonadSafe m, Monoid w) => MonadSafe (WriterT w m) Source # |
Instance details Defined in Pipes.Safe Associated Types type Base (WriterT w m) :: Type -> Type Source # Methods liftBase :: Base (WriterT w m) r -> WriterT w m r Source # register :: Base (WriterT w m) () -> WriterT w m ReleaseKey Source # release :: ReleaseKey -> WriterT w m () Source #
MonadSafe m => MonadSafe (StateT s m) Source # |
Instance details Defined in Pipes.Safe Associated Types type Base (StateT s m) :: Type -> Type Source # Methods liftBase :: Base (StateT s m) r -> StateT s m r Source # register :: Base (StateT s m) () -> StateT s m ReleaseKey Source # release :: ReleaseKey -> StateT s m () Source #
MonadSafe m => MonadSafe (ReaderT i m) Source # |
Instance details Defined in Pipes.Safe Associated Types type Base (ReaderT i m) :: Type -> Type Source # Methods liftBase :: Base (ReaderT i m) r -> ReaderT i m r Source # register :: Base (ReaderT i m) () -> ReaderT i m ReleaseKey Source # release :: ReleaseKey -> ReaderT i m () Source #
MonadSafe m => MonadSafe (IdentityT m) Source # |
Instance details Defined in Pipes.Safe Associated Types type Base (IdentityT m) :: Type -> Type Source # Methods liftBase :: Base (IdentityT m) r -> IdentityT m r Source # register :: Base (IdentityT m) () -> IdentityT m ReleaseKey Source # release :: ReleaseKey -> IdentityT m () Source #
MonadSafe m => MonadSafe (StateT s m) Source # |
Instance details Defined in Pipes.Safe Associated Types type Base (StateT s m) :: Type -> Type Source # Methods liftBase :: Base (StateT s m) r -> StateT s m r Source # register :: Base (StateT s m) () -> StateT s m ReleaseKey Source # release :: ReleaseKey -> StateT s m () Source #
(MonadSafe m, Monoid w) => MonadSafe (WriterT w m) Source # |
Instance details Defined in Pipes.Safe Associated Types type Base (WriterT w m) :: Type -> Type Source # Methods liftBase :: Base (WriterT w m) r -> WriterT w m r Source # register :: Base (WriterT w m) () -> WriterT w m ReleaseKey Source # release :: ReleaseKey -> WriterT w m () Source #
(MonadSafe m, Monoid w) => MonadSafe (RWST i w s m) Source # |
Instance details Defined in Pipes.Safe Associated Types type Base (RWST i w s m) :: Type -> Type Source # Methods liftBase :: Base (RWST i w s m) r -> RWST i w s m r Source # register :: Base (RWST i w s m) () -> RWST i w s m ReleaseKey Source # release :: ReleaseKey -> RWST i w s m () Source #
(MonadSafe m, Monoid w) => MonadSafe (RWST i w s m) Source # |
Instance details Defined in Pipes.Safe Associated Types type Base (RWST i w s m) :: Type -> Type Source # Methods liftBase :: Base (RWST i w s m) r -> RWST i w s m r Source # register :: Base (RWST i w s m) () -> RWST i w s m ReleaseKey Source # release :: ReleaseKey -> RWST i w s m () Source #
MonadSafe m => MonadSafe (Proxy a' a b' b m) Source # |
Instance details Defined in Pipes.Safe Associated Types type Base (Proxy a' a b' b m) :: Type -> Type Source # Methods liftBase :: Base (Proxy a' a b' b m) r -> Proxy a' a b' b m r Source # register :: Base (Proxy a' a b' b m) () -> Proxy a' a b' b m ReleaseKey Source # release :: ReleaseKey -> Proxy a' a b' b m () Source #

# Utilities

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.

onException :: MonadSafe m => m a -> Base m b -> m a Source #

Analogous to `onException` from `Control.Monad.Catch`, except this also protects against premature termination

`(`onException` io)` is a monad morphism.

tryP :: (MonadSafe m, Exception e) => Proxy a' a b' b m r -> Proxy a' a b' b m (Either e r) Source #

Transform a `Proxy` into one that catches any exceptions caused by its effects, and returns the resulting exception.

catchP :: (MonadSafe m, Exception e) => Proxy a' a b' b m r -> (e -> Proxy a' a b' b m r) -> Proxy a' a b' b m r Source #

Allows direct handling of exceptions raised by the effects in a `Proxy`.

finally :: MonadSafe m => m a -> Base m b -> m a Source #

Analogous to `finally` from `Control.Monad.Catch`, except this also protects against premature termination

bracket :: MonadSafe m => Base m a -> (a -> Base m b) -> (a -> m c) -> m c Source #

Analogous to `bracket` from `Control.Monad.Catch`, except this also protects against premature termination

bracket_ :: MonadSafe m => Base m a -> Base m b -> m c -> m c Source #

Analogous to `bracket_` from `Control.Monad.Catch`, except this also protects against premature termination

bracketOnError :: MonadSafe m => Base m a -> (a -> Base m b) -> (a -> m c) -> m c Source #

Analogous to `bracketOnError` from `Control.Monad.Catch`, except this also protects against premature termination

# Re-exports

`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`.

class (Typeable e, Show e) => Exception e where Source #

Any type that you wish to throw or catch as an exception must be an instance of the `Exception` class. The simplest case is a new exception type directly below the root:

    data MyException = ThisException | ThatException
        deriving Show

    instance Exception MyException

The default method definitions in the `Exception` class do what we need in this case. You can now throw and catch `ThisException` and `ThatException` as exceptions:

    *Main> throw ThisException `catch` \e -> putStrLn ("Caught " ++ show (e :: MyException))
    Caught ThisException

In more complicated examples, you may wish to define a whole hierarchy of exceptions:

    ---------------------------------------------------------------------
    -- Make the root exception type for all the exceptions in a compiler

    data SomeCompilerException = forall e . Exception e => SomeCompilerException e

    instance Show SomeCompilerException where
        show (SomeCompilerException e) = show e

    instance Exception SomeCompilerException

    compilerExceptionToException :: Exception e => e -> SomeException
    compilerExceptionToException = toException . SomeCompilerException

    compilerExceptionFromException :: Exception e => SomeException -> Maybe e
    compilerExceptionFromException x = do
        SomeCompilerException a <- fromException x
        cast a

    ---------------------------------------------------------------------
    -- Make a subhierarchy for exceptions in the frontend of the compiler

    data SomeFrontendException = forall e . Exception e => SomeFrontendException e

    instance Show SomeFrontendException where
        show (SomeFrontendException e) = show e

    instance Exception SomeFrontendException where
        toException = compilerExceptionToException
        fromException = compilerExceptionFromException

    frontendExceptionToException :: Exception e => e -> SomeException
    frontendExceptionToException = toException . SomeFrontendException

    frontendExceptionFromException :: Exception e => SomeException -> Maybe e
    frontendExceptionFromException x = do
        SomeFrontendException a <- fromException x
        cast a

    ---------------------------------------------------------------------
    -- Make an exception type for a particular frontend compiler exception

    data MismatchedParentheses = MismatchedParentheses
        deriving Show

    instance Exception MismatchedParentheses where
        toException   = frontendExceptionToException
        fromException = frontendExceptionFromException

We can now catch a `MismatchedParentheses` exception as `MismatchedParentheses`, `SomeFrontendException` or `SomeCompilerException`, but not other types, e.g. `IOException`:

    *Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: MismatchedParentheses))
    Caught MismatchedParentheses
    *Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: SomeFrontendException))
    Caught MismatchedParentheses
    *Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: SomeCompilerException))
    Caught MismatchedParentheses
    *Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: IOException))
    *** Exception: MismatchedParentheses

Minimal complete definition

Nothing

Methods

toException :: e -> SomeException Source #

fromException :: SomeException -> Maybe e Source #

displayException :: e -> String Source #

Render this exception value in a human-friendly manner.

Default implementation: ``show``.

Since: base-4.8.0.0

Instances

Exception Void | Since: base-4.8.0.0
Instance details Defined in Data.Void Methods toException :: Void -> SomeException Source # fromException :: SomeException -> Maybe Void Source # displayException :: Void -> String Source #
Exception BlockedIndefinitelyOnMVar | Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: BlockedIndefinitelyOnMVar -> SomeException Source # fromException :: SomeException -> Maybe BlockedIndefinitelyOnMVar Source # displayException :: BlockedIndefinitelyOnMVar -> String Source #
Exception BlockedIndefinitelyOnSTM | Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: BlockedIndefinitelyOnSTM -> SomeException Source # fromException :: SomeException -> Maybe BlockedIndefinitelyOnSTM Source # displayException :: BlockedIndefinitelyOnSTM -> String Source #
Exception Deadlock | Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: Deadlock -> SomeException Source # fromException :: SomeException -> Maybe Deadlock Source # displayException :: Deadlock -> String Source #
Exception AllocationLimitExceeded | Since: base-4.8.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: AllocationLimitExceeded -> SomeException Source # fromException :: SomeException -> Maybe AllocationLimitExceeded Source # displayException :: AllocationLimitExceeded -> String Source #
Exception CompactionFailed | Since: base-4.10.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: CompactionFailed -> SomeException Source # fromException :: SomeException -> Maybe CompactionFailed Source # displayException :: CompactionFailed -> String Source #
Exception AssertionFailed | Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: AssertionFailed -> SomeException Source # fromException :: SomeException -> Maybe AssertionFailed Source # displayException :: AssertionFailed -> String Source #
Exception SomeAsyncException | Since: base-4.7.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: SomeAsyncException -> SomeException Source # fromException :: SomeException -> Maybe SomeAsyncException Source # displayException :: SomeAsyncException -> String Source #
Exception AsyncException | Since: base-4.7.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: AsyncException -> SomeException Source # fromException :: SomeException -> Maybe AsyncException Source # displayException :: AsyncException -> String Source #
Exception ArrayException | Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: ArrayException -> SomeException Source # fromException :: SomeException -> Maybe ArrayException Source # displayException :: ArrayException -> String Source #
Exception FixIOException | Since: base-4.11.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: FixIOException -> SomeException Source # fromException :: SomeException -> Maybe FixIOException Source # displayException :: FixIOException -> String Source #
Exception ExitCode | Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: ExitCode -> SomeException Source # fromException :: SomeException -> Maybe ExitCode Source # displayException :: ExitCode -> String Source #
Exception IOException | Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: IOException -> SomeException Source # fromException :: SomeException -> Maybe IOException Source # displayException :: IOException -> String Source #
Exception ArithException | Since: base-4.0.0.0
Instance details Defined in GHC.Exception.Type Methods toException :: ArithException -> SomeException Source # fromException :: SomeException -> Maybe ArithException Source # displayException :: ArithException -> String Source #
Exception SomeException | Since: base-3.0
Instance details Defined in GHC.Exception.Type Methods toException :: SomeException -> SomeException Source # fromException :: SomeException -> Maybe SomeException Source # displayException :: SomeException -> String Source #

data SomeException Source #

The `SomeException` type is the root of the exception type hierarchy. When an exception of type `e` is thrown, behind the scenes it is encapsulated in a `SomeException`.

Instances

Show SomeException | Since: base-3.0
Instance details Defined in GHC.Exception.Type Methods showsPrec :: Int -> SomeException -> ShowS Source # show :: SomeException -> String Source # showList :: [SomeException] -> ShowS Source #
Exception SomeException | Since: base-3.0
Instance details Defined in GHC.Exception.Type Methods toException :: SomeException -> SomeException Source # fromException :: SomeException -> Maybe SomeException Source # displayException :: SomeException -> String Source #

catches :: (Foldable f, MonadCatch m) => m a -> f (Handler m a) -> m a Source #

Catches different sorts of exceptions. See Control.Exception's `catches`

tryJust :: (MonadCatch m, Exception e) => (e -> Maybe b) -> m a -> m (Either b a) Source #

A variant of `try` that takes an exception predicate to select which exceptions are caught. See Control.Exception's `tryJust`

handleJust :: (MonadCatch m, Exception e) => (e -> Maybe b) -> (b -> m a) -> m a -> m a Source #

Flipped `catchJust`. See Control.Exception's `handleJust`.

handleIf :: (MonadCatch m, Exception e) => (e -> Bool) -> (e -> m a) -> m a -> m a Source #

Flipped `catchIf`

handleAll :: MonadCatch m => (SomeException -> m a) -> m a -> m a Source #

Flipped `catchAll`

handleIOError :: MonadCatch m => (IOError -> m a) -> m a -> m a Source #

Flipped `catchIOError`

handle :: (MonadCatch m, Exception e) => (e -> m a) -> m a -> m a Source #

Flipped `catch`. See Control.Exception's `handle`.

catchJust :: (MonadCatch m, Exception e) => (e -> Maybe b) -> m a -> (b -> m a) -> m a Source #

A more generalized way of determining which exceptions to catch at run time.

catchIf :: (MonadCatch m, Exception e) => (e -> Bool) -> m a -> (e -> m a) -> m a Source #

Catch exceptions only if they pass some predicate. Often useful with the predicates for testing `IOError` values in System.IO.Error.

catchIOError :: MonadCatch m => m a -> (IOError -> m a) -> m a Source #

Catch all `IOError` (eqv. `IOException`) exceptions. Still somewhat too general, but better than using `catchAll`. See `catchIf` for an easy way of catching specific `IOError`s based on the predicates in System.IO.Error.

catchAll :: MonadCatch m => m a -> (SomeException -> m a) -> m a Source #

Catches all exceptions, and somewhat defeats the purpose of the extensible exception system. Use sparingly.

NOTE This catches all exceptions, but if the monad supports other ways of aborting the computation, those other kinds of errors will not be caught.

uninterruptibleMask_ :: MonadMask m => m a -> m a Source #

Like `uninterruptibleMask`, but does not pass a `restore` action to the argument.

mask_ :: MonadMask m => m a -> m a Source #

Like `mask`, but does not pass a `restore` action to the argument.

class Monad m => MonadThrow (m :: Type -> Type) where Source #

A class for monads in which exceptions may be thrown.

Instances should obey the following law:

    throwM e >> x = throwM e

In other words, throwing an exception short-circuits the rest of the monadic computation.

Methods

throwM :: Exception e => e -> m a Source #

Throw an exception. Note that this throws when this action is run in the monad `m`, not when it is applied. It is a generalization of Control.Exception's `throwIO`.

Should satisfy the law:

    throwM e >> f = throwM e

Instances

MonadThrow [] |
Instance details Defined in Control.Monad.Catch Methods throwM :: Exception e => e -> [a] Source #
MonadThrow Maybe |
Instance details Defined in Control.Monad.Catch Methods throwM :: Exception e => e -> Maybe a Source #
MonadThrow IO |
Instance details Defined in Control.Monad.Catch Methods throwM :: Exception e => e -> IO a Source #
MonadThrow Q |
Instance details Defined in Control.Monad.Catch Methods throwM :: Exception e => e -> Q a Source #
MonadThrow STM |
Instance details Defined in Control.Monad.Catch Methods throwM :: Exception e => e -> STM a Source #
e ~ SomeException => MonadThrow (Either e) |
Instance details Defined in Control.Monad.Catch Methods throwM :: Exception e0 => e0 -> Either e a Source #
MonadThrow m => MonadThrow (MaybeT m) | Throws exceptions into the base monad.
Instance details Defined in Control.Monad.Catch Methods throwM :: Exception e => e -> MaybeT m a Source #
Monad m => MonadThrow (CatchT m) |
Instance details Defined in Control.Monad.Catch.Pure Methods throwM :: Exception e => e -> CatchT m a Source #
MonadThrow m => MonadThrow (ListT m) |
Instance details Defined in Control.Monad.Catch Methods throwM :: Exception e => e -> ListT m a Source #
MonadThrow m => MonadThrow (ListT m) |
Instance details Defined in Pipes Methods throwM :: Exception e => e -> ListT m a Source #
MonadThrow m => MonadThrow (SafeT m) Source # |
Instance details Defined in Pipes.Safe Methods throwM :: Exception e => e -> SafeT m a Source #
MonadThrow m => MonadThrow (ExceptT e m) | Throws exceptions into the base monad.
Instance details Defined in Control.Monad.Catch Methods throwM :: Exception e0 => e0 -> ExceptT e m a Source #
(MonadThrow m, Monoid w) => MonadThrow (WriterT w m) |
Instance details Defined in Control.Monad.Catch Methods throwM :: Exception e => e -> WriterT w m a Source #
MonadThrow m => MonadThrow (StateT s m) |
Instance details Defined in Control.Monad.Catch Methods throwM :: Exception e => e -> StateT s m a Source #
MonadThrow m => MonadThrow (ReaderT r m) |
Instance details Defined in Control.Monad.Catch Methods throwM :: Exception e => e -> ReaderT r m a Source #
(Error e, MonadThrow m) => MonadThrow (ErrorT e m) | Throws exceptions into the base monad.
Instance details Defined in Control.Monad.Catch Methods throwM :: Exception e0 => e0 -> ErrorT e m a Source #
MonadThrow m => MonadThrow (IdentityT m) |
Instance details Defined in Control.Monad.Catch Methods throwM :: Exception e => e -> IdentityT m a Source #
MonadThrow m => MonadThrow (StateT s m) |
Instance details Defined in Control.Monad.Catch Methods throwM :: Exception e => e -> StateT s m a Source #
(MonadThrow m, Monoid w) => MonadThrow (WriterT w m) |
Instance details Defined in Control.Monad.Catch Methods throwM :: Exception e => e -> WriterT w m a Source #
MonadThrow m => MonadThrow (ContT r m) |
Instance details Defined in Control.Monad.Catch Methods throwM :: Exception e => e -> ContT r m a Source #
(MonadThrow m, Monoid w) => MonadThrow (RWST r w s m) |
Instance details Defined in Control.Monad.Catch Methods throwM :: Exception e => e -> RWST r w s m a Source #
(MonadThrow m, Monoid w) => MonadThrow (RWST r w s m) |
Instance details Defined in Control.Monad.Catch Methods throwM :: Exception e => e -> RWST r w s m a Source #
MonadThrow m => MonadThrow (Proxy a' a b' b m) |
Instance details Defined in Pipes.Internal Methods throwM :: Exception e => e -> Proxy a' a b' b m a0 Source #

class MonadThrow m => MonadCatch (m :: Type -> Type) where Source #

A class for monads which allow exceptions to be caught, in particular exceptions which were thrown by `throwM`.

Instances should obey the following law:

    catch (throwM e) f = f e

Note that the ability to catch an exception does not guarantee that we can deal with all possible exit points from a computation. Some monads, such as continuation-based stacks, allow for more than just a success/failure strategy, and therefore `catch` cannot be used by those monads to properly implement a function such as `finally`. For more information, see `MonadMask`.

Methods

catch :: Exception e => m a -> (e -> m a) -> m a Source #

Provide a handler for exceptions thrown during execution of the first action. Note that type of the type of the argument to the handler will constrain which exceptions are caught. See Control.Exception's `catch`.

Instances

MonadCatch IO |
Instance details Defined in Control.Monad.Catch Methods catch :: Exception e => IO a -> (e -> IO a) -> IO a Source #
MonadCatch STM |
Instance details Defined in Control.Monad.Catch Methods catch :: Exception e => STM a -> (e -> STM a) -> STM a Source #
e ~ SomeException => MonadCatch (Either e) | Since: exceptions-0.8.3
Instance details Defined in Control.Monad.Catch Methods catch :: Exception e0 => Either e a -> (e0 -> Either e a) -> Either e a Source #
MonadCatch m => MonadCatch (MaybeT m) | Catches exceptions from the base monad.
Instance details Defined in Control.Monad.Catch Methods catch :: Exception e => MaybeT m a -> (e -> MaybeT m a) -> MaybeT m a Source #
Monad m => MonadCatch (CatchT m) |
Instance details Defined in Control.Monad.Catch.Pure Methods catch :: Exception e => CatchT m a -> (e -> CatchT m a) -> CatchT m a Source #
MonadCatch m => MonadCatch (ListT m) |
Instance details Defined in Control.Monad.Catch Methods catch :: Exception e => ListT m a -> (e -> ListT m a) -> ListT m a Source #
MonadCatch m => MonadCatch (ListT m) |
Instance details Defined in Pipes Methods catch :: Exception e => ListT m a -> (e -> ListT m a) -> ListT m a Source #
MonadCatch m => MonadCatch (SafeT m) Source # |
Instance details Defined in Pipes.Safe Methods catch :: Exception e => SafeT m a -> (e -> SafeT m a) -> SafeT m a Source #
MonadCatch m => MonadCatch (ExceptT e m) | Catches exceptions from the base monad.
Instance details Defined in Control.Monad.Catch Methods catch :: Exception e0 => ExceptT e m a -> (e0 -> ExceptT e m a) -> ExceptT e m a Source #
(MonadCatch m, Monoid w) => MonadCatch (WriterT w m) |
Instance details Defined in Control.Monad.Catch Methods catch :: Exception e => WriterT w m a -> (e -> WriterT w m a) -> WriterT w m a Source #
MonadCatch m => MonadCatch (StateT s m) |
Instance details Defined in Control.Monad.Catch Methods catch :: Exception e => StateT s m a -> (e -> StateT s m a) -> StateT s m a Source #
MonadCatch m => MonadCatch (ReaderT r m) |
Instance details Defined in Control.Monad.Catch Methods catch :: Exception e => ReaderT r m a -> (e -> ReaderT r m a) -> ReaderT r m a Source #
(Error e, MonadCatch m) => MonadCatch (ErrorT e m) | Catches exceptions from the base monad.
Instance details Defined in Control.Monad.Catch Methods catch :: Exception e0 => ErrorT e m a -> (e0 -> ErrorT e m a) -> ErrorT e m a Source #
MonadCatch m => MonadCatch (IdentityT m) |
Instance details Defined in Control.Monad.Catch Methods catch :: Exception e => IdentityT m a -> (e -> IdentityT m a) -> IdentityT m a Source #
MonadCatch m => MonadCatch (StateT s m) |
Instance details Defined in Control.Monad.Catch Methods catch :: Exception e => StateT s m a -> (e -> StateT s m a) -> StateT s m a Source #
(MonadCatch m, Monoid w) => MonadCatch (WriterT w m) |
Instance details Defined in Control.Monad.Catch Methods catch :: Exception e => WriterT w m a -> (e -> WriterT w m a) -> WriterT w m a Source #
(MonadCatch m, Monoid w) => MonadCatch (RWST r w s m) |
Instance details Defined in Control.Monad.Catch Methods catch :: Exception e => RWST r w s m a -> (e -> RWST r w s m a) -> RWST r w s m a Source #
(MonadCatch m, Monoid w) => MonadCatch (RWST r w s m) |
Instance details Defined in Control.Monad.Catch Methods catch :: Exception e => RWST r w s m a -> (e -> RWST r w s m a) -> RWST r w s m a Source #
MonadCatch m => MonadCatch (Proxy a' a b' b m) |
Instance details Defined in Pipes.Internal Methods catch :: Exception e => Proxy a' a b' b m a0 -> (e -> Proxy a' a b' b m a0) -> Proxy a' a b' b m a0 Source #

class MonadCatch m => MonadMask (m :: Type -> Type) where Source #

A class for monads which provide for the ability to account for all possible exit points from a computation, and to mask asynchronous exceptions. Continuation-based monads are invalid instances of this class.

Instances should ensure that, in the following code:

    fg = f `finally` g

The action `g` is called regardless of what occurs within `f`, including async exceptions. Some monads allow `f` to abort the computation via other effects than throwing an exception. For simplicity, we will consider aborting and throwing an exception to be two forms of "throwing an error".

If `f` and `g` both throw an error, the error thrown by `fg` depends on which errors we're talking about. In a monad transformer stack, the deeper layers override the effects of the inner layers; for example, `ExceptT e1 (Except e2) a` represents a value of type `Either e2 (Either e1 a)`, so throwing both an `e1` and an `e2` will result in `Left e2`. If `f` and `g` both throw an error from the same layer, instances should ensure that the error from `g` wins.

Effects other than throwing an error are also overriden by the deeper layers. For example, `StateT s Maybe a` represents a value of type `s -> Maybe (a, s)`, so if an error thrown from `f` causes this function to return `Nothing`, any changes to the state which `f` also performed will be erased. As a result, `g` will see the state as it was before `f`. Once `g` completes, `f`'s error will be rethrown, so `g`' state changes will be erased as well. This is the normal interaction between effects in a monad transformer stack.

By contrast, lifted-base's version of `finally` always discards all of `g`'s non-IO effects, and `g` never sees any of `f`'s non-IO effects, regardless of the layer ordering and regardless of whether `f` throws an error. This is not the result of interacting effects, but a consequence of `MonadBaseControl`'s approach.

Methods

mask :: ((forall a. m a -> m a) -> m b) -> m b Source #

Runs an action with asynchronous exceptions disabled. The action is provided a method for restoring the async. environment to what it was at the `mask` call. See Control.Exception's `mask`.

uninterruptibleMask :: ((forall a. m a -> m a) -> m b) -> m b Source #

Like `mask`, but the masked computation is not interruptible (see Control.Exception's `uninterruptibleMask`. WARNING: Only use if you need to mask exceptions around an interruptible operation AND you can guarantee the interruptible operation will only block for a short period of time. Otherwise you render the program/thread unresponsive and/or unkillable.

generalBracket Source #

Arguments

:: m a | acquire some resource
-> (a -> ExitCase b -> m c) | release the resource, observing the outcome of the inner action
-> (a -> m b) | inner action to perform with the resource
-> m (b, c) |

A generalized version of `bracket` which uses `ExitCase` to distinguish the different exit cases, and returns the values of both the `use` and `release` actions. In practice, this extra information is rarely needed, so it is often more convenient to use one of the simpler functions which are defined in terms of this one, such as `bracket`, `finally`, `onError`, and `bracketOnError`.

This function exists because in order to thread their effects through the execution of `bracket`, monad transformers need values to be threaded from `use` to `release` and from `release` to the output value.

NOTE This method was added in version 0.9.0 of this library. Previously, implementation of functions like `bracket` and `finally` in this module were based on the `mask` and `uninterruptibleMask` functions only, disallowing some classes of tranformers from having `MonadMask` instances (notably multi-exit-point transformers like `ExceptT`). If you are a library author, you'll now need to provide an implementation for this method. The `StateT` implementation demonstrates most of the subtleties:

    generalBracket acquire release use = StateT $ s0 -> do
      ((b, _s2), (c, s3)) <- generalBracket
        (runStateT acquire s0)
        ((resource, s1) exitCase -> case exitCase of
          ExitCaseSuccess (b, s2) -> runStateT (release resource (ExitCaseSuccess b)) s2

          -- In the two other cases, the base monad overrides use's state
          -- changes and the state reverts to s1.
          ExitCaseException e     -> runStateT (release resource (ExitCaseException e)) s1
          ExitCaseAbort           -> runStateT (release resource ExitCaseAbort) s1
        )
        ((resource, s1) -> runStateT (use resource) s1)
      return ((b, c), s3)

The `StateT s m` implementation of `generalBracket` delegates to the `m` implementation of `generalBracket`. The `acquire`, `use`, and `release` arguments given to `StateT`'s implementation produce actions of type `StateT s m a`, `StateT s m b`, and `StateT s m c`. In order to run those actions in the base monad, we need to call `runStateT`, from which we obtain actions of type `m (a, s)`, `m (b, s)`, and `m (c, s)`. Since each action produces the next state, it is important to feed the state produced by the previous action to the next action.

In the `ExitCaseSuccess` case, the state starts at `s0`, flows through `acquire` to become `s1`, flows through `use` to become `s2`, and finally flows through `release` to become `s3`. In the other two cases, `release` does not receive the value `s2`, so its action cannot see the state changes performed by `use`. This is fine, because in those two cases, an error was thrown in the base monad, so as per the usual interaction between effects in a monad transformer stack, those state changes get reverted. So we start from `s1` instead.

Finally, the `m` implementation of `generalBracket` returns the pairs `(b, s)` and `(c, s)`. For monad transformers other than `StateT`, this will be some other type representing the effects and values performed and returned by the `use` and `release` actions. The effect part of the `use` result, in this case `_s2`, usually needs to be discarded, since those effects have already been incorporated in the `release` action.

The only effect which is intentionally not incorporated in the `release` action is the effect of throwing an error. In that case, the error must be re-thrown. One subtlety which is easy to miss is that in the case in which `use` and `release` both throw an error, the error from `release` should take priority. Here is an implementation for `ExceptT` which demonstrates how to do this.

    generalBracket acquire release use = ExceptT $ do
      (eb, ec) <- generalBracket
        (runExceptT acquire)
        (eresource exitCase -> case eresource of
          Left e -> return (Left e) -- nothing to release, acquire didn't succeed
          Right resource -> case exitCase of
            ExitCaseSuccess (Right b) -> runExceptT (release resource (ExitCaseSuccess b))
            ExitCaseException e       -> runExceptT (release resource (ExitCaseException e))
            _                         -> runExceptT (release resource ExitCaseAbort))
        (either (return . Left) (runExceptT . use))
      return $ do
        -- The order in which we perform those two Either effects determines
        -- which error will win if they are both Lefts. We want the error from
        -- release to win.
        c <- ec
        b <- eb
        return (b, c)

Since: exceptions-0.9.0

Instances

MonadMask IO |
Instance details Defined in Control.Monad.Catch Methods mask :: ((forall a. IO a -> IO a) -> IO b) -> IO b Source # uninterruptibleMask :: ((forall a. IO a -> IO a) -> IO b) -> IO b Source # generalBracket :: IO a -> (a -> ExitCase b -> IO c) -> (a -> IO b) -> IO (b, c) Source #
e ~ SomeException => MonadMask (Either e) | Since: exceptions-0.8.3
Instance details Defined in Control.Monad.Catch Methods mask :: ((forall a. Either e a -> Either e a) -> Either e b) -> Either e b Source # uninterruptibleMask :: ((forall a. Either e a -> Either e a) -> Either e b) -> Either e b Source # generalBracket :: Either e a -> (a -> ExitCase b -> Either e c) -> (a -> Either e b) -> Either e (b, c) Source #
MonadMask m => MonadMask (MaybeT m) | Since: exceptions-0.10.0
Instance details Defined in Control.Monad.Catch Methods mask :: ((forall a. MaybeT m a -> MaybeT m a) -> MaybeT m b) -> MaybeT m b Source # uninterruptibleMask :: ((forall a. MaybeT m a -> MaybeT m a) -> MaybeT m b) -> MaybeT m b Source # generalBracket :: MaybeT m a -> (a -> ExitCase b -> MaybeT m c) -> (a -> MaybeT m b) -> MaybeT m (b, c) Source #
Monad m => MonadMask (CatchT m) | Note: This instance is only valid if the underlying monad has a single exit point! For example, `IO` or `Either` would be invalid base monads, but `Reader` or `State` would be acceptable.
Instance details Defined in Control.Monad.Catch.Pure Methods mask :: ((forall a. CatchT m a -> CatchT m a) -> CatchT m b) -> CatchT m b Source # uninterruptibleMask :: ((forall a. CatchT m a -> CatchT m a) -> CatchT m b) -> CatchT m b Source # generalBracket :: CatchT m a -> (a -> ExitCase b -> CatchT m c) -> (a -> CatchT m b) -> CatchT m (b, c) Source #
MonadMask m => MonadMask (SafeT m) Source # |
Instance details Defined in Pipes.Safe Methods mask :: ((forall a. SafeT m a -> SafeT m a) -> SafeT m b) -> SafeT m b Source # uninterruptibleMask :: ((forall a. SafeT m a -> SafeT m a) -> SafeT m b) -> SafeT m b Source # generalBracket :: SafeT m a -> (a -> ExitCase b -> SafeT m c) -> (a -> SafeT m b) -> SafeT m (b, c) Source #
MonadMask m => MonadMask (ExceptT e m) | Since: exceptions-0.9.0
Instance details Defined in Control.Monad.Catch Methods mask :: ((forall a. ExceptT e m a -> ExceptT e m a) -> ExceptT e m b) -> ExceptT e m b Source # uninterruptibleMask :: ((forall a. ExceptT e m a -> ExceptT e m a) -> ExceptT e m b) -> ExceptT e m b Source # generalBracket :: ExceptT e m a -> (a -> ExitCase b -> ExceptT e m c) -> (a -> ExceptT e m b) -> ExceptT e m (b, c) Source #
(MonadMask m, Monoid w) => MonadMask (WriterT w m) |
Instance details Defined in Control.Monad.Catch Methods mask :: ((forall a. WriterT w m a -> WriterT w m a) -> WriterT w m b) -> WriterT w m b Source # uninterruptibleMask :: ((forall a. WriterT w m a -> WriterT w m a) -> WriterT w m b) -> WriterT w m b Source # generalBracket :: WriterT w m a -> (a -> ExitCase b -> WriterT w m c) -> (a -> WriterT w m b) -> WriterT w m (b, c) Source #
MonadMask m => MonadMask (StateT s m) |
Instance details Defined in Control.Monad.Catch Methods mask :: ((forall a. StateT s m a -> StateT s m a) -> StateT s m b) -> StateT s m b Source # uninterruptibleMask :: ((forall a. StateT s m a -> StateT s m a) -> StateT s m b) -> StateT s m b Source # generalBracket :: StateT s m a -> (a -> ExitCase b -> StateT s m c) -> (a -> StateT s m b) -> StateT s m (b, c) Source #
MonadMask m => MonadMask (ReaderT r m) |
Instance details Defined in Control.Monad.Catch Methods mask :: ((forall a. ReaderT r m a -> ReaderT r m a) -> ReaderT r m b) -> ReaderT r m b Source # uninterruptibleMask :: ((forall a. ReaderT r m a -> ReaderT r m a) -> ReaderT r m b) -> ReaderT r m b Source # generalBracket :: ReaderT r m a -> (a -> ExitCase b -> ReaderT r m c) -> (a -> ReaderT r m b) -> ReaderT r m (b, c) Source #
(Error e, MonadMask m) => MonadMask (ErrorT e m) |
Instance details Defined in Control.Monad.Catch Methods mask :: ((forall a. ErrorT e m a -> ErrorT e m a) -> ErrorT e m b) -> ErrorT e m b Source # uninterruptibleMask :: ((forall a. ErrorT e m a -> ErrorT e m a) -> ErrorT e m b) -> ErrorT e m b Source # generalBracket :: ErrorT e m a -> (a -> ExitCase b -> ErrorT e m c) -> (a -> ErrorT e m b) -> ErrorT e m (b, c) Source #
MonadMask m => MonadMask (IdentityT m) |
Instance details Defined in Control.Monad.Catch Methods mask :: ((forall a. IdentityT m a -> IdentityT m a) -> IdentityT m b) -> IdentityT m b Source # uninterruptibleMask :: ((forall a. IdentityT m a -> IdentityT m a) -> IdentityT m b) -> IdentityT m b Source # generalBracket :: IdentityT m a -> (a -> ExitCase b -> IdentityT m c) -> (a -> IdentityT m b) -> IdentityT m (b, c) Source #
MonadMask m => MonadMask (StateT s m) |
Instance details Defined in Control.Monad.Catch Methods mask :: ((forall a. StateT s m a -> StateT s m a) -> StateT s m b) -> StateT s m b Source # uninterruptibleMask :: ((forall a. StateT s m a -> StateT s m a) -> StateT s m b) -> StateT s m b Source # generalBracket :: StateT s m a -> (a -> ExitCase b -> StateT s m c) -> (a -> StateT s m b) -> StateT s m (b, c) Source #
(MonadMask m, Monoid w) => MonadMask (WriterT w m) |
Instance details Defined in Control.Monad.Catch Methods mask :: ((forall a. WriterT w m a -> WriterT w m a) -> WriterT w m b) -> WriterT w m b Source # uninterruptibleMask :: ((forall a. WriterT w m a -> WriterT w m a) -> WriterT w m b) -> WriterT w m b Source # generalBracket :: WriterT w m a -> (a -> ExitCase b -> WriterT w m c) -> (a -> WriterT w m b) -> WriterT w m (b, c) Source #
(MonadMask m, Monoid w) => MonadMask (RWST r w s m) |
Instance details Defined in Control.Monad.Catch Methods mask :: ((forall a. RWST r w s m a -> RWST r w s m a) -> RWST r w s m b) -> RWST r w s m b Source # uninterruptibleMask :: ((forall a. RWST r w s m a -> RWST r w s m a) -> RWST r w s m b) -> RWST r w s m b Source # generalBracket :: RWST r w s m a -> (a -> ExitCase b -> RWST r w s m c) -> (a -> RWST r w s m b) -> RWST r w s m (b, c) Source #
(MonadMask m, Monoid w) => MonadMask (RWST r w s m) |
Instance details Defined in Control.Monad.Catch Methods mask :: ((forall a. RWST r w s m a -> RWST r w s m a) -> RWST r w s m b) -> RWST r w s m b Source # uninterruptibleMask :: ((forall a. RWST r w s m a -> RWST r w s m a) -> RWST r w s m b) -> RWST r w s m b Source # generalBracket :: RWST r w s m a -> (a -> ExitCase b -> RWST r w s m c) -> (a -> RWST r w s m b) -> RWST r w s m (b, c) Source #
(MonadMask m, MonadIO m) => MonadMask (Proxy a' a b' b m) Source # |

Instance details

Defined in Pipes.Safe

Methods

mask :: ((forall a0. Proxy a' a b' b m a0 -> Proxy a' a b' b m a0) -> Proxy a' a b' b m b0) -> Proxy a' a b' b m b0 Source #

uninterruptibleMask :: ((forall a0. Proxy a' a b' b m a0 -> Proxy a' a b' b m a0) -> Proxy a' a b' b m b0) -> Proxy a' a b' b m b0 Source #

generalBracket :: Proxy a' a b' b m a0 -> (a0 -> ExitCase b0 -> Proxy a' a b' b m c) -> (a0 -> Proxy a' a b' b m b0) -> Proxy a' a b' b m (b0, c) Source #

data ExitCase a Source #

A `MonadMask` computation may either succeed with a value, abort with an exception, or abort for some other reason. For example, in `ExceptT e IO` you can use `throwM` to abort with an exception (`ExitCaseException`) or `throwE` to abort with a value of type `e` (`ExitCaseAbort`).

Constructors

ExitCaseSuccess a |
ExitCaseException SomeException |
ExitCaseAbort |

Instances

Show a => Show (ExitCase a) |
Instance details Defined in Control.Monad.Catch Methods showsPrec :: Int -> ExitCase a -> ShowS Source # show :: ExitCase a -> String Source # showList :: [ExitCase a] -> ShowS Source #

data Handler (m :: Type -> Type) a where Source #

Generalized version of `Handler`

Constructors

Handler :: forall (m :: Type -> Type) a e. Exception e => (e -> m a) -> Handler m a |

Instances

Monad m => Functor (Handler m) |
Instance details Defined in Control.Monad.Catch Methods fmap :: (a -> b) -> Handler m a -> Handler m b Source # (<$) :: a -> Handler m b -> Handler m a Source #

class (Typeable e, Show e) => Exception e where Source #

Any type that you wish to throw or catch as an exception must be an instance of the `Exception` class. The simplest case is a new exception type directly below the root:

    data MyException = ThisException | ThatException
        deriving Show

    instance Exception MyException

The default method definitions in the `Exception` class do what we need in this case. You can now throw and catch `ThisException` and `ThatException` as exceptions:

    *Main> throw ThisException `catch` \e -> putStrLn ("Caught " ++ show (e :: MyException))
    Caught ThisException

In more complicated examples, you may wish to define a whole hierarchy of exceptions:

    ---------------------------------------------------------------------
    -- Make the root exception type for all the exceptions in a compiler

    data SomeCompilerException = forall e . Exception e => SomeCompilerException e

    instance Show SomeCompilerException where
        show (SomeCompilerException e) = show e

    instance Exception SomeCompilerException

    compilerExceptionToException :: Exception e => e -> SomeException
    compilerExceptionToException = toException . SomeCompilerException

    compilerExceptionFromException :: Exception e => SomeException -> Maybe e
    compilerExceptionFromException x = do
        SomeCompilerException a <- fromException x
        cast a

    ---------------------------------------------------------------------
    -- Make a subhierarchy for exceptions in the frontend of the compiler

    data SomeFrontendException = forall e . Exception e => SomeFrontendException e

    instance Show SomeFrontendException where
        show (SomeFrontendException e) = show e

    instance Exception SomeFrontendException where
        toException = compilerExceptionToException
        fromException = compilerExceptionFromException

    frontendExceptionToException :: Exception e => e -> SomeException
    frontendExceptionToException = toException . SomeFrontendException

    frontendExceptionFromException :: Exception e => SomeException -> Maybe e
    frontendExceptionFromException x = do
        SomeFrontendException a <- fromException x
        cast a

    ---------------------------------------------------------------------
    -- Make an exception type for a particular frontend compiler exception

    data MismatchedParentheses = MismatchedParentheses
        deriving Show

    instance Exception MismatchedParentheses where
        toException   = frontendExceptionToException
        fromException = frontendExceptionFromException

We can now catch a `MismatchedParentheses` exception as `MismatchedParentheses`, `SomeFrontendException` or `SomeCompilerException`, but not other types, e.g. `IOException`:

    *Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: MismatchedParentheses))
    Caught MismatchedParentheses
    *Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: SomeFrontendException))
    Caught MismatchedParentheses
    *Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: SomeCompilerException))
    Caught MismatchedParentheses
    *Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: IOException))
    *** Exception: MismatchedParentheses

Minimal complete definition

Nothing

Methods

toException :: e -> SomeException Source #

fromException :: SomeException -> Maybe e Source #

displayException :: e -> String Source #

Render this exception value in a human-friendly manner.

Default implementation: ``show``.

Since: base-4.8.0.0

Instances

Exception Void | Since: base-4.8.0.0
Instance details Defined in Data.Void Methods toException :: Void -> SomeException Source # fromException :: SomeException -> Maybe Void Source # displayException :: Void -> String Source #
Exception BlockedIndefinitelyOnMVar | Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: BlockedIndefinitelyOnMVar -> SomeException Source # fromException :: SomeException -> Maybe BlockedIndefinitelyOnMVar Source # displayException :: BlockedIndefinitelyOnMVar -> String Source #
Exception BlockedIndefinitelyOnSTM | Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: BlockedIndefinitelyOnSTM -> SomeException Source # fromException :: SomeException -> Maybe BlockedIndefinitelyOnSTM Source # displayException :: BlockedIndefinitelyOnSTM -> String Source #
Exception Deadlock | Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: Deadlock -> SomeException Source # fromException :: SomeException -> Maybe Deadlock Source # displayException :: Deadlock -> String Source #
Exception AllocationLimitExceeded | Since: base-4.8.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: AllocationLimitExceeded -> SomeException Source # fromException :: SomeException -> Maybe AllocationLimitExceeded Source # displayException :: AllocationLimitExceeded -> String Source #
Exception CompactionFailed | Since: base-4.10.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: CompactionFailed -> SomeException Source # fromException :: SomeException -> Maybe CompactionFailed Source # displayException :: CompactionFailed -> String Source #
Exception AssertionFailed | Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: AssertionFailed -> SomeException Source # fromException :: SomeException -> Maybe AssertionFailed Source # displayException :: AssertionFailed -> String Source #
Exception SomeAsyncException | Since: base-4.7.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: SomeAsyncException -> SomeException Source # fromException :: SomeException -> Maybe SomeAsyncException Source # displayException :: SomeAsyncException -> String Source #
Exception AsyncException | Since: base-4.7.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: AsyncException -> SomeException Source # fromException :: SomeException -> Maybe AsyncException Source # displayException :: AsyncException -> String Source #
Exception ArrayException | Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: ArrayException -> SomeException Source # fromException :: SomeException -> Maybe ArrayException Source # displayException :: ArrayException -> String Source #
Exception FixIOException | Since: base-4.11.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: FixIOException -> SomeException Source # fromException :: SomeException -> Maybe FixIOException Source # displayException :: FixIOException -> String Source #
Exception ExitCode | Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: ExitCode -> SomeException Source # fromException :: SomeException -> Maybe ExitCode Source # displayException :: ExitCode -> String Source #
Exception IOException | Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: IOException -> SomeException Source # fromException :: SomeException -> Maybe IOException Source # displayException :: IOException -> String Source #
Exception ArithException | Since: base-4.0.0.0
Instance details Defined in GHC.Exception.Type Methods toException :: ArithException -> SomeException Source # fromException :: SomeException -> Maybe ArithException Source # displayException :: ArithException -> String Source #
Exception SomeException | Since: base-3.0
Instance details Defined in GHC.Exception.Type Methods toException :: SomeException -> SomeException Source # fromException :: SomeException -> Maybe SomeException Source # displayException :: SomeException -> String Source #

data SomeException where Source #

The `SomeException` type is the root of the exception type hierarchy. When an exception of type `e` is thrown, behind the scenes it is encapsulated in a `SomeException`.

Constructors

SomeException :: forall e. Exception e => e -> SomeException |

Instances

Show SomeException | Since: base-3.0
Instance details Defined in GHC.Exception.Type Methods showsPrec :: Int -> SomeException -> ShowS Source # show :: SomeException -> String Source # showList :: [SomeException] -> ShowS Source #
Exception SomeException | Since: base-3.0
Instance details Defined in GHC.Exception.Type Methods toException :: SomeException -> SomeException Source # fromException :: SomeException -> Maybe SomeException Source # displayException :: SomeException -> String Source #

# Orphan instances

(MonadMask m, MonadIO m) => MonadMask (Proxy a' a b' b m) Source # |

Instance details

Methods

mask :: ((forall a0. Proxy a' a b' b m a0 -> Proxy a' a b' b m a0) -> Proxy a' a b' b m b0) -> Proxy a' a b' b m b0 Source #

uninterruptibleMask :: ((forall a0. Proxy a' a b' b m a0 -> Proxy a' a b' b m a0) -> Proxy a' a b' b m b0) -> Proxy a' a b' b m b0 Source #

generalBracket :: Proxy a' a b' b m a0 -> (a0 -> ExitCase b0 -> Proxy a' a b' b m c) -> (a0 -> Proxy a' a b' b m b0) -> Proxy a' a b' b m (b0, c) Source #