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