[project @ 2004-11-12 15:14:17 by simonmar]
[packages/old-time.git] / GHC / Exception.lhs
1 \begin{code}
2 {-# OPTIONS -fno-implicit-prelude #-}
3 -----------------------------------------------------------------------------
4 -- |
5 -- Module      :  GHC.Exception
6 -- Copyright   :  (c) The University of Glasgow, 1998-2002
7 -- License     :  see libraries/base/LICENSE
8 -- 
9 -- Maintainer  :  cvs-ghc@haskell.org
10 -- Stability   :  internal
11 -- Portability :  non-portable (GHC extensions)
12 --
13 -- Exceptions and exception-handling functions.
14 -- 
15 -----------------------------------------------------------------------------
16
17 module GHC.Exception 
18         ( module GHC.Exception, 
19           Exception(..), AsyncException(..), 
20           IOException(..), ArithException(..), ArrayException(..),
21           throw, throwIO, ioError ) 
22   where
23
24 import GHC.Base
25 import GHC.IOBase
26 \end{code}
27
28 %*********************************************************
29 %*                                                      *
30 \subsection{Primitive catch}
31 %*                                                      *
32 %*********************************************************
33
34 catchException used to handle the passing around of the state to the
35 action and the handler.  This turned out to be a bad idea - it meant
36 that we had to wrap both arguments in thunks so they could be entered
37 as normal (remember IO returns an unboxed pair...).
38
39 Now catch# has type
40
41     catch# :: IO a -> (b -> IO a) -> IO a
42
43 (well almost; the compiler doesn't know about the IO newtype so we
44 have to work around that in the definition of catchException below).
45
46 \begin{code}
47 catchException :: IO a -> (Exception -> IO a) -> IO a
48 catchException (IO m) k =  IO $ \s -> catch# m (\ex -> unIO (k ex)) s
49
50 -- | The 'catch' function establishes a handler that receives any 'IOError'
51 -- raised in the action protected by 'catch'.  An 'IOError' is caught by
52 -- the most recent handler established by 'catch'.  These handlers are
53 -- not selective: all 'IOError's are caught.  Exception propagation
54 -- must be explicitly provided in a handler by re-raising any unwanted
55 -- exceptions.  For example, in
56 --
57 -- > f = catch g (\e -> if IO.isEOFError e then return [] else ioError e)
58 --
59 -- the function @f@ returns @[]@ when an end-of-file exception
60 -- (cf. 'System.IO.Error.isEOFError') occurs in @g@; otherwise, the
61 -- exception is propagated to the next outer handler.
62 --
63 -- When an exception propagates outside the main program, the Haskell
64 -- system prints the associated 'IOError' value and exits the program.
65 --
66 -- Non-I\/O exceptions are not caught by this variant; to catch all
67 -- exceptions, use 'Control.Exception.catch' from "Control.Exception".
68 catch           :: IO a -> (IOError -> IO a) -> IO a 
69 catch m k       =  catchException m handler
70   where handler (IOException err)   = k err
71         handler other               = throw other
72 \end{code}
73
74
75 %*********************************************************
76 %*                                                      *
77 \subsection{Controlling asynchronous exception delivery}
78 %*                                                      *
79 %*********************************************************
80
81 \begin{code}
82 -- | Applying 'block' to a computation will
83 -- execute that computation with asynchronous exceptions
84 -- /blocked/.  That is, any thread which
85 -- attempts to raise an exception in the current thread will be
86 -- blocked until asynchronous exceptions are enabled again.  There\'s
87 -- no need to worry about re-enabling asynchronous exceptions; that is
88 -- done automatically on exiting the scope of
89 -- 'block'.
90 block :: IO a -> IO a
91
92 -- | To re-enable asynchronous exceptions inside the scope of
93 -- 'block', 'unblock' can be
94 -- used.  It scopes in exactly the same way, so on exit from
95 -- 'unblock' asynchronous exception delivery will
96 -- be disabled again.
97 unblock :: IO a -> IO a
98
99 block (IO io) = IO $ blockAsyncExceptions# io
100 unblock (IO io) = IO $ unblockAsyncExceptions# io
101 \end{code}
102
103 \begin{code}
104 -- | Forces its argument to be evaluated, and returns the result in
105 -- the 'IO' monad.  It can be used to order evaluation with respect to
106 -- other 'IO' operations; its semantics are given by
107 --
108 -- >   evaluate undefined `seq` return ()  ==> return ()
109 -- >   catch (evaluate undefined) (\e -> return ())  ==> return ()
110 --
111 -- NOTE: @(evaluate a)@ is /not/ the same as @(a \`seq\` return a)@.
112 evaluate :: a -> IO a
113 evaluate a = IO $ \s -> case a `seq` () of () -> (# s, a #)
114         -- NB. can't write  
115         --      a `seq` (# s, a #)
116         -- because we can't have an unboxed tuple as a function argument
117 \end{code}