lambda lifting: add GHC specific details

Author: doyougnu

src/Optimizations/GHC_opt/lambda_lifting.rst

@@ -72,17 +72,63 @@ default method GHC uses for handling local functions and free variables.
 Instead, GHC uses an alternative strategy called :term:`Closure Conversion`,
 which creates more uniformity at the cost of extra heap allocation.
 
-Automated Lambda Lifting in GHC is *Selective* and based on several heuristics:
+Automated lambda lifting in GHC occurs *late* in the compiler pipeline at STG,
+right before code generation. GHC lambda lifts at STG instead of Core because
+lambda lifting interferes with other optimizations.
+
+Lambda lifting in GHC is also *Selective*. GHC uses a cost model that calculates
+hypothetical heap allocations a function will induce. GHC lists heuristics for
+when *not* to lambda lift in `Note [When to lift]
+<https://gitlab.haskell.org/ghc/ghc/-/blob/master/compiler/GHC/Stg/Lift/Analysis.hs#L46>`_
+, we repeat the basic ideas here. See :cite:t:`selectiveLambdaLifting`, and the
+`lambda lifting wiki
+<https://gitlab.haskell.org/ghc/ghc/-/wikis/late-lam-lift>`_ entry for more
+details.
+
+GHC does not lambda lift:
+
+#. :term:`Top-level` bindings. By definition these
+   cannot be lifted.
+#. :term:`Thunk` and Data Constructors. Lifting either of these would destroy
+   sharing.
+#. :term:`Join Point` because there is no lifting possible in a join point.
+   Similarly, abstracting over join points destroys the join point by turning it
+   into an argument to a lifted function.
+#. Any local :term:`known function`. This would turn a known function call into
+   an :term:`unknown function` call, which is slower. The flag
+   ``-fstg-lift-lams-known`` disables this restriction and enables lifting of
+   known functions.
+#. Any function whose lifted form would have a higher arity than the available
+   number of registers for the function's calling convention. See flags
+   ``-fstg-lift-(non)rec-args(-any)``
+#. Any function whose lifted form will result in *closure grawth*. Closure
+   growth occurs when formerly free variables, that are now additional
+   arguments, did not previously occur in the closure, thereby increasing
+   allocations. This is especially bad for :term:`multi-shot` lambdas which will
+   allocate many times.
 
 
 Observing the Effect of Lambda Lifting
 --------------------------------------
 
+You may directly observe the effect of late lambda lifting by comparing Core to
+STG when late lambda lifting is enabled. You can also directly disable or enable
+late lambda lifting with the flags ``-f-stg-lift-lams`` and
+``-fno-stg-lift-lams``. In general, lambda lifting performs the following
+syntactic changes:
+
+#. It eliminates a let binding.
+#. It creates a new :term:`Top-level` binding.
+#. It replaces all occurrences of the lifted function in the let's body with a
+   partial application. For example, all occurrences of ``f`` are replaced with
+   ``$lf b`` in the let's body.
+#. All non-top-level variables (i.e., free variables) in the let's body become
+   occurrences of parameters.
 
 When to Manually Apply Lambda Lifting
 -------------------------------------
 
-
+tomorrow: update glossary, start here
 
 
 Testing Exec