+basicKnownKeyTable :: [(OccName, Unique)]

+basicKnownKeyTable

+thKnownKeyTable :: [(OccName,Unique)]

+thKnownKeyTable = []

+        knownKeyOccMap, knownKeyUniqMap,

+import GHC.Builtin.Names.TH ( templateHaskellNames, thKnownKeyTable )

+knownKeyOccMap = mkOccEnv (basicKnownKeyTable ++ thKnownKeyTable)

+

+knownKeyUniqMap :: UniqFM Unique OccName

+knownKeyUniqMap = listToUFM [ (uniq, occ)

+                            | (occ, uniq) <- basicKnownKeyTable ++ thKnownKeyTable ]

+data KnotVars a = KnotVars { kv_domain :: [Module]

+                                  -- Domain of kv_lookup

+                                  -- See Note [KnotVars: Why store the domain?]

+

+                                  -- Invariant: kv_lookup is surjective relative to kv_domain

+  LangExt.DefinesKnownKeyNames -> "DefinesKnownKeyNames"

+import GHC.Iface.Load( lookupKnownKeyThing )

+

+import qualified GHC.LanguageExtensions as LangExt

+

+import GHC.Data.Maybe

+                           , if_rec_types = KnotVars [mod] knot_var_fun }

+                  -- Failing tests here are `ghci` and `T11985` if you get this wrong.

+                  -- This is very very "at a distance" because the reason for this check

+                  -- is that the type_env in interactive mode is the smushed together

+                  -- of all the interactive modules.

+                  -- See Note [Why is KnotVars not a ModuleEnv]

+

+        knot_var_fun :: Module -> Maybe (IfG TypeEnv)

+        knot_var_fun that_mod

+          | that_mod == mod || isInteractiveModule mod = Just (return type_env)

+          | otherwise                                  = Nothing

+

+

+dsToIfL iface_action

+dsLookupKnownKey :: Unique -> DsM TyThing

+dsLookupKnownKey uniq

+  = do { normal_path <- xoptM LangExt.ImplicitKnownKeyNames

+       ; mb_rdr_env <- if normal_path

+                       then return Nothing

+                       else Just <$> dsGetGlobalRdrEnv

+       ; dsToIfL $

+         do { mb_res <- lookupKnownKeyThing mb_rdr_env uniq

+            ; case mb_res of

+                 Succeeded thing -> return thing

+                 Failed msg -> failIfM (pprDiagnostic msg) } }

+

+dsLookupKnownKeyTyCon :: Unique -> DsM TyCon

+dsLookupKnownKeyTyCon uniq

+  = tyThingTyCon <$> dsLookupKnownKey uniq

+import GHC.Builtin.Names (rationalTyConKey, toListName)

+            rat_tc <- dsLookupKnownKeyTyCon rationalTyConKey

+lookupKnownKeyType :: Unique      -- Unique of type constructor (e.g. (M TH.Exp))

+                   -> MetaM Type  -- The type

+lookupKnownKeyType tc_key

+  = do { tc <- lift $ dsLookupKnownKeyTyCon tc_key

+       ; return (mkTyConApp tc []) }

+

+mk_rational r = do rat_ty <- lookupKnownKeyType rationalTyConKey

+import GHC.Types.Unique

+import GHC.Utils.Misc( HasDebugCallStack )

+import GHC.Utils.Panic( callStackDoc )

+newGlobalBinder :: HasDebugCallStack => Module -> OccName -> Maybe Unique

+                -> SrcSpan -> TcRnIf a b Name

+-- because we may have seen an /occurrence/ before, but now is the

+newGlobalBinder mod occ mb_uniq loc

+       ; name <- liftIO $ allocateGlobalBinder (hsc_NC hsc_env) mod occ mb_uniq loc

+                  vcat [ ppr mod <+> ppr occ <+> ppr loc, ppr name, callStackDoc])

+  allocateGlobalBinder (hsc_NC hsc_env) mod occ Nothing loc

+  -> Module -> OccName -> Maybe Unique -> SrcSpan

+allocateGlobalBinder nc mod occ mb_uniq loc

+                  -> warnPprTrace wrong_unique "allocateGlobalBinder" (ppr mb_uniq $$ ppr name) $

