ghc-7.6.3: The GHC API

Safe Haskell | None

CoreMonad

Contents

- Configuration of the core-to-core passes
- Plugins
- Counting
- The monad
  - Reading from the monad
  - Writing to the monad
  - Lifting into the monad
  - Global initialization
  - Dealing with annotations
  - Debug output
  - Screen output
- Getting `Name`s

Synopsis

- data CoreToDo
  - = CoreDoSimplify Int SimplifierMode
  - | CoreDoPluginPass String PluginPass
  - | CoreDoFloatInwards
  - | CoreDoFloatOutwards FloatOutSwitches
  - | CoreLiberateCase
  - | CoreDoPrintCore
  - | CoreDoStaticArgs
  - | CoreDoStrictness
  - | CoreDoWorkerWrapper
  - | CoreDoSpecialising
  - | CoreDoSpecConstr
  - | CoreCSE
  - | CoreDoRuleCheck CompilerPhase String
  - | CoreDoVectorisation
  - | CoreDoNothing
  - | CoreDoPasses [CoreToDo]
  - | CoreDesugar
  - | CoreDesugarOpt
  - | CoreTidy
  - | CorePrep
- runWhen :: Bool -> CoreToDo -> CoreToDo
- runMaybe :: Maybe a -> (a -> CoreToDo) -> CoreToDo
- data SimplifierMode = SimplMode {
  - sm_names :: [String]
  - sm_phase :: CompilerPhase
  - sm_rules :: Bool
  - sm_inline :: Bool
  - sm_case_case :: Bool
  - sm_eta_expand :: Bool
  }
- data FloatOutSwitches = FloatOutSwitches {
  - floatOutLambdas :: Maybe Int
  - floatOutConstants :: Bool
  - floatOutPartialApplications :: Bool
  }
- dumpSimplPhase :: DynFlags -> SimplifierMode -> Bool
- pprPassDetails :: CoreToDo -> SDoc
- type PluginPass = ModGuts -> CoreM ModGuts
- data Plugin = Plugin {
  - installCoreToDos :: [CommandLineOption] -> [CoreToDo] -> CoreM [CoreToDo]
  }
- type CommandLineOption = String
- defaultPlugin :: Plugin
- bindsOnlyPass :: (CoreProgram -> CoreM CoreProgram) -> ModGuts -> CoreM ModGuts
- data SimplCount
- doSimplTick :: Tick -> SimplCount -> SimplCount
- doFreeSimplTick :: Tick -> SimplCount -> SimplCount
- simplCountN :: SimplCount -> Int
- pprSimplCount :: SimplCount -> SDoc
- plusSimplCount :: SimplCount -> SimplCount -> SimplCount
- zeroSimplCount :: DynFlags -> SimplCount
- isZeroSimplCount :: SimplCount -> Bool
- hasDetailedCounts :: SimplCount -> Bool
- data Tick
  - = PreInlineUnconditionally Id
  - | PostInlineUnconditionally Id
  - | UnfoldingDone Id
  - | RuleFired FastString
  - | LetFloatFromLet
  - | EtaExpansion Id
  - | EtaReduction Id
  - | BetaReduction Id
  - | CaseOfCase Id
  - | KnownBranch Id
  - | CaseMerge Id
  - | AltMerge Id
  - | CaseElim Id
  - | CaseIdentity Id
  - | FillInCaseDefault Id
  - | BottomFound
  - | SimplifierDone
- data CoreM a
- runCoreM :: HscEnv -> RuleBase -> UniqSupply -> Module -> CoreM a -> IO (a, SimplCount)
- getHscEnv :: CoreM HscEnv
- getRuleBase :: CoreM RuleBase
- getModule :: CoreM Module
- getDynFlags :: HasDynFlags m => m DynFlags
- getOrigNameCache :: CoreM OrigNameCache
- addSimplCount :: SimplCount -> CoreM ()
- liftIO :: MonadIO m => IO a -> m a
- liftIOWithCount :: IO (SimplCount, a) -> CoreM a
- liftIO1 :: MonadIO m => (a -> IO b) -> a -> m b
- liftIO2 :: MonadIO m => (a -> b -> IO c) -> a -> b -> m c
- liftIO3 :: MonadIO m => (a -> b -> c -> IO d) -> a -> b -> c -> m d
- liftIO4 :: MonadIO m => (a -> b -> c -> d -> IO e) -> a -> b -> c -> d -> m e
- reinitializeGlobals :: CoreM ()
- getAnnotations :: Typeable a => ([Word8] -> a) -> ModGuts -> CoreM (UniqFM [a])
- getFirstAnnotations :: Typeable a => ([Word8] -> a) -> ModGuts -> CoreM (UniqFM a)
- showPass :: DynFlags -> CoreToDo -> IO ()
- endPass :: DynFlags -> CoreToDo -> CoreProgram -> [CoreRule] -> IO ()
- dumpPassResult :: DynFlags -> Maybe DynFlag -> SDoc -> SDoc -> CoreProgram -> [CoreRule] -> IO ()
- lintPassResult :: DynFlags -> CoreToDo -> CoreProgram -> IO ()
- dumpIfSet :: DynFlags -> Bool -> CoreToDo -> SDoc -> SDoc -> IO ()
- putMsg :: SDoc -> CoreM ()
- putMsgS :: String -> CoreM ()
- errorMsg :: SDoc -> CoreM ()
- errorMsgS :: String -> CoreM ()
- fatalErrorMsg :: SDoc -> CoreM ()
- fatalErrorMsgS :: String -> CoreM ()
- debugTraceMsg :: SDoc -> CoreM ()
- debugTraceMsgS :: String -> CoreM ()
- dumpIfSet_dyn :: DynFlag -> String -> SDoc -> CoreM ()
- thNameToGhcName :: Name -> CoreM (Maybe Name)

