[commit: ghc] master: Add Note [FamInstEnv determinism] (64bce8c)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/64bce8c31450d846cf1a1ca4ff31ec6c724f2e46/ghc

>---------------------------------------------------------------

commit 64bce8c31450d846cf1a1ca4ff31ec6c724f2e46
Author: Bartosz Nitka <niteria at gmail.com>
Date:   Thu Jul 7 08:12:05 2016 -0700

    Add Note [FamInstEnv determinism]
    
    I'm just turning previous commit message into a Note
    
    GHC Trac: #4012


>---------------------------------------------------------------

64bce8c31450d846cf1a1ca4ff31ec6c724f2e46
 compiler/types/FamInstEnv.hs | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/compiler/types/FamInstEnv.hs b/compiler/types/FamInstEnv.hs
index c860dbc..d2fb520 100644
--- a/compiler/types/FamInstEnv.hs
+++ b/compiler/types/FamInstEnv.hs
@@ -359,10 +359,23 @@ Then we get a data type for each instance, and an axiom:
 
 These two axioms for T, one with one pattern, one with two;
 see Note [Eta reduction for data families]
+
+Note [FamInstEnv determinism]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+We turn FamInstEnvs into a list in some places that don't directly affect
+the ABI. That happens in family consistency checks and when producing output
+for `:info`. Unfortunately that nondeterminism is nonlocal and it's hard
+to tell what it affects without following a chain of functions. It's also
+easy to accidentally make that nondeterminism affect the ABI. Furthermore
+the envs should be relatively small, so it should be free to use deterministic
+maps here. Testing with nofib and validate detected no difference between
+UniqFM and UniqDFM.
+See Note [Deterministic UniqFM].
 -}
 
 type FamInstEnv = UniqDFM FamilyInstEnv  -- Maps a family to its instances
      -- See Note [FamInstEnv]
+     -- See Note [FamInstEnv determinism]
 
 type FamInstEnvs = (FamInstEnv, FamInstEnv)
      -- External package inst-env, Home-package inst-env
@@ -385,6 +398,7 @@ emptyFamInstEnv = emptyUDFM
 
 famInstEnvElts :: FamInstEnv -> [FamInst]
 famInstEnvElts fi = [elt | FamIE elts <- eltsUDFM fi, elt <- elts]
+  -- See Note [FamInstEnv determinism]
 
 familyInstances :: (FamInstEnv, FamInstEnv) -> TyCon -> [FamInst]
 familyInstances (pkg_fie, home_fie) fam