Control.Exception.Lifted

lifted-base-0.2.3.6: lifted IO operations from the base library

Copyright | Bas van Dijk Anders Kaseorg
License | BSD-style
Maintainer | Bas van Dijk <v.dijk.bas@gmail.com>
Stability | experimental
Portability | non-portable (extended exceptions)
Safe Haskell | Trustworthy
Language | Haskell98

Control.Exception.Lifted

Contents

- Throwing exceptions
- Catching exceptions
  - The `catch` functions
  - The `handle` functions
  - The `try` functions
  - The `evaluate` function
- Asynchronous Exceptions
  - Asynchronous exception control
- Brackets
- Utilities

Description

This is a wrapped version of Control.Exception with types generalized from `IO` to all monads in either `MonadBase` or `MonadBaseControl`.

Synopsis

- assert :: Bool -> a -> a
- mapException :: (Exception e1, Exception e2) => (e1 -> e2) -> a -> a
- newtype PatternMatchFail = PatternMatchFail String
- newtype RecSelError = RecSelError String
- newtype RecConError = RecConError String
- newtype RecUpdError = RecUpdError String
- newtype NoMethodError = NoMethodError String
- newtype TypeError = TypeError String
- data NonTermination = NonTermination
- data NestedAtomically = NestedAtomically
- asyncExceptionFromException :: Exception e => SomeException -> Maybe e
- asyncExceptionToException :: Exception e => e -> SomeException
- data BlockedIndefinitelyOnMVar = BlockedIndefinitelyOnMVar
- data BlockedIndefinitelyOnSTM = BlockedIndefinitelyOnSTM
- data Deadlock = Deadlock
- data AllocationLimitExceeded = AllocationLimitExceeded
- newtype CompactionFailed = CompactionFailed String
- newtype AssertionFailed = AssertionFailed String
- data SomeAsyncException where
  - SomeAsyncException :: forall e. Exception e => e -> SomeAsyncException
- data AsyncException
  - = StackOverflow
  - | HeapOverflow
  - | ThreadKilled
  - | UserInterrupt
- data ArrayException
  - = IndexOutOfBounds String
  - | UndefinedElement String
- interruptible :: IO a -> IO a
- data MaskingState
  - = Unmasked
  - | MaskedInterruptible
  - | MaskedUninterruptible
- data IOException
- throw :: Exception e => e -> a
- data ErrorCall where
  - ErrorCallWithLocation String String
  - pattern ErrorCall :: String -> ErrorCall
- class (Typeable e, Show e) => Exception e where
  - toException :: e -> SomeException
  - fromException :: SomeException -> Maybe e
  - displayException :: e -> String
- data ArithException
  - = Overflow
  - | Underflow
  - | LossOfPrecision
  - | DivideByZero
  - | Denormal
  - | RatioZeroDenominator
- data SomeException where
  - SomeException :: forall e. Exception e => e -> SomeException
- throwIO :: (MonadBase IO m, Exception e) => e -> m a
- ioError :: MonadBase IO m => IOError -> m a
- throwTo :: (MonadBase IO m, Exception e) => ThreadId -> e -> m ()
- catch :: (MonadBaseControl IO m, Exception e) => m a -> (e -> m a) -> m a
- catches :: MonadBaseControl IO m => m a -> [Handler m a] -> m a
- data Handler m a = Exception e => Handler (e -> m a)
- catchJust :: (MonadBaseControl IO m, Exception e) => (e -> Maybe b) -> m a -> (b -> m a) -> m a
- handle :: (MonadBaseControl IO m, Exception e) => (e -> m a) -> m a -> m a
- handleJust :: (MonadBaseControl IO m, Exception e) => (e -> Maybe b) -> (b -> m a) -> m a -> m a
- try :: (MonadBaseControl IO m, Exception e) => m a -> m (Either e a)
- tryJust :: (MonadBaseControl IO m, Exception e) => (e -> Maybe b) -> m a -> m (Either b a)
- evaluate :: MonadBase IO m => a -> m a
- mask :: MonadBaseControl IO m => ((forall a. m a -> m a) -> m b) -> m b
- mask_ :: MonadBaseControl IO m => m a -> m a
- uninterruptibleMask :: MonadBaseControl IO m => ((forall a. m a -> m a) -> m b) -> m b
- uninterruptibleMask_ :: MonadBaseControl IO m => m a -> m a
- getMaskingState :: MonadBase IO m => m MaskingState
- allowInterrupt :: MonadBase IO m => m ()
- bracket :: MonadBaseControl IO m => m a -> (a -> m b) -> (a -> m c) -> m c
- bracket_ :: MonadBaseControl IO m => m a -> m b -> m c -> m c
- bracketOnError :: MonadBaseControl IO m => m a -> (a -> m b) -> (a -> m c) -> m c
- finally :: MonadBaseControl IO m => m a -> m b -> m a
- onException :: MonadBaseControl IO m => m a -> m b -> m a

