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