# Configuration of the core-to-core passes

data CoreToDo

Constructors

CoreDoSimplify Int SimplifierMode |
CoreDoPluginPass String PluginPass |
CoreDoFloatInwards |
CoreDoFloatOutwards FloatOutSwitches |
CoreLiberateCase |
CoreDoPrintCore |
CoreDoStaticArgs |
CoreDoStrictness |
CoreDoWorkerWrapper |
CoreDoSpecialising |
CoreDoSpecConstr |
CoreCSE |
CoreDoRuleCheck CompilerPhase String |
CoreDoVectorisation |
CoreDoNothing |
CoreDoPasses [CoreToDo] |
CoreDesugar |
CoreDesugarOpt |
CoreTidy |
CorePrep |

Instances

Outputable CoreToDo |

runWhen :: Bool -> CoreToDo -> CoreToDo

runMaybe :: Maybe a -> (a -> CoreToDo) -> CoreToDo

data SimplifierMode

Constructors

SimplMode |

Fields

sm_names :: [String]
sm_phase :: CompilerPhase
sm_rules :: Bool
sm_inline :: Bool
sm_case_case :: Bool
sm_eta_expand :: Bool

Instances

Outputable SimplifierMode |

data FloatOutSwitches

Constructors

FloatOutSwitches |

Fields

floatOutLambdas :: Maybe Int

  Just n = float lambdas to top level, if doing so will abstract over n or fewer value variables Nothing = float all lambdas to top level, regardless of how many free variables Just 0 is the vanilla case: float a lambda iff it has no free vars

floatOutConstants :: Bool

  True = float constants to top level, even if they do not escape a lambda

floatOutPartialApplications :: Bool

  True = float out partial applications based on arity information.

Instances

Outputable FloatOutSwitches |

dumpSimplPhase :: DynFlags -> SimplifierMode -> Bool

pprPassDetails :: CoreToDo -> SDoc

# Plugins

type PluginPass = ModGuts -> CoreM ModGuts

A description of the plugin pass itself

data Plugin

`Plugin` is the core compiler plugin data type. Try to avoid constructing one of these directly, and just modify some fields of `defaultPlugin` instead: this is to try and preserve source-code compatability when we add fields to this.

Nonetheless, this API is preliminary and highly likely to change in the future.

Constructors

Plugin |

Fields

installCoreToDos :: [CommandLineOption] -> [CoreToDo] -> CoreM [CoreToDo]

  Modify the Core pipeline that will be used for compilation. This is called as the Core pipeline is built for every module being compiled, and plugins get the opportunity to modify the pipeline in a nondeterministic order.

type CommandLineOption = String

Command line options gathered from the -PModule.Name:stuff syntax are given to you as this type

defaultPlugin :: Plugin

Default plugin: does nothing at all! For compatability reasons you should base all your plugin definitions on this default value.

bindsOnlyPass :: (CoreProgram -> CoreM CoreProgram) -> ModGuts -> CoreM ModGuts

# Counting

data SimplCount

doSimplTick :: Tick -> SimplCount -> SimplCount

doFreeSimplTick :: Tick -> SimplCount -> SimplCount

simplCountN :: SimplCount -> Int

pprSimplCount :: SimplCount -> SDoc

plusSimplCount :: SimplCount -> SimplCount -> SimplCount

zeroSimplCount :: DynFlags -> SimplCount

isZeroSimplCount :: SimplCount -> Bool

hasDetailedCounts :: SimplCount -> Bool

data Tick

Constructors

