safe-exceptions-0.1.6.0: Safe, consistent, and easy exception handling

Safe Haskell | Safe
Language | Haskell2010

Control.Exception.Safe

Contents

- Throwing
- Catching (with recovery)
- Cleanup (no recovery)
- Coercion to sync and async
- Check exception type
- Reexports

Description

Please see the README.md file in the safe-exceptions repo for information on how to use this module. Relevant links:

- https://github.com/fpco/safe-exceptions#readme
- https://www.stackage.org/package/safe-exceptions

Synopsis

- throw :: (MonadThrow m, Exception e) => e -> m a
- throwIO :: (MonadThrow m, Exception e) => e -> m a
- throwM :: (MonadThrow m, Exception e) => e -> m a
- throwString :: (MonadThrow m, HasCallStack) => String -> m a
- data StringException = StringException String CallStack
- throwTo :: (Exception e, MonadIO m) => ThreadId -> e -> m ()
- impureThrow :: Exception e => e -> a
- catch :: (MonadCatch m, Exception e) => m a -> (e -> m a) -> m a
- catchIO :: MonadCatch m => m a -> (IOException -> m a) -> m a
- catchAny :: MonadCatch m => m a -> (SomeException -> m a) -> m a
- catchDeep :: (MonadCatch m, MonadIO m, Exception e, NFData a) => m a -> (e -> m a) -> m a
- catchAnyDeep :: (MonadCatch m, MonadIO m, NFData a) => m a -> (SomeException -> m a) -> m a
- catchAsync :: (MonadCatch m, Exception e) => m a -> (e -> m a) -> m a
- catchJust :: (MonadCatch m, Exception e) => (e -> Maybe b) -> m a -> (b -> m a) -> m a
- handle :: (MonadCatch m, Exception e) => (e -> m a) -> m a -> m a
- handleIO :: MonadCatch m => (IOException -> m a) -> m a -> m a
- handleAny :: MonadCatch m => (SomeException -> m a) -> m a -> m a
- handleDeep :: (MonadCatch m, Exception e, MonadIO m, NFData a) => (e -> m a) -> m a -> m a
- handleAnyDeep :: (MonadCatch m, MonadIO m, NFData a) => (SomeException -> m a) -> m a -> m a
- handleAsync :: (MonadCatch m, Exception e) => (e -> m a) -> m a -> m a
- handleJust :: (MonadCatch m, Exception e) => (e -> Maybe b) -> (b -> m a) -> m a -> m a
- try :: (MonadCatch m, Exception e) => m a -> m (Either e a)
- tryIO :: MonadCatch m => m a -> m (Either IOException a)
- tryAny :: MonadCatch m => m a -> m (Either SomeException a)
- tryDeep :: (MonadCatch m, MonadIO m, Exception e, NFData a) => m a -> m (Either e a)
- tryAnyDeep :: (MonadCatch m, MonadIO m, NFData a) => m a -> m (Either SomeException a)
- tryAsync :: (MonadCatch m, Exception e) => m a -> m (Either e a)
- tryJust :: (MonadCatch m, Exception e) => (e -> Maybe b) -> m a -> m (Either b a)
- data Handler m a :: (* -> *) -> * -> * where
  - Handler :: Handler m a
- catches :: (MonadCatch m, MonadThrow m) => m a -> [Handler m a] -> m a
- catchesDeep :: (MonadCatch m, MonadThrow m, MonadIO m, NFData a) => m a -> [Handler m a] -> m a
- catchesAsync :: (MonadCatch m, MonadThrow m) => m a -> [Handler m a] -> m a
- onException :: MonadMask m => m a -> m b -> m a
- bracket :: forall m a b c. MonadMask m => m a -> (a -> m b) -> (a -> m c) -> m c
- bracket_ :: MonadMask m => m a -> m b -> m c -> m c
- finally :: MonadMask m => m a -> m b -> m a
- withException :: (MonadMask m, Exception e) => m a -> (e -> m b) -> m a
- bracketOnError :: forall m a b c. MonadMask m => m a -> (a -> m b) -> (a -> m c) -> m c
- bracketOnError_ :: MonadMask m => m a -> m b -> m c -> m c
- data SyncExceptionWrapper = Exception e => SyncExceptionWrapper e
- toSyncException :: Exception e => e -> SomeException
- data AsyncExceptionWrapper = Exception e => AsyncExceptionWrapper e
- toAsyncException :: Exception e => e -> SomeException
- isSyncException :: Exception e => e -> Bool
- isAsyncException :: Exception e => e -> Bool
- class Monad m => MonadThrow m
- class MonadThrow m => MonadCatch m
- class MonadCatch m => MonadMask m where
- mask_ :: MonadMask m => m a -> m a
- uninterruptibleMask_ :: MonadMask m => m a -> m a
- catchIOError :: MonadCatch m => m a -> (IOError -> m a) -> m a
- handleIOError :: MonadCatch m => (IOError -> m a) -> m a -> m a
- class (Typeable * e, Show e) => Exception e where
- class Typeable k a
- data SomeException :: * where
  - SomeException :: SomeException
