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