# Documentation

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.

mapException :: (Exception e1, Exception e2) => (e1 -> e2) -> a -> a #

This function maps one exception into another as proposed in the paper "A semantics for imprecise exceptions".

newtype PatternMatchFail #

A pattern match failed. The `String` gives information about the source location of the pattern.

Constructors

PatternMatchFail String |

Instances

Show PatternMatchFail | Since: base-4.0
Instance details Defined in Control.Exception.Base Methods showsPrec :: Int -> PatternMatchFail -> ShowS # show :: PatternMatchFail -> String # showList :: [PatternMatchFail] -> ShowS #
Exception PatternMatchFail | Since: base-4.0
Instance details Defined in Control.Exception.Base Methods toException :: PatternMatchFail -> SomeException # fromException :: SomeException -> Maybe PatternMatchFail # displayException :: PatternMatchFail -> String #

newtype RecSelError #

A record selector was applied to a constructor without the appropriate field. This can only happen with a datatype with multiple constructors, where some fields are in one constructor but not another. The `String` gives information about the source location of the record selector.

Constructors

RecSelError String |

Instances

Show RecSelError | Since: base-4.0
Instance details Defined in Control.Exception.Base Methods showsPrec :: Int -> RecSelError -> ShowS # show :: RecSelError -> String # showList :: [RecSelError] -> ShowS #
Exception RecSelError | Since: base-4.0
Instance details Defined in Control.Exception.Base Methods toException :: RecSelError -> SomeException # fromException :: SomeException -> Maybe RecSelError # displayException :: RecSelError -> String #

newtype RecConError #

An uninitialised record field was used. The `String` gives information about the source location where the record was constructed.

Constructors

RecConError String |

Instances

Show RecConError | Since: base-4.0
Instance details Defined in Control.Exception.Base Methods showsPrec :: Int -> RecConError -> ShowS # show :: RecConError -> String # showList :: [RecConError] -> ShowS #
Exception RecConError | Since: base-4.0
Instance details Defined in Control.Exception.Base Methods toException :: RecConError -> SomeException # fromException :: SomeException -> Maybe RecConError # displayException :: RecConError -> String #

newtype RecUpdError #

A record update was performed on a constructor without the appropriate field. This can only happen with a datatype with multiple constructors, where some fields are in one constructor but not another. The `String` gives information about the source location of the record update.

Constructors

RecUpdError String |

Instances

Show RecUpdError | Since: base-4.0
Instance details Defined in Control.Exception.Base Methods showsPrec :: Int -> RecUpdError -> ShowS # show :: RecUpdError -> String # showList :: [RecUpdError] -> ShowS #
Exception RecUpdError | Since: base-4.0
Instance details Defined in Control.Exception.Base Methods toException :: RecUpdError -> SomeException # fromException :: SomeException -> Maybe RecUpdError # displayException :: RecUpdError -> String #

newtype NoMethodError #

A class method without a definition (neither a default definition, nor a definition in the appropriate instance) was called. The `String` gives information about which method it was.

Constructors

NoMethodError String |

Instances

Show NoMethodError | Since: base-4.0
Instance details Defined in Control.Exception.Base Methods showsPrec :: Int -> NoMethodError -> ShowS # show :: NoMethodError -> String # showList :: [NoMethodError] -> ShowS #
Exception NoMethodError | Since: base-4.0
Instance details Defined in Control.Exception.Base Methods toException :: NoMethodError -> SomeException # fromException :: SomeException -> Maybe NoMethodError # displayException :: NoMethodError -> String #

newtype TypeError #

An expression that didn't typecheck during compile time was called. This is only possible with -fdefer-type-errors. The `String` gives details about the failed type check.

Since: base-4.9.0.0

Constructors

TypeError String |

Instances

