Moduleghc-10.0.0.20260917GHC2024

GHC.Unit.Home.Graph

A HomeUnitGraph (HUG) collects information about all the home units. Crucially, each node in a HomeUnitGraph includes a HomePackageTable.

Often, we don't want to query just a single HomePackageTable, but rather all HomePackageTables of all home units.

This module is responsible for maintaining this bridge between querying all home units vs querying the home package table directly. Think lookupHug vs lookupHpt, hugAllInstances vs hptAllInstances, where the hug version replies with information from all home units, and the hpt version with information pertaining to a single home unit.

Meant to be imported qualified as HUG. Example usage:

import GHC.Unit.Home.Graph (HomeUnitGraph, HomeUnitEnv)
import qualified GHC.Unit.Home.Graph as HUG
usage = ... HUG.insertHug hug uid modname modinfo ...

3 types
32 values

Packageghc-10.0.0.20260917
Exports35
LanguageGHC2024
LicenceBSD-3-Clause
SourceGraph.hs

typetype HomeUnitGraph = UnitEnvGraph HomeUnitEnv

datadata HomeUnitEnv

Constructors

HomeUnitEnv
- homeUnitEnv_units :: !UnitState
  External units
- homeUnitEnv_dflags :: DynFlags
  The dynamic flag settings
- homeUnitEnv_hpt :: HomePackageTable
  The home package table describes already-compiled home-package modules, excluding the module we are compiling right now. (In one-shot mode the current module is the only home-package module, so homeUnitEnv_hpt is empty. All other modules count as "external-package" modules. However, even in GHCi mode, hi-boot interfaces are demand-loaded into the external-package table.)
  homeUnitEnv_hpt is not mutable because we only demand-load external packages; the home package is eagerly loaded, module by module, by the compilation manager.
  The HPT may contain modules compiled earlier by --make but not actually below the current module in the dependency graph.
  (This changes a previous invariant: changed Jan 05.)
- homeUnitEnv_home_unit :: !Maybe HomeUnit
  Home-unit

valuemkHomeUnitEnv

Operations

5 declarations

valueaddHomeModInfoToHug :: HomeModInfo -> HomeUnitGraph -> IO ()

Add an entry to the HomePackageTable under the unit of that entry.

valuerestrictHug :: [(UnitId, [HomeModInfo])] -> HomeUnitGraph -> IO ()

Thin each HPT variable to only contain keys from the given dependencies. This is used at the end of upsweep to make sure that only completely successfully loaded modules are visible for subsequent operations.

valuerenameUnitId :: UnitId -> UnitId -> HomeUnitGraph -> Maybe HomeUnitGraph

Rename a unit id in the HomeUnitGraph

renameUnitId oldUnit newUnit hug, if oldUnit is not found in hug, returns Nothing. If it exists, the result maps newUnit to the HomeUnitEnv of the oldUnit (and oldUnit is removed from hug)

valueallUnits :: HomeUnitGraph -> Set UnitId

Retrieve all UnitIds of units in the HomeUnitGraph.

valueupdateUnitFlags

Set the DynFlags of the HomeUnitEnv for unit in the HomeModuleGraph

Lookups

valuelookupHug :: HomeUnitGraph -> UnitId -> ModuleName -> IO (Maybe HomeModInfo)

Lookup the HomeModInfo of a Module in the HomeUnitGraph given its UnitId and ModuleName (via the HomePackageTable of the corresponding unit)

valuelookupHugByModule :: Module -> HomeUnitGraph -> IO (Maybe HomeModInfo)

Lookup the HomeModInfo of a Module in the HomeUnitGraph (via the HomePackageTable of the corresponding unit)

valuelookupHugUnit :: Unit -> HomeUnitGraph -> Maybe HomeUnitEnv

Lookup up the HomeUnitEnv by the Unit in the HomeUnitGraph. If the Unit can be turned into a UnitId, we behave identical to lookupHugUnitId.

A HoleUnit is never part of the HomeUnitGraph, only instantiated Units

