From 22a25aa92bdbdcd4b29ada4cea187496b44bc53b Mon Sep 17 00:00:00 2001 From: "simonpj@microsoft.com" Date: Wed, 17 Nov 2010 11:15:59 +0000 Subject: [PATCH] Document SPECIALISE for imported functions This is a really useful new facility, but I'd forgotten to document it. Pls merge to 7.0 branch --- docs/users_guide/glasgow_exts.xml | 103 +++++++++++++++++++++++++++++++++---- 1 file changed, 94 insertions(+), 9 deletions(-) diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml index 161371b..dab683a 100644 --- a/docs/users_guide/glasgow_exts.xml +++ b/docs/users_guide/glasgow_exts.xml @@ -7712,27 +7712,48 @@ itself, so an INLINE pragma is always ignored. INLINABLE pragma -An INLINABLE pragma works very like an INLINE pragma, except that: +An {-# INLINABLE f #-} pragma on a +function f has the following behaviour: -INLINE says "please inline me", but INLINABLE says "feel free to inline me; use your +While INLINE says "please inline me", the 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 +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 +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, +One way to use INLINABLE is in conjunction with +the special function inline (). +The call inline f tries very hard to inline f. +To make sure that f can be inlined, +it is a good idea to mark the definition +of f as INLINABLE, so that GHC guarantees to expose an unfolding regardless of how big it is. +Moreover, by annotating f as INLINABLE, +you ensure that f's original RHS is inlined, rather than +whatever random optimised version of f GHC's optimiser +has produced. + + + +The INLINABLE pragma also works with SPECIALISE: +if you mark function f as INLINABLE, then +you can subsequently SPECIALISE in another module +(see ). + + +Unlike INLINE, it is OK to use +an INLINABLE pragma on a recursive function. +The principal reason do to so to allow later use of SPECIALISE @@ -7995,6 +8016,9 @@ RULE with a somewhat-complex left-hand side (try it yourself), so it might not f well. If you use this kind of specialisation, let us know how well it works. + + SPECIALIZE INLINE + A SPECIALIZE pragma can optionally be followed with a INLINE or NOINLINE pragma, optionally followed by a phase, as described in . @@ -8023,6 +8047,66 @@ specialisation, whose body is also inlined. The result is a type-based unrolling of the indexing function. Warning: you can make GHC diverge by using SPECIALISE INLINE on an ordinarily-recursive function. + + +SPECIALIZE for imported functions + + +Generally, you can only give a SPECIALIZE pragma +for a function defined in the same module. +However if a function f is given an INLINABLE +pragma at its definition site, then it can subequently be specialised by +importing modules (see ). +For example + +module Map( lookup, blah blah ) where + lookup :: Ord key => [(key,a)] -> key -> Maybe a + lookup = ... + {-# INLINABLE lookup #-} + +module Client where + import Map( lookup ) + + data T = T1 | T2 deriving( Eq, Ord ) + {-# SPECIALISE lookup :: [(T,a)] -> T -> Maybe a + +Here, lookup is declared INLINABLE, but +it cannot be specialised for type T at its definition site, +because that type does not exist yet. Instead a client module can define T +and then specialise lookup at that type. + + +Moreover, every module that imports Client (or imports a module +that imports Client, transitively) will "see", and make use of, +the specialised version of lookup. You don't need to put +a SPECIALIZE pragma in every module. + + +Moreover you often don't even need the SPECIALIZE pragma in the +first place. When compiling a module M, +GHC's optimiser (with -O) automatically considers each top-level +overloaded function declared in M, and specialises it +for the different types at which it is called in M. The optimiser +also considers each imported +INLINABLE overloaded function, and specialises it +for the different types at which it is called in M. +So in our example, it would be enough for lookup to +be called at type T: + +module Client where + import Map( lookup ) + + data T = T1 | T2 deriving( Eq, Ord ) + + findT1 :: [(T,a)] -> Maybe a + findT1 m = lookup m T1 -- A call of lookup at type T + +However, sometimes there are no such calls, in which case the +pragma can be useful. + + + +Obselete SPECIALIZE syntax Note: In earlier versions of GHC, it was possible to provide your own specialised function for a given type: @@ -8033,6 +8117,7 @@ on an ordinarily-recursive function. This feature has been removed, as it is now subsumed by the RULES pragma (see ). + -- 1.7.10.4