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