Clean up handling of known-key Names in interface files

Previously BinIface had some dedicated logic for handling tuple names in
the symbol table. As it turns out, this logic was essentially dead code
as it was superceded by the special handling of known-key things. Here
we cull the tuple code-path and use the known-key codepath for all
tuple-ish things.

This had a surprising number of knock-on effects,

 * constraint tuple datacons had to be made known-key (previously they
   were not)

 * IfaceTopBndr was changed from being a synonym of OccName to a
   synonym of Name (since we now need to be able to deserialize Names
   directly from interface files)

 * the change to IfaceTopBndr complicated fingerprinting, since we need
   to ensure that we don't go looking for the fingerprint of the thing
   we are currently fingerprinting in the fingerprint environment (see
   notes in MkIface). Handling this required distinguishing between
   binding and non-binding Name occurrences in the Binary serializers.

 * the original name cache logic which previously lived in IfaceEnv has
   been moved to a new NameCache module

 * I ripped tuples and sums out of knownKeyNames since they introduce a
   very large number of entries. During interface file deserialization
   we use static functions (defined in the new KnownUniques module) to
   map from a Unique to a known-key Name (the Unique better correspond
   to a known-key name!) When we need to do an original name cache
   lookup we rely on the parser implemented in isBuiltInOcc_maybe.

 * HscMain.allKnownKeyNames was folded into PrelInfo.knownKeyNames.

 * Lots of comments were sprinkled about describing the new scheme.

Updates haddock submodule.

Test Plan: Validate

Reviewers: niteria, simonpj, austin, hvr

Reviewed By: simonpj

Subscribers: simonmar, niteria, thomie

Differential Revision: https://phabricator.haskell.org/D2467

GHC Trac Issues: #12532, #12415

1 files changed, 30 insertions, 19 deletions

diff --git a/compiler/prelude/PrelNames.hs b/compiler/prelude/PrelNames.hs
index 558619a9db..41c9e36304 100644
--- a/compiler/prelude/PrelNames.hs
+++ b/compiler/prelude/PrelNames.hs
@@ -73,33 +73,44 @@ This is accomplished through a combination of mechanisms:
      stuff gets the right Unique, and is why it is so important to
      place your known-key names in the appropriate lists.
 
-  3. For "infinite families" of known-key names (i.e. tuples), we have
-     to be extra careful. Because there are an infinite number of
+  3. For "infinite families" of known-key names (i.e. tuples and sums), we
+     have to be extra careful. Because there are an infinite number of
      these things, we cannot add them to the list of known-key names
      used to initialise the OrigNameCache. Instead, we have to
-     rely on never having to look them up in that cache.
+     rely on never having to look them up in that cache. See
+     Note [Infinite families of known-key names] for details.
 
-     This is accomplished through a variety of mechanisms:
 
-       a) The parser recognises them specially and generates an
-          Exact Name (hence not looked up in the orig-name cache)
+Note [Infinite families of known-key names]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-       b) The known infinite families of names are specially
-          serialised by BinIface.putName, with that special treatment
-          detected when we read back to ensure that we get back to the
-          correct uniques.
+Infinite families of known-key things (e.g. tuples and sums) pose a tricky
+problem: we can't add them to the knownKeyNames finite map which we use to
+ensure that, e.g., a reference to (,) gets assigned the right unique (if this
+doesn't sound familiar see Note [Known-key names] above).
 
-       Most of the infinite families cannot occur in source code,
-       so mechanisms (a,b) sufficies to ensure that they always have
-       the right Unique. In particular, implicit param TyCon names,
-       constraint tuples and Any TyCons cannot be mentioned by the
-       user.
+We instead handle tuples and sums separately from the "vanilla" known-key
+things,
 
-       c) IfaceEnv.lookupOrigNameCache uses isBuiltInOcc_maybe to map
-          built-in syntax directly onto the corresponding name, rather
-          than trying to find it in the original-name cache.
+  a) The parser recognises them specially and generates an Exact Name (hence not
+     looked up in the orig-name cache)
 
-          See also Note [Built-in syntax and the OrigNameCache]
+  b) The known infinite families of names are specially serialised by
+     BinIface.putName, with that special treatment detected when we read back to
+     ensure that we get back to the correct uniques. See Note [Symbol table
+     representation of names] in BinIface and Note [How tuples work] in
+     TysWiredIn.
+
+Most of the infinite families cannot occur in source code, so mechanisms (a) and (b)
+suffice to ensure that they always have the right Unique. In particular,
+implicit param TyCon names, constraint tuples and Any TyCons cannot be mentioned
+by the user. For those things that *can* appear in source programs,
+
+  c) IfaceEnv.lookupOrigNameCache uses isBuiltInOcc_maybe to map built-in syntax
+     directly onto the corresponding name, rather than trying to find it in the
+     original-name cache.
+
+     See also Note [Built-in syntax and the OrigNameCache]
 -}
 
 {-# LANGUAGE CPP #-}