compiler/prelude/primops.txt.pp

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