+{-# 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/.
--
--- The External API for exceptions. The functions provided in this
--- module allow catching of exceptions in the IO monad.
+-- * /Asynchronous exceptions in Haskell/, by Simon Marlow, Simon Peyton
+-- Jones, Andy Moran and John Reppy, in /PLDI'01/.
+--
+-- * /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
- 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
+ BlockedIndefinitelyOnMVar(..),
+ BlockedIndefinitelyOnSTM(..),
+ 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 System.IO.Error
-import GHC.Base ( 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 e | isUserError e = Just (ioeGetErrorString 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)