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