Show TypeError | Since: base-4.9.0.0
Instance details Defined in Control.Exception.Base Methods showsPrec :: Int -> TypeError -> ShowS # show :: TypeError -> String # showList :: [TypeError] -> ShowS #
Exception TypeError | Since: base-4.9.0.0
Instance details Defined in Control.Exception.Base Methods toException :: TypeError -> SomeException # fromException :: SomeException -> Maybe TypeError # displayException :: TypeError -> String #

data NonTermination #

Thrown when the runtime system detects that the computation is guaranteed not to terminate. Note that there is no guarantee that the runtime system will notice whether any given computation is guaranteed to terminate or not.

Constructors

NonTermination |

Instances

Show NonTermination | Since: base-4.0
Instance details Defined in Control.Exception.Base Methods showsPrec :: Int -> NonTermination -> ShowS # show :: NonTermination -> String # showList :: [NonTermination] -> ShowS #
Exception NonTermination | Since: base-4.0
Instance details Defined in Control.Exception.Base Methods toException :: NonTermination -> SomeException # fromException :: SomeException -> Maybe NonTermination # displayException :: NonTermination -> String #

data NestedAtomically #

Thrown when the program attempts to call `atomically`, from the `stm` package, inside another call to `atomically`.

Constructors

NestedAtomically |

Instances

Show NestedAtomically | Since: base-4.0
Instance details Defined in Control.Exception.Base Methods showsPrec :: Int -> NestedAtomically -> ShowS # show :: NestedAtomically -> String # showList :: [NestedAtomically] -> ShowS #
Exception NestedAtomically | Since: base-4.0
Instance details Defined in Control.Exception.Base Methods toException :: NestedAtomically -> SomeException # fromException :: SomeException -> Maybe NestedAtomically # displayException :: NestedAtomically -> String #

asyncExceptionFromException :: Exception e => SomeException -> Maybe e #

Since: base-4.7.0.0

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

Since: base-4.7.0.0

data BlockedIndefinitelyOnMVar #

The thread is blocked on an `MVar`, but there are no other references to the `MVar` so it can't ever continue.

Constructors

BlockedIndefinitelyOnMVar |

Instances

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

data BlockedIndefinitelyOnSTM #

The thread is waiting to retry an STM transaction, but there are no other references to any `TVar`s involved, so it can't ever continue.

Constructors

BlockedIndefinitelyOnSTM |

Instances

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

data Deadlock #

There are no runnable threads, so the program is deadlocked. The `Deadlock` exception is raised in the main thread only.

Constructors

Deadlock |

Instances

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

data AllocationLimitExceeded #

This thread has exceeded its allocation limit. See `setAllocationCounter` and `enableAllocationLimit`.

Since: base-4.8.0.0

Constructors

AllocationLimitExceeded |

Instances

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

newtype CompactionFailed #

Compaction found an object that cannot be compacted. Functions cannot be compacted, nor can mutable objects or pinned objects. See `compact`.

Since: base-4.10.0.0

Constructors

CompactionFailed String |

Instances

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

newtype AssertionFailed #

`assert` was applied to `False`.

Constructors

AssertionFailed String |

Instances

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

data SomeAsyncException where #

Superclass for asynchronous exceptions.

Since: base-4.7.0.0

Constructors

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

Instances

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

data AsyncException #

Asynchronous exceptions.

Constructors

StackOverflow | The current thread's stack exceeded its limit. Since an exception has been raised, the thread's stack will certainly be below its limit again, but the programmer should take remedial action immediately.
HeapOverflow | The program's heap is reaching its limit, and the program should take action to reduce the amount of live data it has. Notes: It is undefined which thread receives this exception. GHC currently throws this to the same thread that receives `UserInterrupt`, but this may change in the future. The GHC RTS currently can only recover from heap overflow if it detects that an explicit memory limit (set via RTS flags). has been exceeded. Currently, failure to allocate memory from the operating system results in immediate termination of the program.
ThreadKilled | This exception is raised by another thread calling `killThread`, or by the system if it needs to terminate the thread for some reason.
UserInterrupt | This exception is raised by default in the main thread of the program when the user requests to terminate the program via the usual mechanism(s) (e.g. Control-C in the console).

Instances

