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 scanned
 636          for pointers. It carries its own size (in bytes). There are
 637          three sets of operations for accessing byte array contents:
 638          index for reading from immutable byte arrays, and read/write
 639          for mutable byte arrays.  Each set contains operations for
 640          a range of useful primitive data types.  Each operation takes
 641          an offset measured in terms of the size fo the primitive type
 642          being read or written.}
 643
 644 ------------------------------------------------------------------------
 645
 646 primtype ByteArray#
 647
 648 primtype MutableByteArray# s
 649
 650 primop  NewByteArrayOp_Char "newByteArray#" GenPrimOp
 651    Int# -> State# s -> (# State# s, MutableByteArray# s #)
 652    {Create a new mutable byte array of specified size (in bytes), in
 653     the specified state thread.}
 654    with out_of_line = True
 655         has_side_effects = True
 656
 657 primop  NewPinnedByteArrayOp_Char "newPinnedByteArray#" GenPrimOp
 658    Int# -> State# s -> (# State# s, MutableByteArray# s #)
 659    {Create a mutable byte array that the GC guarantees not to move.}
 660    with out_of_line = True
 661         has_side_effects = True
 662
 663 primop  NewAlignedPinnedByteArrayOp_Char "newAlignedPinnedByteArray#" GenPrimOp
 664    Int# -> Int# -> State# s -> (# State# s, MutableByteArray# s #)
 665    {Create a mutable byte array, aligned by the specified amount, that the GC guarantees not to move.}
 666    with out_of_line = True
 667         has_side_effects = True
 668
 669 primop  ByteArrayContents_Char "byteArrayContents#" GenPrimOp
 670    ByteArray# -> Addr#
 671    {Intended for use with pinned arrays; otherwise very unsafe!}
 672
 673 primop  SameMutableByteArrayOp "sameMutableByteArray#" GenPrimOp
 674    MutableByteArray# s -> MutableByteArray# s -> Bool
 675
 676 primop  UnsafeFreezeByteArrayOp "unsafeFreezeByteArray#" GenPrimOp
 677    MutableByteArray# s -> State# s -> (# State# s, ByteArray# #)
 678    {Make a mutable byte array immutable, without copying.}
 679    with
 680    has_side_effects = True
 681
 682 primop  SizeofByteArrayOp "sizeofByteArray#" GenPrimOp
 683    ByteArray# -> Int#
 684
 685 primop  SizeofMutableByteArrayOp "sizeofMutableByteArray#" GenPrimOp
 686    MutableByteArray# s -> Int#
 687
 688
 689 primop IndexByteArrayOp_Char "indexCharArray#" GenPrimOp
 690    ByteArray# -> Int# -> Char#
 691    {Read 8-bit character; offset in bytes.}
 692
 693 primop IndexByteArrayOp_WideChar "indexWideCharArray#" GenPrimOp
 694    ByteArray# -> Int# -> Char#
 695    {Read 31-bit character; offset in 4-byte words.}
 696
 697 primop IndexByteArrayOp_Int "indexIntArray#" GenPrimOp
 698    ByteArray# -> Int# -> Int#
 699
 700 primop IndexByteArrayOp_Word "indexWordArray#" GenPrimOp
 701    ByteArray# -> Int# -> Word#
 702
 703 primop IndexByteArrayOp_Addr "indexAddrArray#" GenPrimOp
 704    ByteArray# -> Int# -> Addr#
 705
 706 primop IndexByteArrayOp_Float "indexFloatArray#" GenPrimOp
 707    ByteArray# -> Int# -> Float#
 708
 709 primop IndexByteArrayOp_Double "indexDoubleArray#" GenPrimOp
 710    ByteArray# -> Int# -> Double#
 711
 712 primop IndexByteArrayOp_StablePtr "indexStablePtrArray#" GenPrimOp
 713    ByteArray# -> Int# -> StablePtr# a
 714
 715 primop IndexByteArrayOp_Int8 "indexInt8Array#" GenPrimOp
 716    ByteArray# -> Int# -> Int#
 717
 718 primop IndexByteArrayOp_Int16 "indexInt16Array#" GenPrimOp
 719    ByteArray# -> Int# -> Int#
 720
 721 primop IndexByteArrayOp_Int32 "indexInt32Array#" GenPrimOp
 722    ByteArray# -> Int# -> INT32
 723
 724 primop IndexByteArrayOp_Int64 "indexInt64Array#" GenPrimOp
 725    ByteArray# -> Int# -> INT64
 726
 727 primop IndexByteArrayOp_Word8 "indexWord8Array#" GenPrimOp
 728    ByteArray# -> Int# -> Word#
 729
 730 primop IndexByteArrayOp_Word16 "indexWord16Array#" GenPrimOp
 731    ByteArray# -> Int# -> Word#
 732
 733 primop IndexByteArrayOp_Word32 "indexWord32Array#" GenPrimOp
 734    ByteArray# -> Int# -> WORD32
 735
 736 primop IndexByteArrayOp_Word64 "indexWord64Array#" GenPrimOp
 737    ByteArray# -> Int# -> WORD64
 738
 739 primop  ReadByteArrayOp_Char "readCharArray#" GenPrimOp
 740    MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
 741    {Read 8-bit character; offset in bytes.}
 742    with has_side_effects = True
 743
 744 primop  ReadByteArrayOp_WideChar "readWideCharArray#" GenPrimOp
 745    MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
 746    {Read 31-bit character; offset in 4-byte words.}
 747    with has_side_effects = True
 748
 749 primop  ReadByteArrayOp_Int "readIntArray#" GenPrimOp
 750    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
 751    with has_side_effects = True
 752
 753 primop  ReadByteArrayOp_Word "readWordArray#" GenPrimOp
 754    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
 755    with has_side_effects = True
 756
 757 primop  ReadByteArrayOp_Addr "readAddrArray#" GenPrimOp
 758    MutableByteArray# s -> Int# -> State# s -> (# State# s, Addr# #)
 759    with has_side_effects = True
 760
 761 primop  ReadByteArrayOp_Float "readFloatArray#" GenPrimOp
 762    MutableByteArray# s -> Int# -> State# s -> (# State# s, Float# #)
 763    with has_side_effects = True
 764
 765 primop  ReadByteArrayOp_Double "readDoubleArray#" GenPrimOp
 766    MutableByteArray# s -> Int# -> State# s -> (# State# s, Double# #)
 767    with has_side_effects = True
 768
 769 primop  ReadByteArrayOp_StablePtr "readStablePtrArray#" GenPrimOp
 770    MutableByteArray# s -> Int# -> State# s -> (# State# s, StablePtr# a #)
 771    with has_side_effects = True
 772
 773 primop  ReadByteArrayOp_Int8 "readInt8Array#" GenPrimOp
 774    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
 775    with has_side_effects = True
 776
 777 primop  ReadByteArrayOp_Int16 "readInt16Array#" GenPrimOp
 778    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
 779    with has_side_effects = True
 780
 781 primop  ReadByteArrayOp_Int32 "readInt32Array#" GenPrimOp
 782    MutableByteArray# s -> Int# -> State# s -> (# State# s, INT32 #)
 783    with has_side_effects = True
 784
 785 primop  ReadByteArrayOp_Int64 "readInt64Array#" GenPrimOp
 786    MutableByteArray# s -> Int# -> State# s -> (# State# s, INT64 #)
 787    with has_side_effects = True
 788
 789 primop  ReadByteArrayOp_Word8 "readWord8Array#" GenPrimOp
 790    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
 791    with has_side_effects = True
 792
 793 primop  ReadByteArrayOp_Word16 "readWord16Array#" GenPrimOp
 794    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
 795    with has_side_effects = True
 796
 797 primop  ReadByteArrayOp_Word32 "readWord32Array#" GenPrimOp
 798    MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD32 #)
 799    with has_side_effects = True
 800
 801 primop  ReadByteArrayOp_Word64 "readWord64Array#" GenPrimOp
 802    MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD64 #)
 803    with has_side_effects = True
 804
 805 primop  WriteByteArrayOp_Char "writeCharArray#" GenPrimOp
 806    MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
 807    {Write 8-bit character; offset in bytes.}
 808    with has_side_effects = True
 809
 810 primop  WriteByteArrayOp_WideChar "writeWideCharArray#" GenPrimOp
 811    MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
 812    {Write 31-bit character; offset in 4-byte words.}
 813    with has_side_effects = True
 814
 815 primop  WriteByteArrayOp_Int "writeIntArray#" GenPrimOp
 816    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
 817    with has_side_effects = True
 818
 819 primop  WriteByteArrayOp_Word "writeWordArray#" GenPrimOp
 820    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
 821    with has_side_effects = True
 822
 823 primop  WriteByteArrayOp_Addr "writeAddrArray#" GenPrimOp
 824    MutableByteArray# s -> Int# -> Addr# -> State# s -> State# s
 825    with has_side_effects = True
 826
 827 primop  WriteByteArrayOp_Float "writeFloatArray#" GenPrimOp
 828    MutableByteArray# s -> Int# -> Float# -> State# s -> State# s
 829    with has_side_effects = True
 830
 831 primop  WriteByteArrayOp_Double "writeDoubleArray#" GenPrimOp
 832    MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
 833    with has_side_effects = True
 834
 835 primop  WriteByteArrayOp_StablePtr "writeStablePtrArray#" GenPrimOp
 836    MutableByteArray# s -> Int# -> StablePtr# a -> State# s -> State# s
 837    with has_side_effects = True
 838
 839 primop  WriteByteArrayOp_Int8 "writeInt8Array#" GenPrimOp
 840    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
 841    with has_side_effects = True
 842
 843 primop  WriteByteArrayOp_Int16 "writeInt16Array#" GenPrimOp
 844    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
 845    with has_side_effects = True
 846
 847 primop  WriteByteArrayOp_Int32 "writeInt32Array#" GenPrimOp
 848    MutableByteArray# s -> Int# -> INT32 -> State# s -> State# s
 849    with has_side_effects = True
 850
 851 primop  WriteByteArrayOp_Int64 "writeInt64Array#" GenPrimOp
 852    MutableByteArray# s -> Int# -> INT64 -> State# s -> State# s
 853    with has_side_effects = True
 854
 855 primop  WriteByteArrayOp_Word8 "writeWord8Array#" GenPrimOp
 856    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
 857    with has_side_effects = True
 858
 859 primop  WriteByteArrayOp_Word16 "writeWord16Array#" GenPrimOp
 860    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
 861    with has_side_effects = True
 862
 863 primop  WriteByteArrayOp_Word32 "writeWord32Array#" GenPrimOp
 864    MutableByteArray# s -> Int# -> WORD32 -> State# s -> State# s
 865    with has_side_effects = True
 866
 867 primop  WriteByteArrayOp_Word64 "writeWord64Array#" GenPrimOp
 868    MutableByteArray# s -> Int# -> WORD64 -> State# s -> State# s
 869    with has_side_effects = True
 870
 871 ------------------------------------------------------------------------
 872 section "Addr#"
 873 ------------------------------------------------------------------------
 874
 875 primtype Addr#
 876         { An arbitrary machine address assumed to point outside
 877          the garbage-collected heap. }
 878
 879 pseudoop "nullAddr#" Addr#
 880         { The null address. }
 881
 882 primop   AddrAddOp "plusAddr#" GenPrimOp Addr# -> Int# -> Addr#
 883 primop   AddrSubOp "minusAddr#" GenPrimOp Addr# -> Addr# -> Int#
 884          {Result is meaningless if two {\tt Addr\#}s are so far apart that their
 885          difference doesn't fit in an {\tt Int\#}.}
 886 primop   AddrRemOp "remAddr#" GenPrimOp Addr# -> Int# -> Int#
 887          {Return the remainder when the {\tt Addr\#} arg, treated like an {\tt Int\#},
 888           is divided by the {\tt Int\#} arg.}
 889 #if (WORD_SIZE_IN_BITS == 32 || WORD_SIZE_IN_BITS == 64)
 890 primop   Addr2IntOp  "addr2Int#"     GenPrimOp   Addr# -> Int#
 891         {Coerce directly from address to int. Strongly deprecated.}
 892 primop   Int2AddrOp   "int2Addr#"    GenPrimOp  Int# -> Addr#
 893         {Coerce directly from int to address. Strongly deprecated.}
 894 #endif
 895
 896 primop   AddrGtOp  "gtAddr#"   Compare   Addr# -> Addr# -> Bool
 897 primop   AddrGeOp  "geAddr#"   Compare   Addr# -> Addr# -> Bool
 898 primop   AddrEqOp  "eqAddr#"   Compare   Addr# -> Addr# -> Bool
 899 primop   AddrNeOp  "neAddr#"   Compare   Addr# -> Addr# -> Bool
 900 primop   AddrLtOp  "ltAddr#"   Compare   Addr# -> Addr# -> Bool
 901 primop   AddrLeOp  "leAddr#"   Compare   Addr# -> Addr# -> Bool
 902
 903 primop IndexOffAddrOp_Char "indexCharOffAddr#" GenPrimOp
 904    Addr# -> Int# -> Char#
 905    {Reads 8-bit character; offset in bytes.}
 906
 907 primop IndexOffAddrOp_WideChar "indexWideCharOffAddr#" GenPrimOp
 908    Addr# -> Int# -> Char#
 909    {Reads 31-bit character; offset in 4-byte words.}
 910
 911 primop IndexOffAddrOp_Int "indexIntOffAddr#" GenPrimOp
 912    Addr# -> Int# -> Int#
 913
 914 primop IndexOffAddrOp_Word "indexWordOffAddr#" GenPrimOp
 915    Addr# -> Int# -> Word#
 916
 917 primop IndexOffAddrOp_Addr "indexAddrOffAddr#" GenPrimOp
 918    Addr# -> Int# -> Addr#
 919
 920 primop IndexOffAddrOp_Float "indexFloatOffAddr#" GenPrimOp
 921    Addr# -> Int# -> Float#
 922
 923 primop IndexOffAddrOp_Double "indexDoubleOffAddr#" GenPrimOp
 924    Addr# -> Int# -> Double#
 925
 926 primop IndexOffAddrOp_StablePtr "indexStablePtrOffAddr#" GenPrimOp
 927    Addr# -> Int# -> StablePtr# a
 928
 929 primop IndexOffAddrOp_Int8 "indexInt8OffAddr#" GenPrimOp
 930    Addr# -> Int# -> Int#
 931
 932 primop IndexOffAddrOp_Int16 "indexInt16OffAddr#" GenPrimOp
 933    Addr# -> Int# -> Int#
 934
 935 primop IndexOffAddrOp_Int32 "indexInt32OffAddr#" GenPrimOp
 936    Addr# -> Int# -> INT32
 937
 938 primop IndexOffAddrOp_Int64 "indexInt64OffAddr#" GenPrimOp
 939    Addr# -> Int# -> INT64
 940
 941 primop IndexOffAddrOp_Word8 "indexWord8OffAddr#" GenPrimOp
 942    Addr# -> Int# -> Word#
 943
 944 primop IndexOffAddrOp_Word16 "indexWord16OffAddr#" GenPrimOp
 945    Addr# -> Int# -> Word#
 946
 947 primop IndexOffAddrOp_Word32 "indexWord32OffAddr#" GenPrimOp
 948    Addr# -> Int# -> WORD32
 949
 950 primop IndexOffAddrOp_Word64 "indexWord64OffAddr#" GenPrimOp
 951    Addr# -> Int# -> WORD64
 952
 953 primop ReadOffAddrOp_Char "readCharOffAddr#" GenPrimOp
 954    Addr# -> Int# -> State# s -> (# State# s, Char# #)
 955    {Reads 8-bit character; offset in bytes.}
 956    with has_side_effects = True
 957
 958 primop ReadOffAddrOp_WideChar "readWideCharOffAddr#" GenPrimOp
 959    Addr# -> Int# -> State# s -> (# State# s, Char# #)
 960    {Reads 31-bit character; offset in 4-byte words.}
 961    with has_side_effects = True
 962
 963 primop ReadOffAddrOp_Int "readIntOffAddr#" GenPrimOp
 964    Addr# -> Int# -> State# s -> (# State# s, Int# #)
 965    with has_side_effects = True
 966
 967 primop ReadOffAddrOp_Word "readWordOffAddr#" GenPrimOp
 968    Addr# -> Int# -> State# s -> (# State# s, Word# #)
 969    with has_side_effects = True
 970
 971 primop ReadOffAddrOp_Addr "readAddrOffAddr#" GenPrimOp
 972    Addr# -> Int# -> State# s -> (# State# s, Addr# #)
 973    with has_side_effects = True
 974
 975 primop ReadOffAddrOp_Float "readFloatOffAddr#" GenPrimOp
 976    Addr# -> Int# -> State# s -> (# State# s, Float# #)
 977    with has_side_effects = True
 978
 979 primop ReadOffAddrOp_Double "readDoubleOffAddr#" GenPrimOp
 980    Addr# -> Int# -> State# s -> (# State# s, Double# #)
 981    with has_side_effects = True
 982
 983 primop ReadOffAddrOp_StablePtr "readStablePtrOffAddr#" GenPrimOp
 984    Addr# -> Int# -> State# s -> (# State# s, StablePtr# a #)
 985    with has_side_effects = True
 986
 987 primop ReadOffAddrOp_Int8 "readInt8OffAddr#" GenPrimOp
 988    Addr# -> Int# -> State# s -> (# State# s, Int# #)
 989    with has_side_effects = True
 990
 991 primop ReadOffAddrOp_Int16 "readInt16OffAddr#" GenPrimOp
 992    Addr# -> Int# -> State# s -> (# State# s, Int# #)
 993    with has_side_effects = True
 994
 995 primop ReadOffAddrOp_Int32 "readInt32OffAddr#" GenPrimOp
 996    Addr# -> Int# -> State# s -> (# State# s, INT32 #)
 997    with has_side_effects = True
 998
 999 primop ReadOffAddrOp_Int64 "readInt64OffAddr#" GenPrimOp
1000    Addr# -> Int# -> State# s -> (# State# s, INT64 #)
1001    with has_side_effects = True
1002
1003 primop ReadOffAddrOp_Word8 "readWord8OffAddr#" GenPrimOp
1004    Addr# -> Int# -> State# s -> (# State# s, Word# #)
1005    with has_side_effects = True
1006
1007 primop ReadOffAddrOp_Word16 "readWord16OffAddr#" GenPrimOp
1008    Addr# -> Int# -> State# s -> (# State# s, Word# #)
1009    with has_side_effects = True
1010
1011 primop ReadOffAddrOp_Word32 "readWord32OffAddr#" GenPrimOp
1012    Addr# -> Int# -> State# s -> (# State# s, WORD32 #)
1013    with has_side_effects = True
1014
1015 primop ReadOffAddrOp_Word64 "readWord64OffAddr#" GenPrimOp
1016    Addr# -> Int# -> State# s -> (# State# s, WORD64 #)
1017    with has_side_effects = True
1018
1019
1020 primop  WriteOffAddrOp_Char "writeCharOffAddr#" GenPrimOp
1021    Addr# -> Int# -> Char# -> State# s -> State# s
1022    with has_side_effects = True
1023
1024 primop  WriteOffAddrOp_WideChar "writeWideCharOffAddr#" GenPrimOp
1025    Addr# -> Int# -> Char# -> State# s -> State# s
1026    with has_side_effects = True
1027
1028 primop  WriteOffAddrOp_Int "writeIntOffAddr#" GenPrimOp
1029    Addr# -> Int# -> Int# -> State# s -> State# s
1030    with has_side_effects = True
1031
1032 primop  WriteOffAddrOp_Word "writeWordOffAddr#" GenPrimOp
1033    Addr# -> Int# -> Word# -> State# s -> State# s
1034    with has_side_effects = True
1035
1036 primop  WriteOffAddrOp_Addr "writeAddrOffAddr#" GenPrimOp
1037    Addr# -> Int# -> Addr# -> State# s -> State# s
1038    with has_side_effects = True
1039
1040 primop  WriteOffAddrOp_Float "writeFloatOffAddr#" GenPrimOp
1041    Addr# -> Int# -> Float# -> State# s -> State# s
1042    with has_side_effects = True
1043
1044 primop  WriteOffAddrOp_Double "writeDoubleOffAddr#" GenPrimOp
1045    Addr# -> Int# -> Double# -> State# s -> State# s
1046    with has_side_effects = True
1047
1048 primop  WriteOffAddrOp_StablePtr "writeStablePtrOffAddr#" GenPrimOp
1049    Addr# -> Int# -> StablePtr# a -> State# s -> State# s
1050    with has_side_effects = True
1051
1052 primop  WriteOffAddrOp_Int8 "writeInt8OffAddr#" GenPrimOp
1053    Addr# -> Int# -> Int# -> State# s -> State# s
1054    with has_side_effects = True
1055
1056 primop  WriteOffAddrOp_Int16 "writeInt16OffAddr#" GenPrimOp
1057    Addr# -> Int# -> Int# -> State# s -> State# s
1058    with has_side_effects = True
1059
1060 primop  WriteOffAddrOp_Int32 "writeInt32OffAddr#" GenPrimOp
1061    Addr# -> Int# -> INT32 -> State# s -> State# s
1062    with has_side_effects = True
1063
1064 primop  WriteOffAddrOp_Int64 "writeInt64OffAddr#" GenPrimOp
1065    Addr# -> Int# -> INT64 -> State# s -> State# s
1066    with has_side_effects = True
1067
1068 primop  WriteOffAddrOp_Word8 "writeWord8OffAddr#" GenPrimOp
1069    Addr# -> Int# -> Word# -> State# s -> State# s
1070    with has_side_effects = True
1071
1072 primop  WriteOffAddrOp_Word16 "writeWord16OffAddr#" GenPrimOp
1073    Addr# -> Int# -> Word# -> State# s -> State# s
1074    with has_side_effects = True
1075
1076 primop  WriteOffAddrOp_Word32 "writeWord32OffAddr#" GenPrimOp
1077    Addr# -> Int# -> WORD32 -> State# s -> State# s
1078    with has_side_effects = True
1079
1080 primop  WriteOffAddrOp_Word64 "writeWord64OffAddr#" GenPrimOp
1081    Addr# -> Int# -> WORD64 -> State# s -> State# s
1082    with has_side_effects = True
1083
1084 ------------------------------------------------------------------------
1085 section "Mutable variables"
1086         {Operations on MutVar\#s.}
1087 ------------------------------------------------------------------------
1088
1089 primtype MutVar# s a
1090         {A {\tt MutVar\#} behaves like a single-element mutable array.}
1091
1092 primop  NewMutVarOp "newMutVar#" GenPrimOp
1093    a -> State# s -> (# State# s, MutVar# s a #)
1094    {Create {\tt MutVar\#} with specified initial value in specified state thread.}
1095    with
1096    out_of_line = True
1097    has_side_effects = True
1098
1099 primop  ReadMutVarOp "readMutVar#" GenPrimOp
1100    MutVar# s a -> State# s -> (# State# s, a #)
1101    {Read contents of {\tt MutVar\#}. Result is not yet evaluated.}
1102    with
1103    has_side_effects = True
1104
1105 primop  WriteMutVarOp "writeMutVar#"  GenPrimOp
1106    MutVar# s a -> a -> State# s -> State# s
1107    {Write contents of {\tt MutVar\#}.}
1108    with
1109    has_side_effects = True
1110
1111 primop  SameMutVarOp "sameMutVar#" GenPrimOp
1112    MutVar# s a -> MutVar# s a -> Bool
1113
1114 -- not really the right type, but we don't know about pairs here.  The
1115 -- correct type is
1116 --
1117 --   MutVar# s a -> (a -> (a,b)) -> State# s -> (# State# s, b #)
1118 --
1119 primop  AtomicModifyMutVarOp "atomicModifyMutVar#" GenPrimOp
1120    MutVar# s a -> (a -> b) -> State# s -> (# State# s, c #)
1121    with
1122    out_of_line = True
1123    has_side_effects = True
1124
1125 ------------------------------------------------------------------------
1126 section "Exceptions"
1127 ------------------------------------------------------------------------
1128
1129 primop  CatchOp "catch#" GenPrimOp
1130           (State# RealWorld -> (# State# RealWorld, a #) )
1131        -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1132        -> State# RealWorld
1133        -> (# State# RealWorld, a #)
1134    with
1135         -- Catch is actually strict in its first argument
1136         -- but we don't want to tell the strictness
1137         -- analyser about that!
1138         -- might use caught action multiply
1139    out_of_line = True
1140    has_side_effects = True
1141
1142 primop  RaiseOp "raise#" GenPrimOp
1143    a -> b
1144    with
1145    strictness  = { \ _arity -> mkStrictSig (mkTopDmdType [lazyDmd] BotRes) }
1146       -- NB: result is bottom
1147    out_of_line = True
1148
1149 -- raiseIO# needs to be a primop, because exceptions in the IO monad
1150 -- must be *precise* - we don't want the strictness analyser turning
1151 -- one kind of bottom into another, as it is allowed to do in pure code.
1152
1153 primop  RaiseIOOp "raiseIO#" GenPrimOp
1154    a -> State# RealWorld -> (# State# RealWorld, b #)
1155    with
1156    out_of_line = True
1157    has_side_effects = True
1158
1159 primop  BlockAsyncExceptionsOp "blockAsyncExceptions#" GenPrimOp
1160         (State# RealWorld -> (# State# RealWorld, a #))
1161      -> (State# RealWorld -> (# State# RealWorld, a #))
1162    with
1163    out_of_line = True
1164    has_side_effects = True
1165
1166 primop  UnblockAsyncExceptionsOp "unblockAsyncExceptions#" GenPrimOp
1167         (State# RealWorld -> (# State# RealWorld, a #))
1168      -> (State# RealWorld -> (# State# RealWorld, a #))
1169    with
1170    out_of_line = True
1171    has_side_effects = True
1172
1173 primop  AsyncExceptionsBlockedOp "asyncExceptionsBlocked#" GenPrimOp
1174         State# RealWorld -> (# State# RealWorld, Int# #)
1175    with
1176    out_of_line = True
1177    has_side_effects = True
1178
1179 ------------------------------------------------------------------------
1180 section "STM-accessible Mutable Variables"
1181 ------------------------------------------------------------------------
1182
1183 primtype TVar# s a
1184
1185 primop  AtomicallyOp "atomically#" GenPrimOp
1186       (State# RealWorld -> (# State# RealWorld, a #) )
1187    -> State# RealWorld -> (# State# RealWorld, a #)
1188    with
1189    out_of_line = True
1190    has_side_effects = True
1191
1192 primop  RetryOp "retry#" GenPrimOp
1193    State# RealWorld -> (# State# RealWorld, a #)
1194    with
1195    out_of_line = True
1196    has_side_effects = True
1197
1198 primop  CatchRetryOp "catchRetry#" GenPrimOp
1199       (State# RealWorld -> (# State# RealWorld, a #) )
1200    -> (State# RealWorld -> (# State# RealWorld, a #) )
1201    -> (State# RealWorld -> (# State# RealWorld, a #) )
1202    with
1203    out_of_line = True
1204    has_side_effects = True
1205
1206 primop  CatchSTMOp "catchSTM#" GenPrimOp
1207       (State# RealWorld -> (# State# RealWorld, a #) )
1208    -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1209    -> (State# RealWorld -> (# State# RealWorld, a #) )
1210    with
1211    out_of_line = True
1212    has_side_effects = True
1213
1214 primop  Check "check#" GenPrimOp
1215       (State# RealWorld -> (# State# RealWorld, a #) )
1216    -> (State# RealWorld -> (# State# RealWorld, () #) )
1217    with
1218    out_of_line = True
1219    has_side_effects = True
1220
1221 primop  NewTVarOp "newTVar#" GenPrimOp
1222        a
1223     -> State# s -> (# State# s, TVar# s a #)
1224    {Create a new {\tt TVar\#} holding a specified initial value.}
1225    with
1226    out_of_line  = True
1227    has_side_effects = True
1228
1229 primop  ReadTVarOp "readTVar#" GenPrimOp
1230        TVar# s a
1231     -> State# s -> (# State# s, a #)
1232    {Read contents of {\tt TVar\#}.  Result is not yet evaluated.}
1233    with
1234    out_of_line  = True
1235    has_side_effects = True
1236
1237 primop ReadTVarIOOp "readTVarIO#" GenPrimOp
1238        TVar# s a
1239     -> State# s -> (# State# s, a #)
1240    {Read contents of {\tt TVar\#} outside an STM transaction}
1241    with
1242    out_of_line  = True
1243    has_side_effects = True
1244
1245 primop  WriteTVarOp "writeTVar#" GenPrimOp
1246        TVar# s a
1247     -> a
1248     -> State# s -> State# s
1249    {Write contents of {\tt TVar\#}.}
1250    with
1251    out_of_line      = True
1252    has_side_effects = True
1253
1254 primop  SameTVarOp "sameTVar#" GenPrimOp
1255    TVar# s a -> TVar# s a -> Bool
1256
1257
1258 ------------------------------------------------------------------------
1259 section "Synchronized Mutable Variables"
1260         {Operations on {\tt MVar\#}s. }
1261 ------------------------------------------------------------------------
1262
1263 primtype MVar# s a
1264         { A shared mutable variable ({\it not} the same as a {\tt MutVar\#}!).
1265         (Note: in a non-concurrent implementation, {\tt (MVar\# a)} can be
1266         represented by {\tt (MutVar\# (Maybe a))}.) }
1267
1268 primop  NewMVarOp "newMVar#"  GenPrimOp
1269    State# s -> (# State# s, MVar# s a #)
1270    {Create new {\tt MVar\#}; initially empty.}
1271    with
1272    out_of_line = True
1273    has_side_effects = True
1274
1275 primop  TakeMVarOp "takeMVar#" GenPrimOp
1276    MVar# s a -> State# s -> (# State# s, a #)
1277    {If {\tt MVar\#} is empty, block until it becomes full.
1278    Then remove and return its contents, and set it empty.}
1279    with
1280    out_of_line      = True
1281    has_side_effects = True
1282
1283 primop  TryTakeMVarOp "tryTakeMVar#" GenPrimOp
1284    MVar# s a -> State# s -> (# State# s, Int#, a #)
1285    {If {\tt MVar\#} is empty, immediately return with integer 0 and value undefined.
1286    Otherwise, return with integer 1 and contents of {\tt MVar\#}, and set {\tt MVar\#} empty.}
1287    with
1288    out_of_line      = True
1289    has_side_effects = True
1290
1291 primop  PutMVarOp "putMVar#" GenPrimOp
1292    MVar# s a -> a -> State# s -> State# s
1293    {If {\tt MVar\#} is full, block until it becomes empty.
1294    Then store value arg as its new contents.}
1295    with
1296    out_of_line      = True
1297    has_side_effects = True
1298
1299 primop  TryPutMVarOp "tryPutMVar#" GenPrimOp
1300    MVar# s a -> a -> State# s -> (# State# s, Int# #)
1301    {If {\tt MVar\#} is full, immediately return with integer 0.
1302     Otherwise, store value arg as {\tt MVar\#}'s new contents, and return with integer 1.}
1303    with
1304    out_of_line      = True
1305    has_side_effects = True
1306
1307 primop  SameMVarOp "sameMVar#" GenPrimOp
1308    MVar# s a -> MVar# s a -> Bool
1309
1310 primop  IsEmptyMVarOp "isEmptyMVar#" GenPrimOp
1311    MVar# s a -> State# s -> (# State# s, Int# #)
1312    {Return 1 if {\tt MVar\#} is empty; 0 otherwise.}
1313    with
1314    out_of_line = True
1315    has_side_effects = True
1316
1317 ------------------------------------------------------------------------
1318 section "Delay/wait operations"
1319 ------------------------------------------------------------------------
1320
1321 primop  DelayOp "delay#" GenPrimOp
1322    Int# -> State# s -> State# s
1323    {Sleep specified number of microseconds.}
1324    with
1325    needs_wrapper    = True
1326    has_side_effects = True
1327    out_of_line      = True
1328
1329 primop  WaitReadOp "waitRead#" GenPrimOp
1330    Int# -> State# s -> State# s
1331    {Block until input is available on specified file descriptor.}
1332    with
1333    needs_wrapper    = True
1334    has_side_effects = True
1335    out_of_line      = True
1336
1337 primop  WaitWriteOp "waitWrite#" GenPrimOp
1338    Int# -> State# s -> State# s
1339    {Block until output is possible on specified file descriptor.}
1340    with
1341    needs_wrapper    = True
1342    has_side_effects = True
1343    out_of_line      = True
1344
1345 #ifdef mingw32_TARGET_OS
1346 primop  AsyncReadOp "asyncRead#" GenPrimOp
1347    Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1348    {Asynchronously read bytes from specified file descriptor.}
1349    with
1350    needs_wrapper    = True
1351    has_side_effects = True
1352    out_of_line      = True
1353
1354 primop  AsyncWriteOp "asyncWrite#" GenPrimOp
1355    Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1356    {Asynchronously write bytes from specified file descriptor.}
1357    with
1358    needs_wrapper    = True
1359    has_side_effects = True
1360    out_of_line      = True
1361
1362 primop  AsyncDoProcOp "asyncDoProc#" GenPrimOp
1363    Addr# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1364    {Asynchronously perform procedure (first arg), passing it 2nd arg.}
1365    with
1366    needs_wrapper    = True
1367    has_side_effects = True
1368    out_of_line      = True
1369
1370 #endif
1371
1372 ------------------------------------------------------------------------
1373 section "Concurrency primitives"
1374 ------------------------------------------------------------------------
1375
1376 primtype State# s
1377         { {\tt State\#} is the primitive, unlifted type of states.  It has
1378         one type parameter, thus {\tt State\# RealWorld}, or {\tt State\# s},
1379         where s is a type variable. The only purpose of the type parameter
1380         is to keep different state threads separate.  It is represented by
1381         nothing at all. }
1382
1383 primtype RealWorld
1384         { {\tt RealWorld} is deeply magical.  It is {\it primitive}, but it is not
1385         {\it unlifted} (hence {\tt ptrArg}).  We never manipulate values of type
1386         {\tt RealWorld}; it's only used in the type system, to parameterise {\tt State\#}. }
1387
1388 primtype ThreadId#
1389         {(In a non-concurrent implementation, this can be a singleton
1390         type, whose (unique) value is returned by {\tt myThreadId\#}.  The
1391         other operations can be omitted.)}
1392
1393 primop  ForkOp "fork#" GenPrimOp
1394    a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
1395    with
1396    has_side_effects = True
1397    out_of_line      = True
1398
1399 primop  ForkOnOp "forkOn#" GenPrimOp
1400    Int# -> a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
1401    with
1402    has_side_effects = True
1403    out_of_line      = True
1404
1405 primop  KillThreadOp "killThread#"  GenPrimOp
1406    ThreadId# -> a -> State# RealWorld -> State# RealWorld
1407    with
1408    has_side_effects = True
1409    out_of_line      = True
1410
1411 primop  YieldOp "yield#" GenPrimOp
1412    State# RealWorld -> State# RealWorld
1413    with
1414    has_side_effects = True
1415    out_of_line      = True
1416
1417 primop  MyThreadIdOp "myThreadId#" GenPrimOp
1418    State# RealWorld -> (# State# RealWorld, ThreadId# #)
1419    with
1420    out_of_line = True
1421    has_side_effects = True
1422
1423 primop LabelThreadOp "labelThread#" GenPrimOp
1424    ThreadId# -> Addr# -> State# RealWorld -> State# RealWorld
1425    with
1426    has_side_effects = True
1427    out_of_line      = True
1428
1429 primop  IsCurrentThreadBoundOp "isCurrentThreadBound#" GenPrimOp
1430    State# RealWorld -> (# State# RealWorld, Int# #)
1431    with
1432    out_of_line = True
1433    has_side_effects = True
1434
1435 primop  NoDuplicateOp "noDuplicate#" GenPrimOp
1436    State# RealWorld -> State# RealWorld
1437    with
1438    out_of_line = True
1439    has_side_effects = True
1440
1441 primop  ThreadStatusOp "threadStatus#" GenPrimOp
1442    ThreadId# -> State# RealWorld -> (# State# RealWorld, Int# #)
1443    with
1444    out_of_line = True
1445    has_side_effects = True
1446
1447 ------------------------------------------------------------------------
1448 section "Weak pointers"
1449 ------------------------------------------------------------------------
1450
1451 primtype Weak# b
1452
1453 -- note that tyvar "o" denotes openAlphaTyVar
1454
1455 primop  MkWeakOp "mkWeak#" GenPrimOp
1456    o -> b -> c -> State# RealWorld -> (# State# RealWorld, Weak# b #)
1457    with
1458    has_side_effects = True
1459    out_of_line      = True
1460
1461 primop  MkWeakForeignEnvOp "mkWeakForeignEnv#" GenPrimOp
1462    o -> b -> Addr# -> Addr# -> Int# -> Addr# -> State# RealWorld -> (# State# RealWorld, Weak# b #)
1463    with
1464    has_side_effects = True
1465    out_of_line      = True
1466
1467 primop  DeRefWeakOp "deRefWeak#" GenPrimOp
1468    Weak# a -> State# RealWorld -> (# State# RealWorld, Int#, a #)
1469    with
1470    has_side_effects = True
1471    out_of_line      = True
1472
1473 primop  FinalizeWeakOp "finalizeWeak#" GenPrimOp
1474    Weak# a -> State# RealWorld -> (# State# RealWorld, Int#,
1475               (State# RealWorld -> (# State# RealWorld, () #)) #)
1476    with
1477    has_side_effects = True
1478    out_of_line      = True
1479
1480 primop TouchOp "touch#" GenPrimOp
1481    o -> State# RealWorld -> State# RealWorld
1482    with
1483    has_side_effects = True
1484
1485 ------------------------------------------------------------------------
1486 section "Stable pointers and names"
1487 ------------------------------------------------------------------------
1488
1489 primtype StablePtr# a
1490
1491 primtype StableName# a
1492
1493 primop  MakeStablePtrOp "makeStablePtr#" GenPrimOp
1494    a -> State# RealWorld -> (# State# RealWorld, StablePtr# a #)
1495    with
1496    has_side_effects = True
1497    out_of_line      = True
1498
1499 primop  DeRefStablePtrOp "deRefStablePtr#" GenPrimOp
1500    StablePtr# a -> State# RealWorld -> (# State# RealWorld, a #)
1501    with
1502    needs_wrapper    = True
1503    has_side_effects = True
1504    out_of_line      = True
1505
1506 primop  EqStablePtrOp "eqStablePtr#" GenPrimOp
1507    StablePtr# a -> StablePtr# a -> Int#
1508    with
1509    has_side_effects = True
1510
1511 primop  MakeStableNameOp "makeStableName#" GenPrimOp
1512    a -> State# RealWorld -> (# State# RealWorld, StableName# a #)
1513    with
1514    needs_wrapper    = True
1515    has_side_effects = True
1516    out_of_line      = True
1517
1518 primop  EqStableNameOp "eqStableName#" GenPrimOp
1519    StableName# a -> StableName# a -> Int#
1520
1521 primop  StableNameToIntOp "stableNameToInt#" GenPrimOp
1522    StableName# a -> Int#
1523
1524 ------------------------------------------------------------------------
1525 section "Unsafe pointer equality"
1526 --  (#1 Bad Guy: Alistair Reid :)
1527 ------------------------------------------------------------------------
1528
1529 primop  ReallyUnsafePtrEqualityOp "reallyUnsafePtrEquality#" GenPrimOp
1530    a -> a -> Int#
1531
1532 ------------------------------------------------------------------------
1533 section "Parallelism"
1534 ------------------------------------------------------------------------
1535
1536 primop  ParOp "par#" GenPrimOp
1537    a -> Int#
1538    with
1539       -- Note that Par is lazy to avoid that the sparked thing
1540       -- gets evaluted strictly, which it should *not* be
1541    has_side_effects = True
1542
1543 primop GetSparkOp "getSpark#" GenPrimOp
1544    State# s -> (# State# s, Int#, a #)
1545    with
1546    has_side_effects = True
1547    out_of_line = True
1548
1549 -- HWL: The first 4 Int# in all par... annotations denote:
1550 --   name, granularity info, size of result, degree of parallelism
1551 --      Same  structure as _seq_ i.e. returns Int#
1552 -- KSW: v, the second arg in parAt# and parAtForNow#, is used only to determine
1553 --   `the processor containing the expression v'; it is not evaluated
1554
1555 primop  ParGlobalOp  "parGlobal#"  GenPrimOp
1556    a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1557    with
1558    has_side_effects = True
1559
1560 primop  ParLocalOp  "parLocal#"  GenPrimOp
1561    a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1562    with
1563    has_side_effects = True
1564
1565 primop  ParAtOp  "parAt#"  GenPrimOp
1566    b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
1567    with
1568    has_side_effects = True
1569
1570 primop  ParAtAbsOp  "parAtAbs#"  GenPrimOp
1571    a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1572    with
1573    has_side_effects = True
1574
1575 primop  ParAtRelOp  "parAtRel#" GenPrimOp
1576    a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1577    with
1578    has_side_effects = True
1579
1580 primop  ParAtForNowOp  "parAtForNow#" GenPrimOp
1581    b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
1582    with
1583    has_side_effects = True
1584
1585 -- copyable# and noFollow# are yet to be implemented (for GpH)
1586 --
1587 --primop  CopyableOp  "copyable#" GenPrimOp
1588 --   a -> Int#
1589 --   with
1590 --   has_side_effects = True
1591 --
1592 --primop  NoFollowOp "noFollow#" GenPrimOp
1593 --   a -> Int#
1594 --   with
1595 --   has_side_effects = True
1596
1597
1598 ------------------------------------------------------------------------
1599 section "Tag to enum stuff"
1600         {Convert back and forth between values of enumerated types
1601         and small integers.}
1602 ------------------------------------------------------------------------
1603
1604 primop  DataToTagOp "dataToTag#" GenPrimOp
1605    a -> Int#
1606    with
1607    strictness  = { \ _arity -> mkStrictSig (mkTopDmdType [seqDmd] TopRes) }
1608         -- dataToTag# must have an evaluated argument
1609
1610 primop  TagToEnumOp "tagToEnum#" GenPrimOp
1611    Int# -> a
1612
1613 ------------------------------------------------------------------------
1614 section "Bytecode operations"
1615         {Support for the bytecode interpreter and linker.}
1616 ------------------------------------------------------------------------
1617
1618 primtype BCO#
1619    {Primitive bytecode type.}
1620
1621 primop   AddrToHValueOp "addrToHValue#" GenPrimOp
1622    Addr# -> (# a #)
1623    {Convert an {\tt Addr\#} to a followable type.}
1624
1625 primop   MkApUpd0_Op "mkApUpd0#" GenPrimOp
1626    BCO# -> (# a #)
1627    with
1628    out_of_line = True
1629
1630 primop  NewBCOOp "newBCO#" GenPrimOp
1631    ByteArray# -> ByteArray# -> Array# a -> Int# -> ByteArray# -> State# s -> (# State# s, BCO# #)
1632    with
1633    has_side_effects = True
1634    out_of_line      = True
1635
1636 primop  UnpackClosureOp "unpackClosure#" GenPrimOp
1637    a -> (# Addr#, Array# b, ByteArray# #)
1638    with
1639    out_of_line = True
1640
1641 primop  GetApStackValOp "getApStackVal#" GenPrimOp
1642    a -> Int# -> (# Int#, b #)
1643    with
1644    out_of_line = True
1645
1646 ------------------------------------------------------------------------
1647 section "Misc"
1648         {These aren't nearly as wired in as Etc...}
1649 ------------------------------------------------------------------------
1650
1651 primop  TraceCcsOp "traceCcs#" GenPrimOp
1652    a -> b -> b
1653    with
1654    has_side_effects = True
1655    out_of_line = True
1656
1657 ------------------------------------------------------------------------
1658 section "Etc"
1659         {Miscellaneous built-ins}
1660 ------------------------------------------------------------------------
1661
1662 pseudoop   "seq"
1663    a -> b -> b
1664    { Evaluates its first argument to head normal form, and then returns its second
1665         argument as the result. }
1666
1667 pseudoop   "inline"
1668    a -> a
1669    { The call {\tt (inline f)} arranges that f is inlined, regardless of its size.
1670         More precisely, the call {\tt (inline f)} rewrites to the right-hand side of
1671         {\tt f}'s definition. This allows the programmer to control inlining from a
1672         particular call site rather than the definition site of the function (c.f.
1673         {\tt INLINE} pragmas in User's Guide, Section 7.10.3, "INLINE and NOINLINE
1674         pragmas").
1675
1676         This inlining occurs regardless of the argument to the call or the size of
1677         {\tt f}'s definition; it is unconditional. The main caveat is that {\tt f}'s
1678         definition must be visible to the compiler. That is, {\tt f} must be
1679         {\tt let}-bound in the current scope. If no inlining takes place, the
1680         {\tt inline} function expands to the identity function in Phase zero; so its
1681         use imposes no overhead.
1682
1683         If the function is defined in another module, GHC only exposes its inlining
1684         in the interface file if the function is sufficiently small that it might be
1685         inlined by the automatic mechanism. There is currently no way to tell GHC to
1686         expose arbitrarily-large functions in the interface file. (This shortcoming
1687         is something that could be fixed, with some kind of pragma.) }
1688
1689 pseudoop   "lazy"
1690    a -> a
1691    { The {\tt lazy} function restrains strictness analysis a little. The call
1692         {\tt (lazy e)} means the same as {\tt e}, but {\tt lazy} has a magical
1693         property so far as strictness analysis is concerned: it is lazy in its first
1694         argument, even though its semantics is strict. After strictness analysis has
1695         run, calls to {\tt lazy} are inlined to be the identity function.
1696
1697         This behaviour is occasionally useful when controlling evaluation order.
1698         Notably, {\tt lazy} is used in the library definition of {\tt Control.Parallel.par}:
1699
1700         {\tt par :: a -> b -> b}
1701
1702         {\tt par x y = case (par\# x) of \_ -> lazy y}
1703
1704         If {\tt lazy} were not lazy, {\tt par} would look strict in {\tt y} which
1705         would defeat the whole purpose of {\tt par}.
1706
1707         Like {\tt seq}, the argument of {\tt lazy} can have an unboxed type. }
1708
1709 primtype Any a
1710         { The type constructor {\tt Any} is type to which you can unsafely coerce any
1711         lifted type, and back.
1712
1713           * It is lifted, and hence represented by a pointer
1714
1715           * It does not claim to be a {\it data} type, and that's important for
1716             the code generator, because the code gen may {\it enter} a data value
1717             but never enters a function value.
1718
1719         It's also used to instantiate un-constrained type variables after type
1720         checking.  For example
1721
1722         {\tt length Any []}
1723
1724         Annoyingly, we sometimes need {\tt Any}s of other kinds, such as {\tt (* -> *)} etc.
1725         This is a bit like tuples.   We define a couple of useful ones here,
1726         and make others up on the fly.  If any of these others end up being exported
1727         into interface files, we'll get a crash; at least until we add interface-file
1728         syntax to support them. }
1729
1730 pseudoop   "unsafeCoerce#"
1731    a -> b
1732    { The function {\tt unsafeCoerce\#} allows you to side-step the typechecker entirely. That
1733         is, it allows you to coerce any type into any other type. If you use this function,
1734         you had better get it right, otherwise segmentation faults await. It is generally
1735         used when you want to write a program that you know is well-typed, but where Haskell's
1736         type system is not expressive enough to prove that it is well typed.
1737
1738         The following uses of {\tt unsafeCoerce\#} are supposed to work (i.e. not lead to
1739         spurious compile-time or run-time crashes):
1740
1741          * Casting any lifted type to {\tt Any}
1742
1743          * Casting {\tt Any} back to the real type
1744
1745          * Casting an unboxed type to another unboxed type of the same size
1746            (but not coercions between floating-point and integral types)
1747
1748          * Casting between two types that have the same runtime representation.  One case is when
1749            the two types differ only in "phantom" type parameters, for example
1750            {\tt Ptr Int} to {\tt Ptr Float}, or {\tt [Int]} to {\tt [Float]} when the list is
1751            known to be empty.  Also, a {\tt newtype} of a type {\tt T} has the same representation
1752            at runtime as {\tt T}.
1753
1754         Other uses of {\tt unsafeCoerce\#} are undefined.  In particular, you should not use
1755         {\tt unsafeCoerce\#} to cast a T to an algebraic data type D, unless T is also
1756         an algebraic data type.  For example, do not cast {\tt Int->Int} to {\tt Bool}, even if
1757         you later cast that {\tt Bool} back to {\tt Int->Int} before applying it.  The reasons
1758         have to do with GHC's internal representation details (for the congnoscenti, data values
1759         can be entered but function closures cannot).  If you want a safe type to cast things
1760         to, use {\tt Any}, which is not an algebraic data type.
1761
1762         }
1763
1764 -- NB. It is tempting to think that casting a value to a type that it doesn't have is safe
1765 -- as long as you don't "do anything" with the value in its cast form, such as seq on it.  This
1766 -- isn't the case: the compiler can insert seqs itself, and if these happen at the wrong type,
1767 -- Bad Things Might Happen.  See bug #1616: in this case we cast a function of type (a,b) -> (a,b)
1768 -- to () -> () and back again.  The strictness analyser saw that the function was strict, but
1769 -- the wrapper had type () -> (), and hence the wrapper de-constructed the (), the worker re-constructed
1770 -- a new (), with the result that the code ended up with "case () of (a,b) -> ...".
1771
1772 primop  TraceEventOp "traceEvent#" GenPrimOp
1773    Addr# -> State# s -> State# s
1774    { Emits an event via the RTS tracing framework.  The contents
1775      of the event is the zero-terminated byte string passed as the first
1776      argument.  The event will be emitted either to the .eventlog file,
1777      or to stderr, depending on the runtime RTS flags. }
1778    with
1779    has_side_effects = True
1780    out_of_line      = True
1781
1782 ------------------------------------------------------------------------
1783 ---                                                                  ---
1784 ------------------------------------------------------------------------
1785
1786 thats_all_folks
1787
1788
1789