b30db97400c140fa23222bd4e34d2782180ac7ab
[ghc.git] / libraries / ghc-prim / GHC / Types.hs
1 {-# LANGUAGE MagicHash, NoImplicitPrelude, TypeFamilies, UnboxedTuples,
2 MultiParamTypeClasses, RoleAnnotations, CPP, TypeOperators #-}
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 type (~~), Coercible,
33 TYPE, Levity(..), Type, type (*), type (), Constraint,
34 -- The historical type * should ideally be written as
35 -- `type *`, without the parentheses. But that's a true
36 -- pain to parse, and for little gain.
37
38 -- * Runtime type representation
39 Module(..), TrName(..), TyCon(..)
40 ) where
41
42 import GHC.Prim
43
44 infixr 5 :
45
46 {- *********************************************************************
47 * *
48 Kinds
49 * *
50 ********************************************************************* -}
51
52 -- | The kind of constraints, like @Show a@
53 data Constraint
54
55 -- | The kind of types with values. For example @Int :: Type@.
56 type Type = TYPE 'Lifted
57
58 -- | A backward-compatible (pre-GHC 8.0) synonym for 'Type'
59 type * = TYPE 'Lifted
60
61 -- | A unicode backward-compatible (pre-GHC 8.0) synonym for 'Type'
62 type= TYPE 'Lifted
63
64 {- *********************************************************************
65 * *
66 Nat and Symbol
67 * *
68 ********************************************************************* -}
69
70 -- | (Kind) This is the kind of type-level natural numbers.
71 data Nat
72
73 -- | (Kind) This is the kind of type-level symbols.
74 -- Declared here because class IP needs it
75 data Symbol
76
77 {- *********************************************************************
78 * *
79 Lists
80
81 NB: lists are built-in syntax, and hence not explicitly exported
82 * *
83 ********************************************************************* -}
84
85 data [] a = [] | a : [a]
86
87
88 {- *********************************************************************
89 * *
90 Ordering
91 * *
92 ********************************************************************* -}
93
94 data Ordering = LT | EQ | GT
95
96
97 {- *********************************************************************
98 * *
99 Int, Char, Word, Float, Double
100 * *
101 ********************************************************************* -}
102
103 {- | The character type 'Char' is an enumeration whose values represent
104 Unicode (or equivalently ISO\/IEC 10646) characters (see
105 <http://www.unicode.org/> for details). This set extends the ISO 8859-1
106 (Latin-1) character set (the first 256 characters), which is itself an extension
107 of the ASCII character set (the first 128 characters). A character literal in
108 Haskell has type 'Char'.
109
110 To convert a 'Char' to or from the corresponding 'Int' value defined
111 by Unicode, use 'Prelude.toEnum' and 'Prelude.fromEnum' from the
112 'Prelude.Enum' class respectively (or equivalently 'ord' and 'chr').
113 -}
114 data {-# CTYPE "HsChar" #-} Char = C# Char#
115
116 -- | A fixed-precision integer type with at least the range @[-2^29 .. 2^29-1]@.
117 -- The exact range for a given implementation can be determined by using
118 -- 'Prelude.minBound' and 'Prelude.maxBound' from the 'Prelude.Bounded' class.
119 data {-# CTYPE "HsInt" #-} Int = I# Int#
120
121 -- |A 'Word' is an unsigned integral type, with the same size as 'Int'.
122 data {-# CTYPE "HsWord" #-} Word = W# Word#
123
124 -- | Single-precision floating point numbers.
125 -- It is desirable that this type be at least equal in range and precision
126 -- to the IEEE single-precision type.
127 data {-# CTYPE "HsFloat" #-} Float = F# Float#
128
129 -- | Double-precision floating point numbers.
130 -- It is desirable that this type be at least equal in range and precision
131 -- to the IEEE double-precision type.
132 data {-# CTYPE "HsDouble" #-} Double = D# Double#
133
134
135 {- *********************************************************************
136 * *
137 IO
138 * *
139 ********************************************************************* -}
140
141 {- |
142 A value of type @'IO' a@ is a computation which, when performed,
143 does some I\/O before returning a value of type @a@.
144
145 There is really only one way to \"perform\" an I\/O action: bind it to
146 @Main.main@ in your program. When your program is run, the I\/O will
147 be performed. It isn't possible to perform I\/O from an arbitrary
148 function, unless that function is itself in the 'IO' monad and called
149 at some point, directly or indirectly, from @Main.main@.
150
151 'IO' is a monad, so 'IO' actions can be combined using either the do-notation
152 or the '>>' and '>>=' operations from the 'Monad' class.
153 -}
154 newtype IO a = IO (State# RealWorld -> (# State# RealWorld, a #))
155 type role IO representational
156
157 {- The 'type role' role annotation for IO is redundant but is included
158 because this role is significant in the normalisation of FFI
159 types. Specifically, if this role were to become nominal (which would
160 be very strange, indeed!), changes elsewhere in GHC would be
161 necessary. See [FFI type roles] in TcForeign. -}
162
163
164 {- *********************************************************************
165 * *
166 (~) and Coercible
167
168 NB: (~) is built-in syntax, and hence not explicitly exported
169 * *
170 ********************************************************************* -}
171
172 {-
173 Note [Kind-changing of (~) and Coercible]
174 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
175
176 (~) and Coercible are tricky to define. To the user, they must appear as
177 constraints, but we cannot define them as such in Haskell. But we also cannot
178 just define them only in GHC.Prim (like (->)), because we need a real module
179 for them, e.g. to compile the constructor's info table.
180
181 Furthermore the type of MkCoercible cannot be written in Haskell
182 (no syntax for ~#R).
183
184 So we define them as regular data types in GHC.Types, and do magic in TysWiredIn,
185 inside GHC, to change the kind and type.
186 -}
187
188
189 -- | Lifted, heterogeneous equality. By lifted, we mean that it
190 -- can be bogus (deferred type error). By heterogeneous, the two
191 -- types @a@ and @b@ might have different kinds.
192 class a ~~ b
193 -- See also Note [The equality types story] in TysPrim
194
195 -- | @Coercible@ is a two-parameter class that has instances for types @a@ and @b@ if
196 -- the compiler can infer that they have the same representation. This class
197 -- does not have regular instances; instead they are created on-the-fly during
198 -- type-checking. Trying to manually declare an instance of @Coercible@
199 -- is an error.
200 --
201 -- Nevertheless one can pretend that the following three kinds of instances
202 -- exist. First, as a trivial base-case:
203 --
204 -- @instance a a@
205 --
206 -- Furthermore, for every type constructor there is
207 -- an instance that allows to coerce under the type constructor. For
208 -- example, let @D@ be a prototypical type constructor (@data@ or
209 -- @newtype@) with three type arguments, which have roles @nominal@,
210 -- @representational@ resp. @phantom@. Then there is an instance of
211 -- the form
212 --
213 -- @instance Coercible b b\' => Coercible (D a b c) (D a b\' c\')@
214 --
215 -- Note that the @nominal@ type arguments are equal, the
216 -- @representational@ type arguments can differ, but need to have a
217 -- @Coercible@ instance themself, and the @phantom@ type arguments can be
218 -- changed arbitrarily.
219 --
220 -- The third kind of instance exists for every @newtype NT = MkNT T@ and
221 -- comes in two variants, namely
222 --
223 -- @instance Coercible a T => Coercible a NT@
224 --
225 -- @instance Coercible T b => Coercible NT b@
226 --
227 -- This instance is only usable if the constructor @MkNT@ is in scope.
228 --
229 -- If, as a library author of a type constructor like @Set a@, you
230 -- want to prevent a user of your module to write
231 -- @coerce :: Set T -> Set NT@,
232 -- you need to set the role of @Set@\'s type parameter to @nominal@,
233 -- by writing
234 --
235 -- @type role Set nominal@
236 --
237 -- For more details about this feature, please refer to
238 -- <http://www.cis.upenn.edu/~eir/papers/2014/coercible/coercible.pdf Safe Coercions>
239 -- by Joachim Breitner, Richard A. Eisenberg, Simon Peyton Jones and Stephanie Weirich.
240 --
241 -- @since 4.7.0.0
242 class Coercible a b
243 -- See also Note [The equality types story] in TysPrim
244
245 {- *********************************************************************
246 * *
247 Bool, and isTrue#
248 * *
249 ********************************************************************* -}
250
251 data {-# CTYPE "HsBool" #-} Bool = False | True
252
253 {-# INLINE isTrue# #-}
254 -- | Alias for 'tagToEnum#'. Returns True if its parameter is 1# and False
255 -- if it is 0#.
256 isTrue# :: Int# -> Bool -- See Note [Optimizing isTrue#]
257 isTrue# x = tagToEnum# x
258
259 {- Note [Optimizing isTrue#]
260 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
261 Current definition of isTrue# is a temporary workaround. We would like to
262 have functions isTrue# and isFalse# defined like this:
263
264 isTrue# :: Int# -> Bool
265 isTrue# 1# = True
266 isTrue# _ = False
267
268 isFalse# :: Int# -> Bool
269 isFalse# 0# = True
270 isFalse# _ = False
271
272 These functions would allow us to safely check if a tag can represent True
273 or False. Using isTrue# and isFalse# as defined above will not introduce
274 additional case into the code. When we scrutinize return value of isTrue#
275 or isFalse#, either explicitly in a case expression or implicitly in a guard,
276 the result will always be a single case expression (given that optimizations
277 are turned on). This results from case-of-case transformation. Consider this
278 code (this is both valid Haskell and Core):
279
280 case isTrue# (a ># b) of
281 True -> e1
282 False -> e2
283
284 Inlining isTrue# gives:
285
286 case (case (a ># b) of { 1# -> True; _ -> False } ) of
287 True -> e1
288 False -> e2
289
290 Case-of-case transforms that to:
291
292 case (a ># b) of
293 1# -> case True of
294 True -> e1
295 False -> e2
296 _ -> case False of
297 True -> e1
298 False -> e2
299
300 Which is then simplified by case-of-known-constructor:
301
302 case (a ># b) of
303 1# -> e1
304 _ -> e2
305
306 While we get good Core here, the code generator will generate very bad Cmm
307 if e1 or e2 do allocation. It will push heap checks into case alternatives
308 which results in about 2.5% increase in code size. Until this is improved we
309 just make isTrue# an alias to tagToEnum#. This is a temporary solution (if
310 you're reading this in 2023 then things went wrong). See #8326.
311 -}
312
313
314 {- *********************************************************************
315 * *
316 SPEC
317 * *
318 ********************************************************************* -}
319
320 -- | 'SPEC' is used by GHC in the @SpecConstr@ pass in order to inform
321 -- the compiler when to be particularly aggressive. In particular, it
322 -- tells GHC to specialize regardless of size or the number of
323 -- specializations. However, not all loops fall into this category.
324 --
325 -- Libraries can specify this by using 'SPEC' data type to inform which
326 -- loops should be aggressively specialized.
327 data SPEC = SPEC | SPEC2
328
329 -- | GHC divides all proper types (that is, types that can perhaps be
330 -- inhabited, as distinct from type constructors or type-level data)
331 -- into two worlds: lifted types and unlifted types. For example,
332 -- @Int@ is lifted while @Int#@ is unlifted. Certain operations need
333 -- to be polymorphic in this distinction. A classic example is 'unsafeCoerce#',
334 -- which needs to be able to coerce between lifted and unlifted types.
335 -- To achieve this, we use kind polymorphism: lifted types have kind
336 -- @TYPE Lifted@ and unlifted ones have kind @TYPE Unlifted@. 'Levity'
337 -- is the kind of 'Lifted' and 'Unlifted'. @*@ is a synonym for @TYPE Lifted@
338 -- and @#@ is a synonym for @TYPE Unlifted@.
339 data Levity = Lifted | Unlifted
340
341 {- *********************************************************************
342 * *
343 Runtime represntation of TyCon
344 * *
345 ********************************************************************* -}
346
347 {- Note [Runtime representation of modules and tycons]
348 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
349 We generate a binding for M.$modName and M.$tcT for every module M and
350 data type T. Things to think about
351
352 - We want them to be economical on space; ideally pure data with no thunks.
353
354 - We do this for every module (except this module GHC.Types), so we can't
355 depend on anything else (eg string unpacking code)
356
357 That's why we have these terribly low-level repesentations. The TrName
358 type lets us use the TrNameS constructor when allocating static data;
359 but we also need TrNameD for the case where we are deserialising a TyCon
360 or Module (for example when deserialising a TypeRep), in which case we
361 can't conveniently come up with an Addr#.
362
363
364 Note [Representations of types defined in GHC.Types]
365 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
366
367 The representations for the types defined in GHC.Types are
368 defined in GHC.Typeable.Internal.
369
370 -}
371
372 #include "MachDeps.h"
373
374 data Module = Module
375 TrName -- Package name
376 TrName -- Module name
377
378 data TrName
379 = TrNameS Addr# -- Static
380 | TrNameD [Char] -- Dynamic
381
382 #if WORD_SIZE_IN_BITS < 64
383 data TyCon = TyCon
384 Word64# Word64# -- Fingerprint
385 Module -- Module in which this is defined
386 TrName -- Type constructor name
387 #else
388 data TyCon = TyCon
389 Word# Word#
390 Module
391 TrName
392 #endif