PrelRules: Handle Int left shifts of more than word-size bits
[ghc.git] / compiler / prelude / primops.txt.pp
1 -----------------------------------------------------------------------
2 --
3 -- (c) 2010 The University of Glasgow
4 --
5 -- Primitive Operations and Types
6 --
7 -- For more information on PrimOps, see
8 --   http://ghc.haskell.org/trac/ghc/wiki/Commentary/PrimOps
9 --
10 -----------------------------------------------------------------------
11
12 -- This file is processed by the utility program genprimopcode to produce
13 -- a number of include files within the compiler and optionally to produce
14 -- human-readable documentation.
15 --
16 -- It should first be preprocessed.
17 --
18 -- Information on how PrimOps are implemented and the steps necessary to
19 -- add a new one can be found in the Commentary:
20 --
21 --  http://ghc.haskell.org/trac/ghc/wiki/Commentary/PrimOps
22
23 -- This file is divided into named sections, each containing or more
24 -- primop entries. Section headers have the format:
25 --
26 --      section "section-name" {description}
27 --
28 -- This information is used solely when producing documentation; it is
29 -- otherwise ignored.  The description is optional.
30 --
31 -- The format of each primop entry is as follows:
32 --
33 --      primop internal-name "name-in-program-text" type category {description} attributes
34
35 -- The default attribute values which apply if you don't specify
36 -- other ones.  Attribute values can be True, False, or arbitrary
37 -- text between curly brackets.  This is a kludge to enable
38 -- processors of this file to easily get hold of simple info
39 -- (eg, out_of_line), whilst avoiding parsing complex expressions
40 -- needed for strictness info.
41 --
42 -- type refers to the general category of the primop. Valid settings include,
43 --
44 --  * Compare:   A comparison operation of the shape a -> a -> Int#
45 --  * Monadic:   A unary operation of shape a -> a
46 --  * Dyadic:    A binary operation of shape a -> a -> a
47 --  * GenPrimOp: Any other sort of primop
48 --
49
50 -- The vector attribute is rather special. It takes a list of 3-tuples, each of
51 -- which is of the form <ELEM_TYPE,SCALAR_TYPE,LENGTH>. ELEM_TYPE is the type of
52 -- the elements in the vector; LENGTH is the length of the vector; and
53 -- SCALAR_TYPE is the scalar type used to inject to/project from vector
54 -- element. Note that ELEM_TYPE and SCALAR_TYPE are not the same; for example,
55 -- to broadcast a scalar value to a vector whose elements are of type Int8, we
56 -- use an Int#.
57
58 -- When a primtype or primop has a vector attribute, it is instantiated at each
59 -- 3-tuple in the list of 3-tuples. That is, the vector attribute allows us to
60 -- define a family of types or primops. Vector support also adds three new
61 -- keywords: VECTOR, SCALAR, and VECTUPLE. These keywords are expanded to types
62 -- derived from the 3-tuple. For the 3-tuple <Int64,INT64,2>, VECTOR expands to
63 -- Int64X2#, SCALAR expands to INT64, and VECTUPLE expands to (# INT64, INT64
64 -- #).
65
66 defaults
67    has_side_effects = False
68    out_of_line      = False   -- See Note Note [PrimOp can_fail and has_side_effects] in PrimOp
69    can_fail         = False   -- See Note Note [PrimOp can_fail and has_side_effects] in PrimOp
70    commutable       = False
71    code_size        = { primOpCodeSizeDefault }
72    strictness       = { \ arity -> mkClosedStrictSig (replicate arity topDmd) topRes }
73    fixity           = Nothing
74    llvm_only        = False
75    vector           = []
76
77 -- Currently, documentation is produced using latex, so contents of
78 -- description fields should be legal latex. Descriptions can contain
79 -- matched pairs of embedded curly brackets.
80
81 #include "MachDeps.h"
82
83 -- We need platform defines (tests for mingw32 below).
84 #include "ghc_boot_platform.h"
85
86 section "The word size story."
87         {Haskell98 specifies that signed integers (type {\tt Int})
88          must contain at least 30 bits. GHC always implements {\tt
89          Int} using the primitive type {\tt Int\#}, whose size equals
90          the {\tt MachDeps.h} constant {\tt WORD\_SIZE\_IN\_BITS}.
91          This is normally set based on the {\tt config.h} parameter
92          {\tt SIZEOF\_HSWORD}, i.e., 32 bits on 32-bit machines, 64
93          bits on 64-bit machines.  However, it can also be explicitly
94          set to a smaller number, e.g., 31 bits, to allow the
95          possibility of using tag bits. Currently GHC itself has only
96          32-bit and 64-bit variants, but 30 or 31-bit code can be
97          exported as an external core file for use in other back ends.
98
99          GHC also implements a primitive unsigned integer type {\tt
100          Word\#} which always has the same number of bits as {\tt
101          Int\#}.
102
103          In addition, GHC supports families of explicit-sized integers
104          and words at 8, 16, 32, and 64 bits, with the usual
105          arithmetic operations, comparisons, and a range of
106          conversions.  The 8-bit and 16-bit sizes are always
107          represented as {\tt Int\#} and {\tt Word\#}, and the
108          operations implemented in terms of the the primops on these
109          types, with suitable range restrictions on the results (using
110          the {\tt narrow$n$Int\#} and {\tt narrow$n$Word\#} families
111          of primops.  The 32-bit sizes are represented using {\tt
112          Int\#} and {\tt Word\#} when {\tt WORD\_SIZE\_IN\_BITS}
113          $\geq$ 32; otherwise, these are represented using distinct
114          primitive types {\tt Int32\#} and {\tt Word32\#}. These (when
115          needed) have a complete set of corresponding operations;
116          however, nearly all of these are implemented as external C
117          functions rather than as primops.  Exactly the same story
118          applies to the 64-bit sizes.  All of these details are hidden
119          under the {\tt PrelInt} and {\tt PrelWord} modules, which use
120          {\tt \#if}-defs to invoke the appropriate types and
121          operators.
122
123          Word size also matters for the families of primops for
124          indexing/reading/writing fixed-size quantities at offsets
125          from an array base, address, or foreign pointer.  Here, a
126          slightly different approach is taken.  The names of these
127          primops are fixed, but their {\it types} vary according to
128          the value of {\tt WORD\_SIZE\_IN\_BITS}. For example, if word
129          size is at least 32 bits then an operator like
130          \texttt{indexInt32Array\#} has type {\tt ByteArray\# -> Int\#
131          -> Int\#}; otherwise it has type {\tt ByteArray\# -> Int\# ->
132          Int32\#}.  This approach confines the necessary {\tt
133          \#if}-defs to this file; no conditional compilation is needed
134          in the files that expose these primops.
135
136          Finally, there are strongly deprecated primops for coercing
137          between {\tt Addr\#}, the primitive type of machine
138          addresses, and {\tt Int\#}.  These are pretty bogus anyway,
139          but will work on existing 32-bit and 64-bit GHC targets; they
140          are completely bogus when tag bits are used in {\tt Int\#},
141          so are not available in this case.  }
142
143 -- Define synonyms for indexing ops.
144
145 #if WORD_SIZE_IN_BITS < 32
146 #define INT32 Int32#
147 #define WORD32 Word32#
148 #else
149 #define INT32 Int#
150 #define WORD32 Word#
151 #endif
152
153 #if WORD_SIZE_IN_BITS < 64
154 #define INT64 Int64#
155 #define WORD64 Word64#
156 #else
157 #define INT64 Int#
158 #define WORD64 Word#
159 #endif
160
161 ------------------------------------------------------------------------
162 section "Char#"
163         {Operations on 31-bit characters.}
164 ------------------------------------------------------------------------
165
166 primtype Char#
167
168 primop   CharGtOp  "gtChar#"   Compare   Char# -> Char# -> Int#
169 primop   CharGeOp  "geChar#"   Compare   Char# -> Char# -> Int#
170
171 primop   CharEqOp  "eqChar#"   Compare
172    Char# -> Char# -> Int#
173    with commutable = True
174
175 primop   CharNeOp  "neChar#"   Compare
176    Char# -> Char# -> Int#
177    with commutable = True
178
179 primop   CharLtOp  "ltChar#"   Compare   Char# -> Char# -> Int#
180 primop   CharLeOp  "leChar#"   Compare   Char# -> Char# -> Int#
181
182 primop   OrdOp   "ord#"  GenPrimOp   Char# -> Int#
183    with code_size = 0
184
185 ------------------------------------------------------------------------
186 section "Int#"
187         {Operations on native-size integers (30+ bits).}
188 ------------------------------------------------------------------------
189
190 primtype Int#
191
192 primop   IntAddOp    "+#"    Dyadic
193    Int# -> Int# -> Int#
194    with commutable = True
195         fixity = infixl 6
196
197 primop   IntSubOp    "-#"    Dyadic   Int# -> Int# -> Int#
198    with fixity = infixl 6
199
200 primop   IntMulOp    "*#"
201    Dyadic   Int# -> Int# -> Int#
202    {Low word of signed integer multiply.}
203    with commutable = True
204         fixity = infixl 7
205
206 primop   IntMulMayOfloOp  "mulIntMayOflo#"
207    Dyadic   Int# -> Int# -> Int#
208    {Return non-zero if there is any possibility that the upper word of a
209     signed integer multiply might contain useful information.  Return
210     zero only if you are completely sure that no overflow can occur.
211     On a 32-bit platform, the recommended implementation is to do a
212     32 x 32 -> 64 signed multiply, and subtract result[63:32] from
213     (result[31] >>signed 31).  If this is zero, meaning that the
214     upper word is merely a sign extension of the lower one, no
215     overflow can occur.
216
217     On a 64-bit platform it is not always possible to
218     acquire the top 64 bits of the result.  Therefore, a recommended
219     implementation is to take the absolute value of both operands, and
220     return 0 iff bits[63:31] of them are zero, since that means that their
221     magnitudes fit within 31 bits, so the magnitude of the product must fit
222     into 62 bits.
223
224     If in doubt, return non-zero, but do make an effort to create the
225     correct answer for small args, since otherwise the performance of
226     \texttt{(*) :: Integer -> Integer -> Integer} will be poor.
227    }
228    with commutable = True
229
230 primop   IntQuotOp    "quotInt#"    Dyadic
231    Int# -> Int# -> Int#
232    {Rounds towards zero. The behavior is undefined if the second argument is
233     zero.
234    }
235    with can_fail = True
236
237 primop   IntRemOp    "remInt#"    Dyadic
238    Int# -> Int# -> Int#
239    {Satisfies \texttt{(quotInt\# x y) *\# y +\# (remInt\# x y) == x}. The
240     behavior is undefined if the second argument is zero.
241    }
242    with can_fail = True
243
244 primop   IntQuotRemOp "quotRemInt#"    GenPrimOp
245    Int# -> Int# -> (# Int#, Int# #)
246    {Rounds towards zero.}
247    with can_fail = True
248
249 primop   AndIOp   "andI#"   Dyadic    Int# -> Int# -> Int#
250    with commutable = True
251
252 primop   OrIOp   "orI#"     Dyadic    Int# -> Int# -> Int#
253    with commutable = True
254
255 primop   XorIOp   "xorI#"   Dyadic    Int# -> Int# -> Int#
256    with commutable = True
257
258 primop   NotIOp   "notI#"   Monadic   Int# -> Int#
259
260 primop   IntNegOp    "negateInt#"    Monadic   Int# -> Int#
261 primop   IntAddCOp   "addIntC#"    GenPrimOp   Int# -> Int# -> (# Int#, Int# #)
262          {Add signed integers reporting overflow.
263           First member of result is the sum truncated to an {\tt Int#};
264           second member is zero if the true sum fits in an {\tt Int#},
265           nonzero if overflow occurred (the sum is either too large
266           or too small to fit in an {\tt Int#}).}
267    with code_size = 2
268
269 primop   IntSubCOp   "subIntC#"    GenPrimOp   Int# -> Int# -> (# Int#, Int# #)
270          {Subtract signed integers reporting overflow.
271           First member of result is the difference truncated to an {\tt Int#};
272           second member is zero if the true difference fits in an {\tt Int#},
273           nonzero if overflow occurred (the difference is either too large
274           or too small to fit in an {\tt Int#}).}
275    with code_size = 2
276
277 primop   IntGtOp  ">#"   Compare   Int# -> Int# -> Int#
278    with fixity = infix 4
279
280 primop   IntGeOp  ">=#"   Compare   Int# -> Int# -> Int#
281    with fixity = infix 4
282
283 primop   IntEqOp  "==#"   Compare
284    Int# -> Int# -> Int#
285    with commutable = True
286         fixity = infix 4
287
288 primop   IntNeOp  "/=#"   Compare
289    Int# -> Int# -> Int#
290    with commutable = True
291         fixity = infix 4
292
293 primop   IntLtOp  "<#"   Compare   Int# -> Int# -> Int#
294    with fixity = infix 4
295
296 primop   IntLeOp  "<=#"   Compare   Int# -> Int# -> Int#
297    with fixity = infix 4
298
299 primop   ChrOp   "chr#"   GenPrimOp   Int# -> Char#
300    with code_size = 0
301
302 primop   Int2WordOp "int2Word#" GenPrimOp Int# -> Word#
303    with code_size = 0
304
305 primop   Int2FloatOp   "int2Float#"      GenPrimOp  Int# -> Float#
306 primop   Int2DoubleOp   "int2Double#"          GenPrimOp  Int# -> Double#
307
308 primop   Word2FloatOp   "word2Float#"      GenPrimOp  Word# -> Float#
309 primop   Word2DoubleOp   "word2Double#"          GenPrimOp  Word# -> Double#
310
311 primop   ISllOp   "uncheckedIShiftL#" GenPrimOp  Int# -> Int# -> Int#
312          {Shift left.  Result undefined if shift amount is not
313           in the range 0 to word size - 1 inclusive.}
314 primop   ISraOp   "uncheckedIShiftRA#" GenPrimOp Int# -> Int# -> Int#
315          {Shift right arithmetic.  Result undefined if shift amount is not
316           in the range 0 to word size - 1 inclusive.}
317 primop   ISrlOp   "uncheckedIShiftRL#" GenPrimOp Int# -> Int# -> Int#
318          {Shift right logical.  Result undefined if shift amount is not
319           in the range 0 to word size - 1 inclusive.}
320
321 ------------------------------------------------------------------------
322 section "Word#"
323         {Operations on native-sized unsigned words (30+ bits).}
324 ------------------------------------------------------------------------
325
326 primtype Word#
327
328 primop   WordAddOp   "plusWord#"   Dyadic   Word# -> Word# -> Word#
329    with commutable = True
330
331 primop   WordSubCOp   "subWordC#"   GenPrimOp   Word# -> Word# -> (# Word#, Int# #)
332          {Subtract unsigned integers reporting overflow.
333           The first element of the pair is the result.  The second element is
334           the carry flag, which is nonzero on overflow.}
335
336 -- Returns (# high, low #) (or equivalently, (# carry, low #))
337 primop   WordAdd2Op  "plusWord2#"  GenPrimOp
338    Word# -> Word# -> (# Word#, Word# #)
339    with commutable = True
340
341 primop   WordSubOp   "minusWord#"   Dyadic   Word# -> Word# -> Word#
342
343 primop   WordMulOp   "timesWord#"   Dyadic   Word# -> Word# -> Word#
344    with commutable = True
345
346 -- Returns (# high, low #)
347 primop   WordMul2Op  "timesWord2#"   GenPrimOp
348    Word# -> Word# -> (# Word#, Word# #)
349    with commutable = True
350
351 primop   WordQuotOp   "quotWord#"   Dyadic   Word# -> Word# -> Word#
352    with can_fail = True
353
354 primop   WordRemOp   "remWord#"   Dyadic   Word# -> Word# -> Word#
355    with can_fail = True
356
357 primop   WordQuotRemOp "quotRemWord#" GenPrimOp
358    Word# -> Word# -> (# Word#, Word# #)
359    with can_fail = True
360
361 -- Takes high word of dividend, then low word of dividend, then divisor.
362 -- Requires that high word is not divisible by divisor.
363 primop   WordQuotRem2Op "quotRemWord2#" GenPrimOp
364    Word# -> Word# -> Word# -> (# Word#, Word# #)
365    with can_fail = True
366
367 primop   AndOp   "and#"   Dyadic   Word# -> Word# -> Word#
368    with commutable = True
369
370 primop   OrOp   "or#"   Dyadic   Word# -> Word# -> Word#
371    with commutable = True
372
373 primop   XorOp   "xor#"   Dyadic   Word# -> Word# -> Word#
374    with commutable = True
375
376 primop   NotOp   "not#"   Monadic   Word# -> Word#
377
378 primop   SllOp   "uncheckedShiftL#"   GenPrimOp   Word# -> Int# -> Word#
379          {Shift left logical.   Result undefined if shift amount is not
380           in the range 0 to word size - 1 inclusive.}
381 primop   SrlOp   "uncheckedShiftRL#"   GenPrimOp   Word# -> Int# -> Word#
382          {Shift right logical.   Result undefined if shift  amount is not
383           in the range 0 to word size - 1 inclusive.}
384
385 primop   Word2IntOp   "word2Int#"   GenPrimOp   Word# -> Int#
386    with code_size = 0
387
388 primop   WordGtOp   "gtWord#"   Compare   Word# -> Word# -> Int#
389 primop   WordGeOp   "geWord#"   Compare   Word# -> Word# -> Int#
390 primop   WordEqOp   "eqWord#"   Compare   Word# -> Word# -> Int#
391 primop   WordNeOp   "neWord#"   Compare   Word# -> Word# -> Int#
392 primop   WordLtOp   "ltWord#"   Compare   Word# -> Word# -> Int#
393 primop   WordLeOp   "leWord#"   Compare   Word# -> Word# -> Int#
394
395 primop   PopCnt8Op   "popCnt8#"   Monadic   Word# -> Word#
396     {Count the number of set bits in the lower 8 bits of a word.}
397 primop   PopCnt16Op   "popCnt16#"   Monadic   Word# -> Word#
398     {Count the number of set bits in the lower 16 bits of a word.}
399 primop   PopCnt32Op   "popCnt32#"   Monadic   Word# -> Word#
400     {Count the number of set bits in the lower 32 bits of a word.}
401 primop   PopCnt64Op   "popCnt64#"   GenPrimOp   WORD64 -> Word#
402     {Count the number of set bits in a 64-bit word.}
403 primop   PopCntOp   "popCnt#"   Monadic   Word# -> Word#
404     {Count the number of set bits in a word.}
405
406 primop   Clz8Op   "clz8#" Monadic   Word# -> Word#
407     {Count leading zeros in the lower 8 bits of a word.}
408 primop   Clz16Op   "clz16#" Monadic   Word# -> Word#
409     {Count leading zeros in the lower 16 bits of a word.}
410 primop   Clz32Op   "clz32#" Monadic   Word# -> Word#
411     {Count leading zeros in the lower 32 bits of a word.}
412 primop   Clz64Op   "clz64#" GenPrimOp WORD64 -> Word#
413     {Count leading zeros in a 64-bit word.}
414 primop   ClzOp     "clz#"   Monadic   Word# -> Word#
415     {Count leading zeros in a word.}
416
417 primop   Ctz8Op   "ctz8#"  Monadic   Word# -> Word#
418     {Count trailing zeros in the lower 8 bits of a word.}
419 primop   Ctz16Op   "ctz16#" Monadic   Word# -> Word#
420     {Count trailing zeros in the lower 16 bits of a word.}
421 primop   Ctz32Op   "ctz32#" Monadic   Word# -> Word#
422     {Count trailing zeros in the lower 32 bits of a word.}
423 primop   Ctz64Op   "ctz64#" GenPrimOp WORD64 -> Word#
424     {Count trailing zeros in a 64-bit word.}
425 primop   CtzOp     "ctz#"   Monadic   Word# -> Word#
426     {Count trailing zeros in a word.}
427
428 primop   BSwap16Op   "byteSwap16#"   Monadic   Word# -> Word#
429     {Swap bytes in the lower 16 bits of a word. The higher bytes are undefined. }
430 primop   BSwap32Op   "byteSwap32#"   Monadic   Word# -> Word#
431     {Swap bytes in the lower 32 bits of a word. The higher bytes are undefined. }
432 primop   BSwap64Op   "byteSwap64#"   Monadic   WORD64 -> WORD64
433     {Swap bytes in a 64 bits of a word.}
434 primop   BSwapOp     "byteSwap#"     Monadic   Word# -> Word#
435     {Swap bytes in a word.}
436
437 ------------------------------------------------------------------------
438 section "Narrowings"
439         {Explicit narrowing of native-sized ints or words.}
440 ------------------------------------------------------------------------
441
442 primop   Narrow8IntOp      "narrow8Int#"      Monadic   Int# -> Int#
443 primop   Narrow16IntOp     "narrow16Int#"     Monadic   Int# -> Int#
444 primop   Narrow32IntOp     "narrow32Int#"     Monadic   Int# -> Int#
445 primop   Narrow8WordOp     "narrow8Word#"     Monadic   Word# -> Word#
446 primop   Narrow16WordOp    "narrow16Word#"    Monadic   Word# -> Word#
447 primop   Narrow32WordOp    "narrow32Word#"    Monadic   Word# -> Word#
448
449
450 #if WORD_SIZE_IN_BITS < 32
451 ------------------------------------------------------------------------
452 section "Int32#"
453         {Operations on 32-bit integers ({\tt Int32\#}).  This type is only used
454          if plain {\tt Int\#} has less than 32 bits.  In any case, the operations
455          are not primops; they are implemented (if needed) as ccalls instead.}
456 ------------------------------------------------------------------------
457
458 primtype Int32#
459
460 ------------------------------------------------------------------------
461 section "Word32#"
462         {Operations on 32-bit unsigned words. This type is only used
463          if plain {\tt Word\#} has less than 32 bits. In any case, the operations
464          are not primops; they are implemented (if needed) as ccalls instead.}
465 ------------------------------------------------------------------------
466
467 primtype Word32#
468
469 #endif
470
471
472 #if WORD_SIZE_IN_BITS < 64
473 ------------------------------------------------------------------------
474 section "Int64#"
475         {Operations on 64-bit unsigned words. This type is only used
476          if plain {\tt Int\#} has less than 64 bits. In any case, the operations
477          are not primops; they are implemented (if needed) as ccalls instead.}
478 ------------------------------------------------------------------------
479
480 primtype Int64#
481
482 ------------------------------------------------------------------------
483 section "Word64#"
484         {Operations on 64-bit unsigned words. This type is only used
485          if plain {\tt Word\#} has less than 64 bits. In any case, the operations
486          are not primops; they are implemented (if needed) as ccalls instead.}
487 ------------------------------------------------------------------------
488
489 primtype Word64#
490
491 #endif
492
493 ------------------------------------------------------------------------
494 section "Double#"
495         {Operations on double-precision (64 bit) floating-point numbers.}
496 ------------------------------------------------------------------------
497
498 primtype Double#
499
500 primop   DoubleGtOp ">##"   Compare   Double# -> Double# -> Int#
501    with fixity = infix 4
502
503 primop   DoubleGeOp ">=##"   Compare   Double# -> Double# -> Int#
504    with fixity = infix 4
505
506 primop DoubleEqOp "==##"   Compare
507    Double# -> Double# -> Int#
508    with commutable = True
509         fixity = infix 4
510
511 primop DoubleNeOp "/=##"   Compare
512    Double# -> Double# -> Int#
513    with commutable = True
514         fixity = infix 4
515
516 primop   DoubleLtOp "<##"   Compare   Double# -> Double# -> Int#
517    with fixity = infix 4
518
519 primop   DoubleLeOp "<=##"   Compare   Double# -> Double# -> Int#
520    with fixity = infix 4
521
522 primop   DoubleAddOp   "+##"   Dyadic
523    Double# -> Double# -> Double#
524    with commutable = True
525         fixity = infixl 6
526
527 primop   DoubleSubOp   "-##"   Dyadic   Double# -> Double# -> Double#
528    with fixity = infixl 6
529
530 primop   DoubleMulOp   "*##"   Dyadic
531    Double# -> Double# -> Double#
532    with commutable = True
533         fixity = infixl 7
534
535 primop   DoubleDivOp   "/##"   Dyadic
536    Double# -> Double# -> Double#
537    with can_fail = True
538         fixity = infixl 7
539
540 primop   DoubleNegOp   "negateDouble#"  Monadic   Double# -> Double#
541
542 primop   DoubleFabsOp  "fabsDouble#"    Monadic   Double# -> Double#
543
544 primop   Double2IntOp   "double2Int#"          GenPrimOp  Double# -> Int#
545    {Truncates a {\tt Double#} value to the nearest {\tt Int#}.
546     Results are undefined if the truncation if truncation yields
547     a value outside the range of {\tt Int#}.}
548
549 primop   Double2FloatOp   "double2Float#" GenPrimOp Double# -> Float#
550
551 primop   DoubleExpOp   "expDouble#"      Monadic
552    Double# -> Double#
553    with
554    code_size = { primOpCodeSizeForeignCall }
555
556 primop   DoubleLogOp   "logDouble#"      Monadic
557    Double# -> Double#
558    with
559    code_size = { primOpCodeSizeForeignCall }
560    can_fail = True
561
562 primop   DoubleSqrtOp   "sqrtDouble#"      Monadic
563    Double# -> Double#
564    with
565    code_size = { primOpCodeSizeForeignCall }
566
567 primop   DoubleSinOp   "sinDouble#"      Monadic
568    Double# -> Double#
569    with
570    code_size = { primOpCodeSizeForeignCall }
571
572 primop   DoubleCosOp   "cosDouble#"      Monadic
573    Double# -> Double#
574    with
575    code_size = { primOpCodeSizeForeignCall }
576
577 primop   DoubleTanOp   "tanDouble#"      Monadic
578    Double# -> Double#
579    with
580    code_size = { primOpCodeSizeForeignCall }
581
582 primop   DoubleAsinOp   "asinDouble#"      Monadic
583    Double# -> Double#
584    with
585    code_size = { primOpCodeSizeForeignCall }
586    can_fail = True
587
588 primop   DoubleAcosOp   "acosDouble#"      Monadic
589    Double# -> Double#
590    with
591    code_size = { primOpCodeSizeForeignCall }
592    can_fail = True
593
594 primop   DoubleAtanOp   "atanDouble#"      Monadic
595    Double# -> Double#
596    with
597    code_size = { primOpCodeSizeForeignCall }
598
599 primop   DoubleSinhOp   "sinhDouble#"      Monadic
600    Double# -> Double#
601    with
602    code_size = { primOpCodeSizeForeignCall }
603
604 primop   DoubleCoshOp   "coshDouble#"      Monadic
605    Double# -> Double#
606    with
607    code_size = { primOpCodeSizeForeignCall }
608
609 primop   DoubleTanhOp   "tanhDouble#"      Monadic
610    Double# -> Double#
611    with
612    code_size = { primOpCodeSizeForeignCall }
613
614 primop   DoublePowerOp   "**##" Dyadic
615    Double# -> Double# -> Double#
616    {Exponentiation.}
617    with
618    code_size = { primOpCodeSizeForeignCall }
619
620 primop   DoubleDecode_2IntOp   "decodeDouble_2Int#" GenPrimOp
621    Double# -> (# Int#, Word#, Word#, Int# #)
622    {Convert to integer.
623     First component of the result is -1 or 1, indicating the sign of the
624     mantissa. The next two are the high and low 32 bits of the mantissa
625     respectively, and the last is the exponent.}
626    with out_of_line = True
627
628 primop   DoubleDecode_Int64Op   "decodeDouble_Int64#" GenPrimOp
629    Double# -> (# INT64, Int# #)
630    {Decode {\tt Double\#} into mantissa and base-2 exponent.}
631    with out_of_line = True
632
633 ------------------------------------------------------------------------
634 section "Float#"
635         {Operations on single-precision (32-bit) floating-point numbers.}
636 ------------------------------------------------------------------------
637
638 primtype Float#
639
640 primop   FloatGtOp  "gtFloat#"   Compare   Float# -> Float# -> Int#
641 primop   FloatGeOp  "geFloat#"   Compare   Float# -> Float# -> Int#
642
643 primop   FloatEqOp  "eqFloat#"   Compare
644    Float# -> Float# -> Int#
645    with commutable = True
646
647 primop   FloatNeOp  "neFloat#"   Compare
648    Float# -> Float# -> Int#
649    with commutable = True
650
651 primop   FloatLtOp  "ltFloat#"   Compare   Float# -> Float# -> Int#
652 primop   FloatLeOp  "leFloat#"   Compare   Float# -> Float# -> Int#
653
654 primop   FloatAddOp   "plusFloat#"      Dyadic
655    Float# -> Float# -> Float#
656    with commutable = True
657
658 primop   FloatSubOp   "minusFloat#"      Dyadic      Float# -> Float# -> Float#
659
660 primop   FloatMulOp   "timesFloat#"      Dyadic
661    Float# -> Float# -> Float#
662    with commutable = True
663
664 primop   FloatDivOp   "divideFloat#"      Dyadic
665    Float# -> Float# -> Float#
666    with can_fail = True
667
668 primop   FloatNegOp   "negateFloat#"      Monadic    Float# -> Float#
669
670 primop   FloatFabsOp  "fabsFloat#"        Monadic    Float# -> Float#
671
672 primop   Float2IntOp   "float2Int#"      GenPrimOp  Float# -> Int#
673    {Truncates a {\tt Float#} value to the nearest {\tt Int#}.
674     Results are undefined if the truncation if truncation yields
675     a value outside the range of {\tt Int#}.}
676
677 primop   FloatExpOp   "expFloat#"      Monadic
678    Float# -> Float#
679    with
680    code_size = { primOpCodeSizeForeignCall }
681
682 primop   FloatLogOp   "logFloat#"      Monadic
683    Float# -> Float#
684    with
685    code_size = { primOpCodeSizeForeignCall }
686    can_fail = True
687
688 primop   FloatSqrtOp   "sqrtFloat#"      Monadic
689    Float# -> Float#
690    with
691    code_size = { primOpCodeSizeForeignCall }
692
693 primop   FloatSinOp   "sinFloat#"      Monadic
694    Float# -> Float#
695    with
696    code_size = { primOpCodeSizeForeignCall }
697
698 primop   FloatCosOp   "cosFloat#"      Monadic
699    Float# -> Float#
700    with
701    code_size = { primOpCodeSizeForeignCall }
702
703 primop   FloatTanOp   "tanFloat#"      Monadic
704    Float# -> Float#
705    with
706    code_size = { primOpCodeSizeForeignCall }
707
708 primop   FloatAsinOp   "asinFloat#"      Monadic
709    Float# -> Float#
710    with
711    code_size = { primOpCodeSizeForeignCall }
712    can_fail = True
713
714 primop   FloatAcosOp   "acosFloat#"      Monadic
715    Float# -> Float#
716    with
717    code_size = { primOpCodeSizeForeignCall }
718    can_fail = True
719
720 primop   FloatAtanOp   "atanFloat#"      Monadic
721    Float# -> Float#
722    with
723    code_size = { primOpCodeSizeForeignCall }
724
725 primop   FloatSinhOp   "sinhFloat#"      Monadic
726    Float# -> Float#
727    with
728    code_size = { primOpCodeSizeForeignCall }
729
730 primop   FloatCoshOp   "coshFloat#"      Monadic
731    Float# -> Float#
732    with
733    code_size = { primOpCodeSizeForeignCall }
734
735 primop   FloatTanhOp   "tanhFloat#"      Monadic
736    Float# -> Float#
737    with
738    code_size = { primOpCodeSizeForeignCall }
739
740 primop   FloatPowerOp   "powerFloat#"      Dyadic
741    Float# -> Float# -> Float#
742    with
743    code_size = { primOpCodeSizeForeignCall }
744
745 primop   Float2DoubleOp   "float2Double#" GenPrimOp  Float# -> Double#
746
747 primop   FloatDecode_IntOp   "decodeFloat_Int#" GenPrimOp
748    Float# -> (# Int#, Int# #)
749    {Convert to integers.
750     First {\tt Int\#} in result is the mantissa; second is the exponent.}
751    with out_of_line = True
752
753 ------------------------------------------------------------------------
754 section "Arrays"
755         {Operations on {\tt Array\#}.}
756 ------------------------------------------------------------------------
757
758 primtype Array# a
759
760 primtype MutableArray# s a
761
762 primop  NewArrayOp "newArray#" GenPrimOp
763    Int# -> a -> State# s -> (# State# s, MutableArray# s a #)
764    {Create a new mutable array with the specified number of elements,
765     in the specified state thread,
766     with each element containing the specified initial value.}
767    with
768    out_of_line = True
769    has_side_effects = True
770
771 primop  SameMutableArrayOp "sameMutableArray#" GenPrimOp
772    MutableArray# s a -> MutableArray# s a -> Int#
773
774 primop  ReadArrayOp "readArray#" GenPrimOp
775    MutableArray# s a -> Int# -> State# s -> (# State# s, a #)
776    {Read from specified index of mutable array. Result is not yet evaluated.}
777    with
778    has_side_effects = True
779    can_fail         = True
780
781 primop  WriteArrayOp "writeArray#" GenPrimOp
782    MutableArray# s a -> Int# -> a -> State# s -> State# s
783    {Write to specified index of mutable array.}
784    with
785    has_side_effects = True
786    can_fail         = True
787    code_size        = 2 -- card update too
788
789 primop  SizeofArrayOp "sizeofArray#" GenPrimOp
790    Array# a -> Int#
791    {Return the number of elements in the array.}
792
793 primop  SizeofMutableArrayOp "sizeofMutableArray#" GenPrimOp
794    MutableArray# s a -> Int#
795    {Return the number of elements in the array.}
796
797 primop  IndexArrayOp "indexArray#" GenPrimOp
798    Array# a -> Int# -> (# a #)
799    {Read from specified index of immutable array. Result is packaged into
800     an unboxed singleton; the result itself is not yet evaluated.}
801    with
802    can_fail         = True
803
804 primop  UnsafeFreezeArrayOp "unsafeFreezeArray#" GenPrimOp
805    MutableArray# s a -> State# s -> (# State# s, Array# a #)
806    {Make a mutable array immutable, without copying.}
807    with
808    has_side_effects = True
809
810 primop  UnsafeThawArrayOp  "unsafeThawArray#" GenPrimOp
811    Array# a -> State# s -> (# State# s, MutableArray# s a #)
812    {Make an immutable array mutable, without copying.}
813    with
814    out_of_line = True
815    has_side_effects = True
816
817 primop  CopyArrayOp "copyArray#" GenPrimOp
818   Array# a -> Int# -> MutableArray# s a -> Int# -> Int# -> State# s -> State# s
819   {Given a source array, an offset into the source array, a
820    destination array, an offset into the destination array, and a
821    number of elements to copy, copy the elements from the source array
822    to the destination array. Both arrays must fully contain the
823    specified ranges, but this is not checked. The two arrays must not
824    be the same array in different states, but this is not checked
825    either.}
826   with
827   out_of_line      = True
828   has_side_effects = True
829   can_fail         = True
830
831 primop  CopyMutableArrayOp "copyMutableArray#" GenPrimOp
832   MutableArray# s a -> Int# -> MutableArray# s a -> Int# -> Int# -> State# s -> State# s
833   {Given a source array, an offset into the source array, a
834    destination array, an offset into the destination array, and a
835    number of elements to copy, copy the elements from the source array
836    to the destination array. Both arrays must fully contain the
837    specified ranges, but this is not checked. In the case where
838    the source and destination are the same array the source and
839    destination regions may overlap.}
840   with
841   out_of_line      = True
842   has_side_effects = True
843   can_fail         = True
844
845 primop  CloneArrayOp "cloneArray#" GenPrimOp
846   Array# a -> Int# -> Int# -> Array# a
847   {Given a source array, an offset into the source array, and a number
848    of elements to copy, create a new array with the elements from the
849    source array. The provided array must fully contain the specified
850    range, but this is not checked.}
851   with
852   out_of_line      = True
853   has_side_effects = True
854   can_fail         = True
855
856 primop  CloneMutableArrayOp "cloneMutableArray#" GenPrimOp
857   MutableArray# s a -> Int# -> Int# -> State# s -> (# State# s, MutableArray# s a #)
858   {Given a source array, an offset into the source array, and a number
859    of elements to copy, create a new array with the elements from the
860    source array. The provided array must fully contain the specified
861    range, but this is not checked.}
862   with
863   out_of_line      = True
864   has_side_effects = True
865   can_fail         = True
866
867 primop  FreezeArrayOp "freezeArray#" GenPrimOp
868   MutableArray# s a -> Int# -> Int# -> State# s -> (# State# s, Array# a #)
869   {Given a source array, an offset into the source array, and a number
870    of elements to copy, create a new array with the elements from the
871    source array. The provided array must fully contain the specified
872    range, but this is not checked.}
873   with
874   out_of_line      = True
875   has_side_effects = True
876   can_fail         = True
877
878 primop  ThawArrayOp "thawArray#" GenPrimOp
879   Array# a -> Int# -> Int# -> State# s -> (# State# s, MutableArray# s a #)
880   {Given a source array, an offset into the source array, and a number
881    of elements to copy, create a new array with the elements from the
882    source array. The provided array must fully contain the specified
883    range, but this is not checked.}
884   with
885   out_of_line      = True
886   has_side_effects = True
887   can_fail         = True
888
889 primop CasArrayOp  "casArray#" GenPrimOp
890    MutableArray# s a -> Int# -> a -> a -> State# s -> (# State# s, Int#, a #)
891    {Unsafe, machine-level atomic compare and swap on an element within an Array.}
892    with
893    out_of_line = True
894    has_side_effects = True
895
896
897 ------------------------------------------------------------------------
898 section "Small Arrays"
899
900         {Operations on {\tt SmallArray\#}. A {\tt SmallArray\#} works
901          just like an {\tt Array\#}, but with different space use and
902          performance characteristics (that are often useful with small
903          arrays). The {\tt SmallArray\#} and {\tt SmallMutableArray#}
904          lack a `card table'. The purpose of a card table is to avoid
905          having to scan every element of the array on each GC by
906          keeping track of which elements have changed since the last GC
907          and only scanning those that have changed. So the consequence
908          of there being no card table is that the representation is
909          somewhat smaller and the writes are somewhat faster (because
910          the card table does not need to be updated). The disadvantage
911          of course is that for a {\tt SmallMutableArray#} the whole
912          array has to be scanned on each GC. Thus it is best suited for
913          use cases where the mutable array is not long lived, e.g.
914          where a mutable array is initialised quickly and then frozen
915          to become an immutable {\tt SmallArray\#}.
916         }
917
918 ------------------------------------------------------------------------
919
920 primtype SmallArray# a
921
922 primtype SmallMutableArray# s a
923
924 primop  NewSmallArrayOp "newSmallArray#" GenPrimOp
925    Int# -> a -> State# s -> (# State# s, SmallMutableArray# s a #)
926    {Create a new mutable array with the specified number of elements,
927     in the specified state thread,
928     with each element containing the specified initial value.}
929    with
930    out_of_line = True
931    has_side_effects = True
932
933 primop  SameSmallMutableArrayOp "sameSmallMutableArray#" GenPrimOp
934    SmallMutableArray# s a -> SmallMutableArray# s a -> Int#
935
936 primop  ReadSmallArrayOp "readSmallArray#" GenPrimOp
937    SmallMutableArray# s a -> Int# -> State# s -> (# State# s, a #)
938    {Read from specified index of mutable array. Result is not yet evaluated.}
939    with
940    has_side_effects = True
941    can_fail         = True
942
943 primop  WriteSmallArrayOp "writeSmallArray#" GenPrimOp
944    SmallMutableArray# s a -> Int# -> a -> State# s -> State# s
945    {Write to specified index of mutable array.}
946    with
947    has_side_effects = True
948    can_fail         = True
949
950 primop  SizeofSmallArrayOp "sizeofSmallArray#" GenPrimOp
951    SmallArray# a -> Int#
952    {Return the number of elements in the array.}
953
954 primop  SizeofSmallMutableArrayOp "sizeofSmallMutableArray#" GenPrimOp
955    SmallMutableArray# s a -> Int#
956    {Return the number of elements in the array.}
957
958 primop  IndexSmallArrayOp "indexSmallArray#" GenPrimOp
959    SmallArray# a -> Int# -> (# a #)
960    {Read from specified index of immutable array. Result is packaged into
961     an unboxed singleton; the result itself is not yet evaluated.}
962    with
963    can_fail         = True
964
965 primop  UnsafeFreezeSmallArrayOp "unsafeFreezeSmallArray#" GenPrimOp
966    SmallMutableArray# s a -> State# s -> (# State# s, SmallArray# a #)
967    {Make a mutable array immutable, without copying.}
968    with
969    has_side_effects = True
970
971 primop  UnsafeThawSmallArrayOp  "unsafeThawSmallArray#" GenPrimOp
972    SmallArray# a -> State# s -> (# State# s, SmallMutableArray# s a #)
973    {Make an immutable array mutable, without copying.}
974    with
975    out_of_line = True
976    has_side_effects = True
977
978 -- The code_size is only correct for the case when the copy family of
979 -- primops aren't inlined. It would be nice to keep track of both.
980
981 primop  CopySmallArrayOp "copySmallArray#" GenPrimOp
982   SmallArray# a -> Int# -> SmallMutableArray# s a -> Int# -> Int# -> State# s -> State# s
983   {Given a source array, an offset into the source array, a
984    destination array, an offset into the destination array, and a
985    number of elements to copy, copy the elements from the source array
986    to the destination array. Both arrays must fully contain the
987    specified ranges, but this is not checked. The two arrays must not
988    be the same array in different states, but this is not checked
989    either.}
990   with
991   out_of_line      = True
992   has_side_effects = True
993   can_fail         = True
994
995 primop  CopySmallMutableArrayOp "copySmallMutableArray#" GenPrimOp
996   SmallMutableArray# s a -> Int# -> SmallMutableArray# s a -> Int# -> Int# -> State# s -> State# s
997   {Given a source array, an offset into the source array, a
998    destination array, an offset into the destination array, and a
999    number of elements to copy, copy the elements from the source array
1000    to the destination array. The source and destination arrays can
1001    refer to the same array. Both arrays must fully contain the
1002    specified ranges, but this is not checked.
1003    The regions are allowed to overlap, although this is only possible when the same 
1004    array is provided as both the source and the destination. }
1005   with
1006   out_of_line      = True
1007   has_side_effects = True
1008   can_fail         = True
1009
1010 primop  CloneSmallArrayOp "cloneSmallArray#" GenPrimOp
1011   SmallArray# a -> Int# -> Int# -> SmallArray# a
1012   {Given a source array, an offset into the source array, and a number
1013    of elements to copy, create a new array with the elements from the
1014    source array. The provided array must fully contain the specified
1015    range, but this is not checked.}
1016   with
1017   out_of_line      = True
1018   has_side_effects = True
1019   can_fail         = True
1020
1021 primop  CloneSmallMutableArrayOp "cloneSmallMutableArray#" GenPrimOp
1022   SmallMutableArray# s a -> Int# -> Int# -> State# s -> (# State# s, SmallMutableArray# s a #)
1023   {Given a source array, an offset into the source array, and a number
1024    of elements to copy, create a new array with the elements from the
1025    source array. The provided array must fully contain the specified
1026    range, but this is not checked.}
1027   with
1028   out_of_line      = True
1029   has_side_effects = True
1030   can_fail         = True
1031
1032 primop  FreezeSmallArrayOp "freezeSmallArray#" GenPrimOp
1033   SmallMutableArray# s a -> Int# -> Int# -> State# s -> (# State# s, SmallArray# a #)
1034   {Given a source array, an offset into the source array, and a number
1035    of elements to copy, create a new array with the elements from the
1036    source array. The provided array must fully contain the specified
1037    range, but this is not checked.}
1038   with
1039   out_of_line      = True
1040   has_side_effects = True
1041   can_fail         = True
1042
1043 primop  ThawSmallArrayOp "thawSmallArray#" GenPrimOp
1044   SmallArray# a -> Int# -> Int# -> State# s -> (# State# s, SmallMutableArray# s a #)
1045   {Given a source array, an offset into the source array, and a number
1046    of elements to copy, create a new array with the elements from the
1047    source array. The provided array must fully contain the specified
1048    range, but this is not checked.}
1049   with
1050   out_of_line      = True
1051   has_side_effects = True
1052   can_fail         = True
1053
1054 primop CasSmallArrayOp  "casSmallArray#" GenPrimOp
1055    SmallMutableArray# s a -> Int# -> a -> a -> State# s -> (# State# s, Int#, a #)
1056    {Unsafe, machine-level atomic compare and swap on an element within an array.}
1057    with
1058    out_of_line = True
1059    has_side_effects = True
1060
1061 ------------------------------------------------------------------------
1062 section "Byte Arrays"
1063         {Operations on {\tt ByteArray\#}. A {\tt ByteArray\#} is a just a region of
1064          raw memory in the garbage-collected heap, which is not
1065          scanned for pointers. It carries its own size (in bytes).
1066          There are
1067          three sets of operations for accessing byte array contents:
1068          index for reading from immutable byte arrays, and read/write
1069          for mutable byte arrays.  Each set contains operations for a
1070          range of useful primitive data types.  Each operation takes
1071          an offset measured in terms of the size of the primitive type
1072          being read or written.}
1073
1074 ------------------------------------------------------------------------
1075
1076 primtype ByteArray#
1077
1078 primtype MutableByteArray# s
1079
1080 primop  NewByteArrayOp_Char "newByteArray#" GenPrimOp
1081    Int# -> State# s -> (# State# s, MutableByteArray# s #)
1082    {Create a new mutable byte array of specified size (in bytes), in
1083     the specified state thread.}
1084    with out_of_line = True
1085         has_side_effects = True
1086
1087 primop  NewPinnedByteArrayOp_Char "newPinnedByteArray#" GenPrimOp
1088    Int# -> State# s -> (# State# s, MutableByteArray# s #)
1089    {Create a mutable byte array that the GC guarantees not to move.}
1090    with out_of_line = True
1091         has_side_effects = True
1092
1093 primop  NewAlignedPinnedByteArrayOp_Char "newAlignedPinnedByteArray#" GenPrimOp
1094    Int# -> Int# -> State# s -> (# State# s, MutableByteArray# s #)
1095    {Create a mutable byte array, aligned by the specified amount, that the GC guarantees not to move.}
1096    with out_of_line = True
1097         has_side_effects = True
1098
1099 primop  MutableByteArrayIsPinnedOp "isMutableByteArrayPinned#" GenPrimOp
1100    MutableByteArray# s -> Int#
1101    {Determine whether a {\tt MutableByteArray\#} is guaranteed not to move
1102    during GC.}
1103    with out_of_line = True
1104
1105 primop  ByteArrayIsPinnedOp "isByteArrayPinned#" GenPrimOp
1106    ByteArray# -> Int#
1107    {Determine whether a {\tt ByteArray\#} is guaranteed not to move during GC.}
1108    with out_of_line = True
1109
1110 primop  ByteArrayContents_Char "byteArrayContents#" GenPrimOp
1111    ByteArray# -> Addr#
1112    {Intended for use with pinned arrays; otherwise very unsafe!}
1113
1114 primop  SameMutableByteArrayOp "sameMutableByteArray#" GenPrimOp
1115    MutableByteArray# s -> MutableByteArray# s -> Int#
1116
1117 primop  ShrinkMutableByteArrayOp_Char "shrinkMutableByteArray#" GenPrimOp
1118    MutableByteArray# s -> Int# -> State# s -> State# s
1119    {Shrink mutable byte array to new specified size (in bytes), in
1120     the specified state thread. The new size argument must be less than or
1121     equal to the current size as reported by {\tt sizeofMutableArray\#}.}
1122    with out_of_line = True
1123         has_side_effects = True
1124
1125 primop  ResizeMutableByteArrayOp_Char "resizeMutableByteArray#" GenPrimOp
1126    MutableByteArray# s -> Int# -> State# s -> (# State# s,MutableByteArray# s #)
1127    {Resize (unpinned) mutable byte array to new specified size (in bytes).
1128     The returned {\tt MutableByteArray\#} is either the original
1129     {\tt MutableByteArray\#} resized in-place or, if not possible, a newly
1130     allocated (unpinned) {\tt MutableByteArray\#} (with the original content
1131     copied over).
1132
1133     To avoid undefined behaviour, the original {\tt MutableByteArray\#} shall
1134     not be accessed anymore after a {\tt resizeMutableByteArray\#} has been
1135     performed.  Moreover, no reference to the old one should be kept in order
1136     to allow garbage collection of the original {\tt MutableByteArray\#} in
1137     case a new {\tt MutableByteArray\#} had to be allocated.}
1138    with out_of_line = True
1139         has_side_effects = True
1140
1141 primop  UnsafeFreezeByteArrayOp "unsafeFreezeByteArray#" GenPrimOp
1142    MutableByteArray# s -> State# s -> (# State# s, ByteArray# #)
1143    {Make a mutable byte array immutable, without copying.}
1144    with
1145    has_side_effects = True
1146
1147 primop  SizeofByteArrayOp "sizeofByteArray#" GenPrimOp
1148    ByteArray# -> Int#
1149    {Return the size of the array in bytes.}
1150
1151 primop  SizeofMutableByteArrayOp "sizeofMutableByteArray#" GenPrimOp
1152    MutableByteArray# s -> Int#
1153    {Return the size of the array in bytes. Note that this is deprecated as it is
1154    unsafe in the presence of concurrent resize operations on the same byte
1155    array. See {\tt getSizeofMutableByteArray}.}
1156
1157 primop  GetSizeofMutableByteArrayOp "getSizeofMutableByteArray#" GenPrimOp
1158    MutableByteArray# s -> State# s -> (# State# s, Int# #)
1159    {Return the number of elements in the array.}
1160
1161 primop IndexByteArrayOp_Char "indexCharArray#" GenPrimOp
1162    ByteArray# -> Int# -> Char#
1163    {Read 8-bit character; offset in bytes.}
1164    with can_fail = True
1165
1166 primop IndexByteArrayOp_WideChar "indexWideCharArray#" GenPrimOp
1167    ByteArray# -> Int# -> Char#
1168    {Read 31-bit character; offset in 4-byte words.}
1169    with can_fail = True
1170
1171 primop IndexByteArrayOp_Int "indexIntArray#" GenPrimOp
1172    ByteArray# -> Int# -> Int#
1173    with can_fail = True
1174
1175 primop IndexByteArrayOp_Word "indexWordArray#" GenPrimOp
1176    ByteArray# -> Int# -> Word#
1177    with can_fail = True
1178
1179 primop IndexByteArrayOp_Addr "indexAddrArray#" GenPrimOp
1180    ByteArray# -> Int# -> Addr#
1181    with can_fail = True
1182
1183 primop IndexByteArrayOp_Float "indexFloatArray#" GenPrimOp
1184    ByteArray# -> Int# -> Float#
1185    with can_fail = True
1186
1187 primop IndexByteArrayOp_Double "indexDoubleArray#" GenPrimOp
1188    ByteArray# -> Int# -> Double#
1189    with can_fail = True
1190
1191 primop IndexByteArrayOp_StablePtr "indexStablePtrArray#" GenPrimOp
1192    ByteArray# -> Int# -> StablePtr# a
1193    with can_fail = True
1194
1195 primop IndexByteArrayOp_Int8 "indexInt8Array#" GenPrimOp
1196    ByteArray# -> Int# -> Int#
1197    {Read 8-bit integer; offset in bytes.}
1198    with can_fail = True
1199
1200 primop IndexByteArrayOp_Int16 "indexInt16Array#" GenPrimOp
1201    ByteArray# -> Int# -> Int#
1202    {Read 16-bit integer; offset in 16-bit words.}
1203    with can_fail = True
1204
1205 primop IndexByteArrayOp_Int32 "indexInt32Array#" GenPrimOp
1206    ByteArray# -> Int# -> INT32
1207    {Read 32-bit integer; offset in 32-bit words.}
1208    with can_fail = True
1209
1210 primop IndexByteArrayOp_Int64 "indexInt64Array#" GenPrimOp
1211    ByteArray# -> Int# -> INT64
1212    {Read 64-bit integer; offset in 64-bit words.}
1213    with can_fail = True
1214
1215 primop IndexByteArrayOp_Word8 "indexWord8Array#" GenPrimOp
1216    ByteArray# -> Int# -> Word#
1217    {Read 8-bit word; offset in bytes.}
1218    with can_fail = True
1219
1220 primop IndexByteArrayOp_Word16 "indexWord16Array#" GenPrimOp
1221    ByteArray# -> Int# -> Word#
1222    {Read 16-bit word; offset in 16-bit words.}
1223    with can_fail = True
1224
1225 primop IndexByteArrayOp_Word32 "indexWord32Array#" GenPrimOp
1226    ByteArray# -> Int# -> WORD32
1227    {Read 32-bit word; offset in 32-bit words.}
1228    with can_fail = True
1229
1230 primop IndexByteArrayOp_Word64 "indexWord64Array#" GenPrimOp
1231    ByteArray# -> Int# -> WORD64
1232    {Read 64-bit word; offset in 64-bit words.}
1233    with can_fail = True
1234
1235 primop  ReadByteArrayOp_Char "readCharArray#" GenPrimOp
1236    MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
1237    {Read 8-bit character; offset in bytes.}
1238    with has_side_effects = True
1239         can_fail = True
1240
1241 primop  ReadByteArrayOp_WideChar "readWideCharArray#" GenPrimOp
1242    MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
1243    {Read 31-bit character; offset in 4-byte words.}
1244    with has_side_effects = True
1245         can_fail = True
1246
1247 primop  ReadByteArrayOp_Int "readIntArray#" GenPrimOp
1248    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
1249    {Read integer; offset in words.}
1250    with has_side_effects = True
1251         can_fail = True
1252
1253 primop  ReadByteArrayOp_Word "readWordArray#" GenPrimOp
1254    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
1255    {Read word; offset in words.}
1256    with has_side_effects = True
1257         can_fail = True
1258
1259 primop  ReadByteArrayOp_Addr "readAddrArray#" GenPrimOp
1260    MutableByteArray# s -> Int# -> State# s -> (# State# s, Addr# #)
1261    with has_side_effects = True
1262         can_fail = True
1263
1264 primop  ReadByteArrayOp_Float "readFloatArray#" GenPrimOp
1265    MutableByteArray# s -> Int# -> State# s -> (# State# s, Float# #)
1266    with has_side_effects = True
1267         can_fail = True
1268
1269 primop  ReadByteArrayOp_Double "readDoubleArray#" GenPrimOp
1270    MutableByteArray# s -> Int# -> State# s -> (# State# s, Double# #)
1271    with has_side_effects = True
1272         can_fail = True
1273
1274 primop  ReadByteArrayOp_StablePtr "readStablePtrArray#" GenPrimOp
1275    MutableByteArray# s -> Int# -> State# s -> (# State# s, StablePtr# a #)
1276    with has_side_effects = True
1277         can_fail = True
1278
1279 primop  ReadByteArrayOp_Int8 "readInt8Array#" GenPrimOp
1280    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
1281    with has_side_effects = True
1282         can_fail = True
1283
1284 primop  ReadByteArrayOp_Int16 "readInt16Array#" GenPrimOp
1285    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
1286    with has_side_effects = True
1287         can_fail = True
1288
1289 primop  ReadByteArrayOp_Int32 "readInt32Array#" GenPrimOp
1290    MutableByteArray# s -> Int# -> State# s -> (# State# s, INT32 #)
1291    with has_side_effects = True
1292         can_fail = True
1293
1294 primop  ReadByteArrayOp_Int64 "readInt64Array#" GenPrimOp
1295    MutableByteArray# s -> Int# -> State# s -> (# State# s, INT64 #)
1296    with has_side_effects = True
1297         can_fail = True
1298
1299 primop  ReadByteArrayOp_Word8 "readWord8Array#" GenPrimOp
1300    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
1301    with has_side_effects = True
1302         can_fail = True
1303
1304 primop  ReadByteArrayOp_Word16 "readWord16Array#" GenPrimOp
1305    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
1306    with has_side_effects = True
1307         can_fail = True
1308
1309 primop  ReadByteArrayOp_Word32 "readWord32Array#" GenPrimOp
1310    MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD32 #)
1311    with has_side_effects = True
1312         can_fail = True
1313
1314 primop  ReadByteArrayOp_Word64 "readWord64Array#" GenPrimOp
1315    MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD64 #)
1316    with has_side_effects = True
1317         can_fail = True
1318
1319 primop  WriteByteArrayOp_Char "writeCharArray#" GenPrimOp
1320    MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
1321    {Write 8-bit character; offset in bytes.}
1322    with has_side_effects = True
1323         can_fail = True
1324
1325 primop  WriteByteArrayOp_WideChar "writeWideCharArray#" GenPrimOp
1326    MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
1327    {Write 31-bit character; offset in 4-byte words.}
1328    with has_side_effects = True
1329         can_fail = True
1330
1331 primop  WriteByteArrayOp_Int "writeIntArray#" GenPrimOp
1332    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1333    with has_side_effects = True
1334         can_fail = True
1335
1336 primop  WriteByteArrayOp_Word "writeWordArray#" GenPrimOp
1337    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
1338    with has_side_effects = True
1339         can_fail = True
1340
1341 primop  WriteByteArrayOp_Addr "writeAddrArray#" GenPrimOp
1342    MutableByteArray# s -> Int# -> Addr# -> State# s -> State# s
1343    with has_side_effects = True
1344         can_fail = True
1345
1346 primop  WriteByteArrayOp_Float "writeFloatArray#" GenPrimOp
1347    MutableByteArray# s -> Int# -> Float# -> State# s -> State# s
1348    with has_side_effects = True
1349         can_fail = True
1350
1351 primop  WriteByteArrayOp_Double "writeDoubleArray#" GenPrimOp
1352    MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
1353    with has_side_effects = True
1354         can_fail = True
1355
1356 primop  WriteByteArrayOp_StablePtr "writeStablePtrArray#" GenPrimOp
1357    MutableByteArray# s -> Int# -> StablePtr# a -> State# s -> State# s
1358    with has_side_effects = True
1359         can_fail = True
1360
1361 primop  WriteByteArrayOp_Int8 "writeInt8Array#" GenPrimOp
1362    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1363    with has_side_effects = True
1364         can_fail = True
1365
1366 primop  WriteByteArrayOp_Int16 "writeInt16Array#" GenPrimOp
1367    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1368    with has_side_effects = True
1369         can_fail = True
1370
1371 primop  WriteByteArrayOp_Int32 "writeInt32Array#" GenPrimOp
1372    MutableByteArray# s -> Int# -> INT32 -> State# s -> State# s
1373    with has_side_effects = True
1374         can_fail = True
1375
1376 primop  WriteByteArrayOp_Int64 "writeInt64Array#" GenPrimOp
1377    MutableByteArray# s -> Int# -> INT64 -> State# s -> State# s
1378    with can_fail = True
1379         has_side_effects = True
1380
1381 primop  WriteByteArrayOp_Word8 "writeWord8Array#" GenPrimOp
1382    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
1383    with has_side_effects = True
1384         can_fail = True
1385
1386 primop  WriteByteArrayOp_Word16 "writeWord16Array#" GenPrimOp
1387    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
1388    with has_side_effects = True
1389         can_fail = True
1390
1391 primop  WriteByteArrayOp_Word32 "writeWord32Array#" GenPrimOp
1392    MutableByteArray# s -> Int# -> WORD32 -> State# s -> State# s
1393    with has_side_effects = True
1394         can_fail = True
1395
1396 primop  WriteByteArrayOp_Word64 "writeWord64Array#" GenPrimOp
1397    MutableByteArray# s -> Int# -> WORD64 -> State# s -> State# s
1398    with has_side_effects = True
1399         can_fail = True
1400
1401 primop  CopyByteArrayOp "copyByteArray#" GenPrimOp
1402   ByteArray# -> Int# -> MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1403   {Copy a range of the ByteArray# to the specified region in the MutableByteArray#.
1404    Both arrays must fully contain the specified ranges, but this is not checked.
1405    The two arrays must not be the same array in different states, but this is not checked either.}
1406   with
1407   has_side_effects = True
1408   code_size = { primOpCodeSizeForeignCall + 4}
1409   can_fail = True
1410
1411 primop  CopyMutableByteArrayOp "copyMutableByteArray#" GenPrimOp
1412   MutableByteArray# s -> Int# -> MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1413   {Copy a range of the first MutableByteArray# to the specified region in the second MutableByteArray#.
1414    Both arrays must fully contain the specified ranges, but this is not checked. The regions are
1415    allowed to overlap, although this is only possible when the same array is provided
1416    as both the source and the destination.}
1417   with
1418   has_side_effects = True
1419   code_size = { primOpCodeSizeForeignCall + 4 }
1420   can_fail = True
1421
1422 primop  CopyByteArrayToAddrOp "copyByteArrayToAddr#" GenPrimOp
1423   ByteArray# -> Int# -> Addr# -> Int# -> State# s -> State# s
1424   {Copy a range of the ByteArray# to the memory range starting at the Addr#.
1425    The ByteArray# and the memory region at Addr# must fully contain the
1426    specified ranges, but this is not checked. The Addr# must not point into the
1427    ByteArray# (e.g. if the ByteArray# were pinned), but this is not checked
1428    either.}
1429   with
1430   has_side_effects = True
1431   code_size = { primOpCodeSizeForeignCall + 4}
1432   can_fail = True
1433
1434 primop  CopyMutableByteArrayToAddrOp "copyMutableByteArrayToAddr#" GenPrimOp
1435   MutableByteArray# s -> Int# -> Addr# -> Int# -> State# s -> State# s
1436   {Copy a range of the MutableByteArray# to the memory range starting at the
1437    Addr#. The MutableByteArray# and the memory region at Addr# must fully
1438    contain the specified ranges, but this is not checked. The Addr# must not
1439    point into the MutableByteArray# (e.g. if the MutableByteArray# were
1440    pinned), but this is not checked either.}
1441   with
1442   has_side_effects = True
1443   code_size = { primOpCodeSizeForeignCall + 4}
1444   can_fail = True
1445
1446 primop  CopyAddrToByteArrayOp "copyAddrToByteArray#" GenPrimOp
1447   Addr# -> MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1448   {Copy a memory range starting at the Addr# to the specified range in the
1449    MutableByteArray#. The memory region at Addr# and the ByteArray# must fully
1450    contain the specified ranges, but this is not checked. The Addr# must not
1451    point into the MutableByteArray# (e.g. if the MutableByteArray# were pinned),
1452    but this is not checked either.}
1453   with
1454   has_side_effects = True
1455   code_size = { primOpCodeSizeForeignCall + 4}
1456   can_fail = True
1457
1458 primop  SetByteArrayOp "setByteArray#" GenPrimOp
1459   MutableByteArray# s -> Int# -> Int# -> Int# -> State# s -> State# s
1460   {{\tt setByteArray# ba off len c} sets the byte range {\tt [off, off+len]} of
1461    the {\tt MutableByteArray#} to the byte {\tt c}.}
1462   with
1463   has_side_effects = True
1464   code_size = { primOpCodeSizeForeignCall + 4 }
1465   can_fail = True
1466
1467 -- Atomic operations
1468
1469 primop  AtomicReadByteArrayOp_Int "atomicReadIntArray#" GenPrimOp
1470    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
1471    {Given an array and an offset in Int units, read an element. The
1472     index is assumed to be in bounds. Implies a full memory barrier.}
1473    with has_side_effects = True
1474         can_fail = True
1475
1476 primop  AtomicWriteByteArrayOp_Int "atomicWriteIntArray#" GenPrimOp
1477    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1478    {Given an array and an offset in Int units, write an element. The
1479     index is assumed to be in bounds. Implies a full memory barrier.}
1480    with has_side_effects = True
1481         can_fail = True
1482
1483 primop CasByteArrayOp_Int "casIntArray#" GenPrimOp
1484    MutableByteArray# s -> Int# -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1485    {Given an array, an offset in Int units, the expected old value, and
1486     the new value, perform an atomic compare and swap i.e. write the new
1487     value if the current value matches the provided old value. Returns
1488     the value of the element before the operation. Implies a full memory
1489     barrier.}
1490    with has_side_effects = True
1491         can_fail = True
1492
1493 primop FetchAddByteArrayOp_Int "fetchAddIntArray#" GenPrimOp
1494    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1495    {Given an array, and offset in Int units, and a value to add,
1496     atomically add the value to the element. Returns the value of the
1497     element before the operation. Implies a full memory barrier.}
1498    with has_side_effects = True
1499         can_fail = True
1500
1501 primop FetchSubByteArrayOp_Int "fetchSubIntArray#" GenPrimOp
1502    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1503    {Given an array, and offset in Int units, and a value to subtract,
1504     atomically substract the value to the element. Returns the value of
1505     the element before the operation. Implies a full memory barrier.}
1506    with has_side_effects = True
1507         can_fail = True
1508
1509 primop FetchAndByteArrayOp_Int "fetchAndIntArray#" GenPrimOp
1510    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1511    {Given an array, and offset in Int units, and a value to AND,
1512     atomically AND the value to the element. Returns the value of the
1513     element before the operation. Implies a full memory barrier.}
1514    with has_side_effects = True
1515         can_fail = True
1516
1517 primop FetchNandByteArrayOp_Int "fetchNandIntArray#" GenPrimOp
1518    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1519    {Given an array, and offset in Int units, and a value to NAND,
1520     atomically NAND the value to the element. Returns the value of the
1521     element before the operation. Implies a full memory barrier.}
1522    with has_side_effects = True
1523         can_fail = True
1524
1525 primop FetchOrByteArrayOp_Int "fetchOrIntArray#" GenPrimOp
1526    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1527    {Given an array, and offset in Int units, and a value to OR,
1528     atomically OR the value to the element. Returns the value of the
1529     element before the operation. Implies a full memory barrier.}
1530    with has_side_effects = True
1531         can_fail = True
1532
1533 primop FetchXorByteArrayOp_Int "fetchXorIntArray#" GenPrimOp
1534    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1535    {Given an array, and offset in Int units, and a value to XOR,
1536     atomically XOR the value to the element. Returns the value of the
1537     element before the operation. Implies a full memory barrier.}
1538    with has_side_effects = True
1539         can_fail = True
1540
1541
1542 ------------------------------------------------------------------------
1543 section "Arrays of arrays"
1544         {Operations on {\tt ArrayArray\#}. An {\tt ArrayArray\#} contains references to {\em unpointed}
1545          arrays, such as {\tt ByteArray\#s}. Hence, it is not parameterised by the element types,
1546          just like a {\tt ByteArray\#}, but it needs to be scanned during GC, just like an {\tt Array#}.
1547          We represent an {\tt ArrayArray\#} exactly as a {\tt Array\#}, but provide element-type-specific
1548          indexing, reading, and writing.}
1549 ------------------------------------------------------------------------
1550
1551 primtype ArrayArray#
1552
1553 primtype MutableArrayArray# s
1554
1555 primop  NewArrayArrayOp "newArrayArray#" GenPrimOp
1556    Int# -> State# s -> (# State# s, MutableArrayArray# s #)
1557    {Create a new mutable array of arrays with the specified number of elements,
1558     in the specified state thread, with each element recursively referring to the
1559     newly created array.}
1560    with
1561    out_of_line = True
1562    has_side_effects = True
1563
1564 primop  SameMutableArrayArrayOp "sameMutableArrayArray#" GenPrimOp
1565    MutableArrayArray# s -> MutableArrayArray# s -> Int#
1566
1567 primop  UnsafeFreezeArrayArrayOp "unsafeFreezeArrayArray#" GenPrimOp
1568    MutableArrayArray# s -> State# s -> (# State# s, ArrayArray# #)
1569    {Make a mutable array of arrays immutable, without copying.}
1570    with
1571    has_side_effects = True
1572
1573 primop  SizeofArrayArrayOp "sizeofArrayArray#" GenPrimOp
1574    ArrayArray# -> Int#
1575    {Return the number of elements in the array.}
1576
1577 primop  SizeofMutableArrayArrayOp "sizeofMutableArrayArray#" GenPrimOp
1578    MutableArrayArray# s -> Int#
1579    {Return the number of elements in the array.}
1580
1581 primop IndexArrayArrayOp_ByteArray "indexByteArrayArray#" GenPrimOp
1582    ArrayArray# -> Int# -> ByteArray#
1583    with can_fail = True
1584
1585 primop IndexArrayArrayOp_ArrayArray "indexArrayArrayArray#" GenPrimOp
1586    ArrayArray# -> Int# -> ArrayArray#
1587    with can_fail = True
1588
1589 primop  ReadArrayArrayOp_ByteArray "readByteArrayArray#" GenPrimOp
1590    MutableArrayArray# s -> Int# -> State# s -> (# State# s, ByteArray# #)
1591    with has_side_effects = True
1592         can_fail = True
1593
1594 primop  ReadArrayArrayOp_MutableByteArray "readMutableByteArrayArray#" GenPrimOp
1595    MutableArrayArray# s -> Int# -> State# s -> (# State# s, MutableByteArray# s #)
1596    with has_side_effects = True
1597         can_fail = True
1598
1599 primop  ReadArrayArrayOp_ArrayArray "readArrayArrayArray#" GenPrimOp
1600    MutableArrayArray# s -> Int# -> State# s -> (# State# s, ArrayArray# #)
1601    with has_side_effects = True
1602         can_fail = True
1603
1604 primop  ReadArrayArrayOp_MutableArrayArray "readMutableArrayArrayArray#" GenPrimOp
1605    MutableArrayArray# s -> Int# -> State# s -> (# State# s, MutableArrayArray# s #)
1606    with has_side_effects = True
1607         can_fail = True
1608
1609 primop  WriteArrayArrayOp_ByteArray "writeByteArrayArray#" GenPrimOp
1610    MutableArrayArray# s -> Int# -> ByteArray# -> State# s -> State# s
1611    with has_side_effects = True
1612         can_fail = True
1613
1614 primop  WriteArrayArrayOp_MutableByteArray "writeMutableByteArrayArray#" GenPrimOp
1615    MutableArrayArray# s -> Int# -> MutableByteArray# s -> State# s -> State# s
1616    with has_side_effects = True
1617         can_fail = True
1618
1619 primop  WriteArrayArrayOp_ArrayArray "writeArrayArrayArray#" GenPrimOp
1620    MutableArrayArray# s -> Int# -> ArrayArray# -> State# s -> State# s
1621    with has_side_effects = True
1622         can_fail = True
1623
1624 primop  WriteArrayArrayOp_MutableArrayArray "writeMutableArrayArrayArray#" GenPrimOp
1625    MutableArrayArray# s -> Int# -> MutableArrayArray# s -> State# s -> State# s
1626    with has_side_effects = True
1627         can_fail = True
1628
1629 primop  CopyArrayArrayOp "copyArrayArray#" GenPrimOp
1630   ArrayArray# -> Int# -> MutableArrayArray# s -> Int# -> Int# -> State# s -> State# s
1631   {Copy a range of the ArrayArray# to the specified region in the MutableArrayArray#.
1632    Both arrays must fully contain the specified ranges, but this is not checked.
1633    The two arrays must not be the same array in different states, but this is not checked either.}
1634   with
1635   out_of_line      = True
1636   has_side_effects = True
1637   can_fail         = True
1638
1639 primop  CopyMutableArrayArrayOp "copyMutableArrayArray#" GenPrimOp
1640   MutableArrayArray# s -> Int# -> MutableArrayArray# s -> Int# -> Int# -> State# s -> State# s
1641   {Copy a range of the first MutableArrayArray# to the specified region in the second
1642    MutableArrayArray#.
1643    Both arrays must fully contain the specified ranges, but this is not checked.
1644    The regions are allowed to overlap, although this is only possible when the same 
1645    array is provided as both the source and the destination.
1646    }
1647   with
1648   out_of_line      = True
1649   has_side_effects = True
1650   can_fail         = True
1651
1652 ------------------------------------------------------------------------
1653 section "Addr#"
1654 ------------------------------------------------------------------------
1655
1656 primtype Addr#
1657         { An arbitrary machine address assumed to point outside
1658          the garbage-collected heap. }
1659
1660 pseudoop "nullAddr#" Addr#
1661         { The null address. }
1662
1663 primop   AddrAddOp "plusAddr#" GenPrimOp Addr# -> Int# -> Addr#
1664 primop   AddrSubOp "minusAddr#" GenPrimOp Addr# -> Addr# -> Int#
1665          {Result is meaningless if two {\tt Addr\#}s are so far apart that their
1666          difference doesn't fit in an {\tt Int\#}.}
1667 primop   AddrRemOp "remAddr#" GenPrimOp Addr# -> Int# -> Int#
1668          {Return the remainder when the {\tt Addr\#} arg, treated like an {\tt Int\#},
1669           is divided by the {\tt Int\#} arg.}
1670 #if (WORD_SIZE_IN_BITS == 32 || WORD_SIZE_IN_BITS == 64)
1671 primop   Addr2IntOp  "addr2Int#"     GenPrimOp   Addr# -> Int#
1672         {Coerce directly from address to int. Strongly deprecated.}
1673    with code_size = 0
1674 primop   Int2AddrOp   "int2Addr#"    GenPrimOp  Int# -> Addr#
1675         {Coerce directly from int to address. Strongly deprecated.}
1676    with code_size = 0
1677 #endif
1678
1679 primop   AddrGtOp  "gtAddr#"   Compare   Addr# -> Addr# -> Int#
1680 primop   AddrGeOp  "geAddr#"   Compare   Addr# -> Addr# -> Int#
1681 primop   AddrEqOp  "eqAddr#"   Compare   Addr# -> Addr# -> Int#
1682 primop   AddrNeOp  "neAddr#"   Compare   Addr# -> Addr# -> Int#
1683 primop   AddrLtOp  "ltAddr#"   Compare   Addr# -> Addr# -> Int#
1684 primop   AddrLeOp  "leAddr#"   Compare   Addr# -> Addr# -> Int#
1685
1686 primop IndexOffAddrOp_Char "indexCharOffAddr#" GenPrimOp
1687    Addr# -> Int# -> Char#
1688    {Reads 8-bit character; offset in bytes.}
1689    with can_fail = True
1690
1691 primop IndexOffAddrOp_WideChar "indexWideCharOffAddr#" GenPrimOp
1692    Addr# -> Int# -> Char#
1693    {Reads 31-bit character; offset in 4-byte words.}
1694    with can_fail = True
1695
1696 primop IndexOffAddrOp_Int "indexIntOffAddr#" GenPrimOp
1697    Addr# -> Int# -> Int#
1698    with can_fail = True
1699
1700 primop IndexOffAddrOp_Word "indexWordOffAddr#" GenPrimOp
1701    Addr# -> Int# -> Word#
1702    with can_fail = True
1703
1704 primop IndexOffAddrOp_Addr "indexAddrOffAddr#" GenPrimOp
1705    Addr# -> Int# -> Addr#
1706    with can_fail = True
1707
1708 primop IndexOffAddrOp_Float "indexFloatOffAddr#" GenPrimOp
1709    Addr# -> Int# -> Float#
1710    with can_fail = True
1711
1712 primop IndexOffAddrOp_Double "indexDoubleOffAddr#" GenPrimOp
1713    Addr# -> Int# -> Double#
1714    with can_fail = True
1715
1716 primop IndexOffAddrOp_StablePtr "indexStablePtrOffAddr#" GenPrimOp
1717    Addr# -> Int# -> StablePtr# a
1718    with can_fail = True
1719
1720 primop IndexOffAddrOp_Int8 "indexInt8OffAddr#" GenPrimOp
1721    Addr# -> Int# -> Int#
1722    with can_fail = True
1723
1724 primop IndexOffAddrOp_Int16 "indexInt16OffAddr#" GenPrimOp
1725    Addr# -> Int# -> Int#
1726    with can_fail = True
1727
1728 primop IndexOffAddrOp_Int32 "indexInt32OffAddr#" GenPrimOp
1729    Addr# -> Int# -> INT32
1730    with can_fail = True
1731
1732 primop IndexOffAddrOp_Int64 "indexInt64OffAddr#" GenPrimOp
1733    Addr# -> Int# -> INT64
1734    with can_fail = True
1735
1736 primop IndexOffAddrOp_Word8 "indexWord8OffAddr#" GenPrimOp
1737    Addr# -> Int# -> Word#
1738    with can_fail = True
1739
1740 primop IndexOffAddrOp_Word16 "indexWord16OffAddr#" GenPrimOp
1741    Addr# -> Int# -> Word#
1742    with can_fail = True
1743
1744 primop IndexOffAddrOp_Word32 "indexWord32OffAddr#" GenPrimOp
1745    Addr# -> Int# -> WORD32
1746    with can_fail = True
1747
1748 primop IndexOffAddrOp_Word64 "indexWord64OffAddr#" GenPrimOp
1749    Addr# -> Int# -> WORD64
1750    with can_fail = True
1751
1752 primop ReadOffAddrOp_Char "readCharOffAddr#" GenPrimOp
1753    Addr# -> Int# -> State# s -> (# State# s, Char# #)
1754    {Reads 8-bit character; offset in bytes.}
1755    with has_side_effects = True
1756         can_fail         = True
1757
1758 primop ReadOffAddrOp_WideChar "readWideCharOffAddr#" GenPrimOp
1759    Addr# -> Int# -> State# s -> (# State# s, Char# #)
1760    {Reads 31-bit character; offset in 4-byte words.}
1761    with has_side_effects = True
1762         can_fail         = True
1763
1764 primop ReadOffAddrOp_Int "readIntOffAddr#" GenPrimOp
1765    Addr# -> Int# -> State# s -> (# State# s, Int# #)
1766    with has_side_effects = True
1767         can_fail         = True
1768
1769 primop ReadOffAddrOp_Word "readWordOffAddr#" GenPrimOp
1770    Addr# -> Int# -> State# s -> (# State# s, Word# #)
1771    with has_side_effects = True
1772         can_fail         = True
1773
1774 primop ReadOffAddrOp_Addr "readAddrOffAddr#" GenPrimOp
1775    Addr# -> Int# -> State# s -> (# State# s, Addr# #)
1776    with has_side_effects = True
1777         can_fail         = True
1778
1779 primop ReadOffAddrOp_Float "readFloatOffAddr#" GenPrimOp
1780    Addr# -> Int# -> State# s -> (# State# s, Float# #)
1781    with has_side_effects = True
1782         can_fail         = True
1783
1784 primop ReadOffAddrOp_Double "readDoubleOffAddr#" GenPrimOp
1785    Addr# -> Int# -> State# s -> (# State# s, Double# #)
1786    with has_side_effects = True
1787         can_fail         = True
1788
1789 primop ReadOffAddrOp_StablePtr "readStablePtrOffAddr#" GenPrimOp
1790    Addr# -> Int# -> State# s -> (# State# s, StablePtr# a #)
1791    with has_side_effects = True
1792         can_fail         = True
1793
1794 primop ReadOffAddrOp_Int8 "readInt8OffAddr#" GenPrimOp
1795    Addr# -> Int# -> State# s -> (# State# s, Int# #)
1796    with has_side_effects = True
1797         can_fail         = True
1798
1799 primop ReadOffAddrOp_Int16 "readInt16OffAddr#" GenPrimOp
1800    Addr# -> Int# -> State# s -> (# State# s, Int# #)
1801    with has_side_effects = True
1802         can_fail         = True
1803
1804 primop ReadOffAddrOp_Int32 "readInt32OffAddr#" GenPrimOp
1805    Addr# -> Int# -> State# s -> (# State# s, INT32 #)
1806    with has_side_effects = True
1807         can_fail         = True
1808
1809 primop ReadOffAddrOp_Int64 "readInt64OffAddr#" GenPrimOp
1810    Addr# -> Int# -> State# s -> (# State# s, INT64 #)
1811    with has_side_effects = True
1812         can_fail         = True
1813
1814 primop ReadOffAddrOp_Word8 "readWord8OffAddr#" GenPrimOp
1815    Addr# -> Int# -> State# s -> (# State# s, Word# #)
1816    with has_side_effects = True
1817         can_fail         = True
1818
1819 primop ReadOffAddrOp_Word16 "readWord16OffAddr#" GenPrimOp
1820    Addr# -> Int# -> State# s -> (# State# s, Word# #)
1821    with has_side_effects = True
1822         can_fail         = True
1823
1824 primop ReadOffAddrOp_Word32 "readWord32OffAddr#" GenPrimOp
1825    Addr# -> Int# -> State# s -> (# State# s, WORD32 #)
1826    with has_side_effects = True
1827         can_fail         = True
1828
1829 primop ReadOffAddrOp_Word64 "readWord64OffAddr#" GenPrimOp
1830    Addr# -> Int# -> State# s -> (# State# s, WORD64 #)
1831    with has_side_effects = True
1832         can_fail         = True
1833
1834 primop  WriteOffAddrOp_Char "writeCharOffAddr#" GenPrimOp
1835    Addr# -> Int# -> Char# -> State# s -> State# s
1836    with has_side_effects = True
1837         can_fail         = True
1838
1839 primop  WriteOffAddrOp_WideChar "writeWideCharOffAddr#" GenPrimOp
1840    Addr# -> Int# -> Char# -> State# s -> State# s
1841    with has_side_effects = True
1842         can_fail         = True
1843
1844 primop  WriteOffAddrOp_Int "writeIntOffAddr#" GenPrimOp
1845    Addr# -> Int# -> Int# -> State# s -> State# s
1846    with has_side_effects = True
1847         can_fail         = True
1848
1849 primop  WriteOffAddrOp_Word "writeWordOffAddr#" GenPrimOp
1850    Addr# -> Int# -> Word# -> State# s -> State# s
1851    with has_side_effects = True
1852         can_fail         = True
1853
1854 primop  WriteOffAddrOp_Addr "writeAddrOffAddr#" GenPrimOp
1855    Addr# -> Int# -> Addr# -> State# s -> State# s
1856    with has_side_effects = True
1857         can_fail         = True
1858
1859 primop  WriteOffAddrOp_Float "writeFloatOffAddr#" GenPrimOp
1860    Addr# -> Int# -> Float# -> State# s -> State# s
1861    with has_side_effects = True
1862         can_fail         = True
1863
1864 primop  WriteOffAddrOp_Double "writeDoubleOffAddr#" GenPrimOp
1865    Addr# -> Int# -> Double# -> State# s -> State# s
1866    with has_side_effects = True
1867         can_fail         = True
1868
1869 primop  WriteOffAddrOp_StablePtr "writeStablePtrOffAddr#" GenPrimOp
1870    Addr# -> Int# -> StablePtr# a -> State# s -> State# s
1871    with has_side_effects = True
1872         can_fail         = True
1873
1874 primop  WriteOffAddrOp_Int8 "writeInt8OffAddr#" GenPrimOp
1875    Addr# -> Int# -> Int# -> State# s -> State# s
1876    with has_side_effects = True
1877         can_fail         = True
1878
1879 primop  WriteOffAddrOp_Int16 "writeInt16OffAddr#" GenPrimOp
1880    Addr# -> Int# -> Int# -> State# s -> State# s
1881    with has_side_effects = True
1882         can_fail         = True
1883
1884 primop  WriteOffAddrOp_Int32 "writeInt32OffAddr#" GenPrimOp
1885    Addr# -> Int# -> INT32 -> State# s -> State# s
1886    with has_side_effects = True
1887         can_fail         = True
1888
1889 primop  WriteOffAddrOp_Int64 "writeInt64OffAddr#" GenPrimOp
1890    Addr# -> Int# -> INT64 -> State# s -> State# s
1891    with has_side_effects = True
1892         can_fail         = True
1893
1894 primop  WriteOffAddrOp_Word8 "writeWord8OffAddr#" GenPrimOp
1895    Addr# -> Int# -> Word# -> State# s -> State# s
1896    with has_side_effects = True
1897         can_fail         = True
1898
1899 primop  WriteOffAddrOp_Word16 "writeWord16OffAddr#" GenPrimOp
1900    Addr# -> Int# -> Word# -> State# s -> State# s
1901    with has_side_effects = True
1902         can_fail         = True
1903
1904 primop  WriteOffAddrOp_Word32 "writeWord32OffAddr#" GenPrimOp
1905    Addr# -> Int# -> WORD32 -> State# s -> State# s
1906    with has_side_effects = True
1907         can_fail         = True
1908
1909 primop  WriteOffAddrOp_Word64 "writeWord64OffAddr#" GenPrimOp
1910    Addr# -> Int# -> WORD64 -> State# s -> State# s
1911    with has_side_effects = True
1912         can_fail         = True
1913
1914 ------------------------------------------------------------------------
1915 section "Mutable variables"
1916         {Operations on MutVar\#s.}
1917 ------------------------------------------------------------------------
1918
1919 primtype MutVar# s a
1920         {A {\tt MutVar\#} behaves like a single-element mutable array.}
1921
1922 primop  NewMutVarOp "newMutVar#" GenPrimOp
1923    a -> State# s -> (# State# s, MutVar# s a #)
1924    {Create {\tt MutVar\#} with specified initial value in specified state thread.}
1925    with
1926    out_of_line = True
1927    has_side_effects = True
1928
1929 -- Note [Why MutVar# ops can't fail]
1930 -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1931 --
1932 -- We don't label readMutVar# or writeMutVar# as can_fail.
1933 -- This may seem a bit peculiar, because they surely *could*
1934 -- fail spectacularly if passed a pointer to unallocated memory.
1935 -- But MutVar#s are always correct by construction; we never
1936 -- test if a pointer is valid before using it with these operations.
1937 -- So we never have to worry about floating the pointer reference
1938 -- outside a validity test. At the moment, has_side_effects blocks
1939 -- up the relevant optimizations anyway, but we hope to draw finer
1940 -- distinctions soon, which should improve matters for readMutVar#
1941 -- at least.
1942
1943 primop  ReadMutVarOp "readMutVar#" GenPrimOp
1944    MutVar# s a -> State# s -> (# State# s, a #)
1945    {Read contents of {\tt MutVar\#}. Result is not yet evaluated.}
1946    with
1947    -- See Note [Why MutVar# ops can't fail]
1948    has_side_effects = True
1949
1950 primop  WriteMutVarOp "writeMutVar#"  GenPrimOp
1951    MutVar# s a -> a -> State# s -> State# s
1952    {Write contents of {\tt MutVar\#}.}
1953    with
1954    -- See Note [Why MutVar# ops can't fail]
1955    has_side_effects = True
1956    code_size = { primOpCodeSizeForeignCall } -- for the write barrier
1957
1958 primop  SameMutVarOp "sameMutVar#" GenPrimOp
1959    MutVar# s a -> MutVar# s a -> Int#
1960
1961 -- Note [Why not an unboxed tuple in atomicModifyMutVar#?]
1962 -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1963 --
1964 -- Looking at the type of atomicModifyMutVar#, one might wonder why
1965 -- it doesn't return an unboxed tuple. e.g.,
1966 --
1967 --   MutVar# s a -> (a -> (# a, b #)) -> State# s -> (# State# s, b #)
1968 --
1969 -- The reason is that atomicModifyMutVar# relies on laziness for its atomicity.
1970 -- Given a MutVar# containing x, atomicModifyMutVar# merely replaces the
1971 -- its contents with a thunk of the form (fst (f x)). This can be done using an
1972 -- atomic compare-and-swap as it is merely replacing a pointer.
1973
1974 primop  AtomicModifyMutVarOp "atomicModifyMutVar#" GenPrimOp
1975    MutVar# s a -> (a -> b) -> State# s -> (# State# s, c #)
1976    { Modify the contents of a {\tt MutVar\#}. Note that this isn't strictly
1977      speaking the correct type for this function, it should really be
1978      {\tt MutVar# s a -> (a -> (a,b)) -> State# s -> (# State# s, b #)}, however
1979      we don't know about pairs here. }
1980    with
1981    out_of_line = True
1982    has_side_effects = True
1983    can_fail         = True
1984
1985 primop  CasMutVarOp "casMutVar#" GenPrimOp
1986   MutVar# s a -> a -> a -> State# s -> (# State# s, Int#, a #)
1987    with
1988    out_of_line = True
1989    has_side_effects = True
1990
1991 ------------------------------------------------------------------------
1992 section "Exceptions"
1993 ------------------------------------------------------------------------
1994
1995 -- Note [Strictness for mask/unmask/catch]
1996 -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1997 -- Consider this example, which comes from GHC.IO.Handle.Internals:
1998 --    wantReadableHandle3 f ma b st
1999 --      = case ... of
2000 --          DEFAULT -> case ma of MVar a -> ...
2001 --          0#      -> maskAsynchExceptions# (\st -> case ma of MVar a -> ...)
2002 -- The outer case just decides whether to mask exceptions, but we don't want
2003 -- thereby to hide the strictness in 'ma'!  Hence the use of strictApply1Dmd.
2004 --
2005 -- For catch, catchSTM, and catchRetry, we must be extra careful; see
2006 -- Note [Exceptions and strictness] in Demand
2007
2008 primop  CatchOp "catch#" GenPrimOp
2009           (State# RealWorld -> (# State# RealWorld, a #) )
2010        -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
2011        -> State# RealWorld
2012        -> (# State# RealWorld, a #)
2013    with
2014    strictness  = { \ _arity -> mkClosedStrictSig [ lazyApply1Dmd
2015                                                  , lazyApply2Dmd
2016                                                  , topDmd] topRes }
2017                  -- See Note [Strictness for mask/unmask/catch]
2018    out_of_line = True
2019    has_side_effects = True
2020
2021 primop  RaiseOp "raise#" GenPrimOp
2022    b -> o
2023       -- NB: the type variable "o" is "a", but with OpenKind
2024    with
2025    strictness  = { \ _arity -> mkClosedStrictSig [topDmd] exnRes }
2026       -- NB: result is ThrowsExn
2027    out_of_line = True
2028    has_side_effects = True
2029      -- raise# certainly throws a Haskell exception and hence has_side_effects
2030      -- It doesn't actually make much difference because the fact that it
2031      -- returns bottom independently ensures that we are careful not to discard
2032      -- it.  But still, it's better to say the Right Thing.
2033
2034 -- raiseIO# needs to be a primop, because exceptions in the IO monad
2035 -- must be *precise* - we don't want the strictness analyser turning
2036 -- one kind of bottom into another, as it is allowed to do in pure code.
2037 --
2038 -- But we *do* want to know that it returns bottom after
2039 -- being applied to two arguments, so that this function is strict in y
2040 --     f x y | x>0       = raiseIO blah
2041 --           | y>0       = return 1
2042 --           | otherwise = return 2
2043 --
2044 -- TODO Check that the above notes on @f@ are valid. The function successfully
2045 -- produces an IO exception when compiled without optimization. If we analyze
2046 -- it as strict in @y@, won't we change that behavior under optimization?
2047 -- I thought the rule was that it was okay to replace one valid imprecise
2048 -- exception with another, but not to replace a precise exception with
2049 -- an imprecise one (dfeuer, 2017-03-05).
2050
2051 primop  RaiseIOOp "raiseIO#" GenPrimOp
2052    a -> State# RealWorld -> (# State# RealWorld, b #)
2053    with
2054    strictness  = { \ _arity -> mkClosedStrictSig [topDmd, topDmd] exnRes }
2055    out_of_line = True
2056    has_side_effects = True
2057
2058 primop  MaskAsyncExceptionsOp "maskAsyncExceptions#" GenPrimOp
2059         (State# RealWorld -> (# State# RealWorld, a #))
2060      -> (State# RealWorld -> (# State# RealWorld, a #))
2061    with
2062    strictness  = { \ _arity -> mkClosedStrictSig [strictApply1Dmd,topDmd] topRes }
2063                  -- See Note [Strictness for mask/unmask/catch]
2064    out_of_line = True
2065    has_side_effects = True
2066
2067 primop  MaskUninterruptibleOp "maskUninterruptible#" GenPrimOp
2068         (State# RealWorld -> (# State# RealWorld, a #))
2069      -> (State# RealWorld -> (# State# RealWorld, a #))
2070    with
2071    strictness  = { \ _arity -> mkClosedStrictSig [strictApply1Dmd,topDmd] topRes }
2072    out_of_line = True
2073    has_side_effects = True
2074
2075 primop  UnmaskAsyncExceptionsOp "unmaskAsyncExceptions#" GenPrimOp
2076         (State# RealWorld -> (# State# RealWorld, a #))
2077      -> (State# RealWorld -> (# State# RealWorld, a #))
2078    with
2079    strictness  = { \ _arity -> mkClosedStrictSig [strictApply1Dmd,topDmd] topRes }
2080                  -- See Note [Strictness for mask/unmask/catch]
2081    out_of_line = True
2082    has_side_effects = True
2083
2084 primop  MaskStatus "getMaskingState#" GenPrimOp
2085         State# RealWorld -> (# State# RealWorld, Int# #)
2086    with
2087    out_of_line = True
2088    has_side_effects = True
2089
2090 ------------------------------------------------------------------------
2091 section "STM-accessible Mutable Variables"
2092 ------------------------------------------------------------------------
2093
2094 primtype TVar# s a
2095
2096 primop  AtomicallyOp "atomically#" GenPrimOp
2097       (State# RealWorld -> (# State# RealWorld, a #) )
2098    -> State# RealWorld -> (# State# RealWorld, a #)
2099    with
2100    strictness  = { \ _arity -> mkClosedStrictSig [strictApply1Dmd,topDmd] topRes }
2101                  -- See Note [Strictness for mask/unmask/catch]
2102    out_of_line = True
2103    has_side_effects = True
2104
2105 -- NB: retry#'s strictness information specifies it to throw an exception
2106 -- This lets the compiler perform some extra simplifications, since retry#
2107 -- will technically never return.
2108 --
2109 -- This allows the simplifier to replace things like:
2110 --   case retry# s1
2111 --     (# s2, a #) -> e
2112 -- with:
2113 --   retry# s1
2114 -- where 'e' would be unreachable anyway.  See Trac #8091.
2115 --
2116 -- Note that it *does not* return botRes as the "exception" that is throw may be
2117 -- "caught" by catchRetry#. This mistake caused #14171.
2118 primop  RetryOp "retry#" GenPrimOp
2119    State# RealWorld -> (# State# RealWorld, a #)
2120    with
2121    strictness  = { \ _arity -> mkClosedStrictSig [topDmd] exnRes }
2122    out_of_line = True
2123    has_side_effects = True
2124
2125 primop  CatchRetryOp "catchRetry#" GenPrimOp
2126       (State# RealWorld -> (# State# RealWorld, a #) )
2127    -> (State# RealWorld -> (# State# RealWorld, a #) )
2128    -> (State# RealWorld -> (# State# RealWorld, a #) )
2129    with
2130    strictness  = { \ _arity -> mkClosedStrictSig [ catchArgDmd
2131                                                  , lazyApply1Dmd
2132                                                  , topDmd ] topRes }
2133                  -- See Note [Strictness for mask/unmask/catch]
2134    out_of_line = True
2135    has_side_effects = True
2136
2137 primop  CatchSTMOp "catchSTM#" GenPrimOp
2138       (State# RealWorld -> (# State# RealWorld, a #) )
2139    -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
2140    -> (State# RealWorld -> (# State# RealWorld, a #) )
2141    with
2142    strictness  = { \ _arity -> mkClosedStrictSig [ lazyApply1Dmd
2143                                                  , lazyApply2Dmd
2144                                                  , topDmd ] topRes }
2145                  -- See Note [Strictness for mask/unmask/catch]
2146    out_of_line = True
2147    has_side_effects = True
2148
2149 primop  Check "check#" GenPrimOp
2150       (State# RealWorld -> (# State# RealWorld, a #) )
2151    -> (State# RealWorld -> State# RealWorld)
2152    with
2153    out_of_line = True
2154    has_side_effects = True
2155
2156 primop  NewTVarOp "newTVar#" GenPrimOp
2157        a
2158     -> State# s -> (# State# s, TVar# s a #)
2159    {Create a new {\tt TVar\#} holding a specified initial value.}
2160    with
2161    out_of_line  = True
2162    has_side_effects = True
2163
2164 primop  ReadTVarOp "readTVar#" GenPrimOp
2165        TVar# s a
2166     -> State# s -> (# State# s, a #)
2167    {Read contents of {\tt TVar\#}.  Result is not yet evaluated.}
2168    with
2169    out_of_line  = True
2170    has_side_effects = True
2171
2172 primop ReadTVarIOOp "readTVarIO#" GenPrimOp
2173        TVar# s a
2174     -> State# s -> (# State# s, a #)
2175    {Read contents of {\tt TVar\#} outside an STM transaction}
2176    with
2177    out_of_line      = True
2178    has_side_effects = True
2179
2180 primop  WriteTVarOp "writeTVar#" GenPrimOp
2181        TVar# s a
2182     -> a
2183     -> State# s -> State# s
2184    {Write contents of {\tt TVar\#}.}
2185    with
2186    out_of_line      = True
2187    has_side_effects = True
2188
2189 primop  SameTVarOp "sameTVar#" GenPrimOp
2190    TVar# s a -> TVar# s a -> Int#
2191
2192
2193 ------------------------------------------------------------------------
2194 section "Synchronized Mutable Variables"
2195         {Operations on {\tt MVar\#}s. }
2196 ------------------------------------------------------------------------
2197
2198 primtype MVar# s a
2199         { A shared mutable variable ({\it not} the same as a {\tt MutVar\#}!).
2200         (Note: in a non-concurrent implementation, {\tt (MVar\# a)} can be
2201         represented by {\tt (MutVar\# (Maybe a))}.) }
2202
2203 primop  NewMVarOp "newMVar#"  GenPrimOp
2204    State# s -> (# State# s, MVar# s a #)
2205    {Create new {\tt MVar\#}; initially empty.}
2206    with
2207    out_of_line = True
2208    has_side_effects = True
2209
2210 primop  TakeMVarOp "takeMVar#" GenPrimOp
2211    MVar# s a -> State# s -> (# State# s, a #)
2212    {If {\tt MVar\#} is empty, block until it becomes full.
2213    Then remove and return its contents, and set it empty.}
2214    with
2215    out_of_line      = True
2216    has_side_effects = True
2217
2218 primop  TryTakeMVarOp "tryTakeMVar#" GenPrimOp
2219    MVar# s a -> State# s -> (# State# s, Int#, a #)
2220    {If {\tt MVar\#} is empty, immediately return with integer 0 and value undefined.
2221    Otherwise, return with integer 1 and contents of {\tt MVar\#}, and set {\tt MVar\#} empty.}
2222    with
2223    out_of_line      = True
2224    has_side_effects = True
2225
2226 primop  PutMVarOp "putMVar#" GenPrimOp
2227    MVar# s a -> a -> State# s -> State# s
2228    {If {\tt MVar\#} is full, block until it becomes empty.
2229    Then store value arg as its new contents.}
2230    with
2231    out_of_line      = True
2232    has_side_effects = True
2233
2234 primop  TryPutMVarOp "tryPutMVar#" GenPrimOp
2235    MVar# s a -> a -> State# s -> (# State# s, Int# #)
2236    {If {\tt MVar\#} is full, immediately return with integer 0.
2237     Otherwise, store value arg as {\tt MVar\#}'s new contents, and return with integer 1.}
2238    with
2239    out_of_line      = True
2240    has_side_effects = True
2241
2242 primop  ReadMVarOp "readMVar#" GenPrimOp
2243    MVar# s a -> State# s -> (# State# s, a #)
2244    {If {\tt MVar\#} is empty, block until it becomes full.
2245    Then read its contents without modifying the MVar, without possibility
2246    of intervention from other threads.}
2247    with
2248    out_of_line      = True
2249    has_side_effects = True
2250
2251 primop  TryReadMVarOp "tryReadMVar#" GenPrimOp
2252    MVar# s a -> State# s -> (# State# s, Int#, a #)
2253    {If {\tt MVar\#} is empty, immediately return with integer 0 and value undefined.
2254    Otherwise, return with integer 1 and contents of {\tt MVar\#}.}
2255    with
2256    out_of_line      = True
2257    has_side_effects = True
2258
2259 primop  SameMVarOp "sameMVar#" GenPrimOp
2260    MVar# s a -> MVar# s a -> Int#
2261
2262 primop  IsEmptyMVarOp "isEmptyMVar#" GenPrimOp
2263    MVar# s a -> State# s -> (# State# s, Int# #)
2264    {Return 1 if {\tt MVar\#} is empty; 0 otherwise.}
2265    with
2266    out_of_line = True
2267    has_side_effects = True
2268
2269 ------------------------------------------------------------------------
2270 section "Delay/wait operations"
2271 ------------------------------------------------------------------------
2272
2273 primop  DelayOp "delay#" GenPrimOp
2274    Int# -> State# s -> State# s
2275    {Sleep specified number of microseconds.}
2276    with
2277    has_side_effects = True
2278    out_of_line      = True
2279
2280 primop  WaitReadOp "waitRead#" GenPrimOp
2281    Int# -> State# s -> State# s
2282    {Block until input is available on specified file descriptor.}
2283    with
2284    has_side_effects = True
2285    out_of_line      = True
2286
2287 primop  WaitWriteOp "waitWrite#" GenPrimOp
2288    Int# -> State# s -> State# s
2289    {Block until output is possible on specified file descriptor.}
2290    with
2291    has_side_effects = True
2292    out_of_line      = True
2293
2294 #if defined(mingw32_TARGET_OS)
2295 primop  AsyncReadOp "asyncRead#" GenPrimOp
2296    Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
2297    {Asynchronously read bytes from specified file descriptor.}
2298    with
2299    has_side_effects = True
2300    out_of_line      = True
2301
2302 primop  AsyncWriteOp "asyncWrite#" GenPrimOp
2303    Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
2304    {Asynchronously write bytes from specified file descriptor.}
2305    with
2306    has_side_effects = True
2307    out_of_line      = True
2308
2309 primop  AsyncDoProcOp "asyncDoProc#" GenPrimOp
2310    Addr# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
2311    {Asynchronously perform procedure (first arg), passing it 2nd arg.}
2312    with
2313    has_side_effects = True
2314    out_of_line      = True
2315
2316 #endif
2317
2318 ------------------------------------------------------------------------
2319 section "Concurrency primitives"
2320 ------------------------------------------------------------------------
2321
2322 primtype State# s
2323         { {\tt State\#} is the primitive, unlifted type of states.  It has
2324         one type parameter, thus {\tt State\# RealWorld}, or {\tt State\# s},
2325         where s is a type variable. The only purpose of the type parameter
2326         is to keep different state threads separate.  It is represented by
2327         nothing at all. }
2328
2329 primtype RealWorld
2330         { {\tt RealWorld} is deeply magical.  It is {\it primitive}, but it is not
2331         {\it unlifted} (hence {\tt ptrArg}).  We never manipulate values of type
2332         {\tt RealWorld}; it's only used in the type system, to parameterise {\tt State\#}. }
2333
2334 primtype ThreadId#
2335         {(In a non-concurrent implementation, this can be a singleton
2336         type, whose (unique) value is returned by {\tt myThreadId\#}.  The
2337         other operations can be omitted.)}
2338
2339 primop  ForkOp "fork#" GenPrimOp
2340    a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
2341    with
2342    has_side_effects = True
2343    out_of_line      = True
2344
2345 primop  ForkOnOp "forkOn#" GenPrimOp
2346    Int# -> a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
2347    with
2348    has_side_effects = True
2349    out_of_line      = True
2350
2351 primop  KillThreadOp "killThread#"  GenPrimOp
2352    ThreadId# -> a -> State# RealWorld -> State# RealWorld
2353    with
2354    has_side_effects = True
2355    out_of_line      = True
2356
2357 primop  YieldOp "yield#" GenPrimOp
2358    State# RealWorld -> State# RealWorld
2359    with
2360    has_side_effects = True
2361    out_of_line      = True
2362
2363 primop  MyThreadIdOp "myThreadId#" GenPrimOp
2364    State# RealWorld -> (# State# RealWorld, ThreadId# #)
2365    with
2366    out_of_line = True
2367    has_side_effects = True
2368
2369 primop LabelThreadOp "labelThread#" GenPrimOp
2370    ThreadId# -> Addr# -> State# RealWorld -> State# RealWorld
2371    with
2372    has_side_effects = True
2373    out_of_line      = True
2374
2375 primop  IsCurrentThreadBoundOp "isCurrentThreadBound#" GenPrimOp
2376    State# RealWorld -> (# State# RealWorld, Int# #)
2377    with
2378    out_of_line = True
2379    has_side_effects = True
2380
2381 primop  NoDuplicateOp "noDuplicate#" GenPrimOp
2382    State# s -> State# s
2383    with
2384    out_of_line = True
2385    has_side_effects = True
2386
2387 primop  ThreadStatusOp "threadStatus#" GenPrimOp
2388    ThreadId# -> State# RealWorld -> (# State# RealWorld, Int#, Int#, Int# #)
2389    with
2390    out_of_line = True
2391    has_side_effects = True
2392
2393 ------------------------------------------------------------------------
2394 section "Weak pointers"
2395 ------------------------------------------------------------------------
2396
2397 primtype Weak# b
2398
2399 -- note that tyvar "o" denotes openAlphaTyVar
2400
2401 primop  MkWeakOp "mkWeak#" GenPrimOp
2402    o -> b -> (State# RealWorld -> (# State# RealWorld, c #))
2403      -> State# RealWorld -> (# State# RealWorld, Weak# b #)
2404    { {\tt mkWeak# k v finalizer s} creates a weak reference to value {\tt k},
2405      with an associated reference to some value {\tt v}. If {\tt k} is still
2406      alive then {\tt v} can be retrieved using {\tt deRefWeak#}. Note that
2407      the type of {\tt k} must be represented by a pointer (i.e. of kind {\tt
2408      TYPE 'LiftedRep} or {\tt TYPE 'UnliftedRep}). }
2409    with
2410    has_side_effects = True
2411    out_of_line      = True
2412
2413 primop  MkWeakNoFinalizerOp "mkWeakNoFinalizer#" GenPrimOp
2414    o -> b -> State# RealWorld -> (# State# RealWorld, Weak# b #)
2415    with
2416    has_side_effects = True
2417    out_of_line      = True
2418
2419 primop  AddCFinalizerToWeakOp "addCFinalizerToWeak#" GenPrimOp
2420    Addr# -> Addr# -> Int# -> Addr# -> Weak# b
2421           -> State# RealWorld -> (# State# RealWorld, Int# #)
2422    { {\tt addCFinalizerToWeak# fptr ptr flag eptr w} attaches a C
2423      function pointer {\tt fptr} to a weak pointer {\tt w} as a finalizer. If
2424      {\tt flag} is zero, {\tt fptr} will be called with one argument,
2425      {\tt ptr}. Otherwise, it will be called with two arguments,
2426      {\tt eptr} and {\tt ptr}. {\tt addCFinalizerToWeak#} returns
2427      1 on success, or 0 if {\tt w} is already dead. }
2428    with
2429    has_side_effects = True
2430    out_of_line      = True
2431
2432 primop  DeRefWeakOp "deRefWeak#" GenPrimOp
2433    Weak# a -> State# RealWorld -> (# State# RealWorld, Int#, a #)
2434    with
2435    has_side_effects = True
2436    out_of_line      = True
2437
2438 primop  FinalizeWeakOp "finalizeWeak#" GenPrimOp
2439    Weak# a -> State# RealWorld -> (# State# RealWorld, Int#,
2440               (State# RealWorld -> (# State# RealWorld, b #) ) #)
2441    { Finalize a weak pointer. The return value is an unboxed tuple
2442      containing the new state of the world and an "unboxed Maybe",
2443      represented by an {\tt Int#} and a (possibly invalid) finalization
2444      action. An {\tt Int#} of {\tt 1} indicates that the finalizer is valid. The
2445      return value {\tt b} from the finalizer should be ignored. }
2446    with
2447    has_side_effects = True
2448    out_of_line      = True
2449
2450 primop TouchOp "touch#" GenPrimOp
2451    o -> State# RealWorld -> State# RealWorld
2452    with
2453    code_size = { 0 }
2454    has_side_effects = True
2455
2456 ------------------------------------------------------------------------
2457 section "Stable pointers and names"
2458 ------------------------------------------------------------------------
2459
2460 primtype StablePtr# a
2461
2462 primtype StableName# a
2463
2464 primop  MakeStablePtrOp "makeStablePtr#" GenPrimOp
2465    a -> State# RealWorld -> (# State# RealWorld, StablePtr# a #)
2466    with
2467    has_side_effects = True
2468    out_of_line      = True
2469
2470 primop  DeRefStablePtrOp "deRefStablePtr#" GenPrimOp
2471    StablePtr# a -> State# RealWorld -> (# State# RealWorld, a #)
2472    with
2473    has_side_effects = True
2474    out_of_line      = True
2475
2476 primop  EqStablePtrOp "eqStablePtr#" GenPrimOp
2477    StablePtr# a -> StablePtr# a -> Int#
2478    with
2479    has_side_effects = True
2480
2481 primop  MakeStableNameOp "makeStableName#" GenPrimOp
2482    a -> State# RealWorld -> (# State# RealWorld, StableName# a #)
2483    with
2484    has_side_effects = True
2485    out_of_line      = True
2486
2487 primop  EqStableNameOp "eqStableName#" GenPrimOp
2488    StableName# a -> StableName# b -> Int#
2489
2490 primop  StableNameToIntOp "stableNameToInt#" GenPrimOp
2491    StableName# a -> Int#
2492
2493 ------------------------------------------------------------------------
2494 section "Compact normal form"
2495 ------------------------------------------------------------------------
2496
2497 primtype Compact#
2498
2499 primop  CompactNewOp "compactNew#" GenPrimOp
2500    Word# -> State# RealWorld -> (# State# RealWorld, Compact# #)
2501    { Create a new Compact with the given size (in bytes, not words).
2502      The size is rounded up to a multiple of the allocator block size,
2503      and capped to one mega block. }
2504    with
2505    has_side_effects = True
2506    out_of_line      = True
2507
2508 primop  CompactResizeOp "compactResize#" GenPrimOp
2509    Compact# -> Word# -> State# RealWorld ->
2510    State# RealWorld
2511    { Set the new allocation size of the compact. This value (in bytes)
2512      determines the size of each block in the compact chain. }
2513    with
2514    has_side_effects = True
2515    out_of_line      = True
2516
2517 primop  CompactContainsOp "compactContains#" GenPrimOp
2518    Compact# -> a -> State# RealWorld -> (# State# RealWorld, Int# #)
2519    { Returns 1# if the object is contained in the compact, 0# otherwise. }
2520    with
2521    out_of_line      = True
2522
2523 primop  CompactContainsAnyOp "compactContainsAny#" GenPrimOp
2524    a -> State# RealWorld -> (# State# RealWorld, Int# #)
2525    { Returns 1# if the object is in any compact at all, 0# otherwise. }
2526    with
2527    out_of_line      = True
2528
2529 primop  CompactGetFirstBlockOp "compactGetFirstBlock#" GenPrimOp
2530    Compact# -> State# RealWorld -> (# State# RealWorld, Addr#, Word# #)
2531    { Returns the address and the size (in bytes) of the first block of
2532      a compact. }
2533    with
2534    out_of_line      = True
2535
2536 primop  CompactGetNextBlockOp "compactGetNextBlock#" GenPrimOp
2537    Compact# -> Addr# -> State# RealWorld -> (# State# RealWorld, Addr#, Word# #)
2538    { Given a compact and the address of one its blocks, returns the
2539      next block and its size, or #nullAddr if the argument was the
2540      last block in the compact. }
2541    with
2542    out_of_line      = True
2543
2544 primop  CompactAllocateBlockOp "compactAllocateBlock#" GenPrimOp
2545    Word# -> Addr# -> State# RealWorld -> (# State# RealWorld, Addr# #)
2546    { Attempt to allocate a compact block with the given size (in
2547      bytes) at the given address. The first argument is a hint to
2548      the allocator, allocation might be satisfied at a different
2549      address (which is returned).
2550      The resulting block is not known to the GC until
2551      compactFixupPointers# is called on it, and care must be taken
2552      so that the address does not escape or memory will be leaked.
2553    }
2554    with
2555    has_side_effects = True
2556    out_of_line      = True
2557
2558 primop  CompactFixupPointersOp "compactFixupPointers#" GenPrimOp
2559    Addr# -> Addr# -> State# RealWorld -> (# State# RealWorld, Compact#, Addr# #)
2560    { Given the pointer to the first block of a compact, and the
2561      address of the root object in the old address space, fix up
2562      the internal pointers inside the compact to account for
2563      a different position in memory than when it was serialized.
2564      This method must be called exactly once after importing
2565      a serialized compact, and returns the new compact and
2566      the new adjusted root address. }
2567    with
2568    has_side_effects = True
2569    out_of_line      = True
2570
2571 primop CompactAdd "compactAdd#" GenPrimOp
2572    Compact# -> a -> State# RealWorld -> (# State# RealWorld, a #)
2573    { Recursively add a closure and its transitive closure to a
2574      {\texttt Compact\#}, evaluating any unevaluated components at the
2575      same time.  Note: {\texttt compactAdd\#} is not thread-safe, so
2576      only one thread may call {\texttt compactAdd\#} with a particular
2577      {\texttt Compact#} at any given time.  The primop does not
2578      enforce any mutual exclusion; the caller is expected to
2579      arrange this. }
2580    with
2581    has_side_effects = True
2582    out_of_line      = True
2583
2584 primop CompactAddWithSharing "compactAddWithSharing#" GenPrimOp
2585    Compact# -> a -> State# RealWorld -> (# State# RealWorld, a #)
2586    { Like {\texttt compactAdd\#}, but retains sharing and cycles
2587    during compaction. }
2588    with
2589    has_side_effects = True
2590    out_of_line      = True
2591
2592 primop CompactSize "compactSize#" GenPrimOp
2593    Compact# -> State# RealWorld -> (# State# RealWorld, Word# #)
2594    { Return the size (in bytes) of the total amount of data in the Compact# }
2595    with
2596    has_side_effects = True
2597    out_of_line      = True
2598
2599 ------------------------------------------------------------------------
2600 section "Unsafe pointer equality"
2601 --  (#1 Bad Guy: Alastair Reid :)
2602 ------------------------------------------------------------------------
2603
2604 primop  ReallyUnsafePtrEqualityOp "reallyUnsafePtrEquality#" GenPrimOp
2605    a -> a -> Int#
2606    { Returns 1# if the given pointers are equal and 0# otherwise. }
2607    with
2608    can_fail   = True -- See Note [reallyUnsafePtrEquality#]
2609
2610
2611 -- Note [reallyUnsafePtrEquality#]
2612 -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2613 -- 
2614 -- reallyUnsafePtrEquality# can't actually fail, per se, but we mark it can_fail
2615 -- anyway. Until 5a9a1738023a, GHC considered primops okay for speculation only
2616 -- when their arguments were known to be forced. This was unnecessarily
2617 -- conservative, but it prevented reallyUnsafePtrEquality# from floating out of
2618 -- places where its arguments were known to be forced. Unfortunately, GHC could
2619 -- sometimes lose track of whether those arguments were forced, leading to let/app
2620 -- invariant failures (see Trac 13027 and the discussion in Trac 11444). Now that
2621 -- ok_for_speculation skips over lifted arguments, we need to explicitly prevent
2622 -- reallyUnsafePtrEquality# from floating out. The reasons are closely related
2623 -- to those described in Note [dataToTag#], although the consequences are less
2624 -- severe. Imagine if we had
2625 -- 
2626 --     \x y . case x of x'
2627 --              DEFAULT ->
2628 --            case y of y'
2629 --              DEFAULT ->
2630 --               let eq = reallyUnsafePtrEquality# x' y'
2631 --               in ...
2632 -- 
2633 -- If the let floats out, we'll get
2634 -- 
2635 --     \x y . let eq = reallyUnsafePtrEquality# x y
2636 --            in case x of ...
2637 -- 
2638 -- The trouble is that pointer equality between thunks is very different
2639 -- from pointer equality between the values those thunks reduce to, and the latter
2640 -- is typically much more precise.
2641
2642 ------------------------------------------------------------------------
2643 section "Parallelism"
2644 ------------------------------------------------------------------------
2645
2646 primop  ParOp "par#" GenPrimOp
2647    a -> Int#
2648    with
2649       -- Note that Par is lazy to avoid that the sparked thing
2650       -- gets evaluated strictly, which it should *not* be
2651    has_side_effects = True
2652    code_size = { primOpCodeSizeForeignCall }
2653
2654 primop SparkOp "spark#" GenPrimOp
2655    a -> State# s -> (# State# s, a #)
2656    with has_side_effects = True
2657    code_size = { primOpCodeSizeForeignCall }
2658
2659 primop SeqOp "seq#" GenPrimOp
2660    a -> State# s -> (# State# s, a #)
2661
2662    -- why return the value?  So that we can control sharing of seq'd
2663    -- values: in
2664    --    let x = e in x `seq` ... x ...
2665    -- we don't want to inline x, so better to represent it as
2666    --    let x = e in case seq# x RW of (# _, x' #) -> ... x' ...
2667    -- also it matches the type of rseq in the Eval monad.
2668
2669 primop GetSparkOp "getSpark#" GenPrimOp
2670    State# s -> (# State# s, Int#, a #)
2671    with
2672    has_side_effects = True
2673    out_of_line = True
2674
2675 primop NumSparks "numSparks#" GenPrimOp
2676    State# s -> (# State# s, Int# #)
2677    { Returns the number of sparks in the local spark pool. }
2678    with
2679    has_side_effects = True
2680    out_of_line = True
2681
2682 ------------------------------------------------------------------------
2683 section "Tag to enum stuff"
2684         {Convert back and forth between values of enumerated types
2685         and small integers.}
2686 ------------------------------------------------------------------------
2687
2688 primop  DataToTagOp "dataToTag#" GenPrimOp
2689    a -> Int#
2690    with
2691    can_fail   = True -- See Note [dataToTag#]
2692    strictness = { \ _arity -> mkClosedStrictSig [evalDmd] topRes }
2693                 -- dataToTag# must have an evaluated argument
2694
2695 primop  TagToEnumOp "tagToEnum#" GenPrimOp
2696    Int# -> a
2697
2698 {- Note [dataToTag#]
2699 ~~~~~~~~~~~~~~~~~~~~
2700 The dataToTag# primop should always be applied to an evaluated argument.
2701 The way to ensure this is to invoke it via the 'getTag' wrapper in GHC.Base:
2702    getTag :: a -> Int#
2703    getTag !x = dataToTag# x
2704
2705 But now consider
2706     \z. case x of y -> let v = dataToTag# y in ...
2707
2708 To improve floating, the FloatOut pass (deliberately) does a
2709 binder-swap on the case, to give
2710     \z. case x of y -> let v = dataToTag# x in ...
2711
2712 Now FloatOut might float that v-binding outside the \z.  But that is
2713 bad because that might mean x gest evaluated much too early!  (CorePrep
2714 adds an eval to a dataToTag# call, to ensure that the argument really is
2715 evaluated; see CorePrep Note [dataToTag magic].)
2716
2717 Solution: make DataToTag into a can_fail primop.  That will stop it floating
2718 (see Note [PrimOp can_fail and has_side_effects] in PrimOp).  It's a bit of
2719 a hack but never mind.
2720 -}
2721
2722 ------------------------------------------------------------------------
2723 section "Bytecode operations"
2724         {Support for manipulating bytecode objects used by the interpreter and
2725         linker.
2726
2727         Bytecode objects are heap objects which represent top-level bindings and
2728         contain a list of instructions and data needed by these instructions.}
2729 ------------------------------------------------------------------------
2730
2731 primtype BCO#
2732    { Primitive bytecode type. }
2733
2734 primop   AddrToAnyOp "addrToAny#" GenPrimOp
2735    Addr# -> (# a #)
2736    { Convert an {\tt Addr\#} to a followable Any type. }
2737    with
2738    code_size = 0
2739
2740 primop   AnyToAddrOp "anyToAddr#" GenPrimOp
2741    a -> State# RealWorld -> (# State# RealWorld, Addr# #)
2742    { Retrieve the address of any Haskell value. This is
2743      essentially an {\texttt unsafeCoerce\#}, but if implemented as such
2744      the core lint pass complains and fails to compile.
2745      As a primop, it is opaque to core/stg, and only appears
2746      in cmm (where the copy propagation pass will get rid of it).
2747      Note that "a" must be a value, not a thunk! It's too late
2748      for strictness analysis to enforce this, so you're on your
2749      own to guarantee this. Also note that {\texttt Addr\#} is not a GC
2750      pointer - up to you to guarantee that it does not become
2751      a dangling pointer immediately after you get it.}
2752    with
2753    code_size = 0
2754
2755 primop   MkApUpd0_Op "mkApUpd0#" GenPrimOp
2756    BCO# -> (# a #)
2757    { Wrap a BCO in a {\tt AP_UPD} thunk which will be updated with the value of
2758      the BCO when evaluated. }
2759    with
2760    out_of_line = True
2761
2762 primop  NewBCOOp "newBCO#" GenPrimOp
2763    ByteArray# -> ByteArray# -> Array# a -> Int# -> ByteArray# -> State# s -> (# State# s, BCO# #)
2764    { {\tt newBCO\# instrs lits ptrs arity bitmap} creates a new bytecode object. The
2765      resulting object encodes a function of the given arity with the instructions
2766      encoded in {\tt instrs}, and a static reference table usage bitmap given by
2767      {\tt bitmap}. }
2768    with
2769    has_side_effects = True
2770    out_of_line      = True
2771
2772 primop  UnpackClosureOp "unpackClosure#" GenPrimOp
2773    a -> (# Addr#, Array# b, ByteArray# #)
2774    { {\tt unpackClosure\# closure} copies non-pointers and pointers in the
2775      payload of the given closure into two new arrays, and returns a pointer to
2776      the first word of the closure's info table, a pointer array for the
2777      pointers in the payload, and a non-pointer array for the non-pointers in
2778      the payload. }
2779    with
2780    out_of_line = True
2781
2782 primop  GetApStackValOp "getApStackVal#" GenPrimOp
2783    a -> Int# -> (# Int#, b #)
2784    with
2785    out_of_line = True
2786
2787 ------------------------------------------------------------------------
2788 section "Misc"
2789         {These aren't nearly as wired in as Etc...}
2790 ------------------------------------------------------------------------
2791
2792 primop  GetCCSOfOp "getCCSOf#" GenPrimOp
2793    a -> State# s -> (# State# s, Addr# #)
2794
2795 primop  GetCurrentCCSOp "getCurrentCCS#" GenPrimOp
2796    a -> State# s -> (# State# s, Addr# #)
2797    { Returns the current {\tt CostCentreStack} (value is {\tt NULL} if
2798      not profiling).  Takes a dummy argument which can be used to
2799      avoid the call to {\tt getCCCS\#} being floated out by the
2800      simplifier, which would result in an uninformative stack
2801      ("CAF"). }
2802
2803 primop  ClearCCSOp "clearCCS#" GenPrimOp
2804    (State# s -> (# State# s, a #)) -> State# s -> (# State# s, a #)
2805    { Run the supplied IO action with an empty CCS.  For example, this
2806      is used by the interpreter to run an interpreted computation
2807      without the call stack showing that it was invoked from GHC. }
2808    with
2809    out_of_line = True
2810
2811 ------------------------------------------------------------------------
2812 section "Etc"
2813         {Miscellaneous built-ins}
2814 ------------------------------------------------------------------------
2815
2816 primtype Proxy# a
2817    { The type constructor {\tt Proxy#} is used to bear witness to some
2818    type variable. It's used when you want to pass around proxy values
2819    for doing things like modelling type applications. A {\tt Proxy#}
2820    is not only unboxed, it also has a polymorphic kind, and has no
2821    runtime representation, being totally free. }
2822
2823 pseudoop "proxy#"
2824    Proxy# a
2825    { Witness for an unboxed {\tt Proxy#} value, which has no runtime
2826    representation. }
2827
2828 pseudoop   "seq"
2829    a -> b -> b
2830    { The value of {\tt seq a b} is bottom if {\tt a} is bottom, and
2831      otherwise equal to {\tt b}. In other words, it evaluates the first 
2832      argument {\tt a} to weak head normal form (WHNF). {\tt seq} is usually 
2833      introduced to improve performance by avoiding unneeded laziness.
2834
2835      A note on evaluation order: the expression {\tt seq a b} does
2836      {\it not} guarantee that {\tt a} will be evaluated before {\tt b}.
2837      The only guarantee given by {\tt seq} is that the both {\tt a}
2838      and {\tt b} will be evaluated before {\tt seq} returns a value.
2839      In particular, this means that {\tt b} may be evaluated before
2840      {\tt a}. If you need to guarantee a specific order of evaluation,
2841      you must use the function {\tt pseq} from the "parallel" package. }
2842
2843 pseudoop   "unsafeCoerce#"
2844    a -> b
2845    { The function {\tt unsafeCoerce\#} allows you to side-step the typechecker entirely. That
2846         is, it allows you to coerce any type into any other type. If you use this function,
2847         you had better get it right, otherwise segmentation faults await. It is generally
2848         used when you want to write a program that you know is well-typed, but where Haskell's
2849         type system is not expressive enough to prove that it is well typed.
2850
2851         The following uses of {\tt unsafeCoerce\#} are supposed to work (i.e. not lead to
2852         spurious compile-time or run-time crashes):
2853
2854          * Casting any lifted type to {\tt Any}
2855
2856          * Casting {\tt Any} back to the real type
2857
2858          * Casting an unboxed type to another unboxed type of the same size.
2859            (Casting between floating-point and integral types does not work.
2860            See the {\tt GHC.Float} module for functions to do work.)
2861
2862          * Casting between two types that have the same runtime representation.  One case is when
2863            the two types differ only in "phantom" type parameters, for example
2864            {\tt Ptr Int} to {\tt Ptr Float}, or {\tt [Int]} to {\tt [Float]} when the list is
2865            known to be empty.  Also, a {\tt newtype} of a type {\tt T} has the same representation
2866            at runtime as {\tt T}.
2867
2868         Other uses of {\tt unsafeCoerce\#} are undefined.  In particular, you should not use
2869         {\tt unsafeCoerce\#} to cast a T to an algebraic data type D, unless T is also
2870         an algebraic data type.  For example, do not cast {\tt Int->Int} to {\tt Bool}, even if
2871         you later cast that {\tt Bool} back to {\tt Int->Int} before applying it.  The reasons
2872         have to do with GHC's internal representation details (for the congnoscenti, data values
2873         can be entered but function closures cannot).  If you want a safe type to cast things
2874         to, use {\tt Any}, which is not an algebraic data type.
2875
2876         }
2877
2878 -- NB. It is tempting to think that casting a value to a type that it doesn't have is safe
2879 -- as long as you don't "do anything" with the value in its cast form, such as seq on it.  This
2880 -- isn't the case: the compiler can insert seqs itself, and if these happen at the wrong type,
2881 -- Bad Things Might Happen.  See bug #1616: in this case we cast a function of type (a,b) -> (a,b)
2882 -- to () -> () and back again.  The strictness analyser saw that the function was strict, but
2883 -- the wrapper had type () -> (), and hence the wrapper de-constructed the (), the worker re-constructed
2884 -- a new (), with the result that the code ended up with "case () of (a,b) -> ...".
2885
2886 primop  TraceEventOp "traceEvent#" GenPrimOp
2887    Addr# -> State# s -> State# s
2888    { Emits an event via the RTS tracing framework.  The contents
2889      of the event is the zero-terminated byte string passed as the first
2890      argument.  The event will be emitted either to the .eventlog file,
2891      or to stderr, depending on the runtime RTS flags. }
2892    with
2893    has_side_effects = True
2894    out_of_line      = True
2895
2896 primop  TraceMarkerOp "traceMarker#" GenPrimOp
2897    Addr# -> State# s -> State# s
2898    { Emits a marker event via the RTS tracing framework.  The contents
2899      of the event is the zero-terminated byte string passed as the first
2900      argument.  The event will be emitted either to the .eventlog file,
2901      or to stderr, depending on the runtime RTS flags. }
2902    with
2903    has_side_effects = True
2904    out_of_line      = True
2905
2906 ------------------------------------------------------------------------
2907 section "Safe coercions"
2908 ------------------------------------------------------------------------
2909
2910 pseudoop   "coerce"
2911    Coercible a b => a -> b
2912    { The function {\tt coerce} allows you to safely convert between values of
2913      types that have the same representation with no run-time overhead. In the
2914      simplest case you can use it instead of a newtype constructor, to go from
2915      the newtype's concrete type to the abstract type. But it also works in
2916      more complicated settings, e.g. converting a list of newtypes to a list of
2917      concrete types.
2918    }
2919
2920 ------------------------------------------------------------------------
2921 section "SIMD Vectors"
2922         {Operations on SIMD vectors.}
2923 ------------------------------------------------------------------------
2924
2925 #define ALL_VECTOR_TYPES \
2926   [<Int8,Int#,16>,<Int16,Int#,8>,<Int32,INT32,4>,<Int64,INT64,2> \
2927   ,<Int8,Int#,32>,<Int16,Int#,16>,<Int32,INT32,8>,<Int64,INT64,4> \
2928   ,<Int8,Int#,64>,<Int16,Int#,32>,<Int32,INT32,16>,<Int64,INT64,8> \
2929   ,<Word8,Word#,16>,<Word16,Word#,8>,<Word32,WORD32,4>,<Word64,WORD64,2> \
2930   ,<Word8,Word#,32>,<Word16,Word#,16>,<Word32,WORD32,8>,<Word64,WORD64,4> \
2931   ,<Word8,Word#,64>,<Word16,Word#,32>,<Word32,WORD32,16>,<Word64,WORD64,8> \
2932   ,<Float,Float#,4>,<Double,Double#,2> \
2933   ,<Float,Float#,8>,<Double,Double#,4> \
2934   ,<Float,Float#,16>,<Double,Double#,8>]
2935
2936 #define SIGNED_VECTOR_TYPES \
2937   [<Int8,Int#,16>,<Int16,Int#,8>,<Int32,INT32,4>,<Int64,INT64,2> \
2938   ,<Int8,Int#,32>,<Int16,Int#,16>,<Int32,INT32,8>,<Int64,INT64,4> \
2939   ,<Int8,Int#,64>,<Int16,Int#,32>,<Int32,INT32,16>,<Int64,INT64,8> \
2940   ,<Float,Float#,4>,<Double,Double#,2> \
2941   ,<Float,Float#,8>,<Double,Double#,4> \
2942   ,<Float,Float#,16>,<Double,Double#,8>]
2943
2944 #define FLOAT_VECTOR_TYPES \
2945   [<Float,Float#,4>,<Double,Double#,2> \
2946   ,<Float,Float#,8>,<Double,Double#,4> \
2947   ,<Float,Float#,16>,<Double,Double#,8>]
2948
2949 #define INT_VECTOR_TYPES \
2950   [<Int8,Int#,16>,<Int16,Int#,8>,<Int32,INT32,4>,<Int64,INT64,2> \
2951   ,<Int8,Int#,32>,<Int16,Int#,16>,<Int32,INT32,8>,<Int64,INT64,4> \
2952   ,<Int8,Int#,64>,<Int16,Int#,32>,<Int32,INT32,16>,<Int64,INT64,8> \
2953   ,<Word8,Word#,16>,<Word16,Word#,8>,<Word32,WORD32,4>,<Word64,WORD64,2> \
2954   ,<Word8,Word#,32>,<Word16,Word#,16>,<Word32,WORD32,8>,<Word64,WORD64,4> \
2955   ,<Word8,Word#,64>,<Word16,Word#,32>,<Word32,WORD32,16>,<Word64,WORD64,8>]
2956
2957 primtype VECTOR
2958    with llvm_only = True
2959         vector = ALL_VECTOR_TYPES
2960
2961 primop VecBroadcastOp "broadcast#" GenPrimOp
2962    SCALAR -> VECTOR
2963    { Broadcast a scalar to all elements of a vector. }
2964    with llvm_only = True
2965         vector = ALL_VECTOR_TYPES
2966
2967 primop VecPackOp "pack#" GenPrimOp
2968    VECTUPLE -> VECTOR
2969    { Pack the elements of an unboxed tuple into a vector. }
2970    with llvm_only = True
2971         vector = ALL_VECTOR_TYPES
2972
2973 primop VecUnpackOp "unpack#" GenPrimOp
2974    VECTOR -> VECTUPLE
2975    { Unpack the elements of a vector into an unboxed tuple. #}
2976    with llvm_only = True
2977         vector = ALL_VECTOR_TYPES
2978
2979 primop VecInsertOp "insert#" GenPrimOp
2980    VECTOR -> SCALAR -> Int# -> VECTOR
2981    { Insert a scalar at the given position in a vector. }
2982    with can_fail = True
2983         llvm_only = True
2984         vector = ALL_VECTOR_TYPES
2985
2986 primop VecAddOp "plus#" Dyadic
2987    VECTOR -> VECTOR -> VECTOR
2988    { Add two vectors element-wise. }
2989    with commutable = True
2990         llvm_only = True
2991         vector = ALL_VECTOR_TYPES
2992
2993 primop VecSubOp "minus#" Dyadic
2994    VECTOR -> VECTOR -> VECTOR
2995    { Subtract two vectors element-wise. }
2996    with llvm_only = True
2997         vector = ALL_VECTOR_TYPES
2998
2999 primop VecMulOp "times#" Dyadic
3000    VECTOR -> VECTOR -> VECTOR
3001    { Multiply two vectors element-wise. }
3002    with commutable = True
3003         llvm_only = True
3004         vector = ALL_VECTOR_TYPES
3005
3006 primop VecDivOp "divide#" Dyadic
3007    VECTOR -> VECTOR -> VECTOR
3008    { Divide two vectors element-wise. }
3009    with can_fail = True
3010         llvm_only = True
3011         vector = FLOAT_VECTOR_TYPES
3012
3013 primop VecQuotOp "quot#" Dyadic
3014    VECTOR -> VECTOR -> VECTOR
3015    { Rounds towards zero element-wise. }
3016    with can_fail = True
3017         llvm_only = True
3018         vector = INT_VECTOR_TYPES
3019
3020 primop VecRemOp "rem#" Dyadic
3021    VECTOR -> VECTOR -> VECTOR
3022    { Satisfies \texttt{(quot\# x y) times\# y plus\# (rem\# x y) == x}. }
3023    with can_fail = True
3024         llvm_only = True
3025         vector = INT_VECTOR_TYPES
3026
3027 primop VecNegOp "negate#" Monadic
3028    VECTOR -> VECTOR
3029    { Negate element-wise. }
3030    with llvm_only = True
3031         vector = SIGNED_VECTOR_TYPES
3032
3033 primop VecIndexByteArrayOp "indexArray#" GenPrimOp
3034    ByteArray# -> Int# -> VECTOR
3035    { Read a vector from specified index of immutable array. }
3036    with can_fail = True
3037         llvm_only = True
3038         vector = ALL_VECTOR_TYPES
3039
3040 primop VecReadByteArrayOp "readArray#" GenPrimOp
3041    MutableByteArray# s -> Int# -> State# s -> (# State# s, VECTOR #)
3042    { Read a vector from specified index of mutable array. }
3043    with has_side_effects = True
3044         can_fail = True
3045         llvm_only = True
3046         vector = ALL_VECTOR_TYPES
3047
3048 primop VecWriteByteArrayOp "writeArray#" GenPrimOp
3049    MutableByteArray# s -> Int# -> VECTOR -> State# s -> State# s
3050    { Write a vector to specified index of mutable array. }
3051    with has_side_effects = True
3052         can_fail = True
3053         llvm_only = True
3054         vector = ALL_VECTOR_TYPES
3055
3056 primop VecIndexOffAddrOp "indexOffAddr#" GenPrimOp
3057    Addr# -> Int# -> VECTOR
3058    { Reads vector; offset in bytes. }
3059    with can_fail = True
3060         llvm_only = True
3061         vector = ALL_VECTOR_TYPES
3062
3063 primop VecReadOffAddrOp "readOffAddr#" GenPrimOp
3064    Addr# -> Int# -> State# s -> (# State# s, VECTOR #)
3065    { Reads vector; offset in bytes. }
3066    with has_side_effects = True
3067         can_fail = True
3068         llvm_only = True
3069         vector = ALL_VECTOR_TYPES
3070
3071 primop VecWriteOffAddrOp "writeOffAddr#" GenPrimOp
3072    Addr# -> Int# -> VECTOR -> State# s -> State# s
3073    { Write vector; offset in bytes. }
3074    with has_side_effects = True
3075         can_fail = True
3076         llvm_only = True
3077         vector = ALL_VECTOR_TYPES
3078
3079
3080 primop VecIndexScalarByteArrayOp "indexArrayAs#" GenPrimOp
3081    ByteArray# -> Int# -> VECTOR
3082    { Read a vector from specified index of immutable array of scalars; offset is in scalar elements. }
3083    with can_fail = True
3084         llvm_only = True
3085         vector = ALL_VECTOR_TYPES
3086
3087 primop VecReadScalarByteArrayOp "readArrayAs#" GenPrimOp
3088    MutableByteArray# s -> Int# -> State# s -> (# State# s, VECTOR #)
3089    { Read a vector from specified index of mutable array of scalars; offset is in scalar elements. }
3090    with has_side_effects = True
3091         can_fail = True
3092         llvm_only = True
3093         vector = ALL_VECTOR_TYPES
3094
3095 primop VecWriteScalarByteArrayOp "writeArrayAs#" GenPrimOp
3096    MutableByteArray# s -> Int# -> VECTOR -> State# s -> State# s
3097    { Write a vector to specified index of mutable array of scalars; offset is in scalar elements. }
3098    with has_side_effects = True
3099         can_fail = True
3100         llvm_only = True
3101         vector = ALL_VECTOR_TYPES
3102
3103 primop VecIndexScalarOffAddrOp "indexOffAddrAs#" GenPrimOp
3104    Addr# -> Int# -> VECTOR
3105    { Reads vector; offset in scalar elements. }
3106    with can_fail = True
3107         llvm_only = True
3108         vector = ALL_VECTOR_TYPES
3109
3110 primop VecReadScalarOffAddrOp "readOffAddrAs#" GenPrimOp
3111    Addr# -> Int# -> State# s -> (# State# s, VECTOR #)
3112    { Reads vector; offset in scalar elements. }
3113    with has_side_effects = True
3114         can_fail = True
3115         llvm_only = True
3116         vector = ALL_VECTOR_TYPES
3117
3118 primop VecWriteScalarOffAddrOp "writeOffAddrAs#" GenPrimOp
3119    Addr# -> Int# -> VECTOR -> State# s -> State# s
3120    { Write vector; offset in scalar elements. }
3121    with has_side_effects = True
3122         can_fail = True
3123         llvm_only = True
3124         vector = ALL_VECTOR_TYPES
3125
3126 ------------------------------------------------------------------------
3127
3128 section "Prefetch"
3129         {Prefetch operations: Note how every prefetch operation has a name
3130   with the pattern prefetch*N#, where N is either 0,1,2, or 3.
3131
3132   This suffix number, N, is the "locality level" of the prefetch, following the
3133   convention in GCC and other compilers.
3134   Higher locality numbers correspond to the memory being loaded in more
3135   levels of the cpu cache, and being retained after initial use. The naming
3136   convention follows the naming convention of the prefetch intrinsic found
3137   in the GCC and Clang C compilers.
3138
3139   On the LLVM backend, prefetch*N# uses the LLVM prefetch intrinsic
3140   with locality level N. The code generated by LLVM is target architecture
3141   dependent, but should agree with the GHC NCG on x86 systems.
3142
3143   On the Sparc and PPC native backends, prefetch*N is a No-Op.
3144
3145   On the x86 NCG, N=0 will generate prefetchNTA,
3146   N=1 generates prefetcht2, N=2 generates prefetcht1, and
3147   N=3 generates prefetcht0.
3148
3149   For streaming workloads, the prefetch*0 operations are recommended.
3150   For workloads which do many reads or writes to a memory location in a short period of time,
3151   prefetch*3 operations are recommended.
3152
3153   For further reading about prefetch and associated systems performance optimization,
3154   the instruction set and optimization manuals by Intel and other CPU vendors are
3155   excellent starting place.
3156
3157
3158   The "Intel 64 and IA-32 Architectures Optimization Reference Manual" is
3159   especially a helpful read, even if your software is meant for other CPU
3160   architectures or vendor hardware. The manual can be found at
3161   http://www.intel.com/content/www/us/en/architecture-and-technology/64-ia-32-architectures-optimization-manual.html .
3162
3163   The {\tt prefetch*} family of operations has the order of operations
3164   determined by passing around the {\tt State#} token.
3165
3166   To get a "pure" version of these operations, use {\tt inlinePerformIO} which is quite safe in this context.
3167
3168   It is important to note that while the prefetch operations will never change the
3169   answer to a pure computation, They CAN change the memory locations resident
3170   in a CPU cache and that may change the performance and timing characteristics
3171   of an application. The prefetch operations are marked has_side_effects=True
3172   to reflect that these operations have side effects with respect to the runtime
3173   performance characteristics of the resulting code. Additionally, if the prefetchValue
3174   operations did not have this attribute, GHC does a float out transformation that
3175   results in a let/app violation, at least with the current design.
3176   }
3177
3178
3179
3180 ------------------------------------------------------------------------
3181
3182
3183 --- the Int# argument for prefetch is the byte offset on the byteArray or  Addr#
3184
3185 ---
3186 primop PrefetchByteArrayOp3 "prefetchByteArray3#" GenPrimOp
3187   ByteArray# -> Int# ->  State# s -> State# s
3188   with has_side_effects =  True
3189
3190 primop PrefetchMutableByteArrayOp3 "prefetchMutableByteArray3#" GenPrimOp
3191   MutableByteArray# s -> Int# -> State# s -> State# s
3192   with has_side_effects =  True
3193
3194 primop PrefetchAddrOp3 "prefetchAddr3#" GenPrimOp
3195   Addr# -> Int# -> State# s -> State# s
3196   with has_side_effects =  True
3197
3198 primop PrefetchValueOp3 "prefetchValue3#" GenPrimOp
3199    a -> State# s -> State# s
3200    with strictness  = { \ _arity -> mkClosedStrictSig [botDmd, topDmd] topRes }
3201         has_side_effects =  True
3202 ----
3203
3204 primop PrefetchByteArrayOp2 "prefetchByteArray2#" GenPrimOp
3205   ByteArray# -> Int# ->  State# s -> State# s
3206   with has_side_effects =  True
3207
3208 primop PrefetchMutableByteArrayOp2 "prefetchMutableByteArray2#" GenPrimOp
3209   MutableByteArray# s -> Int# -> State# s -> State# s
3210   with has_side_effects =  True
3211
3212 primop PrefetchAddrOp2 "prefetchAddr2#" GenPrimOp
3213   Addr# -> Int# ->  State# s -> State# s
3214   with has_side_effects =  True
3215
3216 primop PrefetchValueOp2 "prefetchValue2#" GenPrimOp
3217    a ->  State# s -> State# s
3218    with strictness  = { \ _arity -> mkClosedStrictSig [botDmd, topDmd] topRes }
3219         has_side_effects =  True
3220 ----
3221
3222 primop PrefetchByteArrayOp1 "prefetchByteArray1#" GenPrimOp
3223    ByteArray# -> Int# -> State# s -> State# s
3224    with has_side_effects =  True
3225
3226 primop PrefetchMutableByteArrayOp1 "prefetchMutableByteArray1#" GenPrimOp
3227   MutableByteArray# s -> Int# -> State# s -> State# s
3228   with has_side_effects =  True
3229
3230 primop PrefetchAddrOp1 "prefetchAddr1#" GenPrimOp
3231   Addr# -> Int# -> State# s -> State# s
3232   with has_side_effects =  True
3233
3234 primop PrefetchValueOp1 "prefetchValue1#" GenPrimOp
3235    a -> State# s -> State# s
3236    with strictness  = { \ _arity -> mkClosedStrictSig [botDmd, topDmd] topRes }
3237         has_side_effects =  True
3238 ----
3239
3240 primop PrefetchByteArrayOp0 "prefetchByteArray0#" GenPrimOp
3241   ByteArray# -> Int# ->  State# s -> State# s
3242   with has_side_effects =  True
3243
3244 primop PrefetchMutableByteArrayOp0 "prefetchMutableByteArray0#" GenPrimOp
3245   MutableByteArray# s -> Int# -> State# s -> State# s
3246   with has_side_effects =  True
3247
3248 primop PrefetchAddrOp0 "prefetchAddr0#" GenPrimOp
3249   Addr# -> Int# -> State# s -> State# s
3250   with has_side_effects =  True
3251
3252 primop PrefetchValueOp0 "prefetchValue0#" GenPrimOp
3253    a -> State# s -> State# s
3254    with strictness  = { \ _arity -> mkClosedStrictSig [botDmd, topDmd] topRes }
3255         has_side_effects =  True
3256
3257 ------------------------------------------------------------------------
3258 ---                                                                  ---
3259 ------------------------------------------------------------------------
3260
3261 thats_all_folks