These invariants don't seem to make any sense in the current code.  The
text talks about c_child_r as if it were an StgClosure, for which RSET()
would make sense, but it's a retainer aka 'CostCentreStack*'.

A lot of comments and strings are still talking about old names, fix
that.

Keeping track of the maximum stack seems like a good idea in all
configurations. The associated ASSERTs only materialize in debug mode but
having the statistic is nice.

To make the debug code less prone to bitrotting I introduce a function
'debug()' which doesn't actually print by default and is #define'd away
only when the standard DEBUG define is off.

This gets all remaining functions in-line with the new 'traverse' prefix
and module name.

Commit dbef766c ("Profiling cleanup.") made this debug code obsolete by
removing the 'cost' function without a replacement. As best I can tell the
retainer profiler used to do some heap census too and this debug code was
mainly concerned with that.

In the old code when DEBUG_RETAINER was set, FIRST_APPROACH is
implied. However ProfHeap.c now depends on printRetainerSetShort which is
only available with SECOND_APPROACH. This is because with FIRST_APPROACH
retainerProfile() will free all retainer sets before returning so by the
time ProfHeap calls dumpCensus the retainer set pointers are segfaulty.

Since all of this debugging code obviously hasn't been compiled in ages
anyways I'm taking the liberty of just removing it.

Remember guys: Dead code is a liability not an asset :)

Instead of breaking out of the switch-in-while construct using `return` this
uses `goto out` which makes it possible to share a lot of the out-variable
assignment code in all the cases.

I also replaced the nasty `while(true)` business by the real loop
condition: `while(*c == NULL)`. All `break` calls inside the switch aready
have either a check for NULL or an assignment of `c` to NULL so this should
not change any behaviour.

Using `goto out` also allowed me to remove another minor wart: In the
MVAR_*/WEAK cases the popOff() call used to happen before reading the
stackElement. This looked like a use-after-free hazard to me as the stack
is allocated in blocks and depletion of a block could mean it getting freed
and possibly overwritten by zero or garbage, depending on the block
allocator's behaviour.

This essentially turns the heap traversal code into a visitor. You add a
bunch of roots to the work-stack and then the callback you give to
traverseWorkStack() will be called with every reachable closure at least
once.

This commit starts renaming some flip bit related functions for the
generalised heap traversal code and adds provitions for sharing the
per-closure profiling header field currently used exclusively for retainer
profiling with other heap traversal profiling modes.

This essentially ammounts to s/retainer/stackData/, s/c_child_r/data/ and
some temporary casting of c_child_r to stackData until refactoring of this
module is completed by a subsequent commit. We also introduce a new union
'stackData' which will contain the actual extra data to be stored on the
stack.

The idea is to make the heap traversal logic of the retainer profiler ready
for extraction into it's own module. So talking about "retainers" there
doesn't really make sense anymore.

Essentially the "retainers" we store in the stack are just data associated
with the push()ed closures which we return when pop()ing it.

I don't see a point in having this live in 'info', just seems to make the
code more complicated.

Global state is ugly and hard to test. Since the profiling code isn't quite
as performance critical as, say, GC we should prefer better code here.

I would like to move the 'flip' bit into the struct too but that's
complicated by the fact that the defines which use it directly are also
called from ProfHeap where the traversalState is not easily
available. Maybe in a future commit.

This got renamed to 'era' in dbef766c ("[project @ 2001-11-26 16:54:21 by
simonmar] Profiling cleanup").

The `defined(DEBUG_RETAINER) == true` branch doesn't even compile anymore
because 1) retainerSet was renamed to RetainerSet and 2) even if I fix that
the context in Rts.h seems to have changed such that it's not in scope. If
3) I fix that 'flip' is still not in scope :)  At that point I just gave up.