- data SomeAsyncException :: * where
  - SomeAsyncException :: SomeAsyncException
- data IOException :: *
- assert :: Bool -> a -> a

# Throwing

throw :: (MonadThrow m, Exception e) => e -> m a #

Synchronously throw the given exception

Since: 0.1.0.0

throwIO :: (MonadThrow m, Exception e) => e -> m a #

Synonym for `throw`

Since: 0.1.0.0

throwM :: (MonadThrow m, Exception e) => e -> m a #

Synonym for `throw`

Since: 0.1.0.0

throwString :: (MonadThrow m, HasCallStack) => String -> m a #

A convenience function for throwing a user error. This is useful for cases where it would be too high a burden to define your own exception type.

This throws an exception of type `StringException`. When GHC supports it (base 4.9 and GHC 8.0 and onward), it includes a call stack.

Since: 0.1.5.0

data StringException #

Exception type thrown by `throwString`.

Note that the second field of the data constructor depends on GHC/base version. For base 4.9 and GHC 8.0 and later, the second field is a call stack. Previous versions of GHC and base do not support call stacks, and the field is simply unit (provided to make pattern matching across GHC versions easier).

Since: 0.1.5.0

Constructors

StringException String CallStack |

Instances

Show StringException # |
Methods showsPrec :: Int -> StringException -> ShowS # show :: StringException -> String # showList :: [StringException] -> ShowS #
Exception StringException # |
Methods toException :: StringException -> SomeException # fromException :: SomeException -> Maybe StringException # displayException :: StringException -> String #

throwTo :: (Exception e, MonadIO m) => ThreadId -> e -> m () #

Throw an asynchronous exception to another thread.

Synchronously typed exceptions will be wrapped into an `AsyncExceptionWrapper`, see https://github.com/fpco/safe-exceptions#determining-sync-vs-async

It's usually a better idea to use the async package, see https://github.com/fpco/safe-exceptions#quickstart

Since: 0.1.0.0

impureThrow :: Exception e => e -> a #

Generate a pure value which, when forced, will synchronously throw the given exception

Generally it's better to avoid using this function and instead use `throw`, see https://github.com/fpco/safe-exceptions#quickstart

Since: 0.1.0.0

# Catching (with recovery)

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

Same as upstream `catch`, but will not catch asynchronous exceptions

Since: 0.1.0.0

catchIO :: MonadCatch m => m a -> (IOException -> m a) -> m a #

`catch` specialized to only catching `IOException`s

Since: 0.1.3.0

catchAny :: MonadCatch m => m a -> (SomeException -> m a) -> m a #

`catch` specialized to catch all synchronous exception

Since: 0.1.0.0

catchDeep :: (MonadCatch m, MonadIO m, Exception e, NFData a) => m a -> (e -> m a) -> m a #

Same as `catch`, but fully force evaluation of the result value to find all impure exceptions.

Since: 0.1.1.0

catchAnyDeep :: (MonadCatch m, MonadIO m, NFData a) => m a -> (SomeException -> m a) -> m a #

`catchDeep` specialized to catch all synchronous exception

Since: 0.1.1.0

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

`catch` without async exception safety

Generally it's better to avoid using this function since we do not want to recover from async exceptions, see https://github.com/fpco/safe-exceptions#quickstart

Since: 0.1.0.0

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

