Control.Exception.Lifted

lifted-base-0.2.3.12: 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 | Safe
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

- data BlockedIndefinitelyOnMVar = BlockedIndefinitelyOnMVar
- assert :: Bool -> a -> a
- newtype TypeError = TypeError String
- data SomeException = (Exception e, HasExceptionContext) => SomeException e
- data ArithException
  - = Overflow
  - | Underflow
  - | LossOfPrecision
  - | DivideByZero
  - | Denormal
  - | RatioZeroDenominator
- data ExceptionWithContext a = ExceptionWithContext ExceptionContext a
- class (Typeable e, Show e) => Exception e where
  - toException :: e -> SomeException
  - fromException :: SomeException -> Maybe e
  - displayException :: e -> String
  - backtraceDesired :: e -> Bool
- someExceptionContext :: SomeException -> ExceptionContext
- addExceptionContext :: ExceptionAnnotation a => a -> SomeException -> SomeException
- data ErrorCall where
  - ErrorCallWithLocation String String
  - pattern ErrorCall :: String -> ErrorCall
- throw :: forall a e. (?callStack :: CallStack, Exception e) => e -> a
- data IOException
- data MaskingState
  - = Unmasked
  - | MaskedInterruptible
  - | MaskedUninterruptible
- annotateIO :: ExceptionAnnotation e => e -> IO a -> IO a
- interruptible :: IO a -> IO a
- data ArrayException
  - = IndexOutOfBounds String
  - | UndefinedElement String
- data AsyncException
  - = StackOverflow
  - | HeapOverflow
  - | ThreadKilled
  - | UserInterrupt
- data SomeAsyncException = Exception e => SomeAsyncException e
- newtype AssertionFailed = AssertionFailed String
- newtype CompactionFailed = CompactionFailed String
- data AllocationLimitExceeded = AllocationLimitExceeded
- data Deadlock = Deadlock
- data BlockedIndefinitelyOnSTM = BlockedIndefinitelyOnSTM
- asyncExceptionToException :: Exception e => e -> SomeException
- asyncExceptionFromException :: Exception e => SomeException -> Maybe e
- data NestedAtomically = NestedAtomically
- data NonTermination = NonTermination
- newtype NoMethodError = NoMethodError String
- newtype RecUpdError = RecUpdError String
- newtype RecConError = RecConError String
- newtype RecSelError = RecSelError String
- newtype PatternMatchFail = PatternMatchFail String
- mapException :: (Exception e1, Exception e2) => (e1 -> e2) -> a -> a
- 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 :: Type -> Type) 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

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

Instances details

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

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.

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

Instances details

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

data SomeException #

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

(Exception e, HasExceptionContext) => SomeException e |

#### Instances

Instances details

Exception SomeException | This drops any attached `ExceptionContext`. @since base-3.0
Instance details Defined in GHC.Internal.Exception.Type Methods toException :: SomeException -> SomeException # fromException :: SomeException -> Maybe SomeException # displayException :: SomeException -> String # backtraceDesired :: SomeException -> Bool #
Show SomeException | Since: ghc-internal-3.0
Instance details Defined in GHC.Internal.Exception.Type Methods showsPrec :: Int -> SomeException -> ShowS # show :: SomeException -> String # showList :: [SomeException] -> ShowS #

data ArithException #

Arithmetic exceptions.

Constructors

Overflow |
Underflow |
LossOfPrecision |
DivideByZero |
Denormal |
RatioZeroDenominator | @since base-4.6.0.0

#### Instances

Instances details

Exception ArithException | @since base-4.0.0.0
Instance details Defined in GHC.Internal.Exception.Type Methods toException :: ArithException -> SomeException # fromException :: SomeException -> Maybe ArithException # displayException :: ArithException -> String # backtraceDesired :: ArithException -> Bool #
Show ArithException | @since base-4.0.0.0
Instance details Defined in GHC.Internal.Exception.Type Methods showsPrec :: Int -> ArithException -> ShowS # show :: ArithException -> String # showList :: [ArithException] -> ShowS #
Eq ArithException | @since base-3.0
Instance details Defined in GHC.Internal.Exception.Type Methods (==) :: ArithException -> ArithException -> Bool # (/=) :: ArithException -> ArithException -> Bool #
Ord ArithException | @since base-3.0
Instance details Defined in GHC.Internal.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 #

data ExceptionWithContext a #

