{-# LANGUAGE MagicHash #-}{-# LANGUAGE NoImplicitPrelude #-}{-# LANGUAGE Trustworthy #-}------------------------------------------------------------------------------- |-- Module : Control.Exception.Base-- Copyright : (c) The University of Glasgow 2001-- License : BSD-style (see the file libraries/base/LICENSE)---- Maintainer : libraries@haskell.org-- Stability : experimental-- Portability : non-portable (extended exceptions)---- Extensible exceptions, except for multiple handlers.-------------------------------------------------------------------------------moduleControl.Exception.Base(-- * The Exception typeSomeException (..),Exception (..),IOException ,ArithException (..),ArrayException (..),AssertionFailed (..),SomeAsyncException (..),AsyncException (..),asyncExceptionToException ,asyncExceptionFromException ,NonTermination (..),NestedAtomically (..),BlockedIndefinitelyOnMVar (..),FixIOException (..),BlockedIndefinitelyOnSTM (..),AllocationLimitExceeded (..),CompactionFailed (..),Deadlock (..),NoMethodError (..),PatternMatchFail (..),RecConError (..),RecSelError (..),RecUpdError (..),ErrorCall (..),TypeError (..),-- #10284, custom error type for deferred type errors-- * Throwing exceptionsthrowIO ,throw ,ioError ,throwTo ,-- * Catching Exceptions-- ** The @catch@ functionscatch ,catchJust ,-- ** The @handle@ functionshandle ,handleJust ,-- ** The @try@ functionstry ,tryJust ,onException ,-- ** The @evaluate@ functionevaluate ,-- ** The @mapException@ functionmapException ,-- * Asynchronous Exceptions-- ** Asynchronous exception controlmask ,mask_ ,uninterruptibleMask ,uninterruptibleMask_ ,MaskingState (..),getMaskingState ,-- * Assertionsassert ,-- * Utilitiesbracket ,bracket_ ,bracketOnError ,finally ,-- * Calls for GHC runtimerecSelError ,recConError ,runtimeError ,nonExhaustiveGuardsError ,patError ,noMethodBindingError ,typeError ,nonTermination ,nestedAtomically ,)whereimportGHC.Base importGHC.Exception importGHC.IO hiding(bracket ,finally ,onException )importGHC.IO.Exception importGHC.Show -- import GHC.Exception hiding ( Exception )importGHC.Conc.Sync importData.Either ------------------------------------------------------------------------------- Catching exceptions-- | The function 'catchJust' is like 'catch', but it takes an extra-- argument which is an /exception predicate/, a function which-- selects which type of exceptions we\'re interested in.---- > catchJust (\e -> if isDoesNotExistErrorType (ioeGetErrorType e) then Just () else Nothing)-- > (readFile f)-- > (\_ -> do hPutStrLn stderr ("No such file: " ++ show f)-- > return "")---- Any other exceptions which are not matched by the predicate-- are re-raised, and may be caught by an enclosing-- 'catch', 'catchJust', etc.catchJust ::Exception e =>(e ->Maybe b )-- ^ Predicate to select exceptions->IO a -- ^ Computation to run->(b ->IO a )-- ^ Handler->IO a catchJust :: forall e b a.
Exception e =>
(e -> Maybe b) -> IO a -> (b -> IO a) -> IO a
catchJust e -> Maybe b
p IO a
a b -> IO a
handler =forall e a. Exception e => IO a -> (e -> IO a) -> IO a
catch IO a
a e -> IO a
handler' wherehandler' :: e -> IO a
handler' e
e =casee -> Maybe b
p e
e ofMaybe b
Nothing ->forall e a. Exception e => e -> IO a
throwIO e
e Just b
b ->b -> IO a
handler b
b -- | A version of 'catch' with the arguments swapped around; useful in-- situations where the code for the handler is shorter. For example:---- > do handle (\NonTermination -> exitWith (ExitFailure 1)) $-- > ...handle ::Exception e =>(e ->IO a )->IO a ->IO a handle :: forall e a. Exception e => (e -> IO a) -> IO a -> IO a
handle =forall a b c. (a -> b -> c) -> b -> a -> c
flip forall e a. Exception e => IO a -> (e -> IO a) -> IO a
catch -- | A version of 'catchJust' with the arguments swapped around (see-- 'handle').handleJust ::Exception e =>(e ->Maybe b )->(b ->IO a )->IO a ->IO a handleJust :: forall e b a.
Exception e =>
(e -> Maybe b) -> (b -> IO a) -> IO a -> IO a
handleJust e -> Maybe b
p =forall a b c. (a -> b -> c) -> b -> a -> c
flip (forall e b a.
Exception e =>
(e -> Maybe b) -> IO a -> (b -> IO a) -> IO a
catchJust e -> Maybe b
p )------------------------------------------------------------------------------- 'mapException'-- | This function maps one exception into another as proposed in the-- paper \"A semantics for imprecise exceptions\".-- Notice that the usage of 'unsafePerformIO' is safe here.mapException ::(Exception e1 ,Exception e2 )=>(e1 ->e2 )->a ->a mapException :: forall e1 e2 a.
(Exception e1, Exception e2) =>
(e1 -> e2) -> a -> a
mapException e1 -> e2
f a
v =forall a. IO a -> a
unsafePerformIO (forall e a. Exception e => IO a -> (e -> IO a) -> IO a
catch (forall a. a -> IO a
evaluate a
v )(\e1
x ->forall e a. Exception e => e -> IO a
throwIO (e1 -> e2
f e1
x )))------------------------------------------------------------------------------- 'try' and variations.-- | Similar to 'catch', but returns an 'Either' result which is-- @('Right' a)@ if no exception of type @e@ was raised, or @('Left' ex)@-- if an exception of type @e@ was raised and its value is @ex@.-- If any other type of exception is raised then it will be propagated-- up to the next enclosing exception handler.---- > try a = catch (Right `liftM` a) (return . Left)try ::Exception e =>IO a ->IO (Either e a )try :: forall e a. Exception e => IO a -> IO (Either e a)
try IO a
a =forall e a. Exception e => IO a -> (e -> IO a) -> IO a
catch (IO a
a forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= \a
v ->forall (m :: * -> *) a. Monad m => a -> m a
return (forall a b. b -> Either a b
Right a
v ))(\e
e ->forall (m :: * -> *) a. Monad m => a -> m a
return (forall a b. a -> Either a b
Left e
e ))-- | A variant of 'try' that takes an exception predicate to select-- which exceptions are caught (c.f. 'catchJust'). If the exception-- does not match the predicate, it is re-thrown.tryJust ::Exception e =>(e ->Maybe b )->IO a ->IO (Either b a )tryJust :: forall e b a.
Exception e =>
(e -> Maybe b) -> IO a -> IO (Either b a)
tryJust e -> Maybe b
p IO a
a =doEither e a
r <-forall e a. Exception e => IO a -> IO (Either e a)
try IO a
a caseEither e a
r ofRight a
v ->forall (m :: * -> *) a. Monad m => a -> m a
return (forall a b. b -> Either a b
Right a
v )Left e
e ->casee -> Maybe b
p e
e ofMaybe b
Nothing ->forall e a. Exception e => e -> IO a
throwIO e
e Just b
b ->forall (m :: * -> *) a. Monad m => a -> m a
return (forall a b. a -> Either a b
Left b
b )-- | Like 'finally', but only performs the final action if there was an-- exception raised by the computation.onException ::IO a ->IO b ->IO a onException :: forall a b. IO a -> IO b -> IO a
onException IO a
io IO b
what =IO a
io forall e a. Exception e => IO a -> (e -> IO a) -> IO a
`catch` \SomeException
e ->dob
_<-IO b
what forall e a. Exception e => e -> IO a
throwIO (SomeException
e ::SomeException )------------------------------------------------------------------------------- Some Useful Functions-- | When you want to acquire a resource, do some work with it, and-- then release the resource, it is a good idea to use 'bracket',-- because 'bracket' will install the necessary exception handler to-- release the resource in the event that an exception is raised-- during the computation. If an exception is raised, then 'bracket' will-- re-raise the exception (after performing the release).---- A common example is opening a file:---- > bracket-- > (openFile "filename" ReadMode)-- > (hClose)-- > (\fileHandle -> do { ... })---- The arguments to 'bracket' are in this order so that we can partially apply-- it, e.g.:---- > withFile name mode = bracket (openFile name mode) hClose---- Bracket wraps the release action with 'mask', which is sufficient to ensure-- that the release action executes to completion when it does not invoke any-- interruptible actions, even in the presence of asynchronous exceptions. For-- example, `hClose` is uninterruptible when it is not racing other uses of the-- handle. Similarly, closing a socket (from \"network\" package) is also-- uninterruptible under similar conditions. An example of an interruptible-- action is 'killThread'. Completion of interruptible release actions can be-- ensured by wrapping them in in 'uninterruptibleMask_', but this risks making-- the program non-responsive to @Control-C@, or timeouts. Another option is to-- run the release action asynchronously in its own thread:---- > void $ uninterruptibleMask_ $ forkIO $ do { ... }---- The resource will be released as soon as possible, but the thread that invoked-- bracket will not block in an uninterruptible state.--bracket ::IO a -- ^ computation to run first (\"acquire resource\")->(a ->IO b )-- ^ computation to run last (\"release resource\")->(a ->IO c )-- ^ computation to run in-between->IO c -- returns the value from the in-between computationbracket :: forall a b c. IO a -> (a -> IO b) -> (a -> IO c) -> IO c
bracket IO a
before a -> IO b
after a -> IO c
thing =forall b. ((forall a. IO a -> IO a) -> IO b) -> IO b
mask forall a b. (a -> b) -> a -> b
$ \forall a. IO a -> IO a
restore ->doa
a <-IO a
before c
r <-forall a. IO a -> IO a
restore (a -> IO c
thing a
a )forall a b. IO a -> IO b -> IO a
`onException` a -> IO b
after a
a b
_<-a -> IO b
after a
a forall (m :: * -> *) a. Monad m => a -> m a
return c
r -- | A specialised variant of 'bracket' with just a computation to run-- afterward.--finally ::IO a -- ^ computation to run first->IO b -- ^ computation to run afterward (even if an exception-- was raised)->IO a -- returns the value from the first computationIO a
a finally :: forall a b. IO a -> IO b -> IO a
`finally` IO b
sequel =forall b. ((forall a. IO a -> IO a) -> IO b) -> IO b
mask forall a b. (a -> b) -> a -> b
$ \forall a. IO a -> IO a
restore ->doa
r <-forall a. IO a -> IO a
restore IO a
a forall a b. IO a -> IO b -> IO a
`onException` IO b
sequel b
_<-IO b
sequel forall (m :: * -> *) a. Monad m => a -> m a
return a
r -- | A variant of 'bracket' where the return value from the first computation-- is not required.bracket_ ::IO a ->IO b ->IO c ->IO c bracket_ :: forall a b c. IO a -> IO b -> IO c -> IO c
bracket_ IO a
before IO b
after IO c
thing =forall a b c. IO a -> (a -> IO b) -> (a -> IO c) -> IO c
bracket IO a
before (forall a b. a -> b -> a
const IO b
after )(forall a b. a -> b -> a
const IO c
thing )-- | Like 'bracket', but only performs the final action if there was an-- exception raised by the in-between computation.bracketOnError ::IO a -- ^ computation to run first (\"acquire resource\")->(a ->IO b )-- ^ computation to run last (\"release resource\")->(a ->IO c )-- ^ computation to run in-between->IO c -- returns the value from the in-between computationbracketOnError :: forall a b c. IO a -> (a -> IO b) -> (a -> IO c) -> IO c
bracketOnError IO a
before a -> IO b
after a -> IO c
thing =forall b. ((forall a. IO a -> IO a) -> IO b) -> IO b
mask forall a b. (a -> b) -> a -> b
$ \forall a. IO a -> IO a
restore ->doa
a <-IO a
before forall a. IO a -> IO a
restore (a -> IO c
thing a
a )forall a b. IO a -> IO b -> IO a
`onException` a -> IO b
after a
a ------- |A pattern match failed. The @String@ gives information about the-- source location of the pattern.newtypePatternMatchFail =PatternMatchFail String -- | @since 4.0instanceShow PatternMatchFail whereshowsPrec :: Int -> PatternMatchFail -> ShowS
showsPrec Int
_(PatternMatchFail String
err )=String -> ShowS
showString String
err -- | @since 4.0instanceException PatternMatchFail ------- |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.newtypeRecSelError =RecSelError String -- | @since 4.0instanceShow RecSelError whereshowsPrec :: Int -> RecSelError -> ShowS
showsPrec Int
_(RecSelError String
err )=String -> ShowS
showString String
err -- | @since 4.0instanceException RecSelError ------- |An uninitialised record field was used. The @String@ gives-- information about the source location where the record was-- constructed.newtypeRecConError =RecConError String -- | @since 4.0instanceShow RecConError whereshowsPrec :: Int -> RecConError -> ShowS
showsPrec Int
_(RecConError String
err )=String -> ShowS
showString String
err -- | @since 4.0instanceException RecConError ------- |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.newtypeRecUpdError =RecUpdError String -- | @since 4.0instanceShow RecUpdError whereshowsPrec :: Int -> RecUpdError -> ShowS
showsPrec Int
_(RecUpdError String
err )=String -> ShowS
showString String
err -- | @since 4.0instanceException RecUpdError ------- |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.newtypeNoMethodError =NoMethodError String -- | @since 4.0instanceShow NoMethodError whereshowsPrec :: Int -> NoMethodError -> ShowS
showsPrec Int
_(NoMethodError String
err )=String -> ShowS
showString String
err -- | @since 4.0instanceException NoMethodError ------- |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 4.9.0.0newtypeTypeError =TypeError String -- | @since 4.9.0.0instanceShow TypeError whereshowsPrec :: Int -> TypeError -> ShowS
showsPrec Int
_(TypeError String
err )=String -> ShowS
showString String
err -- | @since 4.9.0.0instanceException TypeError ------- |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.dataNonTermination =NonTermination -- | @since 4.0instanceShow NonTermination whereshowsPrec :: Int -> NonTermination -> ShowS
showsPrec Int
_NonTermination
NonTermination =String -> ShowS
showString String
"<<loop>>"-- | @since 4.0instanceException NonTermination ------- |Thrown when the program attempts to call @atomically@, from the @stm@-- package, inside another call to @atomically@.dataNestedAtomically =NestedAtomically -- | @since 4.0instanceShow NestedAtomically whereshowsPrec :: Int -> NestedAtomically -> ShowS
showsPrec Int
_NestedAtomically
NestedAtomically =String -> ShowS
showString String
"Control.Concurrent.STM.atomically was nested"-- | @since 4.0instanceException NestedAtomically ------- See Note [Compiler error functions] in ghc-prim:GHC.Prim.PanicrecSelError ,recConError ,runtimeError ,nonExhaustiveGuardsError ,patError ,noMethodBindingError ,typeError ::Addr# ->a -- All take a UTF8-encoded C stringrecSelError :: forall a. Addr# -> a
recSelError Addr#
s =forall a e. Exception e => e -> a
throw (String -> RecSelError
RecSelError (String
"No match in record selector "forall a. [a] -> [a] -> [a]
++ Addr# -> String
unpackCStringUtf8# Addr#
s ))-- No location info unfortunatelyruntimeError :: forall a. Addr# -> a
runtimeError Addr#
s =forall a. String -> a
errorWithoutStackTrace (Addr# -> String
unpackCStringUtf8# Addr#
s )-- No location info unfortunatelynonExhaustiveGuardsError :: forall a. Addr# -> a
nonExhaustiveGuardsError Addr#
s =forall a e. Exception e => e -> a
throw (String -> PatternMatchFail
PatternMatchFail (Addr# -> ShowS
untangle Addr#
s String
"Non-exhaustive guards in"))recConError :: forall a. Addr# -> a
recConError Addr#
s =forall a e. Exception e => e -> a
throw (String -> RecConError
RecConError (Addr# -> ShowS
untangle Addr#
s String
"Missing field in record construction"))noMethodBindingError :: forall a. Addr# -> a
noMethodBindingError Addr#
s =forall a e. Exception e => e -> a
throw (String -> NoMethodError
NoMethodError (Addr# -> ShowS
untangle Addr#
s String
"No instance nor default method for class operation"))patError :: forall a. Addr# -> a
patError Addr#
s =forall a e. Exception e => e -> a
throw (String -> PatternMatchFail
PatternMatchFail (Addr# -> ShowS
untangle Addr#
s String
"Non-exhaustive patterns in"))typeError :: forall a. Addr# -> a
typeError Addr#
s =forall a e. Exception e => e -> a
throw (String -> TypeError
TypeError (Addr# -> String
unpackCStringUtf8# Addr#
s ))-- GHC's RTS calls thisnonTermination ::SomeException nonTermination :: SomeException
nonTermination =forall e. Exception e => e -> SomeException
toException NonTermination
NonTermination -- GHC's RTS calls thisnestedAtomically ::SomeException nestedAtomically :: SomeException
nestedAtomically =forall e. Exception e => e -> SomeException
toException NestedAtomically
NestedAtomically