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