GHC.Linker.Loader

ghc-9.14.0.20251028: The GHC API

Safe Haskell | None
Language | GHC2021

GHC.Linker.Loader

Contents

- Load & Unload
- LoadedEnv
- Internals

Description

The loader

This module deals with the top-level issues of dynamic linking (loading), calling the object-code linker and the byte-code linker where necessary.

Synopsis

- newtype Loader = Loader {
  - loader_state :: MVar (Maybe LoaderState)
  }
- data LoaderState = LoaderState {
  - linker_env :: !LinkerEnv
  - bcos_loaded :: !LinkableSet
  - objs_loaded :: !LinkableSet
  - pkgs_loaded :: !PkgsLoaded
  - temp_sos :: ![(FilePath, String)]
  - linked_breaks :: !LinkedBreaks
  }
- initLoaderState :: Interp -> HscEnv -> IO ()
- uninitializedLoader :: IO Loader
- showLoaderState :: Interp -> IO SDoc
- getLoaderState :: Interp -> IO (Maybe LoaderState)
- loadDecls :: Interp -> HscEnv -> SrcSpan -> Linkable -> IO ([(Name, ForeignHValue)], [Linkable], PkgsLoaded)
- loadPackages :: Interp -> HscEnv -> [UnitId] -> IO ()
- loadModule :: Interp -> HscEnv -> Module -> IO ()
- loadCmdLineLibs :: Interp -> HscEnv -> IO ()
- loadName :: Interp -> HscEnv -> Name -> IO (ForeignHValue, [Linkable], PkgsLoaded)
- unload :: Interp -> HscEnv -> [Linkable] -> IO ()
- withExtendedLoadedEnv :: ExceptionMonad m => Interp -> [(Name, ForeignHValue)] -> m a -> m a
- extendLoadedEnv :: Interp -> [(Name, ForeignHValue)] -> IO ()
- deleteFromLoadedEnv :: Interp -> [Name] -> IO ()
- allocateBreakArrays :: Interp -> ModuleEnv (ForeignRef BreakArray) -> [InternalModBreaks] -> IO (ModuleEnv (ForeignRef BreakArray))
- rmDupLinkables :: LinkableSet -> [Linkable] -> (LinkableSet, [Linkable])
- modifyLoaderState :: Interp -> (LoaderState -> IO (LoaderState, a)) -> IO a
- initLinkDepsOpts :: HscEnv -> LinkDepsOpts
- getGccSearchDirectory :: Logger -> DynFlags -> String -> IO [FilePath]

# Documentation

newtype Loader Source #

Constructors

Loader |
Fields loader_state :: MVar (Maybe LoaderState)

data LoaderState Source #

Constructors

LoaderState |
Fields linker_env :: !LinkerEnv Current global mapping from Names to their true values bcos_loaded :: !LinkableSet The currently loaded interpreted modules (home package) objs_loaded :: !LinkableSet And the currently-loaded compiled modules (home package) pkgs_loaded :: !PkgsLoaded The currently-loaded packages; always object code haskell libraries, system libraries, transitive dependencies temp_sos :: ![(FilePath, String)] We need to remember the name of previous temporary DLL/.so libraries so we can link them (see #10322) linked_breaks :: !LinkedBreaks Mapping from loaded modules to their breakpoint arrays

initLoaderState :: Interp -> HscEnv -> IO () Source #

Initialise the dynamic linker. This entails

a) Calling the C initialisation procedure,

b) Loading any packages specified on the command line,

c) Loading any packages specified on the command line, now held in the `-l` options in `v_Opt_l`,

d) Loading any `.o/.dll` files specified on the command line, now held in `ldInputs`,

e) Loading any MacOS frameworks.

NOTE: This function is idempotent; if called more than once, it does nothing. This is useful in Template Haskell, where we call it before trying to link.

uninitializedLoader :: IO Loader Source #

showLoaderState :: Interp -> IO SDoc Source #

Display the loader state.

getLoaderState :: Interp -> IO (Maybe LoaderState) Source #

# Load & Unload

loadDecls :: Interp -> HscEnv -> SrcSpan -> Linkable -> IO ([(Name, ForeignHValue)], [Linkable], PkgsLoaded) Source #

loadPackages :: Interp -> HscEnv -> [UnitId] -> IO () Source #

Load exactly the specified packages, and their dependents (unless of course they are already loaded). The dependents are loaded automatically, and it doesn't matter what order you specify the input packages.

loadModule :: Interp -> HscEnv -> Module -> IO () Source #

loadCmdLineLibs :: Interp -> HscEnv -> IO () Source #

loadName :: Interp -> HscEnv -> Name -> IO (ForeignHValue, [Linkable], PkgsLoaded) Source #

Load the module containing the given Name and get its associated `HValue`.

Throws a `ProgramError` if loading fails or the name cannot be found.

unload Source #

Arguments

:: Interp |
-> HscEnv |
-> [Linkable] | The linkables to *keep*.
-> IO () |

Unloading old objects ready for a new compilation sweep.

The compilation manager provides us with a list of linkables that it considers "stable", i.e. won't be recompiled this time around. For each of the modules current linked in memory,

- if the linkable is stable (and it's the same one -- the user may have recompiled the module on the side), we keep it,
- otherwise, we unload it.
- we also implicitly unload all temporary bindings at this point.

# LoadedEnv

withExtendedLoadedEnv :: ExceptionMonad m => Interp -> [(Name, ForeignHValue)] -> m a -> m a Source #

Temporarily extend the loaded env.

extendLoadedEnv :: Interp -> [(Name, ForeignHValue)] -> IO () Source #

deleteFromLoadedEnv :: Interp -> [Name] -> IO () Source #

# Internals

allocateBreakArrays :: Interp -> ModuleEnv (ForeignRef BreakArray) -> [InternalModBreaks] -> IO (ModuleEnv (ForeignRef BreakArray)) Source #

Given a list of `InternalModBreaks` collected from a list of `CompiledByteCode`, allocate the `BreakArray` used to trigger breakpoints.

rmDupLinkables :: LinkableSet -> [Linkable] -> (LinkableSet, [Linkable]) Source #

modifyLoaderState :: Interp -> (LoaderState -> IO (LoaderState, a)) -> IO a Source #

initLinkDepsOpts :: HscEnv -> LinkDepsOpts Source #

getGccSearchDirectory :: Logger -> DynFlags -> String -> IO [FilePath] Source #