Add has_side_effets to the raise# primop
[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 -- Atomic operations
1367
1368 primop  AtomicReadByteArrayOp_Int "atomicReadIntArray#" GenPrimOp
1369    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
1370    {Given an array and an offset in Int units, read an element. The
1371     index is assumed to be in bounds. Implies a full memory barrier.}
1372    with has_side_effects = True
1373         can_fail = True
1374
1375 primop  AtomicWriteByteArrayOp_Int "atomicWriteIntArray#" GenPrimOp
1376    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1377    {Given an array and an offset in Int units, write an element. The
1378     index is assumed to be in bounds. Implies a full memory barrier.}
1379    with has_side_effects = True
1380         can_fail = True
1381
1382 primop CasByteArrayOp_Int "casIntArray#" GenPrimOp
1383    MutableByteArray# s -> Int# -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1384    {Given an array, an offset in Int units, the expected old value, and
1385     the new value, perform an atomic compare and swap i.e. write the new
1386     value if the current value matches the provided old value. Returns
1387     the value of the element before the operation. Implies a full memory
1388     barrier.}
1389    with has_side_effects = True
1390         can_fail = True
1391
1392 primop FetchAddByteArrayOp_Int "fetchAddIntArray#" GenPrimOp
1393    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1394    {Given an array, and offset in Int units, and a value to add,
1395     atomically add the value to the element. Returns the value of the
1396     element before the operation. Implies a full memory barrier.}
1397    with has_side_effects = True
1398         can_fail = True
1399
1400 primop FetchSubByteArrayOp_Int "fetchSubIntArray#" GenPrimOp
1401    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1402    {Given an array, and offset in Int units, and a value to subtract,
1403     atomically substract the value to the element. Returns the value of
1404     the element before the operation. Implies a full memory barrier.}
1405    with has_side_effects = True
1406         can_fail = True
1407
1408 primop FetchAndByteArrayOp_Int "fetchAndIntArray#" GenPrimOp
1409    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1410    {Given an array, and offset in Int units, and a value to AND,
1411     atomically AND the value to the element. Returns the value of the
1412     element before the operation. Implies a full memory barrier.}
1413    with has_side_effects = True
1414         can_fail = True
1415
1416 primop FetchNandByteArrayOp_Int "fetchNandIntArray#" GenPrimOp
1417    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1418    {Given an array, and offset in Int units, and a value to NAND,
1419     atomically NAND the value to the element. Returns the value of the
1420     element before the operation. Implies a full memory barrier.}
1421    with has_side_effects = True
1422         can_fail = True
1423
1424 primop FetchOrByteArrayOp_Int "fetchOrIntArray#" GenPrimOp
1425    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1426    {Given an array, and offset in Int units, and a value to OR,
1427     atomically OR the value to the element. Returns the value of the
1428     element before the operation. Implies a full memory barrier.}
1429    with has_side_effects = True
1430         can_fail = True
1431
1432 primop FetchXorByteArrayOp_Int "fetchXorIntArray#" GenPrimOp
1433    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1434    {Given an array, and offset in Int units, and a value to XOR,
1435     atomically XOR the value to the element. Returns the value of the
1436     element before the operation. Implies a full memory barrier.}
1437    with has_side_effects = True
1438         can_fail = True
1439
1440
1441 ------------------------------------------------------------------------
1442 section "Arrays of arrays"
1443         {Operations on {\tt ArrayArray\#}. An {\tt ArrayArray\#} contains references to {\em unpointed}
1444          arrays, such as {\tt ByteArray\#s}. Hence, it is not parameterised by the element types,
1445          just like a {\tt ByteArray\#}, but it needs to be scanned during GC, just like an {\tt Array#}.
1446          We represent an {\tt ArrayArray\#} exactly as a {\tt Array\#}, but provide element-type-specific
1447          indexing, reading, and writing.}
1448 ------------------------------------------------------------------------
1449
1450 primtype ArrayArray#
1451
1452 primtype MutableArrayArray# s
1453
1454 primop  NewArrayArrayOp "newArrayArray#" GenPrimOp
1455    Int# -> State# s -> (# State# s, MutableArrayArray# s #)
1456    {Create a new mutable array of arrays with the specified number of elements,
1457     in the specified state thread, with each element recursively referring to the
1458     newly created array.}
1459    with
1460    out_of_line = True
1461    has_side_effects = True
1462
1463 primop  SameMutableArrayArrayOp "sameMutableArrayArray#" GenPrimOp
1464    MutableArrayArray# s -> MutableArrayArray# s -> Int#
1465
1466 primop  UnsafeFreezeArrayArrayOp "unsafeFreezeArrayArray#" GenPrimOp
1467    MutableArrayArray# s -> State# s -> (# State# s, ArrayArray# #)
1468    {Make a mutable array of arrays immutable, without copying.}
1469    with
1470    has_side_effects = True
1471
1472 primop  SizeofArrayArrayOp "sizeofArrayArray#" GenPrimOp
1473    ArrayArray# -> Int#
1474    {Return the number of elements in the array.}
1475
1476 primop  SizeofMutableArrayArrayOp "sizeofMutableArrayArray#" GenPrimOp
1477    MutableArrayArray# s -> Int#
1478    {Return the number of elements in the array.}
1479
1480 primop IndexArrayArrayOp_ByteArray "indexByteArrayArray#" GenPrimOp
1481    ArrayArray# -> Int# -> ByteArray#
1482    with can_fail = True
1483
1484 primop IndexArrayArrayOp_ArrayArray "indexArrayArrayArray#" GenPrimOp
1485    ArrayArray# -> Int# -> ArrayArray#
1486    with can_fail = True
1487
1488 primop  ReadArrayArrayOp_ByteArray "readByteArrayArray#" GenPrimOp
1489    MutableArrayArray# s -> Int# -> State# s -> (# State# s, ByteArray# #)
1490    with has_side_effects = True
1491         can_fail = True
1492
1493 primop  ReadArrayArrayOp_MutableByteArray "readMutableByteArrayArray#" GenPrimOp
1494    MutableArrayArray# s -> Int# -> State# s -> (# State# s, MutableByteArray# s #)
1495    with has_side_effects = True
1496         can_fail = True
1497
1498 primop  ReadArrayArrayOp_ArrayArray "readArrayArrayArray#" GenPrimOp
1499    MutableArrayArray# s -> Int# -> State# s -> (# State# s, ArrayArray# #)
1500    with has_side_effects = True
1501         can_fail = True
1502
1503 primop  ReadArrayArrayOp_MutableArrayArray "readMutableArrayArrayArray#" GenPrimOp
1504    MutableArrayArray# s -> Int# -> State# s -> (# State# s, MutableArrayArray# s #)
1505    with has_side_effects = True
1506         can_fail = True
1507
1508 primop  WriteArrayArrayOp_ByteArray "writeByteArrayArray#" GenPrimOp
1509    MutableArrayArray# s -> Int# -> ByteArray# -> State# s -> State# s
1510    with has_side_effects = True
1511         can_fail = True
1512
1513 primop  WriteArrayArrayOp_MutableByteArray "writeMutableByteArrayArray#" GenPrimOp
1514    MutableArrayArray# s -> Int# -> MutableByteArray# s -> State# s -> State# s
1515    with has_side_effects = True
1516         can_fail = True
1517
1518 primop  WriteArrayArrayOp_ArrayArray "writeArrayArrayArray#" GenPrimOp
1519    MutableArrayArray# s -> Int# -> ArrayArray# -> State# s -> State# s
1520    with has_side_effects = True
1521         can_fail = True
1522
1523 primop  WriteArrayArrayOp_MutableArrayArray "writeMutableArrayArrayArray#" GenPrimOp
1524    MutableArrayArray# s -> Int# -> MutableArrayArray# s -> State# s -> State# s
1525    with has_side_effects = True
1526         can_fail = True
1527
1528 primop  CopyArrayArrayOp "copyArrayArray#" GenPrimOp
1529   ArrayArray# -> Int# -> MutableArrayArray# s -> Int# -> Int# -> State# s -> State# s
1530   {Copy a range of the ArrayArray# to the specified region in the MutableArrayArray#.
1531    Both arrays must fully contain the specified ranges, but this is not checked.
1532    The two arrays must not be the same array in different states, but this is not checked either.}
1533   with
1534   out_of_line      = True
1535   has_side_effects = True
1536   can_fail         = True
1537
1538 primop  CopyMutableArrayArrayOp "copyMutableArrayArray#" GenPrimOp
1539   MutableArrayArray# s -> Int# -> MutableArrayArray# s -> Int# -> Int# -> State# s -> State# s
1540   {Copy a range of the first MutableArrayArray# to the specified region in the second
1541    MutableArrayArray#.
1542    Both arrays must fully contain the specified ranges, but this is not checked.}
1543   with
1544   out_of_line      = True
1545   has_side_effects = True
1546   can_fail         = True
1547
1548 ------------------------------------------------------------------------
1549 section "Addr#"
1550 ------------------------------------------------------------------------
1551
1552 primtype Addr#
1553         { An arbitrary machine address assumed to point outside
1554          the garbage-collected heap. }
1555
1556 pseudoop "nullAddr#" Addr#
1557         { The null address. }
1558
1559 primop   AddrAddOp "plusAddr#" GenPrimOp Addr# -> Int# -> Addr#
1560 primop   AddrSubOp "minusAddr#" GenPrimOp Addr# -> Addr# -> Int#
1561          {Result is meaningless if two {\tt Addr\#}s are so far apart that their
1562          difference doesn't fit in an {\tt Int\#}.}
1563 primop   AddrRemOp "remAddr#" GenPrimOp Addr# -> Int# -> Int#
1564          {Return the remainder when the {\tt Addr\#} arg, treated like an {\tt Int\#},
1565           is divided by the {\tt Int\#} arg.}
1566 #if (WORD_SIZE_IN_BITS == 32 || WORD_SIZE_IN_BITS == 64)
1567 primop   Addr2IntOp  "addr2Int#"     GenPrimOp   Addr# -> Int#
1568         {Coerce directly from address to int. Strongly deprecated.}
1569    with code_size = 0
1570 primop   Int2AddrOp   "int2Addr#"    GenPrimOp  Int# -> Addr#
1571         {Coerce directly from int to address. Strongly deprecated.}
1572    with code_size = 0
1573 #endif
1574
1575 primop   AddrGtOp  "gtAddr#"   Compare   Addr# -> Addr# -> Int#
1576 primop   AddrGeOp  "geAddr#"   Compare   Addr# -> Addr# -> Int#
1577 primop   AddrEqOp  "eqAddr#"   Compare   Addr# -> Addr# -> Int#
1578 primop   AddrNeOp  "neAddr#"   Compare   Addr# -> Addr# -> Int#
1579 primop   AddrLtOp  "ltAddr#"   Compare   Addr# -> Addr# -> Int#
1580 primop   AddrLeOp  "leAddr#"   Compare   Addr# -> Addr# -> Int#
1581
1582 primop IndexOffAddrOp_Char "indexCharOffAddr#" GenPrimOp
1583    Addr# -> Int# -> Char#
1584    {Reads 8-bit character; offset in bytes.}
1585    with can_fail = True
1586
1587 primop IndexOffAddrOp_WideChar "indexWideCharOffAddr#" GenPrimOp
1588    Addr# -> Int# -> Char#
1589    {Reads 31-bit character; offset in 4-byte words.}
1590    with can_fail = True
1591
1592 primop IndexOffAddrOp_Int "indexIntOffAddr#" GenPrimOp
1593    Addr# -> Int# -> Int#
1594    with can_fail = True
1595
1596 primop IndexOffAddrOp_Word "indexWordOffAddr#" GenPrimOp
1597    Addr# -> Int# -> Word#
1598    with can_fail = True
1599
1600 primop IndexOffAddrOp_Addr "indexAddrOffAddr#" GenPrimOp
1601    Addr# -> Int# -> Addr#
1602    with can_fail = True
1603
1604 primop IndexOffAddrOp_Float "indexFloatOffAddr#" GenPrimOp
1605    Addr# -> Int# -> Float#
1606    with can_fail = True
1607
1608 primop IndexOffAddrOp_Double "indexDoubleOffAddr#" GenPrimOp
1609    Addr# -> Int# -> Double#
1610    with can_fail = True
1611
1612 primop IndexOffAddrOp_StablePtr "indexStablePtrOffAddr#" GenPrimOp
1613    Addr# -> Int# -> StablePtr# a
1614    with can_fail = True
1615
1616 primop IndexOffAddrOp_Int8 "indexInt8OffAddr#" GenPrimOp
1617    Addr# -> Int# -> Int#
1618    with can_fail = True
1619
1620 primop IndexOffAddrOp_Int16 "indexInt16OffAddr#" GenPrimOp
1621    Addr# -> Int# -> Int#
1622    with can_fail = True
1623
1624 primop IndexOffAddrOp_Int32 "indexInt32OffAddr#" GenPrimOp
1625    Addr# -> Int# -> INT32
1626    with can_fail = True
1627
1628 primop IndexOffAddrOp_Int64 "indexInt64OffAddr#" GenPrimOp
1629    Addr# -> Int# -> INT64
1630    with can_fail = True
1631
1632 primop IndexOffAddrOp_Word8 "indexWord8OffAddr#" GenPrimOp
1633    Addr# -> Int# -> Word#
1634    with can_fail = True
1635
1636 primop IndexOffAddrOp_Word16 "indexWord16OffAddr#" GenPrimOp
1637    Addr# -> Int# -> Word#
1638    with can_fail = True
1639
1640 primop IndexOffAddrOp_Word32 "indexWord32OffAddr#" GenPrimOp
1641    Addr# -> Int# -> WORD32
1642    with can_fail = True
1643
1644 primop IndexOffAddrOp_Word64 "indexWord64OffAddr#" GenPrimOp
1645    Addr# -> Int# -> WORD64
1646    with can_fail = True
1647
1648 primop ReadOffAddrOp_Char "readCharOffAddr#" GenPrimOp
1649    Addr# -> Int# -> State# s -> (# State# s, Char# #)
1650    {Reads 8-bit character; offset in bytes.}
1651    with has_side_effects = True
1652         can_fail         = True
1653
1654 primop ReadOffAddrOp_WideChar "readWideCharOffAddr#" GenPrimOp
1655    Addr# -> Int# -> State# s -> (# State# s, Char# #)
1656    {Reads 31-bit character; offset in 4-byte words.}
1657    with has_side_effects = True
1658         can_fail         = True
1659
1660 primop ReadOffAddrOp_Int "readIntOffAddr#" GenPrimOp
1661    Addr# -> Int# -> State# s -> (# State# s, Int# #)
1662    with has_side_effects = True
1663         can_fail         = True
1664
1665 primop ReadOffAddrOp_Word "readWordOffAddr#" GenPrimOp
1666    Addr# -> Int# -> State# s -> (# State# s, Word# #)
1667    with has_side_effects = True
1668         can_fail         = True
1669
1670 primop ReadOffAddrOp_Addr "readAddrOffAddr#" GenPrimOp
1671    Addr# -> Int# -> State# s -> (# State# s, Addr# #)
1672    with has_side_effects = True
1673         can_fail         = True
1674
1675 primop ReadOffAddrOp_Float "readFloatOffAddr#" GenPrimOp
1676    Addr# -> Int# -> State# s -> (# State# s, Float# #)
1677    with has_side_effects = True
1678         can_fail         = True
1679
1680 primop ReadOffAddrOp_Double "readDoubleOffAddr#" GenPrimOp
1681    Addr# -> Int# -> State# s -> (# State# s, Double# #)
1682    with has_side_effects = True
1683         can_fail         = True
1684
1685 primop ReadOffAddrOp_StablePtr "readStablePtrOffAddr#" GenPrimOp
1686    Addr# -> Int# -> State# s -> (# State# s, StablePtr# a #)
1687    with has_side_effects = True
1688         can_fail         = True
1689
1690 primop ReadOffAddrOp_Int8 "readInt8OffAddr#" GenPrimOp
1691    Addr# -> Int# -> State# s -> (# State# s, Int# #)
1692    with has_side_effects = True
1693         can_fail         = True
1694
1695 primop ReadOffAddrOp_Int16 "readInt16OffAddr#" GenPrimOp
1696    Addr# -> Int# -> State# s -> (# State# s, Int# #)
1697    with has_side_effects = True
1698         can_fail         = True
1699
1700 primop ReadOffAddrOp_Int32 "readInt32OffAddr#" GenPrimOp
1701    Addr# -> Int# -> State# s -> (# State# s, INT32 #)
1702    with has_side_effects = True
1703         can_fail         = True
1704
1705 primop ReadOffAddrOp_Int64 "readInt64OffAddr#" GenPrimOp
1706    Addr# -> Int# -> State# s -> (# State# s, INT64 #)
1707    with has_side_effects = True
1708         can_fail         = True
1709
1710 primop ReadOffAddrOp_Word8 "readWord8OffAddr#" GenPrimOp
1711    Addr# -> Int# -> State# s -> (# State# s, Word# #)
1712    with has_side_effects = True
1713         can_fail         = True
1714
1715 primop ReadOffAddrOp_Word16 "readWord16OffAddr#" GenPrimOp
1716    Addr# -> Int# -> State# s -> (# State# s, Word# #)
1717    with has_side_effects = True
1718         can_fail         = True
1719
1720 primop ReadOffAddrOp_Word32 "readWord32OffAddr#" GenPrimOp
1721    Addr# -> Int# -> State# s -> (# State# s, WORD32 #)
1722    with has_side_effects = True
1723         can_fail         = True
1724
1725 primop ReadOffAddrOp_Word64 "readWord64OffAddr#" GenPrimOp
1726    Addr# -> Int# -> State# s -> (# State# s, WORD64 #)
1727    with has_side_effects = True
1728         can_fail         = True
1729
1730 primop  WriteOffAddrOp_Char "writeCharOffAddr#" GenPrimOp
1731    Addr# -> Int# -> Char# -> State# s -> State# s
1732    with has_side_effects = True
1733         can_fail         = True
1734
1735 primop  WriteOffAddrOp_WideChar "writeWideCharOffAddr#" GenPrimOp
1736    Addr# -> Int# -> Char# -> State# s -> State# s
1737    with has_side_effects = True
1738         can_fail         = True
1739
1740 primop  WriteOffAddrOp_Int "writeIntOffAddr#" GenPrimOp
1741    Addr# -> Int# -> Int# -> State# s -> State# s
1742    with has_side_effects = True
1743         can_fail         = True
1744
1745 primop  WriteOffAddrOp_Word "writeWordOffAddr#" GenPrimOp
1746    Addr# -> Int# -> Word# -> State# s -> State# s
1747    with has_side_effects = True
1748         can_fail         = True
1749
1750 primop  WriteOffAddrOp_Addr "writeAddrOffAddr#" GenPrimOp
1751    Addr# -> Int# -> Addr# -> State# s -> State# s
1752    with has_side_effects = True
1753         can_fail         = True
1754
1755 primop  WriteOffAddrOp_Float "writeFloatOffAddr#" GenPrimOp
1756    Addr# -> Int# -> Float# -> State# s -> State# s
1757    with has_side_effects = True
1758         can_fail         = True
1759
1760 primop  WriteOffAddrOp_Double "writeDoubleOffAddr#" GenPrimOp
1761    Addr# -> Int# -> Double# -> State# s -> State# s
1762    with has_side_effects = True
1763         can_fail         = True
1764
1765 primop  WriteOffAddrOp_StablePtr "writeStablePtrOffAddr#" GenPrimOp
1766    Addr# -> Int# -> StablePtr# a -> State# s -> State# s
1767    with has_side_effects = True
1768         can_fail         = True
1769
1770 primop  WriteOffAddrOp_Int8 "writeInt8OffAddr#" GenPrimOp
1771    Addr# -> Int# -> Int# -> State# s -> State# s
1772    with has_side_effects = True
1773         can_fail         = True
1774
1775 primop  WriteOffAddrOp_Int16 "writeInt16OffAddr#" GenPrimOp
1776    Addr# -> Int# -> Int# -> State# s -> State# s
1777    with has_side_effects = True
1778         can_fail         = True
1779
1780 primop  WriteOffAddrOp_Int32 "writeInt32OffAddr#" GenPrimOp
1781    Addr# -> Int# -> INT32 -> State# s -> State# s
1782    with has_side_effects = True
1783         can_fail         = True
1784
1785 primop  WriteOffAddrOp_Int64 "writeInt64OffAddr#" GenPrimOp
1786    Addr# -> Int# -> INT64 -> State# s -> State# s
1787    with has_side_effects = True
1788         can_fail         = True
1789
1790 primop  WriteOffAddrOp_Word8 "writeWord8OffAddr#" GenPrimOp
1791    Addr# -> Int# -> Word# -> State# s -> State# s
1792    with has_side_effects = True
1793         can_fail         = True
1794
1795 primop  WriteOffAddrOp_Word16 "writeWord16OffAddr#" GenPrimOp
1796    Addr# -> Int# -> Word# -> State# s -> State# s
1797    with has_side_effects = True
1798         can_fail         = True
1799
1800 primop  WriteOffAddrOp_Word32 "writeWord32OffAddr#" GenPrimOp
1801    Addr# -> Int# -> WORD32 -> State# s -> State# s
1802    with has_side_effects = True
1803         can_fail         = True
1804
1805 primop  WriteOffAddrOp_Word64 "writeWord64OffAddr#" GenPrimOp
1806    Addr# -> Int# -> WORD64 -> State# s -> State# s
1807    with has_side_effects = True
1808         can_fail         = True
1809
1810 ------------------------------------------------------------------------
1811 section "Mutable variables"
1812         {Operations on MutVar\#s.}
1813 ------------------------------------------------------------------------
1814
1815 primtype MutVar# s a
1816         {A {\tt MutVar\#} behaves like a single-element mutable array.}
1817
1818 primop  NewMutVarOp "newMutVar#" GenPrimOp
1819    a -> State# s -> (# State# s, MutVar# s a #)
1820    {Create {\tt MutVar\#} with specified initial value in specified state thread.}
1821    with
1822    out_of_line = True
1823    has_side_effects = True
1824
1825 primop  ReadMutVarOp "readMutVar#" GenPrimOp
1826    MutVar# s a -> State# s -> (# State# s, a #)
1827    {Read contents of {\tt MutVar\#}. Result is not yet evaluated.}
1828    with
1829    has_side_effects = True
1830    can_fail         = True
1831
1832 primop  WriteMutVarOp "writeMutVar#"  GenPrimOp
1833    MutVar# s a -> a -> State# s -> State# s
1834    {Write contents of {\tt MutVar\#}.}
1835    with
1836    has_side_effects = True
1837    code_size = { primOpCodeSizeForeignCall } -- for the write barrier
1838    can_fail         = True
1839
1840 primop  SameMutVarOp "sameMutVar#" GenPrimOp
1841    MutVar# s a -> MutVar# s a -> Int#
1842
1843 -- not really the right type, but we don't know about pairs here.  The
1844 -- correct type is
1845 --
1846 --   MutVar# s a -> (a -> (a,b)) -> State# s -> (# State# s, b #)
1847 --
1848 primop  AtomicModifyMutVarOp "atomicModifyMutVar#" GenPrimOp
1849    MutVar# s a -> (a -> b) -> State# s -> (# State# s, c #)
1850    with
1851    out_of_line = True
1852    has_side_effects = True
1853    can_fail         = True
1854
1855 primop  CasMutVarOp "casMutVar#" GenPrimOp
1856   MutVar# s a -> a -> a -> State# s -> (# State# s, Int#, a #)
1857    with
1858    out_of_line = True
1859    has_side_effects = True
1860
1861 ------------------------------------------------------------------------
1862 section "Exceptions"
1863 ------------------------------------------------------------------------
1864
1865 primop  CatchOp "catch#" GenPrimOp
1866           (State# RealWorld -> (# State# RealWorld, a #) )
1867        -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1868        -> State# RealWorld
1869        -> (# State# RealWorld, a #)
1870    with
1871         -- Catch is actually strict in its first argument
1872         -- but we don't want to tell the strictness
1873         -- analyser about that, so that exceptions stay inside it.
1874    strictness  = { \ _arity -> mkClosedStrictSig [apply1Dmd,apply2Dmd,topDmd] topRes }
1875    out_of_line = True
1876    has_side_effects = True
1877
1878 primop  RaiseOp "raise#" GenPrimOp
1879    a -> b
1880    with
1881    strictness  = { \ _arity -> mkClosedStrictSig [topDmd] botRes }
1882       -- NB: result is bottom
1883    out_of_line = True
1884    has_side_effects = True
1885      -- raise# certainly throws a Haskell exception and hence has_side_effects
1886      -- It doesn't actually make much difference because the fact that it
1887      -- returns bottom independently ensures that we are careful not to discard
1888      -- it.  But still, it's better to say the Right Thing.
1889
1890 -- raiseIO# needs to be a primop, because exceptions in the IO monad
1891 -- must be *precise* - we don't want the strictness analyser turning
1892 -- one kind of bottom into another, as it is allowed to do in pure code.
1893 --
1894 -- But we *do* want to know that it returns bottom after
1895 -- being applied to two arguments, so that this function is strict in y
1896 --     f x y | x>0       = raiseIO blah
1897 --           | y>0       = return 1
1898 --           | otherwise = return 2
1899
1900 primop  RaiseIOOp "raiseIO#" GenPrimOp
1901    a -> State# RealWorld -> (# State# RealWorld, b #)
1902    with
1903    strictness  = { \ _arity -> mkClosedStrictSig [topDmd, topDmd] botRes }
1904    out_of_line = True
1905    has_side_effects = True
1906
1907 primop  MaskAsyncExceptionsOp "maskAsyncExceptions#" GenPrimOp
1908         (State# RealWorld -> (# State# RealWorld, a #))
1909      -> (State# RealWorld -> (# State# RealWorld, a #))
1910    with
1911    strictness  = { \ _arity -> mkClosedStrictSig [apply1Dmd,topDmd] topRes }
1912    out_of_line = True
1913    has_side_effects = True
1914
1915 primop  MaskUninterruptibleOp "maskUninterruptible#" GenPrimOp
1916         (State# RealWorld -> (# State# RealWorld, a #))
1917      -> (State# RealWorld -> (# State# RealWorld, a #))
1918    with
1919    strictness  = { \ _arity -> mkClosedStrictSig [apply1Dmd,topDmd] topRes }
1920    out_of_line = True
1921    has_side_effects = True
1922
1923 primop  UnmaskAsyncExceptionsOp "unmaskAsyncExceptions#" GenPrimOp
1924         (State# RealWorld -> (# State# RealWorld, a #))
1925      -> (State# RealWorld -> (# State# RealWorld, a #))
1926    with
1927    strictness  = { \ _arity -> mkClosedStrictSig [apply1Dmd,topDmd] topRes }
1928    out_of_line = True
1929    has_side_effects = True
1930
1931 primop  MaskStatus "getMaskingState#" GenPrimOp
1932         State# RealWorld -> (# State# RealWorld, Int# #)
1933    with
1934    out_of_line = True
1935    has_side_effects = True
1936
1937 ------------------------------------------------------------------------
1938 section "STM-accessible Mutable Variables"
1939 ------------------------------------------------------------------------
1940
1941 primtype TVar# s a
1942
1943 primop  AtomicallyOp "atomically#" GenPrimOp
1944       (State# RealWorld -> (# State# RealWorld, a #) )
1945    -> State# RealWorld -> (# State# RealWorld, a #)
1946    with
1947    strictness  = { \ _arity -> mkClosedStrictSig [apply1Dmd,topDmd] topRes }
1948    out_of_line = True
1949    has_side_effects = True
1950
1951 -- NB: retry#'s strictness information specifies it to return bottom.
1952 -- This lets the compiler perform some extra simplifications, since retry#
1953 -- will technically never return.
1954 --
1955 -- This allows the simplifier to replace things like:
1956 --   case retry# s1
1957 --     (# s2, a #) -> e
1958 -- with:
1959 --   retry# s1
1960 -- where 'e' would be unreachable anyway.  See Trac #8091.
1961 primop  RetryOp "retry#" GenPrimOp
1962    State# RealWorld -> (# State# RealWorld, a #)
1963    with
1964    strictness  = { \ _arity -> mkClosedStrictSig [topDmd] botRes }
1965    out_of_line = True
1966    has_side_effects = True
1967
1968 primop  CatchRetryOp "catchRetry#" GenPrimOp
1969       (State# RealWorld -> (# State# RealWorld, a #) )
1970    -> (State# RealWorld -> (# State# RealWorld, a #) )
1971    -> (State# RealWorld -> (# State# RealWorld, a #) )
1972    with
1973    strictness  = { \ _arity -> mkClosedStrictSig [apply1Dmd,apply1Dmd,topDmd] topRes }
1974    out_of_line = True
1975    has_side_effects = True
1976
1977 primop  CatchSTMOp "catchSTM#" GenPrimOp
1978       (State# RealWorld -> (# State# RealWorld, a #) )
1979    -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1980    -> (State# RealWorld -> (# State# RealWorld, a #) )
1981    with
1982    strictness  = { \ _arity -> mkClosedStrictSig [apply1Dmd,apply2Dmd,topDmd] topRes }
1983    out_of_line = True
1984    has_side_effects = True
1985
1986 primop  Check "check#" GenPrimOp
1987       (State# RealWorld -> (# State# RealWorld, a #) )
1988    -> (State# RealWorld -> (# State# RealWorld, () #) )
1989    with
1990    out_of_line = True
1991    has_side_effects = True
1992
1993 primop  NewTVarOp "newTVar#" GenPrimOp
1994        a
1995     -> State# s -> (# State# s, TVar# s a #)
1996    {Create a new {\tt TVar\#} holding a specified initial value.}
1997    with
1998    out_of_line  = True
1999    has_side_effects = True
2000
2001 primop  ReadTVarOp "readTVar#" GenPrimOp
2002        TVar# s a
2003     -> State# s -> (# State# s, a #)
2004    {Read contents of {\tt TVar\#}.  Result is not yet evaluated.}
2005    with
2006    out_of_line  = True
2007    has_side_effects = True
2008
2009 primop ReadTVarIOOp "readTVarIO#" GenPrimOp
2010        TVar# s a
2011     -> State# s -> (# State# s, a #)
2012    {Read contents of {\tt TVar\#} outside an STM transaction}
2013    with
2014    out_of_line  = True
2015    has_side_effects = True
2016
2017 primop  WriteTVarOp "writeTVar#" GenPrimOp
2018        TVar# s a
2019     -> a
2020     -> State# s -> State# s
2021    {Write contents of {\tt TVar\#}.}
2022    with
2023    out_of_line      = True
2024    has_side_effects = True
2025
2026 primop  SameTVarOp "sameTVar#" GenPrimOp
2027    TVar# s a -> TVar# s a -> Int#
2028
2029
2030 ------------------------------------------------------------------------
2031 section "Synchronized Mutable Variables"
2032         {Operations on {\tt MVar\#}s. }
2033 ------------------------------------------------------------------------
2034
2035 primtype MVar# s a
2036         { A shared mutable variable ({\it not} the same as a {\tt MutVar\#}!).
2037         (Note: in a non-concurrent implementation, {\tt (MVar\# a)} can be
2038         represented by {\tt (MutVar\# (Maybe a))}.) }
2039
2040 primop  NewMVarOp "newMVar#"  GenPrimOp
2041    State# s -> (# State# s, MVar# s a #)
2042    {Create new {\tt MVar\#}; initially empty.}
2043    with
2044    out_of_line = True
2045    has_side_effects = True
2046
2047 primop  TakeMVarOp "takeMVar#" GenPrimOp
2048    MVar# s a -> State# s -> (# State# s, a #)
2049    {If {\tt MVar\#} is empty, block until it becomes full.
2050    Then remove and return its contents, and set it empty.}
2051    with
2052    out_of_line      = True
2053    has_side_effects = True
2054
2055 primop  TryTakeMVarOp "tryTakeMVar#" GenPrimOp
2056    MVar# s a -> State# s -> (# State# s, Int#, a #)
2057    {If {\tt MVar\#} is empty, immediately return with integer 0 and value undefined.
2058    Otherwise, return with integer 1 and contents of {\tt MVar\#}, and set {\tt MVar\#} empty.}
2059    with
2060    out_of_line      = True
2061    has_side_effects = True
2062
2063 primop  PutMVarOp "putMVar#" GenPrimOp
2064    MVar# s a -> a -> State# s -> State# s
2065    {If {\tt MVar\#} is full, block until it becomes empty.
2066    Then store value arg as its new contents.}
2067    with
2068    out_of_line      = True
2069    has_side_effects = True
2070
2071 primop  TryPutMVarOp "tryPutMVar#" GenPrimOp
2072    MVar# s a -> a -> State# s -> (# State# s, Int# #)
2073    {If {\tt MVar\#} is full, immediately return with integer 0.
2074     Otherwise, store value arg as {\tt MVar\#}'s new contents, and return with integer 1.}
2075    with
2076    out_of_line      = True
2077    has_side_effects = True
2078
2079 primop  ReadMVarOp "readMVar#" GenPrimOp
2080    MVar# s a -> State# s -> (# State# s, a #)
2081    {If {\tt MVar\#} is empty, block until it becomes full.
2082    Then read its contents without modifying the MVar, without possibility
2083    of intervention from other threads.}
2084    with
2085    out_of_line      = True
2086    has_side_effects = True
2087
2088 primop  TryReadMVarOp "tryReadMVar#" GenPrimOp
2089    MVar# s a -> State# s -> (# State# s, Int#, a #)
2090    {If {\tt MVar\#} is empty, immediately return with integer 0 and value undefined.
2091    Otherwise, return with integer 1 and contents of {\tt MVar\#}.}
2092    with
2093    out_of_line      = True
2094    has_side_effects = True
2095
2096 primop  SameMVarOp "sameMVar#" GenPrimOp
2097    MVar# s a -> MVar# s a -> Int#
2098
2099 primop  IsEmptyMVarOp "isEmptyMVar#" GenPrimOp
2100    MVar# s a -> State# s -> (# State# s, Int# #)
2101    {Return 1 if {\tt MVar\#} is empty; 0 otherwise.}
2102    with
2103    out_of_line = True
2104    has_side_effects = True
2105
2106 ------------------------------------------------------------------------
2107 section "Delay/wait operations"
2108 ------------------------------------------------------------------------
2109
2110 primop  DelayOp "delay#" GenPrimOp
2111    Int# -> State# s -> State# s
2112    {Sleep specified number of microseconds.}
2113    with
2114    has_side_effects = True
2115    out_of_line      = True
2116
2117 primop  WaitReadOp "waitRead#" GenPrimOp
2118    Int# -> State# s -> State# s
2119    {Block until input is available on specified file descriptor.}
2120    with
2121    has_side_effects = True
2122    out_of_line      = True
2123
2124 primop  WaitWriteOp "waitWrite#" GenPrimOp
2125    Int# -> State# s -> State# s
2126    {Block until output is possible on specified file descriptor.}
2127    with
2128    has_side_effects = True
2129    out_of_line      = True
2130
2131 #ifdef mingw32_TARGET_OS
2132 primop  AsyncReadOp "asyncRead#" GenPrimOp
2133    Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
2134    {Asynchronously read bytes from specified file descriptor.}
2135    with
2136    has_side_effects = True
2137    out_of_line      = True
2138
2139 primop  AsyncWriteOp "asyncWrite#" GenPrimOp
2140    Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
2141    {Asynchronously write bytes from specified file descriptor.}
2142    with
2143    has_side_effects = True
2144    out_of_line      = True
2145
2146 primop  AsyncDoProcOp "asyncDoProc#" GenPrimOp
2147    Addr# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
2148    {Asynchronously perform procedure (first arg), passing it 2nd arg.}
2149    with
2150    has_side_effects = True
2151    out_of_line      = True
2152
2153 #endif
2154
2155 ------------------------------------------------------------------------
2156 section "Concurrency primitives"
2157 ------------------------------------------------------------------------
2158
2159 primtype State# s
2160         { {\tt State\#} is the primitive, unlifted type of states.  It has
2161         one type parameter, thus {\tt State\# RealWorld}, or {\tt State\# s},
2162         where s is a type variable. The only purpose of the type parameter
2163         is to keep different state threads separate.  It is represented by
2164         nothing at all. }
2165
2166 primtype RealWorld
2167         { {\tt RealWorld} is deeply magical.  It is {\it primitive}, but it is not
2168         {\it unlifted} (hence {\tt ptrArg}).  We never manipulate values of type
2169         {\tt RealWorld}; it's only used in the type system, to parameterise {\tt State\#}. }
2170
2171 primtype ThreadId#
2172         {(In a non-concurrent implementation, this can be a singleton
2173         type, whose (unique) value is returned by {\tt myThreadId\#}.  The
2174         other operations can be omitted.)}
2175
2176 primop  ForkOp "fork#" GenPrimOp
2177    a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
2178    with
2179    has_side_effects = True
2180    out_of_line      = True
2181
2182 primop  ForkOnOp "forkOn#" GenPrimOp
2183    Int# -> a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
2184    with
2185    has_side_effects = True
2186    out_of_line      = True
2187
2188 primop  KillThreadOp "killThread#"  GenPrimOp
2189    ThreadId# -> a -> State# RealWorld -> State# RealWorld
2190    with
2191    has_side_effects = True
2192    out_of_line      = True
2193
2194 primop  YieldOp "yield#" GenPrimOp
2195    State# RealWorld -> State# RealWorld
2196    with
2197    has_side_effects = True
2198    out_of_line      = True
2199
2200 primop  MyThreadIdOp "myThreadId#" GenPrimOp
2201    State# RealWorld -> (# State# RealWorld, ThreadId# #)
2202    with
2203    out_of_line = True
2204    has_side_effects = True
2205
2206 primop LabelThreadOp "labelThread#" GenPrimOp
2207    ThreadId# -> Addr# -> State# RealWorld -> State# RealWorld
2208    with
2209    has_side_effects = True
2210    out_of_line      = True
2211
2212 primop  IsCurrentThreadBoundOp "isCurrentThreadBound#" GenPrimOp
2213    State# RealWorld -> (# State# RealWorld, Int# #)
2214    with
2215    out_of_line = True
2216    has_side_effects = True
2217
2218 primop  NoDuplicateOp "noDuplicate#" GenPrimOp
2219    State# RealWorld -> State# RealWorld
2220    with
2221    out_of_line = True
2222    has_side_effects = True
2223
2224 primop  ThreadStatusOp "threadStatus#" GenPrimOp
2225    ThreadId# -> State# RealWorld -> (# State# RealWorld, Int#, Int#, Int# #)
2226    with
2227    out_of_line = True
2228    has_side_effects = True
2229
2230 ------------------------------------------------------------------------
2231 section "Weak pointers"
2232 ------------------------------------------------------------------------
2233
2234 primtype Weak# b
2235
2236 -- note that tyvar "o" denotes openAlphaTyVar
2237
2238 primop  MkWeakOp "mkWeak#" GenPrimOp
2239    o -> b -> c -> State# RealWorld -> (# State# RealWorld, Weak# b #)
2240    with
2241    has_side_effects = True
2242    out_of_line      = True
2243
2244 primop  MkWeakNoFinalizerOp "mkWeakNoFinalizer#" GenPrimOp
2245    o -> b -> State# RealWorld -> (# State# RealWorld, Weak# b #)
2246    with
2247    has_side_effects = True
2248    out_of_line      = True
2249
2250 primop  AddCFinalizerToWeakOp "addCFinalizerToWeak#" GenPrimOp
2251    Addr# -> Addr# -> Int# -> Addr# -> Weak# b
2252           -> State# RealWorld -> (# State# RealWorld, Int# #)
2253    { {\tt addCFinalizerToWeak# fptr ptr flag eptr w} attaches a C
2254      function pointer {\tt fptr} to a weak pointer {\tt w} as a finalizer. If
2255      {\tt flag} is zero, {\tt fptr} will be called with one argument,
2256      {\tt ptr}. Otherwise, it will be called with two arguments,
2257      {\tt eptr} and {\tt ptr}. {\tt addCFinalizerToWeak#} returns
2258      1 on success, or 0 if {\tt w} is already dead. }
2259    with
2260    has_side_effects = True
2261    out_of_line      = True
2262
2263 primop  DeRefWeakOp "deRefWeak#" GenPrimOp
2264    Weak# a -> State# RealWorld -> (# State# RealWorld, Int#, a #)
2265    with
2266    has_side_effects = True
2267    out_of_line      = True
2268
2269 primop  FinalizeWeakOp "finalizeWeak#" GenPrimOp
2270    Weak# a -> State# RealWorld -> (# State# RealWorld, Int#,
2271               (State# RealWorld -> (# State# RealWorld, () #)) #)
2272    with
2273    has_side_effects = True
2274    out_of_line      = True
2275
2276 primop TouchOp "touch#" GenPrimOp
2277    o -> State# RealWorld -> State# RealWorld
2278    with
2279    code_size = { 0 }
2280    has_side_effects = True
2281
2282 ------------------------------------------------------------------------
2283 section "Stable pointers and names"
2284 ------------------------------------------------------------------------
2285
2286 primtype StablePtr# a
2287
2288 primtype StableName# a
2289
2290 primop  MakeStablePtrOp "makeStablePtr#" GenPrimOp
2291    a -> State# RealWorld -> (# State# RealWorld, StablePtr# a #)
2292    with
2293    has_side_effects = True
2294    out_of_line      = True
2295
2296 primop  DeRefStablePtrOp "deRefStablePtr#" GenPrimOp
2297    StablePtr# a -> State# RealWorld -> (# State# RealWorld, a #)
2298    with
2299    has_side_effects = True
2300    out_of_line      = True
2301
2302 primop  EqStablePtrOp "eqStablePtr#" GenPrimOp
2303    StablePtr# a -> StablePtr# a -> Int#
2304    with
2305    has_side_effects = True
2306
2307 primop  MakeStableNameOp "makeStableName#" GenPrimOp
2308    a -> State# RealWorld -> (# State# RealWorld, StableName# a #)
2309    with
2310    has_side_effects = True
2311    out_of_line      = True
2312
2313 primop  EqStableNameOp "eqStableName#" GenPrimOp
2314    StableName# a -> StableName# b -> Int#
2315
2316 primop  StableNameToIntOp "stableNameToInt#" GenPrimOp
2317    StableName# a -> Int#
2318
2319 ------------------------------------------------------------------------
2320 section "Unsafe pointer equality"
2321 --  (#1 Bad Guy: Alistair Reid :)
2322 ------------------------------------------------------------------------
2323
2324 primop  ReallyUnsafePtrEqualityOp "reallyUnsafePtrEquality#" GenPrimOp
2325    a -> a -> Int#
2326
2327 ------------------------------------------------------------------------
2328 section "Parallelism"
2329 ------------------------------------------------------------------------
2330
2331 primop  ParOp "par#" GenPrimOp
2332    a -> Int#
2333    with
2334       -- Note that Par is lazy to avoid that the sparked thing
2335       -- gets evaluted strictly, which it should *not* be
2336    has_side_effects = True
2337    code_size = { primOpCodeSizeForeignCall }
2338
2339 primop SparkOp "spark#" GenPrimOp
2340    a -> State# s -> (# State# s, a #)
2341    with has_side_effects = True
2342    code_size = { primOpCodeSizeForeignCall }
2343
2344 primop SeqOp "seq#" GenPrimOp
2345    a -> State# s -> (# State# s, a #)
2346
2347    -- why return the value?  So that we can control sharing of seq'd
2348    -- values: in
2349    --    let x = e in x `seq` ... x ...
2350    -- we don't want to inline x, so better to represent it as
2351    --    let x = e in case seq# x RW of (# _, x' #) -> ... x' ...
2352    -- also it matches the type of rseq in the Eval monad.
2353
2354 primop GetSparkOp "getSpark#" GenPrimOp
2355    State# s -> (# State# s, Int#, a #)
2356    with
2357    has_side_effects = True
2358    out_of_line = True
2359
2360 primop NumSparks "numSparks#" GenPrimOp
2361    State# s -> (# State# s, Int# #)
2362    { Returns the number of sparks in the local spark pool. }
2363    with
2364    has_side_effects = True
2365    out_of_line = True
2366
2367 -- HWL: The first 4 Int# in all par... annotations denote:
2368 --   name, granularity info, size of result, degree of parallelism
2369 --      Same  structure as _seq_ i.e. returns Int#
2370 -- KSW: v, the second arg in parAt# and parAtForNow#, is used only to determine
2371 --   `the processor containing the expression v'; it is not evaluated
2372
2373 primop  ParGlobalOp  "parGlobal#"  GenPrimOp
2374    a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
2375    with
2376    has_side_effects = True
2377
2378 primop  ParLocalOp  "parLocal#"  GenPrimOp
2379    a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
2380    with
2381    has_side_effects = True
2382
2383 primop  ParAtOp  "parAt#"  GenPrimOp
2384    b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
2385    with
2386    has_side_effects = True
2387
2388 primop  ParAtAbsOp  "parAtAbs#"  GenPrimOp
2389    a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
2390    with
2391    has_side_effects = True
2392
2393 primop  ParAtRelOp  "parAtRel#" GenPrimOp
2394    a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
2395    with
2396    has_side_effects = True
2397
2398 primop  ParAtForNowOp  "parAtForNow#" GenPrimOp
2399    b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
2400    with
2401    has_side_effects = True
2402
2403 -- copyable# and noFollow# are yet to be implemented (for GpH)
2404 --
2405 --primop  CopyableOp  "copyable#" GenPrimOp
2406 --   a -> Int#
2407 --   with
2408 --   has_side_effects = True
2409 --
2410 --primop  NoFollowOp "noFollow#" GenPrimOp
2411 --   a -> Int#
2412 --   with
2413 --   has_side_effects = True
2414
2415
2416 ------------------------------------------------------------------------
2417 section "Tag to enum stuff"
2418         {Convert back and forth between values of enumerated types
2419         and small integers.}
2420 ------------------------------------------------------------------------
2421
2422 primop  DataToTagOp "dataToTag#" GenPrimOp
2423    a -> Int#
2424    with
2425    strictness  = { \ _arity -> mkClosedStrictSig [evalDmd] topRes }
2426
2427         -- dataToTag# must have an evaluated argument
2428
2429 primop  TagToEnumOp "tagToEnum#" GenPrimOp
2430    Int# -> a
2431
2432 ------------------------------------------------------------------------
2433 section "Bytecode operations"
2434         {Support for the bytecode interpreter and linker.}
2435 ------------------------------------------------------------------------
2436
2437 primtype BCO#
2438    {Primitive bytecode type.}
2439
2440 primop   AddrToAnyOp "addrToAny#" GenPrimOp
2441    Addr# -> (# a #)
2442    {Convert an {\tt Addr\#} to a followable Any type.}
2443    with
2444    code_size = 0
2445
2446 primop   MkApUpd0_Op "mkApUpd0#" GenPrimOp
2447    BCO# -> (# a #)
2448    with
2449    out_of_line = True
2450
2451 primop  NewBCOOp "newBCO#" GenPrimOp
2452    ByteArray# -> ByteArray# -> Array# a -> Int# -> ByteArray# -> State# s -> (# State# s, BCO# #)
2453    with
2454    has_side_effects = True
2455    out_of_line      = True
2456
2457 primop  UnpackClosureOp "unpackClosure#" GenPrimOp
2458    a -> (# Addr#, Array# b, ByteArray# #)
2459    with
2460    out_of_line = True
2461
2462 primop  GetApStackValOp "getApStackVal#" GenPrimOp
2463    a -> Int# -> (# Int#, b #)
2464    with
2465    out_of_line = True
2466
2467 ------------------------------------------------------------------------
2468 section "Misc"
2469         {These aren't nearly as wired in as Etc...}
2470 ------------------------------------------------------------------------
2471
2472 primop  GetCCSOfOp "getCCSOf#" GenPrimOp
2473    a -> State# s -> (# State# s, Addr# #)
2474
2475 primop  GetCurrentCCSOp "getCurrentCCS#" GenPrimOp
2476    a -> State# s -> (# State# s, Addr# #)
2477    { Returns the current {\tt CostCentreStack} (value is {\tt NULL} if
2478      not profiling).  Takes a dummy argument which can be used to
2479      avoid the call to {\tt getCCCS\#} being floated out by the
2480      simplifier, which would result in an uninformative stack
2481      ("CAF"). }
2482
2483 ------------------------------------------------------------------------
2484 section "Etc"
2485         {Miscellaneous built-ins}
2486 ------------------------------------------------------------------------
2487
2488 primtype Proxy# a
2489    { The type constructor {\tt Proxy#} is used to bear witness to some
2490    type variable. It's used when you want to pass around proxy values
2491    for doing things like modelling type applications. A {\tt Proxy#}
2492    is not only unboxed, it also has a polymorphic kind, and has no
2493    runtime representation, being totally free. }
2494
2495 pseudoop "proxy#"
2496    Proxy# a
2497    { Witness for an unboxed {\tt Proxy#} value, which has no runtime
2498    representation. }
2499
2500 pseudoop   "seq"
2501    a -> b -> b
2502    { Evaluates its first argument to head normal form, and then returns its second
2503         argument as the result. }
2504
2505 primtype Any
2506         { The type constructor {\tt Any} is type to which you can unsafely coerce any
2507         lifted type, and back.
2508
2509           * It is lifted, and hence represented by a pointer
2510
2511           * It does not claim to be a {\it data} type, and that's important for
2512             the code generator, because the code gen may {\it enter} a data value
2513             but never enters a function value.
2514
2515         It's also used to instantiate un-constrained type variables after type
2516         checking.  For example, {\tt length} has type
2517
2518         {\tt length :: forall a. [a] -> Int}
2519
2520         and the list datacon for the empty list has type
2521
2522         {\tt [] :: forall a. [a]}
2523
2524         In order to compose these two terms as {\tt length []} a type
2525         application is required, but there is no constraint on the
2526         choice.  In this situation GHC uses {\tt Any}:
2527
2528         {\tt length (Any *) ([] (Any *))}
2529
2530         Above, we print kinds explicitly, as if with
2531         {\tt -fprint-explicit-kinds}.
2532
2533         Note that {\tt Any} is kind polymorphic; its kind is thus
2534         {\tt forall k. k}.}
2535
2536 primtype AnyK
2537         { The kind {\tt AnyK} is the kind level counterpart to {\tt Any}. In a
2538         kind polymorphic setting, a similar example to the length of the empty
2539         list can be given at the type level:
2540
2541         {\tt type family Length (l :: [k]) :: Nat}
2542         {\tt type instance Length [] = Zero}
2543
2544         When {\tt Length} is applied to the empty (promoted) list it will have
2545         the kind {\tt Length AnyK []}.
2546
2547         {\tt AnyK} is currently not exported and cannot be used directly, but
2548         you might see it in debug output from the compiler.
2549         }
2550
2551 pseudoop   "unsafeCoerce#"
2552    a -> b
2553    { The function {\tt unsafeCoerce\#} allows you to side-step the typechecker entirely. That
2554         is, it allows you to coerce any type into any other type. If you use this function,
2555         you had better get it right, otherwise segmentation faults await. It is generally
2556         used when you want to write a program that you know is well-typed, but where Haskell's
2557         type system is not expressive enough to prove that it is well typed.
2558
2559         The following uses of {\tt unsafeCoerce\#} are supposed to work (i.e. not lead to
2560         spurious compile-time or run-time crashes):
2561
2562          * Casting any lifted type to {\tt Any}
2563
2564          * Casting {\tt Any} back to the real type
2565
2566          * Casting an unboxed type to another unboxed type of the same size
2567            (but not coercions between floating-point and integral types)
2568
2569          * Casting between two types that have the same runtime representation.  One case is when
2570            the two types differ only in "phantom" type parameters, for example
2571            {\tt Ptr Int} to {\tt Ptr Float}, or {\tt [Int]} to {\tt [Float]} when the list is
2572            known to be empty.  Also, a {\tt newtype} of a type {\tt T} has the same representation
2573            at runtime as {\tt T}.
2574
2575         Other uses of {\tt unsafeCoerce\#} are undefined.  In particular, you should not use
2576         {\tt unsafeCoerce\#} to cast a T to an algebraic data type D, unless T is also
2577         an algebraic data type.  For example, do not cast {\tt Int->Int} to {\tt Bool}, even if
2578         you later cast that {\tt Bool} back to {\tt Int->Int} before applying it.  The reasons
2579         have to do with GHC's internal representation details (for the congnoscenti, data values
2580         can be entered but function closures cannot).  If you want a safe type to cast things
2581         to, use {\tt Any}, which is not an algebraic data type.
2582
2583         }
2584
2585 -- NB. It is tempting to think that casting a value to a type that it doesn't have is safe
2586 -- as long as you don't "do anything" with the value in its cast form, such as seq on it.  This
2587 -- isn't the case: the compiler can insert seqs itself, and if these happen at the wrong type,
2588 -- Bad Things Might Happen.  See bug #1616: in this case we cast a function of type (a,b) -> (a,b)
2589 -- to () -> () and back again.  The strictness analyser saw that the function was strict, but
2590 -- the wrapper had type () -> (), and hence the wrapper de-constructed the (), the worker re-constructed
2591 -- a new (), with the result that the code ended up with "case () of (a,b) -> ...".
2592
2593 primop  TraceEventOp "traceEvent#" GenPrimOp
2594    Addr# -> State# s -> State# s
2595    { Emits an event via the RTS tracing framework.  The contents
2596      of the event is the zero-terminated byte string passed as the first
2597      argument.  The event will be emitted either to the .eventlog file,
2598      or to stderr, depending on the runtime RTS flags. }
2599    with
2600    has_side_effects = True
2601    out_of_line      = True
2602
2603 primop  TraceMarkerOp "traceMarker#" GenPrimOp
2604    Addr# -> State# s -> State# s
2605    { Emits a marker event via the RTS tracing framework.  The contents
2606      of the event is the zero-terminated byte string passed as the first
2607      argument.  The event will be emitted either to the .eventlog file,
2608      or to stderr, depending on the runtime RTS flags. }
2609    with
2610    has_side_effects = True
2611    out_of_line      = True
2612
2613 ------------------------------------------------------------------------
2614 section "Safe coercions"
2615 ------------------------------------------------------------------------
2616
2617 pseudoop   "coerce"
2618    Coercible a b => a -> b
2619    { The function {\tt coerce} allows you to safely convert between values of
2620      types that have the same representation with no run-time overhead. In the
2621      simplest case you can use it instead of a newtype constructor, to go from
2622      the newtype's concrete type to the abstract type. But it also works in
2623      more complicated settings, e.g. converting a list of newtypes to a list of
2624      concrete types.
2625    }
2626
2627 ------------------------------------------------------------------------
2628 section "SIMD Vectors"
2629         {Operations on SIMD vectors.}
2630 ------------------------------------------------------------------------
2631
2632 #define ALL_VECTOR_TYPES \
2633   [<Int8,Int#,16>,<Int16,Int#,8>,<Int32,INT32,4>,<Int64,INT64,2> \
2634   ,<Int8,Int#,32>,<Int16,Int#,16>,<Int32,INT32,8>,<Int64,INT64,4> \
2635   ,<Int8,Int#,64>,<Int16,Int#,32>,<Int32,INT32,16>,<Int64,INT64,8> \
2636   ,<Word8,Word#,16>,<Word16,Word#,8>,<Word32,WORD32,4>,<Word64,WORD64,2> \
2637   ,<Word8,Word#,32>,<Word16,Word#,16>,<Word32,WORD32,8>,<Word64,WORD64,4> \
2638   ,<Word8,Word#,64>,<Word16,Word#,32>,<Word32,WORD32,16>,<Word64,WORD64,8> \
2639   ,<Float,Float#,4>,<Double,Double#,2> \
2640   ,<Float,Float#,8>,<Double,Double#,4> \
2641   ,<Float,Float#,16>,<Double,Double#,8>]
2642
2643 #define SIGNED_VECTOR_TYPES \
2644   [<Int8,Int#,16>,<Int16,Int#,8>,<Int32,INT32,4>,<Int64,INT64,2> \
2645   ,<Int8,Int#,32>,<Int16,Int#,16>,<Int32,INT32,8>,<Int64,INT64,4> \
2646   ,<Int8,Int#,64>,<Int16,Int#,32>,<Int32,INT32,16>,<Int64,INT64,8> \
2647   ,<Float,Float#,4>,<Double,Double#,2> \
2648   ,<Float,Float#,8>,<Double,Double#,4> \
2649   ,<Float,Float#,16>,<Double,Double#,8>]
2650
2651 #define FLOAT_VECTOR_TYPES \
2652   [<Float,Float#,4>,<Double,Double#,2> \
2653   ,<Float,Float#,8>,<Double,Double#,4> \
2654   ,<Float,Float#,16>,<Double,Double#,8>]
2655
2656 #define INT_VECTOR_TYPES \
2657   [<Int8,Int#,16>,<Int16,Int#,8>,<Int32,INT32,4>,<Int64,INT64,2> \
2658   ,<Int8,Int#,32>,<Int16,Int#,16>,<Int32,INT32,8>,<Int64,INT64,4> \
2659   ,<Int8,Int#,64>,<Int16,Int#,32>,<Int32,INT32,16>,<Int64,INT64,8> \
2660   ,<Word8,Word#,16>,<Word16,Word#,8>,<Word32,WORD32,4>,<Word64,WORD64,2> \
2661   ,<Word8,Word#,32>,<Word16,Word#,16>,<Word32,WORD32,8>,<Word64,WORD64,4> \
2662   ,<Word8,Word#,64>,<Word16,Word#,32>,<Word32,WORD32,16>,<Word64,WORD64,8>]
2663
2664 primtype VECTOR
2665    with llvm_only = True
2666         vector = ALL_VECTOR_TYPES
2667
2668 primop VecBroadcastOp "broadcast#" GenPrimOp
2669    SCALAR -> VECTOR
2670    { Broadcast a scalar to all elements of a vector. }
2671    with llvm_only = True
2672         vector = ALL_VECTOR_TYPES
2673
2674 primop VecPackOp "pack#" GenPrimOp
2675    VECTUPLE -> VECTOR
2676    { Pack the elements of an unboxed tuple into a vector. }
2677    with llvm_only = True
2678         vector = ALL_VECTOR_TYPES
2679
2680 primop VecUnpackOp "unpack#" GenPrimOp
2681    VECTOR -> VECTUPLE
2682    { Unpack the elements of a vector into an unboxed tuple. #}
2683    with llvm_only = True
2684         vector = ALL_VECTOR_TYPES
2685
2686 primop VecInsertOp "insert#" GenPrimOp
2687    VECTOR -> SCALAR -> Int# -> VECTOR
2688    { Insert a scalar at the given position in a vector. }
2689    with can_fail = True
2690         llvm_only = True
2691         vector = ALL_VECTOR_TYPES
2692
2693 primop VecAddOp "plus#" Dyadic
2694    VECTOR -> VECTOR -> VECTOR
2695    { Add two vectors element-wise. }
2696    with commutable = True
2697         llvm_only = True
2698         vector = ALL_VECTOR_TYPES
2699
2700 primop VecSubOp "minus#" Dyadic
2701    VECTOR -> VECTOR -> VECTOR
2702    { Subtract two vectors element-wise. }
2703    with llvm_only = True
2704         vector = ALL_VECTOR_TYPES
2705
2706 primop VecMulOp "times#" Dyadic
2707    VECTOR -> VECTOR -> VECTOR
2708    { Multiply two vectors element-wise. }
2709    with commutable = True
2710         llvm_only = True
2711         vector = ALL_VECTOR_TYPES
2712
2713 primop VecDivOp "divide#" Dyadic
2714    VECTOR -> VECTOR -> VECTOR
2715    { Divide two vectors element-wise. }
2716    with can_fail = True
2717         llvm_only = True
2718         vector = FLOAT_VECTOR_TYPES
2719
2720 primop VecQuotOp "quot#" Dyadic
2721    VECTOR -> VECTOR -> VECTOR
2722    { Rounds towards zero element-wise. }
2723    with can_fail = True
2724         llvm_only = True
2725         vector = INT_VECTOR_TYPES
2726
2727 primop VecRemOp "rem#" Dyadic
2728    VECTOR -> VECTOR -> VECTOR
2729    { Satisfies \texttt{(quot\# x y) times\# y plus\# (rem\# x y) == x}. }
2730    with can_fail = True
2731         llvm_only = True
2732         vector = INT_VECTOR_TYPES
2733
2734 primop VecNegOp "negate#" Monadic
2735    VECTOR -> VECTOR
2736    { Negate element-wise. }
2737    with llvm_only = True
2738         vector = SIGNED_VECTOR_TYPES
2739
2740 primop VecIndexByteArrayOp "indexArray#" GenPrimOp
2741    ByteArray# -> Int# -> VECTOR
2742    { Read a vector from specified index of immutable array. }
2743    with can_fail = True
2744         llvm_only = True
2745         vector = ALL_VECTOR_TYPES
2746
2747 primop VecReadByteArrayOp "readArray#" GenPrimOp
2748    MutableByteArray# s -> Int# -> State# s -> (# State# s, VECTOR #)
2749    { Read a vector from specified index of mutable array. }
2750    with has_side_effects = True
2751         can_fail = True
2752         llvm_only = True
2753         vector = ALL_VECTOR_TYPES
2754
2755 primop VecWriteByteArrayOp "writeArray#" GenPrimOp
2756    MutableByteArray# s -> Int# -> VECTOR -> State# s -> State# s
2757    { Write a vector to specified index of mutable array. }
2758    with has_side_effects = True
2759         can_fail = True
2760         llvm_only = True
2761         vector = ALL_VECTOR_TYPES
2762
2763 primop VecIndexOffAddrOp "indexOffAddr#" GenPrimOp
2764    Addr# -> Int# -> VECTOR
2765    { Reads vector; offset in bytes. }
2766    with can_fail = True
2767         llvm_only = True
2768         vector = ALL_VECTOR_TYPES
2769
2770 primop VecReadOffAddrOp "readOffAddr#" GenPrimOp
2771    Addr# -> Int# -> State# s -> (# State# s, VECTOR #)
2772    { Reads vector; offset in bytes. }
2773    with has_side_effects = True
2774         can_fail = True
2775         llvm_only = True
2776         vector = ALL_VECTOR_TYPES
2777
2778 primop VecWriteOffAddrOp "writeOffAddr#" GenPrimOp
2779    Addr# -> Int# -> VECTOR -> State# s -> State# s
2780    { Write vector; offset in bytes. }
2781    with has_side_effects = True
2782         can_fail = True
2783         llvm_only = True
2784         vector = ALL_VECTOR_TYPES
2785
2786
2787 primop VecIndexScalarByteArrayOp "indexArrayAs#" GenPrimOp
2788    ByteArray# -> Int# -> VECTOR
2789    { Read a vector from specified index of immutable array of scalars; offset is in scalar elements. }
2790    with can_fail = True
2791         llvm_only = True
2792         vector = ALL_VECTOR_TYPES
2793
2794 primop VecReadScalarByteArrayOp "readArrayAs#" GenPrimOp
2795    MutableByteArray# s -> Int# -> State# s -> (# State# s, VECTOR #)
2796    { Read a vector from specified index of mutable array of scalars; offset is in scalar elements. }
2797    with has_side_effects = True
2798         can_fail = True
2799         llvm_only = True
2800         vector = ALL_VECTOR_TYPES
2801
2802 primop VecWriteScalarByteArrayOp "writeArrayAs#" GenPrimOp
2803    MutableByteArray# s -> Int# -> VECTOR -> State# s -> State# s
2804    { Write a vector to specified index of mutable array of scalars; offset is in scalar elements. }
2805    with has_side_effects = True
2806         can_fail = True
2807         llvm_only = True
2808         vector = ALL_VECTOR_TYPES
2809
2810 primop VecIndexScalarOffAddrOp "indexOffAddrAs#" GenPrimOp
2811    Addr# -> Int# -> VECTOR
2812    { Reads vector; offset in scalar elements. }
2813    with can_fail = True
2814         llvm_only = True
2815         vector = ALL_VECTOR_TYPES
2816
2817 primop VecReadScalarOffAddrOp "readOffAddrAs#" GenPrimOp
2818    Addr# -> Int# -> State# s -> (# State# s, VECTOR #)
2819    { Reads vector; offset in scalar elements. }
2820    with has_side_effects = True
2821         can_fail = True
2822         llvm_only = True
2823         vector = ALL_VECTOR_TYPES
2824
2825 primop VecWriteScalarOffAddrOp "writeOffAddrAs#" GenPrimOp
2826    Addr# -> Int# -> VECTOR -> State# s -> State# s
2827    { Write vector; offset in scalar elements. }
2828    with has_side_effects = True
2829         can_fail = True
2830         llvm_only = True
2831         vector = ALL_VECTOR_TYPES
2832
2833 ------------------------------------------------------------------------
2834
2835 section "Prefetch"
2836         {Prefetch operations: Note how every prefetch operation has a name
2837   with the pattern prefetch*N#, where N is either 0,1,2, or 3.
2838
2839   This suffix number, N, is the "locality level" of the prefetch, following the
2840   convention in GCC and other compilers.
2841   Higher locality numbers correspond to the memory being loaded in more
2842   levels of the cpu cache, and being retained after initial use. The naming
2843   convention follows the naming convention of the prefetch intrinsic found
2844   in the GCC and Clang C compilers.
2845
2846   On the LLVM backend, prefetch*N# uses the LLVM prefetch intrinsic
2847   with locality level N. The code generated by LLVM is target architecture
2848   dependent, but should agree with the GHC NCG on x86 systems.
2849
2850   On the Sparc and PPC native backends, prefetch*N is a No-Op.
2851
2852   On the x86 NCG, N=0 will generate prefetchNTA,
2853   N=1 generates prefetcht2, N=2 generates prefetcht1, and
2854   N=3 generates prefetcht0.
2855
2856   For streaming workloads, the prefetch*0 operations are recommended.
2857   For workloads which do many reads or writes to a memory location in a short period of time,
2858   prefetch*3 operations are recommended.
2859
2860   For further reading about prefetch and associated systems performance optimization,
2861   the instruction set and optimization manuals by Intel and other CPU vendors are
2862   excellent starting place.
2863
2864
2865   The "Intel 64 and IA-32 Architectures Optimization Reference Manual" is
2866   especially a helpful read, even if your software is meant for other CPU
2867   architectures or vendor hardware. The manual can be found at
2868   http://www.intel.com/content/www/us/en/architecture-and-technology/64-ia-32-architectures-optimization-manual.html .
2869
2870   The {\tt prefetchMutableByteArray} family of operations has the order of operations
2871   determined by passing around the {\tt State#} token.
2872
2873   For the {\tt prefetchByteArray}
2874   and {\tt prefetchAddr} families of operations, consider the following example:
2875
2876   {\tt let a1 = prefetchByteArray2# a n in ...a1... }
2877
2878   In the above fragement, {\tt a} is the input variable for the prefetch
2879   and {\tt a1 == a} will be true. To ensure that the prefetch is not treated as deadcode,
2880   the body of the let should only use {\tt a1} and NOT {\tt a}. The same principle
2881   applies for uses of prefetch in a loop.
2882
2883   }
2884
2885
2886 ------------------------------------------------------------------------
2887
2888
2889 --- the Int# argument for prefetch is the byte offset on the byteArray or  Addr#
2890
2891 ---
2892 primop PrefetchByteArrayOp3 "prefetchByteArray3#" GenPrimOp
2893    ByteArray# -> Int# -> ByteArray#
2894
2895 primop PrefetchMutableByteArrayOp3 "prefetchMutableByteArray3#" GenPrimOp
2896    MutableByteArray# s -> Int# -> State# s -> State# s
2897
2898 primop PrefetchAddrOp3 "prefetchAddr3#" GenPrimOp
2899     Addr# -> Int# -> Addr#
2900
2901 ----
2902
2903 primop PrefetchByteArrayOp2 "prefetchByteArray2#" GenPrimOp
2904    ByteArray# -> Int# -> ByteArray#
2905
2906 primop PrefetchMutableByteArrayOp2 "prefetchMutableByteArray2#" GenPrimOp
2907    MutableByteArray# s -> Int# -> State# s -> State# s
2908
2909 primop PrefetchAddrOp2 "prefetchAddr2#" GenPrimOp
2910    Addr# -> Int# -> Addr#
2911
2912 ----
2913
2914 primop PrefetchByteArrayOp1 "prefetchByteArray1#" GenPrimOp
2915    ByteArray# -> Int# -> ByteArray#
2916
2917 primop PrefetchMutableByteArrayOp1 "prefetchMutableByteArray1#" GenPrimOp
2918    MutableByteArray# s -> Int# -> State# s -> State# s
2919
2920 primop PrefetchAddrOp1 "prefetchAddr1#" GenPrimOp
2921    Addr# -> Int# -> Addr#
2922
2923 ----
2924
2925 primop PrefetchByteArrayOp0 "prefetchByteArray0#" GenPrimOp
2926    ByteArray# -> Int# -> ByteArray#
2927
2928 primop PrefetchMutableByteArrayOp0 "prefetchMutableByteArray0#" GenPrimOp
2929    MutableByteArray# s -> Int# -> State# s -> State# s
2930
2931 primop PrefetchAddrOp0 "prefetchAddr0#" GenPrimOp
2932    Addr# -> Int# -> Addr#
2933
2934
2935
2936 ------------------------------------------------------------------------
2937 ---                                                                  ---
2938 ------------------------------------------------------------------------
2939
2940 thats_all_folks