From 317da78a27cda0c07fce325953f096453bcef477 Mon Sep 17 00:00:00 2001 From: "simonpj@microsoft.com" Date: Thu, 18 May 2006 11:32:12 +0000 Subject: [PATCH] Improve documentation of INLINE pragmas --- docs/users_guide/glasgow_exts.xml | 93 ++++++++++++++++++------------------- 1 file changed, 44 insertions(+), 49 deletions(-) diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml index 9a9cd38..e5b7154 100644 --- a/docs/users_guide/glasgow_exts.xml +++ b/docs/users_guide/glasgow_exts.xml @@ -5010,63 +5010,58 @@ key_function :: Int -> String -> (Bool, Double) If you use you'll see the sequence of phase numbers for successive runs of the simplifier. In an INLINE pragma you can optionally specify a - phase number, thus: - + phase number, thus: - You can say "inline f in Phase 2 - and all subsequent phases": - - {-# INLINE [2] f #-} - - - - + "INLINE[k] f" means: do not inline + f + until phase k, but from phase + k onwards be very keen to inline it. + - You can say "inline g in all - phases up to, but not including, Phase 3": - - {-# INLINE [~3] g #-} - - - - + "INLINE[~k] f" means: be very keen to inline + f + until phase k, but from phase + k onwards do not inline it. + - If you omit the phase indicator, you mean "inline in - all phases". - + "NOINLINE[k] f" means: do not inline + f + until phase k, but from phase + k onwards be willing to inline it (as if + there was no pragma). + + + "INLINE[~k] f" means: be willing to inline + f + until phase k, but from phase + k onwards do not inline it. + - - 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": +The same information is summarised here: - {-# NOINLINE [2] f #-} - - - + -- Before phase 2 Phase 2 and later + {-# INLINE [2] f #-} -- No Yes + {-# INLINE [~2] f #-} -- Yes No + {-# NOINLINE [2] f #-} -- No Maybe + {-# NOINLINE [~2] f #-} -- Maybe No - - 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 #-} + {-# INLINE f #-} -- Yes Yes + {-# NOINLINE f #-} -- No No - - - - - If you omit the phase indicator, you mean "never - inline this function". - - - - The same phase-numbering control is available for RULES +By "Maybe" we mean that the usual heuristic inlining rules apply (if the +function body is small, or it is applied to interesting-looking arguments etc). +Another way to understand the semantics is this: + +For both INLINE and NOINLINE, the phase number says +when inlining is allowed at all. +The INLINE pragma has the additional effect of making the +function body look small, so that when inlining is allowed it is very likely to +happen. + + + +The same phase-numbering control is available for RULES (). -- 1.7.10.4