7d6f60e411e2788d8dbd0edb5ea3bac79f77cf22
[ghc.git] / libraries / ghc-prim / GHC / Magic.hs
1 {-# LANGUAGE CPP #-}
2 {-# LANGUAGE Trustworthy #-}
3 {-# LANGUAGE NoImplicitPrelude #-}
4 {-# LANGUAGE MagicHash #-}
5 {-# LANGUAGE UnboxedTuples #-}
6 {-# LANGUAGE TypeInType #-}
7 {-# LANGUAGE ScopedTypeVariables #-}
8
9 -----------------------------------------------------------------------------
10 -- |
11 -- Module : GHC.Magic
12 -- Copyright : (c) The University of Glasgow 2009
13 -- License : see libraries/ghc-prim/LICENSE
14 --
15 -- Maintainer : cvs-ghc@haskell.org
16 -- Stability : internal
17 -- Portability : non-portable (GHC Extensions)
18 --
19 -- GHC magic.
20 --
21 -- Use GHC.Exts from the base package instead of importing this
22 -- module directly.
23 --
24 -----------------------------------------------------------------------------
25
26 module GHC.Magic ( inline, noinline, lazy, oneShot, runRW# ) where
27
28 --------------------------------------------------
29 -- See Note [magicIds] in MkId.hs
30 --------------------------------------------------
31
32 import GHC.Prim
33 import GHC.CString ()
34 import GHC.Types (RuntimeRep, TYPE)
35
36 -- | The call @inline f@ arranges that 'f' is inlined, regardless of
37 -- its size. More precisely, the call @inline f@ rewrites to the
38 -- right-hand side of @f@'s definition. This allows the programmer to
39 -- control inlining from a particular call site rather than the
40 -- definition site of the function (c.f. 'INLINE' pragmas).
41 --
42 -- This inlining occurs regardless of the argument to the call or the
43 -- size of @f@'s definition; it is unconditional. The main caveat is
44 -- that @f@'s definition must be visible to the compiler; it is
45 -- therefore recommended to mark the function with an 'INLINABLE'
46 -- pragma at its definition so that GHC guarantees to record its
47 -- unfolding regardless of size.
48 --
49 -- If no inlining takes place, the 'inline' function expands to the
50 -- identity function in Phase zero, so its use imposes no overhead.
51 {-# NOINLINE[0] inline #-}
52 inline :: a -> a
53 inline x = x
54
55 -- | The call @noinline f@ arranges that 'f' will not be inlined.
56 -- It is removed during CorePrep so that its use imposes no overhead
57 -- (besides the fact that it blocks inlining.)
58 {-# NOINLINE noinline #-}
59 noinline :: a -> a
60 noinline x = x
61
62 -- | The 'lazy' function restrains strictness analysis a little. The
63 -- call @lazy e@ means the same as 'e', but 'lazy' has a magical
64 -- property so far as strictness analysis is concerned: it is lazy in
65 -- its first argument, even though its semantics is strict. After
66 -- strictness analysis has run, calls to 'lazy' are inlined to be the
67 -- identity function.
68 --
69 -- This behaviour is occasionally useful when controlling evaluation
70 -- order. Notably, 'lazy' is used in the library definition of
71 -- 'Control.Parallel.par':
72 --
73 -- > par :: a -> b -> b
74 -- > par x y = case (par# x) of _ -> lazy y
75 --
76 -- If 'lazy' were not lazy, 'par' would look strict in 'y' which
77 -- would defeat the whole purpose of 'par'.
78 --
79 -- Like 'seq', the argument of 'lazy' can have an unboxed type.
80 lazy :: a -> a
81 lazy x = x
82 -- Implementation note: its strictness and unfolding are over-ridden
83 -- by the definition in MkId.hs; in both cases to nothing at all.
84 -- That way, 'lazy' does not get inlined, and the strictness analyser
85 -- sees it as lazy. Then the worker/wrapper phase inlines it.
86 -- Result: happiness
87
88
89 -- | The 'oneShot' function can be used to give a hint to the compiler that its
90 -- argument will be called at most once, which may (or may not) enable certain
91 -- optimizations. It can be useful to improve the performance of code in continuation
92 -- passing style.
93 --
94 -- If 'oneShot' is used wrongly, then it may be that computations whose result
95 -- that would otherwise be shared are re-evaluated every time they are used. Otherwise,
96 -- the use of `oneShot` is safe.
97 --
98 -- 'oneShot' is representation polymorphic: the type variables may refer to lifted
99 -- or unlifted types.
100 oneShot :: forall (q :: RuntimeRep) (r :: RuntimeRep)
101 (a :: TYPE q) (b :: TYPE r).
102 (a -> b) -> a -> b
103 oneShot f = f
104 -- Implementation note: This is wired in in MkId.hs, so the code here is
105 -- mostly there to have a place for the documentation.
106
107 -- | Apply a function to a 'State# RealWorld' token. When manually applying
108 -- a function to `realWorld#`, it is necessary to use `NOINLINE` to prevent
109 -- semantically undesirable floating. `runRW#` is inlined, but only very late
110 -- in compilation after all floating is complete.
111
112 -- 'runRW#' is representation polymorphic: the result may have a lifted or
113 -- unlifted type.
114
115 runRW# :: forall (r :: RuntimeRep) (o :: TYPE r).
116 (State# RealWorld -> o) -> o
117 -- See Note [runRW magic] in CorePrep
118 {-# NOINLINE runRW# #-} -- runRW# is inlined manually in CorePrep
119 #if !defined(__HADDOCK_VERSION__)
120 runRW# m = m realWorld#
121 #else
122 runRW# = runRW# -- The realWorld# is too much for haddock
123 #endif