valuelookupHugUnitId :: UnitId -> HomeUnitGraph -> Maybe HomeUnitEnv

Lookup a HomeUnitEnv by UnitId in a HomeUnitGraph

valuelookupAllHug :: HomeUnitGraph -> ModuleName -> IO [HomeModInfo]

Lookup all HomeModInfo that have the same ModuleName as the given ModuleName. ModuleNames are not unique in the case of multiple home units, so there can be more than one possible HomeModInfo.

You should always prefer lookupHug and lookupHugByModule when possible.

valuememberHugUnit :: Unit -> HomeUnitGraph -> Bool

Check whether the Unit is present in the HomeUnitGraph

A HoleUnit is never part of the HomeUnitGraph, only instantiated Units

valuememberHugUnitId :: UnitId -> HomeUnitGraph -> Bool

Check whether the UnitId is present in the HomeUnitGraph

Reachability

valuetransitiveHomeDeps :: UnitId -> HomeUnitGraph -> Maybe [UnitId]

Compute the transitive closure of a unit in the HomeUnitGraph. If the argument unit is not present in the graph returns Nothing.

Very important queries

4 declarations

valueallInstances :: HomeUnitGraph -> IO (InstEnv, [FamInst])

Find all the instance declarations (of classes and families) from the Home Package Table filtered by the provided predicate function. Used in tcRnImports, to select the instances that are in the transitive closure of imports from the currently compiled module.

valueallFamInstances :: HomeUnitGraph -> IO (ModuleEnv FamInstEnv)

valueallAnns :: HomeUnitGraph -> IO AnnEnv

valueallCompleteSigs :: HomeUnitGraph -> IO CompleteMatches

Get all CompleteMatches (arising from COMPLETE pragmas) present across all home units.

Utilities

2 declarations

valuehugSCCs :: HomeUnitGraph -> [SCC UnitId]

valuehugFromList :: [(UnitId, HomeUnitEnv)] -> HomeUnitGraph

Printing

valuepprHomeUnitGraph :: HomeUnitGraph -> IO SDoc

valuepprHomeUnitEnv :: UnitId -> HomeUnitEnv -> IO SDoc

Auxiliary internal structure

11 declarations

newtypenewtype UnitEnvGraph v

Constructors

UnitEnvGraph
- unitEnv_graph :: Map UnitEnvGraphKey v

Instances3Functor, Foldable, Traversable

Functor UnitEnvGraphDefined in ghc-10.0.0.20260917 · GHC.Unit.Home.Graph
Foldable UnitEnvGraphDefined in ghc-10.0.0.20260917 · GHC.Unit.Home.Graph
Traversable UnitEnvGraphDefined in ghc-10.0.0.20260917 · GHC.Unit.Home.Graph

valueunitEnv_lookup_maybe :: UnitEnvGraphKey -> UnitEnvGraph v -> Maybe v

valueunitEnv_foldWithKey

:: b -> UnitEnvGraphKey -> a -> b
-> b
-> UnitEnvGraph a
-> b

valueunitEnv_singleton :: UnitEnvGraphKey -> v -> UnitEnvGraph v

valueunitEnv_adjust

:: v -> v
-> UnitEnvGraphKey
-> UnitEnvGraph v
-> UnitEnvGraph v

valueunitEnv_keys :: UnitEnvGraph v -> Set UnitEnvGraphKey

valueunitEnv_insert :: UnitEnvGraphKey -> v -> UnitEnvGraph v -> UnitEnvGraph v

valueunitEnv_new :: Map UnitEnvGraphKey v -> UnitEnvGraph v

valueunitEnv_lookup :: UnitEnvGraphKey -> UnitEnvGraph v -> v

valueunitEnv_traverseWithKey

:: Applicative f
=> UnitEnvGraphKey -> a -> f b
-> UnitEnvGraph a
-> f (UnitEnvGraph b)

valueunitEnv_assocs :: UnitEnvGraph a -> [(UnitEnvGraphKey, a)]