GHC/TopHandler.lhs

   1 \begin{code}
   2 {-# OPTIONS_HADDOCK hide #-}
   3 -----------------------------------------------------------------------------
   4 -- |
   5 -- Module      :  GHC.TopHandler
   6 -- Copyright   :  (c) The University of Glasgow, 2001-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 -- Support for catching exceptions raised during top-level computations
  14 -- (e.g. @Main.main@, 'Control.Concurrent.forkIO', and foreign exports)
  15 --
  16 -----------------------------------------------------------------------------
  17
  18 -- #hide
  19 module GHC.TopHandler (
  20    runMainIO, runIO, runIOFastExit, runNonIO, reportStackOverflow, reportError
  21   ) where
  22
  23 import Prelude
  24
  25 import System.IO
  26 import Control.Exception
  27
  28 import Foreign.C        ( CInt )
  29 import GHC.IOBase
  30 import GHC.Exception
  31 import GHC.Prim (unsafeCoerce#)
  32
  33 -- | 'runMainIO' is wrapped around 'Main.main' (or whatever main is
  34 -- called in the program).  It catches otherwise uncaught exceptions,
  35 -- and also flushes stdout\/stderr before exiting.
  36 runMainIO :: IO a -> IO a
  37 runMainIO main = (do a <- main; cleanUp; return a) `catchException` topHandler
  38
  39 -- | 'runIO' is wrapped around every @foreign export@ and @foreign
  40 -- import \"wrapper\"@ to mop up any uncaught exceptions.  Thus, the
  41 -- result of running 'System.Exit.exitWith' in a foreign-exported
  42 -- function is the same as in the main thread: it terminates the
  43 -- program.
  44 --
  45 runIO :: IO a -> IO a
  46 runIO main = catchException main topHandler
  47
  48 -- | Like 'runIO', but in the event of an exception that causes an exit,
  49 -- we don't shut down the system cleanly, we just exit.  This is
  50 -- useful in some cases, because the safe exit version will give other
  51 -- threads a chance to clean up first, which might shut down the
  52 -- system in a different way.  For example, try
  53 --
  54 --   main = forkIO (runIO (exitWith (ExitFailure 1))) >> threadDelay 10000
  55 --
  56 -- This will sometimes exit with "interrupted" and code 0, because the
  57 -- main thread is given a chance to shut down when the child thread calls
  58 -- safeExit.  There is a race to shut down between the main and child threads.
  59 --
  60 runIOFastExit :: IO a -> IO a
  61 runIOFastExit main = catchException main topHandlerFastExit
  62         -- NB. this is used by the testsuite driver
  63
  64 -- | The same as 'runIO', but for non-IO computations.  Used for
  65 -- wrapping @foreign export@ and @foreign import \"wrapper\"@ when these
  66 -- are used to export Haskell functions with non-IO types.
  67 --
  68 runNonIO :: a -> IO a
  69 runNonIO a = catchException (a `seq` return a) topHandler
  70
  71 topHandler :: Exception -> IO a
  72 topHandler err = catchException (real_handler safeExit err) topHandler
  73
  74 topHandlerFastExit :: Exception -> IO a
  75 topHandlerFastExit err =
  76   catchException (real_handler fastExit err) topHandlerFastExit
  77
  78 -- Make sure we handle errors while reporting the error!
  79 -- (e.g. evaluating the string passed to 'error' might generate
  80 --  another error, etc.)
  81 --
  82 real_handler :: (Int -> IO a) -> Exception -> IO a
  83 real_handler exit exn =
  84   cleanUp >>
  85   case exn of
  86         AsyncException StackOverflow -> do
  87            reportStackOverflow
  88            exit 2
  89
  90         -- only the main thread gets ExitException exceptions
  91         ExitException ExitSuccess     -> exit 0
  92         ExitException (ExitFailure n) -> exit n
  93
  94         other -> do
  95            reportError other
  96            exit 1
  97
  98
  99 reportStackOverflow :: IO a
 100 reportStackOverflow = do callStackOverflowHook; return undefined
 101
 102 reportError :: Exception -> IO a
 103 reportError ex = do
 104    handler <- getUncaughtExceptionHandler
 105    handler ex
 106    return undefined
 107
 108 -- SUP: Are the hooks allowed to re-enter Haskell land?  If so, remove
 109 -- the unsafe below.
 110 foreign import ccall unsafe "stackOverflow"
 111         callStackOverflowHook :: IO ()
 112
 113 -- try to flush stdout/stderr, but don't worry if we fail
 114 -- (these handles might have errors, and we don't want to go into
 115 -- an infinite loop).
 116 cleanUp :: IO ()
 117 cleanUp = do
 118   hFlush stdout `catchException` \_ -> return ()
 119   hFlush stderr `catchException` \_ -> return ()
 120
 121 cleanUpAndExit :: Int -> IO a
 122 cleanUpAndExit r = do cleanUp; safeExit r
 123
 124 -- we have to use unsafeCoerce# to get the 'IO a' result type, since the
 125 -- compiler doesn't let us declare that as the result type of a foreign export.
 126 safeExit :: Int -> IO a
 127 safeExit r = unsafeCoerce# (shutdownHaskellAndExit $ fromIntegral r)
 128
 129 -- NOTE: shutdownHaskellAndExit must be called "safe", because it *can*
 130 -- re-enter Haskell land through finalizers.
 131 foreign import ccall "Rts.h shutdownHaskellAndExit"
 132   shutdownHaskellAndExit :: CInt -> IO ()
 133
 134 fastExit :: Int -> IO a
 135 fastExit r = unsafeCoerce# (stg_exit (fromIntegral r))
 136
 137 foreign import ccall "Rts.h stg_exit"
 138   stg_exit :: CInt -> IO ()
 139 \end{code}