GHC/Exception.lhs

   1 \begin{code}
   2 {-# OPTIONS_GHC -XNoImplicitPrelude #-}
   3 {-# OPTIONS_HADDOCK hide #-}
   4 -----------------------------------------------------------------------------
   5 -- |
   6 -- Module      :  GHC.Exception
   7 -- Copyright   :  (c) The University of Glasgow, 1998-2002
   8 -- License     :  see libraries/base/LICENSE
   9 --
  10 -- Maintainer  :  cvs-ghc@haskell.org
  11 -- Stability   :  internal
  12 -- Portability :  non-portable (GHC extensions)
  13 --
  14 -- Exceptions and exception-handling functions.
  15 --
  16 -----------------------------------------------------------------------------
  17
  18 -- #hide
  19 module GHC.Exception
  20         ( module GHC.Exception,
  21           Exception(..), AsyncException(..),
  22           IOException(..), ArithException(..), ArrayException(..),
  23           throw, throwIO, ioError )
  24   where
  25
  26 import GHC.Base
  27 import GHC.IOBase
  28 \end{code}
  29
  30 %*********************************************************
  31 %*                                                      *
  32 \subsection{Primitive catch}
  33 %*                                                      *
  34 %*********************************************************
  35
  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...).
  40
  41 Now catch# has type
  42
  43     catch# :: IO a -> (b -> IO a) -> IO a
  44
  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).
  47
  48 \begin{code}
  49 catchException :: IO a -> (Exception -> IO a) -> IO a
  50 catchException (IO m) k =  IO $ \s -> catch# m (\ex -> unIO (k ex)) s
  51
  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
  58 --
  59 -- > f = catch g (\e -> if IO.isEOFError e then return [] else ioError e)
  60 --
  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.
  64 --
  65 -- When an exception propagates outside the main program, the Haskell
  66 -- system prints the associated 'IOError' value and exits the program.
  67 --
  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
  74 \end{code}
  75
  76
  77 %*********************************************************
  78 %*                                                      *
  79 \subsection{Controlling asynchronous exception delivery}
  80 %*                                                      *
  81 %*********************************************************
  82
  83 \begin{code}
  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
  91 -- 'block'.
  92 --
  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.
  98 block :: IO a -> IO a
  99
 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
 106
 107 block (IO io) = IO $ blockAsyncExceptions# io
 108 unblock (IO io) = IO $ unblockAsyncExceptions# io
 109
 110 -- | returns True if asynchronous exceptions are blocked in the
 111 -- current thread.
 112 blocked :: IO Bool
 113 blocked = IO $ \s -> case asyncExceptionsBlocked# s of
 114                         (# s', i #) -> (# s', i /=# 0# #)
 115 \end{code}
 116
 117 \begin{code}
 118 -- | Forces its argument to be evaluated when the resultant 'IO' action
 119 -- is executed.  It can be used to order evaluation with respect to
 120 -- other 'IO' operations; its semantics are given by
 121 --
 122 -- >   evaluate x `seq` y    ==>  y
 123 -- >   evaluate x `catch` f  ==>  (return $! x) `catch` f
 124 -- >   evaluate x >>= f      ==>  (return $! x) >>= f
 125 --
 126 -- /Note:/ the first equation implies that @(evaluate x)@ is /not/ the
 127 -- same as @(return $! x)@.  A correct definition is
 128 --
 129 -- >   evaluate x = (return $! x) >>= return
 130 --
 131 evaluate :: a -> IO a
 132 evaluate a = IO $ \s -> case a `seq` () of () -> (# s, a #)
 133         -- NB. can't write
 134         --      a `seq` (# s, a #)
 135         -- because we can't have an unboxed tuple as a function argument
 136 \end{code}