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