This can only ever be one since 5f1d949a ("Remove explicit recursion in
retainer profiling"), so it's pointless.

The pattern match oracle can now cope with the abundance of information
that ViewPatterns, NPlusKPats, overloaded lists, etc. provide.

No need to have PmFake anymore!

Also got rid of a spurious call to `allCompleteMatches`, which we used to call
*for every constructor* match. Naturally this blows up quadratically for
programs like `ManyAlternatives`.

-------------------------
Metric Decrease:
    ManyAlternatives

Metric Increase:
    T11822
-------------------------

This updates the documentation of the MIN_PAYLOAD_SIZE constant and adds
a new Note [Mark bits in mark-compact collector] explaning why the
mark-compact collector uses two bits per objet and why we need
MIN_PAYLOAD_SIZE.

Using EvVars for capturing type constraints implied side-effects in DsM
when we just wanted to *construct* type constraints.

But giving names to type constraints is only necessary when passing
Givens to the type checker, of which the majority of the pattern match
checker should be unaware.

Thus, we simply generate `newtype TyCt = TyCt PredType`, which are
nicely stateless. But at the same time this means we have to allocate
EvVars when we want to query the type oracle! So we keep the type oracle
state as `newtype TyState = TySt (Bag EvVar)`, which nicely makes a
distinction between new, unchecked `TyCt`s and the inert set in
`TyState`.

Issue #17056 revealed that we were sometimes building a case
expression whose type field (in the Case constructor) was bogus.

Consider a phantom type synonym
   type S a = Int
and we want to form the case expression
   case x of K (a::*) -> (e :: S a)
We must not make the type field of the Case constructor be (S a)
because 'a' isn't in scope.  We must instead expand the synonym.

Changes in this patch:

* Expand synonyms in the new function CoreUtils.mkSingleAltCase.

* Use mkSingleAltCase in MkCore.wrapFloat, which was the proximate
  source of the bug (when called by exprIsConApp_maybe)

* Use mkSingleAltCase elsewhere

* Documentation
    CoreSyn   new invariant (6) in Note [Case expression invariants]
    CoreSyn   Note [Why does Case have a 'Type' field?]
    CoreUtils Note [Care with the type of a case expression]

* I improved Core Lint's error reporting, which was pretty
  confusing in this case, because it didn't mention that the offending
  type was the return type of a case expression.

* A little bit of cosmetic refactoring in CoreUtils

PmOracle.addVarCoreCt was giving a bogus (empty) in-scope set to
exprIsConApp_maybe, which resulted in a substitution-invariant
failure (see MR !1647 discussion).

This patch fixes it, by taking the free vars of the expression.

Add GHC.Hs module hierarchy replacing hsSyn.

Metric Increase:
    haddock.compiler

Fixes #17200.

'withTiming' becomes a function that, when passed '-vN' (N >= 2) or
'-ddump-timings', will print timing (and possibly allocations) related
information. When additionally built with '-eventlog' and executed with
'+RTS -l', 'withTiming' will also emit both 'traceMarker' and 'traceEvent'
events to the eventlog.

'withTimingSilent' on the other hand will never print any timing information,
under any circumstance, and will only emit 'traceEvent' events to the eventlog.
As pointed out in !1672, 'traceMarker' is better suited for things that we
might want to visualize in tools like eventlog2html, while 'traceEvent'
is better suited for internal events that occur a lot more often and that we
don't necessarily want to visualize.

This addresses #17138 by using 'withTimingSilent' for all the codegen bits
that are expressed as a bunch of small computations over streams of codegen
ASTs.

The particular test is already fixed, but the issue seems to have
multiple different test cases lumped together.

Apparently ghc-lib-parser's API blew up because the newly induced cyclic
dependency between TcRnTypes and PmOracle pulled in the other half of
GHC into the relevant strongly-connected component.

This patch arranges it so that PmTypes exposes mostly data type
definitions and type class instances to be used within PmOracle, without
importing the any of the possibly offending modules DsMonad, TcSimplify
and FamInst.

Also add reference from isUnliftedType to mightBeUnliftedType.

This fixes #15809, and is covered in
Note [Use level numbers for quantification] in TcMType.

This patch removes the "global tyvars" from the
environment, a nice little win.

This commit should have no change in behavior.(*)

The observation was that Note [Recipe for checking a signature]
says that every metavariable in a type-checked type must either
  (A) be generalized
  (B) be promoted
  (C) be zapped.
Yet the code paths for doing these were all somewhat separate.
This led to some steps being skipped. This commit shores this
all up. The key innovation is TcHsType.kindGeneralizeSome, with
appropriate commentary.

This commit also sets the stage for #15809, by turning the
WARNing about bad level-numbers in generalisation into an
ASSERTion. The actual fix for #15809 will be in a separate
commit.

Other changes:
 * zonkPromoteType is now replaced by kindGeneralizeNone.
   This might have a small performance degradation, because
   zonkPromoteType zonked and promoted all at once. The new
   code path promotes first, and then zonks.

 * A call to kindGeneralizeNone was added in tcHsPartialSigType.
   I think this was a lurking bug, because it did not follow
   Note [Recipe for checking a signature]. I did not try to
   come up with an example showing the bug. This is the (*)
   above.

   Because of this change, there is an error message regression
   in partial-sigs/should_fail/T14040a. This problem isn't really
   a direct result of this refactoring, but is a symptom of
   something deeper. See #16775, which addresses the deeper
   problem.

 * I added a short-cut to quantifyTyVars, in case there's
   nothing to quantify.

 * There was a horribly-outdated Note that wasn't referred
   to. Gone now.

 * While poking around with T14040a, I discovered a small
   mistake in the Coercion.simplifyArgsWorker. Easy to fix,
   happily.

 * See new Note [Free vars in coercion hole] in TcMType.
   Previously, we were doing the wrong thing when looking
   at a coercion hole in the gather-candidates algorithm.
   Fixed now, with lengthy explanation.

Metric Decrease:
  T14683