Wraps a particular exception exposing its `ExceptionContext`. Intended to be used when `catch`ing exceptions in cases where access to the context is desired.

Constructors

ExceptionWithContext ExceptionContext a |

#### Instances

Instances details

Exception a => Exception (ExceptionWithContext a) |
Instance details Defined in GHC.Internal.Exception.Type Methods toException :: ExceptionWithContext a -> SomeException # fromException :: SomeException -> Maybe (ExceptionWithContext a) # displayException :: ExceptionWithContext a -> String # backtraceDesired :: ExceptionWithContext a -> Bool #
Show a => Show (ExceptionWithContext a) |
Instance details Defined in GHC.Internal.Exception.Type Methods showsPrec :: Int -> ExceptionWithContext a -> ShowS # show :: ExceptionWithContext a -> String # showList :: [ExceptionWithContext a] -> ShowS #

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 #

`toException` should produce a `SomeException` with no attached `ExceptionContext`.

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

backtraceDesired :: e -> Bool #

#### Instances

Instances details

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 # backtraceDesired :: Timeout -> Bool #
Exception Void | @since base-4.8.0.0
Instance details Defined in GHC.Internal.Exception.Type Methods toException :: Void -> SomeException # fromException :: SomeException -> Maybe Void # displayException :: Void -> String # backtraceDesired :: Void -> Bool #
Exception NestedAtomically | @since base-4.0
Instance details Defined in GHC.Internal.Control.Exception.Base Methods toException :: NestedAtomically -> SomeException # fromException :: SomeException -> Maybe NestedAtomically # displayException :: NestedAtomically -> String # backtraceDesired :: NestedAtomically -> Bool #
Exception NoMatchingContinuationPrompt | @since base-4.18
Instance details Defined in GHC.Internal.Control.Exception.Base Methods toException :: NoMatchingContinuationPrompt -> SomeException # fromException :: SomeException -> Maybe NoMatchingContinuationPrompt # displayException :: NoMatchingContinuationPrompt -> String # backtraceDesired :: NoMatchingContinuationPrompt -> Bool #
Exception NoMethodError | @since base-4.0
Instance details Defined in GHC.Internal.Control.Exception.Base Methods toException :: NoMethodError -> SomeException # fromException :: SomeException -> Maybe NoMethodError # displayException :: NoMethodError -> String # backtraceDesired :: NoMethodError -> Bool #
Exception NonTermination | @since base-4.0
Instance details Defined in GHC.Internal.Control.Exception.Base Methods toException :: NonTermination -> SomeException # fromException :: SomeException -> Maybe NonTermination # displayException :: NonTermination -> String # backtraceDesired :: NonTermination -> Bool #
Exception PatternMatchFail | @since base-4.0
Instance details Defined in GHC.Internal.Control.Exception.Base Methods toException :: PatternMatchFail -> SomeException # fromException :: SomeException -> Maybe PatternMatchFail # displayException :: PatternMatchFail -> String # backtraceDesired :: PatternMatchFail -> Bool #
Exception RecConError | @since base-4.0
Instance details Defined in GHC.Internal.Control.Exception.Base Methods toException :: RecConError -> SomeException # fromException :: SomeException -> Maybe RecConError # displayException :: RecConError -> String # backtraceDesired :: RecConError -> Bool #
Exception RecSelError | @since base-4.0
Instance details Defined in GHC.Internal.Control.Exception.Base Methods toException :: RecSelError -> SomeException # fromException :: SomeException -> Maybe RecSelError # displayException :: RecSelError -> String # backtraceDesired :: RecSelError -> Bool #
Exception RecUpdError | @since base-4.0
Instance details Defined in GHC.Internal.Control.Exception.Base Methods toException :: RecUpdError -> SomeException # fromException :: SomeException -> Maybe RecUpdError # displayException :: RecUpdError -> String # backtraceDesired :: RecUpdError -> Bool #
Exception TypeError | @since base-4.9.0.0
Instance details Defined in GHC.Internal.Control.Exception.Base Methods toException :: TypeError -> SomeException # fromException :: SomeException -> Maybe TypeError # displayException :: TypeError -> String # backtraceDesired :: TypeError -> Bool #
Exception ErrorCall | @since base-4.0.0.0
Instance details Defined in GHC.Internal.Exception Methods toException :: ErrorCall -> SomeException # fromException :: SomeException -> Maybe ErrorCall # displayException :: ErrorCall -> String # backtraceDesired :: ErrorCall -> Bool #
Exception ArithException | @since base-4.0.0.0
Instance details Defined in GHC.Internal.Exception.Type Methods toException :: ArithException -> SomeException # fromException :: SomeException -> Maybe ArithException # displayException :: ArithException -> String # backtraceDesired :: ArithException -> Bool #
Exception SomeException | This drops any attached `ExceptionContext`. @since base-3.0
Instance details Defined in GHC.Internal.Exception.Type Methods toException :: SomeException -> SomeException # fromException :: SomeException -> Maybe SomeException # displayException :: SomeException -> String # backtraceDesired :: SomeException -> Bool #
Exception AllocationLimitExceeded | @since base-4.8.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: AllocationLimitExceeded -> SomeException # fromException :: SomeException -> Maybe AllocationLimitExceeded # displayException :: AllocationLimitExceeded -> String # backtraceDesired :: AllocationLimitExceeded -> Bool #
Exception ArrayException | @since base-4.1.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: ArrayException -> SomeException # fromException :: SomeException -> Maybe ArrayException # displayException :: ArrayException -> String # backtraceDesired :: ArrayException -> Bool #
Exception AssertionFailed | @since base-4.1.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: AssertionFailed -> SomeException # fromException :: SomeException -> Maybe AssertionFailed # displayException :: AssertionFailed -> String # backtraceDesired :: AssertionFailed -> Bool #
Exception AsyncException | @since base-4.7.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: AsyncException -> SomeException # fromException :: SomeException -> Maybe AsyncException # displayException :: AsyncException -> String # backtraceDesired :: AsyncException -> Bool #
Exception BlockedIndefinitelyOnMVar | @since base-4.1.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: BlockedIndefinitelyOnMVar -> SomeException # fromException :: SomeException -> Maybe BlockedIndefinitelyOnMVar # displayException :: BlockedIndefinitelyOnMVar -> String # backtraceDesired :: BlockedIndefinitelyOnMVar -> Bool #
Exception BlockedIndefinitelyOnSTM | @since base-4.1.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: BlockedIndefinitelyOnSTM -> SomeException # fromException :: SomeException -> Maybe BlockedIndefinitelyOnSTM # displayException :: BlockedIndefinitelyOnSTM -> String # backtraceDesired :: BlockedIndefinitelyOnSTM -> Bool #
Exception CompactionFailed | @since base-4.10.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: CompactionFailed -> SomeException # fromException :: SomeException -> Maybe CompactionFailed # displayException :: CompactionFailed -> String # backtraceDesired :: CompactionFailed -> Bool #
Exception Deadlock | @since base-4.1.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: Deadlock -> SomeException # fromException :: SomeException -> Maybe Deadlock # displayException :: Deadlock -> String # backtraceDesired :: Deadlock -> Bool #
Exception ExitCode | @since base-4.1.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: ExitCode -> SomeException # fromException :: SomeException -> Maybe ExitCode # displayException :: ExitCode -> String # backtraceDesired :: ExitCode -> Bool #
Exception FixIOException | @since base-4.11.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: FixIOException -> SomeException # fromException :: SomeException -> Maybe FixIOException # displayException :: FixIOException -> String # backtraceDesired :: FixIOException -> Bool #
Exception IOException | @since base-4.1.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: IOException -> SomeException # fromException :: SomeException -> Maybe IOException # displayException :: IOException -> String # backtraceDesired :: IOException -> Bool #
Exception SomeAsyncException | @since base-4.7.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: SomeAsyncException -> SomeException # fromException :: SomeException -> Maybe SomeAsyncException # displayException :: SomeAsyncException -> String # backtraceDesired :: SomeAsyncException -> Bool #
Exception a => Exception (ExceptionWithContext a) |
Instance details Defined in GHC.Internal.Exception.Type Methods toException :: ExceptionWithContext a -> SomeException # fromException :: SomeException -> Maybe (ExceptionWithContext a) # displayException :: ExceptionWithContext a -> String # backtraceDesired :: ExceptionWithContext a -> Bool #
Exception e => Exception (NoBacktrace e) |
Instance details Defined in GHC.Internal.Exception.Type Methods toException :: NoBacktrace e -> SomeException # fromException :: SomeException -> Maybe (NoBacktrace e) # displayException :: NoBacktrace e -> String # backtraceDesired :: NoBacktrace e -> Bool #

