22db69f2aef8f3fd3bb695fe925a46f7560dc827
[ghc.git] / libraries / ghc-prim / GHC / Magic.hs
1 {-# LANGUAGE Trustworthy #-}
2 {-# LANGUAGE NoImplicitPrelude #-}
3 -----------------------------------------------------------------------------
4 -- |
5 -- Module : GHC.Magic
6 -- Copyright : (c) The University of Glasgow 2009
7 -- License : see libraries/ghc-prim/LICENSE
8 --
9 -- Maintainer : cvs-ghc@haskell.org
10 -- Stability : internal
11 -- Portability : non-portable (GHC Extensions)
12 --
13 -- GHC magic.
14 --
15 -- Use GHC.Exts from the base package instead of importing this
16 -- module directly.
17 --
18 -----------------------------------------------------------------------------
19
20 module GHC.Magic ( inline, lazy, oneShot ) where
21
22 -- | The call @inline f@ arranges that 'f' is inlined, regardless of
23 -- its size. More precisely, the call @inline f@ rewrites to the
24 -- right-hand side of @f@'s definition. This allows the programmer to
25 -- control inlining from a particular call site rather than the
26 -- definition site of the function (c.f. 'INLINE' pragmas).
27 --
28 -- This inlining occurs regardless of the argument to the call or the
29 -- size of @f@'s definition; it is unconditional. The main caveat is
30 -- that @f@'s definition must be visible to the compiler; it is
31 -- therefore recommended to mark the function with an 'INLINABLE'
32 -- pragma at its definition so that GHC guarantees to record its
33 -- unfolding regardless of size.
34 --
35 -- If no inlining takes place, the 'inline' function expands to the
36 -- identity function in Phase zero, so its use imposes no overhead.
37 {-# NOINLINE[0] inline #-}
38 inline :: a -> a
39 inline x = x
40
41 -- | The 'lazy' function restrains strictness analysis a little. The
42 -- call @lazy e@ means the same as 'e', but 'lazy' has a magical
43 -- property so far as strictness analysis is concerned: it is lazy in
44 -- its first argument, even though its semantics is strict. After
45 -- strictness analysis has run, calls to 'lazy' are inlined to be the
46 -- identity function.
47 --
48 -- This behaviour is occasionally useful when controlling evaluation
49 -- order. Notably, 'lazy' is used in the library definition of
50 -- 'Control.Parallel.par':
51 --
52 -- > par :: a -> b -> b
53 -- > par x y = case (par# x) of _ -> lazy y
54 --
55 -- If 'lazy' were not lazy, 'par' would look strict in 'y' which
56 -- would defeat the whole purpose of 'par'.
57 --
58 -- Like 'seq', the argument of 'lazy' can have an unboxed type.
59 lazy :: a -> a
60 lazy x = x
61 -- Implementation note: its strictness and unfolding are over-ridden
62 -- by the definition in MkId.lhs; in both cases to nothing at all.
63 -- That way, 'lazy' does not get inlined, and the strictness analyser
64 -- sees it as lazy. Then the worker/wrapper phase inlines it.
65 -- Result: happiness
66
67
68 -- | The 'oneShot' function can be used to give a hint to the compiler that its
69 -- argument will be called at most once, which may (or may not) enable certain
70 -- optimizations. It can be useful to improve the performance of code in continuation
71 -- passing style.
72 --
73 -- If 'oneShot' is used wrongly, then it may be that computations whose result
74 -- that would otherwise be shared are re-evaluated every time they are used. Otherwise,
75 -- the use of `oneShot` is safe.
76 --
77 -- 'oneShot' is open kinded, i.e. the type variables can refer to unlifted
78 -- types as well.
79 oneShot :: (a -> b) -> (a -> b)
80 oneShot f = f
81 -- Implementation note: This is wired in in MkId.lhs, so the code here is
82 -- mostly there to have a place for the documentation.