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