Hannes Siebenhandl pushed to branch wip/fendor/external-unit-db-cache at Glasgow Haskell Compiler / GHC Commits: af0bf825 by fendor at 2026-07-22T11:06:52+02:00 Fixup: improve docs - - - - - 8e372d55 by fendor at 2026-07-22T11:07:22+02:00 Fixup: Add graph showing the relation between external Unit types - - - - - 2 changed files: - compiler/GHC/Unit/External/Index.hs - compiler/GHC/Unit/State.hs Changes: ===================================== compiler/GHC/Unit/External/Index.hs ===================================== @@ -1,3 +1,43 @@ +-- | The 'UnitIndex' is a 'UnitEnv' wide data structure that shares +-- external unit information across the 'UnitState' of all home units +-- (e.g., 'HomeUnitEnv') in a particular 'UnitEnv'. +-- +-- It caches already read unit databases, all processed 'UnitInfo's and +-- the 'WireMap'. +-- +-- This module is meant to be imported as @Index@. +-- +-- A short overview of how the different types here related to 'UnitState', 'UnitEnv' +-- and the 'HomeUnitEnv'. +-- +-- ┌─────────┐ +-- │ UnitEnv │ +-- └────┬────┘ +-- ├───────────────────────┐ +-- │ │ +-- ┌────▼──────┐ ┌─────▼─────┐ +-- │HomeUnitEnv│ │ UnitIndex ├────────────────┐ +-- └────┬──────┘ └───────────┘ │ +-- │ │ +-- │ Reads cached unit DBs │ +-- ┌────▼──────┐ ┌─────────────────────┐ │ +-- │ UnitState ├──────────>ExternalUnitDatabases◄──────┤ +-- └────┬──┬───┘ └─────────────────────┘ │ +-- │ └───────────────────────┐ │ +-- │ Writes new UnitInfos │ │ +-- │ during initialisation │ │ +-- ┌────▼────────┐ ┌────────v──────────┐ │ +-- │ UnitInfoMap │ │ GlobalUnitInfoMap ◄────────┘ +-- └────┬────────┘ └────────^──────────┘ +-- │ │ +-- └──────────────────────────┘ +-- UnitInfoMap references +-- GlobalUnitInfoMap values +-- (All UnitInfos are shared) +-- +-- Open arrow @A ───> B@: A uses B. +-- Closed arrow @A ◄─── B@: A is a field of B. +-- module GHC.Unit.External.Index ( -- * The 'UnitIndexCache'. -- A mutable wrapper around 'UnitIndex' @@ -71,8 +111,8 @@ import Data.Maybe (catMaybes) -- The 'UnitIndexCache' ensures that all calls to 'initUnits' will -- share the 'UnitInfo' if it is possible. -- --- To share the 'UnitInfo', it needs to be fully-resolved, i.e., its wired-in --- dependencies and modules need to be resolved. +-- To share the 'UnitInfo', the 'UnitInfo' needs to be fully-resolved, i.e., its wired-in +-- dependencies and modules need to be replaced with the 'UnitId' of the wired-in unit. -- Thus, the 'UnitIndexCache' caches both the global 'WireMap' and the 'UnitInfoMap'. -- -- The 'WireMap' is globally valid, as other parts of the compiler rely on the fact ===================================== compiler/GHC/Unit/State.hs ===================================== @@ -287,14 +287,16 @@ Note [Sharing 'UnitInfo's across the 'UnitEnv'] The 'UnitState' and 'UnitIndex' are closely related. The 'UnitState' stores all information about the external units referenced by -a single HomeUnitEnv. -This includes in particular the 'unitInfoMap', an in-memory representation of +a single 'HomeUnitEnv'. +As a reminder, the 'HomeUnitEnv' stores all information specific to a single home unit, +such as the 'HomePackageTable', 'DynFlags' and the 'UnitState'. +The 'UnitState' retains the 'unitInfoMap', an in-memory representation of the unit databases that a 'HomeUnitEnv' depends on. -Multiple home units can depend on the same unit database, leading to a linear -increase of 'UnitInfo's per 'HomeUnitEnv'. (It used to be quadratic even, due -to accidentally retaining old 'UnitInfo's.) -Thus, we want to share the 'UnitInfo' across multiple 'HomeUnitEnv's. -This where the 'UnitIndex' is needed. +Multiple home units can depend on the same unit database, and reference the same +'UnitInfo's across the GHC session. +We share all 'UnitInfo's across multiple 'HomeUnitEnv's, saving a lot of +duplication of the same 'UnitInfo'. +This what the 'UnitIndex' takes care of. The 'UnitIndex' stores all fully-resolved 'UnitInfo's that can be referenced by the 'UnitState'.'unitInfoMap'. @@ -316,6 +318,9 @@ One instance is stored in 'ExternalUnitDatabases' where variables are resolved, but the wired-in units haven't been resolved. The second instance is the fully-resolved 'UnitInfo' stored in the 'UnitIndex'. + +See the module documentation for 'GHC.Unit.External.Index' for an overview +of how the types relate to each other. -} -- | The 'UnitState' contains a plethora of information local to a single 'HomeUnitEnv'. View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/compare/97fad109104262f5bf28581a38cec67... -- View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/compare/97fad109104262f5bf28581a38cec67... You're receiving this email because of your account on gitlab.haskell.org. Manage all notifications: https://gitlab.haskell.org/-/profile/notifications | Help: https://gitlab.haskell.org/help