From 42b8aa9e4a054ae6784e6c90c9adc615a9703b8c Mon Sep 17 00:00:00 2001 From: "simonpj@microsoft.com" Date: Wed, 15 Sep 2010 15:42:35 +0000 Subject: [PATCH 1/1] Documentation for INLINABLE --- compiler/prelude/primops.txt.pp | 8 +-- docs/users_guide/glasgow_exts.xml | 114 +++++++++++++++++++++++++++++++++---- 2 files changed, 107 insertions(+), 15 deletions(-) diff --git a/compiler/prelude/primops.txt.pp b/compiler/prelude/primops.txt.pp index a0b991f..cb7c792 100644 --- a/compiler/prelude/primops.txt.pp +++ b/compiler/prelude/primops.txt.pp @@ -1685,11 +1685,9 @@ pseudoop "inline" {\tt inline} function expands to the identity function in Phase zero; so its use imposes no overhead. - If the function is defined in another module, GHC only exposes its inlining - in the interface file if the function is sufficiently small that it might be - inlined by the automatic mechanism. There is currently no way to tell GHC to - expose arbitrarily-large functions in the interface file. (This shortcoming - is something that could be fixed, with some kind of pragma.) } + It is good practice to mark the function with an INLINABLE pragma at + its definition, (a) so that GHC guarantees to expose its unfolding regardless + of size, and (b) so that you have control over exactly what is inlined. } pseudoop "lazy" a -> a diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml index aeb9314..3e8df7b 100644 --- a/docs/users_guide/glasgow_exts.xml +++ b/docs/users_guide/glasgow_exts.xml @@ -7594,21 +7594,68 @@ key_function :: Int -> String -> (Bool, Double) function "f" has a number of other effects: -No functions are inlined into f. Otherwise -GHC might inline a big function into f's right hand side, -making f big; and then inline f blindly. +While GHC is keen to inline the function, it does not do so +blindly. For example, if you write + +map key_function xs + +there really isn't any point in inlining key_function to get + +map (\x -> body) xs + +In general, GHC only inlines the function if there is some reason (no matter +how slight) to supose that it is useful to do so. + -The float-in, float-out, and common-sub-expression transformations are not -applied to the body of f. +Moreover, GHC will only inline the function if it is fully applied, +where "fully applied" +means applied to as many arguments as appear (syntactically) +on the LHS of the function +definition. For example: + +comp1 :: (b -> c) -> (a -> b) -> a -> c +{-# INLINE comp1 #-} +comp1 f g = \x -> f (g x) + +comp2 :: (b -> c) -> (a -> b) -> a -> c +{-# INLINE comp2 #-} +comp2 f g x = f (g x) + +The two functions comp1 and comp2 have the +same semantics, but comp1 will be inlined when applied +to two arguments, while comp2 requires +three. This might make a big difference if you say + +map (not `comp1` not) xs + +which will optimise better than the corresponding use of `comp2`. + + + +It is useful for GHC to optimise the definition of an +INLINE function f just like any other non-INLINE function, +in case the non-inlined version of f is +ultimately called. But we don't want to inline +the optimised version +of f; +a major reason for INLINE pragmas is to expose functions +in f's RHS that have +rewrite rules, and it's no good if those functions have been optimised +away. + + +So GHC guarantees to inline precisely the code that you wrote, no more +and no less. It does this by capturing a copy of the definition of the function to use +for inlining (we call this the "inline-RHS"), which it leaves untouched, +while optimising the ordinarly RHS as usual. For externally-visible functions +the inline-RHS (not the optimised RHS) is recorded in the interface file. An INLINE function is not worker/wrappered by strictness analysis. It's going to be inlined wholesale instead. -All of these effects are aimed at ensuring that what gets inlined is -exactly what you asked for, no more and no less. GHC ensures that inlining cannot go on forever: every mutually-recursive group is cut by one or more loop breakers that is never inlined @@ -7636,8 +7683,9 @@ itself, so an INLINE pragma is always ignored. {-# INLINE returnUs #-} - See also the NOINLINE pragma (). + See also the NOINLINE () + and INLINABLE () + pragmas. Note: the HBC compiler doesn't like INLINE pragmas, so if you want your code to be HBC-compatible you'll have to surround @@ -7646,6 +7694,36 @@ itself, so an INLINE pragma is always ignored. + + INLINABLE pragma + +An INLINABLE pragma works very like an INLINE pragma, except that: + + +INLINE says "please inline me", but INLINABLE says "feel free to inline me; use your +discretion". In other words the choice is left to GHC, which uses the same +rules as for pragma-free functions. Unlike INLINE, That decision is made at +the call site, and +will therefore be affected by the inlining threshold, optimisation level etc. + + +Like INLINE, the INLINABLE pragma retains a copy of the original RHS for +inlining purposes, and persists it in the interface file, regardless of +the size of the RHS. + + +If you use the special function inline () +to force inlining at a +call site, you will get a copy of the the original RHS. +Indeed, if you intend to use inline f it +is a good idea to mark the definition of f INLINABLE, +so that GHC guarantees to expose an unfolding regardless of how big it is. + + + + + + NOINLINE pragma @@ -8760,7 +8838,23 @@ r) -> GHC has a few built-in functions with special behaviour. These are now described in the module GHC.Prim -in the library documentation. +in the library documentation. +In particular: + + +inline +allows control over inlining on a per-call-site basis. + + +lazy +restrains the strictness analyser. + + +lazy +allows you to fool the type checker. + + + -- 1.7.10.4