Fix #9097.
[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 recommmended 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.}
225    with can_fail = True
226
227 primop   IntRemOp    "remInt#"    Dyadic
228    Int# -> Int# -> Int#
229    {Satisfies \texttt{(quotInt\# x y) *\# y +\# (remInt\# x y) == x}.}
230    with can_fail = True
231
232 primop   IntQuotRemOp "quotRemInt#"    GenPrimOp
233    Int# -> Int# -> (# Int#, Int# #)
234    {Rounds towards zero.}
235    with can_fail = True
236
237 primop   AndIOp   "andI#"   Dyadic    Int# -> Int# -> Int#
238    with commutable = True
239
240 primop   OrIOp   "orI#"     Dyadic    Int# -> Int# -> Int#
241    with commutable = True
242
243 primop   XorIOp   "xorI#"   Dyadic    Int# -> Int# -> Int#
244    with commutable = True
245
246 primop   NotIOp   "notI#"   Monadic   Int# -> Int#
247
248 primop   IntNegOp    "negateInt#"    Monadic   Int# -> Int#
249 primop   IntAddCOp   "addIntC#"    GenPrimOp   Int# -> Int# -> (# Int#, Int# #)
250          {Add with carry.  First member of result is (wrapped) sum;
251           second member is 0 iff no overflow occured.}
252    with code_size = 2
253
254 primop   IntSubCOp   "subIntC#"    GenPrimOp   Int# -> Int# -> (# Int#, Int# #)
255          {Subtract with carry.  First member of result is (wrapped) difference;
256           second member is 0 iff no overflow occured.}
257    with code_size = 2
258
259 primop   IntGtOp  ">#"   Compare   Int# -> Int# -> Int#
260    with fixity = infix 4
261
262 primop   IntGeOp  ">=#"   Compare   Int# -> Int# -> Int#
263    with fixity = infix 4
264
265 primop   IntEqOp  "==#"   Compare
266    Int# -> Int# -> Int#
267    with commutable = True
268         fixity = infix 4
269
270 primop   IntNeOp  "/=#"   Compare
271    Int# -> Int# -> Int#
272    with commutable = True
273         fixity = infix 4
274
275 primop   IntLtOp  "<#"   Compare   Int# -> Int# -> Int#
276    with fixity = infix 4
277
278 primop   IntLeOp  "<=#"   Compare   Int# -> Int# -> Int#
279    with fixity = infix 4
280
281 primop   ChrOp   "chr#"   GenPrimOp   Int# -> Char#
282    with code_size = 0
283
284 primop   Int2WordOp "int2Word#" GenPrimOp Int# -> Word#
285    with code_size = 0
286
287 primop   Int2FloatOp   "int2Float#"      GenPrimOp  Int# -> Float#
288 primop   Int2DoubleOp   "int2Double#"          GenPrimOp  Int# -> Double#
289
290 primop   Word2FloatOp   "word2Float#"      GenPrimOp  Word# -> Float#
291 primop   Word2DoubleOp   "word2Double#"          GenPrimOp  Word# -> Double#
292
293 primop   ISllOp   "uncheckedIShiftL#" GenPrimOp  Int# -> Int# -> Int#
294          {Shift left.  Result undefined if shift amount is not
295           in the range 0 to word size - 1 inclusive.}
296 primop   ISraOp   "uncheckedIShiftRA#" GenPrimOp Int# -> Int# -> Int#
297          {Shift right arithmetic.  Result undefined if shift amount is not
298           in the range 0 to word size - 1 inclusive.}
299 primop   ISrlOp   "uncheckedIShiftRL#" GenPrimOp Int# -> Int# -> Int#
300          {Shift right logical.  Result undefined if shift amount is not
301           in the range 0 to word size - 1 inclusive.}
302
303 ------------------------------------------------------------------------
304 section "Word#"
305         {Operations on native-sized unsigned words (30+ bits).}
306 ------------------------------------------------------------------------
307
308 primtype Word#
309
310 primop   WordAddOp   "plusWord#"   Dyadic   Word# -> Word# -> Word#
311    with commutable = True
312
313 -- Returns (# high, low #) (or equivalently, (# carry, low #))
314 primop   WordAdd2Op  "plusWord2#"  GenPrimOp
315    Word# -> Word# -> (# Word#, Word# #)
316    with commutable = True
317
318 primop   WordSubOp   "minusWord#"   Dyadic   Word# -> Word# -> Word#
319
320 primop   WordMulOp   "timesWord#"   Dyadic   Word# -> Word# -> Word#
321    with commutable = True
322
323 -- Returns (# high, low #)
324 primop   WordMul2Op  "timesWord2#"   GenPrimOp
325    Word# -> Word# -> (# Word#, Word# #)
326    with commutable = True
327
328 primop   WordQuotOp   "quotWord#"   Dyadic   Word# -> Word# -> Word#
329    with can_fail = True
330
331 primop   WordRemOp   "remWord#"   Dyadic   Word# -> Word# -> Word#
332    with can_fail = True
333
334 primop   WordQuotRemOp "quotRemWord#" GenPrimOp
335    Word# -> Word# -> (# Word#, Word# #)
336    with can_fail = True
337
338 -- Takes high word of dividend, then low word of dividend, then divisor.
339 -- Requires that high word is not divisible by divisor.
340 primop   WordQuotRem2Op "quotRemWord2#" GenPrimOp
341    Word# -> Word# -> Word# -> (# Word#, Word# #)
342    with can_fail = True
343
344 primop   AndOp   "and#"   Dyadic   Word# -> Word# -> Word#
345    with commutable = True
346
347 primop   OrOp   "or#"   Dyadic   Word# -> Word# -> Word#
348    with commutable = True
349
350 primop   XorOp   "xor#"   Dyadic   Word# -> Word# -> Word#
351    with commutable = True
352
353 primop   NotOp   "not#"   Monadic   Word# -> Word#
354
355 primop   SllOp   "uncheckedShiftL#"   GenPrimOp   Word# -> Int# -> Word#
356          {Shift left logical.   Result undefined if shift amount is not
357           in the range 0 to word size - 1 inclusive.}
358 primop   SrlOp   "uncheckedShiftRL#"   GenPrimOp   Word# -> Int# -> Word#
359          {Shift right logical.   Result undefined if shift  amount is not
360           in the range 0 to word size - 1 inclusive.}
361
362 primop   Word2IntOp   "word2Int#"   GenPrimOp   Word# -> Int#
363    with code_size = 0
364
365 primop   WordGtOp   "gtWord#"   Compare   Word# -> Word# -> Int#
366 primop   WordGeOp   "geWord#"   Compare   Word# -> Word# -> Int#
367 primop   WordEqOp   "eqWord#"   Compare   Word# -> Word# -> Int#
368 primop   WordNeOp   "neWord#"   Compare   Word# -> Word# -> Int#
369 primop   WordLtOp   "ltWord#"   Compare   Word# -> Word# -> Int#
370 primop   WordLeOp   "leWord#"   Compare   Word# -> Word# -> Int#
371
372 primop   PopCnt8Op   "popCnt8#"   Monadic   Word# -> Word#
373     {Count the number of set bits in the lower 8 bits of a word.}
374 primop   PopCnt16Op   "popCnt16#"   Monadic   Word# -> Word#
375     {Count the number of set bits in the lower 16 bits of a word.}
376 primop   PopCnt32Op   "popCnt32#"   Monadic   Word# -> Word#
377     {Count the number of set bits in the lower 32 bits of a word.}
378 primop   PopCnt64Op   "popCnt64#"   GenPrimOp   WORD64 -> Word#
379     {Count the number of set bits in a 64-bit word.}
380 primop   PopCntOp   "popCnt#"   Monadic   Word# -> Word#
381     {Count the number of set bits in a word.}
382
383 primop   BSwap16Op   "byteSwap16#"   Monadic   Word# -> Word#
384     {Swap bytes in the lower 16 bits of a word. The higher bytes are undefined. }
385 primop   BSwap32Op   "byteSwap32#"   Monadic   Word# -> Word#
386     {Swap bytes in the lower 32 bits of a word. The higher bytes are undefined. }
387 primop   BSwap64Op   "byteSwap64#"   Monadic   WORD64 -> WORD64
388     {Swap bytes in a 64 bits of a word.}
389 primop   BSwapOp     "byteSwap#"     Monadic   Word# -> Word#
390     {Swap bytes in a word.}
391
392 ------------------------------------------------------------------------
393 section "Narrowings"
394         {Explicit narrowing of native-sized ints or words.}
395 ------------------------------------------------------------------------
396
397 primop   Narrow8IntOp      "narrow8Int#"      Monadic   Int# -> Int#
398 primop   Narrow16IntOp     "narrow16Int#"     Monadic   Int# -> Int#
399 primop   Narrow32IntOp     "narrow32Int#"     Monadic   Int# -> Int#
400 primop   Narrow8WordOp     "narrow8Word#"     Monadic   Word# -> Word#
401 primop   Narrow16WordOp    "narrow16Word#"    Monadic   Word# -> Word#
402 primop   Narrow32WordOp    "narrow32Word#"    Monadic   Word# -> Word#
403
404
405 #if WORD_SIZE_IN_BITS < 32
406 ------------------------------------------------------------------------
407 section "Int32#"
408         {Operations on 32-bit integers ({\tt Int32\#}).  This type is only used
409          if plain {\tt Int\#} has less than 32 bits.  In any case, the operations
410          are not primops; they are implemented (if needed) as ccalls instead.}
411 ------------------------------------------------------------------------
412
413 primtype Int32#
414
415 ------------------------------------------------------------------------
416 section "Word32#"
417         {Operations on 32-bit unsigned words. This type is only used
418          if plain {\tt Word\#} has less than 32 bits. In any case, the operations
419          are not primops; they are implemented (if needed) as ccalls instead.}
420 ------------------------------------------------------------------------
421
422 primtype Word32#
423
424 #endif
425
426
427 #if WORD_SIZE_IN_BITS < 64
428 ------------------------------------------------------------------------
429 section "Int64#"
430         {Operations on 64-bit unsigned words. This type is only used
431          if plain {\tt Int\#} has less than 64 bits. In any case, the operations
432          are not primops; they are implemented (if needed) as ccalls instead.}
433 ------------------------------------------------------------------------
434
435 primtype Int64#
436
437 ------------------------------------------------------------------------
438 section "Word64#"
439         {Operations on 64-bit unsigned words. This type is only used
440          if plain {\tt Word\#} has less than 64 bits. In any case, the operations
441          are not primops; they are implemented (if needed) as ccalls instead.}
442 ------------------------------------------------------------------------
443
444 primtype Word64#
445
446 #endif
447
448 ------------------------------------------------------------------------
449 section "Double#"
450         {Operations on double-precision (64 bit) floating-point numbers.}
451 ------------------------------------------------------------------------
452
453 primtype Double#
454
455 primop   DoubleGtOp ">##"   Compare   Double# -> Double# -> Int#
456    with fixity = infix 4
457
458 primop   DoubleGeOp ">=##"   Compare   Double# -> Double# -> Int#
459    with fixity = infix 4
460
461 primop DoubleEqOp "==##"   Compare
462    Double# -> Double# -> Int#
463    with commutable = True
464         fixity = infix 4
465
466 primop DoubleNeOp "/=##"   Compare
467    Double# -> Double# -> Int#
468    with commutable = True
469         fixity = infix 4
470
471 primop   DoubleLtOp "<##"   Compare   Double# -> Double# -> Int#
472    with fixity = infix 4
473
474 primop   DoubleLeOp "<=##"   Compare   Double# -> Double# -> Int#
475    with fixity = infix 4
476
477 primop   DoubleAddOp   "+##"   Dyadic
478    Double# -> Double# -> Double#
479    with commutable = True
480         fixity = infixl 6
481
482 primop   DoubleSubOp   "-##"   Dyadic   Double# -> Double# -> Double#
483    with fixity = infixl 6
484
485 primop   DoubleMulOp   "*##"   Dyadic
486    Double# -> Double# -> Double#
487    with commutable = True
488         fixity = infixl 7
489
490 primop   DoubleDivOp   "/##"   Dyadic
491    Double# -> Double# -> Double#
492    with can_fail = True
493         fixity = infixl 7
494
495 primop   DoubleNegOp   "negateDouble#"  Monadic   Double# -> Double#
496
497 primop   Double2IntOp   "double2Int#"          GenPrimOp  Double# -> Int#
498    {Truncates a {\tt Double#} value to the nearest {\tt Int#}.
499     Results are undefined if the truncation if truncation yields
500     a value outside the range of {\tt Int#}.}
501
502 primop   Double2FloatOp   "double2Float#" GenPrimOp Double# -> Float#
503
504 primop   DoubleExpOp   "expDouble#"      Monadic
505    Double# -> Double#
506    with
507    code_size = { primOpCodeSizeForeignCall }
508
509 primop   DoubleLogOp   "logDouble#"      Monadic
510    Double# -> Double#
511    with
512    code_size = { primOpCodeSizeForeignCall }
513    can_fail = True
514
515 primop   DoubleSqrtOp   "sqrtDouble#"      Monadic
516    Double# -> Double#
517    with
518    code_size = { primOpCodeSizeForeignCall }
519
520 primop   DoubleSinOp   "sinDouble#"      Monadic
521    Double# -> Double#
522    with
523    code_size = { primOpCodeSizeForeignCall }
524
525 primop   DoubleCosOp   "cosDouble#"      Monadic
526    Double# -> Double#
527    with
528    code_size = { primOpCodeSizeForeignCall }
529
530 primop   DoubleTanOp   "tanDouble#"      Monadic
531    Double# -> Double#
532    with
533    code_size = { primOpCodeSizeForeignCall }
534
535 primop   DoubleAsinOp   "asinDouble#"      Monadic
536    Double# -> Double#
537    with
538    code_size = { primOpCodeSizeForeignCall }
539    can_fail = True
540
541 primop   DoubleAcosOp   "acosDouble#"      Monadic
542    Double# -> Double#
543    with
544    code_size = { primOpCodeSizeForeignCall }
545    can_fail = True
546
547 primop   DoubleAtanOp   "atanDouble#"      Monadic
548    Double# -> Double#
549    with
550    code_size = { primOpCodeSizeForeignCall }
551
552 primop   DoubleSinhOp   "sinhDouble#"      Monadic
553    Double# -> Double#
554    with
555    code_size = { primOpCodeSizeForeignCall }
556
557 primop   DoubleCoshOp   "coshDouble#"      Monadic
558    Double# -> Double#
559    with
560    code_size = { primOpCodeSizeForeignCall }
561
562 primop   DoubleTanhOp   "tanhDouble#"      Monadic
563    Double# -> Double#
564    with
565    code_size = { primOpCodeSizeForeignCall }
566
567 primop   DoublePowerOp   "**##" Dyadic
568    Double# -> Double# -> Double#
569    {Exponentiation.}
570    with
571    code_size = { primOpCodeSizeForeignCall }
572
573 primop   DoubleDecode_2IntOp   "decodeDouble_2Int#" GenPrimOp
574    Double# -> (# Int#, Word#, Word#, Int# #)
575    {Convert to integer.
576     First component of the result is -1 or 1, indicating the sign of the
577     mantissa. The next two are the high and low 32 bits of the mantissa
578     respectively, and the last is the exponent.}
579    with out_of_line = True
580
581 ------------------------------------------------------------------------
582 section "Float#"
583         {Operations on single-precision (32-bit) floating-point numbers.}
584 ------------------------------------------------------------------------
585
586 primtype Float#
587
588 primop   FloatGtOp  "gtFloat#"   Compare   Float# -> Float# -> Int#
589 primop   FloatGeOp  "geFloat#"   Compare   Float# -> Float# -> Int#
590
591 primop   FloatEqOp  "eqFloat#"   Compare
592    Float# -> Float# -> Int#
593    with commutable = True
594
595 primop   FloatNeOp  "neFloat#"   Compare
596    Float# -> Float# -> Int#
597    with commutable = True
598
599 primop   FloatLtOp  "ltFloat#"   Compare   Float# -> Float# -> Int#
600 primop   FloatLeOp  "leFloat#"   Compare   Float# -> Float# -> Int#
601
602 primop   FloatAddOp   "plusFloat#"      Dyadic
603    Float# -> Float# -> Float#
604    with commutable = True
605
606 primop   FloatSubOp   "minusFloat#"      Dyadic      Float# -> Float# -> Float#
607
608 primop   FloatMulOp   "timesFloat#"      Dyadic
609    Float# -> Float# -> Float#
610    with commutable = True
611
612 primop   FloatDivOp   "divideFloat#"      Dyadic
613    Float# -> Float# -> Float#
614    with can_fail = True
615
616 primop   FloatNegOp   "negateFloat#"      Monadic    Float# -> Float#
617
618 primop   Float2IntOp   "float2Int#"      GenPrimOp  Float# -> Int#
619    {Truncates a {\tt Float#} value to the nearest {\tt Int#}.
620     Results are undefined if the truncation if truncation yields
621     a value outside the range of {\tt Int#}.}
622
623 primop   FloatExpOp   "expFloat#"      Monadic
624    Float# -> Float#
625    with
626    code_size = { primOpCodeSizeForeignCall }
627
628 primop   FloatLogOp   "logFloat#"      Monadic
629    Float# -> Float#
630    with
631    code_size = { primOpCodeSizeForeignCall }
632    can_fail = True
633
634 primop   FloatSqrtOp   "sqrtFloat#"      Monadic
635    Float# -> Float#
636    with
637    code_size = { primOpCodeSizeForeignCall }
638
639 primop   FloatSinOp   "sinFloat#"      Monadic
640    Float# -> Float#
641    with
642    code_size = { primOpCodeSizeForeignCall }
643
644 primop   FloatCosOp   "cosFloat#"      Monadic
645    Float# -> Float#
646    with
647    code_size = { primOpCodeSizeForeignCall }
648
649 primop   FloatTanOp   "tanFloat#"      Monadic
650    Float# -> Float#
651    with
652    code_size = { primOpCodeSizeForeignCall }
653
654 primop   FloatAsinOp   "asinFloat#"      Monadic
655    Float# -> Float#
656    with
657    code_size = { primOpCodeSizeForeignCall }
658    can_fail = True
659
660 primop   FloatAcosOp   "acosFloat#"      Monadic
661    Float# -> Float#
662    with
663    code_size = { primOpCodeSizeForeignCall }
664    can_fail = True
665
666 primop   FloatAtanOp   "atanFloat#"      Monadic
667    Float# -> Float#
668    with
669    code_size = { primOpCodeSizeForeignCall }
670
671 primop   FloatSinhOp   "sinhFloat#"      Monadic
672    Float# -> Float#
673    with
674    code_size = { primOpCodeSizeForeignCall }
675
676 primop   FloatCoshOp   "coshFloat#"      Monadic
677    Float# -> Float#
678    with
679    code_size = { primOpCodeSizeForeignCall }
680
681 primop   FloatTanhOp   "tanhFloat#"      Monadic
682    Float# -> Float#
683    with
684    code_size = { primOpCodeSizeForeignCall }
685
686 primop   FloatPowerOp   "powerFloat#"      Dyadic
687    Float# -> Float# -> Float#
688    with
689    code_size = { primOpCodeSizeForeignCall }
690
691 primop   Float2DoubleOp   "float2Double#" GenPrimOp  Float# -> Double#
692
693 primop   FloatDecode_IntOp   "decodeFloat_Int#" GenPrimOp
694    Float# -> (# Int#, Int# #)
695    {Convert to integers.
696     First {\tt Int\#} in result is the mantissa; second is the exponent.}
697    with out_of_line = True
698
699 ------------------------------------------------------------------------
700 section "Arrays"
701         {Operations on {\tt Array\#}.}
702 ------------------------------------------------------------------------
703
704 primtype Array# a
705
706 primtype MutableArray# s a
707
708 primop  NewArrayOp "newArray#" GenPrimOp
709    Int# -> a -> State# s -> (# State# s, MutableArray# s a #)
710    {Create a new mutable array with the specified number of elements,
711     in the specified state thread,
712     with each element containing the specified initial value.}
713    with
714    out_of_line = True
715    has_side_effects = True
716
717 primop  SameMutableArrayOp "sameMutableArray#" GenPrimOp
718    MutableArray# s a -> MutableArray# s a -> Int#
719
720 primop  ReadArrayOp "readArray#" GenPrimOp
721    MutableArray# s a -> Int# -> State# s -> (# State# s, a #)
722    {Read from specified index of mutable array. Result is not yet evaluated.}
723    with
724    has_side_effects = True
725    can_fail         = True
726
727 primop  WriteArrayOp "writeArray#" GenPrimOp
728    MutableArray# s a -> Int# -> a -> State# s -> State# s
729    {Write to specified index of mutable array.}
730    with
731    has_side_effects = True
732    can_fail         = True
733    code_size        = 2 -- card update too
734
735 primop  SizeofArrayOp "sizeofArray#" GenPrimOp
736    Array# a -> Int#
737    {Return the number of elements in the array.}
738
739 primop  SizeofMutableArrayOp "sizeofMutableArray#" GenPrimOp
740    MutableArray# s a -> Int#
741    {Return the number of elements in the array.}
742
743 primop  IndexArrayOp "indexArray#" GenPrimOp
744    Array# a -> Int# -> (# a #)
745    {Read from specified index of immutable array. Result is packaged into
746     an unboxed singleton; the result itself is not yet evaluated.}
747    with
748    can_fail         = True
749
750 primop  UnsafeFreezeArrayOp "unsafeFreezeArray#" GenPrimOp
751    MutableArray# s a -> State# s -> (# State# s, Array# a #)
752    {Make a mutable array immutable, without copying.}
753    with
754    has_side_effects = True
755
756 primop  UnsafeThawArrayOp  "unsafeThawArray#" GenPrimOp
757    Array# a -> State# s -> (# State# s, MutableArray# s a #)
758    {Make an immutable array mutable, without copying.}
759    with
760    out_of_line = True
761    has_side_effects = True
762
763 primop  CopyArrayOp "copyArray#" GenPrimOp
764   Array# a -> Int# -> MutableArray# s a -> Int# -> Int# -> State# s -> State# s
765   {Given a source array, an offset into the source array, a
766    destination array, an offset into the destination array, and a
767    number of elements to copy, copy the elements from the source array
768    to the destination array. Both arrays must fully contain the
769    specified ranges, but this is not checked. The two arrays must not
770    be the same array in different states, but this is not checked
771    either.}
772   with
773   out_of_line      = True
774   has_side_effects = True
775   can_fail         = True
776
777 primop  CopyMutableArrayOp "copyMutableArray#" GenPrimOp
778   MutableArray# s a -> Int# -> MutableArray# s a -> Int# -> Int# -> State# s -> State# s
779   {Given a source array, an offset into the source array, a
780    destination array, an offset into the destination array, and a
781    number of elements to copy, copy the elements from the source array
782    to the destination array. The source and destination arrays can
783    refer to the same array. Both arrays must fully contain the
784    specified ranges, but this is not checked.}
785   with
786   out_of_line      = True
787   has_side_effects = True
788   can_fail         = True
789
790 primop  CloneArrayOp "cloneArray#" GenPrimOp
791   Array# a -> Int# -> Int# -> Array# a
792   {Given a source array, an offset into the source array, and a number
793    of elements to copy, create a new array with the elements from the
794    source array. The provided array must fully contain the specified
795    range, but this is not checked.}
796   with
797   out_of_line      = True
798   has_side_effects = True
799   can_fail         = True
800
801 primop  CloneMutableArrayOp "cloneMutableArray#" GenPrimOp
802   MutableArray# s a -> Int# -> Int# -> State# s -> (# State# s, MutableArray# s a #)
803   {Given a source array, an offset into the source array, and a number
804    of elements to copy, create a new array with the elements from the
805    source array. The provided array must fully contain the specified
806    range, but this is not checked.}
807   with
808   out_of_line      = True
809   has_side_effects = True
810   can_fail         = True
811
812 primop  FreezeArrayOp "freezeArray#" GenPrimOp
813   MutableArray# s a -> Int# -> Int# -> State# s -> (# State# s, Array# a #)
814   {Given a source array, an offset into the source array, and a number
815    of elements to copy, create a new array with the elements from the
816    source array. The provided array must fully contain the specified
817    range, but this is not checked.}
818   with
819   out_of_line      = True
820   has_side_effects = True
821   can_fail         = True
822
823 primop  ThawArrayOp "thawArray#" GenPrimOp
824   Array# a -> Int# -> Int# -> State# s -> (# State# s, MutableArray# s a #)
825   {Given a source array, an offset into the source array, and a number
826    of elements to copy, create a new array with the elements from the
827    source array. The provided array must fully contain the specified
828    range, but this is not checked.}
829   with
830   out_of_line      = True
831   has_side_effects = True
832   can_fail         = True
833
834 primop CasArrayOp  "casArray#" GenPrimOp
835    MutableArray# s a -> Int# -> a -> a -> State# s -> (# State# s, Int#, a #)
836    {Unsafe, machine-level atomic compare and swap on an element within an Array.}
837    with
838    out_of_line = True
839    has_side_effects = True
840
841
842 ------------------------------------------------------------------------
843 section "Small Arrays"
844
845         {Operations on {\tt SmallArray\#}. A {\tt SmallArray\#} works
846          just like an {\tt Array\#}, but with different space use and
847          performance characteristics (that are often useful with small
848          arrays). The {\tt SmallArray\#} and {\tt SmallMutableArray#}
849          lack a `card table'. The purpose of a card table is to avoid
850          having to scan every element of the array on each GC by
851          keeping track of which elements have changed since the last GC
852          and only scanning those that have changed. So the consequence
853          of there being no card table is that the representation is
854          somewhat smaller and the writes are somewhat faster (because
855          the card table does not need to be updated). The disadvantage
856          of course is that for a {\tt SmallMutableArray#} the whole
857          array has to be scanned on each GC. Thus it is best suited for
858          use cases where the mutable array is not long lived, e.g.
859          where a mutable array is initialised quickly and then frozen
860          to become an immutable {\tt SmallArray\#}.
861         }
862
863 ------------------------------------------------------------------------
864
865 primtype SmallArray# a
866
867 primtype SmallMutableArray# s a
868
869 primop  NewSmallArrayOp "newSmallArray#" GenPrimOp
870    Int# -> a -> State# s -> (# State# s, SmallMutableArray# s a #)
871    {Create a new mutable array with the specified number of elements,
872     in the specified state thread,
873     with each element containing the specified initial value.}
874    with
875    out_of_line = True
876    has_side_effects = True
877
878 primop  SameSmallMutableArrayOp "sameSmallMutableArray#" GenPrimOp
879    SmallMutableArray# s a -> SmallMutableArray# s a -> Int#
880
881 primop  ReadSmallArrayOp "readSmallArray#" GenPrimOp
882    SmallMutableArray# s a -> Int# -> State# s -> (# State# s, a #)
883    {Read from specified index of mutable array. Result is not yet evaluated.}
884    with
885    has_side_effects = True
886    can_fail         = True
887
888 primop  WriteSmallArrayOp "writeSmallArray#" GenPrimOp
889    SmallMutableArray# s a -> Int# -> a -> State# s -> State# s
890    {Write to specified index of mutable array.}
891    with
892    has_side_effects = True
893    can_fail         = True
894
895 primop  SizeofSmallArrayOp "sizeofSmallArray#" GenPrimOp
896    SmallArray# a -> Int#
897    {Return the number of elements in the array.}
898
899 primop  SizeofSmallMutableArrayOp "sizeofSmallMutableArray#" GenPrimOp
900    SmallMutableArray# s a -> Int#
901    {Return the number of elements in the array.}
902
903 primop  IndexSmallArrayOp "indexSmallArray#" GenPrimOp
904    SmallArray# a -> Int# -> (# a #)
905    {Read from specified index of immutable array. Result is packaged into
906     an unboxed singleton; the result itself is not yet evaluated.}
907    with
908    can_fail         = True
909
910 primop  UnsafeFreezeSmallArrayOp "unsafeFreezeSmallArray#" GenPrimOp
911    SmallMutableArray# s a -> State# s -> (# State# s, SmallArray# a #)
912    {Make a mutable array immutable, without copying.}
913    with
914    has_side_effects = True
915
916 primop  UnsafeThawSmallArrayOp  "unsafeThawSmallArray#" GenPrimOp
917    SmallArray# a -> State# s -> (# State# s, SmallMutableArray# s a #)
918    {Make an immutable array mutable, without copying.}
919    with
920    out_of_line = True
921    has_side_effects = True
922
923 -- The code_size is only correct for the case when the copy family of
924 -- primops aren't inlined. It would be nice to keep track of both.
925
926 primop  CopySmallArrayOp "copySmallArray#" GenPrimOp
927   SmallArray# a -> Int# -> SmallMutableArray# s a -> Int# -> Int# -> State# s -> State# s
928   {Given a source array, an offset into the source array, a
929    destination array, an offset into the destination array, and a
930    number of elements to copy, copy the elements from the source array
931    to the destination array. Both arrays must fully contain the
932    specified ranges, but this is not checked. The two arrays must not
933    be the same array in different states, but this is not checked
934    either.}
935   with
936   out_of_line      = True
937   has_side_effects = True
938   can_fail         = True
939
940 primop  CopySmallMutableArrayOp "copySmallMutableArray#" GenPrimOp
941   SmallMutableArray# s a -> Int# -> SmallMutableArray# s a -> Int# -> Int# -> State# s -> State# s
942   {Given a source array, an offset into the source array, a
943    destination array, an offset into the destination array, and a
944    number of elements to copy, copy the elements from the source array
945    to the destination array. The source and destination arrays can
946    refer to the same array. Both arrays must fully contain the
947    specified ranges, but this is not checked.}
948   with
949   out_of_line      = True
950   has_side_effects = True
951   can_fail         = True
952
953 primop  CloneSmallArrayOp "cloneSmallArray#" GenPrimOp
954   SmallArray# a -> Int# -> Int# -> SmallArray# a
955   {Given a source array, an offset into the source array, and a number
956    of elements to copy, create a new array with the elements from the
957    source array. The provided array must fully contain the specified
958    range, but this is not checked.}
959   with
960   out_of_line      = True
961   has_side_effects = True
962   can_fail         = True
963
964 primop  CloneSmallMutableArrayOp "cloneSmallMutableArray#" GenPrimOp
965   SmallMutableArray# s a -> Int# -> Int# -> State# s -> (# State# s, SmallMutableArray# s a #)
966   {Given a source array, an offset into the source array, and a number
967    of elements to copy, create a new array with the elements from the
968    source array. The provided array must fully contain the specified
969    range, but this is not checked.}
970   with
971   out_of_line      = True
972   has_side_effects = True
973   can_fail         = True
974
975 primop  FreezeSmallArrayOp "freezeSmallArray#" GenPrimOp
976   SmallMutableArray# s a -> Int# -> Int# -> State# s -> (# State# s, SmallArray# a #)
977   {Given a source array, an offset into the source array, and a number
978    of elements to copy, create a new array with the elements from the
979    source array. The provided array must fully contain the specified
980    range, but this is not checked.}
981   with
982   out_of_line      = True
983   has_side_effects = True
984   can_fail         = True
985
986 primop  ThawSmallArrayOp "thawSmallArray#" GenPrimOp
987   SmallArray# a -> Int# -> Int# -> State# s -> (# State# s, SmallMutableArray# s a #)
988   {Given a source array, an offset into the source array, and a number
989    of elements to copy, create a new array with the elements from the
990    source array. The provided array must fully contain the specified
991    range, but this is not checked.}
992   with
993   out_of_line      = True
994   has_side_effects = True
995   can_fail         = True
996
997 primop CasSmallArrayOp  "casSmallArray#" GenPrimOp
998    SmallMutableArray# s a -> Int# -> a -> a -> State# s -> (# State# s, Int#, a #)
999    {Unsafe, machine-level atomic compare and swap on an element within an array.}
1000    with
1001    out_of_line = True
1002    has_side_effects = True
1003
1004 ------------------------------------------------------------------------
1005 section "Byte Arrays"
1006         {Operations on {\tt ByteArray\#}. A {\tt ByteArray\#} is a just a region of
1007          raw memory in the garbage-collected heap, which is not
1008          scanned for pointers. It carries its own size (in bytes).
1009          There are
1010          three sets of operations for accessing byte array contents:
1011          index for reading from immutable byte arrays, and read/write
1012          for mutable byte arrays.  Each set contains operations for a
1013          range of useful primitive data types.  Each operation takes
1014          an offset measured in terms of the size of the primitive type
1015          being read or written.}
1016
1017 ------------------------------------------------------------------------
1018
1019 primtype ByteArray#
1020
1021 primtype MutableByteArray# s
1022
1023 primop  NewByteArrayOp_Char "newByteArray#" GenPrimOp
1024    Int# -> State# s -> (# State# s, MutableByteArray# s #)
1025    {Create a new mutable byte array of specified size (in bytes), in
1026     the specified state thread.}
1027    with out_of_line = True
1028         has_side_effects = True
1029
1030 primop  NewPinnedByteArrayOp_Char "newPinnedByteArray#" GenPrimOp
1031    Int# -> State# s -> (# State# s, MutableByteArray# s #)
1032    {Create a mutable byte array that the GC guarantees not to move.}
1033    with out_of_line = True
1034         has_side_effects = True
1035
1036 primop  NewAlignedPinnedByteArrayOp_Char "newAlignedPinnedByteArray#" GenPrimOp
1037    Int# -> Int# -> State# s -> (# State# s, MutableByteArray# s #)
1038    {Create a mutable byte array, aligned by the specified amount, that the GC guarantees not to move.}
1039    with out_of_line = True
1040         has_side_effects = True
1041
1042 primop  ByteArrayContents_Char "byteArrayContents#" GenPrimOp
1043    ByteArray# -> Addr#
1044    {Intended for use with pinned arrays; otherwise very unsafe!}
1045
1046 primop  SameMutableByteArrayOp "sameMutableByteArray#" GenPrimOp
1047    MutableByteArray# s -> MutableByteArray# s -> Int#
1048
1049 primop  UnsafeFreezeByteArrayOp "unsafeFreezeByteArray#" GenPrimOp
1050    MutableByteArray# s -> State# s -> (# State# s, ByteArray# #)
1051    {Make a mutable byte array immutable, without copying.}
1052    with
1053    has_side_effects = True
1054
1055 primop  SizeofByteArrayOp "sizeofByteArray#" GenPrimOp
1056    ByteArray# -> Int#
1057    {Return the size of the array in bytes.}
1058
1059 primop  SizeofMutableByteArrayOp "sizeofMutableByteArray#" GenPrimOp
1060    MutableByteArray# s -> Int#
1061    {Return the size of the array in bytes.}
1062
1063 primop IndexByteArrayOp_Char "indexCharArray#" GenPrimOp
1064    ByteArray# -> Int# -> Char#
1065    {Read 8-bit character; offset in bytes.}
1066    with can_fail = True
1067
1068 primop IndexByteArrayOp_WideChar "indexWideCharArray#" GenPrimOp
1069    ByteArray# -> Int# -> Char#
1070    {Read 31-bit character; offset in 4-byte words.}
1071    with can_fail = True
1072
1073 primop IndexByteArrayOp_Int "indexIntArray#" GenPrimOp
1074    ByteArray# -> Int# -> Int#
1075    with can_fail = True
1076
1077 primop IndexByteArrayOp_Word "indexWordArray#" GenPrimOp
1078    ByteArray# -> Int# -> Word#
1079    with can_fail = True
1080
1081 primop IndexByteArrayOp_Addr "indexAddrArray#" GenPrimOp
1082    ByteArray# -> Int# -> Addr#
1083    with can_fail = True
1084
1085 primop IndexByteArrayOp_Float "indexFloatArray#" GenPrimOp
1086    ByteArray# -> Int# -> Float#
1087    with can_fail = True
1088
1089 primop IndexByteArrayOp_Double "indexDoubleArray#" GenPrimOp
1090    ByteArray# -> Int# -> Double#
1091    with can_fail = True
1092
1093 primop IndexByteArrayOp_StablePtr "indexStablePtrArray#" GenPrimOp
1094    ByteArray# -> Int# -> StablePtr# a
1095    with can_fail = True
1096
1097 primop IndexByteArrayOp_Int8 "indexInt8Array#" GenPrimOp
1098    ByteArray# -> Int# -> Int#
1099    {Read 8-bit integer; offset in bytes.}
1100    with can_fail = True
1101
1102 primop IndexByteArrayOp_Int16 "indexInt16Array#" GenPrimOp
1103    ByteArray# -> Int# -> Int#
1104    {Read 16-bit integer; offset in 16-bit words.}
1105    with can_fail = True
1106
1107 primop IndexByteArrayOp_Int32 "indexInt32Array#" GenPrimOp
1108    ByteArray# -> Int# -> INT32
1109    {Read 32-bit integer; offset in 32-bit words.}
1110    with can_fail = True
1111
1112 primop IndexByteArrayOp_Int64 "indexInt64Array#" GenPrimOp
1113    ByteArray# -> Int# -> INT64
1114    {Read 64-bit integer; offset in 64-bit words.}
1115    with can_fail = True
1116
1117 primop IndexByteArrayOp_Word8 "indexWord8Array#" GenPrimOp
1118    ByteArray# -> Int# -> Word#
1119    {Read 8-bit word; offset in bytes.}
1120    with can_fail = True
1121
1122 primop IndexByteArrayOp_Word16 "indexWord16Array#" GenPrimOp
1123    ByteArray# -> Int# -> Word#
1124    {Read 16-bit word; offset in 16-bit words.}
1125    with can_fail = True
1126
1127 primop IndexByteArrayOp_Word32 "indexWord32Array#" GenPrimOp
1128    ByteArray# -> Int# -> WORD32
1129    {Read 32-bit word; offset in 32-bit words.}
1130    with can_fail = True
1131
1132 primop IndexByteArrayOp_Word64 "indexWord64Array#" GenPrimOp
1133    ByteArray# -> Int# -> WORD64
1134    {Read 64-bit word; offset in 64-bit words.}
1135    with can_fail = True
1136
1137 primop  ReadByteArrayOp_Char "readCharArray#" GenPrimOp
1138    MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
1139    {Read 8-bit character; offset in bytes.}
1140    with has_side_effects = True
1141         can_fail = True
1142
1143 primop  ReadByteArrayOp_WideChar "readWideCharArray#" GenPrimOp
1144    MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
1145    {Read 31-bit character; offset in 4-byte words.}
1146    with has_side_effects = True
1147         can_fail = True
1148
1149 primop  ReadByteArrayOp_Int "readIntArray#" GenPrimOp
1150    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
1151    {Read intger; offset in words.}
1152    with has_side_effects = True
1153         can_fail = True
1154
1155 primop  ReadByteArrayOp_Word "readWordArray#" GenPrimOp
1156    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
1157    {Read word; offset in words.}
1158    with has_side_effects = True
1159         can_fail = True
1160
1161 primop  ReadByteArrayOp_Addr "readAddrArray#" GenPrimOp
1162    MutableByteArray# s -> Int# -> State# s -> (# State# s, Addr# #)
1163    with has_side_effects = True
1164         can_fail = True
1165
1166 primop  ReadByteArrayOp_Float "readFloatArray#" GenPrimOp
1167    MutableByteArray# s -> Int# -> State# s -> (# State# s, Float# #)
1168    with has_side_effects = True
1169         can_fail = True
1170
1171 primop  ReadByteArrayOp_Double "readDoubleArray#" GenPrimOp
1172    MutableByteArray# s -> Int# -> State# s -> (# State# s, Double# #)
1173    with has_side_effects = True
1174         can_fail = True
1175
1176 primop  ReadByteArrayOp_StablePtr "readStablePtrArray#" GenPrimOp
1177    MutableByteArray# s -> Int# -> State# s -> (# State# s, StablePtr# a #)
1178    with has_side_effects = True
1179         can_fail = True
1180
1181 primop  ReadByteArrayOp_Int8 "readInt8Array#" GenPrimOp
1182    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
1183    with has_side_effects = True
1184         can_fail = True
1185
1186 primop  ReadByteArrayOp_Int16 "readInt16Array#" GenPrimOp
1187    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
1188    with has_side_effects = True
1189         can_fail = True
1190
1191 primop  ReadByteArrayOp_Int32 "readInt32Array#" GenPrimOp
1192    MutableByteArray# s -> Int# -> State# s -> (# State# s, INT32 #)
1193    with has_side_effects = True
1194         can_fail = True
1195
1196 primop  ReadByteArrayOp_Int64 "readInt64Array#" GenPrimOp
1197    MutableByteArray# s -> Int# -> State# s -> (# State# s, INT64 #)
1198    with has_side_effects = True
1199         can_fail = True
1200
1201 primop  ReadByteArrayOp_Word8 "readWord8Array#" GenPrimOp
1202    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
1203    with has_side_effects = True
1204         can_fail = True
1205
1206 primop  ReadByteArrayOp_Word16 "readWord16Array#" GenPrimOp
1207    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
1208    with has_side_effects = True
1209         can_fail = True
1210
1211 primop  ReadByteArrayOp_Word32 "readWord32Array#" GenPrimOp
1212    MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD32 #)
1213    with has_side_effects = True
1214         can_fail = True
1215
1216 primop  ReadByteArrayOp_Word64 "readWord64Array#" GenPrimOp
1217    MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD64 #)
1218    with has_side_effects = True
1219         can_fail = True
1220
1221 primop  WriteByteArrayOp_Char "writeCharArray#" GenPrimOp
1222    MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
1223    {Write 8-bit character; offset in bytes.}
1224    with has_side_effects = True
1225         can_fail = True
1226
1227 primop  WriteByteArrayOp_WideChar "writeWideCharArray#" GenPrimOp
1228    MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
1229    {Write 31-bit character; offset in 4-byte words.}
1230    with has_side_effects = True
1231         can_fail = True
1232
1233 primop  WriteByteArrayOp_Int "writeIntArray#" GenPrimOp
1234    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1235    with has_side_effects = True
1236         can_fail = True
1237
1238 primop  WriteByteArrayOp_Word "writeWordArray#" GenPrimOp
1239    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
1240    with has_side_effects = True
1241         can_fail = True
1242
1243 primop  WriteByteArrayOp_Addr "writeAddrArray#" GenPrimOp
1244    MutableByteArray# s -> Int# -> Addr# -> State# s -> State# s
1245    with has_side_effects = True
1246         can_fail = True
1247
1248 primop  WriteByteArrayOp_Float "writeFloatArray#" GenPrimOp
1249    MutableByteArray# s -> Int# -> Float# -> State# s -> State# s
1250    with has_side_effects = True
1251         can_fail = True
1252
1253 primop  WriteByteArrayOp_Double "writeDoubleArray#" GenPrimOp
1254    MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
1255    with has_side_effects = True
1256         can_fail = True
1257
1258 primop  WriteByteArrayOp_StablePtr "writeStablePtrArray#" GenPrimOp
1259    MutableByteArray# s -> Int# -> StablePtr# a -> State# s -> State# s
1260    with has_side_effects = True
1261         can_fail = True
1262
1263 primop  WriteByteArrayOp_Int8 "writeInt8Array#" GenPrimOp
1264    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1265    with has_side_effects = True
1266         can_fail = True
1267
1268 primop  WriteByteArrayOp_Int16 "writeInt16Array#" GenPrimOp
1269    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1270    with has_side_effects = True
1271         can_fail = True
1272
1273 primop  WriteByteArrayOp_Int32 "writeInt32Array#" GenPrimOp
1274    MutableByteArray# s -> Int# -> INT32 -> State# s -> State# s
1275    with has_side_effects = True
1276         can_fail = True
1277
1278 primop  WriteByteArrayOp_Int64 "writeInt64Array#" GenPrimOp
1279    MutableByteArray# s -> Int# -> INT64 -> State# s -> State# s
1280    with can_fail = True
1281         has_side_effects = True
1282
1283 primop  WriteByteArrayOp_Word8 "writeWord8Array#" GenPrimOp
1284    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
1285    with has_side_effects = True
1286         can_fail = True
1287
1288 primop  WriteByteArrayOp_Word16 "writeWord16Array#" GenPrimOp
1289    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
1290    with has_side_effects = True
1291         can_fail = True
1292
1293 primop  WriteByteArrayOp_Word32 "writeWord32Array#" GenPrimOp
1294    MutableByteArray# s -> Int# -> WORD32 -> State# s -> State# s
1295    with has_side_effects = True
1296         can_fail = True
1297
1298 primop  WriteByteArrayOp_Word64 "writeWord64Array#" GenPrimOp
1299    MutableByteArray# s -> Int# -> WORD64 -> State# s -> State# s
1300    with has_side_effects = True
1301         can_fail = True
1302
1303 primop  CopyByteArrayOp "copyByteArray#" GenPrimOp
1304   ByteArray# -> Int# -> MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1305   {Copy a range of the ByteArray# to the specified region in the MutableByteArray#.
1306    Both arrays must fully contain the specified ranges, but this is not checked.
1307    The two arrays must not be the same array in different states, but this is not checked either.}
1308   with
1309   has_side_effects = True
1310   code_size = { primOpCodeSizeForeignCall + 4}
1311   can_fail = True
1312
1313 primop  CopyMutableByteArrayOp "copyMutableByteArray#" GenPrimOp
1314   MutableByteArray# s -> Int# -> MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1315   {Copy a range of the first MutableByteArray# to the specified region in the second MutableByteArray#.
1316    Both arrays must fully contain the specified ranges, but this is not checked.}
1317   with
1318   has_side_effects = True
1319   code_size = { primOpCodeSizeForeignCall + 4 }
1320   can_fail = True
1321
1322 primop  CopyByteArrayToAddrOp "copyByteArrayToAddr#" GenPrimOp
1323   ByteArray# -> Int# -> Addr# -> Int# -> State# s -> State# s
1324   {Copy a range of the ByteArray# to the memory range starting at the Addr#.
1325    The ByteArray# and the memory region at Addr# must fully contain the
1326    specified ranges, but this is not checked. The Addr# must not point into the
1327    ByteArray# (e.g. if the ByteArray# were pinned), but this is not checked
1328    either.}
1329   with
1330   has_side_effects = True
1331   code_size = { primOpCodeSizeForeignCall + 4}
1332   can_fail = True
1333
1334 primop  CopyMutableByteArrayToAddrOp "copyMutableByteArrayToAddr#" GenPrimOp
1335   MutableByteArray# s -> Int# -> Addr# -> Int# -> State# s -> State# s
1336   {Copy a range of the MutableByteArray# to the memory range starting at the
1337    Addr#. The MutableByteArray# and the memory region at Addr# must fully
1338    contain the specified ranges, but this is not checked. The Addr# must not
1339    point into the MutableByteArray# (e.g. if the MutableByteArray# were
1340    pinned), but this is not checked either.}
1341   with
1342   has_side_effects = True
1343   code_size = { primOpCodeSizeForeignCall + 4}
1344   can_fail = True
1345
1346 primop  CopyAddrToByteArrayOp "copyAddrToByteArray#" GenPrimOp
1347   Addr# -> MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1348   {Copy a memory range starting at the Addr# to the specified range in the
1349    MutableByteArray#. The memory region at Addr# and the ByteArray# must fully
1350    contain the specified ranges, but this is not checked. The Addr# must not
1351    point into the MutableByteArray# (e.g. if the MutableByteArray# were pinned),
1352    but this is not checked either.}
1353   with
1354   has_side_effects = True
1355   code_size = { primOpCodeSizeForeignCall + 4}
1356   can_fail = True
1357
1358 primop  SetByteArrayOp "setByteArray#" GenPrimOp
1359   MutableByteArray# s -> Int# -> Int# -> Int# -> State# s -> State# s
1360   {Set the range of the MutableByteArray# to the specified character.}
1361   with
1362   has_side_effects = True
1363   code_size = { primOpCodeSizeForeignCall + 4 }
1364   can_fail = True
1365
1366 primop CasByteArrayOp_Int "casIntArray#" GenPrimOp
1367    MutableByteArray# s -> Int# -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1368    {Machine-level atomic compare and swap on a word within a ByteArray.}
1369    with
1370    out_of_line = True
1371    has_side_effects = True
1372
1373 primop FetchAddByteArrayOp_Int "fetchAddIntArray#" GenPrimOp
1374    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1375    {Machine-level word-sized fetch-and-add within a ByteArray.}
1376    with
1377    out_of_line = True
1378    has_side_effects = True
1379
1380
1381 ------------------------------------------------------------------------
1382 section "Arrays of arrays"
1383         {Operations on {\tt ArrayArray\#}. An {\tt ArrayArray\#} contains references to {\em unpointed}
1384          arrays, such as {\tt ByteArray\#s}. Hence, it is not parameterised by the element types,
1385          just like a {\tt ByteArray\#}, but it needs to be scanned during GC, just like an {\tt Array#}.
1386          We represent an {\tt ArrayArray\#} exactly as a {\tt Array\#}, but provide element-type-specific
1387          indexing, reading, and writing.}
1388 ------------------------------------------------------------------------
1389
1390 primtype ArrayArray#
1391
1392 primtype MutableArrayArray# s
1393
1394 primop  NewArrayArrayOp "newArrayArray#" GenPrimOp
1395    Int# -> State# s -> (# State# s, MutableArrayArray# s #)
1396    {Create a new mutable array of arrays with the specified number of elements,
1397     in the specified state thread, with each element recursively referring to the
1398     newly created array.}
1399    with
1400    out_of_line = True
1401    has_side_effects = True
1402
1403 primop  SameMutableArrayArrayOp "sameMutableArrayArray#" GenPrimOp
1404    MutableArrayArray# s -> MutableArrayArray# s -> Int#
1405
1406 primop  UnsafeFreezeArrayArrayOp "unsafeFreezeArrayArray#" GenPrimOp
1407    MutableArrayArray# s -> State# s -> (# State# s, ArrayArray# #)
1408    {Make a mutable array of arrays immutable, without copying.}
1409    with
1410    has_side_effects = True
1411
1412 primop  SizeofArrayArrayOp "sizeofArrayArray#" GenPrimOp
1413    ArrayArray# -> Int#
1414    {Return the number of elements in the array.}
1415
1416 primop  SizeofMutableArrayArrayOp "sizeofMutableArrayArray#" GenPrimOp
1417    MutableArrayArray# s -> Int#
1418    {Return the number of elements in the array.}
1419
1420 primop IndexArrayArrayOp_ByteArray "indexByteArrayArray#" GenPrimOp
1421    ArrayArray# -> Int# -> ByteArray#
1422    with can_fail = True
1423
1424 primop IndexArrayArrayOp_ArrayArray "indexArrayArrayArray#" GenPrimOp
1425    ArrayArray# -> Int# -> ArrayArray#
1426    with can_fail = True
1427
1428 primop  ReadArrayArrayOp_ByteArray "readByteArrayArray#" GenPrimOp
1429    MutableArrayArray# s -> Int# -> State# s -> (# State# s, ByteArray# #)
1430    with has_side_effects = True
1431         can_fail = True
1432
1433 primop  ReadArrayArrayOp_MutableByteArray "readMutableByteArrayArray#" GenPrimOp
1434    MutableArrayArray# s -> Int# -> State# s -> (# State# s, MutableByteArray# s #)
1435    with has_side_effects = True
1436         can_fail = True
1437
1438 primop  ReadArrayArrayOp_ArrayArray "readArrayArrayArray#" GenPrimOp
1439    MutableArrayArray# s -> Int# -> State# s -> (# State# s, ArrayArray# #)
1440    with has_side_effects = True
1441         can_fail = True
1442
1443 primop  ReadArrayArrayOp_MutableArrayArray "readMutableArrayArrayArray#" GenPrimOp
1444    MutableArrayArray# s -> Int# -> State# s -> (# State# s, MutableArrayArray# s #)
1445    with has_side_effects = True
1446         can_fail = True
1447
1448 primop  WriteArrayArrayOp_ByteArray "writeByteArrayArray#" GenPrimOp
1449    MutableArrayArray# s -> Int# -> ByteArray# -> State# s -> State# s
1450    with has_side_effects = True
1451         can_fail = True
1452
1453 primop  WriteArrayArrayOp_MutableByteArray "writeMutableByteArrayArray#" GenPrimOp
1454    MutableArrayArray# s -> Int# -> MutableByteArray# s -> State# s -> State# s
1455    with has_side_effects = True
1456         can_fail = True
1457
1458 primop  WriteArrayArrayOp_ArrayArray "writeArrayArrayArray#" GenPrimOp
1459    MutableArrayArray# s -> Int# -> ArrayArray# -> State# s -> State# s
1460    with has_side_effects = True
1461         can_fail = True
1462
1463 primop  WriteArrayArrayOp_MutableArrayArray "writeMutableArrayArrayArray#" GenPrimOp
1464    MutableArrayArray# s -> Int# -> MutableArrayArray# s -> State# s -> State# s
1465    with has_side_effects = True
1466         can_fail = True
1467
1468 primop  CopyArrayArrayOp "copyArrayArray#" GenPrimOp
1469   ArrayArray# -> Int# -> MutableArrayArray# s -> Int# -> Int# -> State# s -> State# s
1470   {Copy a range of the ArrayArray# to the specified region in the MutableArrayArray#.
1471    Both arrays must fully contain the specified ranges, but this is not checked.
1472    The two arrays must not be the same array in different states, but this is not checked either.}
1473   with
1474   out_of_line      = True
1475   has_side_effects = True
1476   can_fail         = True
1477
1478 primop  CopyMutableArrayArrayOp "copyMutableArrayArray#" GenPrimOp
1479   MutableArrayArray# s -> Int# -> MutableArrayArray# s -> Int# -> Int# -> State# s -> State# s
1480   {Copy a range of the first MutableArrayArray# to the specified region in the second
1481    MutableArrayArray#.
1482    Both arrays must fully contain the specified ranges, but this is not checked.}
1483   with
1484   out_of_line      = True
1485   has_side_effects = True
1486   can_fail         = True
1487
1488 ------------------------------------------------------------------------
1489 section "Addr#"
1490 ------------------------------------------------------------------------
1491
1492 primtype Addr#
1493         { An arbitrary machine address assumed to point outside
1494          the garbage-collected heap. }
1495
1496 pseudoop "nullAddr#" Addr#
1497         { The null address. }
1498
1499 primop   AddrAddOp "plusAddr#" GenPrimOp Addr# -> Int# -> Addr#
1500 primop   AddrSubOp "minusAddr#" GenPrimOp Addr# -> Addr# -> Int#
1501          {Result is meaningless if two {\tt Addr\#}s are so far apart that their
1502          difference doesn't fit in an {\tt Int\#}.}
1503 primop   AddrRemOp "remAddr#" GenPrimOp Addr# -> Int# -> Int#
1504          {Return the remainder when the {\tt Addr\#} arg, treated like an {\tt Int\#},
1505           is divided by the {\tt Int\#} arg.}
1506 #if (WORD_SIZE_IN_BITS == 32 || WORD_SIZE_IN_BITS == 64)
1507 primop   Addr2IntOp  "addr2Int#"     GenPrimOp   Addr# -> Int#
1508         {Coerce directly from address to int. Strongly deprecated.}
1509    with code_size = 0
1510 primop   Int2AddrOp   "int2Addr#"    GenPrimOp  Int# -> Addr#
1511         {Coerce directly from int to address. Strongly deprecated.}
1512    with code_size = 0
1513 #endif
1514
1515 primop   AddrGtOp  "gtAddr#"   Compare   Addr# -> Addr# -> Int#
1516 primop   AddrGeOp  "geAddr#"   Compare   Addr# -> Addr# -> Int#
1517 primop   AddrEqOp  "eqAddr#"   Compare   Addr# -> Addr# -> Int#
1518 primop   AddrNeOp  "neAddr#"   Compare   Addr# -> Addr# -> Int#
1519 primop   AddrLtOp  "ltAddr#"   Compare   Addr# -> Addr# -> Int#
1520 primop   AddrLeOp  "leAddr#"   Compare   Addr# -> Addr# -> Int#
1521
1522 primop IndexOffAddrOp_Char "indexCharOffAddr#" GenPrimOp
1523    Addr# -> Int# -> Char#
1524    {Reads 8-bit character; offset in bytes.}
1525    with can_fail = True
1526
1527 primop IndexOffAddrOp_WideChar "indexWideCharOffAddr#" GenPrimOp
1528    Addr# -> Int# -> Char#
1529    {Reads 31-bit character; offset in 4-byte words.}
1530    with can_fail = True
1531
1532 primop IndexOffAddrOp_Int "indexIntOffAddr#" GenPrimOp
1533    Addr# -> Int# -> Int#
1534    with can_fail = True
1535
1536 primop IndexOffAddrOp_Word "indexWordOffAddr#" GenPrimOp
1537    Addr# -> Int# -> Word#
1538    with can_fail = True
1539
1540 primop IndexOffAddrOp_Addr "indexAddrOffAddr#" GenPrimOp
1541    Addr# -> Int# -> Addr#
1542    with can_fail = True
1543
1544 primop IndexOffAddrOp_Float "indexFloatOffAddr#" GenPrimOp
1545    Addr# -> Int# -> Float#
1546    with can_fail = True
1547
1548 primop IndexOffAddrOp_Double "indexDoubleOffAddr#" GenPrimOp
1549    Addr# -> Int# -> Double#
1550    with can_fail = True
1551
1552 primop IndexOffAddrOp_StablePtr "indexStablePtrOffAddr#" GenPrimOp
1553    Addr# -> Int# -> StablePtr# a
1554    with can_fail = True
1555
1556 primop IndexOffAddrOp_Int8 "indexInt8OffAddr#" GenPrimOp
1557    Addr# -> Int# -> Int#
1558    with can_fail = True
1559
1560 primop IndexOffAddrOp_Int16 "indexInt16OffAddr#" GenPrimOp
1561    Addr# -> Int# -> Int#
1562    with can_fail = True
1563
1564 primop IndexOffAddrOp_Int32 "indexInt32OffAddr#" GenPrimOp
1565    Addr# -> Int# -> INT32
1566    with can_fail = True
1567
1568 primop IndexOffAddrOp_Int64 "indexInt64OffAddr#" GenPrimOp
1569    Addr# -> Int# -> INT64
1570    with can_fail = True
1571
1572 primop IndexOffAddrOp_Word8 "indexWord8OffAddr#" GenPrimOp
1573    Addr# -> Int# -> Word#
1574    with can_fail = True
1575
1576 primop IndexOffAddrOp_Word16 "indexWord16OffAddr#" GenPrimOp
1577    Addr# -> Int# -> Word#
1578    with can_fail = True
1579
1580 primop IndexOffAddrOp_Word32 "indexWord32OffAddr#" GenPrimOp
1581    Addr# -> Int# -> WORD32
1582    with can_fail = True
1583
1584 primop IndexOffAddrOp_Word64 "indexWord64OffAddr#" GenPrimOp
1585    Addr# -> Int# -> WORD64
1586    with can_fail = True
1587
1588 primop ReadOffAddrOp_Char "readCharOffAddr#" GenPrimOp
1589    Addr# -> Int# -> State# s -> (# State# s, Char# #)
1590    {Reads 8-bit character; offset in bytes.}
1591    with has_side_effects = True
1592         can_fail         = True
1593
1594 primop ReadOffAddrOp_WideChar "readWideCharOffAddr#" GenPrimOp
1595    Addr# -> Int# -> State# s -> (# State# s, Char# #)
1596    {Reads 31-bit character; offset in 4-byte words.}
1597    with has_side_effects = True
1598         can_fail         = True
1599
1600 primop ReadOffAddrOp_Int "readIntOffAddr#" GenPrimOp
1601    Addr# -> Int# -> State# s -> (# State# s, Int# #)
1602    with has_side_effects = True
1603         can_fail         = True
1604
1605 primop ReadOffAddrOp_Word "readWordOffAddr#" GenPrimOp
1606    Addr# -> Int# -> State# s -> (# State# s, Word# #)
1607    with has_side_effects = True
1608         can_fail         = True
1609
1610 primop ReadOffAddrOp_Addr "readAddrOffAddr#" GenPrimOp
1611    Addr# -> Int# -> State# s -> (# State# s, Addr# #)
1612    with has_side_effects = True
1613         can_fail         = True
1614
1615 primop ReadOffAddrOp_Float "readFloatOffAddr#" GenPrimOp
1616    Addr# -> Int# -> State# s -> (# State# s, Float# #)
1617    with has_side_effects = True
1618         can_fail         = True
1619
1620 primop ReadOffAddrOp_Double "readDoubleOffAddr#" GenPrimOp
1621    Addr# -> Int# -> State# s -> (# State# s, Double# #)
1622    with has_side_effects = True
1623         can_fail         = True
1624
1625 primop ReadOffAddrOp_StablePtr "readStablePtrOffAddr#" GenPrimOp
1626    Addr# -> Int# -> State# s -> (# State# s, StablePtr# a #)
1627    with has_side_effects = True
1628         can_fail         = True
1629
1630 primop ReadOffAddrOp_Int8 "readInt8OffAddr#" GenPrimOp
1631    Addr# -> Int# -> State# s -> (# State# s, Int# #)
1632    with has_side_effects = True
1633         can_fail         = True
1634
1635 primop ReadOffAddrOp_Int16 "readInt16OffAddr#" GenPrimOp
1636    Addr# -> Int# -> State# s -> (# State# s, Int# #)
1637    with has_side_effects = True
1638         can_fail         = True
1639
1640 primop ReadOffAddrOp_Int32 "readInt32OffAddr#" GenPrimOp
1641    Addr# -> Int# -> State# s -> (# State# s, INT32 #)
1642    with has_side_effects = True
1643         can_fail         = True
1644
1645 primop ReadOffAddrOp_Int64 "readInt64OffAddr#" GenPrimOp
1646    Addr# -> Int# -> State# s -> (# State# s, INT64 #)
1647    with has_side_effects = True
1648         can_fail         = True
1649
1650 primop ReadOffAddrOp_Word8 "readWord8OffAddr#" GenPrimOp
1651    Addr# -> Int# -> State# s -> (# State# s, Word# #)
1652    with has_side_effects = True
1653         can_fail         = True
1654
1655 primop ReadOffAddrOp_Word16 "readWord16OffAddr#" GenPrimOp
1656    Addr# -> Int# -> State# s -> (# State# s, Word# #)
1657    with has_side_effects = True
1658         can_fail         = True
1659
1660 primop ReadOffAddrOp_Word32 "readWord32OffAddr#" GenPrimOp
1661    Addr# -> Int# -> State# s -> (# State# s, WORD32 #)
1662    with has_side_effects = True
1663         can_fail         = True
1664
1665 primop ReadOffAddrOp_Word64 "readWord64OffAddr#" GenPrimOp
1666    Addr# -> Int# -> State# s -> (# State# s, WORD64 #)
1667    with has_side_effects = True
1668         can_fail         = True
1669
1670 primop  WriteOffAddrOp_Char "writeCharOffAddr#" GenPrimOp
1671    Addr# -> Int# -> Char# -> State# s -> State# s
1672    with has_side_effects = True
1673         can_fail         = True
1674
1675 primop  WriteOffAddrOp_WideChar "writeWideCharOffAddr#" GenPrimOp
1676    Addr# -> Int# -> Char# -> State# s -> State# s
1677    with has_side_effects = True
1678         can_fail         = True
1679
1680 primop  WriteOffAddrOp_Int "writeIntOffAddr#" GenPrimOp
1681    Addr# -> Int# -> Int# -> State# s -> State# s
1682    with has_side_effects = True
1683         can_fail         = True
1684
1685 primop  WriteOffAddrOp_Word "writeWordOffAddr#" GenPrimOp
1686    Addr# -> Int# -> Word# -> State# s -> State# s
1687    with has_side_effects = True
1688         can_fail         = True
1689
1690 primop  WriteOffAddrOp_Addr "writeAddrOffAddr#" GenPrimOp
1691    Addr# -> Int# -> Addr# -> State# s -> State# s
1692    with has_side_effects = True
1693         can_fail         = True
1694
1695 primop  WriteOffAddrOp_Float "writeFloatOffAddr#" GenPrimOp
1696    Addr# -> Int# -> Float# -> State# s -> State# s
1697    with has_side_effects = True
1698         can_fail         = True
1699
1700 primop  WriteOffAddrOp_Double "writeDoubleOffAddr#" GenPrimOp
1701    Addr# -> Int# -> Double# -> State# s -> State# s
1702    with has_side_effects = True
1703         can_fail         = True
1704
1705 primop  WriteOffAddrOp_StablePtr "writeStablePtrOffAddr#" GenPrimOp
1706    Addr# -> Int# -> StablePtr# a -> State# s -> State# s
1707    with has_side_effects = True
1708         can_fail         = True
1709
1710 primop  WriteOffAddrOp_Int8 "writeInt8OffAddr#" GenPrimOp
1711    Addr# -> Int# -> Int# -> State# s -> State# s
1712    with has_side_effects = True
1713         can_fail         = True
1714
1715 primop  WriteOffAddrOp_Int16 "writeInt16OffAddr#" GenPrimOp
1716    Addr# -> Int# -> Int# -> State# s -> State# s
1717    with has_side_effects = True
1718         can_fail         = True
1719
1720 primop  WriteOffAddrOp_Int32 "writeInt32OffAddr#" GenPrimOp
1721    Addr# -> Int# -> INT32 -> State# s -> State# s
1722    with has_side_effects = True
1723         can_fail         = True
1724
1725 primop  WriteOffAddrOp_Int64 "writeInt64OffAddr#" GenPrimOp
1726    Addr# -> Int# -> INT64 -> State# s -> State# s
1727    with has_side_effects = True
1728         can_fail         = True
1729
1730 primop  WriteOffAddrOp_Word8 "writeWord8OffAddr#" GenPrimOp
1731    Addr# -> Int# -> Word# -> State# s -> State# s
1732    with has_side_effects = True
1733         can_fail         = True
1734
1735 primop  WriteOffAddrOp_Word16 "writeWord16OffAddr#" GenPrimOp
1736    Addr# -> Int# -> Word# -> State# s -> State# s
1737    with has_side_effects = True
1738         can_fail         = True
1739
1740 primop  WriteOffAddrOp_Word32 "writeWord32OffAddr#" GenPrimOp
1741    Addr# -> Int# -> WORD32 -> State# s -> State# s
1742    with has_side_effects = True
1743         can_fail         = True
1744
1745 primop  WriteOffAddrOp_Word64 "writeWord64OffAddr#" GenPrimOp
1746    Addr# -> Int# -> WORD64 -> State# s -> State# s
1747    with has_side_effects = True
1748         can_fail         = True
1749
1750 ------------------------------------------------------------------------
1751 section "Mutable variables"
1752         {Operations on MutVar\#s.}
1753 ------------------------------------------------------------------------
1754
1755 primtype MutVar# s a
1756         {A {\tt MutVar\#} behaves like a single-element mutable array.}
1757
1758 primop  NewMutVarOp "newMutVar#" GenPrimOp
1759    a -> State# s -> (# State# s, MutVar# s a #)
1760    {Create {\tt MutVar\#} with specified initial value in specified state thread.}
1761    with
1762    out_of_line = True
1763    has_side_effects = True
1764
1765 primop  ReadMutVarOp "readMutVar#" GenPrimOp
1766    MutVar# s a -> State# s -> (# State# s, a #)
1767    {Read contents of {\tt MutVar\#}. Result is not yet evaluated.}
1768    with
1769    has_side_effects = True
1770    can_fail         = True
1771
1772 primop  WriteMutVarOp "writeMutVar#"  GenPrimOp
1773    MutVar# s a -> a -> State# s -> State# s
1774    {Write contents of {\tt MutVar\#}.}
1775    with
1776    has_side_effects = True
1777    code_size = { primOpCodeSizeForeignCall } -- for the write barrier
1778    can_fail         = True
1779
1780 primop  SameMutVarOp "sameMutVar#" GenPrimOp
1781    MutVar# s a -> MutVar# s a -> Int#
1782
1783 -- not really the right type, but we don't know about pairs here.  The
1784 -- correct type is
1785 --
1786 --   MutVar# s a -> (a -> (a,b)) -> State# s -> (# State# s, b #)
1787 --
1788 primop  AtomicModifyMutVarOp "atomicModifyMutVar#" GenPrimOp
1789    MutVar# s a -> (a -> b) -> State# s -> (# State# s, c #)
1790    with
1791    out_of_line = True
1792    has_side_effects = True
1793    can_fail         = True
1794
1795 primop  CasMutVarOp "casMutVar#" GenPrimOp
1796   MutVar# s a -> a -> a -> State# s -> (# State# s, Int#, a #)
1797    with
1798    out_of_line = True
1799    has_side_effects = True
1800
1801 ------------------------------------------------------------------------
1802 section "Exceptions"
1803 ------------------------------------------------------------------------
1804
1805 primop  CatchOp "catch#" GenPrimOp
1806           (State# RealWorld -> (# State# RealWorld, a #) )
1807        -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1808        -> State# RealWorld
1809        -> (# State# RealWorld, a #)
1810    with
1811         -- Catch is actually strict in its first argument
1812         -- but we don't want to tell the strictness
1813         -- analyser about that, so that exceptions stay inside it.
1814    strictness  = { \ _arity -> mkClosedStrictSig [apply1Dmd,apply2Dmd,topDmd] topRes }
1815    out_of_line = True
1816    has_side_effects = True
1817
1818 primop  RaiseOp "raise#" GenPrimOp
1819    a -> b
1820    with
1821    strictness  = { \ _arity -> mkClosedStrictSig [topDmd] botRes }
1822       -- NB: result is bottom
1823    out_of_line = True
1824
1825 -- raiseIO# needs to be a primop, because exceptions in the IO monad
1826 -- must be *precise* - we don't want the strictness analyser turning
1827 -- one kind of bottom into another, as it is allowed to do in pure code.
1828 --
1829 -- But we *do* want to know that it returns bottom after
1830 -- being applied to two arguments, so that this function is strict in y
1831 --     f x y | x>0       = raiseIO blah
1832 --           | y>0       = return 1
1833 --           | otherwise = return 2
1834
1835 primop  RaiseIOOp "raiseIO#" GenPrimOp
1836    a -> State# RealWorld -> (# State# RealWorld, b #)
1837    with
1838    strictness  = { \ _arity -> mkClosedStrictSig [topDmd, topDmd] botRes }
1839    out_of_line = True
1840    has_side_effects = True
1841
1842 primop  MaskAsyncExceptionsOp "maskAsyncExceptions#" GenPrimOp
1843         (State# RealWorld -> (# State# RealWorld, a #))
1844      -> (State# RealWorld -> (# State# RealWorld, a #))
1845    with
1846    strictness  = { \ _arity -> mkClosedStrictSig [apply1Dmd,topDmd] topRes }
1847    out_of_line = True
1848    has_side_effects = True
1849
1850 primop  MaskUninterruptibleOp "maskUninterruptible#" GenPrimOp
1851         (State# RealWorld -> (# State# RealWorld, a #))
1852      -> (State# RealWorld -> (# State# RealWorld, a #))
1853    with
1854    strictness  = { \ _arity -> mkClosedStrictSig [apply1Dmd,topDmd] topRes }
1855    out_of_line = True
1856    has_side_effects = True
1857
1858 primop  UnmaskAsyncExceptionsOp "unmaskAsyncExceptions#" GenPrimOp
1859         (State# RealWorld -> (# State# RealWorld, a #))
1860      -> (State# RealWorld -> (# State# RealWorld, a #))
1861    with
1862    strictness  = { \ _arity -> mkClosedStrictSig [apply1Dmd,topDmd] topRes }
1863    out_of_line = True
1864    has_side_effects = True
1865
1866 primop  MaskStatus "getMaskingState#" GenPrimOp
1867         State# RealWorld -> (# State# RealWorld, Int# #)
1868    with
1869    out_of_line = True
1870    has_side_effects = True
1871
1872 ------------------------------------------------------------------------
1873 section "STM-accessible Mutable Variables"
1874 ------------------------------------------------------------------------
1875
1876 primtype TVar# s a
1877
1878 primop  AtomicallyOp "atomically#" GenPrimOp
1879       (State# RealWorld -> (# State# RealWorld, a #) )
1880    -> State# RealWorld -> (# State# RealWorld, a #)
1881    with
1882    strictness  = { \ _arity -> mkClosedStrictSig [apply1Dmd,topDmd] topRes }
1883    out_of_line = True
1884    has_side_effects = True
1885
1886 -- NB: retry#'s strictness information specifies it to return bottom.
1887 -- This lets the compiler perform some extra simplifications, since retry#
1888 -- will technically never return.
1889 --
1890 -- This allows the simplifier to replace things like:
1891 --   case retry# s1
1892 --     (# s2, a #) -> e
1893 -- with:
1894 --   retry# s1
1895 -- where 'e' would be unreachable anyway.  See Trac #8091.
1896 primop  RetryOp "retry#" GenPrimOp
1897    State# RealWorld -> (# State# RealWorld, a #)
1898    with
1899    strictness  = { \ _arity -> mkClosedStrictSig [topDmd] botRes }
1900    out_of_line = True
1901    has_side_effects = True
1902
1903 primop  CatchRetryOp "catchRetry#" GenPrimOp
1904       (State# RealWorld -> (# State# RealWorld, a #) )
1905    -> (State# RealWorld -> (# State# RealWorld, a #) )
1906    -> (State# RealWorld -> (# State# RealWorld, a #) )
1907    with
1908    strictness  = { \ _arity -> mkClosedStrictSig [apply1Dmd,apply1Dmd,topDmd] topRes }
1909    out_of_line = True
1910    has_side_effects = True
1911
1912 primop  CatchSTMOp "catchSTM#" GenPrimOp
1913       (State# RealWorld -> (# State# RealWorld, a #) )
1914    -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1915    -> (State# RealWorld -> (# State# RealWorld, a #) )
1916    with
1917    strictness  = { \ _arity -> mkClosedStrictSig [apply1Dmd,apply2Dmd,topDmd] topRes }
1918    out_of_line = True
1919    has_side_effects = True
1920
1921 primop  Check "check#" GenPrimOp
1922       (State# RealWorld -> (# State# RealWorld, a #) )
1923    -> (State# RealWorld -> (# State# RealWorld, () #) )
1924    with
1925    out_of_line = True
1926    has_side_effects = True
1927
1928 primop  NewTVarOp "newTVar#" GenPrimOp
1929        a
1930     -> State# s -> (# State# s, TVar# s a #)
1931    {Create a new {\tt TVar\#} holding a specified initial value.}
1932    with
1933    out_of_line  = True
1934    has_side_effects = True
1935
1936 primop  ReadTVarOp "readTVar#" GenPrimOp
1937        TVar# s a
1938     -> State# s -> (# State# s, a #)
1939    {Read contents of {\tt TVar\#}.  Result is not yet evaluated.}
1940    with
1941    out_of_line  = True
1942    has_side_effects = True
1943
1944 primop ReadTVarIOOp "readTVarIO#" GenPrimOp
1945        TVar# s a
1946     -> State# s -> (# State# s, a #)
1947    {Read contents of {\tt TVar\#} outside an STM transaction}
1948    with
1949    out_of_line  = True
1950    has_side_effects = True
1951
1952 primop  WriteTVarOp "writeTVar#" GenPrimOp
1953        TVar# s a
1954     -> a
1955     -> State# s -> State# s
1956    {Write contents of {\tt TVar\#}.}
1957    with
1958    out_of_line      = True
1959    has_side_effects = True
1960
1961 primop  SameTVarOp "sameTVar#" GenPrimOp
1962    TVar# s a -> TVar# s a -> Int#
1963
1964
1965 ------------------------------------------------------------------------
1966 section "Synchronized Mutable Variables"
1967         {Operations on {\tt MVar\#}s. }
1968 ------------------------------------------------------------------------
1969
1970 primtype MVar# s a
1971         { A shared mutable variable ({\it not} the same as a {\tt MutVar\#}!).
1972         (Note: in a non-concurrent implementation, {\tt (MVar\# a)} can be
1973         represented by {\tt (MutVar\# (Maybe a))}.) }
1974
1975 primop  NewMVarOp "newMVar#"  GenPrimOp
1976    State# s -> (# State# s, MVar# s a #)
1977    {Create new {\tt MVar\#}; initially empty.}
1978    with
1979    out_of_line = True
1980    has_side_effects = True
1981
1982 primop  TakeMVarOp "takeMVar#" GenPrimOp
1983    MVar# s a -> State# s -> (# State# s, a #)
1984    {If {\tt MVar\#} is empty, block until it becomes full.
1985    Then remove and return its contents, and set it empty.}
1986    with
1987    out_of_line      = True
1988    has_side_effects = True
1989
1990 primop  TryTakeMVarOp "tryTakeMVar#" GenPrimOp
1991    MVar# s a -> State# s -> (# State# s, Int#, a #)
1992    {If {\tt MVar\#} is empty, immediately return with integer 0 and value undefined.
1993    Otherwise, return with integer 1 and contents of {\tt MVar\#}, and set {\tt MVar\#} empty.}
1994    with
1995    out_of_line      = True
1996    has_side_effects = True
1997
1998 primop  PutMVarOp "putMVar#" GenPrimOp
1999    MVar# s a -> a -> State# s -> State# s
2000    {If {\tt MVar\#} is full, block until it becomes empty.
2001    Then store value arg as its new contents.}
2002    with
2003    out_of_line      = True
2004    has_side_effects = True
2005
2006 primop  TryPutMVarOp "tryPutMVar#" GenPrimOp
2007    MVar# s a -> a -> State# s -> (# State# s, Int# #)
2008    {If {\tt MVar\#} is full, immediately return with integer 0.
2009     Otherwise, store value arg as {\tt MVar\#}'s new contents, and return with integer 1.}
2010    with
2011    out_of_line      = True
2012    has_side_effects = True
2013
2014 primop  ReadMVarOp "readMVar#" GenPrimOp
2015    MVar# s a -> State# s -> (# State# s, a #)
2016    {If {\tt MVar\#} is empty, block until it becomes full.
2017    Then read its contents without modifying the MVar, without possibility
2018    of intervention from other threads.}
2019    with
2020    out_of_line      = True
2021    has_side_effects = True
2022
2023 primop  TryReadMVarOp "tryReadMVar#" GenPrimOp
2024    MVar# s a -> State# s -> (# State# s, Int#, a #)
2025    {If {\tt MVar\#} is empty, immediately return with integer 0 and value undefined.
2026    Otherwise, return with integer 1 and contents of {\tt MVar\#}.}
2027    with
2028    out_of_line      = True
2029    has_side_effects = True
2030
2031 primop  SameMVarOp "sameMVar#" GenPrimOp
2032    MVar# s a -> MVar# s a -> Int#
2033
2034 primop  IsEmptyMVarOp "isEmptyMVar#" GenPrimOp
2035    MVar# s a -> State# s -> (# State# s, Int# #)
2036    {Return 1 if {\tt MVar\#} is empty; 0 otherwise.}
2037    with
2038    out_of_line = True
2039    has_side_effects = True
2040
2041 ------------------------------------------------------------------------
2042 section "Delay/wait operations"
2043 ------------------------------------------------------------------------
2044
2045 primop  DelayOp "delay#" GenPrimOp
2046    Int# -> State# s -> State# s
2047    {Sleep specified number of microseconds.}
2048    with
2049    has_side_effects = True
2050    out_of_line      = True
2051
2052 primop  WaitReadOp "waitRead#" GenPrimOp
2053    Int# -> State# s -> State# s
2054    {Block until input is available on specified file descriptor.}
2055    with
2056    has_side_effects = True
2057    out_of_line      = True
2058
2059 primop  WaitWriteOp "waitWrite#" GenPrimOp
2060    Int# -> State# s -> State# s
2061    {Block until output is possible on specified file descriptor.}
2062    with
2063    has_side_effects = True
2064    out_of_line      = True
2065
2066 #ifdef mingw32_TARGET_OS
2067 primop  AsyncReadOp "asyncRead#" GenPrimOp
2068    Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
2069    {Asynchronously read bytes from specified file descriptor.}
2070    with
2071    has_side_effects = True
2072    out_of_line      = True
2073
2074 primop  AsyncWriteOp "asyncWrite#" GenPrimOp
2075    Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
2076    {Asynchronously write bytes from specified file descriptor.}
2077    with
2078    has_side_effects = True
2079    out_of_line      = True
2080
2081 primop  AsyncDoProcOp "asyncDoProc#" GenPrimOp
2082    Addr# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
2083    {Asynchronously perform procedure (first arg), passing it 2nd arg.}
2084    with
2085    has_side_effects = True
2086    out_of_line      = True
2087
2088 #endif
2089
2090 ------------------------------------------------------------------------
2091 section "Concurrency primitives"
2092 ------------------------------------------------------------------------
2093
2094 primtype State# s
2095         { {\tt State\#} is the primitive, unlifted type of states.  It has
2096         one type parameter, thus {\tt State\# RealWorld}, or {\tt State\# s},
2097         where s is a type variable. The only purpose of the type parameter
2098         is to keep different state threads separate.  It is represented by
2099         nothing at all. }
2100
2101 primtype RealWorld
2102         { {\tt RealWorld} is deeply magical.  It is {\it primitive}, but it is not
2103         {\it unlifted} (hence {\tt ptrArg}).  We never manipulate values of type
2104         {\tt RealWorld}; it's only used in the type system, to parameterise {\tt State\#}. }
2105
2106 primtype ThreadId#
2107         {(In a non-concurrent implementation, this can be a singleton
2108         type, whose (unique) value is returned by {\tt myThreadId\#}.  The
2109         other operations can be omitted.)}
2110
2111 primop  ForkOp "fork#" GenPrimOp
2112    a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
2113    with
2114    has_side_effects = True
2115    out_of_line      = True
2116
2117 primop  ForkOnOp "forkOn#" GenPrimOp
2118    Int# -> a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
2119    with
2120    has_side_effects = True
2121    out_of_line      = True
2122
2123 primop  KillThreadOp "killThread#"  GenPrimOp
2124    ThreadId# -> a -> State# RealWorld -> State# RealWorld
2125    with
2126    has_side_effects = True
2127    out_of_line      = True
2128
2129 primop  YieldOp "yield#" GenPrimOp
2130    State# RealWorld -> State# RealWorld
2131    with
2132    has_side_effects = True
2133    out_of_line      = True
2134
2135 primop  MyThreadIdOp "myThreadId#" GenPrimOp
2136    State# RealWorld -> (# State# RealWorld, ThreadId# #)
2137    with
2138    out_of_line = True
2139    has_side_effects = True
2140
2141 primop LabelThreadOp "labelThread#" GenPrimOp
2142    ThreadId# -> Addr# -> State# RealWorld -> State# RealWorld
2143    with
2144    has_side_effects = True
2145    out_of_line      = True
2146
2147 primop  IsCurrentThreadBoundOp "isCurrentThreadBound#" GenPrimOp
2148    State# RealWorld -> (# State# RealWorld, Int# #)
2149    with
2150    out_of_line = True
2151    has_side_effects = True
2152
2153 primop  NoDuplicateOp "noDuplicate#" GenPrimOp
2154    State# RealWorld -> State# RealWorld
2155    with
2156    out_of_line = True
2157    has_side_effects = True
2158
2159 primop  ThreadStatusOp "threadStatus#" GenPrimOp
2160    ThreadId# -> State# RealWorld -> (# State# RealWorld, Int#, Int#, Int# #)
2161    with
2162    out_of_line = True
2163    has_side_effects = True
2164
2165 ------------------------------------------------------------------------
2166 section "Weak pointers"
2167 ------------------------------------------------------------------------
2168
2169 primtype Weak# b
2170
2171 -- note that tyvar "o" denotes openAlphaTyVar
2172
2173 primop  MkWeakOp "mkWeak#" GenPrimOp
2174    o -> b -> c -> State# RealWorld -> (# State# RealWorld, Weak# b #)
2175    with
2176    has_side_effects = True
2177    out_of_line      = True
2178
2179 primop  MkWeakNoFinalizerOp "mkWeakNoFinalizer#" GenPrimOp
2180    o -> b -> State# RealWorld -> (# State# RealWorld, Weak# b #)
2181    with
2182    has_side_effects = True
2183    out_of_line      = True
2184
2185 primop  AddCFinalizerToWeakOp "addCFinalizerToWeak#" GenPrimOp
2186    Addr# -> Addr# -> Int# -> Addr# -> Weak# b
2187           -> State# RealWorld -> (# State# RealWorld, Int# #)
2188    { {\tt addCFinalizerToWeak# fptr ptr flag eptr w} attaches a C
2189      function pointer {\tt fptr} to a weak pointer {\tt w} as a finalizer. If
2190      {\tt flag} is zero, {\tt fptr} will be called with one argument,
2191      {\tt ptr}. Otherwise, it will be called with two arguments,
2192      {\tt eptr} and {\tt ptr}. {\tt addCFinalizerToWeak#} returns
2193      1 on success, or 0 if {\tt w} is already dead. }
2194    with
2195    has_side_effects = True
2196    out_of_line      = True
2197
2198 primop  DeRefWeakOp "deRefWeak#" GenPrimOp
2199    Weak# a -> State# RealWorld -> (# State# RealWorld, Int#, a #)
2200    with
2201    has_side_effects = True
2202    out_of_line      = True
2203
2204 primop  FinalizeWeakOp "finalizeWeak#" GenPrimOp
2205    Weak# a -> State# RealWorld -> (# State# RealWorld, Int#,
2206               (State# RealWorld -> (# State# RealWorld, () #)) #)
2207    with
2208    has_side_effects = True
2209    out_of_line      = True
2210
2211 primop TouchOp "touch#" GenPrimOp
2212    o -> State# RealWorld -> State# RealWorld
2213    with
2214    code_size = { 0 }
2215    has_side_effects = True
2216
2217 ------------------------------------------------------------------------
2218 section "Stable pointers and names"
2219 ------------------------------------------------------------------------
2220
2221 primtype StablePtr# a
2222
2223 primtype StableName# a
2224
2225 primop  MakeStablePtrOp "makeStablePtr#" GenPrimOp
2226    a -> State# RealWorld -> (# State# RealWorld, StablePtr# a #)
2227    with
2228    has_side_effects = True
2229    out_of_line      = True
2230
2231 primop  DeRefStablePtrOp "deRefStablePtr#" GenPrimOp
2232    StablePtr# a -> State# RealWorld -> (# State# RealWorld, a #)
2233    with
2234    has_side_effects = True
2235    out_of_line      = True
2236
2237 primop  EqStablePtrOp "eqStablePtr#" GenPrimOp
2238    StablePtr# a -> StablePtr# a -> Int#
2239    with
2240    has_side_effects = True
2241
2242 primop  MakeStableNameOp "makeStableName#" GenPrimOp
2243    a -> State# RealWorld -> (# State# RealWorld, StableName# a #)
2244    with
2245    has_side_effects = True
2246    out_of_line      = True
2247
2248 primop  EqStableNameOp "eqStableName#" GenPrimOp
2249    StableName# a -> StableName# b -> Int#
2250
2251 primop  StableNameToIntOp "stableNameToInt#" GenPrimOp
2252    StableName# a -> Int#
2253
2254 ------------------------------------------------------------------------
2255 section "Unsafe pointer equality"
2256 --  (#1 Bad Guy: Alistair Reid :)
2257 ------------------------------------------------------------------------
2258
2259 primop  ReallyUnsafePtrEqualityOp "reallyUnsafePtrEquality#" GenPrimOp
2260    a -> a -> Int#
2261
2262 ------------------------------------------------------------------------
2263 section "Parallelism"
2264 ------------------------------------------------------------------------
2265
2266 primop  ParOp "par#" GenPrimOp
2267    a -> Int#
2268    with
2269       -- Note that Par is lazy to avoid that the sparked thing
2270       -- gets evaluted strictly, which it should *not* be
2271    has_side_effects = True
2272    code_size = { primOpCodeSizeForeignCall }
2273
2274 primop SparkOp "spark#" GenPrimOp
2275    a -> State# s -> (# State# s, a #)
2276    with has_side_effects = True
2277    code_size = { primOpCodeSizeForeignCall }
2278
2279 primop SeqOp "seq#" GenPrimOp
2280    a -> State# s -> (# State# s, a #)
2281
2282    -- why return the value?  So that we can control sharing of seq'd
2283    -- values: in
2284    --    let x = e in x `seq` ... x ...
2285    -- we don't want to inline x, so better to represent it as
2286    --    let x = e in case seq# x RW of (# _, x' #) -> ... x' ...
2287    -- also it matches the type of rseq in the Eval monad.
2288
2289 primop GetSparkOp "getSpark#" GenPrimOp
2290    State# s -> (# State# s, Int#, a #)
2291    with
2292    has_side_effects = True
2293    out_of_line = True
2294
2295 primop NumSparks "numSparks#" GenPrimOp
2296    State# s -> (# State# s, Int# #)
2297    { Returns the number of sparks in the local spark pool. }
2298    with
2299    has_side_effects = True
2300    out_of_line = True
2301
2302 -- HWL: The first 4 Int# in all par... annotations denote:
2303 --   name, granularity info, size of result, degree of parallelism
2304 --      Same  structure as _seq_ i.e. returns Int#
2305 -- KSW: v, the second arg in parAt# and parAtForNow#, is used only to determine
2306 --   `the processor containing the expression v'; it is not evaluated
2307
2308 primop  ParGlobalOp  "parGlobal#"  GenPrimOp
2309    a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
2310    with
2311    has_side_effects = True
2312
2313 primop  ParLocalOp  "parLocal#"  GenPrimOp
2314    a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
2315    with
2316    has_side_effects = True
2317
2318 primop  ParAtOp  "parAt#"  GenPrimOp
2319    b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
2320    with
2321    has_side_effects = True
2322
2323 primop  ParAtAbsOp  "parAtAbs#"  GenPrimOp
2324    a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
2325    with
2326    has_side_effects = True
2327
2328 primop  ParAtRelOp  "parAtRel#" GenPrimOp
2329    a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
2330    with
2331    has_side_effects = True
2332
2333 primop  ParAtForNowOp  "parAtForNow#" GenPrimOp
2334    b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
2335    with
2336    has_side_effects = True
2337
2338 -- copyable# and noFollow# are yet to be implemented (for GpH)
2339 --
2340 --primop  CopyableOp  "copyable#" GenPrimOp
2341 --   a -> Int#
2342 --   with
2343 --   has_side_effects = True
2344 --
2345 --primop  NoFollowOp "noFollow#" GenPrimOp
2346 --   a -> Int#
2347 --   with
2348 --   has_side_effects = True
2349
2350
2351 ------------------------------------------------------------------------
2352 section "Tag to enum stuff"
2353         {Convert back and forth between values of enumerated types
2354         and small integers.}
2355 ------------------------------------------------------------------------
2356
2357 primop  DataToTagOp "dataToTag#" GenPrimOp
2358    a -> Int#
2359    with
2360    strictness  = { \ _arity -> mkClosedStrictSig [evalDmd] topRes }
2361
2362         -- dataToTag# must have an evaluated argument
2363
2364 primop  TagToEnumOp "tagToEnum#" GenPrimOp
2365    Int# -> a
2366
2367 ------------------------------------------------------------------------
2368 section "Bytecode operations"
2369         {Support for the bytecode interpreter and linker.}
2370 ------------------------------------------------------------------------
2371
2372 primtype BCO#
2373    {Primitive bytecode type.}
2374
2375 primop   AddrToAnyOp "addrToAny#" GenPrimOp
2376    Addr# -> (# a #)
2377    {Convert an {\tt Addr\#} to a followable Any type.}
2378    with
2379    code_size = 0
2380
2381 primop   MkApUpd0_Op "mkApUpd0#" GenPrimOp
2382    BCO# -> (# a #)
2383    with
2384    out_of_line = True
2385
2386 primop  NewBCOOp "newBCO#" GenPrimOp
2387    ByteArray# -> ByteArray# -> Array# a -> Int# -> ByteArray# -> State# s -> (# State# s, BCO# #)
2388    with
2389    has_side_effects = True
2390    out_of_line      = True
2391
2392 primop  UnpackClosureOp "unpackClosure#" GenPrimOp
2393    a -> (# Addr#, Array# b, ByteArray# #)
2394    with
2395    out_of_line = True
2396
2397 primop  GetApStackValOp "getApStackVal#" GenPrimOp
2398    a -> Int# -> (# Int#, b #)
2399    with
2400    out_of_line = True
2401
2402 ------------------------------------------------------------------------
2403 section "Misc"
2404         {These aren't nearly as wired in as Etc...}
2405 ------------------------------------------------------------------------
2406
2407 primop  GetCCSOfOp "getCCSOf#" GenPrimOp
2408    a -> State# s -> (# State# s, Addr# #)
2409
2410 primop  GetCurrentCCSOp "getCurrentCCS#" GenPrimOp
2411    a -> State# s -> (# State# s, Addr# #)
2412    { Returns the current {\tt CostCentreStack} (value is {\tt NULL} if
2413      not profiling).  Takes a dummy argument which can be used to
2414      avoid the call to {\tt getCCCS\#} being floated out by the
2415      simplifier, which would result in an uninformative stack
2416      ("CAF"). }
2417
2418 ------------------------------------------------------------------------
2419 section "Etc"
2420         {Miscellaneous built-ins}
2421 ------------------------------------------------------------------------
2422
2423 primtype Proxy# a
2424    { The type constructor {\tt Proxy#} is used to bear witness to some
2425    type variable. It's used when you want to pass around proxy values
2426    for doing things like modelling type applications. A {\tt Proxy#}
2427    is not only unboxed, it also has a polymorphic kind, and has no
2428    runtime representation, being totally free. }
2429
2430 pseudoop "proxy#"
2431    Proxy# a
2432    { Witness for an unboxed {\tt Proxy#} value, which has no runtime
2433    representation. }
2434
2435 pseudoop   "seq"
2436    a -> b -> b
2437    { Evaluates its first argument to head normal form, and then returns its second
2438         argument as the result. }
2439
2440 primtype Any
2441         { The type constructor {\tt Any} is type to which you can unsafely coerce any
2442         lifted type, and back.
2443
2444           * It is lifted, and hence represented by a pointer
2445
2446           * It does not claim to be a {\it data} type, and that's important for
2447             the code generator, because the code gen may {\it enter} a data value
2448             but never enters a function value.
2449
2450         It's also used to instantiate un-constrained type variables after type
2451         checking.  For example, {\tt length} has type
2452
2453         {\tt length :: forall a. [a] -> Int}
2454
2455         and the list datacon for the empty list has type
2456
2457         {\tt [] :: forall a. [a]}
2458
2459         In order to compose these two terms as {\tt length []} a type
2460         application is required, but there is no constraint on the
2461         choice.  In this situation GHC uses {\tt Any}:
2462
2463         {\tt length (Any *) ([] (Any *))}
2464
2465         Above, we print kinds explicitly, as if with
2466         {\tt -fprint-explicit-kinds}.
2467
2468         Note that {\tt Any} is kind polymorphic; its kind is thus
2469         {\tt forall k. k}.}
2470
2471 primtype AnyK
2472         { The kind {\tt AnyK} is the kind level counterpart to {\tt Any}. In a
2473         kind polymorphic setting, a similar example to the length of the empty
2474         list can be given at the type level:
2475
2476         {\tt type family Length (l :: [k]) :: Nat}
2477         {\tt type instance Length [] = Zero}
2478
2479         When {\tt Length} is applied to the empty (promoted) list it will have
2480         the kind {\tt Length AnyK []}.
2481
2482         {\tt AnyK} is currently not exported and cannot be used directly, but
2483         you might see it in debug output from the compiler.
2484         }
2485
2486 pseudoop   "unsafeCoerce#"
2487    a -> b
2488    { The function {\tt unsafeCoerce\#} allows you to side-step the typechecker entirely. That
2489         is, it allows you to coerce any type into any other type. If you use this function,
2490         you had better get it right, otherwise segmentation faults await. It is generally
2491         used when you want to write a program that you know is well-typed, but where Haskell's
2492         type system is not expressive enough to prove that it is well typed.
2493
2494         The following uses of {\tt unsafeCoerce\#} are supposed to work (i.e. not lead to
2495         spurious compile-time or run-time crashes):
2496
2497          * Casting any lifted type to {\tt Any}
2498
2499          * Casting {\tt Any} back to the real type
2500
2501          * Casting an unboxed type to another unboxed type of the same size
2502            (but not coercions between floating-point and integral types)
2503
2504          * Casting between two types that have the same runtime representation.  One case is when
2505            the two types differ only in "phantom" type parameters, for example
2506            {\tt Ptr Int} to {\tt Ptr Float}, or {\tt [Int]} to {\tt [Float]} when the list is
2507            known to be empty.  Also, a {\tt newtype} of a type {\tt T} has the same representation
2508            at runtime as {\tt T}.
2509
2510         Other uses of {\tt unsafeCoerce\#} are undefined.  In particular, you should not use
2511         {\tt unsafeCoerce\#} to cast a T to an algebraic data type D, unless T is also
2512         an algebraic data type.  For example, do not cast {\tt Int->Int} to {\tt Bool}, even if
2513         you later cast that {\tt Bool} back to {\tt Int->Int} before applying it.  The reasons
2514         have to do with GHC's internal representation details (for the congnoscenti, data values
2515         can be entered but function closures cannot).  If you want a safe type to cast things
2516         to, use {\tt Any}, which is not an algebraic data type.
2517
2518         }
2519
2520 -- NB. It is tempting to think that casting a value to a type that it doesn't have is safe
2521 -- as long as you don't "do anything" with the value in its cast form, such as seq on it.  This
2522 -- isn't the case: the compiler can insert seqs itself, and if these happen at the wrong type,
2523 -- Bad Things Might Happen.  See bug #1616: in this case we cast a function of type (a,b) -> (a,b)
2524 -- to () -> () and back again.  The strictness analyser saw that the function was strict, but
2525 -- the wrapper had type () -> (), and hence the wrapper de-constructed the (), the worker re-constructed
2526 -- a new (), with the result that the code ended up with "case () of (a,b) -> ...".
2527
2528 primop  TraceEventOp "traceEvent#" GenPrimOp
2529    Addr# -> State# s -> State# s
2530    { Emits an event via the RTS tracing framework.  The contents
2531      of the event is the zero-terminated byte string passed as the first
2532      argument.  The event will be emitted either to the .eventlog file,
2533      or to stderr, depending on the runtime RTS flags. }
2534    with
2535    has_side_effects = True
2536    out_of_line      = True
2537
2538 primop  TraceMarkerOp "traceMarker#" GenPrimOp
2539    Addr# -> State# s -> State# s
2540    { Emits a marker event via the RTS tracing framework.  The contents
2541      of the event is the zero-terminated byte string passed as the first
2542      argument.  The event will be emitted either to the .eventlog file,
2543      or to stderr, depending on the runtime RTS flags. }
2544    with
2545    has_side_effects = True
2546    out_of_line      = True
2547
2548 ------------------------------------------------------------------------
2549 section "Safe coercions"
2550 ------------------------------------------------------------------------
2551
2552 pseudoop   "coerce"
2553    Coercible a b => a -> b
2554    { The function {\tt coerce} allows you to safely convert between values of
2555      types that have the same representation with no run-time overhead. In the
2556      simplest case you can use it instead of a newtype constructor, to go from
2557      the newtype's concrete type to the abstract type. But it also works in
2558      more complicated settings, e.g. converting a list of newtypes to a list of
2559      concrete types.
2560    }
2561
2562 ------------------------------------------------------------------------
2563 section "SIMD Vectors"
2564         {Operations on SIMD vectors.}
2565 ------------------------------------------------------------------------
2566
2567 #define ALL_VECTOR_TYPES \
2568   [<Int8,Int#,16>,<Int16,Int#,8>,<Int32,INT32,4>,<Int64,INT64,2> \
2569   ,<Int8,Int#,32>,<Int16,Int#,16>,<Int32,INT32,8>,<Int64,INT64,4> \
2570   ,<Int8,Int#,64>,<Int16,Int#,32>,<Int32,INT32,16>,<Int64,INT64,8> \
2571   ,<Word8,Word#,16>,<Word16,Word#,8>,<Word32,WORD32,4>,<Word64,WORD64,2> \
2572   ,<Word8,Word#,32>,<Word16,Word#,16>,<Word32,WORD32,8>,<Word64,WORD64,4> \
2573   ,<Word8,Word#,64>,<Word16,Word#,32>,<Word32,WORD32,16>,<Word64,WORD64,8> \
2574   ,<Float,Float#,4>,<Double,Double#,2> \
2575   ,<Float,Float#,8>,<Double,Double#,4> \
2576   ,<Float,Float#,16>,<Double,Double#,8>]
2577
2578 #define SIGNED_VECTOR_TYPES \
2579   [<Int8,Int#,16>,<Int16,Int#,8>,<Int32,INT32,4>,<Int64,INT64,2> \
2580   ,<Int8,Int#,32>,<Int16,Int#,16>,<Int32,INT32,8>,<Int64,INT64,4> \
2581   ,<Int8,Int#,64>,<Int16,Int#,32>,<Int32,INT32,16>,<Int64,INT64,8> \
2582   ,<Float,Float#,4>,<Double,Double#,2> \
2583   ,<Float,Float#,8>,<Double,Double#,4> \
2584   ,<Float,Float#,16>,<Double,Double#,8>]
2585
2586 #define FLOAT_VECTOR_TYPES \
2587   [<Float,Float#,4>,<Double,Double#,2> \
2588   ,<Float,Float#,8>,<Double,Double#,4> \
2589   ,<Float,Float#,16>,<Double,Double#,8>]
2590
2591 #define INT_VECTOR_TYPES \
2592   [<Int8,Int#,16>,<Int16,Int#,8>,<Int32,INT32,4>,<Int64,INT64,2> \
2593   ,<Int8,Int#,32>,<Int16,Int#,16>,<Int32,INT32,8>,<Int64,INT64,4> \
2594   ,<Int8,Int#,64>,<Int16,Int#,32>,<Int32,INT32,16>,<Int64,INT64,8> \
2595   ,<Word8,Word#,16>,<Word16,Word#,8>,<Word32,WORD32,4>,<Word64,WORD64,2> \
2596   ,<Word8,Word#,32>,<Word16,Word#,16>,<Word32,WORD32,8>,<Word64,WORD64,4> \
2597   ,<Word8,Word#,64>,<Word16,Word#,32>,<Word32,WORD32,16>,<Word64,WORD64,8>]
2598
2599 primtype VECTOR
2600    with llvm_only = True
2601         vector = ALL_VECTOR_TYPES
2602
2603 primop VecBroadcastOp "broadcast#" GenPrimOp
2604    SCALAR -> VECTOR
2605    { Broadcast a scalar to all elements of a vector. }
2606    with llvm_only = True
2607         vector = ALL_VECTOR_TYPES
2608
2609 primop VecPackOp "pack#" GenPrimOp
2610    VECTUPLE -> VECTOR
2611    { Pack the elements of an unboxed tuple into a vector. }
2612    with llvm_only = True
2613         vector = ALL_VECTOR_TYPES
2614
2615 primop VecUnpackOp "unpack#" GenPrimOp
2616    VECTOR -> VECTUPLE
2617    { Unpack the elements of a vector into an unboxed tuple. #}
2618    with llvm_only = True
2619         vector = ALL_VECTOR_TYPES
2620
2621 primop VecInsertOp "insert#" GenPrimOp
2622    VECTOR -> SCALAR -> Int# -> VECTOR
2623    { Insert a scalar at the given position in a vector. }
2624    with can_fail = True
2625         llvm_only = True
2626         vector = ALL_VECTOR_TYPES
2627
2628 primop VecAddOp "plus#" Dyadic
2629    VECTOR -> VECTOR -> VECTOR
2630    { Add two vectors element-wise. }
2631    with commutable = True
2632         llvm_only = True
2633         vector = ALL_VECTOR_TYPES
2634
2635 primop VecSubOp "minus#" Dyadic
2636    VECTOR -> VECTOR -> VECTOR
2637    { Subtract two vectors element-wise. }
2638    with llvm_only = True
2639         vector = ALL_VECTOR_TYPES
2640
2641 primop VecMulOp "times#" Dyadic
2642    VECTOR -> VECTOR -> VECTOR
2643    { Multiply two vectors element-wise. }
2644    with commutable = True
2645         llvm_only = True
2646         vector = ALL_VECTOR_TYPES
2647
2648 primop VecDivOp "divide#" Dyadic
2649    VECTOR -> VECTOR -> VECTOR
2650    { Divide two vectors element-wise. }
2651    with can_fail = True
2652         llvm_only = True
2653         vector = FLOAT_VECTOR_TYPES
2654
2655 primop VecQuotOp "quot#" Dyadic
2656    VECTOR -> VECTOR -> VECTOR
2657    { Rounds towards zero element-wise. }
2658    with can_fail = True
2659         llvm_only = True
2660         vector = INT_VECTOR_TYPES
2661
2662 primop VecRemOp "rem#" Dyadic
2663    VECTOR -> VECTOR -> VECTOR
2664    { Satisfies \texttt{(quot\# x y) times\# y plus\# (rem\# x y) == x}. }
2665    with can_fail = True
2666         llvm_only = True
2667         vector = INT_VECTOR_TYPES
2668
2669 primop VecNegOp "negate#" Monadic
2670    VECTOR -> VECTOR
2671    { Negate element-wise. }
2672    with llvm_only = True
2673         vector = SIGNED_VECTOR_TYPES
2674
2675 primop VecIndexByteArrayOp "indexArray#" GenPrimOp
2676    ByteArray# -> Int# -> VECTOR
2677    { Read a vector from specified index of immutable array. }
2678    with can_fail = True
2679         llvm_only = True
2680         vector = ALL_VECTOR_TYPES
2681
2682 primop VecReadByteArrayOp "readArray#" GenPrimOp
2683    MutableByteArray# s -> Int# -> State# s -> (# State# s, VECTOR #)
2684    { Read a vector from specified index of mutable array. }
2685    with has_side_effects = True
2686         can_fail = True
2687         llvm_only = True
2688         vector = ALL_VECTOR_TYPES
2689
2690 primop VecWriteByteArrayOp "writeArray#" GenPrimOp
2691    MutableByteArray# s -> Int# -> VECTOR -> State# s -> State# s
2692    { Write a vector to specified index of mutable array. }
2693    with has_side_effects = True
2694         can_fail = True
2695         llvm_only = True
2696         vector = ALL_VECTOR_TYPES
2697
2698 primop VecIndexOffAddrOp "indexOffAddr#" GenPrimOp
2699    Addr# -> Int# -> VECTOR
2700    { Reads vector; offset in bytes. }
2701    with can_fail = True
2702         llvm_only = True
2703         vector = ALL_VECTOR_TYPES
2704
2705 primop VecReadOffAddrOp "readOffAddr#" GenPrimOp
2706    Addr# -> Int# -> State# s -> (# State# s, VECTOR #)
2707    { Reads vector; offset in bytes. }
2708    with has_side_effects = True
2709         can_fail = True
2710         llvm_only = True
2711         vector = ALL_VECTOR_TYPES
2712
2713 primop VecWriteOffAddrOp "writeOffAddr#" GenPrimOp
2714    Addr# -> Int# -> VECTOR -> State# s -> State# s
2715    { Write vector; offset in bytes. }
2716    with has_side_effects = True
2717         can_fail = True
2718         llvm_only = True
2719         vector = ALL_VECTOR_TYPES
2720
2721
2722 primop VecIndexScalarByteArrayOp "indexArrayAs#" GenPrimOp
2723    ByteArray# -> Int# -> VECTOR
2724    { Read a vector from specified index of immutable array of scalars; offset is in scalar elements. }
2725    with can_fail = True
2726         llvm_only = True
2727         vector = ALL_VECTOR_TYPES
2728
2729 primop VecReadScalarByteArrayOp "readArrayAs#" GenPrimOp
2730    MutableByteArray# s -> Int# -> State# s -> (# State# s, VECTOR #)
2731    { Read a vector from specified index of mutable array of scalars; offset is in scalar elements. }
2732    with has_side_effects = True
2733         can_fail = True
2734         llvm_only = True
2735         vector = ALL_VECTOR_TYPES
2736
2737 primop VecWriteScalarByteArrayOp "writeArrayAs#" GenPrimOp
2738    MutableByteArray# s -> Int# -> VECTOR -> State# s -> State# s
2739    { Write a vector to specified index of mutable array of scalars; offset is in scalar elements. }
2740    with has_side_effects = True
2741         can_fail = True
2742         llvm_only = True
2743         vector = ALL_VECTOR_TYPES
2744
2745 primop VecIndexScalarOffAddrOp "indexOffAddrAs#" GenPrimOp
2746    Addr# -> Int# -> VECTOR
2747    { Reads vector; offset in scalar elements. }
2748    with can_fail = True
2749         llvm_only = True
2750         vector = ALL_VECTOR_TYPES
2751
2752 primop VecReadScalarOffAddrOp "readOffAddrAs#" GenPrimOp
2753    Addr# -> Int# -> State# s -> (# State# s, VECTOR #)
2754    { Reads vector; offset in scalar elements. }
2755    with has_side_effects = True
2756         can_fail = True
2757         llvm_only = True
2758         vector = ALL_VECTOR_TYPES
2759
2760 primop VecWriteScalarOffAddrOp "writeOffAddrAs#" GenPrimOp
2761    Addr# -> Int# -> VECTOR -> State# s -> State# s
2762    { Write vector; offset in scalar elements. }
2763    with has_side_effects = True
2764         can_fail = True
2765         llvm_only = True
2766         vector = ALL_VECTOR_TYPES
2767
2768 ------------------------------------------------------------------------
2769
2770 section "Prefetch"
2771         {Prefetch operations: Note how every prefetch operation has a name
2772   with the pattern prefetch*N#, where N is either 0,1,2, or 3.
2773
2774   This suffix number, N, is the "locality level" of the prefetch, following the
2775   convention in GCC and other compilers.
2776   Higher locality numbers correspond to the memory being loaded in more
2777   levels of the cpu cache, and being retained after initial use. The naming
2778   convention follows the naming convention of the prefetch intrinsic found
2779   in the GCC and Clang C compilers.
2780
2781   On the LLVM backend, prefetch*N# uses the LLVM prefetch intrinsic
2782   with locality level N. The code generated by LLVM is target architecture
2783   dependent, but should agree with the GHC NCG on x86 systems.
2784
2785   On the Sparc and PPC native backends, prefetch*N is a No-Op.
2786
2787   On the x86 NCG, N=0 will generate prefetchNTA,
2788   N=1 generates prefetcht2, N=2 generates prefetcht1, and
2789   N=3 generates prefetcht0.
2790
2791   For streaming workloads, the prefetch*0 operations are recommended.
2792   For workloads which do many reads or writes to a memory location in a short period of time,
2793   prefetch*3 operations are recommended.
2794
2795   For further reading about prefetch and associated systems performance optimization,
2796   the instruction set and optimization manuals by Intel and other CPU vendors are
2797   excellent starting place.
2798
2799
2800   The "Intel 64 and IA-32 Architectures Optimization Reference Manual" is
2801   especially a helpful read, even if your software is meant for other CPU
2802   architectures or vendor hardware. The manual can be found at
2803   http://www.intel.com/content/www/us/en/architecture-and-technology/64-ia-32-architectures-optimization-manual.html .
2804
2805   The {\tt prefetchMutableByteArray} family of operations has the order of operations
2806   determined by passing around the {\tt State#} token.
2807
2808   For the {\tt prefetchByteArray}
2809   and {\tt prefetchAddr} families of operations, consider the following example:
2810
2811   {\tt let a1 = prefetchByteArray2# a n in ...a1... }
2812
2813   In the above fragement, {\tt a} is the input variable for the prefetch
2814   and {\tt a1 == a} will be true. To ensure that the prefetch is not treated as deadcode,
2815   the body of the let should only use {\tt a1} and NOT {\tt a}. The same principle
2816   applies for uses of prefetch in a loop.
2817
2818   }
2819
2820
2821 ------------------------------------------------------------------------
2822
2823
2824 --- the Int# argument for prefetch is the byte offset on the byteArray or  Addr#
2825
2826 ---
2827 primop PrefetchByteArrayOp3 "prefetchByteArray3#" GenPrimOp
2828    ByteArray# -> Int# -> ByteArray#
2829
2830 primop PrefetchMutableByteArrayOp3 "prefetchMutableByteArray3#" GenPrimOp
2831    MutableByteArray# s -> Int# -> State# s -> State# s
2832
2833 primop PrefetchAddrOp3 "prefetchAddr3#" GenPrimOp
2834     Addr# -> Int# -> Addr#
2835
2836 ----
2837
2838 primop PrefetchByteArrayOp2 "prefetchByteArray2#" GenPrimOp
2839    ByteArray# -> Int# -> ByteArray#
2840
2841 primop PrefetchMutableByteArrayOp2 "prefetchMutableByteArray2#" GenPrimOp
2842    MutableByteArray# s -> Int# -> State# s -> State# s
2843
2844 primop PrefetchAddrOp2 "prefetchAddr2#" GenPrimOp
2845    Addr# -> Int# -> Addr#
2846
2847 ----
2848
2849 primop PrefetchByteArrayOp1 "prefetchByteArray1#" GenPrimOp
2850    ByteArray# -> Int# -> ByteArray#
2851
2852 primop PrefetchMutableByteArrayOp1 "prefetchMutableByteArray1#" GenPrimOp
2853    MutableByteArray# s -> Int# -> State# s -> State# s
2854
2855 primop PrefetchAddrOp1 "prefetchAddr1#" GenPrimOp
2856    Addr# -> Int# -> Addr#
2857
2858 ----
2859
2860 primop PrefetchByteArrayOp0 "prefetchByteArray0#" GenPrimOp
2861    ByteArray# -> Int# -> ByteArray#
2862
2863 primop PrefetchMutableByteArrayOp0 "prefetchMutableByteArray0#" GenPrimOp
2864    MutableByteArray# s -> Int# -> State# s -> State# s
2865
2866 primop PrefetchAddrOp0 "prefetchAddr0#" GenPrimOp
2867    Addr# -> Int# -> Addr#
2868
2869
2870
2871 ------------------------------------------------------------------------
2872 ---                                                                  ---
2873 ------------------------------------------------------------------------
2874
2875 thats_all_folks