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