X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=Control%2FException.hs;h=9824fb0ea75a4a193b1ed778f74203d4ea17daeb;hb=8afc9fecd586d3c4f7ef9c69fb1686a79e5f441d;hp=96205c65defb907844a6fc6654d2088d8ed5024c;hpb=b5882429e82e23f729ce9790b14a39c16bd4d336;p=ghc-base.git diff --git a/Control/Exception.hs b/Control/Exception.hs index 96205c6..9824fb0 100644 --- a/Control/Exception.hs +++ b/Control/Exception.hs @@ -1,233 +1,339 @@ +{-# OPTIONS_GHC -XNoImplicitPrelude #-} + ----------------------------------------------------------------------------- --- +-- | -- Module : Control.Exception -- Copyright : (c) The University of Glasgow 2001 --- License : BSD-style (see the file libraries/core/LICENSE) --- +-- License : BSD-style (see the file libraries/base/LICENSE) +-- -- Maintainer : libraries@haskell.org -- Stability : experimental --- Portability : non-portable +-- Portability : non-portable (extended exceptions) +-- +-- This module provides support for raising and catching both built-in +-- and user-defined exceptions. +-- +-- In addition to exceptions thrown by 'IO' operations, exceptions may +-- be thrown by pure code (imprecise exceptions) or by external events +-- (asynchronous exceptions), but may only be caught in the 'IO' monad. +-- For more details, see: +-- +-- * /A semantics for imprecise exceptions/, by Simon Peyton Jones, +-- Alastair Reid, Tony Hoare, Simon Marlow, Fergus Henderson, +-- in /PLDI'99/. -- --- $Id: Exception.hs,v 1.3 2001/10/18 11:10:19 rrt Exp $ +-- * /Asynchronous exceptions in Haskell/, by Simon Marlow, Simon Peyton +-- Jones, Andy Moran and John Reppy, in /PLDI'01/. -- --- The External API for exceptions. The functions provided in this --- module allow catching of exceptions in the IO monad. +-- * /An Extensible Dynamically-Typed Hierarchy of Exceptions/, +-- by Simon Marlow, in /Haskell '06/. -- ----------------------------------------------------------------------------- module Control.Exception ( - Exception(..), -- instance Eq, Ord, Show, Typeable - IOException, -- instance Eq, Ord, Show, Typeable - ArithException(..), -- instance Eq, Ord, Show, Typeable - ArrayException(..), -- instance Eq, Ord, Show, Typeable - AsyncException(..), -- instance Eq, Ord, Show, Typeable - - try, -- :: IO a -> IO (Either Exception a) - tryJust, -- :: (Exception -> Maybe b) -> a -> IO (Either b a) - - catch, -- :: IO a -> (Exception -> IO a) -> IO a - catchJust, -- :: (Exception -> Maybe b) -> IO a -> (b -> IO a) -> IO a - - handle, -- :: (Exception -> IO a) -> IO a -> IO a - handleJust,-- :: (Exception -> Maybe b) -> (b -> IO a) -> IO a -> IO a - - evaluate, -- :: a -> IO a - - -- Exception predicates (for tryJust, catchJust, handleJust) - - ioErrors, -- :: Exception -> Maybe IOError - arithExceptions, -- :: Exception -> Maybe ArithException - errorCalls, -- :: Exception -> Maybe String - dynExceptions, -- :: Exception -> Maybe Dynamic - assertions, -- :: Exception -> Maybe String - asyncExceptions, -- :: Exception -> Maybe AsyncException - userErrors, -- :: Exception -> Maybe String - - -- Throwing exceptions - - throw, -- :: Exception -> a - -- for now - throwTo, -- :: ThreadId -> Exception -> a - - -- Dynamic exceptions - - throwDyn, -- :: Typeable ex => ex -> b - throwDynTo, -- :: Typeable ex => ThreadId -> ex -> b - catchDyn, -- :: Typeable ex => IO a -> (ex -> IO a) -> IO a - - -- Async exception control + -- * The Exception type +#ifdef __HUGS__ + SomeException, +#else + SomeException(..), +#endif + Exception(..), -- class + IOException, -- instance Eq, Ord, Show, Typeable, Exception + ArithException(..), -- instance Eq, Ord, Show, Typeable, Exception + ArrayException(..), -- instance Eq, Ord, Show, Typeable, Exception + AssertionFailed(..), + AsyncException(..), -- instance Eq, Ord, Show, Typeable, Exception + +#if __GLASGOW_HASKELL__ || __HUGS__ + NonTermination(..), + NestedAtomically(..), +#endif +#ifdef __NHC__ + System.ExitCode(), -- instance Exception +#endif - block, -- :: IO a -> IO a - unblock, -- :: IO a -> IO a + BlockedOnDeadMVar(..), + BlockedIndefinitely(..), + Deadlock(..), + NoMethodError(..), + PatternMatchFail(..), + RecConError(..), + RecSelError(..), + RecUpdError(..), + ErrorCall(..), + + -- * Throwing exceptions + throw, + throwIO, + ioError, +#ifdef __GLASGOW_HASKELL__ + throwTo, +#endif - -- Assertions + -- * Catching Exceptions - -- for now - assert, -- :: Bool -> a -> a + -- $catching - -- Utilities + -- ** Catching all exceptions - finally, -- :: IO a -> IO b -> IO b + -- $catchall - bracket, -- :: IO a -> (a -> IO b) -> (a -> IO c) -> IO () - bracket_, -- :: IO a -> IO b -> IO c -> IO () + -- ** The @catch@ functions + catch, + catches, Handler(..), + catchJust, - ) where + -- ** The @handle@ functions + handle, + handleJust, -#ifdef __GLASGOW_HASKELL__ -import Prelude hiding (catch) -import GHC.Prim ( assert ) -import GHC.Exception hiding (try, catch, bracket, bracket_) -import GHC.Conc ( throwTo, ThreadId ) -import GHC.IOBase ( IO(..) ) -#endif + -- ** The @try@ functions + try, + tryJust, -#ifdef __HUGS__ -import Prelude hiding ( catch ) -import PrelPrim ( catchException - , Exception(..) - , throw - , ArithException(..) - , AsyncException(..) - , assert - ) -#endif + -- ** The @evaluate@ function + evaluate, -import Data.Dynamic + -- ** The @mapException@ function + mapException, -#include "Dynamic.h" -INSTANCE_TYPEABLE0(Exception,exceptionTc,"Exception") -INSTANCE_TYPEABLE0(IOException,ioExceptionTc,"IOException") -INSTANCE_TYPEABLE0(ArithException,arithExceptionTc,"ArithException") -INSTANCE_TYPEABLE0(ArrayException,arrayExceptionTc,"ArrayException") -INSTANCE_TYPEABLE0(AsyncException,asyncExceptionTc,"AsyncException") + -- * Asynchronous Exceptions ------------------------------------------------------------------------------ --- Catching exceptions + -- $async --- GHC.Exception defines 'catchException' for us. + -- ** Asynchronous exception control -catch :: IO a -> (Exception -> IO a) -> IO a -catch = catchException + -- |The following two functions allow a thread to control delivery of + -- asynchronous exceptions during a critical region. -catchJust :: (Exception -> Maybe b) -> IO a -> (b -> IO a) -> IO a -catchJust p a handler = catch a handler' - where handler' e = case p e of - Nothing -> throw e - Just b -> handler b + block, + unblock, + blocked, -handle :: (Exception -> IO a) -> IO a -> IO a -handle = flip catch + -- *** Applying @block@ to an exception handler -handleJust :: (Exception -> Maybe b) -> (b -> IO a) -> IO a -> IO a -handleJust p = flip (catchJust p) + -- $block_handler ------------------------------------------------------------------------------ --- evaluate + -- *** Interruptible operations -evaluate :: a -> IO a -evaluate a = a `seq` return a + -- $interruptible ------------------------------------------------------------------------------ --- 'try' and variations. + -- * Assertions -try :: IO a -> IO (Either Exception a) -try a = catch (a >>= \ v -> return (Right v)) (\e -> return (Left e)) + assert, -tryJust :: (Exception -> Maybe b) -> IO a -> IO (Either b a) -tryJust p a = do - r <- try a - case r of - Right v -> return (Right v) - Left e -> case p e of - Nothing -> throw e - Just b -> return (Left b) + -- * Utilities ------------------------------------------------------------------------------ --- Dynamic exception types. Since one of the possible kinds of exception --- is a dynamically typed value, we can effectively have polymorphic --- exceptions. + bracket, + bracket_, + bracketOnError, --- throwDyn will raise any value as an exception, provided it is in the --- Typeable class (see Dynamic.lhs). + finally, + onException, --- catchDyn will catch any exception of a given type (determined by the --- handler function). Any raised exceptions that don't match are --- re-raised. + ) where -throwDyn :: Typeable exception => exception -> b -throwDyn exception = throw (DynException (toDyn exception)) +import Control.Exception.Base -throwDynTo :: Typeable exception => ThreadId -> exception -> IO () -throwDynTo t exception = throwTo t (DynException (toDyn exception)) +#ifdef __GLASGOW_HASKELL__ +import GHC.Base +-- import GHC.IO hiding ( onException, finally ) +import Data.Maybe +#else +import Prelude hiding (catch) +#endif -catchDyn :: Typeable exception => IO a -> (exception -> IO a) -> IO a -catchDyn m k = catchException m handle - where handle ex = case ex of - (DynException dyn) -> - case fromDynamic dyn of - Just exception -> k exception - Nothing -> throw ex - _ -> throw ex +#ifdef __NHC__ +import System (ExitCode()) +#endif ------------------------------------------------------------------------------ --- Exception Predicates +-- | You need this when using 'catches'. +data Handler a = forall e . Exception e => Handler (e -> IO a) -ioErrors :: Exception -> Maybe IOError -arithExceptions :: Exception -> Maybe ArithException -errorCalls :: Exception -> Maybe String -dynExceptions :: Exception -> Maybe Dynamic -assertions :: Exception -> Maybe String -asyncExceptions :: Exception -> Maybe AsyncException -userErrors :: Exception -> Maybe String +{- | +Sometimes you want to catch two different sorts of exception. You could +do something like -ioErrors e@(IOException _) = Just e -ioErrors _ = Nothing +> f = expr `catch` \ (ex :: ArithException) -> handleArith ex +> `catch` \ (ex :: IOException) -> handleIO ex -arithExceptions (ArithException e) = Just e -arithExceptions _ = Nothing +However, there are a couple of problems with this approach. The first is +that having two exception handlers is inefficient. However, the more +serious issue is that the second exception handler will catch exceptions +in the first, e.g. in the example above, if @handleArith@ throws an +@IOException@ then the second exception handler will catch it. -errorCalls (ErrorCall e) = Just e -errorCalls _ = Nothing +Instead, we provide a function 'catches', which would be used thus: -assertions (AssertionFailed e) = Just e -assertions _ = Nothing +> f = expr `catches` [Handler (\ (ex :: ArithException) -> handleArith ex), +> Handler (\ (ex :: IOException) -> handleIO ex)] +-} +catches :: IO a -> [Handler a] -> IO a +catches io handlers = io `catch` catchesHandler handlers -dynExceptions (DynException e) = Just e -dynExceptions _ = Nothing +catchesHandler :: [Handler a] -> SomeException -> IO a +catchesHandler handlers e = foldr tryHandler (throw e) handlers + where tryHandler (Handler handler) res + = case fromException e of + Just e' -> handler e' + Nothing -> res -asyncExceptions (AsyncException e) = Just e -asyncExceptions _ = Nothing +-- ----------------------------------------------------------------------------- +-- Catching exceptions -userErrors (UserError e) = Just e -userErrors _ = Nothing +{- $catching + +There are several functions for catching and examining +exceptions; all of them may only be used from within the +'IO' monad. + +Here's a rule of thumb for deciding which catch-style function to +use: + + * If you want to do some cleanup in the event that an exception + is raised, use 'finally', 'bracket' or 'onException'. + + * To recover after an exception and do something else, the best + choice is to use one of the 'try' family. + + * ... unless you are recovering from an asynchronous exception, in which + case use 'catch' or 'catchJust'. + +The difference between using 'try' and 'catch' for recovery is that in +'catch' the handler is inside an implicit 'block' (see \"Asynchronous +Exceptions\") which is important when catching asynchronous +exceptions, but when catching other kinds of exception it is +unnecessary. Furthermore it is possible to accidentally stay inside +the implicit 'block' by tail-calling rather than returning from the +handler, which is why we recommend using 'try' rather than 'catch' for +ordinary exception recovery. + +A typical use of 'tryJust' for recovery looks like this: + +> do r <- tryJust (guard . isDoesNotExistError) $ getEnv "HOME" +> case r of +> Left e -> ... +> Right home -> ... + +-} + +-- ----------------------------------------------------------------------------- +-- Asynchronous exceptions + +{- $async + + #AsynchronousExceptions# Asynchronous exceptions are so-called because they arise due to +external influences, and can be raised at any point during execution. +'StackOverflow' and 'HeapOverflow' are two examples of +system-generated asynchronous exceptions. + +The primary source of asynchronous exceptions, however, is +'throwTo': + +> throwTo :: ThreadId -> Exception -> IO () + +'throwTo' (also 'throwDynTo' and 'Control.Concurrent.killThread') allows one +running thread to raise an arbitrary exception in another thread. The +exception is therefore asynchronous with respect to the target thread, +which could be doing anything at the time it receives the exception. +Great care should be taken with asynchronous exceptions; it is all too +easy to introduce race conditions by the over zealous use of +'throwTo'. +-} + +{- $block_handler +There\'s an implied 'block' around every exception handler in a call +to one of the 'catch' family of functions. This is because that is +what you want most of the time - it eliminates a common race condition +in starting an exception handler, because there may be no exception +handler on the stack to handle another exception if one arrives +immediately. If asynchronous exceptions are blocked on entering the +handler, though, we have time to install a new exception handler +before being interrupted. If this weren\'t the default, one would have +to write something like + +> block ( +> catch (unblock (...)) +> (\e -> handler) +> ) + +If you need to unblock asynchronous exceptions again in the exception +handler, just use 'unblock' as normal. + +Note that 'try' and friends /do not/ have a similar default, because +there is no exception handler in this case. Don't use 'try' for +recovering from an asynchronous exception. +-} + +{- $interruptible + +Some operations are /interruptible/, which means that they can receive +asynchronous exceptions even in the scope of a 'block'. Any function +which may itself block is defined as interruptible; this includes +'Control.Concurrent.MVar.takeMVar' +(but not 'Control.Concurrent.MVar.tryTakeMVar'), +and most operations which perform +some I\/O with the outside world. The reason for having +interruptible operations is so that we can write things like + +> block ( +> a <- takeMVar m +> catch (unblock (...)) +> (\e -> ...) +> ) + +if the 'Control.Concurrent.MVar.takeMVar' was not interruptible, +then this particular +combination could lead to deadlock, because the thread itself would be +blocked in a state where it can\'t receive any asynchronous exceptions. +With 'Control.Concurrent.MVar.takeMVar' interruptible, however, we can be +safe in the knowledge that the thread can receive exceptions right up +until the point when the 'Control.Concurrent.MVar.takeMVar' succeeds. +Similar arguments apply for other interruptible operations like +'System.IO.openFile'. +-} + +{- $catchall + +It is possible to catch all exceptions, by using the type 'SomeException': + +> catch f (\e -> ... (e :: SomeException) ...) + +HOWEVER, this is normally not what you want to do! + +For example, suppose you want to read a file, but if it doesn't exist +then continue as if it contained \"\". You might be tempted to just +catch all exceptions and return \"\" in the handler. However, this has +all sorts of undesirable consequences. For example, if the user +presses control-C at just the right moment then the 'UserInterrupt' +exception will be caught, and the program will continue running under +the belief that the file contains \"\". Similarly, if another thread +tries to kill the thread reading the file then the 'ThreadKilled' +exception will be ignored. + +Instead, you should only catch exactly the exceptions that you really +want. In this case, this would likely be more specific than even +\"any IO exception\"; a permissions error would likely also want to be +handled differently. Instead, you would probably want something like: + +> e <- tryJust (guard . isDoesNotExistError) (readFile f) +> let str = either (const "") id e + +There are occassions when you really do need to catch any sort of +exception. However, in most cases this is just so you can do some +cleaning up; you aren't actually interested in the exception itself. +For example, if you open a file then you want to close it again, +whether processing the file executes normally or throws an exception. +However, in these cases you can use functions like 'bracket', 'finally' +and 'onException', which never actually pass you the exception, but +just call the cleanup functions at the appropriate points. + +But sometimes you really do need to catch any exception, and actually +see what the exception is. One example is at the very top-level of a +program, you may wish to catch any exception, print it to a logfile or +the screen, and then exit gracefully. For these cases, you can use +'catch' (or one of the other exception-catching functions) with the +'SomeException' type. +-} ------------------------------------------------------------------------------ --- Some Useful Functions - -bracket :: IO a -> (a -> IO b) -> (a -> IO c) -> IO c -bracket before after thing = - block (do - a <- before - r <- catch - (unblock (thing a)) - (\e -> do { after a; throw e }) - after a - return r - ) - --- finally is an instance of bracket, but it's quite common --- so we give the specialised version for efficiency. -finally :: IO a -> IO b -> IO a -a `finally` sequel = - block (do - r <- catch - (unblock a) - (\e -> do { sequel; throw e }) - sequel - return r - ) - -bracket_ :: IO a -> IO b -> IO c -> IO c -bracket_ before after thing = bracket before (const after) (const thing)