Eq AsyncException | Since: base-4.2.0.0
Instance details Defined in GHC.IO.Exception Methods (==) :: AsyncException -> AsyncException -> Bool # (/=) :: AsyncException -> AsyncException -> Bool #
Ord AsyncException | Since: base-4.2.0.0
Instance details Defined in GHC.IO.Exception Methods compare :: AsyncException -> AsyncException -> Ordering # (<) :: AsyncException -> AsyncException -> Bool # (<=) :: AsyncException -> AsyncException -> Bool # (>) :: AsyncException -> AsyncException -> Bool # (>=) :: AsyncException -> AsyncException -> Bool # max :: AsyncException -> AsyncException -> AsyncException # min :: AsyncException -> AsyncException -> AsyncException #
Show AsyncException | Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods showsPrec :: Int -> AsyncException -> ShowS # show :: AsyncException -> String # showList :: [AsyncException] -> ShowS #
Exception AsyncException | Since: base-4.7.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: AsyncException -> SomeException # fromException :: SomeException -> Maybe AsyncException # displayException :: AsyncException -> String #

data ArrayException #

Exceptions generated by array operations

Constructors

IndexOutOfBounds String | An attempt was made to index an array outside its declared bounds.
UndefinedElement String | An attempt was made to evaluate an element of an array that had not been initialized.

Instances

Eq ArrayException | Since: base-4.2.0.0
Instance details Defined in GHC.IO.Exception Methods (==) :: ArrayException -> ArrayException -> Bool # (/=) :: ArrayException -> ArrayException -> Bool #
Ord ArrayException | Since: base-4.2.0.0
Instance details Defined in GHC.IO.Exception Methods compare :: ArrayException -> ArrayException -> Ordering # (<) :: ArrayException -> ArrayException -> Bool # (<=) :: ArrayException -> ArrayException -> Bool # (>) :: ArrayException -> ArrayException -> Bool # (>=) :: ArrayException -> ArrayException -> Bool # max :: ArrayException -> ArrayException -> ArrayException # min :: ArrayException -> ArrayException -> ArrayException #
Show ArrayException | Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods showsPrec :: Int -> ArrayException -> ShowS # show :: ArrayException -> String # showList :: [ArrayException] -> ShowS #
Exception ArrayException | Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: ArrayException -> SomeException # fromException :: SomeException -> Maybe ArrayException # displayException :: ArrayException -> String #

interruptible :: IO a -> IO a #

Allow asynchronous exceptions to be raised even inside `mask`, making the operation interruptible (see the discussion of "Interruptible operations" in `Exception`).

When called outside `mask`, or inside `uninterruptibleMask`, this function has no effect.

Since: base-4.9.0.0

data MaskingState #

Describes the behaviour of a thread when an asynchronous exception is received.

Constructors

Unmasked | asynchronous exceptions are unmasked (the normal state)
MaskedInterruptible | the state during `mask`: asynchronous exceptions are masked, but blocking operations may still be interrupted
MaskedUninterruptible | the state during `uninterruptibleMask`: asynchronous exceptions are masked, and blocking operations may not be interrupted

Instances

Eq MaskingState | Since: base-4.3.0.0
Instance details Defined in GHC.IO Methods (==) :: MaskingState -> MaskingState -> Bool # (/=) :: MaskingState -> MaskingState -> Bool #
Show MaskingState | Since: base-4.3.0.0
Instance details Defined in GHC.IO Methods showsPrec :: Int -> MaskingState -> ShowS # show :: MaskingState -> String # showList :: [MaskingState] -> ShowS #

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 | Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods (==) :: IOException -> IOException -> Bool # (/=) :: IOException -> IOException -> Bool #
Show IOException | Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods showsPrec :: Int -> IOException -> ShowS # show :: IOException -> String # showList :: [IOException] -> ShowS #
Exception IOException | Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: IOException -> SomeException # fromException :: SomeException -> Maybe IOException # displayException :: IOException -> String #
Error IOException |
Instance details Defined in Control.Monad.Trans.Error Methods noMsg :: IOException # strMsg :: String -> IOException #

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

Throw an exception. Exceptions may be thrown from purely functional code, but may only be caught within the `IO` monad.

data ErrorCall #

This is thrown when the user calls `error`. The first `String` is the argument given to `error`, second `String` is the location.

Constructors

ErrorCallWithLocation String String |

Bundled Patterns

pattern ErrorCall :: String -> ErrorCall |

Instances

