Control.Monad.Exception.IO

A monad transformer for explicitly typed checked exceptions with support for asynchronous exception handling. Explicit exceptions are supported by the ideas described in:

• Jose Iborra, "Explicitly Typed Exceptions for Haskell", PADL'10, January 2010, http://dl.dropbox.com/s/lgm12trtl0swtra/PADL10.pdf?dl=1

The exceptions thrown by a computation are inferred by the typechecker and appear in the type signature of the computation as Throws constraints.

Support for asynchronous exceptions is provided by the monad-control package.

Example

data DivideByZero = DivideByZero deriving (Show, Typeable)
data SumOverflow  = SumOverflow  deriving (Show, Typeable)

instance Exception DivideByZero
instance Exception SumOverflow

data Expr = Add Expr Expr | Div Expr Expr | Val Double

eval (Val x)     = return x
eval (Add a1 a2) = do
   v1 <- eval a1
   v2 <- eval a2
   let sum = v1 + v2
   if sum < v1 || sum < v2 then throw SumOverflow else return sum
eval (Div a1 a2) = do
   v1 <- eval a1
   v2 <- eval a2
   if v2 == 0 then throw DivideByZero else return (v1 / v2)

GHCi infers the following types

eval                                             :: (Throws DivideByZero l, Throws SumOverflow l) => Expr -> EM l Double
eval `catch` \ (e::DivideByZero) -> return (-1)  :: Throws SumOverflow l => Expr -> EM l Double
runEM(eval `catch` \ (e::SomeException) -> return (-1))
                                                 :: Expr -> Double

Important trivia

Hierarchies of Exceptions

If exceptions are hierarchical then you need to teach Throws about the hierarchy. See the documentation of Throws for more info.

Unchecked exceptions

Unchecked exceptions

An exception E can be declared as unchecked by making E an instance of UncaughtException.

instance UncaughtException E

E will still appear in the list of exceptions thrown by a computation but runEMT will not complain if E escapes the computation being run.

Also, tryEMT allows you to run a computation regardless of the exceptions it throws.

Stack Traces

