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