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