1 {-# OPTIONS_GHC -XNoImplicitPrelude #-}
3 -----------------------------------------------------------------------------
5 -- Module : Control.Exception
6 -- Copyright : (c) The University of Glasgow 2001
7 -- License : BSD-style (see the file libraries/base/LICENSE)
9 -- Maintainer : libraries@haskell.org
10 -- Stability : experimental
11 -- Portability : non-portable (extended exceptions)
13 -- This module provides support for raising and catching both built-in
14 -- and user-defined exceptions.
16 -- In addition to exceptions thrown by 'IO' operations, exceptions may
17 -- be thrown by pure code (imprecise exceptions) or by external events
18 -- (asynchronous exceptions), but may only be caught in the 'IO' monad.
19 -- For more details, see:
21 -- * /A semantics for imprecise exceptions/, by Simon Peyton Jones,
22 -- Alastair Reid, Tony Hoare, Simon Marlow, Fergus Henderson,
25 -- * /Asynchronous exceptions in Haskell/, by Simon Marlow, Simon Peyton
26 -- Jones, Andy Moran and John Reppy, in /PLDI'01/.
28 -----------------------------------------------------------------------------
30 module Control.Exception (
32 -- * The Exception type
38 Exception(..), -- instance Eq, Ord, Show, Typeable
39 IOException, -- instance Eq, Ord, Show, Typeable
40 ArithException(..), -- instance Eq, Ord, Show, Typeable
41 ArrayException(..), -- instance Eq, Ord, Show, Typeable
43 AsyncException(..), -- instance Eq, Ord, Show, Typeable
45 #if __GLASGOW_HASKELL__ || __HUGS__
50 BlockedOnDeadMVar(..),
51 BlockedIndefinitely(..),
60 -- * Throwing exceptions
61 throwIO, -- :: Exception -> IO a
62 throw, -- :: Exception -> a
63 ioError, -- :: IOError -> IO a
64 #ifdef __GLASGOW_HASKELL__
65 throwTo, -- :: ThreadId -> Exception -> a
68 -- * Catching Exceptions
70 -- |There are several functions for catching and examining
71 -- exceptions; all of them may only be used from within the
74 -- ** The @catch@ functions
75 catch, -- :: IO a -> (Exception -> IO a) -> IO a
76 #if __GLASGOW_HASKELL__ || __HUGS__
79 catchJust, -- :: (Exception -> Maybe b) -> IO a -> (b -> IO a) -> IO a
81 -- ** The @handle@ functions
82 handle, -- :: (Exception -> IO a) -> IO a -> IO a
83 handleJust,-- :: (Exception -> Maybe b) -> (b -> IO a) -> IO a -> IO a
85 -- ** The @try@ functions
86 try, -- :: IO a -> IO (Either Exception a)
87 tryJust, -- :: (Exception -> Maybe b) -> a -> IO (Either b a)
90 -- ** The @evaluate@ function
91 evaluate, -- :: a -> IO a
93 -- ** The @mapException@ function
94 mapException, -- :: (Exception -> Exception) -> a -> a
96 -- * Asynchronous Exceptions
100 -- ** Asynchronous exception control
102 -- |The following two functions allow a thread to control delivery of
103 -- asynchronous exceptions during a critical region.
105 block, -- :: IO a -> IO a
106 unblock, -- :: IO a -> IO a
107 blocked, -- :: IO Bool
109 -- *** Applying @block@ to an exception handler
113 -- *** Interruptible operations
119 assert, -- :: Bool -> a -> a
123 bracket, -- :: IO a -> (a -> IO b) -> (a -> IO c) -> IO ()
124 bracket_, -- :: IO a -> IO b -> IO c -> IO ()
127 finally, -- :: IO a -> IO b -> IO a
130 import Control.Exception.Base
132 #ifdef __GLASGOW_HASKELL__
137 import Prelude hiding (catch)
140 #if __GLASGOW_HASKELL__ || __HUGS__
141 data Handler a = forall e . Exception e => Handler (e -> IO a)
143 catches :: IO a -> [Handler a] -> IO a
144 catches io handlers = io `catch` catchesHandler handlers
146 catchesHandler :: [Handler a] -> SomeException -> IO a
147 catchesHandler handlers e = foldr tryHandler (throw e) handlers
148 where tryHandler (Handler handler) res
149 = case fromException e of
150 Just e' -> handler e'
154 -- -----------------------------------------------------------------------------
155 -- Asynchronous exceptions
159 #AsynchronousExceptions# Asynchronous exceptions are so-called because they arise due to
160 external influences, and can be raised at any point during execution.
161 'StackOverflow' and 'HeapOverflow' are two examples of
162 system-generated asynchronous exceptions.
164 The primary source of asynchronous exceptions, however, is
167 > throwTo :: ThreadId -> Exception -> IO ()
169 'throwTo' (also 'throwDynTo' and 'Control.Concurrent.killThread') allows one
170 running thread to raise an arbitrary exception in another thread. The
171 exception is therefore asynchronous with respect to the target thread,
172 which could be doing anything at the time it receives the exception.
173 Great care should be taken with asynchronous exceptions; it is all too
174 easy to introduce race conditions by the over zealous use of
179 There\'s an implied 'block' around every exception handler in a call
180 to one of the 'catch' family of functions. This is because that is
181 what you want most of the time - it eliminates a common race condition
182 in starting an exception handler, because there may be no exception
183 handler on the stack to handle another exception if one arrives
184 immediately. If asynchronous exceptions are blocked on entering the
185 handler, though, we have time to install a new exception handler
186 before being interrupted. If this weren\'t the default, one would have
187 to write something like
190 > catch (unblock (...))
194 If you need to unblock asynchronous exceptions again in the exception
195 handler, just use 'unblock' as normal.
197 Note that 'try' and friends /do not/ have a similar default, because
198 there is no exception handler in this case. If you want to use 'try'
199 in an asynchronous-exception-safe way, you will need to use
205 Some operations are /interruptible/, which means that they can receive
206 asynchronous exceptions even in the scope of a 'block'. Any function
207 which may itself block is defined as interruptible; this includes
208 'Control.Concurrent.MVar.takeMVar'
209 (but not 'Control.Concurrent.MVar.tryTakeMVar'),
210 and most operations which perform
211 some I\/O with the outside world. The reason for having
212 interruptible operations is so that we can write things like
216 > catch (unblock (...))
220 if the 'Control.Concurrent.MVar.takeMVar' was not interruptible,
222 combination could lead to deadlock, because the thread itself would be
223 blocked in a state where it can\'t receive any asynchronous exceptions.
224 With 'Control.Concurrent.MVar.takeMVar' interruptible, however, we can be
225 safe in the knowledge that the thread can receive exceptions right up
226 until the point when the 'Control.Concurrent.MVar.takeMVar' succeeds.
227 Similar arguments apply for other interruptible operations like
228 'System.IO.openFile'.