someExceptionContext :: SomeException -> ExceptionContext #

View the `ExceptionContext` of a `SomeException`.

addExceptionContext :: ExceptionAnnotation a => a -> SomeException -> SomeException #

Add more `ExceptionContext` to a `SomeException`.

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

Instances details

Exception ErrorCall | @since base-4.0.0.0
Instance details Defined in GHC.Internal.Exception Methods toException :: ErrorCall -> SomeException # fromException :: SomeException -> Maybe ErrorCall # displayException :: ErrorCall -> String # backtraceDesired :: ErrorCall -> Bool #
Show ErrorCall | @since base-4.0.0.0
Instance details Defined in GHC.Internal.Exception Methods showsPrec :: Int -> ErrorCall -> ShowS # show :: ErrorCall -> String # showList :: [ErrorCall] -> ShowS #
Eq ErrorCall | @since base-4.7.0.0
Instance details Defined in GHC.Internal.Exception Methods (==) :: ErrorCall -> ErrorCall -> Bool # (/=) :: ErrorCall -> ErrorCall -> Bool #
Ord ErrorCall | @since base-4.7.0.0
Instance details Defined in GHC.Internal.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 #

throw :: forall a e. (?callStack :: CallStack, Exception e) => e -> a #

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

WARNING: You may want to use `throwIO` instead so that your pure code stays exception-free.

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

