c16646e0f6288c992fcb225e00698f91cef99cee
[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 fi evaluting 'x' causes a divide-by-zero exception,
1950 it won't be caught.  This seems acceptable:
1951   - x might be evaluated somewhere else outside the catch# anyway
1952   - It's an imprecise eception anyway.  Synchronous exceptions (in the
1953     IO monad) will never move in this way.
1954 There was originally a comment
1955   "Catch is actually strict in its first argument
1956    but we don't want to tell the strictness
1957    analyser about that, so that exceptions stay inside it."
1958 but tracing it back through the commit logs did not give any
1959 rationale.  And making catch# lazy has performance costs for everyone.
1960 -}
1961
1962 primop  CatchOp "catch#" GenPrimOp
1963           (State# RealWorld -> (# State# RealWorld, a #) )
1964        -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1965        -> State# RealWorld
1966        -> (# State# RealWorld, a #)
1967    with
1968    strictness  = { \ _arity -> mkClosedStrictSig [strictApply1Dmd,lazyApply2Dmd,topDmd] topRes }
1969                  -- See Note [Strictness for mask/unmask/catch]
1970    out_of_line = True
1971    has_side_effects = True
1972
1973 primop  RaiseOp "raise#" GenPrimOp
1974    b -> o
1975       -- NB: the type variable "o" is "a", but with OpenKind
1976    with
1977    strictness  = { \ _arity -> mkClosedStrictSig [topDmd] botRes }
1978       -- NB: result is bottom
1979    out_of_line = True
1980    has_side_effects = True
1981      -- raise# certainly throws a Haskell exception and hence has_side_effects
1982      -- It doesn't actually make much difference because the fact that it
1983      -- returns bottom independently ensures that we are careful not to discard
1984      -- it.  But still, it's better to say the Right Thing.
1985
1986 -- raiseIO# needs to be a primop, because exceptions in the IO monad
1987 -- must be *precise* - we don't want the strictness analyser turning
1988 -- one kind of bottom into another, as it is allowed to do in pure code.
1989 --
1990 -- But we *do* want to know that it returns bottom after
1991 -- being applied to two arguments, so that this function is strict in y
1992 --     f x y | x>0       = raiseIO blah
1993 --           | y>0       = return 1
1994 --           | otherwise = return 2
1995
1996 primop  RaiseIOOp "raiseIO#" GenPrimOp
1997    a -> State# RealWorld -> (# State# RealWorld, b #)
1998    with
1999    strictness  = { \ _arity -> mkClosedStrictSig [topDmd, topDmd] botRes }
2000    out_of_line = True
2001    has_side_effects = True
2002
2003 primop  MaskAsyncExceptionsOp "maskAsyncExceptions#" GenPrimOp
2004         (State# RealWorld -> (# State# RealWorld, a #))
2005      -> (State# RealWorld -> (# State# RealWorld, a #))
2006    with
2007    strictness  = { \ _arity -> mkClosedStrictSig [strictApply1Dmd,topDmd] topRes }
2008                  -- See Note [Strictness for mask/unmask/catch]
2009    out_of_line = True
2010    has_side_effects = True
2011
2012 primop  MaskUninterruptibleOp "maskUninterruptible#" GenPrimOp
2013         (State# RealWorld -> (# State# RealWorld, a #))
2014      -> (State# RealWorld -> (# State# RealWorld, a #))
2015    with
2016    strictness  = { \ _arity -> mkClosedStrictSig [strictApply1Dmd,topDmd] topRes }
2017    out_of_line = True
2018    has_side_effects = True
2019
2020 primop  UnmaskAsyncExceptionsOp "unmaskAsyncExceptions#" GenPrimOp
2021         (State# RealWorld -> (# State# RealWorld, a #))
2022      -> (State# RealWorld -> (# State# RealWorld, a #))
2023    with
2024    strictness  = { \ _arity -> mkClosedStrictSig [strictApply1Dmd,topDmd] topRes }
2025                  -- See Note [Strictness for mask/unmask/catch]
2026    out_of_line = True
2027    has_side_effects = True
2028
2029 primop  MaskStatus "getMaskingState#" GenPrimOp
2030         State# RealWorld -> (# State# RealWorld, Int# #)
2031    with
2032    out_of_line = True
2033    has_side_effects = True
2034
2035 ------------------------------------------------------------------------
2036 section "STM-accessible Mutable Variables"
2037 ------------------------------------------------------------------------
2038
2039 primtype TVar# s a
2040
2041 primop  AtomicallyOp "atomically#" GenPrimOp
2042       (State# RealWorld -> (# State# RealWorld, a #) )
2043    -> State# RealWorld -> (# State# RealWorld, a #)
2044    with
2045    strictness  = { \ _arity -> mkClosedStrictSig [strictApply1Dmd,topDmd] topRes }
2046                  -- See Note [Strictness for mask/unmask/catch]
2047    out_of_line = True
2048    has_side_effects = True
2049
2050 -- NB: retry#'s strictness information specifies it to return bottom.
2051 -- This lets the compiler perform some extra simplifications, since retry#
2052 -- will technically never return.
2053 --
2054 -- This allows the simplifier to replace things like:
2055 --   case retry# s1
2056 --     (# s2, a #) -> e
2057 -- with:
2058 --   retry# s1
2059 -- where 'e' would be unreachable anyway.  See Trac #8091.
2060 primop  RetryOp "retry#" GenPrimOp
2061    State# RealWorld -> (# State# RealWorld, a #)
2062    with
2063    strictness  = { \ _arity -> mkClosedStrictSig [topDmd] botRes }
2064    out_of_line = True
2065    has_side_effects = True
2066
2067 primop  CatchRetryOp "catchRetry#" GenPrimOp
2068       (State# RealWorld -> (# State# RealWorld, a #) )
2069    -> (State# RealWorld -> (# State# RealWorld, a #) )
2070    -> (State# RealWorld -> (# State# RealWorld, a #) )
2071    with
2072    strictness  = { \ _arity -> mkClosedStrictSig [strictApply1Dmd,lazyApply1Dmd,topDmd] topRes }
2073                  -- See Note [Strictness for mask/unmask/catch]
2074    out_of_line = True
2075    has_side_effects = True
2076
2077 primop  CatchSTMOp "catchSTM#" GenPrimOp
2078       (State# RealWorld -> (# State# RealWorld, a #) )
2079    -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
2080    -> (State# RealWorld -> (# State# RealWorld, a #) )
2081    with
2082    strictness  = { \ _arity -> mkClosedStrictSig [strictApply1Dmd,lazyApply2Dmd,topDmd] topRes }
2083                  -- See Note [Strictness for mask/unmask/catch]
2084    out_of_line = True
2085    has_side_effects = True
2086
2087 primop  Check "check#" GenPrimOp
2088       (State# RealWorld -> (# State# RealWorld, a #) )
2089    -> (State# RealWorld -> State# RealWorld)
2090    with
2091    out_of_line = True
2092    has_side_effects = True
2093
2094 primop  NewTVarOp "newTVar#" GenPrimOp
2095        a
2096     -> State# s -> (# State# s, TVar# s a #)
2097    {Create a new {\tt TVar\#} holding a specified initial value.}
2098    with
2099    out_of_line  = True
2100    has_side_effects = True
2101
2102 primop  ReadTVarOp "readTVar#" GenPrimOp
2103        TVar# s a
2104     -> State# s -> (# State# s, a #)
2105    {Read contents of {\tt TVar\#}.  Result is not yet evaluated.}
2106    with
2107    out_of_line  = True
2108    has_side_effects = True
2109
2110 primop ReadTVarIOOp "readTVarIO#" GenPrimOp
2111        TVar# s a
2112     -> State# s -> (# State# s, a #)
2113    {Read contents of {\tt TVar\#} outside an STM transaction}
2114    with
2115    out_of_line      = True
2116    has_side_effects = True
2117
2118 primop  WriteTVarOp "writeTVar#" GenPrimOp
2119        TVar# s a
2120     -> a
2121     -> State# s -> State# s
2122    {Write contents of {\tt TVar\#}.}
2123    with
2124    out_of_line      = True
2125    has_side_effects = True
2126
2127 primop  SameTVarOp "sameTVar#" GenPrimOp
2128    TVar# s a -> TVar# s a -> Int#
2129
2130
2131 ------------------------------------------------------------------------
2132 section "Synchronized Mutable Variables"
2133         {Operations on {\tt MVar\#}s. }
2134 ------------------------------------------------------------------------
2135
2136 primtype MVar# s a
2137         { A shared mutable variable ({\it not} the same as a {\tt MutVar\#}!).
2138         (Note: in a non-concurrent implementation, {\tt (MVar\# a)} can be
2139         represented by {\tt (MutVar\# (Maybe a))}.) }
2140
2141 primop  NewMVarOp "newMVar#"  GenPrimOp
2142    State# s -> (# State# s, MVar# s a #)
2143    {Create new {\tt MVar\#}; initially empty.}
2144    with
2145    out_of_line = True
2146    has_side_effects = True
2147
2148 primop  TakeMVarOp "takeMVar#" GenPrimOp
2149    MVar# s a -> State# s -> (# State# s, a #)
2150    {If {\tt MVar\#} is empty, block until it becomes full.
2151    Then remove and return its contents, and set it empty.}
2152    with
2153    out_of_line      = True
2154    has_side_effects = True
2155
2156 primop  TryTakeMVarOp "tryTakeMVar#" GenPrimOp
2157    MVar# s a -> State# s -> (# State# s, Int#, a #)
2158    {If {\tt MVar\#} is empty, immediately return with integer 0 and value undefined.
2159    Otherwise, return with integer 1 and contents of {\tt MVar\#}, and set {\tt MVar\#} empty.}
2160    with
2161    out_of_line      = True
2162    has_side_effects = True
2163
2164 primop  PutMVarOp "putMVar#" GenPrimOp
2165    MVar# s a -> a -> State# s -> State# s
2166    {If {\tt MVar\#} is full, block until it becomes empty.
2167    Then store value arg as its new contents.}
2168    with
2169    out_of_line      = True
2170    has_side_effects = True
2171
2172 primop  TryPutMVarOp "tryPutMVar#" GenPrimOp
2173    MVar# s a -> a -> State# s -> (# State# s, Int# #)
2174    {If {\tt MVar\#} is full, immediately return with integer 0.
2175     Otherwise, store value arg as {\tt MVar\#}'s new contents, and return with integer 1.}
2176    with
2177    out_of_line      = True
2178    has_side_effects = True
2179
2180 primop  ReadMVarOp "readMVar#" GenPrimOp
2181    MVar# s a -> State# s -> (# State# s, a #)
2182    {If {\tt MVar\#} is empty, block until it becomes full.
2183    Then read its contents without modifying the MVar, without possibility
2184    of intervention from other threads.}
2185    with
2186    out_of_line      = True
2187    has_side_effects = True
2188
2189 primop  TryReadMVarOp "tryReadMVar#" GenPrimOp
2190    MVar# s a -> State# s -> (# State# s, Int#, a #)
2191    {If {\tt MVar\#} is empty, immediately return with integer 0 and value undefined.
2192    Otherwise, return with integer 1 and contents of {\tt MVar\#}.}
2193    with
2194    out_of_line      = True
2195    has_side_effects = True
2196
2197 primop  SameMVarOp "sameMVar#" GenPrimOp
2198    MVar# s a -> MVar# s a -> Int#
2199
2200 primop  IsEmptyMVarOp "isEmptyMVar#" GenPrimOp
2201    MVar# s a -> State# s -> (# State# s, Int# #)
2202    {Return 1 if {\tt MVar\#} is empty; 0 otherwise.}
2203    with
2204    out_of_line = True
2205    has_side_effects = True
2206
2207 ------------------------------------------------------------------------
2208 section "Delay/wait operations"
2209 ------------------------------------------------------------------------
2210
2211 primop  DelayOp "delay#" GenPrimOp
2212    Int# -> State# s -> State# s
2213    {Sleep specified number of microseconds.}
2214    with
2215    has_side_effects = True
2216    out_of_line      = True
2217
2218 primop  WaitReadOp "waitRead#" GenPrimOp
2219    Int# -> State# s -> State# s
2220    {Block until input is available on specified file descriptor.}
2221    with
2222    has_side_effects = True
2223    out_of_line      = True
2224
2225 primop  WaitWriteOp "waitWrite#" GenPrimOp
2226    Int# -> State# s -> State# s
2227    {Block until output is possible on specified file descriptor.}
2228    with
2229    has_side_effects = True
2230    out_of_line      = True
2231
2232 #ifdef mingw32_TARGET_OS
2233 primop  AsyncReadOp "asyncRead#" GenPrimOp
2234    Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
2235    {Asynchronously read bytes from specified file descriptor.}
2236    with
2237    has_side_effects = True
2238    out_of_line      = True
2239
2240 primop  AsyncWriteOp "asyncWrite#" GenPrimOp
2241    Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
2242    {Asynchronously write bytes from specified file descriptor.}
2243    with
2244    has_side_effects = True
2245    out_of_line      = True
2246
2247 primop  AsyncDoProcOp "asyncDoProc#" GenPrimOp
2248    Addr# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
2249    {Asynchronously perform procedure (first arg), passing it 2nd arg.}
2250    with
2251    has_side_effects = True
2252    out_of_line      = True
2253
2254 #endif
2255
2256 ------------------------------------------------------------------------
2257 section "Concurrency primitives"
2258 ------------------------------------------------------------------------
2259
2260 primtype State# s
2261         { {\tt State\#} is the primitive, unlifted type of states.  It has
2262         one type parameter, thus {\tt State\# RealWorld}, or {\tt State\# s},
2263         where s is a type variable. The only purpose of the type parameter
2264         is to keep different state threads separate.  It is represented by
2265         nothing at all. }
2266
2267 primtype RealWorld
2268         { {\tt RealWorld} is deeply magical.  It is {\it primitive}, but it is not
2269         {\it unlifted} (hence {\tt ptrArg}).  We never manipulate values of type
2270         {\tt RealWorld}; it's only used in the type system, to parameterise {\tt State\#}. }
2271
2272 primtype ThreadId#
2273         {(In a non-concurrent implementation, this can be a singleton
2274         type, whose (unique) value is returned by {\tt myThreadId\#}.  The
2275         other operations can be omitted.)}
2276
2277 primop  ForkOp "fork#" GenPrimOp
2278    a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
2279    with
2280    has_side_effects = True
2281    out_of_line      = True
2282
2283 primop  ForkOnOp "forkOn#" GenPrimOp
2284    Int# -> a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
2285    with
2286    has_side_effects = True
2287    out_of_line      = True
2288
2289 primop  KillThreadOp "killThread#"  GenPrimOp
2290    ThreadId# -> a -> State# RealWorld -> State# RealWorld
2291    with
2292    has_side_effects = True
2293    out_of_line      = True
2294
2295 primop  YieldOp "yield#" GenPrimOp
2296    State# RealWorld -> State# RealWorld
2297    with
2298    has_side_effects = True
2299    out_of_line      = True
2300
2301 primop  MyThreadIdOp "myThreadId#" GenPrimOp
2302    State# RealWorld -> (# State# RealWorld, ThreadId# #)
2303    with
2304    out_of_line = True
2305    has_side_effects = True
2306
2307 primop LabelThreadOp "labelThread#" GenPrimOp
2308    ThreadId# -> Addr# -> State# RealWorld -> State# RealWorld
2309    with
2310    has_side_effects = True
2311    out_of_line      = True
2312
2313 primop  IsCurrentThreadBoundOp "isCurrentThreadBound#" GenPrimOp
2314    State# RealWorld -> (# State# RealWorld, Int# #)
2315    with
2316    out_of_line = True
2317    has_side_effects = True
2318
2319 primop  NoDuplicateOp "noDuplicate#" GenPrimOp
2320    State# RealWorld -> State# RealWorld
2321    with
2322    out_of_line = True
2323    has_side_effects = True
2324
2325 primop  ThreadStatusOp "threadStatus#" GenPrimOp
2326    ThreadId# -> State# RealWorld -> (# State# RealWorld, Int#, Int#, Int# #)
2327    with
2328    out_of_line = True
2329    has_side_effects = True
2330
2331 ------------------------------------------------------------------------
2332 section "Weak pointers"
2333 ------------------------------------------------------------------------
2334
2335 primtype Weak# b
2336
2337 -- note that tyvar "o" denotes openAlphaTyVar
2338
2339 primop  MkWeakOp "mkWeak#" GenPrimOp
2340    o -> b -> (State# RealWorld -> (# State# RealWorld, c #))
2341      -> State# RealWorld -> (# State# RealWorld, Weak# b #)
2342    with
2343    has_side_effects = True
2344    out_of_line      = True
2345
2346 primop  MkWeakNoFinalizerOp "mkWeakNoFinalizer#" GenPrimOp
2347    o -> b -> State# RealWorld -> (# State# RealWorld, Weak# b #)
2348    with
2349    has_side_effects = True
2350    out_of_line      = True
2351
2352 primop  AddCFinalizerToWeakOp "addCFinalizerToWeak#" GenPrimOp
2353    Addr# -> Addr# -> Int# -> Addr# -> Weak# b
2354           -> State# RealWorld -> (# State# RealWorld, Int# #)
2355    { {\tt addCFinalizerToWeak# fptr ptr flag eptr w} attaches a C
2356      function pointer {\tt fptr} to a weak pointer {\tt w} as a finalizer. If
2357      {\tt flag} is zero, {\tt fptr} will be called with one argument,
2358      {\tt ptr}. Otherwise, it will be called with two arguments,
2359      {\tt eptr} and {\tt ptr}. {\tt addCFinalizerToWeak#} returns
2360      1 on success, or 0 if {\tt w} is already dead. }
2361    with
2362    has_side_effects = True
2363    out_of_line      = True
2364
2365 primop  DeRefWeakOp "deRefWeak#" GenPrimOp
2366    Weak# a -> State# RealWorld -> (# State# RealWorld, Int#, a #)
2367    with
2368    has_side_effects = True
2369    out_of_line      = True
2370
2371 primop  FinalizeWeakOp "finalizeWeak#" GenPrimOp
2372    Weak# a -> State# RealWorld -> (# State# RealWorld, Int#,
2373               (State# RealWorld -> (# State# RealWorld, b #) ) #)
2374    { Finalize a weak pointer. The return value is an unboxed tuple
2375      containing the new state of the world and an "unboxed Maybe",
2376      represented by an {\tt Int#} and a (possibly invalid) finalization
2377      action. An {\tt Int#} of {\tt 1} indicates that the finalizer is valid. The
2378      return value {\tt b} from the finalizer should be ignored. }
2379    with
2380    has_side_effects = True
2381    out_of_line      = True
2382
2383 primop TouchOp "touch#" GenPrimOp
2384    o -> State# RealWorld -> State# RealWorld
2385    with
2386    code_size = { 0 }
2387    has_side_effects = True
2388
2389 ------------------------------------------------------------------------
2390 section "Stable pointers and names"
2391 ------------------------------------------------------------------------
2392
2393 primtype StablePtr# a
2394
2395 primtype StableName# a
2396
2397 primop  MakeStablePtrOp "makeStablePtr#" GenPrimOp
2398    a -> State# RealWorld -> (# State# RealWorld, StablePtr# a #)
2399    with
2400    has_side_effects = True
2401    out_of_line      = True
2402
2403 primop  DeRefStablePtrOp "deRefStablePtr#" GenPrimOp
2404    StablePtr# a -> State# RealWorld -> (# State# RealWorld, a #)
2405    with
2406    has_side_effects = True
2407    out_of_line      = True
2408
2409 primop  EqStablePtrOp "eqStablePtr#" GenPrimOp
2410    StablePtr# a -> StablePtr# a -> Int#
2411    with
2412    has_side_effects = True
2413
2414 primop  MakeStableNameOp "makeStableName#" GenPrimOp
2415    a -> State# RealWorld -> (# State# RealWorld, StableName# a #)
2416    with
2417    has_side_effects = True
2418    out_of_line      = True
2419
2420 primop  EqStableNameOp "eqStableName#" GenPrimOp
2421    StableName# a -> StableName# b -> Int#
2422
2423 primop  StableNameToIntOp "stableNameToInt#" GenPrimOp
2424    StableName# a -> Int#
2425
2426 ------------------------------------------------------------------------
2427 section "Unsafe pointer equality"
2428 --  (#1 Bad Guy: Alistair Reid :)
2429 ------------------------------------------------------------------------
2430
2431 primop  ReallyUnsafePtrEqualityOp "reallyUnsafePtrEquality#" GenPrimOp
2432    a -> a -> Int#
2433
2434 ------------------------------------------------------------------------
2435 section "Parallelism"
2436 ------------------------------------------------------------------------
2437
2438 primop  ParOp "par#" GenPrimOp
2439    a -> Int#
2440    with
2441       -- Note that Par is lazy to avoid that the sparked thing
2442       -- gets evaluted strictly, which it should *not* be
2443    has_side_effects = True
2444    code_size = { primOpCodeSizeForeignCall }
2445
2446 primop SparkOp "spark#" GenPrimOp
2447    a -> State# s -> (# State# s, a #)
2448    with has_side_effects = True
2449    code_size = { primOpCodeSizeForeignCall }
2450
2451 primop SeqOp "seq#" GenPrimOp
2452    a -> State# s -> (# State# s, a #)
2453
2454    -- why return the value?  So that we can control sharing of seq'd
2455    -- values: in
2456    --    let x = e in x `seq` ... x ...
2457    -- we don't want to inline x, so better to represent it as
2458    --    let x = e in case seq# x RW of (# _, x' #) -> ... x' ...
2459    -- also it matches the type of rseq in the Eval monad.
2460
2461 primop GetSparkOp "getSpark#" GenPrimOp
2462    State# s -> (# State# s, Int#, a #)
2463    with
2464    has_side_effects = True
2465    out_of_line = True
2466
2467 primop NumSparks "numSparks#" GenPrimOp
2468    State# s -> (# State# s, Int# #)
2469    { Returns the number of sparks in the local spark pool. }
2470    with
2471    has_side_effects = True
2472    out_of_line = True
2473
2474 ------------------------------------------------------------------------
2475 section "Tag to enum stuff"
2476         {Convert back and forth between values of enumerated types
2477         and small integers.}
2478 ------------------------------------------------------------------------
2479
2480 primop  DataToTagOp "dataToTag#" GenPrimOp
2481    a -> Int#
2482    with
2483    strictness  = { \ _arity -> mkClosedStrictSig [evalDmd] topRes }
2484
2485         -- dataToTag# must have an evaluated argument
2486
2487 primop  TagToEnumOp "tagToEnum#" GenPrimOp
2488    Int# -> a
2489
2490 ------------------------------------------------------------------------
2491 section "Bytecode operations"
2492         {Support for manipulating bytecode objects used by the interpreter and
2493         linker.
2494
2495         Bytecode objects are heap objects which represent top-level bindings and
2496         contain a list of instructions and data needed by these instructions.}
2497 ------------------------------------------------------------------------
2498
2499 primtype BCO#
2500    { Primitive bytecode type. }
2501
2502 primop   AddrToAnyOp "addrToAny#" GenPrimOp
2503    Addr# -> (# a #)
2504    { Convert an {\tt Addr\#} to a followable Any type. }
2505    with
2506    code_size = 0
2507
2508 primop   MkApUpd0_Op "mkApUpd0#" GenPrimOp
2509    BCO# -> (# a #)
2510    { Wrap a BCO in a {\tt AP_UPD} thunk which will be updated with the value of
2511      the BCO when evaluated. }
2512    with
2513    out_of_line = True
2514
2515 primop  NewBCOOp "newBCO#" GenPrimOp
2516    ByteArray# -> ByteArray# -> Array# a -> Int# -> ByteArray# -> State# s -> (# State# s, BCO# #)
2517    { {\tt newBCO\# instrs lits ptrs arity bitmap} creates a new bytecode object. The
2518      resulting object encodes a function of the given arity with the instructions
2519      encoded in {\tt instrs}, and a static reference table usage bitmap given by
2520      {\tt bitmap}. }
2521    with
2522    has_side_effects = True
2523    out_of_line      = True
2524
2525 primop  UnpackClosureOp "unpackClosure#" GenPrimOp
2526    a -> (# Addr#, Array# b, ByteArray# #)
2527    with
2528    out_of_line = True
2529
2530 primop  GetApStackValOp "getApStackVal#" GenPrimOp
2531    a -> Int# -> (# Int#, b #)
2532    with
2533    out_of_line = True
2534
2535 ------------------------------------------------------------------------
2536 section "Misc"
2537         {These aren't nearly as wired in as Etc...}
2538 ------------------------------------------------------------------------
2539
2540 primop  GetCCSOfOp "getCCSOf#" GenPrimOp
2541    a -> State# s -> (# State# s, Addr# #)
2542
2543 primop  GetCurrentCCSOp "getCurrentCCS#" GenPrimOp
2544    a -> State# s -> (# State# s, Addr# #)
2545    { Returns the current {\tt CostCentreStack} (value is {\tt NULL} if
2546      not profiling).  Takes a dummy argument which can be used to
2547      avoid the call to {\tt getCCCS\#} being floated out by the
2548      simplifier, which would result in an uninformative stack
2549      ("CAF"). }
2550
2551 ------------------------------------------------------------------------
2552 section "Etc"
2553         {Miscellaneous built-ins}
2554 ------------------------------------------------------------------------
2555
2556 primtype Proxy# a
2557    { The type constructor {\tt Proxy#} is used to bear witness to some
2558    type variable. It's used when you want to pass around proxy values
2559    for doing things like modelling type applications. A {\tt Proxy#}
2560    is not only unboxed, it also has a polymorphic kind, and has no
2561    runtime representation, being totally free. }
2562
2563 pseudoop "proxy#"
2564    Proxy# a
2565    { Witness for an unboxed {\tt Proxy#} value, which has no runtime
2566    representation. }
2567
2568 pseudoop   "seq"
2569    a -> b -> b
2570    { The value of {\tt seq a b} is bottom if {\tt a} is bottom, and
2571      otherwise equal to {\tt b}. {\tt seq} is usually introduced to
2572      improve performance by avoiding unneeded laziness.
2573
2574      A note on evaluation order: the expression {\tt seq a b} does
2575      {\it not} guarantee that {\tt a} will be evaluated before {\tt b}.
2576      The only guarantee given by {\tt seq} is that the both {\tt a}
2577      and {\tt b} will be evaluated before {\tt seq} returns a value.
2578      In particular, this means that {\tt b} may be evaluated before
2579      {\tt a}. If you need to guarantee a specific order of evaluation,
2580      you must use the function {\tt pseq} from the "parallel" package. }
2581
2582 primtype Any
2583         { The type constructor {\tt Any} is type to which you can unsafely coerce any
2584         lifted type, and back.
2585
2586           * It is lifted, and hence represented by a pointer
2587
2588           * It does not claim to be a {\it data} type, and that's important for
2589             the code generator, because the code gen may {\it enter} a data value
2590             but never enters a function value.
2591
2592         It's also used to instantiate un-constrained type variables after type
2593         checking.  For example, {\tt length} has type
2594
2595         {\tt length :: forall a. [a] -> Int}
2596
2597         and the list datacon for the empty list has type
2598
2599         {\tt [] :: forall a. [a]}
2600
2601         In order to compose these two terms as {\tt length []} a type
2602         application is required, but there is no constraint on the
2603         choice.  In this situation GHC uses {\tt Any}:
2604
2605         {\tt length (Any *) ([] (Any *))}
2606
2607         Above, we print kinds explicitly, as if with
2608         {\tt -fprint-explicit-kinds}.
2609
2610         Note that {\tt Any} is kind polymorphic; its kind is thus
2611         {\tt forall k. k}.}
2612
2613 primtype AnyK
2614         { The kind {\tt AnyK} is the kind level counterpart to {\tt Any}. In a
2615         kind polymorphic setting, a similar example to the length of the empty
2616         list can be given at the type level:
2617
2618         {\tt type family Length (l :: [k]) :: Nat}
2619         {\tt type instance Length [] = Zero}
2620
2621         When {\tt Length} is applied to the empty (promoted) list it will have
2622         the kind {\tt Length AnyK []}.
2623
2624         {\tt AnyK} is currently not exported and cannot be used directly, but
2625         you might see it in debug output from the compiler.
2626         }
2627
2628 pseudoop   "unsafeCoerce#"
2629    a -> b
2630    { The function {\tt unsafeCoerce\#} allows you to side-step the typechecker entirely. That
2631         is, it allows you to coerce any type into any other type. If you use this function,
2632         you had better get it right, otherwise segmentation faults await. It is generally
2633         used when you want to write a program that you know is well-typed, but where Haskell's
2634         type system is not expressive enough to prove that it is well typed.
2635
2636         The following uses of {\tt unsafeCoerce\#} are supposed to work (i.e. not lead to
2637         spurious compile-time or run-time crashes):
2638
2639          * Casting any lifted type to {\tt Any}
2640
2641          * Casting {\tt Any} back to the real type
2642
2643          * Casting an unboxed type to another unboxed type of the same size
2644            (but not coercions between floating-point and integral types)
2645
2646          * Casting between two types that have the same runtime representation.  One case is when
2647            the two types differ only in "phantom" type parameters, for example
2648            {\tt Ptr Int} to {\tt Ptr Float}, or {\tt [Int]} to {\tt [Float]} when the list is
2649            known to be empty.  Also, a {\tt newtype} of a type {\tt T} has the same representation
2650            at runtime as {\tt T}.
2651
2652         Other uses of {\tt unsafeCoerce\#} are undefined.  In particular, you should not use
2653         {\tt unsafeCoerce\#} to cast a T to an algebraic data type D, unless T is also
2654         an algebraic data type.  For example, do not cast {\tt Int->Int} to {\tt Bool}, even if
2655         you later cast that {\tt Bool} back to {\tt Int->Int} before applying it.  The reasons
2656         have to do with GHC's internal representation details (for the congnoscenti, data values
2657         can be entered but function closures cannot).  If you want a safe type to cast things
2658         to, use {\tt Any}, which is not an algebraic data type.
2659
2660         }
2661
2662 -- NB. It is tempting to think that casting a value to a type that it doesn't have is safe
2663 -- as long as you don't "do anything" with the value in its cast form, such as seq on it.  This
2664 -- isn't the case: the compiler can insert seqs itself, and if these happen at the wrong type,
2665 -- Bad Things Might Happen.  See bug #1616: in this case we cast a function of type (a,b) -> (a,b)
2666 -- to () -> () and back again.  The strictness analyser saw that the function was strict, but
2667 -- the wrapper had type () -> (), and hence the wrapper de-constructed the (), the worker re-constructed
2668 -- a new (), with the result that the code ended up with "case () of (a,b) -> ...".
2669
2670 primop  TraceEventOp "traceEvent#" GenPrimOp
2671    Addr# -> State# s -> State# s
2672    { Emits an event via the RTS tracing framework.  The contents
2673      of the event is the zero-terminated byte string passed as the first
2674      argument.  The event will be emitted either to the .eventlog file,
2675      or to stderr, depending on the runtime RTS flags. }
2676    with
2677    has_side_effects = True
2678    out_of_line      = True
2679
2680 primop  TraceMarkerOp "traceMarker#" GenPrimOp
2681    Addr# -> State# s -> State# s
2682    { Emits a marker event via the RTS tracing framework.  The contents
2683      of the event is the zero-terminated byte string passed as the first
2684      argument.  The event will be emitted either to the .eventlog file,
2685      or to stderr, depending on the runtime RTS flags. }
2686    with
2687    has_side_effects = True
2688    out_of_line      = True
2689
2690 ------------------------------------------------------------------------
2691 section "Safe coercions"
2692 ------------------------------------------------------------------------
2693
2694 pseudoop   "coerce"
2695    Coercible a b => a -> b
2696    { The function {\tt coerce} allows you to safely convert between values of
2697      types that have the same representation with no run-time overhead. In the
2698      simplest case you can use it instead of a newtype constructor, to go from
2699      the newtype's concrete type to the abstract type. But it also works in
2700      more complicated settings, e.g. converting a list of newtypes to a list of
2701      concrete types.
2702    }
2703
2704 ------------------------------------------------------------------------
2705 section "SIMD Vectors"
2706         {Operations on SIMD vectors.}
2707 ------------------------------------------------------------------------
2708
2709 #define ALL_VECTOR_TYPES \
2710   [<Int8,Int#,16>,<Int16,Int#,8>,<Int32,INT32,4>,<Int64,INT64,2> \
2711   ,<Int8,Int#,32>,<Int16,Int#,16>,<Int32,INT32,8>,<Int64,INT64,4> \
2712   ,<Int8,Int#,64>,<Int16,Int#,32>,<Int32,INT32,16>,<Int64,INT64,8> \
2713   ,<Word8,Word#,16>,<Word16,Word#,8>,<Word32,WORD32,4>,<Word64,WORD64,2> \
2714   ,<Word8,Word#,32>,<Word16,Word#,16>,<Word32,WORD32,8>,<Word64,WORD64,4> \
2715   ,<Word8,Word#,64>,<Word16,Word#,32>,<Word32,WORD32,16>,<Word64,WORD64,8> \
2716   ,<Float,Float#,4>,<Double,Double#,2> \
2717   ,<Float,Float#,8>,<Double,Double#,4> \
2718   ,<Float,Float#,16>,<Double,Double#,8>]
2719
2720 #define SIGNED_VECTOR_TYPES \
2721   [<Int8,Int#,16>,<Int16,Int#,8>,<Int32,INT32,4>,<Int64,INT64,2> \
2722   ,<Int8,Int#,32>,<Int16,Int#,16>,<Int32,INT32,8>,<Int64,INT64,4> \
2723   ,<Int8,Int#,64>,<Int16,Int#,32>,<Int32,INT32,16>,<Int64,INT64,8> \
2724   ,<Float,Float#,4>,<Double,Double#,2> \
2725   ,<Float,Float#,8>,<Double,Double#,4> \
2726   ,<Float,Float#,16>,<Double,Double#,8>]
2727
2728 #define FLOAT_VECTOR_TYPES \
2729   [<Float,Float#,4>,<Double,Double#,2> \
2730   ,<Float,Float#,8>,<Double,Double#,4> \
2731   ,<Float,Float#,16>,<Double,Double#,8>]
2732
2733 #define INT_VECTOR_TYPES \
2734   [<Int8,Int#,16>,<Int16,Int#,8>,<Int32,INT32,4>,<Int64,INT64,2> \
2735   ,<Int8,Int#,32>,<Int16,Int#,16>,<Int32,INT32,8>,<Int64,INT64,4> \
2736   ,<Int8,Int#,64>,<Int16,Int#,32>,<Int32,INT32,16>,<Int64,INT64,8> \
2737   ,<Word8,Word#,16>,<Word16,Word#,8>,<Word32,WORD32,4>,<Word64,WORD64,2> \
2738   ,<Word8,Word#,32>,<Word16,Word#,16>,<Word32,WORD32,8>,<Word64,WORD64,4> \
2739   ,<Word8,Word#,64>,<Word16,Word#,32>,<Word32,WORD32,16>,<Word64,WORD64,8>]
2740
2741 primtype VECTOR
2742    with llvm_only = True
2743         vector = ALL_VECTOR_TYPES
2744
2745 primop VecBroadcastOp "broadcast#" GenPrimOp
2746    SCALAR -> VECTOR
2747    { Broadcast a scalar to all elements of a vector. }
2748    with llvm_only = True
2749         vector = ALL_VECTOR_TYPES
2750
2751 primop VecPackOp "pack#" GenPrimOp
2752    VECTUPLE -> VECTOR
2753    { Pack the elements of an unboxed tuple into a vector. }
2754    with llvm_only = True
2755         vector = ALL_VECTOR_TYPES
2756
2757 primop VecUnpackOp "unpack#" GenPrimOp
2758    VECTOR -> VECTUPLE
2759    { Unpack the elements of a vector into an unboxed tuple. #}
2760    with llvm_only = True
2761         vector = ALL_VECTOR_TYPES
2762
2763 primop VecInsertOp "insert#" GenPrimOp
2764    VECTOR -> SCALAR -> Int# -> VECTOR
2765    { Insert a scalar at the given position in a vector. }
2766    with can_fail = True
2767         llvm_only = True
2768         vector = ALL_VECTOR_TYPES
2769
2770 primop VecAddOp "plus#" Dyadic
2771    VECTOR -> VECTOR -> VECTOR
2772    { Add two vectors element-wise. }
2773    with commutable = True
2774         llvm_only = True
2775         vector = ALL_VECTOR_TYPES
2776
2777 primop VecSubOp "minus#" Dyadic
2778    VECTOR -> VECTOR -> VECTOR
2779    { Subtract two vectors element-wise. }
2780    with llvm_only = True
2781         vector = ALL_VECTOR_TYPES
2782
2783 primop VecMulOp "times#" Dyadic
2784    VECTOR -> VECTOR -> VECTOR
2785    { Multiply two vectors element-wise. }
2786    with commutable = True
2787         llvm_only = True
2788         vector = ALL_VECTOR_TYPES
2789
2790 primop VecDivOp "divide#" Dyadic
2791    VECTOR -> VECTOR -> VECTOR
2792    { Divide two vectors element-wise. }
2793    with can_fail = True
2794         llvm_only = True
2795         vector = FLOAT_VECTOR_TYPES
2796
2797 primop VecQuotOp "quot#" Dyadic
2798    VECTOR -> VECTOR -> VECTOR
2799    { Rounds towards zero element-wise. }
2800    with can_fail = True
2801         llvm_only = True
2802         vector = INT_VECTOR_TYPES
2803
2804 primop VecRemOp "rem#" Dyadic
2805    VECTOR -> VECTOR -> VECTOR
2806    { Satisfies \texttt{(quot\# x y) times\# y plus\# (rem\# x y) == x}. }
2807    with can_fail = True
2808         llvm_only = True
2809         vector = INT_VECTOR_TYPES
2810
2811 primop VecNegOp "negate#" Monadic
2812    VECTOR -> VECTOR
2813    { Negate element-wise. }
2814    with llvm_only = True
2815         vector = SIGNED_VECTOR_TYPES
2816
2817 primop VecIndexByteArrayOp "indexArray#" GenPrimOp
2818    ByteArray# -> Int# -> VECTOR
2819    { Read a vector from specified index of immutable array. }
2820    with can_fail = True
2821         llvm_only = True
2822         vector = ALL_VECTOR_TYPES
2823
2824 primop VecReadByteArrayOp "readArray#" GenPrimOp
2825    MutableByteArray# s -> Int# -> State# s -> (# State# s, VECTOR #)
2826    { Read a vector from specified index of mutable array. }
2827    with has_side_effects = True
2828         can_fail = True
2829         llvm_only = True
2830         vector = ALL_VECTOR_TYPES
2831
2832 primop VecWriteByteArrayOp "writeArray#" GenPrimOp
2833    MutableByteArray# s -> Int# -> VECTOR -> State# s -> State# s
2834    { Write a vector to specified index of mutable array. }
2835    with has_side_effects = True
2836         can_fail = True
2837         llvm_only = True
2838         vector = ALL_VECTOR_TYPES
2839
2840 primop VecIndexOffAddrOp "indexOffAddr#" GenPrimOp
2841    Addr# -> Int# -> VECTOR
2842    { Reads vector; offset in bytes. }
2843    with can_fail = True
2844         llvm_only = True
2845         vector = ALL_VECTOR_TYPES
2846
2847 primop VecReadOffAddrOp "readOffAddr#" GenPrimOp
2848    Addr# -> Int# -> State# s -> (# State# s, VECTOR #)
2849    { Reads vector; offset in bytes. }
2850    with has_side_effects = True
2851         can_fail = True
2852         llvm_only = True
2853         vector = ALL_VECTOR_TYPES
2854
2855 primop VecWriteOffAddrOp "writeOffAddr#" GenPrimOp
2856    Addr# -> Int# -> VECTOR -> State# s -> State# s
2857    { Write vector; offset in bytes. }
2858    with has_side_effects = True
2859         can_fail = True
2860         llvm_only = True
2861         vector = ALL_VECTOR_TYPES
2862
2863
2864 primop VecIndexScalarByteArrayOp "indexArrayAs#" GenPrimOp
2865    ByteArray# -> Int# -> VECTOR
2866    { Read a vector from specified index of immutable array of scalars; offset is in scalar elements. }
2867    with can_fail = True
2868         llvm_only = True
2869         vector = ALL_VECTOR_TYPES
2870
2871 primop VecReadScalarByteArrayOp "readArrayAs#" GenPrimOp
2872    MutableByteArray# s -> Int# -> State# s -> (# State# s, VECTOR #)
2873    { Read a vector from specified index of mutable array of scalars; offset is in scalar elements. }
2874    with has_side_effects = True
2875         can_fail = True
2876         llvm_only = True
2877         vector = ALL_VECTOR_TYPES
2878
2879 primop VecWriteScalarByteArrayOp "writeArrayAs#" GenPrimOp
2880    MutableByteArray# s -> Int# -> VECTOR -> State# s -> State# s
2881    { Write a vector to specified index of mutable array of scalars; offset is in scalar elements. }
2882    with has_side_effects = True
2883         can_fail = True
2884         llvm_only = True
2885         vector = ALL_VECTOR_TYPES
2886
2887 primop VecIndexScalarOffAddrOp "indexOffAddrAs#" GenPrimOp
2888    Addr# -> Int# -> VECTOR
2889    { Reads vector; offset in scalar elements. }
2890    with can_fail = True
2891         llvm_only = True
2892         vector = ALL_VECTOR_TYPES
2893
2894 primop VecReadScalarOffAddrOp "readOffAddrAs#" GenPrimOp
2895    Addr# -> Int# -> State# s -> (# State# s, VECTOR #)
2896    { Reads vector; offset in scalar elements. }
2897    with has_side_effects = True
2898         can_fail = True
2899         llvm_only = True
2900         vector = ALL_VECTOR_TYPES
2901
2902 primop VecWriteScalarOffAddrOp "writeOffAddrAs#" GenPrimOp
2903    Addr# -> Int# -> VECTOR -> State# s -> State# s
2904    { Write vector; offset in scalar elements. }
2905    with has_side_effects = True
2906         can_fail = True
2907         llvm_only = True
2908         vector = ALL_VECTOR_TYPES
2909
2910 ------------------------------------------------------------------------
2911
2912 section "Prefetch"
2913         {Prefetch operations: Note how every prefetch operation has a name
2914   with the pattern prefetch*N#, where N is either 0,1,2, or 3.
2915
2916   This suffix number, N, is the "locality level" of the prefetch, following the
2917   convention in GCC and other compilers.
2918   Higher locality numbers correspond to the memory being loaded in more
2919   levels of the cpu cache, and being retained after initial use. The naming
2920   convention follows the naming convention of the prefetch intrinsic found
2921   in the GCC and Clang C compilers.
2922
2923   On the LLVM backend, prefetch*N# uses the LLVM prefetch intrinsic
2924   with locality level N. The code generated by LLVM is target architecture
2925   dependent, but should agree with the GHC NCG on x86 systems.
2926
2927   On the Sparc and PPC native backends, prefetch*N is a No-Op.
2928
2929   On the x86 NCG, N=0 will generate prefetchNTA,
2930   N=1 generates prefetcht2, N=2 generates prefetcht1, and
2931   N=3 generates prefetcht0.
2932
2933   For streaming workloads, the prefetch*0 operations are recommended.
2934   For workloads which do many reads or writes to a memory location in a short period of time,
2935   prefetch*3 operations are recommended.
2936
2937   For further reading about prefetch and associated systems performance optimization,
2938   the instruction set and optimization manuals by Intel and other CPU vendors are
2939   excellent starting place.
2940
2941
2942   The "Intel 64 and IA-32 Architectures Optimization Reference Manual" is
2943   especially a helpful read, even if your software is meant for other CPU
2944   architectures or vendor hardware. The manual can be found at
2945   http://www.intel.com/content/www/us/en/architecture-and-technology/64-ia-32-architectures-optimization-manual.html .
2946
2947   The {\tt prefetch*} family of operations has the order of operations
2948   determined by passing around the {\tt State#} token.
2949
2950   To get a "pure" version of these operations, use {\tt inlinePerformIO} which is quite safe in this context.
2951
2952   It is important to note that while the prefetch operations will never change the
2953   answer to a pure computation, They CAN change the memory locations resident
2954   in a CPU cache and that may change the performance and timing characteristics
2955   of an application. The prefetch operations are marked has_side_effects=True
2956   to reflect that these operations have side effects with respect to the runtime
2957   performance characteristics of the resulting code. Additionally, if the prefetchValue
2958   operations did not have this attribute, GHC does a float out transformation that
2959   results in a let/app violation, at least with the current design.
2960   }
2961
2962
2963
2964 ------------------------------------------------------------------------
2965
2966
2967 --- the Int# argument for prefetch is the byte offset on the byteArray or  Addr#
2968
2969 ---
2970 primop PrefetchByteArrayOp3 "prefetchByteArray3#" GenPrimOp
2971   ByteArray# -> Int# ->  State# s -> State# s
2972   with has_side_effects =  True
2973
2974 primop PrefetchMutableByteArrayOp3 "prefetchMutableByteArray3#" GenPrimOp
2975   MutableByteArray# s -> Int# -> State# s -> State# s
2976   with has_side_effects =  True
2977
2978 primop PrefetchAddrOp3 "prefetchAddr3#" GenPrimOp
2979   Addr# -> Int# -> State# s -> State# s
2980   with has_side_effects =  True
2981
2982 primop PrefetchValueOp3 "prefetchValue3#" GenPrimOp
2983    a -> State# s -> State# s
2984    with strictness  = { \ _arity -> mkClosedStrictSig [botDmd, topDmd] topRes }
2985         has_side_effects =  True
2986 ----
2987
2988 primop PrefetchByteArrayOp2 "prefetchByteArray2#" GenPrimOp
2989   ByteArray# -> Int# ->  State# s -> State# s
2990   with has_side_effects =  True
2991
2992 primop PrefetchMutableByteArrayOp2 "prefetchMutableByteArray2#" GenPrimOp
2993   MutableByteArray# s -> Int# -> State# s -> State# s
2994   with has_side_effects =  True
2995
2996 primop PrefetchAddrOp2 "prefetchAddr2#" GenPrimOp
2997   Addr# -> Int# ->  State# s -> State# s
2998   with has_side_effects =  True
2999
3000 primop PrefetchValueOp2 "prefetchValue2#" GenPrimOp
3001    a ->  State# s -> State# s
3002    with strictness  = { \ _arity -> mkClosedStrictSig [botDmd, topDmd] topRes }
3003         has_side_effects =  True
3004 ----
3005
3006 primop PrefetchByteArrayOp1 "prefetchByteArray1#" GenPrimOp
3007    ByteArray# -> Int# -> State# s -> State# s
3008    with has_side_effects =  True
3009
3010 primop PrefetchMutableByteArrayOp1 "prefetchMutableByteArray1#" GenPrimOp
3011   MutableByteArray# s -> Int# -> State# s -> State# s
3012   with has_side_effects =  True
3013
3014 primop PrefetchAddrOp1 "prefetchAddr1#" GenPrimOp
3015   Addr# -> Int# -> State# s -> State# s
3016   with has_side_effects =  True
3017
3018 primop PrefetchValueOp1 "prefetchValue1#" GenPrimOp
3019    a -> State# s -> State# s
3020    with strictness  = { \ _arity -> mkClosedStrictSig [botDmd, topDmd] topRes }
3021         has_side_effects =  True
3022 ----
3023
3024 primop PrefetchByteArrayOp0 "prefetchByteArray0#" GenPrimOp
3025   ByteArray# -> Int# ->  State# s -> State# s
3026   with has_side_effects =  True
3027
3028 primop PrefetchMutableByteArrayOp0 "prefetchMutableByteArray0#" GenPrimOp
3029   MutableByteArray# s -> Int# -> State# s -> State# s
3030   with has_side_effects =  True
3031
3032 primop PrefetchAddrOp0 "prefetchAddr0#" GenPrimOp
3033   Addr# -> Int# -> State# s -> State# s
3034   with has_side_effects =  True
3035
3036 primop PrefetchValueOp0 "prefetchValue0#" GenPrimOp
3037    a -> State# s -> State# s
3038    with strictness  = { \ _arity -> mkClosedStrictSig [botDmd, topDmd] topRes }
3039         has_side_effects =  True
3040
3041 ------------------------------------------------------------------------
3042 ---                                                                  ---
3043 ------------------------------------------------------------------------
3044
3045 thats_all_folks