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