Eq ErrorCall | Since: base-4.7.0.0
Instance details Defined in GHC.Exception Methods (==) :: ErrorCall -> ErrorCall -> Bool # (/=) :: ErrorCall -> ErrorCall -> Bool #
Ord ErrorCall | Since: base-4.7.0.0
Instance details Defined in GHC.Exception Methods compare :: ErrorCall -> ErrorCall -> Ordering # (<) :: ErrorCall -> ErrorCall -> Bool # (<=) :: ErrorCall -> ErrorCall -> Bool # (>) :: ErrorCall -> ErrorCall -> Bool # (>=) :: ErrorCall -> ErrorCall -> Bool # max :: ErrorCall -> ErrorCall -> ErrorCall # min :: ErrorCall -> ErrorCall -> ErrorCall #
Show ErrorCall | Since: base-4.0.0.0
Instance details Defined in GHC.Exception Methods showsPrec :: Int -> ErrorCall -> ShowS # show :: ErrorCall -> String # showList :: [ErrorCall] -> ShowS #
Exception ErrorCall | Since: base-4.0.0.0
Instance details Defined in GHC.Exception Methods toException :: ErrorCall -> SomeException # fromException :: SomeException -> Maybe ErrorCall # displayException :: ErrorCall -> String #

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

    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 #

fromException :: SomeException -> Maybe e #

displayException :: e -> String #

Render this exception value in a human-friendly manner.

Default implementation: ``show``.

Since: base-4.8.0.0

Instances

Exception PatternMatchFail | Since: base-4.0
Instance details Defined in Control.Exception.Base Methods toException :: PatternMatchFail -> SomeException # fromException :: SomeException -> Maybe PatternMatchFail # displayException :: PatternMatchFail -> String #
Exception RecSelError | Since: base-4.0
Instance details Defined in Control.Exception.Base Methods toException :: RecSelError -> SomeException # fromException :: SomeException -> Maybe RecSelError # displayException :: RecSelError -> String #
Exception RecConError | Since: base-4.0
Instance details Defined in Control.Exception.Base Methods toException :: RecConError -> SomeException # fromException :: SomeException -> Maybe RecConError # displayException :: RecConError -> String #
Exception RecUpdError | Since: base-4.0
Instance details Defined in Control.Exception.Base Methods toException :: RecUpdError -> SomeException # fromException :: SomeException -> Maybe RecUpdError # displayException :: RecUpdError -> String #
Exception NoMethodError | Since: base-4.0
Instance details Defined in Control.Exception.Base Methods toException :: NoMethodError -> SomeException # fromException :: SomeException -> Maybe NoMethodError # displayException :: NoMethodError -> String #
Exception TypeError | Since: base-4.9.0.0
Instance details Defined in Control.Exception.Base Methods toException :: TypeError -> SomeException # fromException :: SomeException -> Maybe TypeError # displayException :: TypeError -> String #
Exception NonTermination | Since: base-4.0
Instance details Defined in Control.Exception.Base Methods toException :: NonTermination -> SomeException # fromException :: SomeException -> Maybe NonTermination # displayException :: NonTermination -> String #
Exception NestedAtomically | Since: base-4.0
Instance details Defined in Control.Exception.Base Methods toException :: NestedAtomically -> SomeException # fromException :: SomeException -> Maybe NestedAtomically # displayException :: NestedAtomically -> String #
Exception BlockedIndefinitelyOnMVar | Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: BlockedIndefinitelyOnMVar -> SomeException # fromException :: SomeException -> Maybe BlockedIndefinitelyOnMVar # displayException :: BlockedIndefinitelyOnMVar -> String #
Exception BlockedIndefinitelyOnSTM | Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: BlockedIndefinitelyOnSTM -> SomeException # fromException :: SomeException -> Maybe BlockedIndefinitelyOnSTM # displayException :: BlockedIndefinitelyOnSTM -> String #
Exception Deadlock | Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: Deadlock -> SomeException # fromException :: SomeException -> Maybe Deadlock # displayException :: Deadlock -> String #
Exception AllocationLimitExceeded | Since: base-4.8.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: AllocationLimitExceeded -> SomeException # fromException :: SomeException -> Maybe AllocationLimitExceeded # displayException :: AllocationLimitExceeded -> String #
Exception CompactionFailed | Since: base-4.10.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: CompactionFailed -> SomeException # fromException :: SomeException -> Maybe CompactionFailed # displayException :: CompactionFailed -> String #
Exception AssertionFailed | Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: AssertionFailed -> SomeException # fromException :: SomeException -> Maybe AssertionFailed # displayException :: AssertionFailed -> String #
Exception SomeAsyncException | Since: base-4.7.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: SomeAsyncException -> SomeException # fromException :: SomeException -> Maybe SomeAsyncException # displayException :: SomeAsyncException -> String #
Exception AsyncException | Since: base-4.7.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: AsyncException -> SomeException # fromException :: SomeException -> Maybe AsyncException # displayException :: AsyncException -> String #
Exception ArrayException | Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: ArrayException -> SomeException # fromException :: SomeException -> Maybe ArrayException # displayException :: ArrayException -> String #
Exception FixIOException | Since: base-4.11.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: FixIOException -> SomeException # fromException :: SomeException -> Maybe FixIOException # displayException :: FixIOException -> String #
Exception ExitCode | Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: ExitCode -> SomeException # fromException :: SomeException -> Maybe ExitCode # displayException :: ExitCode -> String #
Exception IOException | Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: IOException -> SomeException # fromException :: SomeException -> Maybe IOException # displayException :: IOException -> String #
Exception ErrorCall | Since: base-4.0.0.0
Instance details Defined in GHC.Exception Methods toException :: ErrorCall -> SomeException # fromException :: SomeException -> Maybe ErrorCall # displayException :: ErrorCall -> String #
Exception ArithException | Since: base-4.0.0.0
Instance details Defined in GHC.Exception.Type Methods toException :: ArithException -> SomeException # fromException :: SomeException -> Maybe ArithException # displayException :: ArithException -> String #
Exception SomeException | Since: base-3.0
Instance details Defined in GHC.Exception.Type Methods toException :: SomeException -> SomeException # fromException :: SomeException -> Maybe SomeException # displayException :: SomeException -> String #
Exception Timeout | Since: base-4.7.0.0
Instance details Defined in System.Timeout Methods toException :: Timeout -> SomeException # fromException :: SomeException -> Maybe Timeout # displayException :: Timeout -> String #