+                     pure (new_cache, name')

+                    wrong_unique = case mb_uniq of

+                                     Nothing      -> False

+                                     Just kn_uniq -> kn_uniq /= uniq

+              uniq <- case mb_uniq of

+                        Just uniq -> return uniq

+                        Nothing   -> takeUniqFromNameCache nc

+    newGlobalBinder m (nameOccName n) Nothing (nameSrcSpan n)

+{-# LANGUAGE ScopedTypeVariables #-}

+        importDecl,

+        lookupKnownKeyThing, loadGlobalName,

+import GHC.Utils.Misc( HasDebugCallStack )

+import GHC.Types.Name.Reader

+import GHC.Types.Unique.FM( listToUFM, lookupUFM )

+

+{- *********************************************************************

+*                                                                      *

+*                      Known-key things                                *

+*                                                                      *

+********************************************************************* -}

+

+lookupKnownKeyThing :: HasDebugCallStack

+                    => Maybe GlobalRdrEnv -> Unique

+                    -> IfM lcl (MaybeErr IfaceMessage TyThing)

+lookupKnownKeyThing Nothing uniq

+  = do { known_key_name_map <- loadKnownKeyOccMap

+       ; let name = lookupUFM known_key_name_map uniq

+                    `orElse` pprPanic "lookupKnownKeyThing" (ppr uniq)

+       ; lookupGlobalName name }

+

+lookupKnownKeyThing (Just gbl_rdr_env) uniq

+  -- Look up the known-key OccName in the current top-level GlobalRdrEnv

+  -- If we get a unique hit, use it; if not, panic.

+  = case lookupGRE gbl_rdr_env (LookupOccName occ SameNameSpace) of

+       [gre] -> lookupGlobalName (greName gre)

+       gres  -> pprPanic "lookupKnownKeyOcc" (ppr occ $$ ppr gres)

+  where

+     occ = lookupUFM knownKeyUniqMap uniq

+           `orElse` pprPanic "lookupKnownKeyThing" (ppr uniq)

+

+loadKnownKeyOccMap :: IfM lcl KnownKeyNameMap

+loadKnownKeyOccMap

+  = do { eps <- getEps

+       ; case eps_known_keys eps of {

+            Just occ_map -> return occ_map ;

+            Nothing ->

+

+    -- We don't have a KnownKeyOccMap yet, so create it

+    -- from the interface file for KnownKeyName

+    do { hsc_env <- getTopEnv

+       ; mb_res <- liftIO $ findImportedModule hsc_env kNOWN_KEY_NAMES NoPkgQual

+       ; iface <- case mb_res of

+           Found _ mod -> loadInterfaceWithException doc mod ImportBySystem

+           _ -> panic "loadKnownKeyOccMap"   -- ToDo tidy up

+

+       ; let occ_map :: KnownKeyNameMap

+             occ_map = listToUFM [ (getUnique nm, nm)

+                                 | avail <- mi_exports iface

+                                 , nm <- availNames avail ]

+

+       -- Record the KnownKeyOccMap in the EPS, so we will find it next time

+       ; updateEps_ (\eps -> eps { eps_known_keys = Just occ_map })

+

+       ; return occ_map } } }

+  where

+    doc = text "Need interface for KnonwKeyNames"

+

+

+{- *********************************************************************

+*                                                                      *

+*                      Global things

+*                                                                      *

+********************************************************************* -}

+

+lookupGlobalName :: Name ->  IfM lcl (MaybeErr IfaceMessage TyThing)

+-- Only works for External Names that have a Module

+lookupGlobalName name = loadGlobalName name (nameModule name)

+

+loadGlobalName :: forall lcl.

+                  Name

+               -> Module  -- Use this for non-External Names (maybe Backpack-related?)

+               -> IfM lcl (MaybeErr IfaceMessage TyThing)

+loadGlobalName name mod

+  = do  { env <- getGblEnv

+        ; case lookupKnotVars (if_rec_types env) mod of

+               -- Note [Tying the knot]

+            Just get_type_env

+                -> do           -- It's defined in a module in the hs-boot loop

+                { type_env <- setLclEnv () get_type_env         -- yuk

+                ; case lookupNameEnv type_env name of

+                    Just thing -> return (Succeeded thing)

+                    -- See Note [Knot-tying fallback on boot]

+                    Nothing   -> via_external

+                }

+

+            _ -> via_external }

+  where

+    via_external = do { hsc_env <- getTopEnv

+                      ; mb_thing <- liftIO (lookupType hsc_env name)

+                      ; case mb_thing of

+                          Just thing -> return (Succeeded thing)

+                          Nothing    -> importDecl name }

+

+-- Note [Tying the knot]

+-- ~~~~~~~~~~~~~~~~~~~~~

+-- The if_rec_types field is used when we are compiling M.hs, which indirectly

+-- imports Foo.hi, which mentions M.T Then we look up M.T in M's type

+-- environment, which is splatted into if_rec_types after we've built M's type

+-- envt.

+--

+-- This is a dark and complicated part of GHC type checking, with a lot

+-- of moving parts.  Interested readers should also look at:

+--

+--      * Note [Knot-tying typecheckIface]

+--      * Note [DFun knot-tying]

+--      * Note [hsc_type_env_var hack]

+--      * Note [Knot-tying fallback on boot]

+--      * Note [Hydrating Modules]

+--

+-- There is also a wiki page on the subject, see:

+--

+--      https://gitlab.haskell.org/ghc/ghc/wikis/commentary/compiler/tying-the-knot

+

+-- Note [Knot-tying fallback on boot]

+-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+-- Suppose that you are typechecking A.hs, which transitively imports,

+-- via B.hs, A.hs-boot. When we poke on B.hs and discover that it

+-- has a reference to a type T from A, what TyThing should we wire

+-- it up with? Clearly, if we have already typechecked T and

+-- added it into the type environment, we should go ahead and use that

+-- type. But what if we haven't typechecked it yet?

+--

+-- For the longest time, GHC adopted the policy that this was

+-- *an error condition*; that you MUST NEVER poke on B.hs's reference

+-- to a T defined in A.hs until A.hs has gotten around to kind-checking

+-- T and adding it to the env. However, actually ensuring this is the

+-- case has proven to be a bug farm, because it's really difficult to

+-- actually ensure this never happens. The problem was especially poignant

+-- with type family consistency checks, which eagerly happen before any

+-- typechecking takes place.

+--

+-- Today, we take a different strategy: if we ever try to access

+-- an entity from A which doesn't exist, we just fall back on the

+-- definition of A from the hs-boot file. This is complicated in

+-- its own way: it means that you may end up with a mix of A.hs and

+-- A.hs-boot TyThings during the course of typechecking.  We don't

+-- think (and have not observed) any cases where this would cause

+-- problems, but the hypothetical situation one might worry about

+-- is something along these lines in Core:

+--

+--    case x of

+--        A -> e1

+--        B -> e2

+--

+-- If, when typechecking this, we find x :: T, and the T we are hooked

+-- up with is the abstract one from the hs-boot file, rather than the

+-- one defined in this module with constructors A and B.  But it's hard

+-- to see how this could happen, especially because the reference to

+-- the constructor (A and B) means that GHC will always typecheck

+-- this expression *after* typechecking T.

+

+

+*      importDecl is the key function for "faulting in"                *

+importDecl :: HasDebugCallStack => Name -> IfM lcl (MaybeErr IfaceMessage TyThing)

+            Nothing    -> pprTrace "importDecl" (ppr name $$ callStackDoc) $

+                          return $ Failed $

+  | local  && external = do new_external_name <- allocateGlobalBinder name_cache mod occ' Nothing loc

+  = do { mod <- case nameModule_maybe name of

+                  Just mod -> return mod

+                  Nothing  -> if_mod <$> getLclEnv

+       ; mb_thing <- loadGlobalName name mod

+       ; case mb_thing of

+            Succeeded thing -> return thing }

+

+import GHC.Builtin.Utils( knownKeyOccMap )

+import GHC.Builtin.Names( rOOT_MAIN )

+

+import GHC.Types.Unique

+        ; newGlobalBinder rdr_mod rdr_occ Nothing (locA loc) }

+  = do  { when (isQual rdr_name) $

+          addErrAt (locA loc) (badQualBndrErr rdr_name)

+             -- Finally we get the "normal path"; an ordinary, top-level binding

+             newTopVanillaSrcBinder (rdrNameOcc rdr_name) (locA loc)

+newTopVanillaSrcBinder :: OccName -> SrcSpan -> RnM Name

+newTopVanillaSrcBinder occ loc

+  = do { this_mod <- getModule

+

+       -- See if this bindings is for a known-key name, and if so get its Unique

+       ; defines_known_keys <- xoptM LangExt.DefinesKnownKeyNames

+       ; let mb_uniq :: Maybe Unique

+             mb_uniq | defines_known_keys = lookupOccEnv knownKeyOccMap occ

+                     | otherwise          = Nothing

+

+       ; name <- newGlobalBinder this_mod occ mb_uniq loc

+       ; traceRn "newTopSrcBinder" $

+         vcat [ text "module:" <+> ppr this_mod

+              , text "occ:" <+> ppr occ

+              , text "mb_uniq:" <+> ppr mb_uniq

+              , text "loc:" <+> ppr loc

+              , text "name:" <+> ppr name ]

+       ; return name

+       }

+

+     ; rep_name <- newGlobalBinder mod rep_occ Nothing loc

+       ; mod_nm        <- newGlobalBinder mod (mkVarOccFS (fsLit "$trModule")) Nothing loc

+  = newGlobalBinder mod occ Nothing loc