[[project @ 2003-02-19 16:30:17 by simonpj]
simonpj**20030219163017
Document phase control
] {
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3522
-INLINE pragma
+INLINE and NOINLINE pragmas
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3529
-
-
-
-You will probably see these unfoldings (in Core syntax) in your
-interface files.
-
-
-
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3545
-
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3556
-An INLINE pragma for a function can be put anywhere its type
+Syntactially, an INLINE pragma for a function can be put anywhere its type
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3574
-
-
-
-NOINLINE pragma
-
+
+The NOINLINE pragma
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3593
+
+
+
+
+Phase control
+
+ Sometimes you want to control exactly when in GHC's pipeline
+the INLINE pragma is switched on. Inlining happens only during runs of
+the simplifier. Each run of the simplifier has a different
+phase number; the phase number decreases towards zero.
+If you use
+you'll see the sequence of phase numbers for successive runs of the simpifier.
+In an INLINE pragma you can optionally specify a phase number, thus:
+
+You can say "inline f in Phase 2 and all subsequent
+phases":
+
+ {-# INLINE [2] f #-}
+
+
+
+You can say "inline g in all phases up to, but
+not including, Phase 3":
+
+ {-# INLINE [~3] g #-}
+
+
+
+If you omit the phase indicator, you mean "inline in all phases".
+
+
+You can use a phase number on a NOINLINE pragma too:
+
+You can say "do not inline f until Phase 2; in
+Phase 2 and subsequently behave as if there was no pragma at all":
+
+ {-# NOINLINE [2] f #-}
+
+
+
+You can say "do not inline g in Phase 3 or any subsequent phase;
+before that, behave as if there was no pragma":
+
+ {-# NOINLINE [~3] g #-}
+
+
+
+If you omit the phase indicator, you mean "never inline this function".
+
+
+
+The same phase-numbering control is available for RULES ().
+
+
+
+
+
+
+
+RULES pragma
+
+
+The RULES pragma lets you specify rewrite rules. It is described in
+.
+
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3661
+
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3784
-
-RULES pragma
-
-
-The RULES pragma lets you specify rewrite rules. It is described in
-.
-
-
-
-
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3856
+
+ There may be zero or more rules in a RULES pragma.
+
+
+
+
+
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3868
-
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3869
+
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3871
- There may be zero or more rules in a RULES pragma.
+A rule may optionally have a phase-control number (see ),
+immediately after the name of the rule. Thus:
+
+ {-# RULES
+ "map/map" [2] forall f g xs. map f (map g xs) = map (f.g) xs
+ #-}
+
+The "[2]" means that the rule is active in Phase 2 and subsequent phases. The inverse
+notation "[~2]" is also accepted, meaning that the rule is active up to, but not including,
+Phase 2.
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3883
+
+
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3893
+
}