data ArithException #

Arithmetic exceptions.

Constructors

Overflow |
Underflow |
LossOfPrecision |
DivideByZero |
Denormal |
RatioZeroDenominator | Since: base-4.6.0.0

Instances

Eq ArithException | Since: base-3.0
Instance details Defined in GHC.Exception.Type Methods (==) :: ArithException -> ArithException -> Bool # (/=) :: ArithException -> ArithException -> Bool #
Ord ArithException | Since: base-3.0
Instance details Defined in GHC.Exception.Type Methods compare :: ArithException -> ArithException -> Ordering # (<) :: ArithException -> ArithException -> Bool # (<=) :: ArithException -> ArithException -> Bool # (>) :: ArithException -> ArithException -> Bool # (>=) :: ArithException -> ArithException -> Bool # max :: ArithException -> ArithException -> ArithException # min :: ArithException -> ArithException -> ArithException #
Show ArithException | Since: base-4.0.0.0
Instance details Defined in GHC.Exception.Type Methods showsPrec :: Int -> ArithException -> ShowS # show :: ArithException -> String # showList :: [ArithException] -> ShowS #
Exception ArithException | Since: base-4.0.0.0
Instance details Defined in GHC.Exception.Type Methods toException :: ArithException -> SomeException # fromException :: SomeException -> Maybe ArithException # displayException :: ArithException -> String #

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 :: 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 # show :: SomeException -> String # showList :: [SomeException] -> ShowS #
Exception SomeException | Since: base-3.0
Instance details Defined in GHC.Exception.Type Methods toException :: SomeException -> SomeException # fromException :: SomeException -> Maybe SomeException # displayException :: SomeException -> String #

# Throwing exceptions

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

Generalized version of `throwIO`.

ioError :: MonadBase IO m => IOError -> m a #

Generalized version of `ioError`.

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

Generalized version of `throwTo`.

# Catching exceptions

## The `catch` functions

catch #

Arguments

:: (MonadBaseControl IO m, Exception e) |
=> m a | The computation to run
-> (e -> m a) | Handler to invoke if an exception is raised
-> m a |

Generalized version of `catch`.

Note, when the given computation throws an exception any monadic side effects in `m` will be discarded.

catches :: MonadBaseControl IO m => m a -> [Handler m a] -> m a #

Generalized version of `catches`.

Note, when the given computation throws an exception any monadic side effects in `m` will be discarded.

data Handler m a #

