[Document the CONLIKE pragma
simonpj@microsoft.com**20091103133431
Ignore-this: a8e36c2ca7bd43cf327cbb94e1c226d3
Do not merge to 6.12
] {
hunk ./docs/users_guide/glasgow_exts.xml 7544
+
+ CONLIKE modifier
+ CONLIKE
+ An INLINE or NOINLINE pragma may have a CONLIKE modifier,
+ which affects matching in RULEs (only). See .
+
+
+
hunk ./docs/users_guide/glasgow_exts.xml 8187
-
+
+
+
+
+
+
+
+How rules interact with INLINE/NOINLINE and CONLIKE pragmas
hunk ./docs/users_guide/glasgow_exts.xml 8201
-{-# RULES "f" f True = False #-}
-
hunk ./docs/users_guide/glasgow_exts.xml 8202
-
hunk ./docs/users_guide/glasgow_exts.xml 8203
+
+{-# RULES "f" f True = False #-}
hunk ./docs/users_guide/glasgow_exts.xml 8218
-pragma on f, to ensure
+pragma, or an INLINE[phase] pragma, on f, to ensure
hunk ./docs/users_guide/glasgow_exts.xml 8221
-
-
-
+
+GHC is very cautious about duplicating work. For example, consider
+
+f k z xs = let xs = build g
+ in ...(foldr k z xs)...sum xs...
+{-# RULES "foldr/build" forall k z g. foldr k z (build g) = g k z #-}
+
+Since xs is used twice, GHC does not fire the foldr/build rule. Rightly
+so, because it might take a lot of work to compute xs, which would be
+duplicated if the rule fired.
+
+
+Sometimes, however, this approach is over-cautious, and we do want the
+rule to fire, even though doing so would duplicate redex. There is no way that GHC can work out
+when this is a good idea, so we provide the CONLIKE pragma to declare it, thus:
+
+{-# INLINE[1] CONLIKE f #-}
+f x = blah
+
+CONLIKE is a modifier to an INLINE or NOINLINE pragam. It specifies that an application
+of f to one argument (in general, the number of arguments to the left of the '=' sign)
+should be considered cheap enough to duplicate, if such a duplication would make rule
+fire. (The name "CONLIKE" is short for "constructor-like", because constructors certainly
+have such a property.)
+The CONLIKE pragam is a modifier to INLINE/NOINLINE because it really only makes sense to match
+f on the LHS of a rule if you are sure that f is
+not going to be inlined before the rule has a chance to fire.
hunk ./docs/users_guide/glasgow_exts.xml 8249
-
hunk ./docs/users_guide/glasgow_exts.xml 8520
-
hunk ./docs/users_guide/glasgow_exts.xml 8521
+
hunk ./docs/users_guide/glasgow_exts.xml 8527
+
hunk ./docs/users_guide/glasgow_exts.xml 8529
+
+ Use to see in great detail what rules are being fired.
+If you add you get a still more detailed listing.
+
+
hunk ./docs/users_guide/glasgow_exts.xml 8535
+
}