Safe Haskell | Safe-Inferred |
---|---|
Language | Haskell2010 |
Control.Exception.Extra
Contents
Description
Extra functions for Control.Exception.
These functions provide retrying, showing in the presence of exceptions,
and functions to catch/ignore exceptions, including monomorphic (no Exception
context) versions.
If you want to use a safer set of exceptions see the safe-exceptions package.
Synopsis
- interruptible :: IO a -> IO a
- class (Typeable e, Show e) => Exception e where
- toException :: e -> SomeException
- fromException :: SomeException -> Maybe e
- displayException :: e -> String
- backtraceDesired :: e -> Bool
- evaluate :: a -> IO a
- ioError :: IOError -> IO a
- assert :: Bool -> a -> a
- throwTo :: Exception e => ThreadId -> e -> IO ()
- allowInterrupt :: IO ()
- catches :: IO a -> [Handler a] -> IO a
- bracket :: IO a -> (a -> IO b) -> (a -> IO c) -> IO c
- bracketOnError :: IO a -> (a -> IO b) -> (a -> IO c) -> IO c
- bracket_ :: IO a -> IO b -> IO c -> IO c
- catchJust :: Exception e => (e -> Maybe b) -> IO a -> (b -> IO a) -> IO a
- finally :: IO a -> IO b -> IO a
- handle :: Exception e => (e -> IO a) -> IO a -> IO a
- handleJust :: Exception e => (e -> Maybe b) -> (b -> IO a) -> IO a -> IO a
- mapException :: (Exception e1, Exception e2) => (e1 -> e2) -> a -> a
- onException :: IO a -> IO b -> IO a
- try :: Exception e => IO a -> IO (Either e a)
- tryJust :: Exception e => (e -> Maybe b) -> IO a -> IO (Either b a)
- throw :: forall a e. (HasCallStack, Exception e) => e -> a
- addExceptionContext :: ExceptionAnnotation a => a -> SomeException -> SomeException
- someExceptionContext :: SomeException -> ExceptionContext
- annotateIO :: ExceptionAnnotation e => e -> IO a -> IO a
- catch :: Exception e => IO a -> (e -> IO a) -> IO a
- getMaskingState :: IO MaskingState
- mask :: ((forall a. IO a -> IO a) -> IO b) -> IO b
- mask_ :: IO a -> IO a
- throwIO :: (HasCallStack, Exception e) => e -> IO a
- uninterruptibleMask :: ((forall a. IO a -> IO a) -> IO b) -> IO b
- uninterruptibleMask_ :: IO a -> IO a
- asyncExceptionFromException :: Exception e => SomeException -> Maybe e
- asyncExceptionToException :: Exception e => e -> SomeException
- data Handler a = Exception e => Handler (e -> IO a)
- data NestedAtomically = NestedAtomically
- newtype NoMethodError = NoMethodError String
- data NonTermination = NonTermination
- newtype PatternMatchFail = PatternMatchFail String
- newtype RecConError = RecConError String
- newtype RecSelError = RecSelError String
- newtype RecUpdError = RecUpdError String
- newtype TypeError = TypeError String
- data ErrorCall where
- ErrorCallWithLocation String String
- pattern ErrorCall :: String -> ErrorCall
- data ArithException
- data ExceptionWithContext a = ExceptionWithContext ExceptionContext a
- data SomeException = (Exception e, HasExceptionContext) => SomeException e
- data MaskingState
- data AllocationLimitExceeded = AllocationLimitExceeded
- data ArrayException
- = IndexOutOfBounds String
- | UndefinedElement String
- newtype AssertionFailed = AssertionFailed String
- data AsyncException
- data BlockedIndefinitelyOnMVar = BlockedIndefinitelyOnMVar
- data BlockedIndefinitelyOnSTM = BlockedIndefinitelyOnSTM
- newtype CompactionFailed = CompactionFailed String
- data Deadlock = Deadlock
- data IOException
- data SomeAsyncException = Exception e => SomeAsyncException e
- type Partial = HasCallStack
- retry :: Int -> IO a -> IO a
- retryBool :: Exception e => (e -> Bool) -> Int -> IO a -> IO a
- errorWithoutStackTrace :: [Char] -> a
- showException :: Show e => e -> IO String
- stringException :: String -> IO String
- errorIO :: Partial => String -> IO a
- assertIO :: Partial => Bool -> IO ()
- ignore :: IO () -> IO ()
- catch_ :: IO a -> (SomeException -> IO a) -> IO a
- handle_ :: (SomeException -> IO a) -> IO a -> IO a
- try_ :: IO a -> IO (Either SomeException a)
- catchJust_ :: (SomeException -> Maybe b) -> IO a -> (b -> IO a) -> IO a
- handleJust_ :: (SomeException -> Maybe b) -> (b -> IO a) -> IO a -> IO a
- tryJust_ :: (SomeException -> Maybe b) -> IO a -> IO (Either b a)
- catchBool :: Exception e => (e -> Bool) -> IO a -> (e -> IO a) -> IO a
- handleBool :: Exception e => (e -> Bool) -> (e -> IO a) -> IO a -> IO a
- tryBool :: Exception e => (e -> Bool) -> IO a -> IO (Either e a)
Documentation
interruptible :: IO a -> IO a #
class (Typeable e, Show e) => Exception e where #
Minimal complete definition
Nothing
Methods
toException :: e -> SomeException #
fromException :: SomeException -> Maybe e #
displayException :: e -> String #
backtraceDesired :: e -> Bool #
Instances
allowInterrupt :: IO () #
mapException :: (Exception e1, Exception e2) => (e1 -> e2) -> a -> a #
onException :: IO a -> IO b -> IO a #
addExceptionContext :: ExceptionAnnotation a => a -> SomeException -> SomeException #
someExceptionContext :: SomeException -> ExceptionContext #
annotateIO :: ExceptionAnnotation e => e -> IO a -> IO a #
uninterruptibleMask_ :: IO a -> IO a #
asyncExceptionFromException :: Exception e => SomeException -> Maybe e #
asyncExceptionToException :: Exception e => e -> SomeException #
data NestedAtomically #
Constructors
NestedAtomically |
Instances
Exception NestedAtomically | |
Defined in GHC.Internal.Control.Exception.Base Methods toException :: NestedAtomically -> SomeException # fromException :: SomeException -> Maybe NestedAtomically # displayException :: NestedAtomically -> String # backtraceDesired :: NestedAtomically -> Bool # | |
Show NestedAtomically | |
Defined in GHC.Internal.Control.Exception.Base Methods showsPrec :: Int -> NestedAtomically -> ShowS show :: NestedAtomically -> String showList :: [NestedAtomically] -> ShowS |
newtype NoMethodError #
Constructors
NoMethodError String |
Instances
Exception NoMethodError | |
Defined in GHC.Internal.Control.Exception.Base Methods toException :: NoMethodError -> SomeException # fromException :: SomeException -> Maybe NoMethodError # displayException :: NoMethodError -> String # backtraceDesired :: NoMethodError -> Bool # | |
Show NoMethodError | |
Defined in GHC.Internal.Control.Exception.Base Methods showsPrec :: Int -> NoMethodError -> ShowS show :: NoMethodError -> String showList :: [NoMethodError] -> ShowS |
data NonTermination #
Constructors
NonTermination |
Instances
Exception NonTermination | |
Defined in GHC.Internal.Control.Exception.Base Methods toException :: NonTermination -> SomeException # fromException :: SomeException -> Maybe NonTermination # displayException :: NonTermination -> String # backtraceDesired :: NonTermination -> Bool # | |
Show NonTermination | |
Defined in GHC.Internal.Control.Exception.Base Methods showsPrec :: Int -> NonTermination -> ShowS show :: NonTermination -> String showList :: [NonTermination] -> ShowS |
newtype PatternMatchFail #
Constructors
PatternMatchFail String |
Instances
Exception PatternMatchFail | |
Defined in GHC.Internal.Control.Exception.Base Methods toException :: PatternMatchFail -> SomeException # fromException :: SomeException -> Maybe PatternMatchFail # displayException :: PatternMatchFail -> String # backtraceDesired :: PatternMatchFail -> Bool # | |
Show PatternMatchFail | |
Defined in GHC.Internal.Control.Exception.Base Methods showsPrec :: Int -> PatternMatchFail -> ShowS show :: PatternMatchFail -> String showList :: [PatternMatchFail] -> ShowS |
newtype RecConError #
Constructors
RecConError String |
Instances
Exception RecConError | |
Defined in GHC.Internal.Control.Exception.Base Methods toException :: RecConError -> SomeException # fromException :: SomeException -> Maybe RecConError # displayException :: RecConError -> String # backtraceDesired :: RecConError -> Bool # | |
Show RecConError | |
Defined in GHC.Internal.Control.Exception.Base Methods showsPrec :: Int -> RecConError -> ShowS show :: RecConError -> String showList :: [RecConError] -> ShowS |
newtype RecSelError #
Constructors
RecSelError String |
Instances
Exception RecSelError | |
Defined in GHC.Internal.Control.Exception.Base Methods toException :: RecSelError -> SomeException # fromException :: SomeException -> Maybe RecSelError # displayException :: RecSelError -> String # backtraceDesired :: RecSelError -> Bool # | |
Show RecSelError | |
Defined in GHC.Internal.Control.Exception.Base Methods showsPrec :: Int -> RecSelError -> ShowS show :: RecSelError -> String showList :: [RecSelError] -> ShowS |
newtype RecUpdError #
Constructors
RecUpdError String |
Instances
Exception RecUpdError | |
Defined in GHC.Internal.Control.Exception.Base Methods toException :: RecUpdError -> SomeException # fromException :: SomeException -> Maybe RecUpdError # displayException :: RecUpdError -> String # backtraceDesired :: RecUpdError -> Bool # | |
Show RecUpdError | |
Defined in GHC.Internal.Control.Exception.Base Methods showsPrec :: Int -> RecUpdError -> ShowS show :: RecUpdError -> String showList :: [RecUpdError] -> ShowS |
Constructors
TypeError String |
Instances
Exception TypeError | |
Defined in GHC.Internal.Control.Exception.Base Methods toException :: TypeError -> SomeException # fromException :: SomeException -> Maybe TypeError # displayException :: TypeError -> String # backtraceDesired :: TypeError -> Bool # | |
Show TypeError | |
Constructors
ErrorCallWithLocation String String |
Instances
Exception ErrorCall | |
Defined in GHC.Internal.Exception Methods toException :: ErrorCall -> SomeException # fromException :: SomeException -> Maybe ErrorCall # displayException :: ErrorCall -> String # backtraceDesired :: ErrorCall -> Bool # | |
Show ErrorCall | |
Eq ErrorCall | |
Ord ErrorCall | |
Defined in GHC.Internal.Exception |
data ArithException #
Instances
data ExceptionWithContext a #
Constructors
ExceptionWithContext ExceptionContext a |
Instances
Exception a => Exception (ExceptionWithContext a) | |
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) | |
Defined in GHC.Internal.Exception.Type Methods showsPrec :: Int -> ExceptionWithContext a -> ShowS show :: ExceptionWithContext a -> String showList :: [ExceptionWithContext a] -> ShowS |
data SomeException #
Constructors
(Exception e, HasExceptionContext) => SomeException e |
Instances
Exception SomeException | |
Defined in GHC.Internal.Exception.Type Methods toException :: SomeException -> SomeException # fromException :: SomeException -> Maybe SomeException # displayException :: SomeException -> String # backtraceDesired :: SomeException -> Bool # | |
Show SomeException | |
Defined in GHC.Internal.Exception.Type Methods showsPrec :: Int -> SomeException -> ShowS show :: SomeException -> String showList :: [SomeException] -> ShowS |
data MaskingState #
Constructors
Unmasked | |
MaskedInterruptible | |
MaskedUninterruptible |
Instances
NFData MaskingState | |
Defined in Control.DeepSeq Methods rnf :: MaskingState -> () | |
Show MaskingState | |
Defined in GHC.Internal.IO Methods showsPrec :: Int -> MaskingState -> ShowS show :: MaskingState -> String showList :: [MaskingState] -> ShowS | |
Eq MaskingState | |
Defined in GHC.Internal.IO |
data AllocationLimitExceeded #
Constructors
AllocationLimitExceeded |
Instances
Exception AllocationLimitExceeded | |
Defined in GHC.Internal.IO.Exception Methods toException :: AllocationLimitExceeded -> SomeException # fromException :: SomeException -> Maybe AllocationLimitExceeded # displayException :: AllocationLimitExceeded -> String # backtraceDesired :: AllocationLimitExceeded -> Bool # | |
Show AllocationLimitExceeded | |
Defined in GHC.Internal.IO.Exception Methods showsPrec :: Int -> AllocationLimitExceeded -> ShowS show :: AllocationLimitExceeded -> String showList :: [AllocationLimitExceeded] -> ShowS |
data ArrayException #
Constructors
IndexOutOfBounds String | |
UndefinedElement String |
Instances
newtype AssertionFailed #
Constructors
AssertionFailed String |
Instances
Exception AssertionFailed | |
Defined in GHC.Internal.IO.Exception Methods toException :: AssertionFailed -> SomeException # fromException :: SomeException -> Maybe AssertionFailed # displayException :: AssertionFailed -> String # backtraceDesired :: AssertionFailed -> Bool # | |
Show AssertionFailed | |
Defined in GHC.Internal.IO.Exception Methods showsPrec :: Int -> AssertionFailed -> ShowS show :: AssertionFailed -> String showList :: [AssertionFailed] -> ShowS |
data AsyncException #
Constructors
StackOverflow | |
HeapOverflow | |
ThreadKilled | |
UserInterrupt |
Instances
data BlockedIndefinitelyOnMVar #
Constructors
BlockedIndefinitelyOnMVar |
Instances
Exception BlockedIndefinitelyOnMVar | |
Defined in GHC.Internal.IO.Exception Methods toException :: BlockedIndefinitelyOnMVar -> SomeException # fromException :: SomeException -> Maybe BlockedIndefinitelyOnMVar # displayException :: BlockedIndefinitelyOnMVar -> String # backtraceDesired :: BlockedIndefinitelyOnMVar -> Bool # | |
Show BlockedIndefinitelyOnMVar | |
Defined in GHC.Internal.IO.Exception Methods showsPrec :: Int -> BlockedIndefinitelyOnMVar -> ShowS show :: BlockedIndefinitelyOnMVar -> String showList :: [BlockedIndefinitelyOnMVar] -> ShowS |
data BlockedIndefinitelyOnSTM #
Constructors
BlockedIndefinitelyOnSTM |
Instances
Exception BlockedIndefinitelyOnSTM | |
Defined in GHC.Internal.IO.Exception Methods toException :: BlockedIndefinitelyOnSTM -> SomeException # fromException :: SomeException -> Maybe BlockedIndefinitelyOnSTM # displayException :: BlockedIndefinitelyOnSTM -> String # backtraceDesired :: BlockedIndefinitelyOnSTM -> Bool # | |
Show BlockedIndefinitelyOnSTM | |
Defined in GHC.Internal.IO.Exception Methods showsPrec :: Int -> BlockedIndefinitelyOnSTM -> ShowS show :: BlockedIndefinitelyOnSTM -> String showList :: [BlockedIndefinitelyOnSTM] -> ShowS |
newtype CompactionFailed #
Constructors
CompactionFailed String |
Instances
Exception CompactionFailed | |
Defined in GHC.Internal.IO.Exception Methods toException :: CompactionFailed -> SomeException # fromException :: SomeException -> Maybe CompactionFailed # displayException :: CompactionFailed -> String # backtraceDesired :: CompactionFailed -> Bool # | |
Show CompactionFailed | |
Defined in GHC.Internal.IO.Exception Methods showsPrec :: Int -> CompactionFailed -> ShowS show :: CompactionFailed -> String showList :: [CompactionFailed] -> ShowS |
Constructors
Deadlock |
Instances
Exception Deadlock | |
Defined in GHC.Internal.IO.Exception Methods toException :: Deadlock -> SomeException # fromException :: SomeException -> Maybe Deadlock # displayException :: Deadlock -> String # backtraceDesired :: Deadlock -> Bool # | |
Show Deadlock | |
data IOException #
Instances
Exception IOException | |
Defined in GHC.Internal.IO.Exception Methods toException :: IOException -> SomeException # fromException :: SomeException -> Maybe IOException # displayException :: IOException -> String # backtraceDesired :: IOException -> Bool # | |
Show IOException | |
Defined in GHC.Internal.IO.Exception Methods showsPrec :: Int -> IOException -> ShowS show :: IOException -> String showList :: [IOException] -> ShowS | |
Eq IOException | |
Defined in GHC.Internal.IO.Exception |
data SomeAsyncException #
Constructors
Exception e => SomeAsyncException e |
Instances
Exception SomeAsyncException | |
Defined in GHC.Internal.IO.Exception Methods toException :: SomeAsyncException -> SomeException # fromException :: SomeException -> Maybe SomeAsyncException # displayException :: SomeAsyncException -> String # backtraceDesired :: SomeAsyncException -> Bool # | |
Show SomeAsyncException | |
Defined in GHC.Internal.IO.Exception Methods showsPrec :: Int -> SomeAsyncException -> ShowS show :: SomeAsyncException -> String showList :: [SomeAsyncException] -> ShowS |
type Partial = HasCallStack Source #
A constraint which documents that a function is partial, and on GHC 8.0 and above produces a stack trace on failure. For example:
myHead :: Partial
=> [a] -> a
myHead [] = error "bad"
myHead (x:xs) = x
When using Partial
with GHC 7.8 or below you need to enable the
language feature ConstraintKinds
, e.g. {-# LANGUAGE ConstraintKinds #-}
at the top of the file.
retry :: Int -> IO a -> IO a Source #
Retry an operation at most n times (n must be positive). If the operation fails the nth time it will throw that final exception.
retry 1 (print "x") == print "x" retry 3 (fail "die") == fail "die"
retryBool :: Exception e => (e -> Bool) -> Int -> IO a -> IO a Source #
Retry an operation at most n times (n must be positive), while the exception value and type match a predicate. If the operation fails the nth time it will throw that final exception.
errorWithoutStackTrace :: [Char] -> a #
showException :: Show e => e -> IO String Source #
Show a value, but if the result contains exceptions, produce
<Exception>
. Defined as
.
Particularly useful for printing exceptions to users, remembering that exceptions
can themselves contain undefined values.stringException
. show
stringException :: String -> IO String Source #
Fully evaluate an input String. If the String contains embedded exceptions it will produce <Exception>
.
stringException "test" == pure "test" stringException ("test" ++ undefined) == pure "test<Exception>" stringException ("test" ++ undefined ++ "hello") == pure "test<Exception>" stringException ['t','e','s','t',undefined] == pure "test<Exception>"
assertIO :: Partial => Bool -> IO () Source #
An IO
action that when evaluated calls assert
in the IO
monad, which throws an AssertionFailed
exception if the argument is False
.
With optimizations enabled (and -fgnore-asserts
) this function ignores its argument and does nothing.
catch (assertIO True >> pure 1) (\(x :: AssertionFailed) -> pure 2) == pure 1 seq (assertIO False) (print 1) == print 1
Exception catching/ignoring
ignore :: IO () -> IO () Source #
Ignore any exceptions thrown by the action.
ignore (print 1) == print 1 ignore (fail "die") == pure ()
catch_ :: IO a -> (SomeException -> IO a) -> IO a Source #
A version of catch
without the Exception
context, restricted to SomeException
,
so catches all exceptions.
catchJust_ :: (SomeException -> Maybe b) -> IO a -> (b -> IO a) -> IO a Source #
handleJust_ :: (SomeException -> Maybe b) -> (b -> IO a) -> IO a -> IO a Source #
Like catch_
but for handleJust
catchBool :: Exception e => (e -> Bool) -> IO a -> (e -> IO a) -> IO a Source #
Catch an exception if the predicate passes, then call the handler with the original exception. As an example:
readFileExists x == catchBool isDoesNotExistError (readFile "myfile") (const $ pure "")