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