`catchJust` is like `catch` but it takes an extra argument which is an exception predicate, a function which selects which type of exceptions we're interested in.

Since: 0.1.4.0

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

Flipped version of `catch`

Since: 0.1.0.0

handleIO :: MonadCatch m => (IOException -> m a) -> m a -> m a #

`handle` specialized to only catching `IOException`s

Since: 0.1.3.0

handleAny :: MonadCatch m => (SomeException -> m a) -> m a -> m a #

Flipped version of `catchAny`

Since: 0.1.0.0

handleDeep :: (MonadCatch m, Exception e, MonadIO m, NFData a) => (e -> m a) -> m a -> m a #

Flipped version of `catchDeep`

Since: 0.1.1.0

handleAnyDeep :: (MonadCatch m, MonadIO m, NFData a) => (SomeException -> m a) -> m a -> m a #

Flipped version of `catchAnyDeep`

Since: 0.1.1.0

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

Flipped version of `catchAsync`

Generally it's better to avoid using this function since we do not want to recover from async exceptions, see https://github.com/fpco/safe-exceptions#quickstart

Since: 0.1.0.0

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

Flipped `catchJust`.

Since: 0.1.4.0

try :: (MonadCatch m, Exception e) => m a -> m (Either e a) #

Same as upstream `try`, but will not catch asynchronous exceptions

Since: 0.1.0.0

tryIO :: MonadCatch m => m a -> m (Either IOException a) #

`try` specialized to only catching `IOException`s

Since: 0.1.3.0

tryAny :: MonadCatch m => m a -> m (Either SomeException a) #

`try` specialized to catch all synchronous exceptions

Since: 0.1.0.0

tryDeep :: (MonadCatch m, MonadIO m, Exception e, NFData a) => m a -> m (Either e a) #

Same as `try`, but fully force evaluation of the result value to find all impure exceptions.

Since: 0.1.1.0

tryAnyDeep :: (MonadCatch m, MonadIO m, NFData a) => m a -> m (Either SomeException a) #

`tryDeep` specialized to catch all synchronous exceptions

Since: 0.1.1.0

tryAsync :: (MonadCatch m, Exception e) => m a -> m (Either e a) #

`try` without async exception safety

Generally it's better to avoid using this function since we do not want to recover from async exceptions, see https://github.com/fpco/safe-exceptions#quickstart

Since: 0.1.0.0

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

A variant of `try` that takes an exception predicate to select which exceptions are caught.

Since: 0.1.4.0

data Handler m a :: (* -> *) -> * -> * where #

Generalized version of `Handler`

Constructors

Handler :: Handler m a |

Instances

Monad m => Functor (Handler m) |
Methods fmap :: (a -> b) -> Handler m a -> Handler m b # (<$) :: a -> Handler m b -> Handler m a #

catches :: (MonadCatch m, MonadThrow m) => m a -> [Handler m a] -> m a #

Same as upstream `catches`, but will not catch asynchronous exceptions

Since: 0.1.2.0

catchesDeep :: (MonadCatch m, MonadThrow m, MonadIO m, NFData a) => m a -> [Handler m a] -> m a #

Same as `catches`, but fully force evaluation of the result value to find all impure exceptions.

Since: 0.1.2.0

catchesAsync :: (MonadCatch m, MonadThrow m) => m a -> [Handler m a] -> m a #

`catches` without async exception safety

Generally it's better to avoid using this function since we do not want to recover from async exceptions, see https://github.com/fpco/safe-exceptions#quickstart

Since: 0.1.2.0

# Cleanup (no recovery)

onException :: MonadMask m => m a -> m b -> m a #

Async safe version of `onException`

Since: 0.1.0.0

bracket :: forall m a b c. MonadMask m => m a -> (a -> m b) -> (a -> m c) -> m c #

Async safe version of `bracket`

Since: 0.1.0.0

bracket_ :: MonadMask m => m a -> m b -> m c -> m c #

Async safe version of `bracket_`

Since: 0.1.0.0

finally :: MonadMask m => m a -> m b -> m a #

Async safe version of `finally`

Since: 0.1.0.0

withException :: (MonadMask m, Exception e) => m a -> (e -> m b) -> m a #

