1{-# LANGUAGE MagicHash, NoImplicitPrelude, TypeFamilies, UnboxedTuples, 2 MultiParamTypeClasses, RoleAnnotations, CPP, TypeOperators, 3 PolyKinds #-} 4----------------------------------------------------------------------------- 5-- | 6-- Module : GHC.Types 7-- Copyright : (c) The University of Glasgow 2009 8-- License : see libraries/ghc-prim/LICENSE 9-- 10-- Maintainer : cvs-ghc@haskell.org 11-- Stability : internal 12-- Portability : non-portable (GHC Extensions) 13-- 14-- GHC type definitions. 15-- Use GHC.Exts from the base package instead of importing this 16-- module directly. 17-- 18----------------------------------------------------------------------------- 19 20module GHC.Types ( 21 -- Data types that are built-in syntax 22 -- They are defined here, but not explicitly exported 23 -- 24 -- Lists: []( [], (:) ) 25 -- Type equality: (~)( Eq# ) 26 27 Bool(..), Char(..), Int(..), Word(..), 28 Float(..), Double(..), 29 Ordering(..), IO(..), 30 isTrue#, 31 SPEC(..), 32 Nat, Symbol, 33 Any, 34 type (~~), Coercible, 35 TYPE, RuntimeRep(..), Type, Constraint, 36 -- The historical type * should ideally be written as 37 -- `type *`, without the parentheses. But that's a true 38 -- pain to parse, and for little gain. 39 VecCount(..), VecElem(..), 40 41 -- * Runtime type representation 42 Module(..), TrName(..), TyCon(..), TypeLitSort(..), 43 KindRep(..), KindBndr 44 ) where 45 46import GHC.Prim 47 48infixr 5 : 49 50{- ********************************************************************* 51* * 52 Kinds 53* * 54********************************************************************* -} 55 56-- | The kind of constraints, like @Show a@ 57data Constraint 58 59-- | The kind of types with lifted values. For example @Int :: Type@. 60type Type = TYPE 'LiftedRep 61 62{- ********************************************************************* 63* * 64 Nat and Symbol 65* * 66********************************************************************* -} 67 68-- | (Kind) This is the kind of type-level natural numbers. 69data Nat 70 71-- | (Kind) This is the kind of type-level symbols. 72-- Declared here because class IP needs it 73data Symbol 74 75{- ********************************************************************* 76* * 77 Any 78* * 79********************************************************************* -} 80 81-- | The type constructor 'Any' is type to which you can unsafely coerce any 82-- lifted type, and back. More concretely, for a lifted type @t@ and 83-- value @x :: t@, -- @unsafeCoerce (unsafeCoerce x :: Any) :: t@ is equivalent 84-- to @x@. 85-- 86type family Any :: k where { } 87-- See Note [Any types] in TysWiredIn. Also, for a bit of history on Any see 88-- #10886. Note that this must be a *closed* type family: we need to ensure 89-- that this can't reduce to a `data` type for the results discussed in 90-- Note [Any types]. 91 92{- ********************************************************************* 93* * 94 Lists 95 96 NB: lists are built-in syntax, and hence not explicitly exported 97* * 98********************************************************************* -} 99 100-- | The builtin list type, usually written in its non-prefix form @[a]@. 101-- 102-- ==== __Examples__ 103-- 104-- Unless the OverloadedLists extension is enabled, list literals are 105-- syntatic sugar for repeated applications of @:@ and @[]@. 106-- 107-- >>> 1:2:3:4:[] == [1,2,3,4] 108-- True 109-- 110-- Similarly, unless the OverloadedStrings extension is enabled, string 111-- literals are syntactic sugar for a lists of characters. 112-- 113-- >>> ['h','e','l','l','o'] == "hello" 114-- True 115-- 116data [] a = [] | a : [a] 117 118 119{- ********************************************************************* 120* * 121 Ordering 122* * 123********************************************************************* -} 124 125data Ordering = LT | EQ | GT 126 127 128{- ********************************************************************* 129* * 130 Int, Char, Word, Float, Double 131* * 132********************************************************************* -} 133 134{- | The character type 'Char' is an enumeration whose values represent 135Unicode (or equivalently ISO\/IEC 10646) code points (i.e. characters, see 136<http://www.unicode.org/> for details). This set extends the ISO 8859-1 137(Latin-1) character set (the first 256 characters), which is itself an extension 138of the ASCII character set (the first 128 characters). A character literal in 139Haskell has type 'Char'. 140 141To convert a 'Char' to or from the corresponding 'Int' value defined 142by Unicode, use 'Prelude.toEnum' and 'Prelude.fromEnum' from the 143'Prelude.Enum' class respectively (or equivalently 'Data.Char.ord' and 144'Data.Char.chr'). 145-} 146data {-# CTYPE "HsChar" #-} Char = C# Char# 147 148-- | A fixed-precision integer type with at least the range @[-2^29 .. 2^29-1]@. 149-- The exact range for a given implementation can be determined by using 150-- 'Prelude.minBound' and 'Prelude.maxBound' from the 'Prelude.Bounded' class. 151data {-# CTYPE "HsInt" #-} Int = I# Int# 152 153-- |A 'Word' is an unsigned integral type, with the same size as 'Int'. 154data {-# CTYPE "HsWord" #-} Word = W# Word# 155 156-- | Single-precision floating point numbers. 157-- It is desirable that this type be at least equal in range and precision 158-- to the IEEE single-precision type. 159data {-# CTYPE "HsFloat" #-} Float = F# Float# 160 161-- | Double-precision floating point numbers. 162-- It is desirable that this type be at least equal in range and precision 163-- to the IEEE double-precision type. 164data {-# CTYPE "HsDouble" #-} Double = D# Double# 165 166 167{- ********************************************************************* 168* * 169 IO 170* * 171********************************************************************* -} 172 173{- | 174A value of type @'IO' a@ is a computation which, when performed, 175does some I\/O before returning a value of type @a@. 176 177There is really only one way to \"perform\" an I\/O action: bind it to 178@Main.main@ in your program. When your program is run, the I\/O will 179be performed. It isn't possible to perform I\/O from an arbitrary 180function, unless that function is itself in the 'IO' monad and called 181at some point, directly or indirectly, from @Main.main@. 182 183'IO' is a monad, so 'IO' actions can be combined using either the do-notation 184or the 'Prelude.>>' and 'Prelude.>>=' operations from the 'Prelude.Monad' 185class. 186-} 187newtype IO a = IO (State# RealWorld -> (# State# RealWorld, a #)) 188type role IO representational 189 190{- The 'type role' role annotation for IO is redundant but is included 191because this role is significant in the normalisation of FFI 192types. Specifically, if this role were to become nominal (which would 193be very strange, indeed!), changes elsewhere in GHC would be 194necessary. See [FFI type roles] in TcForeign. -} 195 196 197{- ********************************************************************* 198* * 199 (~) and Coercible 200 201 NB: (~) is built-in syntax, and hence not explicitly exported 202* * 203********************************************************************* -} 204 205{- 206Note [Kind-changing of (~) and Coercible] 207~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 208 209(~) and Coercible are tricky to define. To the user, they must appear as 210constraints, but we cannot define them as such in Haskell. But we also cannot 211just define them only in GHC.Prim (like (->)), because we need a real module 212for them, e.g. to compile the constructor's info table. 213 214Furthermore the type of MkCoercible cannot be written in Haskell 215(no syntax for ~#R). 216 217So we define them as regular data types in GHC.Types, and do magic in TysWiredIn, 218inside GHC, to change the kind and type. 219-} 220 221 222-- | Lifted, heterogeneous equality. By lifted, we mean that it 223-- can be bogus (deferred type error). By heterogeneous, the two 224-- types @a@ and @b@ might have different kinds. Because @~~@ can 225-- appear unexpectedly in error messages to users who do not care 226-- about the difference between heterogeneous equality @~~@ and 227-- homogeneous equality @~@, this is printed as @~@ unless 228-- @-fprint-equality-relations@ is set. 229class a ~~ b 230 -- See also Note [The equality types story] in TysPrim 231 232-- | Lifted, homogeneous equality. By lifted, we mean that it 233-- can be bogus (deferred type error). By homogeneous, the two 234-- types @a@ and @b@ must have the same kinds. 235class a ~ b 236 -- See also Note [The equality types story] in TysPrim 237 238-- | @Coercible@ is a two-parameter class that has instances for types @a@ and @b@ if 239-- the compiler can infer that they have the same representation. This class 240-- does not have regular instances; instead they are created on-the-fly during 241-- type-checking. Trying to manually declare an instance of @Coercible@ 242-- is an error. 243-- 244-- Nevertheless one can pretend that the following three kinds of instances 245-- exist. First, as a trivial base-case: 246-- 247-- @instance Coercible a a@ 248-- 249-- Furthermore, for every type constructor there is 250-- an instance that allows to coerce under the type constructor. For 251-- example, let @D@ be a prototypical type constructor (@data@ or 252-- @newtype@) with three type arguments, which have roles @nominal@, 253-- @representational@ resp. @phantom@. Then there is an instance of 254-- the form 255-- 256-- @instance Coercible b b\' => Coercible (D a b c) (D a b\' c\')@ 257-- 258-- Note that the @nominal@ type arguments are equal, the 259-- @representational@ type arguments can differ, but need to have a 260-- @Coercible@ instance themself, and the @phantom@ type arguments can be 261-- changed arbitrarily. 262-- 263-- The third kind of instance exists for every @newtype NT = MkNT T@ and 264-- comes in two variants, namely 265-- 266-- @instance Coercible a T => Coercible a NT@ 267-- 268-- @instance Coercible T b => Coercible NT b@ 269-- 270-- This instance is only usable if the constructor @MkNT@ is in scope. 271-- 272-- If, as a library author of a type constructor like @Set a@, you 273-- want to prevent a user of your module to write 274-- @coerce :: Set T -> Set NT@, 275-- you need to set the role of @Set@\'s type parameter to @nominal@, 276-- by writing 277-- 278-- @type role Set nominal@ 279-- 280-- For more details about this feature, please refer to 281-- <http://research.microsoft.com/en-us/um/people/simonpj/papers/ext-f/coercible.pdf Safe Coercions> 282-- by Joachim Breitner, Richard A. Eisenberg, Simon Peyton Jones and Stephanie Weirich. 283-- 284-- @since 4.7.0.0 285class Coercible (a :: k) (b :: k) 286 -- See also Note [The equality types story] in TysPrim 287 288{- ********************************************************************* 289* * 290 Bool, and isTrue# 291* * 292********************************************************************* -} 293 294data {-# CTYPE "HsBool" #-} Bool = False | True 295 296{-# INLINE isTrue# #-} 297-- | Alias for 'tagToEnum#'. Returns True if its parameter is 1# and False 298-- if it is 0#. 299isTrue# :: Int# -> Bool -- See Note [Optimizing isTrue#] 300isTrue# x = tagToEnum# x 301 302{- Note [Optimizing isTrue#] 303~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 304Current definition of isTrue# is a temporary workaround. We would like to 305have functions isTrue# and isFalse# defined like this: 306 307 isTrue# :: Int# -> Bool 308 isTrue# 1# = True 309 isTrue# _ = False 310 311 isFalse# :: Int# -> Bool 312 isFalse# 0# = True 313 isFalse# _ = False 314 315These functions would allow us to safely check if a tag can represent True 316or False. Using isTrue# and isFalse# as defined above will not introduce 317additional case into the code. When we scrutinize return value of isTrue# 318or isFalse#, either explicitly in a case expression or implicitly in a guard, 319the result will always be a single case expression (given that optimizations 320are turned on). This results from case-of-case transformation. Consider this 321code (this is both valid Haskell and Core): 322 323case isTrue# (a ># b) of 324 True -> e1 325 False -> e2 326 327Inlining isTrue# gives: 328 329case (case (a ># b) of { 1# -> True; _ -> False } ) of 330 True -> e1 331 False -> e2 332 333Case-of-case transforms that to: 334 335case (a ># b) of 336 1# -> case True of 337 True -> e1 338 False -> e2 339 _ -> case False of 340 True -> e1 341 False -> e2 342 343Which is then simplified by case-of-known-constructor: 344 345case (a ># b) of 346 1# -> e1 347 _ -> e2 348 349While we get good Core here, the code generator will generate very bad Cmm 350if e1 or e2 do allocation. It will push heap checks into case alternatives 351which results in about 2.5% increase in code size. Until this is improved we 352just make isTrue# an alias to tagToEnum#. This is a temporary solution (if 353you're reading this in 2023 then things went wrong). See #8326. 354-} 355 356 357{- ********************************************************************* 358* * 359 SPEC 360* * 361********************************************************************* -} 362 363-- | 'SPEC' is used by GHC in the @SpecConstr@ pass in order to inform 364-- the compiler when to be particularly aggressive. In particular, it 365-- tells GHC to specialize regardless of size or the number of 366-- specializations. However, not all loops fall into this category. 367-- 368-- Libraries can specify this by using 'SPEC' data type to inform which 369-- loops should be aggressively specialized. 370data SPEC = SPEC | SPEC2 371 372 373{- ********************************************************************* 374* * 375 Levity polymorphism 376* * 377********************************************************************* -} 378 379 380-- | GHC maintains a property that the kind of all inhabited types 381-- (as distinct from type constructors or type-level data) tells us 382-- the runtime representation of values of that type. This datatype 383-- encodes the choice of runtime value. 384-- Note that 'TYPE' is parameterised by 'RuntimeRep'; this is precisely 385-- what we mean by the fact that a type's kind encodes the runtime 386-- representation. 387-- 388-- For boxed values (that is, values that are represented by a pointer), 389-- a further distinction is made, between lifted types (that contain ⊥), 390-- and unlifted ones (that don't). 391data RuntimeRep = VecRep VecCount VecElem -- ^ a SIMD vector type 392 | TupleRep [RuntimeRep] -- ^ An unboxed tuple of the given reps 393 | SumRep [RuntimeRep] -- ^ An unboxed sum of the given reps 394 | LiftedRep -- ^ lifted; represented by a pointer 395 | UnliftedRep -- ^ unlifted; represented by a pointer 396 | IntRep -- ^ signed, word-sized value 397 | Int8Rep -- ^ signed, 8-bit value 398 | Int16Rep -- ^ signed, 16-bit value 399 | Int32Rep -- ^ signed, 32-bit value 400 | Int64Rep -- ^ signed, 64-bit value (on 32-bit only) 401 | WordRep -- ^ unsigned, word-sized value 402 | Word8Rep -- ^ unsigned, 8-bit value 403 | Word16Rep -- ^ unsigned, 16-bit value 404 | Word32Rep -- ^ unsigned, 32-bit value 405 | Word64Rep -- ^ unsigned, 64-bit value (on 32-bit only) 406 | AddrRep -- ^ A pointer, but /not/ to a Haskell value 407 | FloatRep -- ^ a 32-bit floating point number 408 | DoubleRep -- ^ a 64-bit floating point number 409 410-- RuntimeRep is intimately tied to TyCon.RuntimeRep (in GHC proper). See 411-- Note [RuntimeRep and PrimRep] in RepType. 412-- See also Note [Wiring in RuntimeRep] in TysWiredIn 413 414-- | Length of a SIMD vector type 415data VecCount = Vec2 416 | Vec4 417 | Vec8 418 | Vec16 419 | Vec32 420 | Vec64 421-- Enum, Bounded instances in GHC.Enum 422 423-- | Element of a SIMD vector type 424data VecElem = Int8ElemRep 425 | Int16ElemRep 426 | Int32ElemRep 427 | Int64ElemRep 428 | Word8ElemRep 429 | Word16ElemRep 430 | Word32ElemRep 431 | Word64ElemRep 432 | FloatElemRep 433 | DoubleElemRep 434-- Enum, Bounded instances in GHC.Enum 435 436{- ********************************************************************* 437* * 438 Runtime representation of TyCon 439* * 440********************************************************************* -} 441 442{- Note [Runtime representation of modules and tycons] 443~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 444We generate a binding for M.$modName and M.$tcT for every module M and 445data type T. Things to think about 446 447 - We want them to be economical on space; ideally pure data with no thunks. 448 449 - We do this for every module (except this module GHC.Types), so we can't 450 depend on anything else (eg string unpacking code) 451 452That's why we have these terribly low-level representations. The TrName 453type lets us use the TrNameS constructor when allocating static data; 454but we also need TrNameD for the case where we are deserialising a TyCon 455or Module (for example when deserialising a TypeRep), in which case we 456can't conveniently come up with an Addr#. 457-} 458 459#include "MachDeps.h" 460 461data Module = Module 462 TrName -- Package name 463 TrName -- Module name 464 465data TrName 466 = TrNameS Addr# -- Static 467 | TrNameD [Char] -- Dynamic 468 469-- | A de Bruijn index for a binder within a 'KindRep'. 470type KindBndr = Int 471 472#if WORD_SIZE_IN_BITS < 64 473#define WORD64_TY Word64# 474#else 475#define WORD64_TY Word# 476#endif 477 478-- | The representation produced by GHC for conjuring up the kind of a 479-- 'Data.Typeable.TypeRep'. 480 481-- See Note [Representing TyCon kinds: KindRep] in TcTypeable. 482data KindRep = KindRepTyConApp TyCon [KindRep] 483 | KindRepVar !KindBndr 484 | KindRepApp KindRep KindRep 485 | KindRepFun KindRep KindRep 486 | KindRepTYPE !RuntimeRep 487 | KindRepTypeLitS TypeLitSort Addr# 488 | KindRepTypeLitD TypeLitSort [Char] 489 490data TypeLitSort = TypeLitSymbol 491 | TypeLitNat 492 493-- Show instance for TyCon found in GHC.Show 494data TyCon = TyCon WORD64_TY WORD64_TY -- Fingerprint 495 Module -- Module in which this is defined 496 TrName -- Type constructor name 497 Int# -- How many kind variables do we accept? 498 KindRep -- A representation of the type's kind 499