PreInlineUnconditionally Id |
PostInlineUnconditionally Id |
UnfoldingDone Id |
RuleFired FastString |
LetFloatFromLet |
EtaExpansion Id |
EtaReduction Id |
BetaReduction Id |
CaseOfCase Id |
KnownBranch Id |
CaseMerge Id |
AltMerge Id |
CaseElim Id |
CaseIdentity Id |
FillInCaseDefault Id |
BottomFound |
SimplifierDone |

Instances

Eq Tick |
Ord Tick |
Outputable Tick |

# The monad

data CoreM a

The monad used by Core-to-Core passes to access common state, register simplification statistics and so on

Instances

Monad CoreM |
Functor CoreM |
MonadPlus IO => MonadPlus CoreM |
Applicative CoreM |
MonadIO CoreM |
MonadUnique CoreM |
HasDynFlags CoreM |
MonadThings CoreM |

runCoreM :: HscEnv -> RuleBase -> UniqSupply -> Module -> CoreM a -> IO (a, SimplCount)

## Reading from the monad

getHscEnv :: CoreM HscEnv

getRuleBase :: CoreM RuleBase

getModule :: CoreM Module

getDynFlags :: HasDynFlags m => m DynFlags

getOrigNameCache :: CoreM OrigNameCache

The original name cache is the current mapping from `Module` and `OccName` to a compiler-wide unique `Name`

## Writing to the monad

addSimplCount :: SimplCount -> CoreM ()

## Lifting into the monad

liftIO :: MonadIO m => IO a -> m a

liftIOWithCount :: IO (SimplCount, a) -> CoreM a

Lift an `IO` operation into `CoreM` while consuming its `SimplCount`

liftIO1 :: MonadIO m => (a -> IO b) -> a -> m b

Lift an `IO` operation with 1 argument into another monad

liftIO2 :: MonadIO m => (a -> b -> IO c) -> a -> b -> m c

Lift an `IO` operation with 2 arguments into another monad

liftIO3 :: MonadIO m => (a -> b -> c -> IO d) -> a -> b -> c -> m d

Lift an `IO` operation with 3 arguments into another monad

liftIO4 :: MonadIO m => (a -> b -> c -> d -> IO e) -> a -> b -> c -> d -> m e

Lift an `IO` operation with 4 arguments into another monad

## Global initialization

reinitializeGlobals :: CoreM ()

## Dealing with annotations

getAnnotations :: Typeable a => ([Word8] -> a) -> ModGuts -> CoreM (UniqFM [a])

Get all annotations of a given type. This happens lazily, that is no deserialization will take place until the [a] is actually demanded and the [a] can also be empty (the UniqFM is not filtered).

This should be done once at the start of a Core-to-Core pass that uses annotations.

See Note [Annotations]

getFirstAnnotations :: Typeable a => ([Word8] -> a) -> ModGuts -> CoreM (UniqFM a)

Get at most one annotation of a given type per Unique.

## Debug output

showPass :: DynFlags -> CoreToDo -> IO ()

endPass :: DynFlags -> CoreToDo -> CoreProgram -> [CoreRule] -> IO ()

dumpPassResult :: DynFlags -> Maybe DynFlag -> SDoc -> SDoc -> CoreProgram -> [CoreRule] -> IO ()

lintPassResult :: DynFlags -> CoreToDo -> CoreProgram -> IO ()

dumpIfSet :: DynFlags -> Bool -> CoreToDo -> SDoc -> SDoc -> IO ()

## Screen output

putMsg :: SDoc -> CoreM ()

Output a message to the screen

putMsgS :: String -> CoreM ()

Output a String message to the screen

errorMsg :: SDoc -> CoreM ()

Output an error to the screen

errorMsgS :: String -> CoreM ()

Output a string error to the screen

fatalErrorMsg :: SDoc -> CoreM ()

Output a fatal error to the screen. Note this does not by itself cause the compiler to die

fatalErrorMsgS :: String -> CoreM ()

Output a fatal string error to the screen. Note this does not by itself cause the compiler to die

debugTraceMsg :: SDoc -> CoreM ()

Outputs a debugging message at verbosity level of `-v` or higher

debugTraceMsgS :: String -> CoreM ()

Output a string debugging message at verbosity level of `-v` or higher

dumpIfSet_dyn :: DynFlag -> String -> SDoc -> CoreM ()

Show some labelled `SDoc` if a particular flag is set or at a verbosity level of `-v -ddump-most` or higher

# Getting `Name`s

thNameToGhcName :: Name -> CoreM (Maybe Name)

Attempt to convert a Template Haskell name to one that GHC can understand. Original TH names such as those you get when you use the `'foo` syntax will be translated to their equivalent GHC name exactly. Qualified or unqualifed TH names will be dynamically bound to names in the module being compiled, if possible. Exact TH names will be bound to the name they represent, exactly.