Like `onException`, but provides the handler the thrown exception.

Since: 0.1.0.0

bracketOnError :: forall m a b c. MonadMask m => m a -> (a -> m b) -> (a -> m c) -> m c #

Async safe version of `bracketOnError`

Since: 0.1.0.0

bracketOnError_ :: MonadMask m => m a -> m b -> m c -> m c #

A variant of `bracketOnError` where the return value from the first computation is not required.

Since: 0.1.0.0

# Coercion to sync and async

data SyncExceptionWrapper #

Wrap up an asynchronous exception to be treated as a synchronous exception

This is intended to be created via `toSyncException`

Since: 0.1.0.0

Constructors

Exception e => SyncExceptionWrapper e |

Instances

Show SyncExceptionWrapper # |
Methods showsPrec :: Int -> SyncExceptionWrapper -> ShowS # show :: SyncExceptionWrapper -> String # showList :: [SyncExceptionWrapper] -> ShowS #
Exception SyncExceptionWrapper # |
Methods toException :: SyncExceptionWrapper -> SomeException # fromException :: SomeException -> Maybe SyncExceptionWrapper # displayException :: SyncExceptionWrapper -> String #

toSyncException :: Exception e => e -> SomeException #

Convert an exception into a synchronous exception

For synchronous exceptions, this is the same as `toException`. For asynchronous exceptions, this will wrap up the exception with `SyncExceptionWrapper`

Since: 0.1.0.0

data AsyncExceptionWrapper #

Wrap up a synchronous exception to be treated as an asynchronous exception

This is intended to be created via `toAsyncException`

Since: 0.1.0.0

Constructors

Exception e => AsyncExceptionWrapper e |

Instances

Show AsyncExceptionWrapper # |
Methods showsPrec :: Int -> AsyncExceptionWrapper -> ShowS # show :: AsyncExceptionWrapper -> String # showList :: [AsyncExceptionWrapper] -> ShowS #
Exception AsyncExceptionWrapper # |
Methods toException :: AsyncExceptionWrapper -> SomeException # fromException :: SomeException -> Maybe AsyncExceptionWrapper # displayException :: AsyncExceptionWrapper -> String #

toAsyncException :: Exception e => e -> SomeException #

Convert an exception into an asynchronous exception

For asynchronous exceptions, this is the same as `toException`. For synchronous exceptions, this will wrap up the exception with `AsyncExceptionWrapper`

Since: 0.1.0.0

# Check exception type

isSyncException :: Exception e => e -> Bool #

Check if the given exception is synchronous

Since: 0.1.0.0

isAsyncException :: Exception e => e -> Bool #

Check if the given exception is asynchronous

Since: 0.1.0.0

# Reexports

class Monad m => MonadThrow m #

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.

Minimal complete definition

throwM

Instances

MonadThrow [] |
Methods throwM :: Exception e => e -> [a] #
MonadThrow Maybe |
Methods throwM :: Exception e => e -> Maybe a #
MonadThrow IO |
Methods throwM :: Exception e => e -> IO a #
MonadThrow Q |
Methods throwM :: Exception e => e -> Q a #
MonadThrow STM |
Methods throwM :: Exception e => e -> STM a #
(~) * e SomeException => MonadThrow (Either e) |
Methods throwM :: Exception e => e -> Either e a #
MonadThrow m => MonadThrow (ListT m) |
Methods throwM :: Exception e => e -> ListT m a #
MonadThrow m => MonadThrow (MaybeT m) | Throws exceptions into the base monad.
Methods throwM :: Exception e => e -> MaybeT m a #
(Error e, MonadThrow m) => MonadThrow (ErrorT e m) | Throws exceptions into the base monad.
Methods throwM :: Exception e => e -> ErrorT e m a #
MonadThrow m => MonadThrow (ExceptT e m) | Throws exceptions into the base monad.
Methods throwM :: Exception e => e -> ExceptT e m a #
MonadThrow m => MonadThrow (StateT s m) |
Methods throwM :: Exception e => e -> StateT s m a #
MonadThrow m => MonadThrow (StateT s m) |
Methods throwM :: Exception e => e -> StateT s m a #
(MonadThrow m, Monoid w) => MonadThrow (WriterT w m) |
Methods throwM :: Exception e => e -> WriterT w m a #
(MonadThrow m, Monoid w) => MonadThrow (WriterT w m) |
Methods throwM :: Exception e => e -> WriterT w m a #
MonadThrow m => MonadThrow (IdentityT * m) |
Methods throwM :: Exception e => e -> IdentityT * m a #
MonadThrow m => MonadThrow (ContT * r m) |
Methods throwM :: Exception e => e -> ContT * r m a #
MonadThrow m => MonadThrow (ReaderT * r m) |
Methods throwM :: Exception e => e -> ReaderT * r m a #
(MonadThrow m, Monoid w) => MonadThrow (RWST r w s m) |
Methods throwM :: Exception e => e -> RWST r w s m a #
(MonadThrow m, Monoid w) => MonadThrow (RWST r w s m) |
Methods throwM :: Exception e => e -> RWST r w s m a #

