Comments only
authorSimon Peyton Jones <simonpj@microsoft.com>
Fri, 10 Mar 2017 14:40:25 +0000 (14:40 +0000)
committerSimon Peyton Jones <simonpj@microsoft.com>
Fri, 10 Mar 2017 16:05:33 +0000 (16:05 +0000)
libraries/base/GHC/Base.hs
libraries/base/GHC/List.hs

index a678c22..8548da6 100644 (file)
@@ -951,25 +951,40 @@ mapFB ::  (elt -> lst -> lst) -> (a -> elt) -> a -> lst -> lst
 {-# INLINE [0] mapFB #-} -- See Note [Inline FB functions] in GHC.List
 mapFB c f = \x ys -> c (f x) ys
 
--- The rules for map work like this.
---
--- Up to (but not including) phase 1, we use the "map" rule to
--- rewrite all saturated applications of map with its build/fold
--- form, hoping for fusion to happen.
--- In phase 1 and 0, we switch off that rule, inline build, and
--- switch on the "mapList" rule, which rewrites the foldr/mapFB
--- thing back into plain map.
---
--- It's important that these two rules aren't both active at once
--- (along with build's unfolding) else we'd get an infinite loop
--- in the rules.  Hence the activation control below.
---
--- This same pattern is followed by many other functions:
--- e.g. append, filter, iterate, repeat, etc.
---
--- The "mapFB" rule optimises compositions of map and
--- the "mapFB/id" rule get rids of 'map id' calls.
--- (Any similarity to the Functor laws for [] is expected.)
+{- Note [The rules for map]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The rules for map work like this.
+
+* Up to (but not including) phase 1, we use the "map" rule to
+  rewrite all saturated applications of map with its build/fold
+  form, hoping for fusion to happen.
+
+  In phase 1 and 0, we switch off that rule, inline build, and
+  switch on the "mapList" rule, which rewrites the foldr/mapFB
+  thing back into plain map.
+
+  It's important that these two rules aren't both active at once
+  (along with build's unfolding) else we'd get an infinite loop
+  in the rules.  Hence the activation control below.
+
+* This same pattern is followed by many other functions:
+  e.g. append, filter, iterate, repeat, etc. in GHC.List
+
+  See also Note [Inline FB functions] in GHC.List
+
+* The "mapFB" rule optimises compositions of map
+
+* The "mapFB/id" rule get rids of 'map id' calls.
+  You might think that (mapFB c id) will turn into c simply
+  when mapFB is inlined; but before that happens the "mapList"
+  rule turns
+     (foldr (mapFB (:) id) [] a
+  back into
+     map id
+  Which is not very cleveer.
+
+* Any similarity to the Functor laws for [] is expected.
+-}
 
 {-# RULES
 "map"       [~1] forall f xs.   map f xs                = build (\c n -> foldr (mapFB c f) n xs)
index 3eab407..018c0a7 100644 (file)
@@ -203,13 +203,10 @@ We hope that one of the two measure kick in:
      in CoreArity.
 
 The oneShot annotations used in this module are correct, as we only use them in
-argumets to foldr, where we know how the arguments are called.
--}
+arguments to foldr, where we know how the arguments are called.
 
-{-
 Note [Inline FB functions]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 After fusion rules successfully fire, we are usually left with one or more calls
 to list-producing functions abstracted over cons and nil. Here we call them
 FB functions because their names usually end with 'FB'. It's a good idea to