compiler/prelude/primops.txt.pp

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