GHC/Exception.lhs

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