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