meta: end of phase 0

Author: doyougnu

bib/book.bib

@@ -261,6 +261,15 @@ @misc{selectiveLambdaLifting
   copyright = {arXiv.org perpetual, non-exclusive license}
 }
 
+@misc{callArityVsDemandAnalysis,
+  title = {Call Arity vs. Demand Analysis},
+  year = {2017},
+  month = aug,
+  author = {Sebastian Graf},
+  school = {Karlsruher Institut f{\"u}r Technologie (KIT)},
+  institution = {IPD Snelting},
+}
+
 @inproceedings{fastCurry,
 author = {Marlow, Simon and Jones, Simon Peyton},
 title = {Making a Fast Curry: Push/Enter vs. Eval/Apply for Higher-Order Languages},
@@ -277,3 +286,23 @@ @inproceedings{fastCurry
 location = {Snow Bird, UT, USA},
 series = {ICFP '04}
 }
+
+@article{hoCardinality,
+author = {Sergey, Ilya and Vytiniotis, Dimitrios and Peyton Jones, Simon},
+title = {Modular, Higher-Order Cardinality Analysis in Theory and Practice},
+year = {2014},
+issue_date = {January 2014},
+publisher = {Association for Computing Machinery},
+address = {New York, NY, USA},
+volume = {49},
+number = {1},
+issn = {0362-1340},
+url = {https://doi.org/10.1145/2578855.2535861},
+doi = {10.1145/2578855.2535861},
+abstract = {Since the mid '80s, compiler writers for functional languages (especially lazy ones) have been writing papers about identifying and exploiting thunks and lambdas that are used only once. However it has proved difficult to achieve both power and simplicity in practice. We describe a new, modular analysis for a higher-order language, which is both simple and effective, and present measurements of its use in a full-scale, state of the art optimising compiler. The analysis finds many single-entry thunks and one-shot lambdas and enables a number of program optimisations.},
+journal = {SIGPLAN Not.},
+month = {jan},
+pages = {335–347},
+numpages = {13},
+keywords = {lazy evaluation, haskell, functional programming languages, compilers, static analysis, cardinality analysis, program optimisation, operational semantics, types and effects, thunks}
+}

contents.rst

@@ -16,6 +16,7 @@ Haskell Optimization Handbook
    src/Preliminaries/index
    src/Measurement_Observation/index
    src/Optimizations/index
+   src/Case_Studies/index
 
 
 Indices and tables

src/Case_Studies/index.rst

@@ -0,0 +1,9 @@
+Case Studies
+============
+
+.. toctree::
+   :maxdepth: 1
+   :name: Case_Studies
+
+   sbv_572
+   sbv_642

src/Case_Studies/sbv_572.rst

@@ -0,0 +1,4 @@
+.. _SBV572:
+
+Impact of Seq Removal on SBV's Internal Cache
+=============================================

src/Case_Studies/sbv_642.rst

@@ -0,0 +1,4 @@
+.. _SBV642:
+
+SBV and the Bizarre GHC Regression
+==================================

src/Optimizations/GHC_opt/lambda_lifting.rst

@@ -87,7 +87,7 @@ when *not* to lambda lift in `Note [When to lift]
 
 GHC does not lambda lift:
 
-#.  A :term:`Top-level binding`. By definition these cannot be lifted.
+#.  A :term:`top-level` binding. 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.
@@ -103,8 +103,8 @@ GHC does not lambda lift:
 #. 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.
+   allocations. This is especially bad for any :term:`multi-shot lambda`, which
+   will allocate many times.
 
 
 Observing the Effect of Lambda Lifting
@@ -117,7 +117,7 @@ late lambda lifting with the flags ``-f-stg-lift-lams`` and
 syntactic changes:
 
 #. It eliminates a let binding.
-#. It creates a new :term:`Top-level` 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.
@@ -187,9 +187,9 @@ Thus ``g``'s closure will contain ``x`` and ``f_lifted`` will be inlined, same
 as ``f`` in the unlifted version. ``h``'s allocations grow by one slot since
 ``y`` *is now also* free in ``h``, just as ``x`` was. So it would seem that in
 total lambda lifting ``f`` saves one slot of memory because two slots were lost
-in ``f`` and one was gained in ``h``. However, ``g`` is a :term:`multi-shot`
-lambda, thus ``h`` will be allocated *for each* call of ``g``, whereas ``f`` and
-``g`` are only allocated once. Therefore the lift is a net loss.
+in ``f`` and one was gained in ``h``. However, ``g`` is a :term:`multi-shot
+lambda`, thus ``h`` will be allocated *for each* call of ``g``, whereas ``f``
+and ``g`` are only allocated once. Therefore the lift is a net loss.
 
 This example illustrates how tricky good lifts can be and especially for hot
 loops. In general, you should try to train your eye to determine when to

src/Preliminaries/what_makes_fast_hs.rst

@@ -254,10 +254,10 @@ Excessive closure allocation is subtle for two reasons: first, because GHC is
 typically very good at optimizing it away via :term:`Let Floating` most
 Haskeller's never have to confront it (which is a good indication of GHC's
 quality); second, in order to observe it, the programmer must track the memory
-allocation of their program across many functions or even modules, which is not
-a common experience when writing Haskell. For our purposes', we'll inspect
-examples that GHC should have no problem finding and optimizing. See
-:ref:`Case_Study_SBV`
+allocation of their program across many functions, modules and packages, which
+is not a common experience when writing Haskell. For our purposes', we'll
+inspect examples that GHC should have no problem finding and optimizing. See the
+:ref:`Impact of seq Removal on SBV's cache <SBV572>` case study for more.
 
 .. todo::
    Not yet written, see `#18 <https://github.com/input-output-hk/hs-opt-handbook.github.io/issues/18>`_

src/glossary.rst

@@ -14,10 +14,20 @@ Glossary
 
       A Boxed value is a value that is represented by a pointer to the heap.
 
+   Cardinality Analysis
+
+      A static analysis that GHC performs to determine:
+      #. How many times a lambda-expression is called.
+      #. Which components of a data structure are never evaluated.
+      #. How many times a particular thunk is evaluated.
+
+      See :cite:t:`callArityVsDemandAnalysis` and :cite:t:`hoCardinality` for
+      more.
+
    Closure
 
-      A closure is value that associates a function with an environment, where
-      the environment maps every free variable in the function with a value or
+      A closure is value that pairs a function with an environment, where the
+      environment maps every free variable in the function with a value or
       reference to which the free variable was bound when the closure was
       created. Closure's are the canonical way to realize lexical scoping in
       languages with first-class functions, such a Haskell. See `the wikipedia
@@ -199,6 +209,30 @@ Glossary
       type is a set with three values: ``True``, ``False``, and :math:`\bot`.
       Therefore ``Bool`` is a Lifted type.
 
+   Multi-Shot Lambda
+
+      A multi-shot lambda is a lambda that is called *more* than once. In
+      contrast to a :term:`one-shot lambda`, a multi-shot lambda has a high risk
+      of destroying :term:`sharing` if subject to certain optimizations, such as
+      Inlining. GHC determines whether a lambda is one-shot or multi-shot during
+      :term:`Cardinality Analysis`. See :cite:t:`hoCardinality` and
+      :cite:t:`callArityVsDemandAnalysis` for more.
+
+   One-Shot Lambda
+
+      A one-shot lambda is a lambda that is called *exactly* once. These
+      lambda's are common in functional programming and can be subject to more
+      aggressive optimizations due to their one-shot nature. For example, there
+      is no risk of losing :term:`sharing` in a one-shot lambda as a result of
+      inlining free variables or floating let expressions *into* the lambda;
+      something that GHC usually avoids. See :cite:t:`hoCardinality` and
+      :cite:t:`callArityVsDemandAnalysis` for more background. See the magic
+      `oneShot
+      <https://hackage.haskell.org/package/base-4.17.0.0/docs/GHC-Exts.html#v:oneShot>`_
+      function in `GHC.Exts
+      <https://hackage.haskell.org/package/base-4.17.0.0/docs/GHC-Exts.html>`_
+      for an unsafe way to instruct GHC that you have a one-shot lambda.
+
    PAP
 
       A PAP is a partial application. PAPs are heap objects and thus a type of
@@ -219,17 +253,33 @@ Glossary
      <https://gitlab.haskell.org/ghc/ghc/-/wikis/commentary/rts/storage/gc/pinned>`_
      for more.
 
+   Sharing
+
+      Consider the following program:
+
+      .. code-block:: haskell
+
+         foo :: Int -> Int
+         foo n = let x = [1..n]
+                     in zip (fmap (* (last x)) x) x
+
+      We say that ``x`` is *shared* in this program because each of the three
+      references of ``x`` refer to the ``x`` defined in the ``let``. If ``x`` is
+      not shared that the list ``[1..n]`` would be allocated *for each*
+      reference of ``x``. Thus, sharing is fundamental to performance oriented
+      Haskell because it reduces allocations, leverages call-by-need, and saves
+      work.
+
    Thunk
 
       A thunk is a special kind of :term:`Closure` that represents a suspended
       computation. Thunks reside on the heap and are the key feature that
       provides Haskell's laziness. See :cite:t:`SpinelessTaglessGMachine`
       Section 3.1.2 for more details.
 
-   Top-level binding
+   Top-Level
 
-      A top level binding is any binding that exists in the most outer-most or
-      global scope of the program.
+      The most outer-most or global scope of the program.
 
    Unboxed : Levity