Changes between Version 22 and Version 23 of GhcApiStatus

Aug 28, 2008 9:17:58 PM (9 years ago)

Update API changes


  • GhcApiStatus

    v22 v23  
    1010= Current GHC API design =
    12 Most exported API functions that were previously in {{{IO}}} are now
    13 in the {{{Ghc}}} monad.  Those functions now no longer require a {{{Session}}}
    14 parameter.  To start a GHC API session you now use:
     12There were two main issues which were large cross-cutting concerns and, unfortunately, took up most of my time: (a) consistent error handling and (b) explicit passing around of a `Session`.
     14The latter issue is rather straightforward to fix by introducing a monad, however, functions expecting `IO` callbacks complicated things a little bit.  Consistent error handling is trickier.  I decided to use extensible exceptions which required some `#ifdef`s to properly bootstrap and some special `handle*` type functions to portably handle certain exceptions (akin to `handleGhcException`.)  But first, an overview:
     16A `GhcMonad` is a class, and a default datatype which implements it is the `Ghc` monad.  Most interface functions will be of type `GhcMonad m => ... -> m a`.  This should make it easier to use these functions in custom monads which most non-trivial clients will likely need.  Very simple clients can just reuse the `Ghc` monad.  The `GhcMonad` class is defined as follows:
     18class (MonadIO m, WarnLogMonad m, ExceptionMonad m) => GhcMonad m where
     19  getSession :: m HscEnv
     20  setSession :: HscEnv -> m ()
     23The three required classes ensure that: we can use `liftIO` to call `IO` actions inside the GHC monad, accumulate warnings, and handle (extensible) exceptions in that monad.  The three classes are defined as follows:
     25class Monad m => MonadIO m where   -- util/MonadUtils.hs
     26  liftIO :: IO a -> m a
     28type WarningMessages = Bag WarnMsg
     29class Monad m => WarnLogMonad m where -- main/HscTypes.lhs
     30  setWarnings  :: WarningMessages -> m ()
     31  getWarnings :: m WarningMessages
     32  -- An alternative interface with 'addWarnings' and 'clearWarnings'
     33  -- instead of 'setWarnings' may be nicer if we just want to dump
     34  -- warnings somewhere and not accumulate (in which case
     35  -- 'getWarnings' would always return the emptyBag)
     37class Monad m => ExceptionMonad m where -- utils/Exception.hs
     38  gcatch :: Exception e => m a -> (e -> m a) -> m a
     39  gbracket :: m a -> (a -> m b) -> (a -> m c) -> m c
     40  gfinally :: m a -> m b -> m a
     41  -- 'gfinally' and 'gbracket' may be implemented in terms of
     42  -- 'gcatch' if we add 'gblock' and 'gunblock'.
     43  -- The version for GHC < 6.9 also contains 'gcatchDyn'.
     46There are two GHC-API-specific exceptions:
     48data SourceError = SourceError ErrorMessages
     49data GhcApiError = GhcApiError SDoc
     51mkSrcErr :: ErrorMessages -> SourceError
     52srcErrorMessages :: SourceError -> ErrorMessages
     53mkApiErr :: SDoc -> GhcApiError
     56A source error corresponds to a problem with the compiled code and contains all accumulated error messages (but no warnings).  An API error is used to signal failure of an API call and replace many 'Maybe' results.  The choice wasn't always obvious.  In general API errors should be seldom, but catchable, i.e., they should be rare, but not entirely unexpected.  I guess, the choice which functions return which error needs some fine tuning.
     58The 'WarnLogMonad' does what it's name says.  It accumulate warnings, which can be queried with 'getWarnings' and 'clearWarnings'.  Deciding when to clear warnings is a bit delicate.  ATM, I provide a default function that should be invoked in case of a source error (i.e., compilation failure) which prints all errors and warnings and clears the accumulated warnings.
     60printExceptionAndWarnings :: GhcMonad m => SourceError -> m ()
     61printExceptionAndWarnings err = do
     62    let errs = srcErrorMessages err
     63    warns <- getWarnings
     64    dflags <- getSessionDynFlags
     65    liftIO $ printErrorsAndWarnings dflags (warns, errs)
     66    clearWarnings
     69To start a GHC API session you now use:
    1772withGhc :: Maybe FilePath  -- path to GHC library
    18         -> Maybe [String]  -- ^ Optional list of static flags.
    1973        -> Ghc a           -- ^ The action(s) to perform.
    2074        -> IO a
    2377The first parameter can be determined automatically with the ghc-path
    24 package.  The second is a set of "static" command line flags, for
    25 example, profiling options.  Having those part of the run function for
    26 the monad avoids complicated usage rules (e.g. before parseStaticFlags
    27 had to be called before {{{newSession}}}).
     80TODO: We miss a `GhcT` monad transformer and a init function for custom monads `initSession :: GhcMonad m => Maybe FilePath -> m a`.
     82== Callbacks ==
     84Most of GHC's internal IO callbacks have been changed to use the proper class, e.g., `(MonadIO m, ExceptionMonad m) => ... -> m a -> m a`.  However, this cannot be done for external functions with callbacks.  A particularly complicated case are the asynchronous (FFI-initiated) callbacks of the Readline package.  For this case I added two functions to reflect into and reify from the `IO` monad:
     86-- | Reflect a computation in the 'Ghc' monad into the 'IO' monad.
     88-- You can use this to call functions returning an action in the 'Ghc' monad
     89-- inside a 'IO' action.  This is needed for some (too restrictive) callback
     90-- arguments of some library functions:
     92-- > libFunc :: String -> (Int -> IO a) -> IO a
     93-- > ghcFunc :: Int -> Ghc a
     94-- >
     95-- > ghcFuncUsingLibFunc :: String -> Ghc a -> Ghc a
     96-- > ghcFuncUsingLibFunc str =
     97-- >   reifyGhc $ \s ->
     98-- >     libFunc $ \i -> do
     99-- >       reflectGhc (ghcFunc i) s
     101reflectGhc :: Ghc a -> Session -> IO a
     102reflectGhc m = unGhc m
     104-- > Dual to 'reflectGhc'.  See its documentation.
     105reifyGhc :: (Session -> IO a) -> Ghc a
     106reifyGhc act = Ghc $ act
     109== Interface Changes ==
    29111{{{load}}} and {{{setTarget}}} work like before.  {{{checkModule}}}