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