ghc-9.10.3: The GHC API

Safe Haskell | None
Language | GHC2021

GHC.Runtime.Loader

Contents

- Loading plugins
- Force loading information
- Finding names
- Loading values

Description

Dynamically lookup up values from modules and loading them.

Synopsis

- initializePlugins :: HscEnv -> IO HscEnv
- initializeSessionPlugins :: GhcMonad m => m ()
- loadFrontendPlugin :: HscEnv -> ModuleName -> IO (FrontendPlugin, [Linkable], PkgsLoaded)
- forceLoadModuleInterfaces :: HscEnv -> SDoc -> [Module] -> IO ()
- forceLoadNameModuleInterface :: HscEnv -> SDoc -> Name -> IO ()
- forceLoadTyCon :: HscEnv -> Name -> IO TyCon
- lookupRdrNameInModuleForPlugins :: HasDebugCallStack => HscEnv -> ModuleName -> RdrName -> IO (Maybe (Name, ModIface))
- getValueSafely :: HscEnv -> Name -> Type -> IO (Either Type (a, [Linkable], PkgsLoaded))
- getHValueSafely :: Interp -> HscEnv -> Name -> Type -> IO (Either Type (HValue, [Linkable], PkgsLoaded))
- lessUnsafeCoerce :: Logger -> String -> a -> IO b

# Documentation

initializePlugins :: HscEnv -> IO HscEnv Source #

Loads the plugins specified in the pluginModNames field of the dynamic flags. Should be called after command line arguments are parsed, but before actual compilation starts. Idempotent operation. Should be re-called if pluginModNames or pluginModNameOpts changes.

initializeSessionPlugins :: GhcMonad m => m () Source #

Initialise plugins specified by the current DynFlags and update the session.

# Loading plugins

loadFrontendPlugin :: HscEnv -> ModuleName -> IO (FrontendPlugin, [Linkable], PkgsLoaded) Source #

# Force loading information

forceLoadModuleInterfaces :: HscEnv -> SDoc -> [Module] -> IO () Source #

Force the interfaces for the given modules to be loaded. The `SDoc` parameter is used for debugging (`-ddump-if-trace`) only: it is shown as the reason why the module is being loaded.

forceLoadNameModuleInterface :: HscEnv -> SDoc -> Name -> IO () Source #

Force the interface for the module containing the name to be loaded. The `SDoc` parameter is used for debugging (`-ddump-if-trace`) only: it is shown as the reason why the module is being loaded.

forceLoadTyCon :: HscEnv -> Name -> IO TyCon Source #

Load the `TyCon` associated with the given name, come hell or high water. Fails if:

- The interface could not be loaded
- The name is not that of a `TyCon`
- The name did not exist in the loaded module

# Finding names

lookupRdrNameInModuleForPlugins :: HasDebugCallStack => HscEnv -> ModuleName -> RdrName -> IO (Maybe (Name, ModIface)) Source #

Finds the `Name` corresponding to the given `RdrName` in the context of the `ModuleName`. Returns `Nothing` if no such `Name` could be found. Any other condition results in an exception:

- If the module could not be found
- If we could not determine the imports of the module

Can only be used for looking up names while loading plugins (and is *not* suitable for use within plugins). The interface file is loaded very partially: just enough that it can be used, without its rules and instances affecting (and being linked from!) the module being compiled. This was introduced by 57d6798.

Need the module as well to record information in the interface file

# Loading values

getValueSafely :: HscEnv -> Name -> Type -> IO (Either Type (a, [Linkable], PkgsLoaded)) Source #

Loads the value corresponding to a `Name` if that value has the given `Type`. This only provides limited safety in that it is up to the user to ensure that that type corresponds to the type you try to use the return value at!

If the value found was not of the correct type, returns `Left actual_type`. Any other condition results in an exception:

- If we could not load the names module
- If the thing being loaded is not a value
- If the Name does not exist in the module
- If the link failed

getHValueSafely :: Interp -> HscEnv -> Name -> Type -> IO (Either Type (HValue, [Linkable], PkgsLoaded)) Source #

lessUnsafeCoerce :: Logger -> String -> a -> IO b Source #

Coerce a value as usual, but:

1) Evaluate it immediately to get a segfault early if the coercion was wrong

2) Wrap it in some debug messages at verbosity 3 or higher so we can see what happened if it does segfault