class MonadThrow m => MonadCatch m #

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

Minimal complete definition

catch

Instances

MonadCatch IO |
Methods catch :: Exception e => IO a -> (e -> IO a) -> IO a #
MonadCatch STM |
Methods catch :: Exception e => STM a -> (e -> STM a) -> STM a #
(~) * e SomeException => MonadCatch (Either e) | Since: 0.8.3
Methods catch :: Exception e => Either e a -> (e -> Either e a) -> Either e a #
MonadCatch m => MonadCatch (ListT m) |
Methods catch :: Exception e => ListT m a -> (e -> ListT m a) -> ListT m a #
MonadCatch m => MonadCatch (MaybeT m) | Catches exceptions from the base monad.
Methods catch :: Exception e => MaybeT m a -> (e -> MaybeT m a) -> MaybeT m a #
(Error e, MonadCatch m) => MonadCatch (ErrorT e m) | Catches exceptions from the base monad.
Methods catch :: Exception e => ErrorT e m a -> (e -> ErrorT e m a) -> ErrorT e m a #
MonadCatch m => MonadCatch (ExceptT e m) | Catches exceptions from the base monad.
Methods catch :: Exception e => ExceptT e m a -> (e -> ExceptT e m a) -> ExceptT e m a #
MonadCatch m => MonadCatch (StateT s m) |
Methods catch :: Exception e => StateT s m a -> (e -> StateT s m a) -> StateT s m a #
MonadCatch m => MonadCatch (StateT s m) |
Methods catch :: Exception e => StateT s m a -> (e -> StateT s m a) -> StateT s m a #
(MonadCatch m, Monoid w) => MonadCatch (WriterT w m) |
Methods catch :: Exception e => WriterT w m a -> (e -> WriterT w m a) -> WriterT w m a #
(MonadCatch m, Monoid w) => MonadCatch (WriterT w m) |
Methods catch :: Exception e => WriterT w m a -> (e -> WriterT w m a) -> WriterT w m a #
MonadCatch m => MonadCatch (IdentityT * m) |
Methods catch :: Exception e => IdentityT * m a -> (e -> IdentityT * m a) -> IdentityT * m a #
MonadCatch m => MonadCatch (ReaderT * r m) |
Methods catch :: Exception e => ReaderT * r m a -> (e -> ReaderT * r m a) -> ReaderT * r m a #
(MonadCatch m, Monoid w) => MonadCatch (RWST r w s m) |
Methods catch :: Exception e => RWST r w s m a -> (e -> RWST r w s m a) -> RWST r w s m a #
(MonadCatch m, Monoid w) => MonadCatch (RWST r w s m) |
Methods catch :: Exception e => RWST r w s m a -> (e -> RWST r w s m a) -> RWST r w s m a #

class MonadCatch m => MonadMask m where #

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, and stacks such as `ErrorT e IO` which provide for multiple failure modes, are invalid instances of this class.

Note that this package does provide a `MonadMask` instance for `CatchT`. This instance is only valid if the base monad provides no ability to provide multiple exit. For example, `IO` or `Either` would be invalid base monads, but `Reader` or `State` would be acceptable.

Instances should ensure that, in the following code:

    f `finally` g

The action `g` is called regardless of what occurs within `f`, including async exceptions.

Minimal complete definition

