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