compiler/prelude/primops.txt.pp

   1 -----------------------------------------------------------------------
   2 -- $Id: primops.txt.pp,v 1.37 2005/11/25 09:46:19 simonmar Exp $
   3 --
   4 -- Primitive Operations and Types
   5 --
   6 -----------------------------------------------------------------------
   7
   8 -- This file is processed by the utility program genprimopcode to produce
   9 -- a number of include files within the compiler and optionally to produce
  10 -- human-readable documentation.
  11 --
  12 -- It should first be preprocessed.
  13 --
  14 -- To add a new primop, you currently need to update the following files:
  15 --
  16 --      - this file (ghc/compiler/prelude/primops.txt.pp), which includes
  17 --        the type of the primop, and various other properties (its
  18 --        strictness attributes, whether it is defined as a macro
  19 --        or as out-of-line code, etc.)
  20 --
  21 --      - if the primop is inline (i.e. a macro), then:
  22 --              ghc/compiler/AbsCUtils.lhs (dscCOpStmt)
  23 --                defines the translation of the primop into simpler
  24 --                abstract C operations.
  25 --
  26 --      - or, for an out-of-line primop:
  27 --              ghc/includes/StgMiscClosures.h (just add the declaration)
  28 --              ghc/rts/PrimOps.cmm     (define it here)
  29 --              ghc/rts/Linker.c       (declare the symbol for GHCi)
  30 --
  31 --      - the User's Guide
  32 --
  33
  34 -- This file is divided into named sections, each containing or more
  35 -- primop entries. Section headers have the format:
  36 --
  37 --      section "section-name" {description}
  38 --
  39 -- This information is used solely when producing documentation; it is
  40 -- otherwise ignored.  The description is optional.
  41 --
  42 -- The format of each primop entry is as follows:
  43 --
  44 --      primop internal-name "name-in-program-text" type category {description} attributes
  45
  46 -- The default attribute values which apply if you don't specify
  47 -- other ones.  Attribute values can be True, False, or arbitrary
  48 -- text between curly brackets.  This is a kludge to enable
  49 -- processors of this file to easily get hold of simple info
  50 -- (eg, out_of_line), whilst avoiding parsing complex expressions
  51 -- needed for strictness info.
  52
  53 defaults
  54    has_side_effects = False
  55    out_of_line      = False
  56    commutable       = False
  57    needs_wrapper    = False
  58    can_fail         = False
  59    strictness       = { \ arity -> mkStrictSig (mkTopDmdType (replicate arity lazyDmd) TopRes) }
  60
  61 -- Currently, documentation is produced using latex, so contents of
  62 -- description fields should be legal latex. Descriptions can contain
  63 -- matched pairs of embedded curly brackets.
  64
  65 #include "MachDeps.h"
  66
  67 -- We need platform defines (tests for mingw32 below).  However, we only
  68 -- test the TARGET platform, which doesn't vary between stages, so the
  69 -- stage1 platform defines are fine:
  70 #include "../stage1/ghc_boot_platform.h"
  71
  72 section "The word size story."
  73         {Haskell98 specifies that signed integers (type {\tt Int})
  74          must contain at least 30 bits. GHC always implements {\tt
  75          Int} using the primitive type {\tt Int\#}, whose size equals
  76          the {\tt MachDeps.h} constant {\tt WORD\_SIZE\_IN\_BITS}.
  77          This is normally set based on the {\tt config.h} parameter
  78          {\tt SIZEOF\_HSWORD}, i.e., 32 bits on 32-bit machines, 64
  79          bits on 64-bit machines.  However, it can also be explicitly
  80          set to a smaller number, e.g., 31 bits, to allow the
  81          possibility of using tag bits. Currently GHC itself has only
  82          32-bit and 64-bit variants, but 30 or 31-bit code can be
  83          exported as an external core file for use in other back ends.
  84
  85          GHC also implements a primitive unsigned integer type {\tt
  86          Word\#} which always has the same number of bits as {\tt
  87          Int\#}.
  88
  89          In addition, GHC supports families of explicit-sized integers
  90          and words at 8, 16, 32, and 64 bits, with the usual
  91          arithmetic operations, comparisons, and a range of
  92          conversions.  The 8-bit and 16-bit sizes are always
  93          represented as {\tt Int\#} and {\tt Word\#}, and the
  94          operations implemented in terms of the the primops on these
  95          types, with suitable range restrictions on the results (using
  96          the {\tt narrow$n$Int\#} and {\tt narrow$n$Word\#} families
  97          of primops.  The 32-bit sizes are represented using {\tt
  98          Int\#} and {\tt Word\#} when {\tt WORD\_SIZE\_IN\_BITS}
  99          $\geq$ 32; otherwise, these are represented using distinct
 100          primitive types {\tt Int32\#} and {\tt Word32\#}. These (when
 101          needed) have a complete set of corresponding operations;
 102          however, nearly all of these are implemented as external C
 103          functions rather than as primops.  Exactly the same story
 104          applies to the 64-bit sizes.  All of these details are hidden
 105          under the {\tt PrelInt} and {\tt PrelWord} modules, which use
 106          {\tt \#if}-defs to invoke the appropriate types and
 107          operators.
 108
 109          Word size also matters for the families of primops for
 110          indexing/reading/writing fixed-size quantities at offsets
 111          from an array base, address, or foreign pointer.  Here, a
 112          slightly different approach is taken.  The names of these
 113          primops are fixed, but their {\it types} vary according to
 114          the value of {\tt WORD\_SIZE\_IN\_BITS}. For example, if word
 115          size is at least 32 bits then an operator like
 116          \texttt{indexInt32Array\#} has type {\tt ByteArray\# -> Int\#
 117          -> Int\#}; otherwise it has type {\tt ByteArray\# -> Int\# ->
 118          Int32\#}.  This approach confines the necessary {\tt
 119          \#if}-defs to this file; no conditional compilation is needed
 120          in the files that expose these primops.
 121
 122          Finally, there are strongly deprecated primops for coercing
 123          between {\tt Addr\#}, the primitive type of machine
 124          addresses, and {\tt Int\#}.  These are pretty bogus anyway,
 125          but will work on existing 32-bit and 64-bit GHC targets; they
 126          are completely bogus when tag bits are used in {\tt Int\#},
 127          so are not available in this case.  }
 128
 129 -- Define synonyms for indexing ops.
 130
 131 #if WORD_SIZE_IN_BITS < 32
 132 #define INT32 Int32#
 133 #define WORD32 Word32#
 134 #else
 135 #define INT32 Int#
 136 #define WORD32 Word#
 137 #endif
 138
 139 #if WORD_SIZE_IN_BITS < 64
 140 #define INT64 Int64#
 141 #define WORD64 Word64#
 142 #else
 143 #define INT64 Int#
 144 #define WORD64 Word#
 145 #endif
 146
 147 ------------------------------------------------------------------------
 148 section "Char#"
 149         {Operations on 31-bit characters.}
 150 ------------------------------------------------------------------------
 151
 152 primtype Char#
 153
 154 primop   CharGtOp  "gtChar#"   Compare   Char# -> Char# -> Bool
 155 primop   CharGeOp  "geChar#"   Compare   Char# -> Char# -> Bool
 156
 157 primop   CharEqOp  "eqChar#"   Compare
 158    Char# -> Char# -> Bool
 159    with commutable = True
 160
 161 primop   CharNeOp  "neChar#"   Compare
 162    Char# -> Char# -> Bool
 163    with commutable = True
 164
 165 primop   CharLtOp  "ltChar#"   Compare   Char# -> Char# -> Bool
 166 primop   CharLeOp  "leChar#"   Compare   Char# -> Char# -> Bool
 167
 168 primop   OrdOp   "ord#"  GenPrimOp   Char# -> Int#
 169
 170 ------------------------------------------------------------------------
 171 section "Int#"
 172         {Operations on native-size integers (30+ bits).}
 173 ------------------------------------------------------------------------
 174
 175 primtype Int#
 176
 177 primop   IntAddOp    "+#"    Dyadic
 178    Int# -> Int# -> Int#
 179    with commutable = True
 180
 181 primop   IntSubOp    "-#"    Dyadic   Int# -> Int# -> Int#
 182
 183 primop   IntMulOp    "*#"
 184    Dyadic   Int# -> Int# -> Int#
 185    {Low word of signed integer multiply.}
 186    with commutable = True
 187
 188 primop   IntMulMayOfloOp  "mulIntMayOflo#"
 189    Dyadic   Int# -> Int# -> Int#
 190    {Return non-zero if there is any possibility that the upper word of a
 191     signed integer multiply might contain useful information.  Return
 192     zero only if you are completely sure that no overflow can occur.
 193     On a 32-bit platform, the recommmended implementation is to do a
 194     32 x 32 -> 64 signed multiply, and subtract result[63:32] from
 195     (result[31] >>signed 31).  If this is zero, meaning that the
 196     upper word is merely a sign extension of the lower one, no
 197     overflow can occur.
 198
 199     On a 64-bit platform it is not always possible to
 200     acquire the top 64 bits of the result.  Therefore, a recommended
 201     implementation is to take the absolute value of both operands, and
 202     return 0 iff bits[63:31] of them are zero, since that means that their
 203     magnitudes fit within 31 bits, so the magnitude of the product must fit
 204     into 62 bits.
 205
 206     If in doubt, return non-zero, but do make an effort to create the
 207     correct answer for small args, since otherwise the performance of
 208     \texttt{(*) :: Integer -> Integer -> Integer} will be poor.
 209    }
 210    with commutable = True
 211
 212 primop   IntQuotOp    "quotInt#"    Dyadic
 213    Int# -> Int# -> Int#
 214    {Rounds towards zero.}
 215    with can_fail = True
 216
 217 primop   IntRemOp    "remInt#"    Dyadic
 218    Int# -> Int# -> Int#
 219    {Satisfies \texttt{(quotInt\# x y) *\# y +\# (remInt\# x y) == x}.}
 220    with can_fail = True
 221
 222 primop   IntNegOp    "negateInt#"    Monadic   Int# -> Int#
 223 primop   IntAddCOp   "addIntC#"    GenPrimOp   Int# -> Int# -> (# Int#, Int# #)
 224          {Add with carry.  First member of result is (wrapped) sum;
 225           second member is 0 iff no overflow occured.}
 226 primop   IntSubCOp   "subIntC#"    GenPrimOp   Int# -> Int# -> (# Int#, Int# #)
 227          {Subtract with carry.  First member of result is (wrapped) difference;
 228           second member is 0 iff no overflow occured.}
 229
 230 primop   IntGtOp  ">#"   Compare   Int# -> Int# -> Bool
 231 primop   IntGeOp  ">=#"   Compare   Int# -> Int# -> Bool
 232
 233 primop   IntEqOp  "==#"   Compare
 234    Int# -> Int# -> Bool
 235    with commutable = True
 236
 237 primop   IntNeOp  "/=#"   Compare
 238    Int# -> Int# -> Bool
 239    with commutable = True
 240
 241 primop   IntLtOp  "<#"   Compare   Int# -> Int# -> Bool
 242 primop   IntLeOp  "<=#"   Compare   Int# -> Int# -> Bool
 243
 244 primop   ChrOp   "chr#"   GenPrimOp   Int# -> Char#
 245
 246 primop   Int2WordOp "int2Word#" GenPrimOp Int# -> Word#
 247 primop   Int2FloatOp   "int2Float#"      GenPrimOp  Int# -> Float#
 248 primop   Int2DoubleOp   "int2Double#"          GenPrimOp  Int# -> Double#
 249
 250 primop   ISllOp   "uncheckedIShiftL#" GenPrimOp  Int# -> Int# -> Int#
 251          {Shift left.  Result undefined if shift amount is not
 252           in the range 0 to word size - 1 inclusive.}
 253 primop   ISraOp   "uncheckedIShiftRA#" GenPrimOp Int# -> Int# -> Int#
 254          {Shift right arithmetic.  Result undefined if shift amount is not
 255           in the range 0 to word size - 1 inclusive.}
 256 primop   ISrlOp   "uncheckedIShiftRL#" GenPrimOp Int# -> Int# -> Int#
 257          {Shift right logical.  Result undefined if shift amount is not
 258           in the range 0 to word size - 1 inclusive.}
 259
 260 ------------------------------------------------------------------------
 261 section "Word#"
 262         {Operations on native-sized unsigned words (30+ bits).}
 263 ------------------------------------------------------------------------
 264
 265 primtype Word#
 266
 267 primop   WordAddOp   "plusWord#"   Dyadic   Word# -> Word# -> Word#
 268    with commutable = True
 269
 270 primop   WordSubOp   "minusWord#"   Dyadic   Word# -> Word# -> Word#
 271
 272 primop   WordMulOp   "timesWord#"   Dyadic   Word# -> Word# -> Word#
 273    with commutable = True
 274
 275 primop   WordQuotOp   "quotWord#"   Dyadic   Word# -> Word# -> Word#
 276    with can_fail = True
 277
 278 primop   WordRemOp   "remWord#"   Dyadic   Word# -> Word# -> Word#
 279    with can_fail = True
 280
 281 primop   AndOp   "and#"   Dyadic   Word# -> Word# -> Word#
 282    with commutable = True
 283
 284 primop   OrOp   "or#"   Dyadic   Word# -> Word# -> Word#
 285    with commutable = True
 286
 287 primop   XorOp   "xor#"   Dyadic   Word# -> Word# -> Word#
 288    with commutable = True
 289
 290 primop   NotOp   "not#"   Monadic   Word# -> Word#
 291
 292 primop   SllOp   "uncheckedShiftL#"   GenPrimOp   Word# -> Int# -> Word#
 293          {Shift left logical.   Result undefined if shift amount is not
 294           in the range 0 to word size - 1 inclusive.}
 295 primop   SrlOp   "uncheckedShiftRL#"   GenPrimOp   Word# -> Int# -> Word#
 296          {Shift right logical.   Result undefined if shift  amount is not
 297           in the range 0 to word size - 1 inclusive.}
 298
 299 primop   Word2IntOp   "word2Int#"   GenPrimOp   Word# -> Int#
 300
 301 primop   WordGtOp   "gtWord#"   Compare   Word# -> Word# -> Bool
 302 primop   WordGeOp   "geWord#"   Compare   Word# -> Word# -> Bool
 303 primop   WordEqOp   "eqWord#"   Compare   Word# -> Word# -> Bool
 304 primop   WordNeOp   "neWord#"   Compare   Word# -> Word# -> Bool
 305 primop   WordLtOp   "ltWord#"   Compare   Word# -> Word# -> Bool
 306 primop   WordLeOp   "leWord#"   Compare   Word# -> Word# -> Bool
 307
 308 ------------------------------------------------------------------------
 309 section "Narrowings"
 310         {Explicit narrowing of native-sized ints or words.}
 311 ------------------------------------------------------------------------
 312
 313 primop   Narrow8IntOp      "narrow8Int#"      Monadic   Int# -> Int#
 314 primop   Narrow16IntOp     "narrow16Int#"     Monadic   Int# -> Int#
 315 primop   Narrow32IntOp     "narrow32Int#"     Monadic   Int# -> Int#
 316 primop   Narrow8WordOp     "narrow8Word#"     Monadic   Word# -> Word#
 317 primop   Narrow16WordOp    "narrow16Word#"    Monadic   Word# -> Word#
 318 primop   Narrow32WordOp    "narrow32Word#"    Monadic   Word# -> Word#
 319
 320
 321 #if WORD_SIZE_IN_BITS < 32
 322 ------------------------------------------------------------------------
 323 section "Int32#"
 324         {Operations on 32-bit integers ({\tt Int32\#}).  This type is only used
 325          if plain {\tt Int\#} has less than 32 bits.  In any case, the operations
 326          are not primops; they are implemented (if needed) as ccalls instead.}
 327 ------------------------------------------------------------------------
 328
 329 primtype Int32#
 330
 331 ------------------------------------------------------------------------
 332 section "Word32#"
 333         {Operations on 32-bit unsigned words. This type is only used
 334          if plain {\tt Word\#} has less than 32 bits. In any case, the operations
 335          are not primops; they are implemented (if needed) as ccalls instead.}
 336 ------------------------------------------------------------------------
 337
 338 primtype Word32#
 339
 340 #endif
 341
 342
 343 #if WORD_SIZE_IN_BITS < 64
 344 ------------------------------------------------------------------------
 345 section "Int64#"
 346         {Operations on 64-bit unsigned words. This type is only used
 347          if plain {\tt Int\#} has less than 64 bits. In any case, the operations
 348          are not primops; they are implemented (if needed) as ccalls instead.}
 349 ------------------------------------------------------------------------
 350
 351 primtype Int64#
 352
 353 ------------------------------------------------------------------------
 354 section "Word64#"
 355         {Operations on 64-bit unsigned words. This type is only used
 356          if plain {\tt Word\#} has less than 64 bits. In any case, the operations
 357          are not primops; they are implemented (if needed) as ccalls instead.}
 358 ------------------------------------------------------------------------
 359
 360 primtype Word64#
 361
 362 #endif
 363
 364 ------------------------------------------------------------------------
 365 section "Double#"
 366         {Operations on double-precision (64 bit) floating-point numbers.}
 367 ------------------------------------------------------------------------
 368
 369 primtype Double#
 370
 371 primop   DoubleGtOp ">##"   Compare   Double# -> Double# -> Bool
 372 primop   DoubleGeOp ">=##"   Compare   Double# -> Double# -> Bool
 373
 374 primop DoubleEqOp "==##"   Compare
 375    Double# -> Double# -> Bool
 376    with commutable = True
 377
 378 primop DoubleNeOp "/=##"   Compare
 379    Double# -> Double# -> Bool
 380    with commutable = True
 381
 382 primop   DoubleLtOp "<##"   Compare   Double# -> Double# -> Bool
 383 primop   DoubleLeOp "<=##"   Compare   Double# -> Double# -> Bool
 384
 385 primop   DoubleAddOp   "+##"   Dyadic
 386    Double# -> Double# -> Double#
 387    with commutable = True
 388
 389 primop   DoubleSubOp   "-##"   Dyadic   Double# -> Double# -> Double#
 390
 391 primop   DoubleMulOp   "*##"   Dyadic
 392    Double# -> Double# -> Double#
 393    with commutable = True
 394
 395 primop   DoubleDivOp   "/##"   Dyadic
 396    Double# -> Double# -> Double#
 397    with can_fail = True
 398
 399 primop   DoubleNegOp   "negateDouble#"  Monadic   Double# -> Double#
 400
 401 primop   Double2IntOp   "double2Int#"          GenPrimOp  Double# -> Int#
 402    {Truncates a {\tt Double#} value to the nearest {\tt Int#}.
 403     Results are undefined if the truncation if truncation yields
 404     a value outside the range of {\tt Int#}.}
 405
 406 primop   Double2FloatOp   "double2Float#" GenPrimOp Double# -> Float#
 407
 408 primop   DoubleExpOp   "expDouble#"      Monadic
 409    Double# -> Double#
 410    with needs_wrapper = True
 411
 412 primop   DoubleLogOp   "logDouble#"      Monadic
 413    Double# -> Double#
 414    with
 415    needs_wrapper = True
 416    can_fail = True
 417
 418 primop   DoubleSqrtOp   "sqrtDouble#"      Monadic
 419    Double# -> Double#
 420    with needs_wrapper = True
 421
 422 primop   DoubleSinOp   "sinDouble#"      Monadic
 423    Double# -> Double#
 424    with needs_wrapper = True
 425
 426 primop   DoubleCosOp   "cosDouble#"      Monadic
 427    Double# -> Double#
 428    with needs_wrapper = True
 429
 430 primop   DoubleTanOp   "tanDouble#"      Monadic
 431    Double# -> Double#
 432    with needs_wrapper = True
 433
 434 primop   DoubleAsinOp   "asinDouble#"      Monadic
 435    Double# -> Double#
 436    with
 437    needs_wrapper = True
 438    can_fail = True
 439
 440 primop   DoubleAcosOp   "acosDouble#"      Monadic
 441    Double# -> Double#
 442    with
 443    needs_wrapper = True
 444    can_fail = True
 445
 446 primop   DoubleAtanOp   "atanDouble#"      Monadic
 447    Double# -> Double#
 448    with
 449    needs_wrapper = True
 450
 451 primop   DoubleSinhOp   "sinhDouble#"      Monadic
 452    Double# -> Double#
 453    with needs_wrapper = True
 454
 455 primop   DoubleCoshOp   "coshDouble#"      Monadic
 456    Double# -> Double#
 457    with needs_wrapper = True
 458
 459 primop   DoubleTanhOp   "tanhDouble#"      Monadic
 460    Double# -> Double#
 461    with needs_wrapper = True
 462
 463 primop   DoublePowerOp   "**##" Dyadic
 464    Double# -> Double# -> Double#
 465    {Exponentiation.}
 466    with needs_wrapper = True
 467
 468 primop   DoubleDecode_2IntOp   "decodeDouble_2Int#" GenPrimOp
 469    Double# -> (# Int#, Word#, Word#, Int# #)
 470    {Convert to integer.
 471     First component of the result is -1 or 1, indicating the sign of the
 472     mantissa. The next two are the high and low 32 bits of the mantissa
 473     respectively, and the last is the exponent.}
 474    with out_of_line = True
 475
 476 ------------------------------------------------------------------------
 477 section "Float#"
 478         {Operations on single-precision (32-bit) floating-point numbers.}
 479 ------------------------------------------------------------------------
 480
 481 primtype Float#
 482
 483 primop   FloatGtOp  "gtFloat#"   Compare   Float# -> Float# -> Bool
 484 primop   FloatGeOp  "geFloat#"   Compare   Float# -> Float# -> Bool
 485
 486 primop   FloatEqOp  "eqFloat#"   Compare
 487    Float# -> Float# -> Bool
 488    with commutable = True
 489
 490 primop   FloatNeOp  "neFloat#"   Compare
 491    Float# -> Float# -> Bool
 492    with commutable = True
 493
 494 primop   FloatLtOp  "ltFloat#"   Compare   Float# -> Float# -> Bool
 495 primop   FloatLeOp  "leFloat#"   Compare   Float# -> Float# -> Bool
 496
 497 primop   FloatAddOp   "plusFloat#"      Dyadic
 498    Float# -> Float# -> Float#
 499    with commutable = True
 500
 501 primop   FloatSubOp   "minusFloat#"      Dyadic      Float# -> Float# -> Float#
 502
 503 primop   FloatMulOp   "timesFloat#"      Dyadic
 504    Float# -> Float# -> Float#
 505    with commutable = True
 506
 507 primop   FloatDivOp   "divideFloat#"      Dyadic
 508    Float# -> Float# -> Float#
 509    with can_fail = True
 510
 511 primop   FloatNegOp   "negateFloat#"      Monadic    Float# -> Float#
 512
 513 primop   Float2IntOp   "float2Int#"      GenPrimOp  Float# -> Int#
 514    {Truncates a {\tt Float#} value to the nearest {\tt Int#}.
 515     Results are undefined if the truncation if truncation yields
 516     a value outside the range of {\tt Int#}.}
 517
 518 primop   FloatExpOp   "expFloat#"      Monadic
 519    Float# -> Float#
 520    with needs_wrapper = True
 521
 522 primop   FloatLogOp   "logFloat#"      Monadic
 523    Float# -> Float#
 524    with needs_wrapper = True
 525         can_fail = True
 526
 527 primop   FloatSqrtOp   "sqrtFloat#"      Monadic
 528    Float# -> Float#
 529    with needs_wrapper = True
 530
 531 primop   FloatSinOp   "sinFloat#"      Monadic
 532    Float# -> Float#
 533    with needs_wrapper = True
 534
 535 primop   FloatCosOp   "cosFloat#"      Monadic
 536    Float# -> Float#
 537    with needs_wrapper = True
 538
 539 primop   FloatTanOp   "tanFloat#"      Monadic
 540    Float# -> Float#
 541    with needs_wrapper = True
 542
 543 primop   FloatAsinOp   "asinFloat#"      Monadic
 544    Float# -> Float#
 545    with needs_wrapper = True
 546         can_fail = True
 547
 548 primop   FloatAcosOp   "acosFloat#"      Monadic
 549    Float# -> Float#
 550    with needs_wrapper = True
 551         can_fail = True
 552
 553 primop   FloatAtanOp   "atanFloat#"      Monadic
 554    Float# -> Float#
 555    with needs_wrapper = True
 556
 557 primop   FloatSinhOp   "sinhFloat#"      Monadic
 558    Float# -> Float#
 559    with needs_wrapper = True
 560
 561 primop   FloatCoshOp   "coshFloat#"      Monadic
 562    Float# -> Float#
 563    with needs_wrapper = True
 564
 565 primop   FloatTanhOp   "tanhFloat#"      Monadic
 566    Float# -> Float#
 567    with needs_wrapper = True
 568
 569 primop   FloatPowerOp   "powerFloat#"      Dyadic
 570    Float# -> Float# -> Float#
 571    with needs_wrapper = True
 572
 573 primop   Float2DoubleOp   "float2Double#" GenPrimOp  Float# -> Double#
 574
 575 primop   FloatDecode_IntOp   "decodeFloat_Int#" GenPrimOp
 576    Float# -> (# Int#, Int# #)
 577    {Convert to integers.
 578     First {\tt Int\#} in result is the mantissa; second is the exponent.}
 579    with out_of_line = True
 580
 581 ------------------------------------------------------------------------
 582 section "Arrays"
 583         {Operations on {\tt Array\#}.}
 584 ------------------------------------------------------------------------
 585
 586 primtype Array# a
 587
 588 primtype MutableArray# s a
 589
 590 primop  NewArrayOp "newArray#" GenPrimOp
 591    Int# -> a -> State# s -> (# State# s, MutableArray# s a #)
 592    {Create a new mutable array of specified size (in bytes),
 593     in the specified state thread,
 594     with each element containing the specified initial value.}
 595    with
 596    out_of_line = True
 597    has_side_effects = True
 598
 599 primop  SameMutableArrayOp "sameMutableArray#" GenPrimOp
 600    MutableArray# s a -> MutableArray# s a -> Bool
 601
 602 primop  ReadArrayOp "readArray#" GenPrimOp
 603    MutableArray# s a -> Int# -> State# s -> (# State# s, a #)
 604    {Read from specified index of mutable array. Result is not yet evaluated.}
 605    with
 606    has_side_effects = True
 607
 608 primop  WriteArrayOp "writeArray#" GenPrimOp
 609    MutableArray# s a -> Int# -> a -> State# s -> State# s
 610    {Write to specified index of mutable array.}
 611    with
 612    has_side_effects = True
 613
 614 primop  IndexArrayOp "indexArray#" GenPrimOp
 615    Array# a -> Int# -> (# a #)
 616    {Read from specified index of immutable array. Result is packaged into
 617     an unboxed singleton; the result itself is not yet evaluated.}
 618
 619 primop  UnsafeFreezeArrayOp "unsafeFreezeArray#" GenPrimOp
 620    MutableArray# s a -> State# s -> (# State# s, Array# a #)
 621    {Make a mutable array immutable, without copying.}
 622    with
 623    has_side_effects = True
 624
 625 primop  UnsafeThawArrayOp  "unsafeThawArray#" GenPrimOp
 626    Array# a -> State# s -> (# State# s, MutableArray# s a #)
 627    {Make an immutable array mutable, without copying.}
 628    with
 629    out_of_line = True
 630    has_side_effects = True
 631
 632 ------------------------------------------------------------------------
 633 section "Byte Arrays"
 634         {Operations on {\tt ByteArray\#}. A {\tt ByteArray\#} is a just a region of
 635          raw memory in the garbage-collected heap, which is not
 636          scanned for pointers. It carries its own size (in bytes,
 637          rounded up to the nearest multiple of a word). There are
 638          three sets of operations for accessing byte array contents:
 639          index for reading from immutable byte arrays, and read/write
 640          for mutable byte arrays.  Each set contains operations for a
 641          range of useful primitive data types.  Each operation takes
 642          an offset measured in terms of the size fo the primitive type
 643          being read or written.}
 644
 645 ------------------------------------------------------------------------
 646
 647 primtype ByteArray#
 648
 649 primtype MutableByteArray# s
 650
 651 primop  NewByteArrayOp_Char "newByteArray#" GenPrimOp
 652    Int# -> State# s -> (# State# s, MutableByteArray# s #)
 653    {Create a new mutable byte array of specified size (in bytes), in
 654     the specified state thread.}
 655    with out_of_line = True
 656         has_side_effects = True
 657
 658 primop  NewPinnedByteArrayOp_Char "newPinnedByteArray#" GenPrimOp
 659    Int# -> State# s -> (# State# s, MutableByteArray# s #)
 660    {Create a mutable byte array that the GC guarantees not to move.}
 661    with out_of_line = True
 662         has_side_effects = True
 663
 664 primop  NewAlignedPinnedByteArrayOp_Char "newAlignedPinnedByteArray#" GenPrimOp
 665    Int# -> Int# -> State# s -> (# State# s, MutableByteArray# s #)
 666    {Create a mutable byte array, aligned by the specified amount, that the GC guarantees not to move.}
 667    with out_of_line = True
 668         has_side_effects = True
 669
 670 primop  ByteArrayContents_Char "byteArrayContents#" GenPrimOp
 671    ByteArray# -> Addr#
 672    {Intended for use with pinned arrays; otherwise very unsafe!}
 673
 674 primop  SameMutableByteArrayOp "sameMutableByteArray#" GenPrimOp
 675    MutableByteArray# s -> MutableByteArray# s -> Bool
 676
 677 primop  UnsafeFreezeByteArrayOp "unsafeFreezeByteArray#" GenPrimOp
 678    MutableByteArray# s -> State# s -> (# State# s, ByteArray# #)
 679    {Make a mutable byte array immutable, without copying.}
 680    with
 681    has_side_effects = True
 682
 683 primop  SizeofByteArrayOp "sizeofByteArray#" GenPrimOp
 684    ByteArray# -> Int#
 685    {Return the size of the array in bytes, rounded up to the nearest multiple
 686    of a word.}
 687
 688 primop  SizeofMutableByteArrayOp "sizeofMutableByteArray#" GenPrimOp
 689    MutableByteArray# s -> Int#
 690    {Return the size of the array in bytes, rounded up to the nearest multiple
 691    of a word.}
 692
 693 primop IndexByteArrayOp_Char "indexCharArray#" GenPrimOp
 694    ByteArray# -> Int# -> Char#
 695    {Read 8-bit character; offset in bytes.}
 696
 697 primop IndexByteArrayOp_WideChar "indexWideCharArray#" GenPrimOp
 698    ByteArray# -> Int# -> Char#
 699    {Read 31-bit character; offset in 4-byte words.}
 700
 701 primop IndexByteArrayOp_Int "indexIntArray#" GenPrimOp
 702    ByteArray# -> Int# -> Int#
 703
 704 primop IndexByteArrayOp_Word "indexWordArray#" GenPrimOp
 705    ByteArray# -> Int# -> Word#
 706
 707 primop IndexByteArrayOp_Addr "indexAddrArray#" GenPrimOp
 708    ByteArray# -> Int# -> Addr#
 709
 710 primop IndexByteArrayOp_Float "indexFloatArray#" GenPrimOp
 711    ByteArray# -> Int# -> Float#
 712
 713 primop IndexByteArrayOp_Double "indexDoubleArray#" GenPrimOp
 714    ByteArray# -> Int# -> Double#
 715
 716 primop IndexByteArrayOp_StablePtr "indexStablePtrArray#" GenPrimOp
 717    ByteArray# -> Int# -> StablePtr# a
 718
 719 primop IndexByteArrayOp_Int8 "indexInt8Array#" GenPrimOp
 720    ByteArray# -> Int# -> Int#
 721
 722 primop IndexByteArrayOp_Int16 "indexInt16Array#" GenPrimOp
 723    ByteArray# -> Int# -> Int#
 724
 725 primop IndexByteArrayOp_Int32 "indexInt32Array#" GenPrimOp
 726    ByteArray# -> Int# -> INT32
 727
 728 primop IndexByteArrayOp_Int64 "indexInt64Array#" GenPrimOp
 729    ByteArray# -> Int# -> INT64
 730
 731 primop IndexByteArrayOp_Word8 "indexWord8Array#" GenPrimOp
 732    ByteArray# -> Int# -> Word#
 733
 734 primop IndexByteArrayOp_Word16 "indexWord16Array#" GenPrimOp
 735    ByteArray# -> Int# -> Word#
 736
 737 primop IndexByteArrayOp_Word32 "indexWord32Array#" GenPrimOp
 738    ByteArray# -> Int# -> WORD32
 739
 740 primop IndexByteArrayOp_Word64 "indexWord64Array#" GenPrimOp
 741    ByteArray# -> Int# -> WORD64
 742
 743 primop  ReadByteArrayOp_Char "readCharArray#" GenPrimOp
 744    MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
 745    {Read 8-bit character; offset in bytes.}
 746    with has_side_effects = True
 747
 748 primop  ReadByteArrayOp_WideChar "readWideCharArray#" GenPrimOp
 749    MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
 750    {Read 31-bit character; offset in 4-byte words.}
 751    with has_side_effects = True
 752
 753 primop  ReadByteArrayOp_Int "readIntArray#" GenPrimOp
 754    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
 755    with has_side_effects = True
 756
 757 primop  ReadByteArrayOp_Word "readWordArray#" GenPrimOp
 758    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
 759    with has_side_effects = True
 760
 761 primop  ReadByteArrayOp_Addr "readAddrArray#" GenPrimOp
 762    MutableByteArray# s -> Int# -> State# s -> (# State# s, Addr# #)
 763    with has_side_effects = True
 764
 765 primop  ReadByteArrayOp_Float "readFloatArray#" GenPrimOp
 766    MutableByteArray# s -> Int# -> State# s -> (# State# s, Float# #)
 767    with has_side_effects = True
 768
 769 primop  ReadByteArrayOp_Double "readDoubleArray#" GenPrimOp
 770    MutableByteArray# s -> Int# -> State# s -> (# State# s, Double# #)
 771    with has_side_effects = True
 772
 773 primop  ReadByteArrayOp_StablePtr "readStablePtrArray#" GenPrimOp
 774    MutableByteArray# s -> Int# -> State# s -> (# State# s, StablePtr# a #)
 775    with has_side_effects = True
 776
 777 primop  ReadByteArrayOp_Int8 "readInt8Array#" GenPrimOp
 778    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
 779    with has_side_effects = True
 780
 781 primop  ReadByteArrayOp_Int16 "readInt16Array#" GenPrimOp
 782    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
 783    with has_side_effects = True
 784
 785 primop  ReadByteArrayOp_Int32 "readInt32Array#" GenPrimOp
 786    MutableByteArray# s -> Int# -> State# s -> (# State# s, INT32 #)
 787    with has_side_effects = True
 788
 789 primop  ReadByteArrayOp_Int64 "readInt64Array#" GenPrimOp
 790    MutableByteArray# s -> Int# -> State# s -> (# State# s, INT64 #)
 791    with has_side_effects = True
 792
 793 primop  ReadByteArrayOp_Word8 "readWord8Array#" GenPrimOp
 794    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
 795    with has_side_effects = True
 796
 797 primop  ReadByteArrayOp_Word16 "readWord16Array#" GenPrimOp
 798    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
 799    with has_side_effects = True
 800
 801 primop  ReadByteArrayOp_Word32 "readWord32Array#" GenPrimOp
 802    MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD32 #)
 803    with has_side_effects = True
 804
 805 primop  ReadByteArrayOp_Word64 "readWord64Array#" GenPrimOp
 806    MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD64 #)
 807    with has_side_effects = True
 808
 809 primop  WriteByteArrayOp_Char "writeCharArray#" GenPrimOp
 810    MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
 811    {Write 8-bit character; offset in bytes.}
 812    with has_side_effects = True
 813
 814 primop  WriteByteArrayOp_WideChar "writeWideCharArray#" GenPrimOp
 815    MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
 816    {Write 31-bit character; offset in 4-byte words.}
 817    with has_side_effects = True
 818
 819 primop  WriteByteArrayOp_Int "writeIntArray#" GenPrimOp
 820    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
 821    with has_side_effects = True
 822
 823 primop  WriteByteArrayOp_Word "writeWordArray#" GenPrimOp
 824    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
 825    with has_side_effects = True
 826
 827 primop  WriteByteArrayOp_Addr "writeAddrArray#" GenPrimOp
 828    MutableByteArray# s -> Int# -> Addr# -> State# s -> State# s
 829    with has_side_effects = True
 830
 831 primop  WriteByteArrayOp_Float "writeFloatArray#" GenPrimOp
 832    MutableByteArray# s -> Int# -> Float# -> State# s -> State# s
 833    with has_side_effects = True
 834
 835 primop  WriteByteArrayOp_Double "writeDoubleArray#" GenPrimOp
 836    MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
 837    with has_side_effects = True
 838
 839 primop  WriteByteArrayOp_StablePtr "writeStablePtrArray#" GenPrimOp
 840    MutableByteArray# s -> Int# -> StablePtr# a -> State# s -> State# s
 841    with has_side_effects = True
 842
 843 primop  WriteByteArrayOp_Int8 "writeInt8Array#" GenPrimOp
 844    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
 845    with has_side_effects = True
 846
 847 primop  WriteByteArrayOp_Int16 "writeInt16Array#" GenPrimOp
 848    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
 849    with has_side_effects = True
 850
 851 primop  WriteByteArrayOp_Int32 "writeInt32Array#" GenPrimOp
 852    MutableByteArray# s -> Int# -> INT32 -> State# s -> State# s
 853    with has_side_effects = True
 854
 855 primop  WriteByteArrayOp_Int64 "writeInt64Array#" GenPrimOp
 856    MutableByteArray# s -> Int# -> INT64 -> State# s -> State# s
 857    with has_side_effects = True
 858
 859 primop  WriteByteArrayOp_Word8 "writeWord8Array#" GenPrimOp
 860    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
 861    with has_side_effects = True
 862
 863 primop  WriteByteArrayOp_Word16 "writeWord16Array#" GenPrimOp
 864    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
 865    with has_side_effects = True
 866
 867 primop  WriteByteArrayOp_Word32 "writeWord32Array#" GenPrimOp
 868    MutableByteArray# s -> Int# -> WORD32 -> State# s -> State# s
 869    with has_side_effects = True
 870
 871 primop  WriteByteArrayOp_Word64 "writeWord64Array#" GenPrimOp
 872    MutableByteArray# s -> Int# -> WORD64 -> State# s -> State# s
 873    with has_side_effects = True
 874
 875 ------------------------------------------------------------------------
 876 section "Addr#"
 877 ------------------------------------------------------------------------
 878
 879 primtype Addr#
 880         { An arbitrary machine address assumed to point outside
 881          the garbage-collected heap. }
 882
 883 pseudoop "nullAddr#" Addr#
 884         { The null address. }
 885
 886 primop   AddrAddOp "plusAddr#" GenPrimOp Addr# -> Int# -> Addr#
 887 primop   AddrSubOp "minusAddr#" GenPrimOp Addr# -> Addr# -> Int#
 888          {Result is meaningless if two {\tt Addr\#}s are so far apart that their
 889          difference doesn't fit in an {\tt Int\#}.}
 890 primop   AddrRemOp "remAddr#" GenPrimOp Addr# -> Int# -> Int#
 891          {Return the remainder when the {\tt Addr\#} arg, treated like an {\tt Int\#},
 892           is divided by the {\tt Int\#} arg.}
 893 #if (WORD_SIZE_IN_BITS == 32 || WORD_SIZE_IN_BITS == 64)
 894 primop   Addr2IntOp  "addr2Int#"     GenPrimOp   Addr# -> Int#
 895         {Coerce directly from address to int. Strongly deprecated.}
 896 primop   Int2AddrOp   "int2Addr#"    GenPrimOp  Int# -> Addr#
 897         {Coerce directly from int to address. Strongly deprecated.}
 898 #endif
 899
 900 primop   AddrGtOp  "gtAddr#"   Compare   Addr# -> Addr# -> Bool
 901 primop   AddrGeOp  "geAddr#"   Compare   Addr# -> Addr# -> Bool
 902 primop   AddrEqOp  "eqAddr#"   Compare   Addr# -> Addr# -> Bool
 903 primop   AddrNeOp  "neAddr#"   Compare   Addr# -> Addr# -> Bool
 904 primop   AddrLtOp  "ltAddr#"   Compare   Addr# -> Addr# -> Bool
 905 primop   AddrLeOp  "leAddr#"   Compare   Addr# -> Addr# -> Bool
 906
 907 primop IndexOffAddrOp_Char "indexCharOffAddr#" GenPrimOp
 908    Addr# -> Int# -> Char#
 909    {Reads 8-bit character; offset in bytes.}
 910
 911 primop IndexOffAddrOp_WideChar "indexWideCharOffAddr#" GenPrimOp
 912    Addr# -> Int# -> Char#
 913    {Reads 31-bit character; offset in 4-byte words.}
 914
 915 primop IndexOffAddrOp_Int "indexIntOffAddr#" GenPrimOp
 916    Addr# -> Int# -> Int#
 917
 918 primop IndexOffAddrOp_Word "indexWordOffAddr#" GenPrimOp
 919    Addr# -> Int# -> Word#
 920
 921 primop IndexOffAddrOp_Addr "indexAddrOffAddr#" GenPrimOp
 922    Addr# -> Int# -> Addr#
 923
 924 primop IndexOffAddrOp_Float "indexFloatOffAddr#" GenPrimOp
 925    Addr# -> Int# -> Float#
 926
 927 primop IndexOffAddrOp_Double "indexDoubleOffAddr#" GenPrimOp
 928    Addr# -> Int# -> Double#
 929
 930 primop IndexOffAddrOp_StablePtr "indexStablePtrOffAddr#" GenPrimOp
 931    Addr# -> Int# -> StablePtr# a
 932
 933 primop IndexOffAddrOp_Int8 "indexInt8OffAddr#" GenPrimOp
 934    Addr# -> Int# -> Int#
 935
 936 primop IndexOffAddrOp_Int16 "indexInt16OffAddr#" GenPrimOp
 937    Addr# -> Int# -> Int#
 938
 939 primop IndexOffAddrOp_Int32 "indexInt32OffAddr#" GenPrimOp
 940    Addr# -> Int# -> INT32
 941
 942 primop IndexOffAddrOp_Int64 "indexInt64OffAddr#" GenPrimOp
 943    Addr# -> Int# -> INT64
 944
 945 primop IndexOffAddrOp_Word8 "indexWord8OffAddr#" GenPrimOp
 946    Addr# -> Int# -> Word#
 947
 948 primop IndexOffAddrOp_Word16 "indexWord16OffAddr#" GenPrimOp
 949    Addr# -> Int# -> Word#
 950
 951 primop IndexOffAddrOp_Word32 "indexWord32OffAddr#" GenPrimOp
 952    Addr# -> Int# -> WORD32
 953
 954 primop IndexOffAddrOp_Word64 "indexWord64OffAddr#" GenPrimOp
 955    Addr# -> Int# -> WORD64
 956
 957 primop ReadOffAddrOp_Char "readCharOffAddr#" GenPrimOp
 958    Addr# -> Int# -> State# s -> (# State# s, Char# #)
 959    {Reads 8-bit character; offset in bytes.}
 960    with has_side_effects = True
 961
 962 primop ReadOffAddrOp_WideChar "readWideCharOffAddr#" GenPrimOp
 963    Addr# -> Int# -> State# s -> (# State# s, Char# #)
 964    {Reads 31-bit character; offset in 4-byte words.}
 965    with has_side_effects = True
 966
 967 primop ReadOffAddrOp_Int "readIntOffAddr#" GenPrimOp
 968    Addr# -> Int# -> State# s -> (# State# s, Int# #)
 969    with has_side_effects = True
 970
 971 primop ReadOffAddrOp_Word "readWordOffAddr#" GenPrimOp
 972    Addr# -> Int# -> State# s -> (# State# s, Word# #)
 973    with has_side_effects = True
 974
 975 primop ReadOffAddrOp_Addr "readAddrOffAddr#" GenPrimOp
 976    Addr# -> Int# -> State# s -> (# State# s, Addr# #)
 977    with has_side_effects = True
 978
 979 primop ReadOffAddrOp_Float "readFloatOffAddr#" GenPrimOp
 980    Addr# -> Int# -> State# s -> (# State# s, Float# #)
 981    with has_side_effects = True
 982
 983 primop ReadOffAddrOp_Double "readDoubleOffAddr#" GenPrimOp
 984    Addr# -> Int# -> State# s -> (# State# s, Double# #)
 985    with has_side_effects = True
 986
 987 primop ReadOffAddrOp_StablePtr "readStablePtrOffAddr#" GenPrimOp
 988    Addr# -> Int# -> State# s -> (# State# s, StablePtr# a #)
 989    with has_side_effects = True
 990
 991 primop ReadOffAddrOp_Int8 "readInt8OffAddr#" GenPrimOp
 992    Addr# -> Int# -> State# s -> (# State# s, Int# #)
 993    with has_side_effects = True
 994
 995 primop ReadOffAddrOp_Int16 "readInt16OffAddr#" GenPrimOp
 996    Addr# -> Int# -> State# s -> (# State# s, Int# #)
 997    with has_side_effects = True
 998
 999 primop ReadOffAddrOp_Int32 "readInt32OffAddr#" GenPrimOp
1000    Addr# -> Int# -> State# s -> (# State# s, INT32 #)
1001    with has_side_effects = True
1002
1003 primop ReadOffAddrOp_Int64 "readInt64OffAddr#" GenPrimOp
1004    Addr# -> Int# -> State# s -> (# State# s, INT64 #)
1005    with has_side_effects = True
1006
1007 primop ReadOffAddrOp_Word8 "readWord8OffAddr#" GenPrimOp
1008    Addr# -> Int# -> State# s -> (# State# s, Word# #)
1009    with has_side_effects = True
1010
1011 primop ReadOffAddrOp_Word16 "readWord16OffAddr#" GenPrimOp
1012    Addr# -> Int# -> State# s -> (# State# s, Word# #)
1013    with has_side_effects = True
1014
1015 primop ReadOffAddrOp_Word32 "readWord32OffAddr#" GenPrimOp
1016    Addr# -> Int# -> State# s -> (# State# s, WORD32 #)
1017    with has_side_effects = True
1018
1019 primop ReadOffAddrOp_Word64 "readWord64OffAddr#" GenPrimOp
1020    Addr# -> Int# -> State# s -> (# State# s, WORD64 #)
1021    with has_side_effects = True
1022
1023
1024 primop  WriteOffAddrOp_Char "writeCharOffAddr#" GenPrimOp
1025    Addr# -> Int# -> Char# -> State# s -> State# s
1026    with has_side_effects = True
1027
1028 primop  WriteOffAddrOp_WideChar "writeWideCharOffAddr#" GenPrimOp
1029    Addr# -> Int# -> Char# -> State# s -> State# s
1030    with has_side_effects = True
1031
1032 primop  WriteOffAddrOp_Int "writeIntOffAddr#" GenPrimOp
1033    Addr# -> Int# -> Int# -> State# s -> State# s
1034    with has_side_effects = True
1035
1036 primop  WriteOffAddrOp_Word "writeWordOffAddr#" GenPrimOp
1037    Addr# -> Int# -> Word# -> State# s -> State# s
1038    with has_side_effects = True
1039
1040 primop  WriteOffAddrOp_Addr "writeAddrOffAddr#" GenPrimOp
1041    Addr# -> Int# -> Addr# -> State# s -> State# s
1042    with has_side_effects = True
1043
1044 primop  WriteOffAddrOp_Float "writeFloatOffAddr#" GenPrimOp
1045    Addr# -> Int# -> Float# -> State# s -> State# s
1046    with has_side_effects = True
1047
1048 primop  WriteOffAddrOp_Double "writeDoubleOffAddr#" GenPrimOp
1049    Addr# -> Int# -> Double# -> State# s -> State# s
1050    with has_side_effects = True
1051
1052 primop  WriteOffAddrOp_StablePtr "writeStablePtrOffAddr#" GenPrimOp
1053    Addr# -> Int# -> StablePtr# a -> State# s -> State# s
1054    with has_side_effects = True
1055
1056 primop  WriteOffAddrOp_Int8 "writeInt8OffAddr#" GenPrimOp
1057    Addr# -> Int# -> Int# -> State# s -> State# s
1058    with has_side_effects = True
1059
1060 primop  WriteOffAddrOp_Int16 "writeInt16OffAddr#" GenPrimOp
1061    Addr# -> Int# -> Int# -> State# s -> State# s
1062    with has_side_effects = True
1063
1064 primop  WriteOffAddrOp_Int32 "writeInt32OffAddr#" GenPrimOp
1065    Addr# -> Int# -> INT32 -> State# s -> State# s
1066    with has_side_effects = True
1067
1068 primop  WriteOffAddrOp_Int64 "writeInt64OffAddr#" GenPrimOp
1069    Addr# -> Int# -> INT64 -> State# s -> State# s
1070    with has_side_effects = True
1071
1072 primop  WriteOffAddrOp_Word8 "writeWord8OffAddr#" GenPrimOp
1073    Addr# -> Int# -> Word# -> State# s -> State# s
1074    with has_side_effects = True
1075
1076 primop  WriteOffAddrOp_Word16 "writeWord16OffAddr#" GenPrimOp
1077    Addr# -> Int# -> Word# -> State# s -> State# s
1078    with has_side_effects = True
1079
1080 primop  WriteOffAddrOp_Word32 "writeWord32OffAddr#" GenPrimOp
1081    Addr# -> Int# -> WORD32 -> State# s -> State# s
1082    with has_side_effects = True
1083
1084 primop  WriteOffAddrOp_Word64 "writeWord64OffAddr#" GenPrimOp
1085    Addr# -> Int# -> WORD64 -> State# s -> State# s
1086    with has_side_effects = True
1087
1088 ------------------------------------------------------------------------
1089 section "Mutable variables"
1090         {Operations on MutVar\#s.}
1091 ------------------------------------------------------------------------
1092
1093 primtype MutVar# s a
1094         {A {\tt MutVar\#} behaves like a single-element mutable array.}
1095
1096 primop  NewMutVarOp "newMutVar#" GenPrimOp
1097    a -> State# s -> (# State# s, MutVar# s a #)
1098    {Create {\tt MutVar\#} with specified initial value in specified state thread.}
1099    with
1100    out_of_line = True
1101    has_side_effects = True
1102
1103 primop  ReadMutVarOp "readMutVar#" GenPrimOp
1104    MutVar# s a -> State# s -> (# State# s, a #)
1105    {Read contents of {\tt MutVar\#}. Result is not yet evaluated.}
1106    with
1107    has_side_effects = True
1108
1109 primop  WriteMutVarOp "writeMutVar#"  GenPrimOp
1110    MutVar# s a -> a -> State# s -> State# s
1111    {Write contents of {\tt MutVar\#}.}
1112    with
1113    has_side_effects = True
1114
1115 primop  SameMutVarOp "sameMutVar#" GenPrimOp
1116    MutVar# s a -> MutVar# s a -> Bool
1117
1118 -- not really the right type, but we don't know about pairs here.  The
1119 -- correct type is
1120 --
1121 --   MutVar# s a -> (a -> (a,b)) -> State# s -> (# State# s, b #)
1122 --
1123 primop  AtomicModifyMutVarOp "atomicModifyMutVar#" GenPrimOp
1124    MutVar# s a -> (a -> b) -> State# s -> (# State# s, c #)
1125    with
1126    out_of_line = True
1127    has_side_effects = True
1128
1129 ------------------------------------------------------------------------
1130 section "Exceptions"
1131 ------------------------------------------------------------------------
1132
1133 primop  CatchOp "catch#" GenPrimOp
1134           (State# RealWorld -> (# State# RealWorld, a #) )
1135        -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1136        -> State# RealWorld
1137        -> (# State# RealWorld, a #)
1138    with
1139         -- Catch is actually strict in its first argument
1140         -- but we don't want to tell the strictness
1141         -- analyser about that!
1142         -- might use caught action multiply
1143    out_of_line = True
1144    has_side_effects = True
1145
1146 primop  RaiseOp "raise#" GenPrimOp
1147    a -> b
1148    with
1149    strictness  = { \ _arity -> mkStrictSig (mkTopDmdType [lazyDmd] BotRes) }
1150       -- NB: result is bottom
1151    out_of_line = True
1152
1153 -- raiseIO# needs to be a primop, because exceptions in the IO monad
1154 -- must be *precise* - we don't want the strictness analyser turning
1155 -- one kind of bottom into another, as it is allowed to do in pure code.
1156
1157 primop  RaiseIOOp "raiseIO#" GenPrimOp
1158    a -> State# RealWorld -> (# State# RealWorld, b #)
1159    with
1160    out_of_line = True
1161    has_side_effects = True
1162
1163 primop  BlockAsyncExceptionsOp "blockAsyncExceptions#" GenPrimOp
1164         (State# RealWorld -> (# State# RealWorld, a #))
1165      -> (State# RealWorld -> (# State# RealWorld, a #))
1166    with
1167    out_of_line = True
1168    has_side_effects = True
1169
1170 primop  UnblockAsyncExceptionsOp "unblockAsyncExceptions#" GenPrimOp
1171         (State# RealWorld -> (# State# RealWorld, a #))
1172      -> (State# RealWorld -> (# State# RealWorld, a #))
1173    with
1174    out_of_line = True
1175    has_side_effects = True
1176
1177 primop  AsyncExceptionsBlockedOp "asyncExceptionsBlocked#" GenPrimOp
1178         State# RealWorld -> (# State# RealWorld, Int# #)
1179    with
1180    out_of_line = True
1181    has_side_effects = True
1182
1183 ------------------------------------------------------------------------
1184 section "STM-accessible Mutable Variables"
1185 ------------------------------------------------------------------------
1186
1187 primtype TVar# s a
1188
1189 primop  AtomicallyOp "atomically#" GenPrimOp
1190       (State# RealWorld -> (# State# RealWorld, a #) )
1191    -> State# RealWorld -> (# State# RealWorld, a #)
1192    with
1193    out_of_line = True
1194    has_side_effects = True
1195
1196 primop  RetryOp "retry#" GenPrimOp
1197    State# RealWorld -> (# State# RealWorld, a #)
1198    with
1199    out_of_line = True
1200    has_side_effects = True
1201
1202 primop  CatchRetryOp "catchRetry#" GenPrimOp
1203       (State# RealWorld -> (# State# RealWorld, a #) )
1204    -> (State# RealWorld -> (# State# RealWorld, a #) )
1205    -> (State# RealWorld -> (# State# RealWorld, a #) )
1206    with
1207    out_of_line = True
1208    has_side_effects = True
1209
1210 primop  CatchSTMOp "catchSTM#" GenPrimOp
1211       (State# RealWorld -> (# State# RealWorld, a #) )
1212    -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1213    -> (State# RealWorld -> (# State# RealWorld, a #) )
1214    with
1215    out_of_line = True
1216    has_side_effects = True
1217
1218 primop  Check "check#" GenPrimOp
1219       (State# RealWorld -> (# State# RealWorld, a #) )
1220    -> (State# RealWorld -> (# State# RealWorld, () #) )
1221    with
1222    out_of_line = True
1223    has_side_effects = True
1224
1225 primop  NewTVarOp "newTVar#" GenPrimOp
1226        a
1227     -> State# s -> (# State# s, TVar# s a #)
1228    {Create a new {\tt TVar\#} holding a specified initial value.}
1229    with
1230    out_of_line  = True
1231    has_side_effects = True
1232
1233 primop  ReadTVarOp "readTVar#" GenPrimOp
1234        TVar# s a
1235     -> State# s -> (# State# s, a #)
1236    {Read contents of {\tt TVar\#}.  Result is not yet evaluated.}
1237    with
1238    out_of_line  = True
1239    has_side_effects = True
1240
1241 primop ReadTVarIOOp "readTVarIO#" GenPrimOp
1242        TVar# s a
1243     -> State# s -> (# State# s, a #)
1244    {Read contents of {\tt TVar\#} outside an STM transaction}
1245    with
1246    out_of_line  = True
1247    has_side_effects = True
1248
1249 primop  WriteTVarOp "writeTVar#" GenPrimOp
1250        TVar# s a
1251     -> a
1252     -> State# s -> State# s
1253    {Write contents of {\tt TVar\#}.}
1254    with
1255    out_of_line      = True
1256    has_side_effects = True
1257
1258 primop  SameTVarOp "sameTVar#" GenPrimOp
1259    TVar# s a -> TVar# s a -> Bool
1260
1261
1262 ------------------------------------------------------------------------
1263 section "Synchronized Mutable Variables"
1264         {Operations on {\tt MVar\#}s. }
1265 ------------------------------------------------------------------------
1266
1267 primtype MVar# s a
1268         { A shared mutable variable ({\it not} the same as a {\tt MutVar\#}!).
1269         (Note: in a non-concurrent implementation, {\tt (MVar\# a)} can be
1270         represented by {\tt (MutVar\# (Maybe a))}.) }
1271
1272 primop  NewMVarOp "newMVar#"  GenPrimOp
1273    State# s -> (# State# s, MVar# s a #)
1274    {Create new {\tt MVar\#}; initially empty.}
1275    with
1276    out_of_line = True
1277    has_side_effects = True
1278
1279 primop  TakeMVarOp "takeMVar#" GenPrimOp
1280    MVar# s a -> State# s -> (# State# s, a #)
1281    {If {\tt MVar\#} is empty, block until it becomes full.
1282    Then remove and return its contents, and set it empty.}
1283    with
1284    out_of_line      = True
1285    has_side_effects = True
1286
1287 primop  TryTakeMVarOp "tryTakeMVar#" GenPrimOp
1288    MVar# s a -> State# s -> (# State# s, Int#, a #)
1289    {If {\tt MVar\#} is empty, immediately return with integer 0 and value undefined.
1290    Otherwise, return with integer 1 and contents of {\tt MVar\#}, and set {\tt MVar\#} empty.}
1291    with
1292    out_of_line      = True
1293    has_side_effects = True
1294
1295 primop  PutMVarOp "putMVar#" GenPrimOp
1296    MVar# s a -> a -> State# s -> State# s
1297    {If {\tt MVar\#} is full, block until it becomes empty.
1298    Then store value arg as its new contents.}
1299    with
1300    out_of_line      = True
1301    has_side_effects = True
1302
1303 primop  TryPutMVarOp "tryPutMVar#" GenPrimOp
1304    MVar# s a -> a -> State# s -> (# State# s, Int# #)
1305    {If {\tt MVar\#} is full, immediately return with integer 0.
1306     Otherwise, store value arg as {\tt MVar\#}'s new contents, and return with integer 1.}
1307    with
1308    out_of_line      = True
1309    has_side_effects = True
1310
1311 primop  SameMVarOp "sameMVar#" GenPrimOp
1312    MVar# s a -> MVar# s a -> Bool
1313
1314 primop  IsEmptyMVarOp "isEmptyMVar#" GenPrimOp
1315    MVar# s a -> State# s -> (# State# s, Int# #)
1316    {Return 1 if {\tt MVar\#} is empty; 0 otherwise.}
1317    with
1318    out_of_line = True
1319    has_side_effects = True
1320
1321 ------------------------------------------------------------------------
1322 section "Delay/wait operations"
1323 ------------------------------------------------------------------------
1324
1325 primop  DelayOp "delay#" GenPrimOp
1326    Int# -> State# s -> State# s
1327    {Sleep specified number of microseconds.}
1328    with
1329    needs_wrapper    = True
1330    has_side_effects = True
1331    out_of_line      = True
1332
1333 primop  WaitReadOp "waitRead#" GenPrimOp
1334    Int# -> State# s -> State# s
1335    {Block until input is available on specified file descriptor.}
1336    with
1337    needs_wrapper    = True
1338    has_side_effects = True
1339    out_of_line      = True
1340
1341 primop  WaitWriteOp "waitWrite#" GenPrimOp
1342    Int# -> State# s -> State# s
1343    {Block until output is possible on specified file descriptor.}
1344    with
1345    needs_wrapper    = True
1346    has_side_effects = True
1347    out_of_line      = True
1348
1349 #ifdef mingw32_TARGET_OS
1350 primop  AsyncReadOp "asyncRead#" GenPrimOp
1351    Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1352    {Asynchronously read bytes from specified file descriptor.}
1353    with
1354    needs_wrapper    = True
1355    has_side_effects = True
1356    out_of_line      = True
1357
1358 primop  AsyncWriteOp "asyncWrite#" GenPrimOp
1359    Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1360    {Asynchronously write bytes from specified file descriptor.}
1361    with
1362    needs_wrapper    = True
1363    has_side_effects = True
1364    out_of_line      = True
1365
1366 primop  AsyncDoProcOp "asyncDoProc#" GenPrimOp
1367    Addr# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1368    {Asynchronously perform procedure (first arg), passing it 2nd arg.}
1369    with
1370    needs_wrapper    = True
1371    has_side_effects = True
1372    out_of_line      = True
1373
1374 #endif
1375
1376 ------------------------------------------------------------------------
1377 section "Concurrency primitives"
1378 ------------------------------------------------------------------------
1379
1380 primtype State# s
1381         { {\tt State\#} is the primitive, unlifted type of states.  It has
1382         one type parameter, thus {\tt State\# RealWorld}, or {\tt State\# s},
1383         where s is a type variable. The only purpose of the type parameter
1384         is to keep different state threads separate.  It is represented by
1385         nothing at all. }
1386
1387 primtype RealWorld
1388         { {\tt RealWorld} is deeply magical.  It is {\it primitive}, but it is not
1389         {\it unlifted} (hence {\tt ptrArg}).  We never manipulate values of type
1390         {\tt RealWorld}; it's only used in the type system, to parameterise {\tt State\#}. }
1391
1392 primtype ThreadId#
1393         {(In a non-concurrent implementation, this can be a singleton
1394         type, whose (unique) value is returned by {\tt myThreadId\#}.  The
1395         other operations can be omitted.)}
1396
1397 primop  ForkOp "fork#" GenPrimOp
1398    a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
1399    with
1400    has_side_effects = True
1401    out_of_line      = True
1402
1403 primop  ForkOnOp "forkOn#" GenPrimOp
1404    Int# -> a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
1405    with
1406    has_side_effects = True
1407    out_of_line      = True
1408
1409 primop  KillThreadOp "killThread#"  GenPrimOp
1410    ThreadId# -> a -> State# RealWorld -> State# RealWorld
1411    with
1412    has_side_effects = True
1413    out_of_line      = True
1414
1415 primop  YieldOp "yield#" GenPrimOp
1416    State# RealWorld -> State# RealWorld
1417    with
1418    has_side_effects = True
1419    out_of_line      = True
1420
1421 primop  MyThreadIdOp "myThreadId#" GenPrimOp
1422    State# RealWorld -> (# State# RealWorld, ThreadId# #)
1423    with
1424    out_of_line = True
1425    has_side_effects = True
1426
1427 primop LabelThreadOp "labelThread#" GenPrimOp
1428    ThreadId# -> Addr# -> State# RealWorld -> State# RealWorld
1429    with
1430    has_side_effects = True
1431    out_of_line      = True
1432
1433 primop  IsCurrentThreadBoundOp "isCurrentThreadBound#" GenPrimOp
1434    State# RealWorld -> (# State# RealWorld, Int# #)
1435    with
1436    out_of_line = True
1437    has_side_effects = True
1438
1439 primop  NoDuplicateOp "noDuplicate#" GenPrimOp
1440    State# RealWorld -> State# RealWorld
1441    with
1442    out_of_line = True
1443    has_side_effects = True
1444
1445 primop  ThreadStatusOp "threadStatus#" GenPrimOp
1446    ThreadId# -> State# RealWorld -> (# State# RealWorld, Int# #)
1447    with
1448    out_of_line = True
1449    has_side_effects = True
1450
1451 ------------------------------------------------------------------------
1452 section "Weak pointers"
1453 ------------------------------------------------------------------------
1454
1455 primtype Weak# b
1456
1457 -- note that tyvar "o" denotes openAlphaTyVar
1458
1459 primop  MkWeakOp "mkWeak#" GenPrimOp
1460    o -> b -> c -> State# RealWorld -> (# State# RealWorld, Weak# b #)
1461    with
1462    has_side_effects = True
1463    out_of_line      = True
1464
1465 primop  MkWeakForeignEnvOp "mkWeakForeignEnv#" GenPrimOp
1466    o -> b -> Addr# -> Addr# -> Int# -> Addr# -> State# RealWorld -> (# State# RealWorld, Weak# b #)
1467    with
1468    has_side_effects = True
1469    out_of_line      = True
1470
1471 primop  DeRefWeakOp "deRefWeak#" GenPrimOp
1472    Weak# a -> State# RealWorld -> (# State# RealWorld, Int#, a #)
1473    with
1474    has_side_effects = True
1475    out_of_line      = True
1476
1477 primop  FinalizeWeakOp "finalizeWeak#" GenPrimOp
1478    Weak# a -> State# RealWorld -> (# State# RealWorld, Int#,
1479               (State# RealWorld -> (# State# RealWorld, () #)) #)
1480    with
1481    has_side_effects = True
1482    out_of_line      = True
1483
1484 primop TouchOp "touch#" GenPrimOp
1485    o -> State# RealWorld -> State# RealWorld
1486    with
1487    has_side_effects = True
1488
1489 ------------------------------------------------------------------------
1490 section "Stable pointers and names"
1491 ------------------------------------------------------------------------
1492
1493 primtype StablePtr# a
1494
1495 primtype StableName# a
1496
1497 primop  MakeStablePtrOp "makeStablePtr#" GenPrimOp
1498    a -> State# RealWorld -> (# State# RealWorld, StablePtr# a #)
1499    with
1500    has_side_effects = True
1501    out_of_line      = True
1502
1503 primop  DeRefStablePtrOp "deRefStablePtr#" GenPrimOp
1504    StablePtr# a -> State# RealWorld -> (# State# RealWorld, a #)
1505    with
1506    needs_wrapper    = True
1507    has_side_effects = True
1508    out_of_line      = True
1509
1510 primop  EqStablePtrOp "eqStablePtr#" GenPrimOp
1511    StablePtr# a -> StablePtr# a -> Int#
1512    with
1513    has_side_effects = True
1514
1515 primop  MakeStableNameOp "makeStableName#" GenPrimOp
1516    a -> State# RealWorld -> (# State# RealWorld, StableName# a #)
1517    with
1518    needs_wrapper    = True
1519    has_side_effects = True
1520    out_of_line      = True
1521
1522 primop  EqStableNameOp "eqStableName#" GenPrimOp
1523    StableName# a -> StableName# a -> Int#
1524
1525 primop  StableNameToIntOp "stableNameToInt#" GenPrimOp
1526    StableName# a -> Int#
1527
1528 ------------------------------------------------------------------------
1529 section "Unsafe pointer equality"
1530 --  (#1 Bad Guy: Alistair Reid :)
1531 ------------------------------------------------------------------------
1532
1533 primop  ReallyUnsafePtrEqualityOp "reallyUnsafePtrEquality#" GenPrimOp
1534    a -> a -> Int#
1535
1536 ------------------------------------------------------------------------
1537 section "Parallelism"
1538 ------------------------------------------------------------------------
1539
1540 primop  ParOp "par#" GenPrimOp
1541    a -> Int#
1542    with
1543       -- Note that Par is lazy to avoid that the sparked thing
1544       -- gets evaluted strictly, which it should *not* be
1545    has_side_effects = True
1546
1547 primop GetSparkOp "getSpark#" GenPrimOp
1548    State# s -> (# State# s, Int#, a #)
1549    with
1550    has_side_effects = True
1551    out_of_line = True
1552
1553 -- HWL: The first 4 Int# in all par... annotations denote:
1554 --   name, granularity info, size of result, degree of parallelism
1555 --      Same  structure as _seq_ i.e. returns Int#
1556 -- KSW: v, the second arg in parAt# and parAtForNow#, is used only to determine
1557 --   `the processor containing the expression v'; it is not evaluated
1558
1559 primop  ParGlobalOp  "parGlobal#"  GenPrimOp
1560    a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1561    with
1562    has_side_effects = True
1563
1564 primop  ParLocalOp  "parLocal#"  GenPrimOp
1565    a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1566    with
1567    has_side_effects = True
1568
1569 primop  ParAtOp  "parAt#"  GenPrimOp
1570    b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
1571    with
1572    has_side_effects = True
1573
1574 primop  ParAtAbsOp  "parAtAbs#"  GenPrimOp
1575    a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1576    with
1577    has_side_effects = True
1578
1579 primop  ParAtRelOp  "parAtRel#" GenPrimOp
1580    a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1581    with
1582    has_side_effects = True
1583
1584 primop  ParAtForNowOp  "parAtForNow#" GenPrimOp
1585    b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
1586    with
1587    has_side_effects = True
1588
1589 -- copyable# and noFollow# are yet to be implemented (for GpH)
1590 --
1591 --primop  CopyableOp  "copyable#" GenPrimOp
1592 --   a -> Int#
1593 --   with
1594 --   has_side_effects = True
1595 --
1596 --primop  NoFollowOp "noFollow#" GenPrimOp
1597 --   a -> Int#
1598 --   with
1599 --   has_side_effects = True
1600
1601
1602 ------------------------------------------------------------------------
1603 section "Tag to enum stuff"
1604         {Convert back and forth between values of enumerated types
1605         and small integers.}
1606 ------------------------------------------------------------------------
1607
1608 primop  DataToTagOp "dataToTag#" GenPrimOp
1609    a -> Int#
1610    with
1611    strictness  = { \ _arity -> mkStrictSig (mkTopDmdType [seqDmd] TopRes) }
1612         -- dataToTag# must have an evaluated argument
1613
1614 primop  TagToEnumOp "tagToEnum#" GenPrimOp
1615    Int# -> a
1616
1617 ------------------------------------------------------------------------
1618 section "Bytecode operations"
1619         {Support for the bytecode interpreter and linker.}
1620 ------------------------------------------------------------------------
1621
1622 primtype BCO#
1623    {Primitive bytecode type.}
1624
1625 primop   AddrToHValueOp "addrToHValue#" GenPrimOp
1626    Addr# -> (# a #)
1627    {Convert an {\tt Addr\#} to a followable type.}
1628
1629 primop   MkApUpd0_Op "mkApUpd0#" GenPrimOp
1630    BCO# -> (# a #)
1631    with
1632    out_of_line = True
1633
1634 primop  NewBCOOp "newBCO#" GenPrimOp
1635    ByteArray# -> ByteArray# -> Array# a -> Int# -> ByteArray# -> State# s -> (# State# s, BCO# #)
1636    with
1637    has_side_effects = True
1638    out_of_line      = True
1639
1640 primop  UnpackClosureOp "unpackClosure#" GenPrimOp
1641    a -> (# Addr#, Array# b, ByteArray# #)
1642    with
1643    out_of_line = True
1644
1645 primop  GetApStackValOp "getApStackVal#" GenPrimOp
1646    a -> Int# -> (# Int#, b #)
1647    with
1648    out_of_line = True
1649
1650 ------------------------------------------------------------------------
1651 section "Misc"
1652         {These aren't nearly as wired in as Etc...}
1653 ------------------------------------------------------------------------
1654
1655 primop  TraceCcsOp "traceCcs#" GenPrimOp
1656    a -> b -> b
1657    with
1658    has_side_effects = True
1659    out_of_line = True
1660
1661 ------------------------------------------------------------------------
1662 section "Etc"
1663         {Miscellaneous built-ins}
1664 ------------------------------------------------------------------------
1665
1666 pseudoop   "seq"
1667    a -> b -> b
1668    { Evaluates its first argument to head normal form, and then returns its second
1669         argument as the result. }
1670
1671 pseudoop   "inline"
1672    a -> a
1673    { The call {\tt (inline f)} arranges that f is inlined, regardless of its size.
1674         More precisely, the call {\tt (inline f)} rewrites to the right-hand side of
1675         {\tt f}'s definition. This allows the programmer to control inlining from a
1676         particular call site rather than the definition site of the function (c.f.
1677         {\tt INLINE} pragmas in User's Guide, Section 7.10.3, "INLINE and NOINLINE
1678         pragmas").
1679
1680         This inlining occurs regardless of the argument to the call or the size of
1681         {\tt f}'s definition; it is unconditional. The main caveat is that {\tt f}'s
1682         definition must be visible to the compiler. That is, {\tt f} must be
1683         {\tt let}-bound in the current scope. If no inlining takes place, the
1684         {\tt inline} function expands to the identity function in Phase zero; so its
1685         use imposes no overhead.
1686
1687         If the function is defined in another module, GHC only exposes its inlining
1688         in the interface file if the function is sufficiently small that it might be
1689         inlined by the automatic mechanism. There is currently no way to tell GHC to
1690         expose arbitrarily-large functions in the interface file. (This shortcoming
1691         is something that could be fixed, with some kind of pragma.) }
1692
1693 pseudoop   "lazy"
1694    a -> a
1695    { The {\tt lazy} function restrains strictness analysis a little. The call
1696         {\tt (lazy e)} means the same as {\tt e}, but {\tt lazy} has a magical
1697         property so far as strictness analysis is concerned: it is lazy in its first
1698         argument, even though its semantics is strict. After strictness analysis has
1699         run, calls to {\tt lazy} are inlined to be the identity function.
1700
1701         This behaviour is occasionally useful when controlling evaluation order.
1702         Notably, {\tt lazy} is used in the library definition of {\tt Control.Parallel.par}:
1703
1704         {\tt par :: a -> b -> b}
1705
1706         {\tt par x y = case (par\# x) of \_ -> lazy y}
1707
1708         If {\tt lazy} were not lazy, {\tt par} would look strict in {\tt y} which
1709         would defeat the whole purpose of {\tt par}.
1710
1711         Like {\tt seq}, the argument of {\tt lazy} can have an unboxed type. }
1712
1713 primtype Any a
1714         { The type constructor {\tt Any} is type to which you can unsafely coerce any
1715         lifted type, and back.
1716
1717           * It is lifted, and hence represented by a pointer
1718
1719           * It does not claim to be a {\it data} type, and that's important for
1720             the code generator, because the code gen may {\it enter} a data value
1721             but never enters a function value.
1722
1723         It's also used to instantiate un-constrained type variables after type
1724         checking.  For example
1725
1726         {\tt length Any []}
1727
1728         Annoyingly, we sometimes need {\tt Any}s of other kinds, such as {\tt (* -> *)} etc.
1729         This is a bit like tuples.   We define a couple of useful ones here,
1730         and make others up on the fly.  If any of these others end up being exported
1731         into interface files, we'll get a crash; at least until we add interface-file
1732         syntax to support them. }
1733
1734 pseudoop   "unsafeCoerce#"
1735    a -> b
1736    { The function {\tt unsafeCoerce\#} allows you to side-step the typechecker entirely. That
1737         is, it allows you to coerce any type into any other type. If you use this function,
1738         you had better get it right, otherwise segmentation faults await. It is generally
1739         used when you want to write a program that you know is well-typed, but where Haskell's
1740         type system is not expressive enough to prove that it is well typed.
1741
1742         The following uses of {\tt unsafeCoerce\#} are supposed to work (i.e. not lead to
1743         spurious compile-time or run-time crashes):
1744
1745          * Casting any lifted type to {\tt Any}
1746
1747          * Casting {\tt Any} back to the real type
1748
1749          * Casting an unboxed type to another unboxed type of the same size
1750            (but not coercions between floating-point and integral types)
1751
1752          * Casting between two types that have the same runtime representation.  One case is when
1753            the two types differ only in "phantom" type parameters, for example
1754            {\tt Ptr Int} to {\tt Ptr Float}, or {\tt [Int]} to {\tt [Float]} when the list is
1755            known to be empty.  Also, a {\tt newtype} of a type {\tt T} has the same representation
1756            at runtime as {\tt T}.
1757
1758         Other uses of {\tt unsafeCoerce\#} are undefined.  In particular, you should not use
1759         {\tt unsafeCoerce\#} to cast a T to an algebraic data type D, unless T is also
1760         an algebraic data type.  For example, do not cast {\tt Int->Int} to {\tt Bool}, even if
1761         you later cast that {\tt Bool} back to {\tt Int->Int} before applying it.  The reasons
1762         have to do with GHC's internal representation details (for the congnoscenti, data values
1763         can be entered but function closures cannot).  If you want a safe type to cast things
1764         to, use {\tt Any}, which is not an algebraic data type.
1765
1766         }
1767
1768 -- NB. It is tempting to think that casting a value to a type that it doesn't have is safe
1769 -- as long as you don't "do anything" with the value in its cast form, such as seq on it.  This
1770 -- isn't the case: the compiler can insert seqs itself, and if these happen at the wrong type,
1771 -- Bad Things Might Happen.  See bug #1616: in this case we cast a function of type (a,b) -> (a,b)
1772 -- to () -> () and back again.  The strictness analyser saw that the function was strict, but
1773 -- the wrapper had type () -> (), and hence the wrapper de-constructed the (), the worker re-constructed
1774 -- a new (), with the result that the code ended up with "case () of (a,b) -> ...".
1775
1776 primop  TraceEventOp "traceEvent#" GenPrimOp
1777    Addr# -> State# s -> State# s
1778    { Emits an event via the RTS tracing framework.  The contents
1779      of the event is the zero-terminated byte string passed as the first
1780      argument.  The event will be emitted either to the .eventlog file,
1781      or to stderr, depending on the runtime RTS flags. }
1782    with
1783    has_side_effects = True
1784    out_of_line      = True
1785
1786 ------------------------------------------------------------------------
1787 ---                                                                  ---
1788 ------------------------------------------------------------------------
1789
1790 thats_all_folks
1791
1792
1793