mask, uninterruptibleMask

Methods

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

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 #

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.

Instances

MonadMask IO |
Methods mask :: ((forall a. IO a -> IO a) -> IO b) -> IO b # uninterruptibleMask :: ((forall a. IO a -> IO a) -> IO b) -> IO b #
(~) * e SomeException => MonadMask (Either e) | Since: 0.8.3
Methods mask :: ((forall a. Either e a -> Either e a) -> Either e b) -> Either e b # uninterruptibleMask :: ((forall a. Either e a -> Either e a) -> Either e b) -> Either e b #
MonadMask m => MonadMask (StateT s m) |
Methods mask :: ((forall a. StateT s m a -> StateT s m a) -> StateT s m b) -> StateT s m b # uninterruptibleMask :: ((forall a. StateT s m a -> StateT s m a) -> StateT s m b) -> StateT s m b #
MonadMask m => MonadMask (StateT s m) |
Methods mask :: ((forall a. StateT s m a -> StateT s m a) -> StateT s m b) -> StateT s m b # uninterruptibleMask :: ((forall a. StateT s m a -> StateT s m a) -> StateT s m b) -> StateT s m b #
(MonadMask m, Monoid w) => MonadMask (WriterT w m) |
Methods mask :: ((forall a. WriterT w m a -> WriterT w m a) -> WriterT w m b) -> WriterT w m b # uninterruptibleMask :: ((forall a. WriterT w m a -> WriterT w m a) -> WriterT w m b) -> WriterT w m b #
(MonadMask m, Monoid w) => MonadMask (WriterT w m) |
Methods mask :: ((forall a. WriterT w m a -> WriterT w m a) -> WriterT w m b) -> WriterT w m b # uninterruptibleMask :: ((forall a. WriterT w m a -> WriterT w m a) -> WriterT w m b) -> WriterT w m b #
MonadMask m => MonadMask (IdentityT * m) |
Methods mask :: ((forall a. IdentityT * m a -> IdentityT * m a) -> IdentityT * m b) -> IdentityT * m b # uninterruptibleMask :: ((forall a. IdentityT * m a -> IdentityT * m a) -> IdentityT * m b) -> IdentityT * m b #
MonadMask m => MonadMask (ReaderT * r m) |
Methods mask :: ((forall a. ReaderT * r m a -> ReaderT * r m a) -> ReaderT * r m b) -> ReaderT * r m b # uninterruptibleMask :: ((forall a. ReaderT * r m a -> ReaderT * r m a) -> ReaderT * r m b) -> ReaderT * r m b #
(MonadMask m, Monoid w) => MonadMask (RWST r w s m) |
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 # 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 #
(MonadMask m, Monoid w) => MonadMask (RWST r w s m) |
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 # 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 #

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

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

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

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

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

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.

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