Generalized version of `Handler`.

Constructors

Exception e => Handler (e -> m a) |

catchJust #

Arguments

:: (MonadBaseControl IO m, Exception e) |
=> (e -> Maybe b) | Predicate to select exceptions
-> m a | Computation to run
-> (b -> m a) | Handler
-> m a |

Generalized version of `catchJust`.

Note, when the given computation throws an exception any monadic side effects in `m` will be discarded.

## The `handle` functions

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

Generalized version of `handle`.

Note, when the given computation throws an exception any monadic side effects in `m` will be discarded.

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

Generalized version of `handleJust`.

Note, when the given computation throws an exception any monadic side effects in `m` will be discarded.

## The `try` functions

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

Generalized version of `try`.

Note, when the given computation throws an exception any monadic side effects in `m` will be discarded.

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

Generalized version of `tryJust`.

Note, when the given computation throws an exception any monadic side effects in `m` will be discarded.

## The `evaluate` function

evaluate :: MonadBase IO m => a -> m a #

Generalized version of `evaluate`.

# Asynchronous Exceptions

## Asynchronous exception control

The following functions allow a thread to control delivery of asynchronous exceptions during a critical region.

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

Generalized version of `mask`.

mask_ :: MonadBaseControl IO m => m a -> m a #

Generalized version of `mask_`.

uninterruptibleMask :: MonadBaseControl IO m => ((forall a. m a -> m a) -> m b) -> m b #

Generalized version of `uninterruptibleMask`.

uninterruptibleMask_ :: MonadBaseControl IO m => m a -> m a #

Generalized version of `uninterruptibleMask_`.

getMaskingState :: MonadBase IO m => m MaskingState #

Generalized version of `getMaskingState`.

allowInterrupt :: MonadBase IO m => m () #

Generalized version of `allowInterrupt`.

# Brackets

bracket #

Arguments

:: MonadBaseControl IO m |
=> m a | computation to run first ("acquire resource")
-> (a -> m b) | computation to run last ("release resource")
-> (a -> m c) | computation to run in-between
-> m c |

Generalized version of `bracket`.

Note:

- When the "acquire" or "release" computations throw exceptions any monadic side effects in `m` will be discarded.
- When the "in-between" computation throws an exception any monadic side effects in `m` produced by that computation will be discarded but the side effects of the "acquire" or "release" computations will be retained.
- Also, any monadic side effects in `m` of the "release" computation will be discarded; it is run only for its side effects in `IO`.

Note that when your `acquire` and `release` computations are of type `IO` it will be more efficient to write:

    liftBaseOp (bracket acquire release)

bracket_ #

Arguments

:: MonadBaseControl IO m |
=> m a | computation to run first ("acquire resource")
-> m b | computation to run last ("release resource")
-> m c | computation to run in-between
-> m c |

Generalized version of `bracket_`.

Note any monadic side effects in `m` of both the "acquire" and "release" computations will be discarded. To keep the monadic side effects of the "acquire" computation, use `bracket` with constant functions instead.

Note that when your `acquire` and `release` computations are of type `IO` it will be more efficient to write:

    liftBaseOp_ (bracket_ acquire release)

bracketOnError #

Arguments

:: MonadBaseControl IO m |
=> m a | computation to run first ("acquire resource")
-> (a -> m b) | computation to run last ("release resource")
-> (a -> m c) | computation to run in-between
-> m c |

Generalized version of `bracketOnError`.

Note:

- When the "acquire" or "release" computations throw exceptions any monadic side effects in `m` will be discarded.
- When the "in-between" computation throws an exception any monadic side effects in `m` produced by that computation will be discarded but the side effects of the "acquire" computation will be retained.
- Also, any monadic side effects in `m` of the "release" computation will be discarded; it is run only for its side effects in `IO`.

Note that when your `acquire` and `release` computations are of type `IO` it will be more efficient to write:

    liftBaseOp (bracketOnError acquire release)

# Utilities

finally #

Arguments

:: MonadBaseControl IO m |
=> m a | computation to run first
-> m b | computation to run afterward (even if an exception was raised)
-> m a |

Generalized version of `finally`.

Note, any monadic side effects in `m` of the "afterward" computation will be discarded.

onException :: MonadBaseControl IO m => m a -> m b -> m a #

Generalized version of `onException`.

Note, any monadic side effects in `m` of the "afterward" computation will be discarded.