Hannes Siebenhandl pushed to branch wip/fendor/external-unit-db-cache at Glasgow Haskell Compiler / GHC
Commits:
2 changed files:
Changes:
| 1 | +-- | The 'UnitIndex' is a 'UnitEnv' wide data structure that shares
|
|
| 2 | +-- external unit information across the 'UnitState' of all home units
|
|
| 3 | +-- (e.g., 'HomeUnitEnv') in a particular 'UnitEnv'.
|
|
| 4 | +--
|
|
| 5 | +-- It caches already read unit databases, all processed 'UnitInfo's and
|
|
| 6 | +-- the 'WireMap'.
|
|
| 7 | +--
|
|
| 8 | +-- This module is meant to be imported as @Index@.
|
|
| 9 | +--
|
|
| 10 | +-- A short overview of how the different types here related to 'UnitState', 'UnitEnv'
|
|
| 11 | +-- and the 'HomeUnitEnv'.
|
|
| 12 | +--
|
|
| 13 | +-- ┌─────────┐
|
|
| 14 | +-- │ UnitEnv │
|
|
| 15 | +-- └────┬────┘
|
|
| 16 | +-- ├───────────────────────┐
|
|
| 17 | +-- │ │
|
|
| 18 | +-- ┌────▼──────┐ ┌─────▼─────┐
|
|
| 19 | +-- │HomeUnitEnv│ │ UnitIndex ├────────────────┐
|
|
| 20 | +-- └────┬──────┘ └───────────┘ │
|
|
| 21 | +-- │ │
|
|
| 22 | +-- │ Reads cached unit DBs │
|
|
| 23 | +-- ┌────▼──────┐ ┌─────────────────────┐ │
|
|
| 24 | +-- │ UnitState ├──────────>ExternalUnitDatabases◄──────┤
|
|
| 25 | +-- └────┬──┬───┘ └─────────────────────┘ │
|
|
| 26 | +-- │ └───────────────────────┐ │
|
|
| 27 | +-- │ Writes new UnitInfos │ │
|
|
| 28 | +-- │ during initialisation │ │
|
|
| 29 | +-- ┌────▼────────┐ ┌────────v──────────┐ │
|
|
| 30 | +-- │ UnitInfoMap │ │ GlobalUnitInfoMap ◄────────┘
|
|
| 31 | +-- └────┬────────┘ └────────^──────────┘
|
|
| 32 | +-- │ │
|
|
| 33 | +-- └──────────────────────────┘
|
|
| 34 | +-- UnitInfoMap references
|
|
| 35 | +-- GlobalUnitInfoMap values
|
|
| 36 | +-- (All UnitInfos are shared)
|
|
| 37 | +--
|
|
| 38 | +-- Open arrow @A ───> B@: A uses B.
|
|
| 39 | +-- Closed arrow @A ◄─── B@: A is a field of B.
|
|
| 40 | +--
|
|
| 1 | 41 | module GHC.Unit.External.Index (
|
| 2 | 42 | -- * The 'UnitIndexCache'.
|
| 3 | 43 | -- A mutable wrapper around 'UnitIndex'
|
| ... | ... | @@ -71,8 +111,8 @@ import Data.Maybe (catMaybes) |
| 71 | 111 | -- The 'UnitIndexCache' ensures that all calls to 'initUnits' will
|
| 72 | 112 | -- share the 'UnitInfo' if it is possible.
|
| 73 | 113 | --
|
| 74 | --- To share the 'UnitInfo', it needs to be fully-resolved, i.e., its wired-in
|
|
| 75 | --- dependencies and modules need to be resolved.
|
|
| 114 | +-- To share the 'UnitInfo', the 'UnitInfo' needs to be fully-resolved, i.e., its wired-in
|
|
| 115 | +-- dependencies and modules need to be replaced with the 'UnitId' of the wired-in unit.
|
|
| 76 | 116 | -- Thus, the 'UnitIndexCache' caches both the global 'WireMap' and the 'UnitInfoMap'.
|
| 77 | 117 | --
|
| 78 | 118 | -- The 'WireMap' is globally valid, as other parts of the compiler rely on the fact
|
| ... | ... | @@ -287,14 +287,16 @@ Note [Sharing 'UnitInfo's across the 'UnitEnv'] |
| 287 | 287 | The 'UnitState' and 'UnitIndex' are closely related.
|
| 288 | 288 | |
| 289 | 289 | The 'UnitState' stores all information about the external units referenced by
|
| 290 | -a single HomeUnitEnv.
|
|
| 291 | -This includes in particular the 'unitInfoMap', an in-memory representation of
|
|
| 290 | +a single 'HomeUnitEnv'.
|
|
| 291 | +As a reminder, the 'HomeUnitEnv' stores all information specific to a single home unit,
|
|
| 292 | +such as the 'HomePackageTable', 'DynFlags' and the 'UnitState'.
|
|
| 293 | +The 'UnitState' retains the 'unitInfoMap', an in-memory representation of
|
|
| 292 | 294 | the unit databases that a 'HomeUnitEnv' depends on.
|
| 293 | -Multiple home units can depend on the same unit database, leading to a linear
|
|
| 294 | -increase of 'UnitInfo's per 'HomeUnitEnv'. (It used to be quadratic even, due
|
|
| 295 | -to accidentally retaining old 'UnitInfo's.)
|
|
| 296 | -Thus, we want to share the 'UnitInfo' across multiple 'HomeUnitEnv's.
|
|
| 297 | -This where the 'UnitIndex' is needed.
|
|
| 295 | +Multiple home units can depend on the same unit database, and reference the same
|
|
| 296 | +'UnitInfo's across the GHC session.
|
|
| 297 | +We share all 'UnitInfo's across multiple 'HomeUnitEnv's, saving a lot of
|
|
| 298 | +duplication of the same 'UnitInfo'.
|
|
| 299 | +This what the 'UnitIndex' takes care of.
|
|
| 298 | 300 | |
| 299 | 301 | The 'UnitIndex' stores all fully-resolved 'UnitInfo's that can be referenced
|
| 300 | 302 | by the 'UnitState'.'unitInfoMap'.
|
| ... | ... | @@ -316,6 +318,9 @@ One instance is stored in 'ExternalUnitDatabases' where variables are resolved, |
| 316 | 318 | but the wired-in units haven't been resolved.
|
| 317 | 319 | |
| 318 | 320 | The second instance is the fully-resolved 'UnitInfo' stored in the 'UnitIndex'.
|
| 321 | + |
|
| 322 | +See the module documentation for 'GHC.Unit.External.Index' for an overview
|
|
| 323 | +of how the types relate to each other.
|
|
| 319 | 324 | -}
|
| 320 | 325 | |
| 321 | 326 | -- | The 'UnitState' contains a plethora of information local to a single 'HomeUnitEnv'.
|