9c388f4450de1a0b572c33c57109118232e10315
[ghc.git] / libraries / base / Control / Exception.hs
1 {-# LANGUAGE Trustworthy #-}
2 {-# LANGUAGE NoImplicitPrelude, ExistentialQuantification #-}
3
4 -----------------------------------------------------------------------------
5 -- |
6 -- Module : Control.Exception
7 -- Copyright : (c) The University of Glasgow 2001
8 -- License : BSD-style (see the file libraries/base/LICENSE)
9 --
10 -- Maintainer : libraries@haskell.org
11 -- Stability : experimental
12 -- Portability : non-portable (extended exceptions)
13 --
14 -- This module provides support for raising and catching both built-in
15 -- and user-defined exceptions.
16 --
17 -- In addition to exceptions thrown by 'IO' operations, exceptions may
18 -- be thrown by pure code (imprecise exceptions) or by external events
19 -- (asynchronous exceptions), but may only be caught in the 'IO' monad.
20 -- For more details, see:
21 --
22 -- * /A semantics for imprecise exceptions/, by Simon Peyton Jones,
23 -- Alastair Reid, Tony Hoare, Simon Marlow, Fergus Henderson,
24 -- in /PLDI'99/.
25 --
26 -- * /Asynchronous exceptions in Haskell/, by Simon Marlow, Simon Peyton
27 -- Jones, Andy Moran and John Reppy, in /PLDI'01/.
28 --
29 -- * /An Extensible Dynamically-Typed Hierarchy of Exceptions/,
30 -- by Simon Marlow, in /Haskell '06/.
31 --
32 -----------------------------------------------------------------------------
33
34 module Control.Exception (
35
36 -- * The Exception type
37 SomeException(..),
38 Exception(..), -- class
39 IOException, -- instance Eq, Ord, Show, Typeable, Exception
40 ArithException(..), -- instance Eq, Ord, Show, Typeable, Exception
41 ArrayException(..), -- instance Eq, Ord, Show, Typeable, Exception
42 AssertionFailed(..),
43 SomeAsyncException(..),
44 AsyncException(..), -- instance Eq, Ord, Show, Typeable, Exception
45 asyncExceptionToException, asyncExceptionFromException,
46
47 NonTermination(..),
48 NestedAtomically(..),
49 BlockedIndefinitelyOnMVar(..),
50 BlockedIndefinitelyOnSTM(..),
51 AllocationLimitExceeded(..),
52 Deadlock(..),
53 NoMethodError(..),
54 PatternMatchFail(..),
55 RecConError(..),
56 RecSelError(..),
57 RecUpdError(..),
58 ErrorCall(..),
59 TypeError(..),
60
61 -- * Throwing exceptions
62 throw,
63 throwIO,
64 ioError,
65 throwTo,
66
67 -- * Catching Exceptions
68
69 -- $catching
70
71 -- ** Catching all exceptions
72
73 -- $catchall
74
75 -- ** The @catch@ functions
76 catch,
77 catches, Handler(..),
78 catchJust,
79
80 -- ** The @handle@ functions
81 handle,
82 handleJust,
83
84 -- ** The @try@ functions
85 try,
86 tryJust,
87
88 -- ** The @evaluate@ function
89 evaluate,
90
91 -- ** The @mapException@ function
92 mapException,
93
94 -- * Asynchronous Exceptions
95
96 -- $async
97
98 -- ** Asynchronous exception control
99
100 -- |The following functions allow a thread to control delivery of
101 -- asynchronous exceptions during a critical region.
102
103 mask,
104 mask_,
105 uninterruptibleMask,
106 uninterruptibleMask_,
107 MaskingState(..),
108 getMaskingState,
109 interruptible,
110 allowInterrupt,
111
112 -- *** Applying @mask@ to an exception handler
113
114 -- $block_handler
115
116 -- *** Interruptible operations
117
118 -- $interruptible
119
120 -- * Assertions
121
122 assert,
123
124 -- * Utilities
125
126 bracket,
127 bracket_,
128 bracketOnError,
129
130 finally,
131 onException,
132
133 ) where
134
135 import Control.Exception.Base
136
137 import GHC.Base
138 import GHC.IO (interruptible)
139
140 -- | You need this when using 'catches'.
141 data Handler a = forall e . Exception e => Handler (e -> IO a)
142
143 instance Functor Handler where
144 fmap f (Handler h) = Handler (fmap f . h)
145
146 {- |
147 Sometimes you want to catch two different sorts of exception. You could
148 do something like
149
150 > f = expr `catch` \ (ex :: ArithException) -> handleArith ex
151 > `catch` \ (ex :: IOException) -> handleIO ex
152
153 However, there are a couple of problems with this approach. The first is
154 that having two exception handlers is inefficient. However, the more
155 serious issue is that the second exception handler will catch exceptions
156 in the first, e.g. in the example above, if @handleArith@ throws an
157 @IOException@ then the second exception handler will catch it.
158
159 Instead, we provide a function 'catches', which would be used thus:
160
161 > f = expr `catches` [Handler (\ (ex :: ArithException) -> handleArith ex),
162 > Handler (\ (ex :: IOException) -> handleIO ex)]
163 -}
164 catches :: IO a -> [Handler a] -> IO a
165 catches io handlers = io `catch` catchesHandler handlers
166
167 catchesHandler :: [Handler a] -> SomeException -> IO a
168 catchesHandler handlers e = foldr tryHandler (throw e) handlers
169 where tryHandler (Handler handler) res
170 = case fromException e of
171 Just e' -> handler e'
172 Nothing -> res
173
174 -- -----------------------------------------------------------------------------
175 -- Catching exceptions
176
177 {- $catching
178
179 There are several functions for catching and examining
180 exceptions; all of them may only be used from within the
181 'IO' monad.
182
183 Here's a rule of thumb for deciding which catch-style function to
184 use:
185
186 * If you want to do some cleanup in the event that an exception
187 is raised, use 'finally', 'bracket' or 'onException'.
188
189 * To recover after an exception and do something else, the best
190 choice is to use one of the 'try' family.
191
192 * ... unless you are recovering from an asynchronous exception, in which
193 case use 'catch' or 'catchJust'.
194
195 The difference between using 'try' and 'catch' for recovery is that in
196 'catch' the handler is inside an implicit 'mask' (see \"Asynchronous
197 Exceptions\") which is important when catching asynchronous
198 exceptions, but when catching other kinds of exception it is
199 unnecessary. Furthermore it is possible to accidentally stay inside
200 the implicit 'mask' by tail-calling rather than returning from the
201 handler, which is why we recommend using 'try' rather than 'catch' for
202 ordinary exception recovery.
203
204 A typical use of 'tryJust' for recovery looks like this:
205
206 > do r <- tryJust (guard . isDoesNotExistError) $ getEnv "HOME"
207 > case r of
208 > Left e -> ...
209 > Right home -> ...
210
211 -}
212
213 -- -----------------------------------------------------------------------------
214 -- Asynchronous exceptions
215
216 -- | When invoked inside 'mask', this function allows a masked
217 -- asynchronous exception to be raised, if one exists. It is
218 -- equivalent to performing an interruptible operation (see
219 -- #interruptible), but does not involve any actual blocking.
220 --
221 -- When called outside 'mask', or inside 'uninterruptibleMask', this
222 -- function has no effect.
223 --
224 -- @since 4.4.0.0
225 allowInterrupt :: IO ()
226 allowInterrupt = interruptible $ return ()
227
228 {- $async
229
230 #AsynchronousExceptions# Asynchronous exceptions are so-called because they arise due to
231 external influences, and can be raised at any point during execution.
232 'StackOverflow' and 'HeapOverflow' are two examples of
233 system-generated asynchronous exceptions.
234
235 The primary source of asynchronous exceptions, however, is
236 'throwTo':
237
238 > throwTo :: ThreadId -> Exception -> IO ()
239
240 'throwTo' (also 'Control.Concurrent.killThread') allows one
241 running thread to raise an arbitrary exception in another thread. The
242 exception is therefore asynchronous with respect to the target thread,
243 which could be doing anything at the time it receives the exception.
244 Great care should be taken with asynchronous exceptions; it is all too
245 easy to introduce race conditions by the over zealous use of
246 'throwTo'.
247 -}
248
249 {- $block_handler
250 There\'s an implied 'mask' around every exception handler in a call
251 to one of the 'catch' family of functions. This is because that is
252 what you want most of the time - it eliminates a common race condition
253 in starting an exception handler, because there may be no exception
254 handler on the stack to handle another exception if one arrives
255 immediately. If asynchronous exceptions are masked on entering the
256 handler, though, we have time to install a new exception handler
257 before being interrupted. If this weren\'t the default, one would have
258 to write something like
259
260 > mask $ \restore ->
261 > catch (restore (...))
262 > (\e -> handler)
263
264 If you need to unmask asynchronous exceptions again in the exception
265 handler, 'restore' can be used there too.
266
267 Note that 'try' and friends /do not/ have a similar default, because
268 there is no exception handler in this case. Don't use 'try' for
269 recovering from an asynchronous exception.
270 -}
271
272 {- $interruptible
273
274 #interruptible#
275 Some operations are /interruptible/, which means that they can receive
276 asynchronous exceptions even in the scope of a 'mask'. Any function
277 which may itself block is defined as interruptible; this includes
278 'Control.Concurrent.MVar.takeMVar'
279 (but not 'Control.Concurrent.MVar.tryTakeMVar'),
280 and most operations which perform
281 some I\/O with the outside world. The reason for having
282 interruptible operations is so that we can write things like
283
284 > mask $ \restore -> do
285 > a <- takeMVar m
286 > catch (restore (...))
287 > (\e -> ...)
288
289 if the 'Control.Concurrent.MVar.takeMVar' was not interruptible,
290 then this particular
291 combination could lead to deadlock, because the thread itself would be
292 blocked in a state where it can\'t receive any asynchronous exceptions.
293 With 'Control.Concurrent.MVar.takeMVar' interruptible, however, we can be
294 safe in the knowledge that the thread can receive exceptions right up
295 until the point when the 'Control.Concurrent.MVar.takeMVar' succeeds.
296 Similar arguments apply for other interruptible operations like
297 'System.IO.openFile'.
298
299 It is useful to think of 'mask' not as a way to completely prevent
300 asynchronous exceptions, but as a way to switch from asynchronous mode
301 to polling mode. The main difficulty with asynchronous
302 exceptions is that they normally can occur anywhere, but within a
303 'mask' an asynchronous exception is only raised by operations that are
304 interruptible (or call other interruptible operations). In many cases
305 these operations may themselves raise exceptions, such as I\/O errors,
306 so the caller will usually be prepared to handle exceptions arising from the
307 operation anyway. To perfom an explicit poll for asynchronous exceptions
308 inside 'mask', use 'allowInterrupt'.
309
310 Sometimes it is too onerous to handle exceptions in the middle of a
311 critical piece of stateful code. There are three ways to handle this
312 kind of situation:
313
314 * Use STM. Since a transaction is always either completely executed
315 or not at all, transactions are a good way to maintain invariants
316 over state in the presence of asynchronous (and indeed synchronous)
317 exceptions.
318
319 * Use 'mask', and avoid interruptible operations. In order to do
320 this, we have to know which operations are interruptible. It is
321 impossible to know for any given library function whether it might
322 invoke an interruptible operation internally; so instead we give a
323 list of guaranteed-not-to-be-interruptible operations below.
324
325 * Use 'uninterruptibleMask'. This is generally not recommended,
326 unless you can guarantee that any interruptible operations invoked
327 during the scope of 'uninterruptibleMask' can only ever block for
328 a short time. Otherwise, 'uninterruptibleMask' is a good way to
329 make your program deadlock and be unresponsive to user interrupts.
330
331 The following operations are guaranteed not to be interruptible:
332
333 * operations on 'IORef' from "Data.IORef"
334
335 * STM transactions that do not use 'retry'
336
337 * everything from the @Foreign@ modules
338
339 * everything from @Control.Exception@ except for 'throwTo'
340
341 * @tryTakeMVar@, @tryPutMVar@, @isEmptyMVar@
342
343 * @takeMVar@ if the @MVar@ is definitely full, and conversely @putMVar@ if the @MVar@ is definitely empty
344
345 * @newEmptyMVar@, @newMVar@
346
347 * @forkIO@, @forkIOUnmasked@, @myThreadId@
348
349 -}
350
351 {- $catchall
352
353 It is possible to catch all exceptions, by using the type 'SomeException':
354
355 > catch f (\e -> ... (e :: SomeException) ...)
356
357 HOWEVER, this is normally not what you want to do!
358
359 For example, suppose you want to read a file, but if it doesn't exist
360 then continue as if it contained \"\". You might be tempted to just
361 catch all exceptions and return \"\" in the handler. However, this has
362 all sorts of undesirable consequences. For example, if the user
363 presses control-C at just the right moment then the 'UserInterrupt'
364 exception will be caught, and the program will continue running under
365 the belief that the file contains \"\". Similarly, if another thread
366 tries to kill the thread reading the file then the 'ThreadKilled'
367 exception will be ignored.
368
369 Instead, you should only catch exactly the exceptions that you really
370 want. In this case, this would likely be more specific than even
371 \"any IO exception\"; a permissions error would likely also want to be
372 handled differently. Instead, you would probably want something like:
373
374 > e <- tryJust (guard . isDoesNotExistError) (readFile f)
375 > let str = either (const "") id e
376
377 There are occassions when you really do need to catch any sort of
378 exception. However, in most cases this is just so you can do some
379 cleaning up; you aren't actually interested in the exception itself.
380 For example, if you open a file then you want to close it again,
381 whether processing the file executes normally or throws an exception.
382 However, in these cases you can use functions like 'bracket', 'finally'
383 and 'onException', which never actually pass you the exception, but
384 just call the cleanup functions at the appropriate points.
385
386 But sometimes you really do need to catch any exception, and actually
387 see what the exception is. One example is at the very top-level of a
388 program, you may wish to catch any exception, print it to a logfile or
389 the screen, and then exit gracefully. For these cases, you can use
390 'catch' (or one of the other exception-catching functions) with the
391 'SomeException' type.
392 -}
393