Instances details

Exception IOException | @since base-4.1.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: IOException -> SomeException # fromException :: SomeException -> Maybe IOException # displayException :: IOException -> String # backtraceDesired :: IOException -> Bool #
Show IOException | @since base-4.1.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods showsPrec :: Int -> IOException -> ShowS # show :: IOException -> String # showList :: [IOException] -> ShowS #
Eq IOException | @since base-4.1.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods (==) :: IOException -> IOException -> Bool # (/=) :: IOException -> IOException -> Bool #

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

Instances details

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

annotateIO :: ExceptionAnnotation e => e -> IO a -> IO a #

Execute an `IO` action, adding the given `ExceptionContext` to any thrown synchronous exceptions.

@since base-2.20.0.0

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

Instances details

Exception ArrayException | @since base-4.1.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: ArrayException -> SomeException # fromException :: SomeException -> Maybe ArrayException # displayException :: ArrayException -> String # backtraceDesired :: ArrayException -> Bool #
Show ArrayException | @since base-4.1.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods showsPrec :: Int -> ArrayException -> ShowS # show :: ArrayException -> String # showList :: [ArrayException] -> ShowS #
Eq ArrayException | @since base-4.2.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods (==) :: ArrayException -> ArrayException -> Bool # (/=) :: ArrayException -> ArrayException -> Bool #
Ord ArrayException | @since base-4.2.0.0
Instance details Defined in GHC.Internal.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 #

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

Instances details

Exception AsyncException | @since base-4.7.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: AsyncException -> SomeException # fromException :: SomeException -> Maybe AsyncException # displayException :: AsyncException -> String # backtraceDesired :: AsyncException -> Bool #
Show AsyncException | @since base-4.1.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods showsPrec :: Int -> AsyncException -> ShowS # show :: AsyncException -> String # showList :: [AsyncException] -> ShowS #
Eq AsyncException | @since base-4.2.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods (==) :: AsyncException -> AsyncException -> Bool # (/=) :: AsyncException -> AsyncException -> Bool #
Ord AsyncException | @since base-4.2.0.0
Instance details Defined in GHC.Internal.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 #

data SomeAsyncException #

Superclass for asynchronous exceptions.

@since base-4.7.0.0

Constructors

Exception e => SomeAsyncException e |

#### Instances

Instances details

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

newtype AssertionFailed #

`assert` was applied to `False`.

Constructors

AssertionFailed String |

#### Instances

Instances details

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

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

Instances details

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

data AllocationLimitExceeded #

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

@since base-4.8.0.0

Constructors

AllocationLimitExceeded |

#### Instances

Instances details

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

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

Instances details

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

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

Instances details

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

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

@since base-4.7.0.0

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

@since base-4.7.0.0

data NestedAtomically #

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

Constructors

NestedAtomically |

#### Instances

Instances details

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

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

Instances details

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

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

Instances details

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

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

Instances details

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

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

Instances details

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

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

Instances details

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

newtype PatternMatchFail #

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

Constructors

PatternMatchFail String |

#### Instances

Instances details

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

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

# 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 :: Type -> Type) 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.