Flipped `catchIOError`

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

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, Typeable)

    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
        deriving Typeable

    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
        deriving Typeable

    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 (Typeable, 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

Methods

toException :: e -> SomeException #

fromException :: SomeException -> Maybe e #

displayException :: e -> String #

Render this exception value in a human-friendly manner.

Default implementation: ``show``.

Since: 4.8.0.0

Instances

Exception BlockedIndefinitelyOnMVar |
Methods toException :: BlockedIndefinitelyOnMVar -> SomeException # fromException :: SomeException -> Maybe BlockedIndefinitelyOnMVar # displayException :: BlockedIndefinitelyOnMVar -> String #
Exception BlockedIndefinitelyOnSTM |
Methods toException :: BlockedIndefinitelyOnSTM -> SomeException # fromException :: SomeException -> Maybe BlockedIndefinitelyOnSTM # displayException :: BlockedIndefinitelyOnSTM -> String #
Exception Deadlock |
Methods toException :: Deadlock -> SomeException # fromException :: SomeException -> Maybe Deadlock # displayException :: Deadlock -> String #
Exception AllocationLimitExceeded |
Methods toException :: AllocationLimitExceeded -> SomeException # fromException :: SomeException -> Maybe AllocationLimitExceeded # displayException :: AllocationLimitExceeded -> String #
Exception AssertionFailed |
Methods toException :: AssertionFailed -> SomeException # fromException :: SomeException -> Maybe AssertionFailed # displayException :: AssertionFailed -> String #
Exception SomeAsyncException |
Methods toException :: SomeAsyncException -> SomeException # fromException :: SomeException -> Maybe SomeAsyncException # displayException :: SomeAsyncException -> String #
Exception AsyncException |
Methods toException :: AsyncException -> SomeException # fromException :: SomeException -> Maybe AsyncException # displayException :: AsyncException -> String #
Exception ArrayException |
Methods toException :: ArrayException -> SomeException # fromException :: SomeException -> Maybe ArrayException # displayException :: ArrayException -> String #
Exception ExitCode |
Methods toException :: ExitCode -> SomeException # fromException :: SomeException -> Maybe ExitCode # displayException :: ExitCode -> String #
Exception IOException |
Methods toException :: IOException -> SomeException # fromException :: SomeException -> Maybe IOException # displayException :: IOException -> String #
Exception ErrorCall |
Methods toException :: ErrorCall -> SomeException # fromException :: SomeException -> Maybe ErrorCall # displayException :: ErrorCall -> String #
Exception ArithException |
Methods toException :: ArithException -> SomeException # fromException :: SomeException -> Maybe ArithException # displayException :: ArithException -> String #
Exception SomeException |
Methods toException :: SomeException -> SomeException # fromException :: SomeException -> Maybe SomeException # displayException :: SomeException -> String #
Exception AsyncExceptionWrapper # |
Methods toException :: AsyncExceptionWrapper -> SomeException # fromException :: SomeException -> Maybe AsyncExceptionWrapper # displayException :: AsyncExceptionWrapper -> String #
Exception SyncExceptionWrapper # |
Methods toException :: SyncExceptionWrapper -> SomeException # fromException :: SomeException -> Maybe SyncExceptionWrapper # displayException :: SyncExceptionWrapper -> String #
Exception StringException # |
Methods toException :: StringException -> SomeException # fromException :: SomeException -> Maybe StringException # displayException :: StringException -> String #

class Typeable k a #

The class `Typeable` allows a concrete representation of a type to be calculated.

Minimal complete definition

typeRep#

data SomeException :: * where #

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 :: SomeException |

Instances

Show SomeException |
Methods showsPrec :: Int -> SomeException -> ShowS # show :: SomeException -> String # showList :: [SomeException] -> ShowS #
Exception SomeException |
Methods toException :: SomeException -> SomeException # fromException :: SomeException -> Maybe SomeException # displayException :: SomeException -> String #

data SomeAsyncException :: * where #

Superclass for asynchronous exceptions.

Since: 4.7.0.0

Constructors

SomeAsyncException :: SomeAsyncException |

Instances

Show SomeAsyncException |
Methods showsPrec :: Int -> SomeAsyncException -> ShowS # show :: SomeAsyncException -> String # showList :: [SomeAsyncException] -> ShowS #
Exception SomeAsyncException |
Methods toException :: SomeAsyncException -> SomeException # fromException :: SomeException -> Maybe SomeAsyncException # displayException :: SomeAsyncException -> String #

data IOException :: * #

Exceptions that occur in the `IO` monad. An `IOException` records a more specific error type, a descriptive string and maybe the handle that was used when the error was flagged.

Instances

Eq IOException |
Methods (==) :: IOException -> IOException -> Bool # (/=) :: IOException -> IOException -> Bool #
Show IOException |
Methods showsPrec :: Int -> IOException -> ShowS # show :: IOException -> String # showList :: [IOException] -> ShowS #
Exception IOException |
Methods toException :: IOException -> SomeException # fromException :: SomeException -> Maybe IOException # displayException :: IOException -> String #
Error IOException |
Methods noMsg :: IOException # strMsg :: String -> IOException #

assert :: Bool -> a -> a #

If the first argument evaluates to `True`, then the result is the second argument. Otherwise an `AssertionFailed` exception is raised, containing a `String` with the source file and line number of the call to `assert`.

Assertions can normally be turned on or off with a compiler flag (for GHC, assertions are normally on unless optimisation is turned on with `-O` or the `-fignore-asserts` option is given). When assertions are turned off, the first argument to `assert` is ignored, and the second argument is returned as the result.