7bc746f2568223cdd6a37a2c649a359502751b4c
[ghc.git] / libraries / ghc-prim / GHC / Types.hs
1 {-# LANGUAGE MagicHash, NoImplicitPrelude, TypeFamilies, UnboxedTuples,
2 MultiParamTypeClasses, RoleAnnotations #-}
3 -----------------------------------------------------------------------------
4 -- |
5 -- Module : GHC.Types
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 type definitions.
14 -- Use GHC.Exts from the base package instead of importing this
15 -- module directly.
16 --
17 -----------------------------------------------------------------------------
18
19 module GHC.Types (
20 -- Data types that are built-in syntax
21 -- They are defined here, but not explicitly exported
22 --
23 -- Lists: []( [], (:) )
24 -- Type equality: (~)( Eq# )
25
26 Bool(..), Char(..), Int(..), Word(..),
27 Float(..), Double(..),
28 Ordering(..), IO(..),
29 isTrue#,
30 SPEC(..),
31 Nat, Symbol,
32 Coercible,
33 ) where
34
35 import GHC.Prim
36
37
38 infixr 5 :
39
40 {- *********************************************************************
41 * *
42 Nat and Symbol
43 * *
44 ********************************************************************* -}
45
46 -- | (Kind) This is the kind of type-level natural numbers.
47 data Nat
48
49 -- | (Kind) This is the kind of type-level symbols.
50 -- Declared here because class IP needs it
51 data Symbol
52
53
54 {- *********************************************************************
55 * *
56 Lists
57
58 NB: lists are built-in syntax, and hence not explicitly exported
59 * *
60 ********************************************************************* -}
61
62 data [] a = [] | a : [a]
63
64
65 {- *********************************************************************
66 * *
67 Ordering
68 * *
69 ********************************************************************* -}
70
71 data Ordering = LT | EQ | GT
72
73
74 {- *********************************************************************
75 * *
76 Int, Char, Word, Float, Double
77 * *
78 ********************************************************************* -}
79
80 {- | The character type 'Char' is an enumeration whose values represent
81 Unicode (or equivalently ISO\/IEC 10646) characters (see
82 <http://www.unicode.org/> for details). This set extends the ISO 8859-1
83 (Latin-1) character set (the first 256 characters), which is itself an extension
84 of the ASCII character set (the first 128 characters). A character literal in
85 Haskell has type 'Char'.
86
87 To convert a 'Char' to or from the corresponding 'Int' value defined
88 by Unicode, use 'Prelude.toEnum' and 'Prelude.fromEnum' from the
89 'Prelude.Enum' class respectively (or equivalently 'ord' and 'chr').
90 -}
91 data {-# CTYPE "HsChar" #-} Char = C# Char#
92
93 -- | A fixed-precision integer type with at least the range @[-2^29 .. 2^29-1]@.
94 -- The exact range for a given implementation can be determined by using
95 -- 'Prelude.minBound' and 'Prelude.maxBound' from the 'Prelude.Bounded' class.
96 data {-# CTYPE "HsInt" #-} Int = I# Int#
97
98 -- |A 'Word' is an unsigned integral type, with the same size as 'Int'.
99 data {-# CTYPE "HsWord" #-} Word = W# Word#
100
101 -- | Single-precision floating point numbers.
102 -- It is desirable that this type be at least equal in range and precision
103 -- to the IEEE single-precision type.
104 data {-# CTYPE "HsFloat" #-} Float = F# Float#
105
106 -- | Double-precision floating point numbers.
107 -- It is desirable that this type be at least equal in range and precision
108 -- to the IEEE double-precision type.
109 data {-# CTYPE "HsDouble" #-} Double = D# Double#
110
111
112 {- *********************************************************************
113 * *
114 IO
115 * *
116 ********************************************************************* -}
117
118 {- |
119 A value of type @'IO' a@ is a computation which, when performed,
120 does some I\/O before returning a value of type @a@.
121
122 There is really only one way to \"perform\" an I\/O action: bind it to
123 @Main.main@ in your program. When your program is run, the I\/O will
124 be performed. It isn't possible to perform I\/O from an arbitrary
125 function, unless that function is itself in the 'IO' monad and called
126 at some point, directly or indirectly, from @Main.main@.
127
128 'IO' is a monad, so 'IO' actions can be combined using either the do-notation
129 or the '>>' and '>>=' operations from the 'Monad' class.
130 -}
131 newtype IO a = IO (State# RealWorld -> (# State# RealWorld, a #))
132 type role IO representational
133
134 {- The 'type role' role annotation for IO is redundant but is included
135 because this role is significant in the normalisation of FFI
136 types. Specifically, if this role were to become nominal (which would
137 be very strange, indeed!), changes elsewhere in GHC would be
138 necessary. See [FFI type roles] in TcForeign. -}
139
140
141 {- *********************************************************************
142 * *
143 (~) and Coercible
144
145 NB: (~) is built-in syntax, and hence not explicitly exported
146 * *
147 ********************************************************************* -}
148
149 {-
150 Note [Kind-changing of (~) and Coercible]
151 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
152
153 (~) and Coercible are tricky to define. To the user, they must appear as
154 constraints, but we cannot define them as such in Haskell. But we also cannot
155 just define them only in GHC.Prim (like (->)), because we need a real module
156 for them, e.g. to compile the constructor's info table.
157
158 Furthermore the type of MkCoercible cannot be written in Haskell
159 (no syntax for ~#R).
160
161 So we define them as regular data types in GHC.Types, and do magic in TysWiredIn,
162 inside GHC, to change the kind and type.
163 -}
164
165
166 -- | A data constructor used to box up all unlifted equalities
167 --
168 -- The type constructor is special in that GHC pretends that it
169 -- has kind (? -> ? -> Fact) rather than (* -> * -> *)
170 data (~) a b = Eq# ((~#) a b)
171
172
173 -- | This two-parameter class has instances for types @a@ and @b@ if
174 -- the compiler can infer that they have the same representation. This class
175 -- does not have regular instances; instead they are created on-the-fly during
176 -- type-checking. Trying to manually declare an instance of @Coercible@
177 -- is an error.
178 --
179 -- Nevertheless one can pretend that the following three kinds of instances
180 -- exist. First, as a trivial base-case:
181 --
182 -- @instance a a@
183 --
184 -- Furthermore, for every type constructor there is
185 -- an instance that allows to coerce under the type constructor. For
186 -- example, let @D@ be a prototypical type constructor (@data@ or
187 -- @newtype@) with three type arguments, which have roles @nominal@,
188 -- @representational@ resp. @phantom@. Then there is an instance of
189 -- the form
190 --
191 -- @instance Coercible b b\' => Coercible (D a b c) (D a b\' c\')@
192 --
193 -- Note that the @nominal@ type arguments are equal, the
194 -- @representational@ type arguments can differ, but need to have a
195 -- @Coercible@ instance themself, and the @phantom@ type arguments can be
196 -- changed arbitrarily.
197 --
198 -- The third kind of instance exists for every @newtype NT = MkNT T@ and
199 -- comes in two variants, namely
200 --
201 -- @instance Coercible a T => Coercible a NT@
202 --
203 -- @instance Coercible T b => Coercible NT b@
204 --
205 -- This instance is only usable if the constructor @MkNT@ is in scope.
206 --
207 -- If, as a library author of a type constructor like @Set a@, you
208 -- want to prevent a user of your module to write
209 -- @coerce :: Set T -> Set NT@,
210 -- you need to set the role of @Set@\'s type parameter to @nominal@,
211 -- by writing
212 --
213 -- @type role Set nominal@
214 --
215 -- For more details about this feature, please refer to
216 -- <http://www.cis.upenn.edu/~eir/papers/2014/coercible/coercible.pdf Safe Coercions>
217 -- by Joachim Breitner, Richard A. Eisenberg, Simon Peyton Jones and Stephanie Weirich.
218 --
219 -- @since 4.7.0.0
220 data Coercible a b = MkCoercible ((~#) a b)
221 -- It's really ~R# (representational equality), not ~#,
222 -- but * we don't yet have syntax for ~R#,
223 -- * the compiled code is the same either way
224 -- * TysWiredIn has the truthful types
225 -- Also see Note [Kind-changing of (~) and Coercible]
226
227 -- | Alias for 'tagToEnum#'. Returns True if its parameter is 1# and False
228 -- if it is 0#.
229
230 {- *********************************************************************
231 * *
232 Bool, and isTrue#
233 * *
234 ********************************************************************* -}
235
236 data {-# CTYPE "HsBool" #-} Bool = False | True
237
238 {-# INLINE isTrue# #-}
239 isTrue# :: Int# -> Bool -- See Note [Optimizing isTrue#]
240 isTrue# x = tagToEnum# x
241
242 {- Note [Optimizing isTrue#]
243 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
244 Current definition of isTrue# is a temporary workaround. We would like to
245 have functions isTrue# and isFalse# defined like this:
246
247 isTrue# :: Int# -> Bool
248 isTrue# 1# = True
249 isTrue# _ = False
250
251 isFalse# :: Int# -> Bool
252 isFalse# 0# = True
253 isFalse# _ = False
254
255 These functions would allow us to safely check if a tag can represent True
256 or False. Using isTrue# and isFalse# as defined above will not introduce
257 additional case into the code. When we scrutinize return value of isTrue#
258 or isFalse#, either explicitly in a case expression or implicitly in a guard,
259 the result will always be a single case expression (given that optimizations
260 are turned on). This results from case-of-case transformation. Consider this
261 code (this is both valid Haskell and Core):
262
263 case isTrue# (a ># b) of
264 True -> e1
265 False -> e2
266
267 Inlining isTrue# gives:
268
269 case (case (a ># b) of { 1# -> True; _ -> False } ) of
270 True -> e1
271 False -> e2
272
273 Case-of-case transforms that to:
274
275 case (a ># b) of
276 1# -> case True of
277 True -> e1
278 False -> e2
279 _ -> case False of
280 True -> e1
281 False -> e2
282
283 Which is then simplified by case-of-known-constructor:
284
285 case (a ># b) of
286 1# -> e1
287 _ -> e2
288
289 While we get good Core here, the code generator will generate very bad Cmm
290 if e1 or e2 do allocation. It will push heap checks into case alternatives
291 which results in about 2.5% increase in code size. Until this is improved we
292 just make isTrue# an alias to tagToEnum#. This is a temporary solution (if
293 you're reading this in 2023 then things went wrong). See #8326.
294 -}
295
296
297 {- *********************************************************************
298 * *
299 SPEC
300 * *
301 ********************************************************************* -}
302
303 -- | 'SPEC' is used by GHC in the @SpecConstr@ pass in order to inform
304 -- the compiler when to be particularly aggressive. In particular, it
305 -- tells GHC to specialize regardless of size or the number of
306 -- specializations. However, not all loops fall into this category.
307 --
308 -- Libraries can specify this by using 'SPEC' data type to inform which
309 -- loops should be aggressively specialized.
310 data SPEC = SPEC | SPEC2