Safe Haskell | Safe-Infered |
---|
This module is intended as a drop-in replacement for Control.Exception.
- class Monad m => MonadException m where
- catches :: MonadException m => m a -> [Handler m a] -> m a
- data Handler m a = forall e . Exception e => Handler (e -> m a)
- catchJust :: (MonadException m, Exception e) => (e -> Maybe b) -> m a -> (b -> m a) -> m a
- handle :: (MonadException m, Exception e) => (e -> m a) -> m a -> m a
- handleJust :: (MonadException m, Exception e) => (e -> Maybe b) -> (b -> m a) -> m a -> m a
- try :: (MonadException m, Exception e) => m a -> m (Either e a)
- tryJust :: (MonadException m, Exception e) => (e -> Maybe b) -> m a -> m (Either b a)
- bracket_ :: MonadException m => m a -> m b -> m c -> m c
- bracketOnError :: MonadException m => m a -> (a -> m b) -> (a -> m c) -> m c
- finally :: MonadException m => m a -> m b -> m a
- onException :: MonadException m => m a -> m b -> m a
- evaluate :: MonadBase IO m => a -> m a
- unsafeEvaluate :: MonadException m => a -> m a
- mapException :: (Exception e1, Exception e2) => (e1 -> e2) -> a -> a
- throwTo :: (MonadBase IO m, Exception e) => ThreadId -> e -> m ()
- mask :: MonadBaseControl IO m => ((forall n b. MonadBaseControl IO n => n b -> n b) -> m a) -> m a
- mask_ :: MonadBaseControl IO m => m a -> m a
- uninterruptibleMask :: MonadBaseControl IO m => ((forall n b. MonadBaseControl IO n => n b -> n b) -> m a) -> m a
- uninterruptibleMask_ :: MonadBaseControl IO m => m a -> m a
- data MaskingState
- getMaskingState :: MonadBase IO m => m MaskingState
- allowInterrupt :: MonadBase IO m => m ()
- data SomeException where
- SomeException :: Exception e => e -> SomeException
- class (Typeable e, Show e) => Exception e where
- toException :: e -> SomeException
- fromException :: SomeException -> Maybe e
- data IOException
- data ArithException
- = Overflow
- | Underflow
- | LossOfPrecision
- | DivideByZero
- | Denormal
- data ArrayException
- data AssertionFailed = AssertionFailed String
- data AsyncException
- data NonTermination = NonTermination
- data NestedAtomically = NestedAtomically
- data BlockedIndefinitelyOnMVar = BlockedIndefinitelyOnMVar
- data BlockedIndefinitelyOnSTM = BlockedIndefinitelyOnSTM
- data Deadlock = Deadlock
- data NoMethodError = NoMethodError String
- data PatternMatchFail = PatternMatchFail String
- data RecConError = RecConError String
- data RecSelError = RecSelError String
- data RecUpdError = RecUpdError String
- data ErrorCall = ErrorCall String
Documentation
class Monad m => MonadException m whereSource
The MonadException
type class. Minimal complete definition: throw
,
catch
.
throw :: Exception e => e -> m aSource
Generalized version of throwIO
.
catch :: Exception e => m a -> (e -> m a) -> m aSource
Generalized version of catch
.
bracket :: m a -> (a -> m b) -> (a -> m c) -> m cSource
Generalized version of bracket
.
MonadException IO | |
(MonadException b, MonadBaseControl b m) => MonadException m | |
MonadException (Either SomeException) | |
(MonadTransControl t, Monad (t m), MonadException m) => MonadException (t m) | |
Monad m => MonadException (ExceptionT m) |
Catching exceptions
The catch
functions
catches :: MonadException m => m a -> [Handler m a] -> m aSource
Generalized version of catches
.
catchJust :: (MonadException m, Exception e) => (e -> Maybe b) -> m a -> (b -> m a) -> m aSource
Generalized version of catchJust
.
The handle
functions
handle :: (MonadException m, Exception e) => (e -> m a) -> m a -> m aSource
handleJust :: (MonadException m, Exception e) => (e -> Maybe b) -> (b -> m a) -> m a -> m aSource
A version of catchJust
with the arguments swapped around. See
handleJust
.
The try
functions
tryJust :: (MonadException m, Exception e) => (e -> Maybe b) -> m a -> m (Either b a)Source
A generalized version of tryJust
.
Utilities
bracket_ :: MonadException m => m a -> m b -> m c -> m cSource
Generalized version of bracket_
.
bracketOnError :: MonadException m => m a -> (a -> m b) -> (a -> m c) -> m cSource
Generalized version of bracketOnError
.
finally :: MonadException m => m a -> m b -> m aSource
Generalized version of finally
.
onException :: MonadException m => m a -> m b -> m aSource
Generalized version of onException
.
The evaluate
functions
evaluate :: MonadBase IO m => a -> m aSource
Generalized version of evaluate
. This only works on IO
-like monads.
See unsafeEvaluate
for a version that works on every MonadException
.
unsafeEvaluate :: MonadException m => a -> m aSource
Generalized version of evaluate
. This uses unsafePerformIO
behind
the scenes to do something kind of similar to what the spoon
package
does.
The mapException
function
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".
Asynchronous exceptions
throwTo :: (MonadBase IO m, Exception e) => ThreadId -> e -> m ()Source
Generalized version of throwTo
.
mask :: MonadBaseControl IO m => ((forall n b. MonadBaseControl IO n => n b -> n b) -> m a) -> m aSource
Generalized version of mask
.
mask_ :: MonadBaseControl IO m => m a -> m aSource
Generalized version of mask
.
uninterruptibleMask :: MonadBaseControl IO m => ((forall n b. MonadBaseControl IO n => n b -> n b) -> m a) -> m aSource
Generalized version of mask
.
uninterruptibleMask_ :: MonadBaseControl IO m => m a -> m aSource
Generalized version of mask
.
data MaskingState
Describes the behaviour of a thread when an asynchronous exception is received.
Unmasked | asynchronous exceptions are unmasked (the normal state) |
MaskedInterruptible | the state during |
MaskedUninterruptible | the state during |
getMaskingState :: MonadBase IO m => m MaskingStateSource
Generalized version of getMaskingState
.
allowInterrupt :: MonadBase IO m => m ()Source
Generalized version of allowInterrupt
.
Exceptions (re-exported from Control.Exception)
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
.
SomeException :: Exception e => e -> SomeException |
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 MismatchedParenthesescatch
e -> putStrLn ("Caught " ++ show (e :: MismatchedParentheses)) Caught MismatchedParentheses *Main> throw MismatchedParenthesescatch
e -> putStrLn ("Caught " ++ show (e :: SomeFrontendException)) Caught MismatchedParentheses *Main> throw MismatchedParenthesescatch
e -> putStrLn ("Caught " ++ show (e :: SomeCompilerException)) Caught MismatchedParentheses *Main> throw MismatchedParenthesescatch
e -> putStrLn ("Caught " ++ show (e :: IOException)) *** Exception: MismatchedParentheses
toException :: e -> SomeException
fromException :: SomeException -> Maybe e
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.
data ArithException
Arithmetic exceptions.
data ArrayException
Exceptions generated by array operations
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. |
data AssertionFailed
data AsyncException
Asynchronous exceptions.
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:
|
ThreadKilled | This exception is raised by another thread
calling |
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). |
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.
data NestedAtomically
Thrown when the program attempts to call atomically
, from the stm
package, inside another call to atomically
.
data BlockedIndefinitelyOnMVar
The thread is blocked on an MVar
, but there are no other references
to the MVar
so it can't ever continue.
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.
data Deadlock
There are no runnable threads, so the program is deadlocked.
The Deadlock
exception is raised in the main thread only.
data 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.
data PatternMatchFail
A pattern match failed. The String
gives information about the
source location of the pattern.
data RecConError
An uninitialised record field was used. The String
gives
information about the source location where the record was
constructed.
data 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.
data 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.