HORIZON HASKELLDocslts/ghc-10.0.xaa25b892026-10-10Search names, modules, packages, or :: a typeCtrl K

GHC 10.0.0.20260917 · lts/ghc-10.0.x · aa25b89 · 2026-10-10

Moduleghc-10.0.0.20260917GHC2024

GHC.Unit.External.Index

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 UnitInfos 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.

Also, see Note [Sharing UnitInfos across the UnitEnv] for more technical discussion about sharing UnitInfos.

  • 5 types
  • 28 values

The UnitIndexCache.

8 declarations
newtypenewtype UnitIndexCache
#

Mutable version of UnitIndex.

The UnitIndexCache ensures that all calls to initUnits will share the UnitInfo if it is possible.

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 that only one instance of wired-in units is used.

Memory Invariant: The UnitIndexCache is the root object for retaining fully-resolved UnitInfo. UnitState is expected to reference only UnitInfos from the UnitIndexCache. There is exactly one fully-resolved UnitInfo alive for each external unit per unit database.

A second instance may or may not be stored in the externalUnitDatabases, which represent the in-memory cache of the on-disk unit databases.

Constructors

UnitIndex

9 declarations
datadata UnitIndex
#

Global index for external units that can be shared across multiple HomeUnitEnvs.

Allows sharing of the WireMap and UnitInfos that are stored in the UnitState of each HomeUnitEnv.

See Note [Sharing UnitInfos across the UnitEnv] for details about memory usage.

GlobalUnitInfoMap

4 declarations
newtypenewtype GlobalUnitInfoMap
#

Like a UnitInfoMap but stores all UnitInfos.

It is keyed by the UnitId and the UnitInfos UnitAbiHash. In modern cabal, there should never be a conflict of UnitIds, as cabal hashes the Abi, dependency hashes, source hashes and more.

However, a user can choose a conflicting UnitId, causing a conflict after all. We use the UnitAbiHash for disambiguation. If both UnitId and UnitAbiHash are identical in separate unit databases, we can assume they are the same unit, according to the documentation of GHC.

GlobalUnitKey

4 declarations

Wired-in units

6 declarations

Reading external unit databases into the UnitIndexCache

2 declarations