compiler/prelude/primops.txt.pp

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