2 {-# OPTIONS_GHC -XNoImplicitPrelude #-}
3 {-# OPTIONS_HADDOCK hide #-}
4 -----------------------------------------------------------------------------
6 -- Module : GHC.Exception
7 -- Copyright : (c) The University of Glasgow, 1998-2002
8 -- License : see libraries/base/LICENSE
10 -- Maintainer : cvs-ghc@haskell.org
11 -- Stability : internal
12 -- Portability : non-portable (GHC extensions)
14 -- Exceptions and exception-handling functions.
16 -----------------------------------------------------------------------------
20 ( module GHC.Exception,
21 Exception(..), AsyncException(..),
22 IOException(..), ArithException(..), ArrayException(..),
23 throw, throwIO, ioError )
30 %*********************************************************
32 \subsection{Primitive catch}
34 %*********************************************************
36 catchException used to handle the passing around of the state to the
37 action and the handler. This turned out to be a bad idea - it meant
38 that we had to wrap both arguments in thunks so they could be entered
39 as normal (remember IO returns an unboxed pair...).
43 catch# :: IO a -> (b -> IO a) -> IO a
45 (well almost; the compiler doesn't know about the IO newtype so we
46 have to work around that in the definition of catchException below).
49 catchException :: IO a -> (Exception -> IO a) -> IO a
50 catchException (IO m) k = IO $ \s -> catch# m (\ex -> unIO (k ex)) s
52 -- | The 'catch' function establishes a handler that receives any 'IOError'
53 -- raised in the action protected by 'catch'. An 'IOError' is caught by
54 -- the most recent handler established by 'catch'. These handlers are
55 -- not selective: all 'IOError's are caught. Exception propagation
56 -- must be explicitly provided in a handler by re-raising any unwanted
57 -- exceptions. For example, in
59 -- > f = catch g (\e -> if IO.isEOFError e then return [] else ioError e)
61 -- the function @f@ returns @[]@ when an end-of-file exception
62 -- (cf. 'System.IO.Error.isEOFError') occurs in @g@; otherwise, the
63 -- exception is propagated to the next outer handler.
65 -- When an exception propagates outside the main program, the Haskell
66 -- system prints the associated 'IOError' value and exits the program.
68 -- Non-I\/O exceptions are not caught by this variant; to catch all
69 -- exceptions, use 'Control.Exception.catch' from "Control.Exception".
70 catch :: IO a -> (IOError -> IO a) -> IO a
71 catch m k = catchException m handler
72 where handler (IOException err) = k err
73 handler other = throw other
77 %*********************************************************
79 \subsection{Controlling asynchronous exception delivery}
81 %*********************************************************
84 -- | Applying 'block' to a computation will
85 -- execute that computation with asynchronous exceptions
86 -- /blocked/. That is, any thread which
87 -- attempts to raise an exception in the current thread with 'Control.Exception.throwTo' will be
88 -- blocked until asynchronous exceptions are enabled again. There\'s
89 -- no need to worry about re-enabling asynchronous exceptions; that is
90 -- done automatically on exiting the scope of
93 -- Threads created by 'Control.Concurrent.forkIO' inherit the blocked
94 -- state from the parent; that is, to start a thread in blocked mode,
95 -- use @block $ forkIO ...@. This is particularly useful if you need to
96 -- establish an exception handler in the forked thread before any
97 -- asynchronous exceptions are received.
100 -- | To re-enable asynchronous exceptions inside the scope of
101 -- 'block', 'unblock' can be
102 -- used. It scopes in exactly the same way, so on exit from
103 -- 'unblock' asynchronous exception delivery will
104 -- be disabled again.
105 unblock :: IO a -> IO a
107 block (IO io) = IO $ blockAsyncExceptions# io
108 unblock (IO io) = IO $ unblockAsyncExceptions# io
112 -- | Forces its argument to be evaluated when the resultant 'IO' action
113 -- is executed. It can be used to order evaluation with respect to
114 -- other 'IO' operations; its semantics are given by
116 -- > evaluate x `seq` y ==> y
117 -- > evaluate x `catch` f ==> (return $! x) `catch` f
118 -- > evaluate x >>= f ==> (return $! x) >>= f
120 -- /Note:/ the first equation implies that @(evaluate x)@ is /not/ the
121 -- same as @(return $! x)@. A correct definition is
123 -- > evaluate x = (return $! x) >>= return
125 evaluate :: a -> IO a
126 evaluate a = IO $ \s -> case a `seq` () of () -> (# s, a #)
128 -- a `seq` (# s, a #)
129 -- because we can't have an unboxed tuple as a function argument