[commit: ghc] master: Add comments for StgCse and Unarise (232b0cb)

[git at git.haskell.org]

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

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/232b0cb35c1f731be66a032a4deee87bc47db3c9/ghc

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

commit 232b0cb35c1f731be66a032a4deee87bc47db3c9
Author: Simon Peyton Jones <simonpj at microsoft.com>
Date:   Wed Oct 24 17:15:15 2018 +0100

    Add comments for StgCse and Unarise
    
    This just improves docmentation for the fix to Trac #15300


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

232b0cb35c1f731be66a032a4deee87bc47db3c9
 compiler/simplStg/SimplStg.hs |  2 ++
 compiler/simplStg/StgCse.hs   | 16 ++++++++++++++++
 2 files changed, 18 insertions(+)

diff --git a/compiler/simplStg/SimplStg.hs b/compiler/simplStg/SimplStg.hs
index 36bf510..830dd19 100644
--- a/compiler/simplStg/SimplStg.hs
+++ b/compiler/simplStg/SimplStg.hs
@@ -40,6 +40,8 @@ stg2stg dflags binds
         ; stg_linter False "Pre-unarise" binds
         ; let un_binds = unarise us binds
         ; stg_linter True "Unarise" un_binds
+         -- Important that unarisation comes first
+         -- See Note [StgCse after unarisation] in StgCse
 
         ; dumpIfSet_dyn dflags Opt_D_dump_stg "STG syntax:"
                         (pprStgTopBindings un_binds)
diff --git a/compiler/simplStg/StgCse.hs b/compiler/simplStg/StgCse.hs
index 1ae1213..2caf006 100644
--- a/compiler/simplStg/StgCse.hs
+++ b/compiler/simplStg/StgCse.hs
@@ -67,7 +67,23 @@ and nothing stops us from transforming that to
     foo [e] = case e of b { Left [n] -> …
                           , Right [x] -> b}
 
+
+Note [StgCse after unarisation]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Consider two unboxed sum terms:
+
+    (# 1 | #) :: (# Int | Int# #)
+    (# 1 | #) :: (# Int | Int  #)
+
+These two terms are not equal as they unarise to different unboxed
+tuples. However if we run StgCse before Unarise, it'll think the two
+terms (# 1 | #) are equal, and replace one of these with a binder to
+the other. That's bad -- Trac #15300.
+
+Solution: do unarise first.
+
 -}
+
 module StgCse (stgCse) where
 
 import GhcPrelude