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