Stack traces are provided via the MonadLoc package. All you need to do is add the following pragma at the top of your Haskell source files and use do-notation:

 { # OPTIONS_GHC -F -pgmF MonadLoc # }

Only statements in do blocks appear in the stack trace.

Example:

      f () = do throw MyException
      g a  = do f a

      main = runEMT $ do
               g () `catchWithSrcLoc`
                       \loc (e::MyException) -> lift(putStrLn$ showExceptionWithTrace loc e)

       -- Running main produces the output:

      *Main> main
      MyException
       in f, Main(example.hs): (1,6)
          g, Main(example.hs): (2,6)
          main, Main(example.hs): (5,9)
          main, Main(example.hs): (4,16)

Understanding GHC errors

A type error of the form:

   No instance for (UncaughtException MyException)
     arising from a use of `g' at examples/docatch.hs:21:32-35
   Possible fix:
     add an instance declaration for (UncaughtException MyException)
   In the expression: g ()

is the type checker saying:

"hey, you are trying to run a computation which throws a MyException without handling it, and I won't let you"

Either handle it or declare MyException as an UncaughtException.

A type error of the form:

   Overlapping instances for Throws MyException (Caught e NoExceptions)
     arising from a use of `g' at docatch.hs:24:3-6
   Matching instances:
     instance (Throws e l) => Throws e (Caught e' l)
       -- Defined at ../Control/Monad/Exception/Throws.hs:46:9-45
     instance (Exception e) => Throws e (Caught e l)
       -- Defined at ../Control/Monad/Exception/Throws.hs:47:9-44
   (The choice depends on the instantiation of `e'
   ...

is due to an exception handler for MyException missing a type annotation to pin down the type of the exception.

The EM monad

type EM l = EMT l Identity

A monad of explicitly typed, checked exceptions

tryEM :: EM AnyException a -> Either SomeException a

Run a computation explicitly handling exceptions

tryEMWithLoc :: EM AnyException a -> Either (CallTrace, SomeException) a

runEM :: EM NoExceptions a -> a

Run a safe computation

runEMParanoid :: EM ParanoidMode a -> a

Run a computation checking even unchecked (UncaughtExceptions) exceptions

The EMT monad transformer

newtype EMT l m a

A Monad Transformer for explicitly typed checked exceptions.

Constructors

EMT

Fields

• unEMT :: m (Either (CallTrace, CheckedException l) a)

Instances

(Exception e, Throws e l, Monad m) => Failure e (EMT l m)

Defined in Control.Monad.Exception.Base

Methods

failure :: e -> EMT l m v

MonadBase b m => MonadBase b (EMT l m)

Defined in Control.Monad.Exception.Base

Methods

liftBase :: b α -> EMT l m α

MonadBaseControl b m => MonadBaseControl b (EMT l m)

Defined in Control.Monad.Exception.Base

Associated Types

type StM (EMT l m) a :: Type

Methods

liftBaseWith :: (RunInBase (EMT l m) b -> b a) -> EMT l m a

restoreM :: StM (EMT l m) a -> EMT l m a

(Exception e, Monad m) => MonadCatch e (EMT (Caught e l) m) (EMT l m)

Defined in Control.Monad.Exception.Pure

Methods

catch :: EMT (Caught e l) m a -> (e -> EMT l m a) -> EMT l m a

catchWithSrcLoc :: EMT (Caught e l) m a -> ([String] -> e -> EMT l m a) -> EMT l m a

(Exception e, MonadBaseControl IO m) => MonadCatch e (EMT (Caught e l) m) (EMT l m)

Defined in Control.Monad.Exception.IO

Methods

catch :: EMT (Caught e l) m a -> (e -> EMT l m a) -> EMT l m a

catchWithSrcLoc :: EMT (Caught e l) m a -> ([String] -> e -> EMT l m a) -> EMT l m a

Throws MonadZeroException l => Alternative (EM l)

Defined in Control.Monad.Exception.Base

Methods

empty :: EM l a

(<|>) :: EM l a -> EM l a -> EM l a

some :: EM l a -> EM l [a]

many :: EM l a -> EM l [a]

Throws MonadZeroException l => MonadPlus (EM l)

Defined in Control.Monad.Exception.Base

Methods

mzero :: EM l a

mplus :: EM l a -> EM l a -> EM l a

MonadTrans (EMT l)

Defined in Control.Monad.Exception.Base

Methods

lift :: Monad m => m a -> EMT l m a

MonadTransControl (EMT l)

Defined in Control.Monad.Exception.Base

Associated Types

type StT (EMT l) a :: Type

Methods

liftWith :: Monad m => (Run (EMT l) -> m a) -> EMT l m a

restoreT :: Monad m => m (StT (EMT l) a) -> EMT l m a

Monad m => Monad (EMT l m)

Defined in Control.Monad.Exception.Base

Methods

(>>=) :: EMT l m a -> (a -> EMT l m b) -> EMT l m b

(>>) :: EMT l m a -> EMT l m b -> EMT l m b

return :: a -> EMT l m a

fail :: String -> EMT l m a

Monad m => Functor (EMT l m)

Defined in Control.Monad.Exception.Base

Methods

fmap :: (a -> b) -> EMT l m a -> EMT l m b

(<$) :: a -> EMT l m b -> EMT l m a

MonadFix m => MonadFix (EMT l m)

Defined in Control.Monad.Exception.Base

Methods

mfix :: (a -> EMT l m a) -> EMT l m a

Monad m => MonadFail (EMT l m)

Defined in Control.Monad.Exception.Base

Methods

fail :: String -> EMT l m a

Monad m => Applicative (EMT l m)

Defined in Control.Monad.Exception.Base

Methods

pure :: a -> EMT l m a

(<*>) :: EMT l m (a -> b) -> EMT l m a -> EMT l m b

liftA2 :: (a -> b -> c) -> EMT l m a -> EMT l m b -> EMT l m c

(*>) :: EMT l m a -> EMT l m b -> EMT l m b

(<*) :: EMT l m a -> EMT l m b -> EMT l m a

MonadIO m => MonadIO (EMT l m)

Defined in Control.Monad.Exception.Base

Methods

liftIO :: IO a -> EMT l m a

Monad m => MonadLoc (EMT l m)

Defined in Control.Monad.Exception.Base

Methods

withLoc :: String -> EMT l m a -> EMT l m a

type StT (EMT l) a

Defined in Control.Monad.Exception.Base

type StT (EMT l) a = Either (CallTrace, CheckedException l) a

type StM (EMT l m) a

Defined in Control.Monad.Exception.Base

type StM (EMT l m) a = ComposeSt (EMT l) m a

type CallTrace = [String]

tryEMT :: Monad m => EMT AnyException m a -> m (Either SomeException a)

Run a computation explicitly handling exceptions

tryEMTWithLoc :: Monad m => EMT AnyException m a -> m (Either (CallTrace, SomeException) a)

runEMT :: Monad m => EMT NoExceptions m a -> m a

Run a safe computation

runEMTParanoid :: Monad m => EMT ParanoidMode m a -> m a

Run a safe computation checking even unchecked (UncaughtException) exceptions

data AnyException

Instances

Exception e => Throws e AnyException

Defined in Control.Monad.Exception.Base

class Exception e => UncaughtException e

UncaughtException models unchecked exceptions

In order to declare an unchecked exception E, all that is needed is to make e an instance of UncaughtException

instance UncaughtException E

Note that declaring an exception E as unchecked does not automatically turn its children unchecked too. This is a shortcoming of the current encoding.

Instances

UncaughtException SomeException

Defined in Control.Monad.Exception.Base

The Throws type class

class Exception e => Throws e l

Throws is a type level binary relationship used to model a list of exceptions.

There is only one case in which the user must add further instances to Throws. If your sets of exceptions are hierarchical then you need to teach Throws about the hierarchy.

Subtyping

As there is no way to automatically infer the subcases of an exception, they have to be encoded manually mirroring the hierarchy defined in the defined Exception instances. For example, the following instance encodes that MyFileNotFoundException is a subexception of MyIOException :

instance Throws MyFileNotFoundException (Caught MyIOException l)

Throws is not a transitive relation and every ancestor relation must be explicitly encoded.

                                                           --   TopException
                                                           --         |
  instance Throws MidException   (Caught TopException l)   --         |
                                                           --   MidException
  instance Throws ChildException (Caught MidException l)   --         |
  instance Throws ChildException (Caught TopException l)   --         |
                                                           --  ChildException

Note that SomeException is automatically an ancestor of every other exception type.

Instances

UncaughtException e => Throws e NoExceptions

Defined in Control.Monad.Exception.Base

Exception e => Throws e AnyException

Defined in Control.Monad.Exception.Base

Exception e => Throws e (Caught SomeException l)

SomeException is at the top of the exception hierarchy . Capturing SomeException captures every possible exception

Defined in Control.Monad.Exception.Throws

Exception e => Throws e (Caught e l)

Defined in Control.Monad.Exception.Throws

Throws e l => Throws e (Caught e' l)

Defined in Control.Monad.Exception.Throws

Throws SomeException (Caught SomeException l)

Defined in Control.Monad.Exception.Throws

data Caught e l

A type level witness of a exception handler.

Instances

Exception e => Throws e (Caught SomeException l)

SomeException is at the top of the exception hierarchy . Capturing SomeException captures every possible exception

Defined in Control.Monad.Exception.Throws

Exception e => Throws e (Caught e l)

Defined in Control.Monad.Exception.Throws

Throws e l => Throws e (Caught e' l)

Defined in Control.Monad.Exception.Throws

Throws SomeException (Caught SomeException l)

Defined in Control.Monad.Exception.Throws

(Exception e, Monad m) => MonadCatch e (EMT (Caught e l) m) (EMT l m)

Defined in Control.Monad.Exception.Pure

Methods

catch :: EMT (Caught e l) m a -> (e -> EMT l m a) -> EMT l m a

catchWithSrcLoc :: EMT (Caught e l) m a -> ([String] -> e -> EMT l m a) -> EMT l m a

(Exception e, MonadBaseControl IO m) => MonadCatch e (EMT (Caught e l) m) (EMT l m)

Defined in Control.Monad.Exception.IO

Methods

catch :: EMT (Caught e l) m a -> (e -> EMT l m a) -> EMT l m a

catchWithSrcLoc :: EMT (Caught e l) m a -> ([String] -> e -> EMT l m a) -> EMT l m a

Exception primitives

throw :: (Exception e, Throws e l, Monad m) => e -> EMT l m a

The throw primitive

rethrow :: (Throws e l, Monad m) => CallTrace -> e -> EMT l m a

Rethrow an exception keeping the call trace

catch :: (Exception e, MonadBaseControl IO m) => EMT (Caught e l) m a -> (e -> EMT l m a) -> EMT l m a

The catch primitive

catchWithSrcLoc :: (Exception e, MonadBaseControl IO m) => EMT (Caught e l) m a -> (CallTrace -> e -> EMT l m a) -> EMT l m a

Catch and exception and observe the stack trace. If on top of the IO monad, this will also capture asynchronous exceptions

finally :: MonadBaseControl IO m => EMT l m a -> EMT l m b -> EMT l m a

Sequence two computations discarding the result of the second one. If the first computation rises an exception, the second computation is run and then the exception is rethrown.

onException :: MonadBaseControl IO m => EMT l m a -> EMT l m b -> EMT l m a

Like finally, but performs the second computation only when the first one rises an exception

bracket

Arguments

:: MonadBaseControl IO m

=> EMT l m a

acquire resource

-> (a -> EMT l m b)

release resource

-> (a -> EMT l m c)

computation

-> EMT l m c

wrapException :: (Exception e, Throws e' l, MonadBaseControl IO m) => (e -> e') -> EMT (Caught e l) m a -> EMT l m a

Capture an exception e, wrap it, and rethrow. Keeps the original monadic call trace.

showExceptionWithTrace :: Exception e => [String] -> e -> String

data FailException

FailException is thrown by Monad fail

Constructors

FailException String

Instances

Show FailException

Defined in Control.Monad.Exception.Base

Methods

showsPrec :: Int -> FailException -> ShowS

show :: FailException -> String

showList :: [FailException] -> ShowS

Exception FailException

Defined in Control.Monad.Exception.Base

Methods

toException :: FailException -> SomeException

fromException :: SomeException -> Maybe FailException

displayException :: FailException -> String

data MonadZeroException

MonadZeroException is thrown by MonadPlus mzero

Constructors

MonadZeroException

Instances

Show MonadZeroException

Defined in Control.Monad.Exception.Base

Methods

showsPrec :: Int -> MonadZeroException -> ShowS

show :: MonadZeroException -> String

showList :: [MonadZeroException] -> ShowS

Exception MonadZeroException

Defined in Control.Monad.Exception.Base

Methods

toException :: MonadZeroException -> SomeException

fromException :: SomeException -> Maybe MonadZeroException

displayException :: MonadZeroException -> String

mplusDefault :: Monad m => EMT l m a -> EMT l m a -> EMT l m a

This function may be used as a value for mplus in MonadPlus

Reexports

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 BlockedIndefinitelyOnMVar

Since: base-4.1.0.0

Defined in GHC.IO.Exception

Methods

toException :: BlockedIndefinitelyOnMVar -> SomeException

fromException :: SomeException -> Maybe BlockedIndefinitelyOnMVar

displayException :: BlockedIndefinitelyOnMVar -> String

Exception BlockedIndefinitelyOnSTM

Since: base-4.1.0.0

Defined in GHC.IO.Exception

Methods

toException :: BlockedIndefinitelyOnSTM -> SomeException

fromException :: SomeException -> Maybe BlockedIndefinitelyOnSTM

displayException :: BlockedIndefinitelyOnSTM -> String

Exception Deadlock

Since: base-4.1.0.0

Defined in GHC.IO.Exception

Methods

toException :: Deadlock -> SomeException

fromException :: SomeException -> Maybe Deadlock

displayException :: Deadlock -> String

Exception AllocationLimitExceeded

Since: base-4.8.0.0

Defined in GHC.IO.Exception

Methods

toException :: AllocationLimitExceeded -> SomeException

fromException :: SomeException -> Maybe AllocationLimitExceeded

displayException :: AllocationLimitExceeded -> String

Exception CompactionFailed

Since: base-4.10.0.0

Defined in GHC.IO.Exception

Methods

toException :: CompactionFailed -> SomeException

fromException :: SomeException -> Maybe CompactionFailed

displayException :: CompactionFailed -> String

Exception AssertionFailed

Since: base-4.1.0.0

Defined in GHC.IO.Exception

Methods

toException :: AssertionFailed -> SomeException

fromException :: SomeException -> Maybe AssertionFailed

displayException :: AssertionFailed -> String

Exception SomeAsyncException

Since: base-4.7.0.0

Defined in GHC.IO.Exception

Methods

toException :: SomeAsyncException -> SomeException

fromException :: SomeException -> Maybe SomeAsyncException

displayException :: SomeAsyncException -> String

Exception AsyncException

Since: base-4.7.0.0

Defined in GHC.IO.Exception

Methods

toException :: AsyncException -> SomeException

fromException :: SomeException -> Maybe AsyncException

displayException :: AsyncException -> String

Exception ArrayException

Since: base-4.1.0.0

Defined in GHC.IO.Exception

Methods

toException :: ArrayException -> SomeException

fromException :: SomeException -> Maybe ArrayException

displayException :: ArrayException -> String

Exception FixIOException

Since: base-4.11.0.0

Defined in GHC.IO.Exception

Methods

toException :: FixIOException -> SomeException

fromException :: SomeException -> Maybe FixIOException

displayException :: FixIOException -> String

Exception ExitCode

Since: base-4.1.0.0

Defined in GHC.IO.Exception

Methods

toException :: ExitCode -> SomeException

fromException :: SomeException -> Maybe ExitCode

displayException :: ExitCode -> String

Exception IOException

Since: base-4.1.0.0

Defined in GHC.IO.Exception

Methods

toException :: IOException -> SomeException

fromException :: SomeException -> Maybe IOException

displayException :: IOException -> String

Exception ArithException

Since: base-4.0.0.0

Defined in GHC.Exception.Type

Methods

toException :: ArithException -> SomeException

fromException :: SomeException -> Maybe ArithException

displayException :: ArithException -> String

Exception SomeException

Since: base-3.0

Defined in GHC.Exception.Type

Methods

toException :: SomeException -> SomeException

fromException :: SomeException -> Maybe SomeException

displayException :: SomeException -> String

Exception MonadZeroException

Defined in Control.Monad.Exception.Base

Methods

toException :: MonadZeroException -> SomeException

fromException :: SomeException -> Maybe MonadZeroException

displayException :: MonadZeroException -> String

Exception FailException

Defined in Control.Monad.Exception.Base

Methods

toException :: FailException -> SomeException

fromException :: SomeException -> Maybe FailException

displayException :: FailException -> 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

Defined in GHC.Exception.Type

Methods

showsPrec :: Int -> SomeException -> ShowS

show :: SomeException -> String

showList :: [SomeException] -> ShowS

Exception SomeException

Since: base-3.0

Defined in GHC.Exception.Type

Methods

toException :: SomeException -> SomeException

fromException :: SomeException -> Maybe SomeException

displayException :: SomeException -> String

UncaughtException SomeException

Defined in Control.Monad.Exception.Base

Exception e => Throws e (Caught SomeException l)

SomeException is at the top of the exception hierarchy . Capturing SomeException captures every possible exception

Defined in Control.Monad.Exception.Throws

Throws SomeException (Caught SomeException l)

Defined in Control.Monad.Exception.Throws

class Typeable (a :: k)

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

Minimal complete definition

typeRep#

class Monad f => Failure e (f :: Type -> Type) where

Methods

failure :: e -> f v

Instances

Failure e []

Defined in Control.Failure

Methods

failure :: e -> [v]

Failure e Maybe

Defined in Control.Failure

Methods

failure :: e -> Maybe v

Exception e => Failure e IO

Defined in Control.Failure

Methods

failure :: e -> IO v

(MonadTrans t, Failure e m, Monad (t m)) => Failure e (t m)

Instance for all monad transformers, simply lift the failure into the base monad.

Defined in Control.Failure

Methods

failure :: e -> t m v

Failure e (Either e)

Defined in Control.Failure

Methods

failure :: e -> Either e v

(Exception e, Throws e l, Monad m) => Failure e (EMT l m)

Defined in Control.Monad.Exception.Base

Methods

failure :: e -> EMT l m v

Orphan instances

(Exception e, MonadBaseControl IO m) => MonadCatch e (EMT (Caught e l) m) (EMT l m)

Methods

catch :: EMT (Caught e l) m a -> (e -> EMT l m a) -> EMT l m a

catchWithSrcLoc :: EMT (Caught e l) m a -> ([String] -> e -> EMT l m a) -> EMT l m a