exceptions-0.3.3: Extensible optionally-pure exceptions

Portabilitynon-portable
Stabilityexperimental
MaintainerEdward Kmett <ekmett@gmail.com>
Safe HaskellTrustworthy

Control.Monad.Catch

Contents

Description

This module supports monads that can throw extensible exceptions. The exceptions are the very same from Control.Exception, and the operations offered very similar, but here they are not limited to IO.

This code is in the style of both transformers and mtl, and is compatible with them, though doesn't mimic the module structure or offer the complete range of features in those packages.

This is very similar to ErrorT and MonadError, but based on features of Control.Exception. In particular, it handles the complex case of asynchronous exceptions by including mask in the typeclass. Note that the extensible extensions feature relies the RankNTypes language extension.

Synopsis

Typeclass

The mtl style typeclass

class Monad m => MonadCatch m whereSource

Methods

throwM :: Exception e => e -> m aSource

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

catch :: Exception e => m a -> (e -> m a) -> m aSource

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

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

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

uninterruptibleMask :: ((forall a. m a -> m a) -> m b) -> m bSource

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

Instances

Utilities

These functions follow those from Control.Exception, except that they are based on methods from the MonadCatch typeclass. See Control.Exception for API usage.

mask_ :: MonadCatch m => m a -> m aSource

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

uninterruptibleMask_ :: MonadCatch m => m a -> m aSource

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

catchAll :: MonadCatch m => m a -> (SomeException -> m a) -> m aSource

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

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

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

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

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

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

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

data Handler m a Source

Generalized version of Handler

Constructors

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

Instances

Monad m => Functor (Handler m) 

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

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

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

Flipped catch. See Control.Exception's handle.

handleAll :: MonadCatch m => (SomeException -> m a) -> m a -> m aSource

Flipped catchAll

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

Flipped catchIOError

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

Flipped catchJust. See Control.Exception's handleJust.

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

Flipped catchIf

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

Similar to catch, but returns an Either result. See Control.Exception's try.

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

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

onException :: MonadCatch m => m a -> m b -> m aSource

Run an action only if an exception is thrown in the main action. The exception is not caught, simply rethrown.

bracket :: MonadCatch m => m a -> (a -> m b) -> (a -> m c) -> m cSource

Generalized abstracted pattern of safe resource acquisition and release in the face of exceptions. The first action "acquires" some value, which is "released" by the second action at the end. The third action "uses" the value and its result is the result of the bracket.

If an exception occurs during the use, the release still happens before the exception is rethrown.

bracket_ :: MonadCatch m => m a -> m b -> m c -> m cSource

Version of bracket without any value being passed to the second and third actions.

finally :: MonadCatch m => m a -> m b -> m aSource

Perform an action with a finalizer action that is run, even if an exception occurs.

bracketOnError :: MonadCatch m => m a -> (a -> m b) -> (a -> m c) -> m cSource

Like bracket, but only performs the final action if there was an exception raised by the in-between computation.

Re-exports from Control.Exception

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

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

 data MyException = ThisException | ThatException
     deriving (Show, Typeable)

 instance Exception MyException

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

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

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

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

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

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

 instance Exception SomeCompilerException

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

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

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

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

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

 instance Exception SomeFrontendException where
     toException = compilerExceptionToException
     fromException = compilerExceptionFromException

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

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

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

 data MismatchedParentheses = MismatchedParentheses
     deriving (Typeable, Show)

 instance Exception MismatchedParentheses where
     toException   = frontendExceptionToException
     fromException = frontendExceptionFromException

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

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

Methods

toException :: e -> SomeException

fromException :: SomeException -> Maybe e

Instances

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 :: Exception e => e -> SomeException 

Instances