5b5dd9dc8d40db06e63539d976c876da0d784fec
[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" category type {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   DoubleExpM1Op "expm1Double#"    Monadic
767    Double# -> Double#
768    with
769    code_size = { primOpCodeSizeForeignCall }
770
771 primop   DoubleLogOp   "logDouble#"      Monadic
772    Double# -> Double#
773    with
774    code_size = { primOpCodeSizeForeignCall }
775    can_fail = True
776
777 primop   DoubleLog1POp   "log1pDouble#"      Monadic
778    Double# -> Double#
779    with
780    code_size = { primOpCodeSizeForeignCall }
781    can_fail = True
782
783 primop   DoubleSqrtOp   "sqrtDouble#"      Monadic
784    Double# -> Double#
785    with
786    code_size = { primOpCodeSizeForeignCall }
787
788 primop   DoubleSinOp   "sinDouble#"      Monadic
789    Double# -> Double#
790    with
791    code_size = { primOpCodeSizeForeignCall }
792
793 primop   DoubleCosOp   "cosDouble#"      Monadic
794    Double# -> Double#
795    with
796    code_size = { primOpCodeSizeForeignCall }
797
798 primop   DoubleTanOp   "tanDouble#"      Monadic
799    Double# -> Double#
800    with
801    code_size = { primOpCodeSizeForeignCall }
802
803 primop   DoubleAsinOp   "asinDouble#"      Monadic
804    Double# -> Double#
805    with
806    code_size = { primOpCodeSizeForeignCall }
807    can_fail = True
808
809 primop   DoubleAcosOp   "acosDouble#"      Monadic
810    Double# -> Double#
811    with
812    code_size = { primOpCodeSizeForeignCall }
813    can_fail = True
814
815 primop   DoubleAtanOp   "atanDouble#"      Monadic
816    Double# -> Double#
817    with
818    code_size = { primOpCodeSizeForeignCall }
819
820 primop   DoubleSinhOp   "sinhDouble#"      Monadic
821    Double# -> Double#
822    with
823    code_size = { primOpCodeSizeForeignCall }
824
825 primop   DoubleCoshOp   "coshDouble#"      Monadic
826    Double# -> Double#
827    with
828    code_size = { primOpCodeSizeForeignCall }
829
830 primop   DoubleTanhOp   "tanhDouble#"      Monadic
831    Double# -> Double#
832    with
833    code_size = { primOpCodeSizeForeignCall }
834
835 primop   DoubleAsinhOp   "asinhDouble#"      Monadic
836    Double# -> Double#
837    with
838    code_size = { primOpCodeSizeForeignCall }
839
840 primop   DoubleAcoshOp   "acoshDouble#"      Monadic
841    Double# -> Double#
842    with
843    code_size = { primOpCodeSizeForeignCall }
844
845 primop   DoubleAtanhOp   "atanhDouble#"      Monadic
846    Double# -> Double#
847    with
848    code_size = { primOpCodeSizeForeignCall }
849
850 primop   DoublePowerOp   "**##" Dyadic
851    Double# -> Double# -> Double#
852    {Exponentiation.}
853    with
854    code_size = { primOpCodeSizeForeignCall }
855
856 primop   DoubleDecode_2IntOp   "decodeDouble_2Int#" GenPrimOp
857    Double# -> (# Int#, Word#, Word#, Int# #)
858    {Convert to integer.
859     First component of the result is -1 or 1, indicating the sign of the
860     mantissa. The next two are the high and low 32 bits of the mantissa
861     respectively, and the last is the exponent.}
862    with out_of_line = True
863
864 primop   DoubleDecode_Int64Op   "decodeDouble_Int64#" GenPrimOp
865    Double# -> (# INT64, Int# #)
866    {Decode {\tt Double\#} into mantissa and base-2 exponent.}
867    with out_of_line = True
868
869 ------------------------------------------------------------------------
870 section "Float#"
871         {Operations on single-precision (32-bit) floating-point numbers.}
872 ------------------------------------------------------------------------
873
874 primtype Float#
875
876 primop   FloatGtOp  "gtFloat#"   Compare   Float# -> Float# -> Int#
877 primop   FloatGeOp  "geFloat#"   Compare   Float# -> Float# -> Int#
878
879 primop   FloatEqOp  "eqFloat#"   Compare
880    Float# -> Float# -> Int#
881    with commutable = True
882
883 primop   FloatNeOp  "neFloat#"   Compare
884    Float# -> Float# -> Int#
885    with commutable = True
886
887 primop   FloatLtOp  "ltFloat#"   Compare   Float# -> Float# -> Int#
888 primop   FloatLeOp  "leFloat#"   Compare   Float# -> Float# -> Int#
889
890 primop   FloatAddOp   "plusFloat#"      Dyadic
891    Float# -> Float# -> Float#
892    with commutable = True
893
894 primop   FloatSubOp   "minusFloat#"      Dyadic      Float# -> Float# -> Float#
895
896 primop   FloatMulOp   "timesFloat#"      Dyadic
897    Float# -> Float# -> Float#
898    with commutable = True
899
900 primop   FloatDivOp   "divideFloat#"      Dyadic
901    Float# -> Float# -> Float#
902    with can_fail = True
903
904 primop   FloatNegOp   "negateFloat#"      Monadic    Float# -> Float#
905
906 primop   FloatFabsOp  "fabsFloat#"        Monadic    Float# -> Float#
907
908 primop   Float2IntOp   "float2Int#"      GenPrimOp  Float# -> Int#
909    {Truncates a {\tt Float#} value to the nearest {\tt Int#}.
910     Results are undefined if the truncation if truncation yields
911     a value outside the range of {\tt Int#}.}
912
913 primop   FloatExpOp   "expFloat#"      Monadic
914    Float# -> Float#
915    with
916    code_size = { primOpCodeSizeForeignCall }
917
918 primop   FloatExpM1Op   "expm1Float#"      Monadic
919    Float# -> Float#
920    with
921    code_size = { primOpCodeSizeForeignCall }
922
923 primop   FloatLogOp   "logFloat#"      Monadic
924    Float# -> Float#
925    with
926    code_size = { primOpCodeSizeForeignCall }
927    can_fail = True
928
929 primop   FloatLog1POp  "log1pFloat#"     Monadic
930    Float# -> Float#
931    with
932    code_size = { primOpCodeSizeForeignCall }
933    can_fail = True
934
935 primop   FloatSqrtOp   "sqrtFloat#"      Monadic
936    Float# -> Float#
937    with
938    code_size = { primOpCodeSizeForeignCall }
939
940 primop   FloatSinOp   "sinFloat#"      Monadic
941    Float# -> Float#
942    with
943    code_size = { primOpCodeSizeForeignCall }
944
945 primop   FloatCosOp   "cosFloat#"      Monadic
946    Float# -> Float#
947    with
948    code_size = { primOpCodeSizeForeignCall }
949
950 primop   FloatTanOp   "tanFloat#"      Monadic
951    Float# -> Float#
952    with
953    code_size = { primOpCodeSizeForeignCall }
954
955 primop   FloatAsinOp   "asinFloat#"      Monadic
956    Float# -> Float#
957    with
958    code_size = { primOpCodeSizeForeignCall }
959    can_fail = True
960
961 primop   FloatAcosOp   "acosFloat#"      Monadic
962    Float# -> Float#
963    with
964    code_size = { primOpCodeSizeForeignCall }
965    can_fail = True
966
967 primop   FloatAtanOp   "atanFloat#"      Monadic
968    Float# -> Float#
969    with
970    code_size = { primOpCodeSizeForeignCall }
971
972 primop   FloatSinhOp   "sinhFloat#"      Monadic
973    Float# -> Float#
974    with
975    code_size = { primOpCodeSizeForeignCall }
976
977 primop   FloatCoshOp   "coshFloat#"      Monadic
978    Float# -> Float#
979    with
980    code_size = { primOpCodeSizeForeignCall }
981
982 primop   FloatTanhOp   "tanhFloat#"      Monadic
983    Float# -> Float#
984    with
985    code_size = { primOpCodeSizeForeignCall }
986
987 primop   FloatAsinhOp   "asinhFloat#"      Monadic
988    Float# -> Float#
989    with
990    code_size = { primOpCodeSizeForeignCall }
991
992 primop   FloatAcoshOp   "acoshFloat#"      Monadic
993    Float# -> Float#
994    with
995    code_size = { primOpCodeSizeForeignCall }
996
997 primop   FloatAtanhOp   "atanhFloat#"      Monadic
998    Float# -> Float#
999    with
1000    code_size = { primOpCodeSizeForeignCall }
1001
1002 primop   FloatPowerOp   "powerFloat#"      Dyadic
1003    Float# -> Float# -> Float#
1004    with
1005    code_size = { primOpCodeSizeForeignCall }
1006
1007 primop   Float2DoubleOp   "float2Double#" GenPrimOp  Float# -> Double#
1008
1009 primop   FloatDecode_IntOp   "decodeFloat_Int#" GenPrimOp
1010    Float# -> (# Int#, Int# #)
1011    {Convert to integers.
1012     First {\tt Int\#} in result is the mantissa; second is the exponent.}
1013    with out_of_line = True
1014
1015 ------------------------------------------------------------------------
1016 section "Arrays"
1017         {Operations on {\tt Array\#}.}
1018 ------------------------------------------------------------------------
1019
1020 primtype Array# a
1021
1022 primtype MutableArray# s a
1023
1024 primop  NewArrayOp "newArray#" GenPrimOp
1025    Int# -> a -> State# s -> (# State# s, MutableArray# s a #)
1026    {Create a new mutable array with the specified number of elements,
1027     in the specified state thread,
1028     with each element containing the specified initial value.}
1029    with
1030    out_of_line = True
1031    has_side_effects = True
1032
1033 primop  SameMutableArrayOp "sameMutableArray#" GenPrimOp
1034    MutableArray# s a -> MutableArray# s a -> Int#
1035
1036 primop  ReadArrayOp "readArray#" GenPrimOp
1037    MutableArray# s a -> Int# -> State# s -> (# State# s, a #)
1038    {Read from specified index of mutable array. Result is not yet evaluated.}
1039    with
1040    has_side_effects = True
1041    can_fail         = True
1042
1043 primop  WriteArrayOp "writeArray#" GenPrimOp
1044    MutableArray# s a -> Int# -> a -> State# s -> State# s
1045    {Write to specified index of mutable array.}
1046    with
1047    has_side_effects = True
1048    can_fail         = True
1049    code_size        = 2 -- card update too
1050
1051 primop  SizeofArrayOp "sizeofArray#" GenPrimOp
1052    Array# a -> Int#
1053    {Return the number of elements in the array.}
1054
1055 primop  SizeofMutableArrayOp "sizeofMutableArray#" GenPrimOp
1056    MutableArray# s a -> Int#
1057    {Return the number of elements in the array.}
1058
1059 primop  IndexArrayOp "indexArray#" GenPrimOp
1060    Array# a -> Int# -> (# a #)
1061    {Read from the specified index of an immutable array. The result is packaged
1062     into an unboxed unary tuple; the result itself is not yet
1063     evaluated. Pattern matching on the tuple forces the indexing of the
1064     array to happen but does not evaluate the element itself. Evaluating
1065     the thunk prevents additional thunks from building up on the
1066     heap. Avoiding these thunks, in turn, reduces references to the
1067     argument array, allowing it to be garbage collected more promptly.}
1068    with
1069    can_fail         = True
1070
1071 primop  UnsafeFreezeArrayOp "unsafeFreezeArray#" GenPrimOp
1072    MutableArray# s a -> State# s -> (# State# s, Array# a #)
1073    {Make a mutable array immutable, without copying.}
1074    with
1075    has_side_effects = True
1076
1077 primop  UnsafeThawArrayOp  "unsafeThawArray#" GenPrimOp
1078    Array# a -> State# s -> (# State# s, MutableArray# s a #)
1079    {Make an immutable array mutable, without copying.}
1080    with
1081    out_of_line = True
1082    has_side_effects = True
1083
1084 primop  CopyArrayOp "copyArray#" GenPrimOp
1085   Array# a -> Int# -> MutableArray# s a -> Int# -> Int# -> State# s -> State# s
1086   {Given a source array, an offset into the source array, a
1087    destination array, an offset into the destination array, and a
1088    number of elements to copy, copy the elements from the source array
1089    to the destination array. Both arrays must fully contain the
1090    specified ranges, but this is not checked. The two arrays must not
1091    be the same array in different states, but this is not checked
1092    either.}
1093   with
1094   out_of_line      = True
1095   has_side_effects = True
1096   can_fail         = True
1097
1098 primop  CopyMutableArrayOp "copyMutableArray#" GenPrimOp
1099   MutableArray# s a -> Int# -> MutableArray# s a -> Int# -> Int# -> State# s -> State# s
1100   {Given a source array, an offset into the source array, a
1101    destination array, an offset into the destination array, and a
1102    number of elements to copy, copy the elements from the source array
1103    to the destination array. Both arrays must fully contain the
1104    specified ranges, but this is not checked. In the case where
1105    the source and destination are the same array the source and
1106    destination regions may overlap.}
1107   with
1108   out_of_line      = True
1109   has_side_effects = True
1110   can_fail         = True
1111
1112 primop  CloneArrayOp "cloneArray#" GenPrimOp
1113   Array# a -> Int# -> Int# -> 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  CloneMutableArrayOp "cloneMutableArray#" GenPrimOp
1124   MutableArray# s 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  FreezeArrayOp "freezeArray#" GenPrimOp
1135   MutableArray# s a -> Int# -> Int# -> State# s -> (# State# s, Array# a #)
1136   {Given a source array, an offset into the source array, and a number
1137    of elements to copy, create a new array with the elements from the
1138    source array. The provided array must fully contain the specified
1139    range, but this is not checked.}
1140   with
1141   out_of_line      = True
1142   has_side_effects = True
1143   can_fail         = True
1144
1145 primop  ThawArrayOp "thawArray#" GenPrimOp
1146   Array# a -> Int# -> Int# -> State# s -> (# State# s, MutableArray# s a #)
1147   {Given a source array, an offset into the source array, and a number
1148    of elements to copy, create a new array with the elements from the
1149    source array. The provided array must fully contain the specified
1150    range, but this is not checked.}
1151   with
1152   out_of_line      = True
1153   has_side_effects = True
1154   can_fail         = True
1155
1156 primop CasArrayOp  "casArray#" GenPrimOp
1157    MutableArray# s a -> Int# -> a -> a -> State# s -> (# State# s, Int#, a #)
1158    {Given an array, an offset, the expected old value, and
1159     the new value, perform an atomic compare and swap (i.e. write the new
1160     value if the current value and the old value are the same pointer).
1161     Returns 0 if the swap succeeds and 1 if it fails. Additionally, returns
1162     the element at the offset after the operation completes. This means that
1163     on a success the new value is returned, and on a failure the actual old
1164     value (not the expected one) is returned. Implies a full memory barrier.
1165     The use of a pointer equality on a lifted value makes this function harder
1166     to use correctly than {\tt casIntArray\#}. All of the difficulties
1167     of using {\tt reallyUnsafePtrEquality\#} correctly apply to
1168     {\tt casArray\#} as well.
1169    }
1170    with
1171    out_of_line = True
1172    has_side_effects = True
1173
1174
1175 ------------------------------------------------------------------------
1176 section "Small Arrays"
1177
1178         {Operations on {\tt SmallArray\#}. A {\tt SmallArray\#} works
1179          just like an {\tt Array\#}, but with different space use and
1180          performance characteristics (that are often useful with small
1181          arrays). The {\tt SmallArray\#} and {\tt SmallMutableArray#}
1182          lack a `card table'. The purpose of a card table is to avoid
1183          having to scan every element of the array on each GC by
1184          keeping track of which elements have changed since the last GC
1185          and only scanning those that have changed. So the consequence
1186          of there being no card table is that the representation is
1187          somewhat smaller and the writes are somewhat faster (because
1188          the card table does not need to be updated). The disadvantage
1189          of course is that for a {\tt SmallMutableArray#} the whole
1190          array has to be scanned on each GC. Thus it is best suited for
1191          use cases where the mutable array is not long lived, e.g.
1192          where a mutable array is initialised quickly and then frozen
1193          to become an immutable {\tt SmallArray\#}.
1194         }
1195
1196 ------------------------------------------------------------------------
1197
1198 primtype SmallArray# a
1199
1200 primtype SmallMutableArray# s a
1201
1202 primop  NewSmallArrayOp "newSmallArray#" GenPrimOp
1203    Int# -> a -> State# s -> (# State# s, SmallMutableArray# s a #)
1204    {Create a new mutable array with the specified number of elements,
1205     in the specified state thread,
1206     with each element containing the specified initial value.}
1207    with
1208    out_of_line = True
1209    has_side_effects = True
1210
1211 primop  SameSmallMutableArrayOp "sameSmallMutableArray#" GenPrimOp
1212    SmallMutableArray# s a -> SmallMutableArray# s a -> Int#
1213
1214 primop  ReadSmallArrayOp "readSmallArray#" GenPrimOp
1215    SmallMutableArray# s a -> Int# -> State# s -> (# State# s, a #)
1216    {Read from specified index of mutable array. Result is not yet evaluated.}
1217    with
1218    has_side_effects = True
1219    can_fail         = True
1220
1221 primop  WriteSmallArrayOp "writeSmallArray#" GenPrimOp
1222    SmallMutableArray# s a -> Int# -> a -> State# s -> State# s
1223    {Write to specified index of mutable array.}
1224    with
1225    has_side_effects = True
1226    can_fail         = True
1227
1228 primop  SizeofSmallArrayOp "sizeofSmallArray#" GenPrimOp
1229    SmallArray# a -> Int#
1230    {Return the number of elements in the array.}
1231
1232 primop  SizeofSmallMutableArrayOp "sizeofSmallMutableArray#" GenPrimOp
1233    SmallMutableArray# s a -> Int#
1234    {Return the number of elements in the array.}
1235
1236 primop  IndexSmallArrayOp "indexSmallArray#" GenPrimOp
1237    SmallArray# a -> Int# -> (# a #)
1238    {Read from specified index of immutable array. Result is packaged into
1239     an unboxed singleton; the result itself is not yet evaluated.}
1240    with
1241    can_fail         = True
1242
1243 primop  UnsafeFreezeSmallArrayOp "unsafeFreezeSmallArray#" GenPrimOp
1244    SmallMutableArray# s a -> State# s -> (# State# s, SmallArray# a #)
1245    {Make a mutable array immutable, without copying.}
1246    with
1247    has_side_effects = True
1248
1249 primop  UnsafeThawSmallArrayOp  "unsafeThawSmallArray#" GenPrimOp
1250    SmallArray# a -> State# s -> (# State# s, SmallMutableArray# s a #)
1251    {Make an immutable array mutable, without copying.}
1252    with
1253    out_of_line = True
1254    has_side_effects = True
1255
1256 -- The code_size is only correct for the case when the copy family of
1257 -- primops aren't inlined. It would be nice to keep track of both.
1258
1259 primop  CopySmallArrayOp "copySmallArray#" GenPrimOp
1260   SmallArray# a -> Int# -> SmallMutableArray# s a -> Int# -> Int# -> State# s -> State# s
1261   {Given a source array, an offset into the source array, a
1262    destination array, an offset into the destination array, and a
1263    number of elements to copy, copy the elements from the source array
1264    to the destination array. Both arrays must fully contain the
1265    specified ranges, but this is not checked. The two arrays must not
1266    be the same array in different states, but this is not checked
1267    either.}
1268   with
1269   out_of_line      = True
1270   has_side_effects = True
1271   can_fail         = True
1272
1273 primop  CopySmallMutableArrayOp "copySmallMutableArray#" GenPrimOp
1274   SmallMutableArray# s a -> Int# -> SmallMutableArray# s a -> Int# -> Int# -> State# s -> State# s
1275   {Given a source array, an offset into the source array, a
1276    destination array, an offset into the destination array, and a
1277    number of elements to copy, copy the elements from the source array
1278    to the destination array. The source and destination arrays can
1279    refer to the same array. Both arrays must fully contain the
1280    specified ranges, but this is not checked.
1281    The regions are allowed to overlap, although this is only possible when the same
1282    array is provided as both the source and the destination. }
1283   with
1284   out_of_line      = True
1285   has_side_effects = True
1286   can_fail         = True
1287
1288 primop  CloneSmallArrayOp "cloneSmallArray#" GenPrimOp
1289   SmallArray# a -> Int# -> Int# -> 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  CloneSmallMutableArrayOp "cloneSmallMutableArray#" GenPrimOp
1300   SmallMutableArray# s 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  FreezeSmallArrayOp "freezeSmallArray#" GenPrimOp
1311   SmallMutableArray# s a -> Int# -> Int# -> State# s -> (# State# s, SmallArray# a #)
1312   {Given a source array, an offset into the source array, and a number
1313    of elements to copy, create a new array with the elements from the
1314    source array. The provided array must fully contain the specified
1315    range, but this is not checked.}
1316   with
1317   out_of_line      = True
1318   has_side_effects = True
1319   can_fail         = True
1320
1321 primop  ThawSmallArrayOp "thawSmallArray#" GenPrimOp
1322   SmallArray# a -> Int# -> Int# -> State# s -> (# State# s, SmallMutableArray# s a #)
1323   {Given a source array, an offset into the source array, and a number
1324    of elements to copy, create a new array with the elements from the
1325    source array. The provided array must fully contain the specified
1326    range, but this is not checked.}
1327   with
1328   out_of_line      = True
1329   has_side_effects = True
1330   can_fail         = True
1331
1332 primop CasSmallArrayOp  "casSmallArray#" GenPrimOp
1333    SmallMutableArray# s a -> Int# -> a -> a -> State# s -> (# State# s, Int#, a #)
1334    {Unsafe, machine-level atomic compare and swap on an element within an array.
1335     See the documentation of {\tt casArray\#}.}
1336    with
1337    out_of_line = True
1338    has_side_effects = True
1339
1340 ------------------------------------------------------------------------
1341 section "Byte Arrays"
1342         {Operations on {\tt ByteArray\#}. A {\tt ByteArray\#} is a just a region of
1343          raw memory in the garbage-collected heap, which is not
1344          scanned for pointers. It carries its own size (in bytes).
1345          There are
1346          three sets of operations for accessing byte array contents:
1347          index for reading from immutable byte arrays, and read/write
1348          for mutable byte arrays.  Each set contains operations for a
1349          range of useful primitive data types.  Each operation takes
1350          an offset measured in terms of the size of the primitive type
1351          being read or written.}
1352
1353 ------------------------------------------------------------------------
1354
1355 primtype ByteArray#
1356
1357 primtype MutableByteArray# s
1358
1359 primop  NewByteArrayOp_Char "newByteArray#" GenPrimOp
1360    Int# -> State# s -> (# State# s, MutableByteArray# s #)
1361    {Create a new mutable byte array of specified size (in bytes), in
1362     the specified state thread.}
1363    with out_of_line = True
1364         has_side_effects = True
1365
1366 primop  NewPinnedByteArrayOp_Char "newPinnedByteArray#" GenPrimOp
1367    Int# -> State# s -> (# State# s, MutableByteArray# s #)
1368    {Create a mutable byte array that the GC guarantees not to move.}
1369    with out_of_line = True
1370         has_side_effects = True
1371
1372 primop  NewAlignedPinnedByteArrayOp_Char "newAlignedPinnedByteArray#" GenPrimOp
1373    Int# -> Int# -> State# s -> (# State# s, MutableByteArray# s #)
1374    {Create a mutable byte array, aligned by the specified amount, that the GC guarantees not to move.}
1375    with out_of_line = True
1376         has_side_effects = True
1377
1378 primop  MutableByteArrayIsPinnedOp "isMutableByteArrayPinned#" GenPrimOp
1379    MutableByteArray# s -> Int#
1380    {Determine whether a {\tt MutableByteArray\#} is guaranteed not to move
1381    during GC.}
1382    with out_of_line = True
1383
1384 primop  ByteArrayIsPinnedOp "isByteArrayPinned#" GenPrimOp
1385    ByteArray# -> Int#
1386    {Determine whether a {\tt ByteArray\#} is guaranteed not to move during GC.}
1387    with out_of_line = True
1388
1389 primop  ByteArrayContents_Char "byteArrayContents#" GenPrimOp
1390    ByteArray# -> Addr#
1391    {Intended for use with pinned arrays; otherwise very unsafe!}
1392
1393 primop  SameMutableByteArrayOp "sameMutableByteArray#" GenPrimOp
1394    MutableByteArray# s -> MutableByteArray# s -> Int#
1395
1396 primop  ShrinkMutableByteArrayOp_Char "shrinkMutableByteArray#" GenPrimOp
1397    MutableByteArray# s -> Int# -> State# s -> State# s
1398    {Shrink mutable byte array to new specified size (in bytes), in
1399     the specified state thread. The new size argument must be less than or
1400     equal to the current size as reported by {\tt sizeofMutableArray\#}.}
1401    with out_of_line = True
1402         has_side_effects = True
1403
1404 primop  ResizeMutableByteArrayOp_Char "resizeMutableByteArray#" GenPrimOp
1405    MutableByteArray# s -> Int# -> State# s -> (# State# s,MutableByteArray# s #)
1406    {Resize (unpinned) mutable byte array to new specified size (in bytes).
1407     The returned {\tt MutableByteArray\#} is either the original
1408     {\tt MutableByteArray\#} resized in-place or, if not possible, a newly
1409     allocated (unpinned) {\tt MutableByteArray\#} (with the original content
1410     copied over).
1411
1412     To avoid undefined behaviour, the original {\tt MutableByteArray\#} shall
1413     not be accessed anymore after a {\tt resizeMutableByteArray\#} has been
1414     performed.  Moreover, no reference to the old one should be kept in order
1415     to allow garbage collection of the original {\tt MutableByteArray\#} in
1416     case a new {\tt MutableByteArray\#} had to be allocated.}
1417    with out_of_line = True
1418         has_side_effects = True
1419
1420 primop  UnsafeFreezeByteArrayOp "unsafeFreezeByteArray#" GenPrimOp
1421    MutableByteArray# s -> State# s -> (# State# s, ByteArray# #)
1422    {Make a mutable byte array immutable, without copying.}
1423    with
1424    has_side_effects = True
1425
1426 primop  SizeofByteArrayOp "sizeofByteArray#" GenPrimOp
1427    ByteArray# -> Int#
1428    {Return the size of the array in bytes.}
1429
1430 primop  SizeofMutableByteArrayOp "sizeofMutableByteArray#" GenPrimOp
1431    MutableByteArray# s -> Int#
1432    {Return the size of the array in bytes. Note that this is deprecated as it is
1433    unsafe in the presence of concurrent resize operations on the same byte
1434    array.}
1435    with deprecated_msg = { Use 'getSizeofMutableByteArray#' instead }
1436
1437 primop  GetSizeofMutableByteArrayOp "getSizeofMutableByteArray#" GenPrimOp
1438    MutableByteArray# s -> State# s -> (# State# s, Int# #)
1439    {Return the number of elements in the array.}
1440
1441 primop IndexByteArrayOp_Char "indexCharArray#" GenPrimOp
1442    ByteArray# -> Int# -> Char#
1443    {Read 8-bit character; offset in bytes.}
1444    with can_fail = True
1445
1446 primop IndexByteArrayOp_WideChar "indexWideCharArray#" GenPrimOp
1447    ByteArray# -> Int# -> Char#
1448    {Read 31-bit character; offset in 4-byte words.}
1449    with can_fail = True
1450
1451 primop IndexByteArrayOp_Int "indexIntArray#" GenPrimOp
1452    ByteArray# -> Int# -> Int#
1453    with can_fail = True
1454
1455 primop IndexByteArrayOp_Word "indexWordArray#" GenPrimOp
1456    ByteArray# -> Int# -> Word#
1457    with can_fail = True
1458
1459 primop IndexByteArrayOp_Addr "indexAddrArray#" GenPrimOp
1460    ByteArray# -> Int# -> Addr#
1461    with can_fail = True
1462
1463 primop IndexByteArrayOp_Float "indexFloatArray#" GenPrimOp
1464    ByteArray# -> Int# -> Float#
1465    with can_fail = True
1466
1467 primop IndexByteArrayOp_Double "indexDoubleArray#" GenPrimOp
1468    ByteArray# -> Int# -> Double#
1469    with can_fail = True
1470
1471 primop IndexByteArrayOp_StablePtr "indexStablePtrArray#" GenPrimOp
1472    ByteArray# -> Int# -> StablePtr# a
1473    with can_fail = True
1474
1475 primop IndexByteArrayOp_Int8 "indexInt8Array#" GenPrimOp
1476    ByteArray# -> Int# -> Int#
1477    {Read 8-bit integer; offset in bytes.}
1478    with can_fail = True
1479
1480 primop IndexByteArrayOp_Int16 "indexInt16Array#" GenPrimOp
1481    ByteArray# -> Int# -> Int#
1482    {Read 16-bit integer; offset in 16-bit words.}
1483    with can_fail = True
1484
1485 primop IndexByteArrayOp_Int32 "indexInt32Array#" GenPrimOp
1486    ByteArray# -> Int# -> INT32
1487    {Read 32-bit integer; offset in 32-bit words.}
1488    with can_fail = True
1489
1490 primop IndexByteArrayOp_Int64 "indexInt64Array#" GenPrimOp
1491    ByteArray# -> Int# -> INT64
1492    {Read 64-bit integer; offset in 64-bit words.}
1493    with can_fail = True
1494
1495 primop IndexByteArrayOp_Word8 "indexWord8Array#" GenPrimOp
1496    ByteArray# -> Int# -> Word#
1497    {Read 8-bit word; offset in bytes.}
1498    with can_fail = True
1499
1500 primop IndexByteArrayOp_Word16 "indexWord16Array#" GenPrimOp
1501    ByteArray# -> Int# -> Word#
1502    {Read 16-bit word; offset in 16-bit words.}
1503    with can_fail = True
1504
1505 primop IndexByteArrayOp_Word32 "indexWord32Array#" GenPrimOp
1506    ByteArray# -> Int# -> WORD32
1507    {Read 32-bit word; offset in 32-bit words.}
1508    with can_fail = True
1509
1510 primop IndexByteArrayOp_Word64 "indexWord64Array#" GenPrimOp
1511    ByteArray# -> Int# -> WORD64
1512    {Read 64-bit word; offset in 64-bit words.}
1513    with can_fail = True
1514
1515 primop IndexByteArrayOp_Word8AsChar "indexWord8ArrayAsChar#" GenPrimOp
1516    ByteArray# -> Int# -> Char#
1517    {Read 8-bit character; offset in bytes.}
1518    with can_fail = True
1519
1520 primop IndexByteArrayOp_Word8AsWideChar "indexWord8ArrayAsWideChar#" GenPrimOp
1521    ByteArray# -> Int# -> Char#
1522    {Read 31-bit character; offset in bytes.}
1523    with can_fail = True
1524
1525 primop IndexByteArrayOp_Word8AsAddr "indexWord8ArrayAsAddr#" GenPrimOp
1526    ByteArray# -> Int# -> Addr#
1527    {Read address; offset in bytes.}
1528    with can_fail = True
1529
1530 primop IndexByteArrayOp_Word8AsFloat "indexWord8ArrayAsFloat#" GenPrimOp
1531    ByteArray# -> Int# -> Float#
1532    {Read float; offset in bytes.}
1533    with can_fail = True
1534
1535 primop IndexByteArrayOp_Word8AsDouble "indexWord8ArrayAsDouble#" GenPrimOp
1536    ByteArray# -> Int# -> Double#
1537    {Read double; offset in bytes.}
1538    with can_fail = True
1539
1540 primop IndexByteArrayOp_Word8AsStablePtr "indexWord8ArrayAsStablePtr#" GenPrimOp
1541    ByteArray# -> Int# -> StablePtr# a
1542    {Read stable pointer; offset in bytes.}
1543    with can_fail = True
1544
1545 primop IndexByteArrayOp_Word8AsInt16 "indexWord8ArrayAsInt16#" GenPrimOp
1546    ByteArray# -> Int# -> Int#
1547    {Read 16-bit int; offset in bytes.}
1548    with can_fail = True
1549
1550 primop IndexByteArrayOp_Word8AsInt32 "indexWord8ArrayAsInt32#" GenPrimOp
1551    ByteArray# -> Int# -> INT32
1552    {Read 32-bit int; offset in bytes.}
1553    with can_fail = True
1554
1555 primop IndexByteArrayOp_Word8AsInt64 "indexWord8ArrayAsInt64#" GenPrimOp
1556    ByteArray# -> Int# -> INT64
1557    {Read 64-bit int; offset in bytes.}
1558    with can_fail = True
1559
1560 primop IndexByteArrayOp_Word8AsInt "indexWord8ArrayAsInt#" GenPrimOp
1561    ByteArray# -> Int# -> Int#
1562    {Read int; offset in bytes.}
1563    with can_fail = True
1564
1565 primop IndexByteArrayOp_Word8AsWord16 "indexWord8ArrayAsWord16#" GenPrimOp
1566    ByteArray# -> Int# -> Word#
1567    {Read 16-bit word; offset in bytes.}
1568    with can_fail = True
1569
1570 primop IndexByteArrayOp_Word8AsWord32 "indexWord8ArrayAsWord32#" GenPrimOp
1571    ByteArray# -> Int# -> WORD32
1572    {Read 32-bit word; offset in bytes.}
1573    with can_fail = True
1574
1575 primop IndexByteArrayOp_Word8AsWord64 "indexWord8ArrayAsWord64#" GenPrimOp
1576    ByteArray# -> Int# -> WORD64
1577    {Read 64-bit word; offset in bytes.}
1578    with can_fail = True
1579
1580 primop IndexByteArrayOp_Word8AsWord "indexWord8ArrayAsWord#" GenPrimOp
1581    ByteArray# -> Int# -> Word#
1582    {Read word; offset in bytes.}
1583    with can_fail = True
1584
1585 primop  ReadByteArrayOp_Char "readCharArray#" GenPrimOp
1586    MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
1587    {Read 8-bit character; offset in bytes.}
1588    with has_side_effects = True
1589         can_fail = True
1590
1591 primop  ReadByteArrayOp_WideChar "readWideCharArray#" GenPrimOp
1592    MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
1593    {Read 31-bit character; offset in 4-byte words.}
1594    with has_side_effects = True
1595         can_fail = True
1596
1597 primop  ReadByteArrayOp_Int "readIntArray#" GenPrimOp
1598    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
1599    {Read integer; offset in machine words.}
1600    with has_side_effects = True
1601         can_fail = True
1602
1603 primop  ReadByteArrayOp_Word "readWordArray#" GenPrimOp
1604    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
1605    {Read word; offset in machine words.}
1606    with has_side_effects = True
1607         can_fail = True
1608
1609 primop  ReadByteArrayOp_Addr "readAddrArray#" GenPrimOp
1610    MutableByteArray# s -> Int# -> State# s -> (# State# s, Addr# #)
1611    with has_side_effects = True
1612         can_fail = True
1613
1614 primop  ReadByteArrayOp_Float "readFloatArray#" GenPrimOp
1615    MutableByteArray# s -> Int# -> State# s -> (# State# s, Float# #)
1616    with has_side_effects = True
1617         can_fail = True
1618
1619 primop  ReadByteArrayOp_Double "readDoubleArray#" GenPrimOp
1620    MutableByteArray# s -> Int# -> State# s -> (# State# s, Double# #)
1621    with has_side_effects = True
1622         can_fail = True
1623
1624 primop  ReadByteArrayOp_StablePtr "readStablePtrArray#" GenPrimOp
1625    MutableByteArray# s -> Int# -> State# s -> (# State# s, StablePtr# a #)
1626    with has_side_effects = True
1627         can_fail = True
1628
1629 primop  ReadByteArrayOp_Int8 "readInt8Array#" GenPrimOp
1630    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
1631    with has_side_effects = True
1632         can_fail = True
1633
1634 primop  ReadByteArrayOp_Int16 "readInt16Array#" GenPrimOp
1635    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
1636    with has_side_effects = True
1637         can_fail = True
1638
1639 primop  ReadByteArrayOp_Int32 "readInt32Array#" GenPrimOp
1640    MutableByteArray# s -> Int# -> State# s -> (# State# s, INT32 #)
1641    with has_side_effects = True
1642         can_fail = True
1643
1644 primop  ReadByteArrayOp_Int64 "readInt64Array#" GenPrimOp
1645    MutableByteArray# s -> Int# -> State# s -> (# State# s, INT64 #)
1646    with has_side_effects = True
1647         can_fail = True
1648
1649 primop  ReadByteArrayOp_Word8 "readWord8Array#" GenPrimOp
1650    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
1651    with has_side_effects = True
1652         can_fail = True
1653
1654 primop  ReadByteArrayOp_Word16 "readWord16Array#" GenPrimOp
1655    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
1656    with has_side_effects = True
1657         can_fail = True
1658
1659 primop  ReadByteArrayOp_Word32 "readWord32Array#" GenPrimOp
1660    MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD32 #)
1661    with has_side_effects = True
1662         can_fail = True
1663
1664 primop  ReadByteArrayOp_Word64 "readWord64Array#" GenPrimOp
1665    MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD64 #)
1666    with has_side_effects = True
1667         can_fail = True
1668
1669 primop  ReadByteArrayOp_Word8AsChar "readWord8ArrayAsChar#" GenPrimOp
1670    MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
1671    with has_side_effects = True
1672         can_fail = True
1673
1674 primop  ReadByteArrayOp_Word8AsWideChar "readWord8ArrayAsWideChar#" GenPrimOp
1675    MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
1676    with has_side_effects = True
1677         can_fail = True
1678
1679 primop  ReadByteArrayOp_Word8AsAddr "readWord8ArrayAsAddr#" GenPrimOp
1680    MutableByteArray# s -> Int# -> State# s -> (# State# s, Addr# #)
1681    with has_side_effects = True
1682         can_fail = True
1683
1684 primop  ReadByteArrayOp_Word8AsFloat "readWord8ArrayAsFloat#" GenPrimOp
1685    MutableByteArray# s -> Int# -> State# s -> (# State# s, Float# #)
1686    with has_side_effects = True
1687         can_fail = True
1688
1689 primop  ReadByteArrayOp_Word8AsDouble "readWord8ArrayAsDouble#" GenPrimOp
1690    MutableByteArray# s -> Int# -> State# s -> (# State# s, Double# #)
1691    with has_side_effects = True
1692         can_fail = True
1693
1694 primop  ReadByteArrayOp_Word8AsStablePtr "readWord8ArrayAsStablePtr#" GenPrimOp
1695    MutableByteArray# s -> Int# -> State# s -> (# State# s, StablePtr# a #)
1696    with has_side_effects = True
1697         can_fail = True
1698
1699 primop  ReadByteArrayOp_Word8AsInt16 "readWord8ArrayAsInt16#" GenPrimOp
1700    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
1701    with has_side_effects = True
1702         can_fail = True
1703
1704 primop  ReadByteArrayOp_Word8AsInt32 "readWord8ArrayAsInt32#" GenPrimOp
1705    MutableByteArray# s -> Int# -> State# s -> (# State# s, INT32 #)
1706    with has_side_effects = True
1707         can_fail = True
1708
1709 primop  ReadByteArrayOp_Word8AsInt64 "readWord8ArrayAsInt64#" GenPrimOp
1710    MutableByteArray# s -> Int# -> State# s -> (# State# s, INT64 #)
1711    with has_side_effects = True
1712         can_fail = True
1713
1714 primop  ReadByteArrayOp_Word8AsInt "readWord8ArrayAsInt#" GenPrimOp
1715    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
1716    with has_side_effects = True
1717         can_fail = True
1718
1719 primop  ReadByteArrayOp_Word8AsWord16 "readWord8ArrayAsWord16#" GenPrimOp
1720    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
1721    with has_side_effects = True
1722         can_fail = True
1723
1724 primop  ReadByteArrayOp_Word8AsWord32 "readWord8ArrayAsWord32#" GenPrimOp
1725    MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD32 #)
1726    with has_side_effects = True
1727         can_fail = True
1728
1729 primop  ReadByteArrayOp_Word8AsWord64 "readWord8ArrayAsWord64#" GenPrimOp
1730    MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD64 #)
1731    with has_side_effects = True
1732         can_fail = True
1733
1734 primop  ReadByteArrayOp_Word8AsWord "readWord8ArrayAsWord#" GenPrimOp
1735    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
1736    with has_side_effects = True
1737         can_fail = True
1738
1739 primop  WriteByteArrayOp_Char "writeCharArray#" GenPrimOp
1740    MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
1741    {Write 8-bit character; offset in bytes.}
1742    with has_side_effects = True
1743         can_fail = True
1744
1745 primop  WriteByteArrayOp_WideChar "writeWideCharArray#" GenPrimOp
1746    MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
1747    {Write 31-bit character; offset in 4-byte words.}
1748    with has_side_effects = True
1749         can_fail = True
1750
1751 primop  WriteByteArrayOp_Int "writeIntArray#" GenPrimOp
1752    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1753    with has_side_effects = True
1754         can_fail = True
1755
1756 primop  WriteByteArrayOp_Word "writeWordArray#" GenPrimOp
1757    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
1758    with has_side_effects = True
1759         can_fail = True
1760
1761 primop  WriteByteArrayOp_Addr "writeAddrArray#" GenPrimOp
1762    MutableByteArray# s -> Int# -> Addr# -> State# s -> State# s
1763    with has_side_effects = True
1764         can_fail = True
1765
1766 primop  WriteByteArrayOp_Float "writeFloatArray#" GenPrimOp
1767    MutableByteArray# s -> Int# -> Float# -> State# s -> State# s
1768    with has_side_effects = True
1769         can_fail = True
1770
1771 primop  WriteByteArrayOp_Double "writeDoubleArray#" GenPrimOp
1772    MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
1773    with has_side_effects = True
1774         can_fail = True
1775
1776 primop  WriteByteArrayOp_StablePtr "writeStablePtrArray#" GenPrimOp
1777    MutableByteArray# s -> Int# -> StablePtr# a -> State# s -> State# s
1778    with has_side_effects = True
1779         can_fail = True
1780
1781 primop  WriteByteArrayOp_Int8 "writeInt8Array#" GenPrimOp
1782    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1783    with has_side_effects = True
1784         can_fail = True
1785
1786 primop  WriteByteArrayOp_Int16 "writeInt16Array#" GenPrimOp
1787    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1788    with has_side_effects = True
1789         can_fail = True
1790
1791 primop  WriteByteArrayOp_Int32 "writeInt32Array#" GenPrimOp
1792    MutableByteArray# s -> Int# -> INT32 -> State# s -> State# s
1793    with has_side_effects = True
1794         can_fail = True
1795
1796 primop  WriteByteArrayOp_Int64 "writeInt64Array#" GenPrimOp
1797    MutableByteArray# s -> Int# -> INT64 -> State# s -> State# s
1798    with can_fail = True
1799         has_side_effects = True
1800
1801 primop  WriteByteArrayOp_Word8 "writeWord8Array#" GenPrimOp
1802    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
1803    with has_side_effects = True
1804         can_fail = True
1805
1806 primop  WriteByteArrayOp_Word16 "writeWord16Array#" GenPrimOp
1807    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
1808    with has_side_effects = True
1809         can_fail = True
1810
1811 primop  WriteByteArrayOp_Word32 "writeWord32Array#" GenPrimOp
1812    MutableByteArray# s -> Int# -> WORD32 -> State# s -> State# s
1813    with has_side_effects = True
1814         can_fail = True
1815
1816 primop  WriteByteArrayOp_Word64 "writeWord64Array#" GenPrimOp
1817    MutableByteArray# s -> Int# -> WORD64 -> State# s -> State# s
1818    with has_side_effects = True
1819         can_fail = True
1820
1821 primop  WriteByteArrayOp_Word8AsChar "writeWord8ArrayAsChar#" GenPrimOp
1822    MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
1823    with has_side_effects = True
1824         can_fail = True
1825
1826 primop  WriteByteArrayOp_Word8AsWideChar "writeWord8ArrayAsWideChar#" GenPrimOp
1827    MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
1828    with has_side_effects = True
1829         can_fail = True
1830
1831 primop  WriteByteArrayOp_Word8AsAddr "writeWord8ArrayAsAddr#" GenPrimOp
1832    MutableByteArray# s -> Int# -> Addr# -> State# s -> State# s
1833    with has_side_effects = True
1834         can_fail = True
1835
1836 primop  WriteByteArrayOp_Word8AsFloat "writeWord8ArrayAsFloat#" GenPrimOp
1837    MutableByteArray# s -> Int# -> Float# -> State# s -> State# s
1838    with has_side_effects = True
1839         can_fail = True
1840
1841 primop  WriteByteArrayOp_Word8AsDouble "writeWord8ArrayAsDouble#" GenPrimOp
1842    MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
1843    with has_side_effects = True
1844         can_fail = True
1845
1846 primop  WriteByteArrayOp_Word8AsStablePtr "writeWord8ArrayAsStablePtr#" GenPrimOp
1847    MutableByteArray# s -> Int# -> StablePtr# a -> State# s -> State# s
1848    with has_side_effects = True
1849         can_fail = True
1850
1851 primop  WriteByteArrayOp_Word8AsInt16 "writeWord8ArrayAsInt16#" GenPrimOp
1852    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1853    with has_side_effects = True
1854         can_fail = True
1855
1856 primop  WriteByteArrayOp_Word8AsInt32 "writeWord8ArrayAsInt32#" GenPrimOp
1857    MutableByteArray# s -> Int# -> INT32 -> State# s -> State# s
1858    with has_side_effects = True
1859         can_fail = True
1860
1861 primop  WriteByteArrayOp_Word8AsInt64 "writeWord8ArrayAsInt64#" GenPrimOp
1862    MutableByteArray# s -> Int# -> INT64 -> State# s -> State# s
1863    with has_side_effects = True
1864         can_fail = True
1865
1866 primop  WriteByteArrayOp_Word8AsInt "writeWord8ArrayAsInt#" GenPrimOp
1867    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1868    with has_side_effects = True
1869         can_fail = True
1870
1871 primop  WriteByteArrayOp_Word8AsWord16 "writeWord8ArrayAsWord16#" GenPrimOp
1872    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
1873    with has_side_effects = True
1874         can_fail = True
1875
1876 primop  WriteByteArrayOp_Word8AsWord32 "writeWord8ArrayAsWord32#" GenPrimOp
1877    MutableByteArray# s -> Int# -> WORD32 -> State# s -> State# s
1878    with has_side_effects = True
1879         can_fail = True
1880
1881 primop  WriteByteArrayOp_Word8AsWord64 "writeWord8ArrayAsWord64#" GenPrimOp
1882    MutableByteArray# s -> Int# -> WORD64 -> State# s -> State# s
1883    with has_side_effects = True
1884         can_fail = True
1885
1886 primop  WriteByteArrayOp_Word8AsWord "writeWord8ArrayAsWord#" GenPrimOp
1887    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
1888    with has_side_effects = True
1889         can_fail = True
1890
1891 primop  CompareByteArraysOp "compareByteArrays#" GenPrimOp
1892    ByteArray# -> Int# -> ByteArray# -> Int# -> Int# -> Int#
1893    {{\tt compareByteArrays# src1 src1_ofs src2 src2_ofs n} compares
1894     {\tt n} bytes starting at offset {\tt src1_ofs} in the first
1895     {\tt ByteArray#} {\tt src1} to the range of {\tt n} bytes
1896     (i.e. same length) starting at offset {\tt src2_ofs} of the second
1897     {\tt ByteArray#} {\tt src2}.  Both arrays must fully contain the
1898     specified ranges, but this is not checked.  Returns an {\tt Int#}
1899     less than, equal to, or greater than zero if the range is found,
1900     respectively, to be byte-wise lexicographically less than, to
1901     match, or be greater than the second range.}
1902    with
1903    can_fail = True
1904
1905 primop  CopyByteArrayOp "copyByteArray#" GenPrimOp
1906   ByteArray# -> Int# -> MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1907   {{\tt copyByteArray# src src_ofs dst dst_ofs n} copies the range
1908    starting at offset {\tt src_ofs} of length {\tt n} from the
1909    {\tt ByteArray#} {\tt src} to the {\tt MutableByteArray#} {\tt dst}
1910    starting at offset {\tt dst_ofs}.  Both arrays must fully contain
1911    the specified ranges, but this is not checked.  The two arrays must
1912    not be the same array in different states, but this is not checked
1913    either.}
1914   with
1915   has_side_effects = True
1916   code_size = { primOpCodeSizeForeignCall + 4}
1917   can_fail = True
1918
1919 primop  CopyMutableByteArrayOp "copyMutableByteArray#" GenPrimOp
1920   MutableByteArray# s -> Int# -> MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1921   {Copy a range of the first MutableByteArray\# to the specified region in the second MutableByteArray\#.
1922    Both arrays must fully contain the specified ranges, but this is not checked. The regions are
1923    allowed to overlap, although this is only possible when the same array is provided
1924    as both the source and the destination.}
1925   with
1926   has_side_effects = True
1927   code_size = { primOpCodeSizeForeignCall + 4 }
1928   can_fail = True
1929
1930 primop  CopyByteArrayToAddrOp "copyByteArrayToAddr#" GenPrimOp
1931   ByteArray# -> Int# -> Addr# -> Int# -> State# s -> State# s
1932   {Copy a range of the ByteArray\# to the memory range starting at the Addr\#.
1933    The ByteArray\# and the memory region at Addr\# must fully contain the
1934    specified ranges, but this is not checked. The Addr\# must not point into the
1935    ByteArray\# (e.g. if the ByteArray\# were pinned), but this is not checked
1936    either.}
1937   with
1938   has_side_effects = True
1939   code_size = { primOpCodeSizeForeignCall + 4}
1940   can_fail = True
1941
1942 primop  CopyMutableByteArrayToAddrOp "copyMutableByteArrayToAddr#" GenPrimOp
1943   MutableByteArray# s -> Int# -> Addr# -> Int# -> State# s -> State# s
1944   {Copy a range of the MutableByteArray\# to the memory range starting at the
1945    Addr\#. The MutableByteArray\# and the memory region at Addr\# must fully
1946    contain the specified ranges, but this is not checked. The Addr\# must not
1947    point into the MutableByteArray\# (e.g. if the MutableByteArray\# were
1948    pinned), but this is not checked either.}
1949   with
1950   has_side_effects = True
1951   code_size = { primOpCodeSizeForeignCall + 4}
1952   can_fail = True
1953
1954 primop  CopyAddrToByteArrayOp "copyAddrToByteArray#" GenPrimOp
1955   Addr# -> MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1956   {Copy a memory range starting at the Addr\# to the specified range in the
1957    MutableByteArray\#. The memory region at Addr\# and the ByteArray\# must fully
1958    contain the specified ranges, but this is not checked. The Addr\# must not
1959    point into the MutableByteArray\# (e.g. if the MutableByteArray\# were pinned),
1960    but this is not checked either.}
1961   with
1962   has_side_effects = True
1963   code_size = { primOpCodeSizeForeignCall + 4}
1964   can_fail = True
1965
1966 primop  SetByteArrayOp "setByteArray#" GenPrimOp
1967   MutableByteArray# s -> Int# -> Int# -> Int# -> State# s -> State# s
1968   {{\tt setByteArray# ba off len c} sets the byte range {\tt [off, off+len]} of
1969    the {\tt MutableByteArray#} to the byte {\tt c}.}
1970   with
1971   has_side_effects = True
1972   code_size = { primOpCodeSizeForeignCall + 4 }
1973   can_fail = True
1974
1975 -- Atomic operations
1976
1977 primop  AtomicReadByteArrayOp_Int "atomicReadIntArray#" GenPrimOp
1978    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
1979    {Given an array and an offset in machine words, read an element. The
1980     index is assumed to be in bounds. Implies a full memory barrier.}
1981    with has_side_effects = True
1982         can_fail = True
1983
1984 primop  AtomicWriteByteArrayOp_Int "atomicWriteIntArray#" GenPrimOp
1985    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1986    {Given an array and an offset in machine words, write an element. The
1987     index is assumed to be in bounds. Implies a full memory barrier.}
1988    with has_side_effects = True
1989         can_fail = True
1990
1991 primop CasByteArrayOp_Int "casIntArray#" GenPrimOp
1992    MutableByteArray# s -> Int# -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1993    {Given an array, an offset in machine words, the expected old value, and
1994     the new value, perform an atomic compare and swap i.e. write the new
1995     value if the current value matches the provided old value. Returns
1996     the value of the element before the operation. Implies a full memory
1997     barrier.}
1998    with has_side_effects = True
1999         can_fail = True
2000
2001 primop FetchAddByteArrayOp_Int "fetchAddIntArray#" GenPrimOp
2002    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
2003    {Given an array, and offset in machine words, and a value to add,
2004     atomically add the value to the element. Returns the value of the
2005     element before the operation. Implies a full memory barrier.}
2006    with has_side_effects = True
2007         can_fail = True
2008
2009 primop FetchSubByteArrayOp_Int "fetchSubIntArray#" GenPrimOp
2010    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
2011    {Given an array, and offset in machine words, and a value to subtract,
2012     atomically substract the value to the element. Returns the value of
2013     the element before the operation. Implies a full memory barrier.}
2014    with has_side_effects = True
2015         can_fail = True
2016
2017 primop FetchAndByteArrayOp_Int "fetchAndIntArray#" GenPrimOp
2018    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
2019    {Given an array, and offset in machine words, and a value to AND,
2020     atomically AND the value to the element. Returns the value of the
2021     element before the operation. Implies a full memory barrier.}
2022    with has_side_effects = True
2023         can_fail = True
2024
2025 primop FetchNandByteArrayOp_Int "fetchNandIntArray#" GenPrimOp
2026    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
2027    {Given an array, and offset in machine words, and a value to NAND,
2028     atomically NAND the value to the element. Returns the value of the
2029     element before the operation. Implies a full memory barrier.}
2030    with has_side_effects = True
2031         can_fail = True
2032
2033 primop FetchOrByteArrayOp_Int "fetchOrIntArray#" GenPrimOp
2034    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
2035    {Given an array, and offset in machine words, and a value to OR,
2036     atomically OR the value to the element. Returns the value of the
2037     element before the operation. Implies a full memory barrier.}
2038    with has_side_effects = True
2039         can_fail = True
2040
2041 primop FetchXorByteArrayOp_Int "fetchXorIntArray#" GenPrimOp
2042    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
2043    {Given an array, and offset in machine words, and a value to XOR,
2044     atomically XOR the value to the element. Returns the value of the
2045     element before the operation. Implies a full memory barrier.}
2046    with has_side_effects = True
2047         can_fail = True
2048
2049
2050 ------------------------------------------------------------------------
2051 section "Arrays of arrays"
2052         {Operations on {\tt ArrayArray\#}. An {\tt ArrayArray\#} contains references to {\em unpointed}
2053          arrays, such as {\tt ByteArray\#s}. Hence, it is not parameterised by the element types,
2054          just like a {\tt ByteArray\#}, but it needs to be scanned during GC, just like an {\tt Array\#}.
2055          We represent an {\tt ArrayArray\#} exactly as a {\tt Array\#}, but provide element-type-specific
2056          indexing, reading, and writing.}
2057 ------------------------------------------------------------------------
2058
2059 primtype ArrayArray#
2060
2061 primtype MutableArrayArray# s
2062
2063 primop  NewArrayArrayOp "newArrayArray#" GenPrimOp
2064    Int# -> State# s -> (# State# s, MutableArrayArray# s #)
2065    {Create a new mutable array of arrays with the specified number of elements,
2066     in the specified state thread, with each element recursively referring to the
2067     newly created array.}
2068    with
2069    out_of_line = True
2070    has_side_effects = True
2071
2072 primop  SameMutableArrayArrayOp "sameMutableArrayArray#" GenPrimOp
2073    MutableArrayArray# s -> MutableArrayArray# s -> Int#
2074
2075 primop  UnsafeFreezeArrayArrayOp "unsafeFreezeArrayArray#" GenPrimOp
2076    MutableArrayArray# s -> State# s -> (# State# s, ArrayArray# #)
2077    {Make a mutable array of arrays immutable, without copying.}
2078    with
2079    has_side_effects = True
2080
2081 primop  SizeofArrayArrayOp "sizeofArrayArray#" GenPrimOp
2082    ArrayArray# -> Int#
2083    {Return the number of elements in the array.}
2084
2085 primop  SizeofMutableArrayArrayOp "sizeofMutableArrayArray#" GenPrimOp
2086    MutableArrayArray# s -> Int#
2087    {Return the number of elements in the array.}
2088
2089 primop IndexArrayArrayOp_ByteArray "indexByteArrayArray#" GenPrimOp
2090    ArrayArray# -> Int# -> ByteArray#
2091    with can_fail = True
2092
2093 primop IndexArrayArrayOp_ArrayArray "indexArrayArrayArray#" GenPrimOp
2094    ArrayArray# -> Int# -> ArrayArray#
2095    with can_fail = True
2096
2097 primop  ReadArrayArrayOp_ByteArray "readByteArrayArray#" GenPrimOp
2098    MutableArrayArray# s -> Int# -> State# s -> (# State# s, ByteArray# #)
2099    with has_side_effects = True
2100         can_fail = True
2101
2102 primop  ReadArrayArrayOp_MutableByteArray "readMutableByteArrayArray#" GenPrimOp
2103    MutableArrayArray# s -> Int# -> State# s -> (# State# s, MutableByteArray# s #)
2104    with has_side_effects = True
2105         can_fail = True
2106
2107 primop  ReadArrayArrayOp_ArrayArray "readArrayArrayArray#" GenPrimOp
2108    MutableArrayArray# s -> Int# -> State# s -> (# State# s, ArrayArray# #)
2109    with has_side_effects = True
2110         can_fail = True
2111
2112 primop  ReadArrayArrayOp_MutableArrayArray "readMutableArrayArrayArray#" GenPrimOp
2113    MutableArrayArray# s -> Int# -> State# s -> (# State# s, MutableArrayArray# s #)
2114    with has_side_effects = True
2115         can_fail = True
2116
2117 primop  WriteArrayArrayOp_ByteArray "writeByteArrayArray#" GenPrimOp
2118    MutableArrayArray# s -> Int# -> ByteArray# -> State# s -> State# s
2119    with has_side_effects = True
2120         can_fail = True
2121
2122 primop  WriteArrayArrayOp_MutableByteArray "writeMutableByteArrayArray#" GenPrimOp
2123    MutableArrayArray# s -> Int# -> MutableByteArray# s -> State# s -> State# s
2124    with has_side_effects = True
2125         can_fail = True
2126
2127 primop  WriteArrayArrayOp_ArrayArray "writeArrayArrayArray#" GenPrimOp
2128    MutableArrayArray# s -> Int# -> ArrayArray# -> State# s -> State# s
2129    with has_side_effects = True
2130         can_fail = True
2131
2132 primop  WriteArrayArrayOp_MutableArrayArray "writeMutableArrayArrayArray#" GenPrimOp
2133    MutableArrayArray# s -> Int# -> MutableArrayArray# s -> State# s -> State# s
2134    with has_side_effects = True
2135         can_fail = True
2136
2137 primop  CopyArrayArrayOp "copyArrayArray#" GenPrimOp
2138   ArrayArray# -> Int# -> MutableArrayArray# s -> Int# -> Int# -> State# s -> State# s
2139   {Copy a range of the ArrayArray\# to the specified region in the MutableArrayArray\#.
2140    Both arrays must fully contain the specified ranges, but this is not checked.
2141    The two arrays must not be the same array in different states, but this is not checked either.}
2142   with
2143   out_of_line      = True
2144   has_side_effects = True
2145   can_fail         = True
2146
2147 primop  CopyMutableArrayArrayOp "copyMutableArrayArray#" GenPrimOp
2148   MutableArrayArray# s -> Int# -> MutableArrayArray# s -> Int# -> Int# -> State# s -> State# s
2149   {Copy a range of the first MutableArrayArray# to the specified region in the second
2150    MutableArrayArray#.
2151    Both arrays must fully contain the specified ranges, but this is not checked.
2152    The regions are allowed to overlap, although this is only possible when the same
2153    array is provided as both the source and the destination.
2154    }
2155   with
2156   out_of_line      = True
2157   has_side_effects = True
2158   can_fail         = True
2159
2160 ------------------------------------------------------------------------
2161 section "Addr#"
2162 ------------------------------------------------------------------------
2163
2164 primtype Addr#
2165         { An arbitrary machine address assumed to point outside
2166          the garbage-collected heap. }
2167
2168 pseudoop "nullAddr#" Addr#
2169         { The null address. }
2170
2171 primop   AddrAddOp "plusAddr#" GenPrimOp Addr# -> Int# -> Addr#
2172 primop   AddrSubOp "minusAddr#" GenPrimOp Addr# -> Addr# -> Int#
2173          {Result is meaningless if two {\tt Addr\#}s are so far apart that their
2174          difference doesn't fit in an {\tt Int\#}.}
2175 primop   AddrRemOp "remAddr#" GenPrimOp Addr# -> Int# -> Int#
2176          {Return the remainder when the {\tt Addr\#} arg, treated like an {\tt Int\#},
2177           is divided by the {\tt Int\#} arg.}
2178 #if (WORD_SIZE_IN_BITS == 32 || WORD_SIZE_IN_BITS == 64)
2179 primop   Addr2IntOp  "addr2Int#"     GenPrimOp   Addr# -> Int#
2180         {Coerce directly from address to int.}
2181    with code_size = 0
2182         deprecated_msg = { This operation is strongly deprecated. }
2183 primop   Int2AddrOp   "int2Addr#"    GenPrimOp  Int# -> Addr#
2184         {Coerce directly from int to address.}
2185    with code_size = 0
2186         deprecated_msg = { This operation is strongly deprecated. }
2187 #endif
2188
2189 primop   AddrGtOp  "gtAddr#"   Compare   Addr# -> Addr# -> Int#
2190 primop   AddrGeOp  "geAddr#"   Compare   Addr# -> Addr# -> Int#
2191 primop   AddrEqOp  "eqAddr#"   Compare   Addr# -> Addr# -> Int#
2192 primop   AddrNeOp  "neAddr#"   Compare   Addr# -> Addr# -> Int#
2193 primop   AddrLtOp  "ltAddr#"   Compare   Addr# -> Addr# -> Int#
2194 primop   AddrLeOp  "leAddr#"   Compare   Addr# -> Addr# -> Int#
2195
2196 primop IndexOffAddrOp_Char "indexCharOffAddr#" GenPrimOp
2197    Addr# -> Int# -> Char#
2198    {Reads 8-bit character; offset in bytes.}
2199    with can_fail = True
2200
2201 primop IndexOffAddrOp_WideChar "indexWideCharOffAddr#" GenPrimOp
2202    Addr# -> Int# -> Char#
2203    {Reads 31-bit character; offset in 4-byte words.}
2204    with can_fail = True
2205
2206 primop IndexOffAddrOp_Int "indexIntOffAddr#" GenPrimOp
2207    Addr# -> Int# -> Int#
2208    with can_fail = True
2209
2210 primop IndexOffAddrOp_Word "indexWordOffAddr#" GenPrimOp
2211    Addr# -> Int# -> Word#
2212    with can_fail = True
2213
2214 primop IndexOffAddrOp_Addr "indexAddrOffAddr#" GenPrimOp
2215    Addr# -> Int# -> Addr#
2216    with can_fail = True
2217
2218 primop IndexOffAddrOp_Float "indexFloatOffAddr#" GenPrimOp
2219    Addr# -> Int# -> Float#
2220    with can_fail = True
2221
2222 primop IndexOffAddrOp_Double "indexDoubleOffAddr#" GenPrimOp
2223    Addr# -> Int# -> Double#
2224    with can_fail = True
2225
2226 primop IndexOffAddrOp_StablePtr "indexStablePtrOffAddr#" GenPrimOp
2227    Addr# -> Int# -> StablePtr# a
2228    with can_fail = True
2229
2230 primop IndexOffAddrOp_Int8 "indexInt8OffAddr#" GenPrimOp
2231    Addr# -> Int# -> Int#
2232    with can_fail = True
2233
2234 primop IndexOffAddrOp_Int16 "indexInt16OffAddr#" GenPrimOp
2235    Addr# -> Int# -> Int#
2236    with can_fail = True
2237
2238 primop IndexOffAddrOp_Int32 "indexInt32OffAddr#" GenPrimOp
2239    Addr# -> Int# -> INT32
2240    with can_fail = True
2241
2242 primop IndexOffAddrOp_Int64 "indexInt64OffAddr#" GenPrimOp
2243    Addr# -> Int# -> INT64
2244    with can_fail = True
2245
2246 primop IndexOffAddrOp_Word8 "indexWord8OffAddr#" GenPrimOp
2247    Addr# -> Int# -> Word#
2248    with can_fail = True
2249
2250 primop IndexOffAddrOp_Word16 "indexWord16OffAddr#" GenPrimOp
2251    Addr# -> Int# -> Word#
2252    with can_fail = True
2253
2254 primop IndexOffAddrOp_Word32 "indexWord32OffAddr#" GenPrimOp
2255    Addr# -> Int# -> WORD32
2256    with can_fail = True
2257
2258 primop IndexOffAddrOp_Word64 "indexWord64OffAddr#" GenPrimOp
2259    Addr# -> Int# -> WORD64
2260    with can_fail = True
2261
2262 primop ReadOffAddrOp_Char "readCharOffAddr#" GenPrimOp
2263    Addr# -> Int# -> State# s -> (# State# s, Char# #)
2264    {Reads 8-bit character; offset in bytes.}
2265    with has_side_effects = True
2266         can_fail         = True
2267
2268 primop ReadOffAddrOp_WideChar "readWideCharOffAddr#" GenPrimOp
2269    Addr# -> Int# -> State# s -> (# State# s, Char# #)
2270    {Reads 31-bit character; offset in 4-byte words.}
2271    with has_side_effects = True
2272         can_fail         = True
2273
2274 primop ReadOffAddrOp_Int "readIntOffAddr#" GenPrimOp
2275    Addr# -> Int# -> State# s -> (# State# s, Int# #)
2276    with has_side_effects = True
2277         can_fail         = True
2278
2279 primop ReadOffAddrOp_Word "readWordOffAddr#" GenPrimOp
2280    Addr# -> Int# -> State# s -> (# State# s, Word# #)
2281    with has_side_effects = True
2282         can_fail         = True
2283
2284 primop ReadOffAddrOp_Addr "readAddrOffAddr#" GenPrimOp
2285    Addr# -> Int# -> State# s -> (# State# s, Addr# #)
2286    with has_side_effects = True
2287         can_fail         = True
2288
2289 primop ReadOffAddrOp_Float "readFloatOffAddr#" GenPrimOp
2290    Addr# -> Int# -> State# s -> (# State# s, Float# #)
2291    with has_side_effects = True
2292         can_fail         = True
2293
2294 primop ReadOffAddrOp_Double "readDoubleOffAddr#" GenPrimOp
2295    Addr# -> Int# -> State# s -> (# State# s, Double# #)
2296    with has_side_effects = True
2297         can_fail         = True
2298
2299 primop ReadOffAddrOp_StablePtr "readStablePtrOffAddr#" GenPrimOp
2300    Addr# -> Int# -> State# s -> (# State# s, StablePtr# a #)
2301    with has_side_effects = True
2302         can_fail         = True
2303
2304 primop ReadOffAddrOp_Int8 "readInt8OffAddr#" GenPrimOp
2305    Addr# -> Int# -> State# s -> (# State# s, Int# #)
2306    with has_side_effects = True
2307         can_fail         = True
2308
2309 primop ReadOffAddrOp_Int16 "readInt16OffAddr#" GenPrimOp
2310    Addr# -> Int# -> State# s -> (# State# s, Int# #)
2311    with has_side_effects = True
2312         can_fail         = True
2313
2314 primop ReadOffAddrOp_Int32 "readInt32OffAddr#" GenPrimOp
2315    Addr# -> Int# -> State# s -> (# State# s, INT32 #)
2316    with has_side_effects = True
2317         can_fail         = True
2318
2319 primop ReadOffAddrOp_Int64 "readInt64OffAddr#" GenPrimOp
2320    Addr# -> Int# -> State# s -> (# State# s, INT64 #)
2321    with has_side_effects = True
2322         can_fail         = True
2323
2324 primop ReadOffAddrOp_Word8 "readWord8OffAddr#" GenPrimOp
2325    Addr# -> Int# -> State# s -> (# State# s, Word# #)
2326    with has_side_effects = True
2327         can_fail         = True
2328
2329 primop ReadOffAddrOp_Word16 "readWord16OffAddr#" GenPrimOp
2330    Addr# -> Int# -> State# s -> (# State# s, Word# #)
2331    with has_side_effects = True
2332         can_fail         = True
2333
2334 primop ReadOffAddrOp_Word32 "readWord32OffAddr#" GenPrimOp
2335    Addr# -> Int# -> State# s -> (# State# s, WORD32 #)
2336    with has_side_effects = True
2337         can_fail         = True
2338
2339 primop ReadOffAddrOp_Word64 "readWord64OffAddr#" GenPrimOp
2340    Addr# -> Int# -> State# s -> (# State# s, WORD64 #)
2341    with has_side_effects = True
2342         can_fail         = True
2343
2344 primop  WriteOffAddrOp_Char "writeCharOffAddr#" GenPrimOp
2345    Addr# -> Int# -> Char# -> State# s -> State# s
2346    with has_side_effects = True
2347         can_fail         = True
2348
2349 primop  WriteOffAddrOp_WideChar "writeWideCharOffAddr#" GenPrimOp
2350    Addr# -> Int# -> Char# -> State# s -> State# s
2351    with has_side_effects = True
2352         can_fail         = True
2353
2354 primop  WriteOffAddrOp_Int "writeIntOffAddr#" GenPrimOp
2355    Addr# -> Int# -> Int# -> State# s -> State# s
2356    with has_side_effects = True
2357         can_fail         = True
2358
2359 primop  WriteOffAddrOp_Word "writeWordOffAddr#" GenPrimOp
2360    Addr# -> Int# -> Word# -> State# s -> State# s
2361    with has_side_effects = True
2362         can_fail         = True
2363
2364 primop  WriteOffAddrOp_Addr "writeAddrOffAddr#" GenPrimOp
2365    Addr# -> Int# -> Addr# -> State# s -> State# s
2366    with has_side_effects = True
2367         can_fail         = True
2368
2369 primop  WriteOffAddrOp_Float "writeFloatOffAddr#" GenPrimOp
2370    Addr# -> Int# -> Float# -> State# s -> State# s
2371    with has_side_effects = True
2372         can_fail         = True
2373
2374 primop  WriteOffAddrOp_Double "writeDoubleOffAddr#" GenPrimOp
2375    Addr# -> Int# -> Double# -> State# s -> State# s
2376    with has_side_effects = True
2377         can_fail         = True
2378
2379 primop  WriteOffAddrOp_StablePtr "writeStablePtrOffAddr#" GenPrimOp
2380    Addr# -> Int# -> StablePtr# a -> State# s -> State# s
2381    with has_side_effects = True
2382         can_fail         = True
2383
2384 primop  WriteOffAddrOp_Int8 "writeInt8OffAddr#" GenPrimOp
2385    Addr# -> Int# -> Int# -> State# s -> State# s
2386    with has_side_effects = True
2387         can_fail         = True
2388
2389 primop  WriteOffAddrOp_Int16 "writeInt16OffAddr#" GenPrimOp
2390    Addr# -> Int# -> Int# -> State# s -> State# s
2391    with has_side_effects = True
2392         can_fail         = True
2393
2394 primop  WriteOffAddrOp_Int32 "writeInt32OffAddr#" GenPrimOp
2395    Addr# -> Int# -> INT32 -> State# s -> State# s
2396    with has_side_effects = True
2397         can_fail         = True
2398
2399 primop  WriteOffAddrOp_Int64 "writeInt64OffAddr#" GenPrimOp
2400    Addr# -> Int# -> INT64 -> State# s -> State# s
2401    with has_side_effects = True
2402         can_fail         = True
2403
2404 primop  WriteOffAddrOp_Word8 "writeWord8OffAddr#" GenPrimOp
2405    Addr# -> Int# -> Word# -> State# s -> State# s
2406    with has_side_effects = True
2407         can_fail         = True
2408
2409 primop  WriteOffAddrOp_Word16 "writeWord16OffAddr#" GenPrimOp
2410    Addr# -> Int# -> Word# -> State# s -> State# s
2411    with has_side_effects = True
2412         can_fail         = True
2413
2414 primop  WriteOffAddrOp_Word32 "writeWord32OffAddr#" GenPrimOp
2415    Addr# -> Int# -> WORD32 -> State# s -> State# s
2416    with has_side_effects = True
2417         can_fail         = True
2418
2419 primop  WriteOffAddrOp_Word64 "writeWord64OffAddr#" GenPrimOp
2420    Addr# -> Int# -> WORD64 -> State# s -> State# s
2421    with has_side_effects = True
2422         can_fail         = True
2423
2424 ------------------------------------------------------------------------
2425 section "Mutable variables"
2426         {Operations on MutVar\#s.}
2427 ------------------------------------------------------------------------
2428
2429 primtype MutVar# s a
2430         {A {\tt MutVar\#} behaves like a single-element mutable array.}
2431
2432 primop  NewMutVarOp "newMutVar#" GenPrimOp
2433    a -> State# s -> (# State# s, MutVar# s a #)
2434    {Create {\tt MutVar\#} with specified initial value in specified state thread.}
2435    with
2436    out_of_line = True
2437    has_side_effects = True
2438
2439 -- Note [Why MutVar# ops can't fail]
2440 -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2441 --
2442 -- We don't label readMutVar# or writeMutVar# as can_fail.
2443 -- This may seem a bit peculiar, because they surely *could*
2444 -- fail spectacularly if passed a pointer to unallocated memory.
2445 -- But MutVar#s are always correct by construction; we never
2446 -- test if a pointer is valid before using it with these operations.
2447 -- So we never have to worry about floating the pointer reference
2448 -- outside a validity test. At the moment, has_side_effects blocks
2449 -- up the relevant optimizations anyway, but we hope to draw finer
2450 -- distinctions soon, which should improve matters for readMutVar#
2451 -- at least.
2452
2453 primop  ReadMutVarOp "readMutVar#" GenPrimOp
2454    MutVar# s a -> State# s -> (# State# s, a #)
2455    {Read contents of {\tt MutVar\#}. Result is not yet evaluated.}
2456    with
2457    -- See Note [Why MutVar# ops can't fail]
2458    has_side_effects = True
2459
2460 primop  WriteMutVarOp "writeMutVar#"  GenPrimOp
2461    MutVar# s a -> a -> State# s -> State# s
2462    {Write contents of {\tt MutVar\#}.}
2463    with
2464    -- See Note [Why MutVar# ops can't fail]
2465    has_side_effects = True
2466    code_size = { primOpCodeSizeForeignCall } -- for the write barrier
2467
2468 primop  SameMutVarOp "sameMutVar#" GenPrimOp
2469    MutVar# s a -> MutVar# s a -> Int#
2470
2471 -- Note [Why not an unboxed tuple in atomicModifyMutVar2#?]
2472 -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2473 --
2474 -- Looking at the type of atomicModifyMutVar2#, one might wonder why
2475 -- it doesn't return an unboxed tuple. e.g.,
2476 --
2477 --   MutVar# s a -> (a -> (# a, b #)) -> State# s -> (# State# s, a, (# a, b #) #)
2478 --
2479 -- The reason is that atomicModifyMutVar2# relies on laziness for its atomicity.
2480 -- Given a MutVar# containing x, atomicModifyMutVar2# merely replaces
2481 -- its contents with a thunk of the form (fst (f x)). This can be done using an
2482 -- atomic compare-and-swap as it is merely replacing a pointer.
2483
2484 primop  AtomicModifyMutVar2Op "atomicModifyMutVar2#" GenPrimOp
2485    MutVar# s a -> (a -> c) -> State# s -> (# State# s, a, c #)
2486    { Modify the contents of a {\tt MutVar\#}, returning the previous
2487      contents and the result of applying the given function to the
2488      previous contents. Note that this isn't strictly
2489      speaking the correct type for this function; it should really be
2490      {\tt MutVar\# s a -> (a -> (a,b)) -> State\# s -> (\# State\# s, a, (a, b) \#)},
2491      but we don't know about pairs here. }
2492    with
2493    out_of_line = True
2494    has_side_effects = True
2495    can_fail         = True
2496
2497 primop  AtomicModifyMutVar_Op "atomicModifyMutVar_#" GenPrimOp
2498    MutVar# s a -> (a -> a) -> State# s -> (# State# s, a, a #)
2499    { Modify the contents of a {\tt MutVar\#}, returning the previous
2500      contents and the result of applying the given function to the
2501      previous contents. }
2502    with
2503    out_of_line = True
2504    has_side_effects = True
2505    can_fail         = True
2506
2507 primop  CasMutVarOp "casMutVar#" GenPrimOp
2508   MutVar# s a -> a -> a -> State# s -> (# State# s, Int#, a #)
2509    with
2510    out_of_line = True
2511    has_side_effects = True
2512
2513 ------------------------------------------------------------------------
2514 section "Exceptions"
2515 ------------------------------------------------------------------------
2516
2517 -- Note [Strictness for mask/unmask/catch]
2518 -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2519 -- Consider this example, which comes from GHC.IO.Handle.Internals:
2520 --    wantReadableHandle3 f ma b st
2521 --      = case ... of
2522 --          DEFAULT -> case ma of MVar a -> ...
2523 --          0#      -> maskAsynchExceptions# (\st -> case ma of MVar a -> ...)
2524 -- The outer case just decides whether to mask exceptions, but we don't want
2525 -- thereby to hide the strictness in 'ma'!  Hence the use of strictApply1Dmd.
2526
2527 primop  CatchOp "catch#" GenPrimOp
2528           (State# RealWorld -> (# State# RealWorld, a #) )
2529        -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
2530        -> State# RealWorld
2531        -> (# State# RealWorld, a #)
2532    with
2533    strictness  = { \ _arity -> mkClosedStrictSig [ lazyApply1Dmd
2534                                                  , lazyApply2Dmd
2535                                                  , topDmd] topRes }
2536                  -- See Note [Strictness for mask/unmask/catch]
2537    out_of_line = True
2538    has_side_effects = True
2539
2540 primop  RaiseOp "raise#" GenPrimOp
2541    b -> o
2542       -- NB: the type variable "o" is "a", but with OpenKind
2543    with
2544    strictness  = { \ _arity -> mkClosedStrictSig [topDmd] botRes }
2545    out_of_line = True
2546    has_side_effects = True
2547      -- raise# certainly throws a Haskell exception and hence has_side_effects
2548      -- It doesn't actually make much difference because the fact that it
2549      -- returns bottom independently ensures that we are careful not to discard
2550      -- it.  But still, it's better to say the Right Thing.
2551
2552 -- raiseIO# needs to be a primop, because exceptions in the IO monad
2553 -- must be *precise* - we don't want the strictness analyser turning
2554 -- one kind of bottom into another, as it is allowed to do in pure code.
2555 --
2556 -- But we *do* want to know that it returns bottom after
2557 -- being applied to two arguments, so that this function is strict in y
2558 --     f x y | x>0       = raiseIO blah
2559 --           | y>0       = return 1
2560 --           | otherwise = return 2
2561 --
2562 -- TODO Check that the above notes on @f@ are valid. The function successfully
2563 -- produces an IO exception when compiled without optimization. If we analyze
2564 -- it as strict in @y@, won't we change that behavior under optimization?
2565 -- I thought the rule was that it was okay to replace one valid imprecise
2566 -- exception with another, but not to replace a precise exception with
2567 -- an imprecise one (dfeuer, 2017-03-05).
2568
2569 primop  RaiseIOOp "raiseIO#" GenPrimOp
2570    a -> State# RealWorld -> (# State# RealWorld, b #)
2571    with
2572    strictness  = { \ _arity -> mkClosedStrictSig [topDmd, topDmd] botRes }
2573    out_of_line = True
2574    has_side_effects = True
2575
2576 primop  MaskAsyncExceptionsOp "maskAsyncExceptions#" GenPrimOp
2577         (State# RealWorld -> (# State# RealWorld, a #))
2578      -> (State# RealWorld -> (# State# RealWorld, a #))
2579    with
2580    strictness  = { \ _arity -> mkClosedStrictSig [strictApply1Dmd,topDmd] topRes }
2581                  -- See Note [Strictness for mask/unmask/catch]
2582    out_of_line = True
2583    has_side_effects = True
2584
2585 primop  MaskUninterruptibleOp "maskUninterruptible#" GenPrimOp
2586         (State# RealWorld -> (# State# RealWorld, a #))
2587      -> (State# RealWorld -> (# State# RealWorld, a #))
2588    with
2589    strictness  = { \ _arity -> mkClosedStrictSig [strictApply1Dmd,topDmd] topRes }
2590    out_of_line = True
2591    has_side_effects = True
2592
2593 primop  UnmaskAsyncExceptionsOp "unmaskAsyncExceptions#" GenPrimOp
2594         (State# RealWorld -> (# State# RealWorld, a #))
2595      -> (State# RealWorld -> (# State# RealWorld, a #))
2596    with
2597    strictness  = { \ _arity -> mkClosedStrictSig [strictApply1Dmd,topDmd] topRes }
2598                  -- See Note [Strictness for mask/unmask/catch]
2599    out_of_line = True
2600    has_side_effects = True
2601
2602 primop  MaskStatus "getMaskingState#" GenPrimOp
2603         State# RealWorld -> (# State# RealWorld, Int# #)
2604    with
2605    out_of_line = True
2606    has_side_effects = True
2607
2608 ------------------------------------------------------------------------
2609 section "STM-accessible Mutable Variables"
2610 ------------------------------------------------------------------------
2611
2612 primtype TVar# s a
2613
2614 primop  AtomicallyOp "atomically#" GenPrimOp
2615       (State# RealWorld -> (# State# RealWorld, a #) )
2616    -> State# RealWorld -> (# State# RealWorld, a #)
2617    with
2618    strictness  = { \ _arity -> mkClosedStrictSig [strictApply1Dmd,topDmd] topRes }
2619                  -- See Note [Strictness for mask/unmask/catch]
2620    out_of_line = True
2621    has_side_effects = True
2622
2623 -- NB: retry#'s strictness information specifies it to diverge.
2624 -- This lets the compiler perform some extra simplifications, since retry#
2625 -- will technically never return.
2626 --
2627 -- This allows the simplifier to replace things like:
2628 --   case retry# s1
2629 --     (# s2, a #) -> e
2630 -- with:
2631 --   retry# s1
2632 -- where 'e' would be unreachable anyway.  See #8091.
2633 primop  RetryOp "retry#" GenPrimOp
2634    State# RealWorld -> (# State# RealWorld, a #)
2635    with
2636    strictness  = { \ _arity -> mkClosedStrictSig [topDmd] botRes }
2637    out_of_line = True
2638    has_side_effects = True
2639
2640 primop  CatchRetryOp "catchRetry#" GenPrimOp
2641       (State# RealWorld -> (# State# RealWorld, a #) )
2642    -> (State# RealWorld -> (# State# RealWorld, a #) )
2643    -> (State# RealWorld -> (# State# RealWorld, a #) )
2644    with
2645    strictness  = { \ _arity -> mkClosedStrictSig [ lazyApply1Dmd
2646                                                  , lazyApply1Dmd
2647                                                  , topDmd ] topRes }
2648                  -- See Note [Strictness for mask/unmask/catch]
2649    out_of_line = True
2650    has_side_effects = True
2651
2652 primop  CatchSTMOp "catchSTM#" GenPrimOp
2653       (State# RealWorld -> (# State# RealWorld, a #) )
2654    -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
2655    -> (State# RealWorld -> (# State# RealWorld, a #) )
2656    with
2657    strictness  = { \ _arity -> mkClosedStrictSig [ lazyApply1Dmd
2658                                                  , lazyApply2Dmd
2659                                                  , topDmd ] topRes }
2660                  -- See Note [Strictness for mask/unmask/catch]
2661    out_of_line = True
2662    has_side_effects = True
2663
2664 primop  NewTVarOp "newTVar#" GenPrimOp
2665        a
2666     -> State# s -> (# State# s, TVar# s a #)
2667    {Create a new {\tt TVar\#} holding a specified initial value.}
2668    with
2669    out_of_line  = True
2670    has_side_effects = True
2671
2672 primop  ReadTVarOp "readTVar#" GenPrimOp
2673        TVar# s a
2674     -> State# s -> (# State# s, a #)
2675    {Read contents of {\tt TVar\#}.  Result is not yet evaluated.}
2676    with
2677    out_of_line  = True
2678    has_side_effects = True
2679
2680 primop ReadTVarIOOp "readTVarIO#" GenPrimOp
2681        TVar# s a
2682     -> State# s -> (# State# s, a #)
2683    {Read contents of {\tt TVar\#} outside an STM transaction}
2684    with
2685    out_of_line      = True
2686    has_side_effects = True
2687
2688 primop  WriteTVarOp "writeTVar#" GenPrimOp
2689        TVar# s a
2690     -> a
2691     -> State# s -> State# s
2692    {Write contents of {\tt TVar\#}.}
2693    with
2694    out_of_line      = True
2695    has_side_effects = True
2696
2697 primop  SameTVarOp "sameTVar#" GenPrimOp
2698    TVar# s a -> TVar# s a -> Int#
2699
2700
2701 ------------------------------------------------------------------------
2702 section "Synchronized Mutable Variables"
2703         {Operations on {\tt MVar\#}s. }
2704 ------------------------------------------------------------------------
2705
2706 primtype MVar# s a
2707         { A shared mutable variable ({\it not} the same as a {\tt MutVar\#}!).
2708         (Note: in a non-concurrent implementation, {\tt (MVar\# a)} can be
2709         represented by {\tt (MutVar\# (Maybe a))}.) }
2710
2711 primop  NewMVarOp "newMVar#"  GenPrimOp
2712    State# s -> (# State# s, MVar# s a #)
2713    {Create new {\tt MVar\#}; initially empty.}
2714    with
2715    out_of_line = True
2716    has_side_effects = True
2717
2718 primop  TakeMVarOp "takeMVar#" GenPrimOp
2719    MVar# s a -> State# s -> (# State# s, a #)
2720    {If {\tt MVar\#} is empty, block until it becomes full.
2721    Then remove and return its contents, and set it empty.}
2722    with
2723    out_of_line      = True
2724    has_side_effects = True
2725
2726 primop  TryTakeMVarOp "tryTakeMVar#" GenPrimOp
2727    MVar# s a -> State# s -> (# State# s, Int#, a #)
2728    {If {\tt MVar\#} is empty, immediately return with integer 0 and value undefined.
2729    Otherwise, return with integer 1 and contents of {\tt MVar\#}, and set {\tt MVar\#} empty.}
2730    with
2731    out_of_line      = True
2732    has_side_effects = True
2733
2734 primop  PutMVarOp "putMVar#" GenPrimOp
2735    MVar# s a -> a -> State# s -> State# s
2736    {If {\tt MVar\#} is full, block until it becomes empty.
2737    Then store value arg as its new contents.}
2738    with
2739    out_of_line      = True
2740    has_side_effects = True
2741
2742 primop  TryPutMVarOp "tryPutMVar#" GenPrimOp
2743    MVar# s a -> a -> State# s -> (# State# s, Int# #)
2744    {If {\tt MVar\#} is full, immediately return with integer 0.
2745     Otherwise, store value arg as {\tt MVar\#}'s new contents, and return with integer 1.}
2746    with
2747    out_of_line      = True
2748    has_side_effects = True
2749
2750 primop  ReadMVarOp "readMVar#" GenPrimOp
2751    MVar# s a -> State# s -> (# State# s, a #)
2752    {If {\tt MVar\#} is empty, block until it becomes full.
2753    Then read its contents without modifying the MVar, without possibility
2754    of intervention from other threads.}
2755    with
2756    out_of_line      = True
2757    has_side_effects = True
2758
2759 primop  TryReadMVarOp "tryReadMVar#" GenPrimOp
2760    MVar# s a -> State# s -> (# State# s, Int#, a #)
2761    {If {\tt MVar\#} is empty, immediately return with integer 0 and value undefined.
2762    Otherwise, return with integer 1 and contents of {\tt MVar\#}.}
2763    with
2764    out_of_line      = True
2765    has_side_effects = True
2766
2767 primop  SameMVarOp "sameMVar#" GenPrimOp
2768    MVar# s a -> MVar# s a -> Int#
2769
2770 primop  IsEmptyMVarOp "isEmptyMVar#" GenPrimOp
2771    MVar# s a -> State# s -> (# State# s, Int# #)
2772    {Return 1 if {\tt MVar\#} is empty; 0 otherwise.}
2773    with
2774    out_of_line = True
2775    has_side_effects = True
2776
2777 ------------------------------------------------------------------------
2778 section "Delay/wait operations"
2779 ------------------------------------------------------------------------
2780
2781 primop  DelayOp "delay#" GenPrimOp
2782    Int# -> State# s -> State# s
2783    {Sleep specified number of microseconds.}
2784    with
2785    has_side_effects = True
2786    out_of_line      = True
2787
2788 primop  WaitReadOp "waitRead#" GenPrimOp
2789    Int# -> State# s -> State# s
2790    {Block until input is available on specified file descriptor.}
2791    with
2792    has_side_effects = True
2793    out_of_line      = True
2794
2795 primop  WaitWriteOp "waitWrite#" GenPrimOp
2796    Int# -> State# s -> State# s
2797    {Block until output is possible on specified file descriptor.}
2798    with
2799    has_side_effects = True
2800    out_of_line      = True
2801
2802 #if defined(mingw32_TARGET_OS)
2803 primop  AsyncReadOp "asyncRead#" GenPrimOp
2804    Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
2805    {Asynchronously read bytes from specified file descriptor.}
2806    with
2807    has_side_effects = True
2808    out_of_line      = True
2809
2810 primop  AsyncWriteOp "asyncWrite#" GenPrimOp
2811    Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
2812    {Asynchronously write bytes from specified file descriptor.}
2813    with
2814    has_side_effects = True
2815    out_of_line      = True
2816
2817 primop  AsyncDoProcOp "asyncDoProc#" GenPrimOp
2818    Addr# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
2819    {Asynchronously perform procedure (first arg), passing it 2nd arg.}
2820    with
2821    has_side_effects = True
2822    out_of_line      = True
2823
2824 #endif
2825
2826 ------------------------------------------------------------------------
2827 section "Concurrency primitives"
2828 ------------------------------------------------------------------------
2829
2830 primtype State# s
2831         { {\tt State\#} is the primitive, unlifted type of states.  It has
2832         one type parameter, thus {\tt State\# RealWorld}, or {\tt State\# s},
2833         where s is a type variable. The only purpose of the type parameter
2834         is to keep different state threads separate.  It is represented by
2835         nothing at all. }
2836
2837 primtype RealWorld
2838         { {\tt RealWorld} is deeply magical.  It is {\it primitive}, but it is not
2839         {\it unlifted} (hence {\tt ptrArg}).  We never manipulate values of type
2840         {\tt RealWorld}; it's only used in the type system, to parameterise {\tt State\#}. }
2841
2842 primtype ThreadId#
2843         {(In a non-concurrent implementation, this can be a singleton
2844         type, whose (unique) value is returned by {\tt myThreadId\#}.  The
2845         other operations can be omitted.)}
2846
2847 primop  ForkOp "fork#" GenPrimOp
2848    a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
2849    with
2850    has_side_effects = True
2851    out_of_line      = True
2852
2853 primop  ForkOnOp "forkOn#" GenPrimOp
2854    Int# -> a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
2855    with
2856    has_side_effects = True
2857    out_of_line      = True
2858
2859 primop  KillThreadOp "killThread#"  GenPrimOp
2860    ThreadId# -> a -> State# RealWorld -> State# RealWorld
2861    with
2862    has_side_effects = True
2863    out_of_line      = True
2864
2865 primop  YieldOp "yield#" GenPrimOp
2866    State# RealWorld -> State# RealWorld
2867    with
2868    has_side_effects = True
2869    out_of_line      = True
2870
2871 primop  MyThreadIdOp "myThreadId#" GenPrimOp
2872    State# RealWorld -> (# State# RealWorld, ThreadId# #)
2873    with
2874    has_side_effects = True
2875
2876 primop LabelThreadOp "labelThread#" GenPrimOp
2877    ThreadId# -> Addr# -> State# RealWorld -> State# RealWorld
2878    with
2879    has_side_effects = True
2880    out_of_line      = True
2881
2882 primop  IsCurrentThreadBoundOp "isCurrentThreadBound#" GenPrimOp
2883    State# RealWorld -> (# State# RealWorld, Int# #)
2884    with
2885    out_of_line = True
2886    has_side_effects = True
2887
2888 primop  NoDuplicateOp "noDuplicate#" GenPrimOp
2889    State# s -> State# s
2890    with
2891    out_of_line = True
2892    has_side_effects = True
2893
2894 primop  ThreadStatusOp "threadStatus#" GenPrimOp
2895    ThreadId# -> State# RealWorld -> (# State# RealWorld, Int#, Int#, Int# #)
2896    with
2897    out_of_line = True
2898    has_side_effects = True
2899
2900 ------------------------------------------------------------------------
2901 section "Weak pointers"
2902 ------------------------------------------------------------------------
2903
2904 primtype Weak# b
2905
2906 -- note that tyvar "o" denotes openAlphaTyVar
2907
2908 primop  MkWeakOp "mkWeak#" GenPrimOp
2909    o -> b -> (State# RealWorld -> (# State# RealWorld, c #))
2910      -> State# RealWorld -> (# State# RealWorld, Weak# b #)
2911    { {\tt mkWeak# k v finalizer s} creates a weak reference to value {\tt k},
2912      with an associated reference to some value {\tt v}. If {\tt k} is still
2913      alive then {\tt v} can be retrieved using {\tt deRefWeak#}. Note that
2914      the type of {\tt k} must be represented by a pointer (i.e. of kind {\tt
2915      TYPE 'LiftedRep} or {\tt TYPE 'UnliftedRep}). }
2916    with
2917    has_side_effects = True
2918    out_of_line      = True
2919
2920 primop  MkWeakNoFinalizerOp "mkWeakNoFinalizer#" GenPrimOp
2921    o -> b -> State# RealWorld -> (# State# RealWorld, Weak# b #)
2922    with
2923    has_side_effects = True
2924    out_of_line      = True
2925
2926 primop  AddCFinalizerToWeakOp "addCFinalizerToWeak#" GenPrimOp
2927    Addr# -> Addr# -> Int# -> Addr# -> Weak# b
2928           -> State# RealWorld -> (# State# RealWorld, Int# #)
2929    { {\tt addCFinalizerToWeak# fptr ptr flag eptr w} attaches a C
2930      function pointer {\tt fptr} to a weak pointer {\tt w} as a finalizer. If
2931      {\tt flag} is zero, {\tt fptr} will be called with one argument,
2932      {\tt ptr}. Otherwise, it will be called with two arguments,
2933      {\tt eptr} and {\tt ptr}. {\tt addCFinalizerToWeak#} returns
2934      1 on success, or 0 if {\tt w} is already dead. }
2935    with
2936    has_side_effects = True
2937    out_of_line      = True
2938
2939 primop  DeRefWeakOp "deRefWeak#" GenPrimOp
2940    Weak# a -> State# RealWorld -> (# State# RealWorld, Int#, a #)
2941    with
2942    has_side_effects = True
2943    out_of_line      = True
2944
2945 primop  FinalizeWeakOp "finalizeWeak#" GenPrimOp
2946    Weak# a -> State# RealWorld -> (# State# RealWorld, Int#,
2947               (State# RealWorld -> (# State# RealWorld, b #) ) #)
2948    { Finalize a weak pointer. The return value is an unboxed tuple
2949      containing the new state of the world and an "unboxed Maybe",
2950      represented by an {\tt Int#} and a (possibly invalid) finalization
2951      action. An {\tt Int#} of {\tt 1} indicates that the finalizer is valid. The
2952      return value {\tt b} from the finalizer should be ignored. }
2953    with
2954    has_side_effects = True
2955    out_of_line      = True
2956
2957 primop TouchOp "touch#" GenPrimOp
2958    o -> State# RealWorld -> State# RealWorld
2959    with
2960    code_size = { 0 }
2961    has_side_effects = True
2962
2963 ------------------------------------------------------------------------
2964 section "Stable pointers and names"
2965 ------------------------------------------------------------------------
2966
2967 primtype StablePtr# a
2968
2969 primtype StableName# a
2970
2971 primop  MakeStablePtrOp "makeStablePtr#" GenPrimOp
2972    a -> State# RealWorld -> (# State# RealWorld, StablePtr# a #)
2973    with
2974    has_side_effects = True
2975    out_of_line      = True
2976
2977 primop  DeRefStablePtrOp "deRefStablePtr#" GenPrimOp
2978    StablePtr# a -> State# RealWorld -> (# State# RealWorld, a #)
2979    with
2980    has_side_effects = True
2981    out_of_line      = True
2982
2983 primop  EqStablePtrOp "eqStablePtr#" GenPrimOp
2984    StablePtr# a -> StablePtr# a -> Int#
2985    with
2986    has_side_effects = True
2987
2988 primop  MakeStableNameOp "makeStableName#" GenPrimOp
2989    a -> State# RealWorld -> (# State# RealWorld, StableName# a #)
2990    with
2991    has_side_effects = True
2992    out_of_line      = True
2993
2994 primop  EqStableNameOp "eqStableName#" GenPrimOp
2995    StableName# a -> StableName# b -> Int#
2996
2997 primop  StableNameToIntOp "stableNameToInt#" GenPrimOp
2998    StableName# a -> Int#
2999
3000 ------------------------------------------------------------------------
3001 section "Compact normal form"
3002
3003         {Primitives for working with compact regions. The {\tt ghc\-compact}
3004          library and the {\tt compact} library demonstrate how to use these
3005          primitives. The documentation below draws a distinction between
3006          a CNF and a compact block. A CNF contains one or more compact
3007          blocks. The source file {\tt rts\/sm\/CNF.c}
3008          diagrams this relationship. When discussing a compact
3009          block, an additional distinction is drawn between capacity and
3010          utilized bytes. The capacity is the maximum number of bytes that
3011          the compact block can hold. The utilized bytes is the number of
3012          bytes that are actually used by the compact block.
3013         }
3014
3015 ------------------------------------------------------------------------
3016
3017 primtype Compact#
3018
3019 primop  CompactNewOp "compactNew#" GenPrimOp
3020    Word# -> State# RealWorld -> (# State# RealWorld, Compact# #)
3021    { Create a new CNF with a single compact block. The argument is
3022      the capacity of the compact block (in bytes, not words).
3023      The capacity is rounded up to a multiple of the allocator block size
3024      and is capped to one mega block. }
3025    with
3026    has_side_effects = True
3027    out_of_line      = True
3028
3029 primop  CompactResizeOp "compactResize#" GenPrimOp
3030    Compact# -> Word# -> State# RealWorld ->
3031    State# RealWorld
3032    { Set the new allocation size of the CNF. This value (in bytes)
3033      determines the capacity of each compact block in the CNF. It
3034      does not retroactively affect existing compact blocks in the CNF. }
3035    with
3036    has_side_effects = True
3037    out_of_line      = True
3038
3039 primop  CompactContainsOp "compactContains#" GenPrimOp
3040    Compact# -> a -> State# RealWorld -> (# State# RealWorld, Int# #)
3041    { Returns 1\# if the object is contained in the CNF, 0\# otherwise. }
3042    with
3043    out_of_line      = True
3044
3045 primop  CompactContainsAnyOp "compactContainsAny#" GenPrimOp
3046    a -> State# RealWorld -> (# State# RealWorld, Int# #)
3047    { Returns 1\# if the object is in any CNF at all, 0\# otherwise. }
3048    with
3049    out_of_line      = True
3050
3051 primop  CompactGetFirstBlockOp "compactGetFirstBlock#" GenPrimOp
3052    Compact# -> State# RealWorld -> (# State# RealWorld, Addr#, Word# #)
3053    { Returns the address and the utilized size (in bytes) of the
3054      first compact block of a CNF.}
3055    with
3056    out_of_line      = True
3057
3058 primop  CompactGetNextBlockOp "compactGetNextBlock#" GenPrimOp
3059    Compact# -> Addr# -> State# RealWorld -> (# State# RealWorld, Addr#, Word# #)
3060    { Given a CNF and the address of one its compact blocks, returns the
3061      next compact block and its utilized size, or {\tt nullAddr\#} if the
3062      argument was the last compact block in the CNF. }
3063    with
3064    out_of_line      = True
3065
3066 primop  CompactAllocateBlockOp "compactAllocateBlock#" GenPrimOp
3067    Word# -> Addr# -> State# RealWorld -> (# State# RealWorld, Addr# #)
3068    { Attempt to allocate a compact block with the capacity (in
3069      bytes) given by the first argument. The {\texttt Addr\#} is a pointer
3070      to previous compact block of the CNF or {\texttt nullAddr\#} to create a
3071      new CNF with a single compact block.
3072
3073      The resulting block is not known to the GC until
3074      {\texttt compactFixupPointers\#} is called on it, and care must be taken
3075      so that the address does not escape or memory will be leaked.
3076    }
3077    with
3078    has_side_effects = True
3079    out_of_line      = True
3080
3081 primop  CompactFixupPointersOp "compactFixupPointers#" GenPrimOp
3082    Addr# -> Addr# -> State# RealWorld -> (# State# RealWorld, Compact#, Addr# #)
3083    { Given the pointer to the first block of a CNF and the
3084      address of the root object in the old address space, fix up
3085      the internal pointers inside the CNF to account for
3086      a different position in memory than when it was serialized.
3087      This method must be called exactly once after importing
3088      a serialized CNF. It returns the new CNF and the new adjusted
3089      root address. }
3090    with
3091    has_side_effects = True
3092    out_of_line      = True
3093
3094 primop CompactAdd "compactAdd#" GenPrimOp
3095    Compact# -> a -> State# RealWorld -> (# State# RealWorld, a #)
3096    { Recursively add a closure and its transitive closure to a
3097      {\texttt Compact\#} (a CNF), evaluating any unevaluated components
3098      at the same time. Note: {\texttt compactAdd\#} is not thread-safe, so
3099      only one thread may call {\texttt compactAdd\#} with a particular
3100      {\texttt Compact\#} at any given time. The primop does not
3101      enforce any mutual exclusion; the caller is expected to
3102      arrange this. }
3103    with
3104    has_side_effects = True
3105    out_of_line      = True
3106
3107 primop CompactAddWithSharing "compactAddWithSharing#" GenPrimOp
3108    Compact# -> a -> State# RealWorld -> (# State# RealWorld, a #)
3109    { Like {\texttt compactAdd\#}, but retains sharing and cycles
3110    during compaction. }
3111    with
3112    has_side_effects = True
3113    out_of_line      = True
3114
3115 primop CompactSize "compactSize#" GenPrimOp
3116    Compact# -> State# RealWorld -> (# State# RealWorld, Word# #)
3117    { Return the total capacity (in bytes) of all the compact blocks
3118      in the CNF. }
3119    with
3120    has_side_effects = True
3121    out_of_line      = True
3122
3123 ------------------------------------------------------------------------
3124 section "Unsafe pointer equality"
3125 --  (#1 Bad Guy: Alastair Reid :)
3126 ------------------------------------------------------------------------
3127
3128 primop  ReallyUnsafePtrEqualityOp "reallyUnsafePtrEquality#" GenPrimOp
3129    a -> a -> Int#
3130    { Returns {\texttt 1\#} if the given pointers are equal and {\texttt 0\#} otherwise. }
3131    with
3132    can_fail   = True -- See Note [reallyUnsafePtrEquality#]
3133
3134
3135 -- Note [reallyUnsafePtrEquality#]
3136 -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3137 --
3138 -- reallyUnsafePtrEquality# can't actually fail, per se, but we mark it can_fail
3139 -- anyway. Until 5a9a1738023a, GHC considered primops okay for speculation only
3140 -- when their arguments were known to be forced. This was unnecessarily
3141 -- conservative, but it prevented reallyUnsafePtrEquality# from floating out of
3142 -- places where its arguments were known to be forced. Unfortunately, GHC could
3143 -- sometimes lose track of whether those arguments were forced, leading to let/app
3144 -- invariant failures (see #13027 and the discussion in #11444). Now that
3145 -- ok_for_speculation skips over lifted arguments, we need to explicitly prevent
3146 -- reallyUnsafePtrEquality# from floating out. Imagine if we had
3147 --
3148 --     \x y . case x of x'
3149 --              DEFAULT ->
3150 --            case y of y'
3151 --              DEFAULT ->
3152 --               let eq = reallyUnsafePtrEquality# x' y'
3153 --               in ...
3154 --
3155 -- If the let floats out, we'll get
3156 --
3157 --     \x y . let eq = reallyUnsafePtrEquality# x y
3158 --            in case x of ...
3159 --
3160 -- The trouble is that pointer equality between thunks is very different
3161 -- from pointer equality between the values those thunks reduce to, and the latter
3162 -- is typically much more precise.
3163
3164 ------------------------------------------------------------------------
3165 section "Parallelism"
3166 ------------------------------------------------------------------------
3167
3168 primop  ParOp "par#" GenPrimOp
3169    a -> Int#
3170    with
3171       -- Note that Par is lazy to avoid that the sparked thing
3172       -- gets evaluated strictly, which it should *not* be
3173    has_side_effects = True
3174    code_size = { primOpCodeSizeForeignCall }
3175    deprecated_msg = { Use 'spark#' instead }
3176
3177 primop SparkOp "spark#" GenPrimOp
3178    a -> State# s -> (# State# s, a #)
3179    with has_side_effects = True
3180    code_size = { primOpCodeSizeForeignCall }
3181
3182 primop SeqOp "seq#" GenPrimOp
3183    a -> State# s -> (# State# s, a #)
3184    -- See Note [seq# magic] in PrelRules
3185
3186 primop GetSparkOp "getSpark#" GenPrimOp
3187    State# s -> (# State# s, Int#, a #)
3188    with
3189    has_side_effects = True
3190    out_of_line = True
3191
3192 primop NumSparks "numSparks#" GenPrimOp
3193    State# s -> (# State# s, Int# #)
3194    { Returns the number of sparks in the local spark pool. }
3195    with
3196    has_side_effects = True
3197    out_of_line = True
3198
3199 ------------------------------------------------------------------------
3200 section "Tag to enum stuff"
3201         {Convert back and forth between values of enumerated types
3202         and small integers.}
3203 ------------------------------------------------------------------------
3204
3205 primop  DataToTagOp "dataToTag#" GenPrimOp
3206    a -> Int#  -- Zero-indexed; the first constructor has tag zero
3207    with
3208    strictness = { \ _arity -> mkClosedStrictSig [evalDmd] topRes }
3209    -- See Note [dataToTag# magic] in PrelRules
3210
3211 primop  TagToEnumOp "tagToEnum#" GenPrimOp
3212    Int# -> a
3213
3214 ------------------------------------------------------------------------
3215 section "Bytecode operations"
3216         {Support for manipulating bytecode objects used by the interpreter and
3217         linker.
3218
3219         Bytecode objects are heap objects which represent top-level bindings and
3220         contain a list of instructions and data needed by these instructions.}
3221 ------------------------------------------------------------------------
3222
3223 primtype BCO#
3224    { Primitive bytecode type. }
3225
3226 primop   AddrToAnyOp "addrToAny#" GenPrimOp
3227    Addr# -> (# a #)
3228    { Convert an {\tt Addr\#} to a followable Any type. }
3229    with
3230    code_size = 0
3231
3232 primop   AnyToAddrOp "anyToAddr#" GenPrimOp
3233    a -> State# RealWorld -> (# State# RealWorld, Addr# #)
3234    { Retrieve the address of any Haskell value. This is
3235      essentially an {\texttt unsafeCoerce\#}, but if implemented as such
3236      the core lint pass complains and fails to compile.
3237      As a primop, it is opaque to core/stg, and only appears
3238      in cmm (where the copy propagation pass will get rid of it).
3239      Note that "a" must be a value, not a thunk! It's too late
3240      for strictness analysis to enforce this, so you're on your
3241      own to guarantee this. Also note that {\texttt Addr\#} is not a GC
3242      pointer - up to you to guarantee that it does not become
3243      a dangling pointer immediately after you get it.}
3244    with
3245    code_size = 0
3246
3247 primop   MkApUpd0_Op "mkApUpd0#" GenPrimOp
3248    BCO# -> (# a #)
3249    { Wrap a BCO in a {\tt AP_UPD} thunk which will be updated with the value of
3250      the BCO when evaluated. }
3251    with
3252    out_of_line = True
3253
3254 primop  NewBCOOp "newBCO#" GenPrimOp
3255    ByteArray# -> ByteArray# -> Array# a -> Int# -> ByteArray# -> State# s -> (# State# s, BCO# #)
3256    { {\tt newBCO\# instrs lits ptrs arity bitmap} creates a new bytecode object. The
3257      resulting object encodes a function of the given arity with the instructions
3258      encoded in {\tt instrs}, and a static reference table usage bitmap given by
3259      {\tt bitmap}. }
3260    with
3261    has_side_effects = True
3262    out_of_line      = True
3263
3264 primop  UnpackClosureOp "unpackClosure#" GenPrimOp
3265    a -> (# Addr#, ByteArray#, Array# b #)
3266    { {\tt unpackClosure\# closure} copies the closure and pointers in the
3267      payload of the given closure into two new arrays, and returns a pointer to
3268      the first word of the closure's info table, a non-pointer array for the raw
3269      bytes of the closure, and a pointer array for the pointers in the payload. }
3270    with
3271    out_of_line = True
3272
3273 primop  ClosureSizeOp "closureSize#" GenPrimOp
3274    a -> Int#
3275    { {\tt closureSize\# closure} returns the size of the given closure in
3276      machine words. }
3277    with
3278    out_of_line = True
3279
3280 primop  GetApStackValOp "getApStackVal#" GenPrimOp
3281    a -> Int# -> (# Int#, b #)
3282    with
3283    out_of_line = True
3284
3285 ------------------------------------------------------------------------
3286 section "Misc"
3287         {These aren't nearly as wired in as Etc...}
3288 ------------------------------------------------------------------------
3289
3290 primop  GetCCSOfOp "getCCSOf#" GenPrimOp
3291    a -> State# s -> (# State# s, Addr# #)
3292
3293 primop  GetCurrentCCSOp "getCurrentCCS#" GenPrimOp
3294    a -> State# s -> (# State# s, Addr# #)
3295    { Returns the current {\tt CostCentreStack} (value is {\tt NULL} if
3296      not profiling).  Takes a dummy argument which can be used to
3297      avoid the call to {\tt getCurrentCCS\#} being floated out by the
3298      simplifier, which would result in an uninformative stack
3299      ("CAF"). }
3300
3301 primop  ClearCCSOp "clearCCS#" GenPrimOp
3302    (State# s -> (# State# s, a #)) -> State# s -> (# State# s, a #)
3303    { Run the supplied IO action with an empty CCS.  For example, this
3304      is used by the interpreter to run an interpreted computation
3305      without the call stack showing that it was invoked from GHC. }
3306    with
3307    out_of_line = True
3308
3309 ------------------------------------------------------------------------
3310 section "Etc"
3311         {Miscellaneous built-ins}
3312 ------------------------------------------------------------------------
3313
3314 primtype Proxy# a
3315    { The type constructor {\tt Proxy#} is used to bear witness to some
3316    type variable. It's used when you want to pass around proxy values
3317    for doing things like modelling type applications. A {\tt Proxy#}
3318    is not only unboxed, it also has a polymorphic kind, and has no
3319    runtime representation, being totally free. }
3320
3321 pseudoop "proxy#"
3322    Proxy# a
3323    { Witness for an unboxed {\tt Proxy#} value, which has no runtime
3324    representation. }
3325
3326 pseudoop   "seq"
3327    a -> b -> b
3328    { The value of {\tt seq a b} is bottom if {\tt a} is bottom, and
3329      otherwise equal to {\tt b}. In other words, it evaluates the first
3330      argument {\tt a} to weak head normal form (WHNF). {\tt seq} is usually
3331      introduced to improve performance by avoiding unneeded laziness.
3332
3333      A note on evaluation order: the expression {\tt seq a b} does
3334      {\it not} guarantee that {\tt a} will be evaluated before {\tt b}.
3335      The only guarantee given by {\tt seq} is that the both {\tt a}
3336      and {\tt b} will be evaluated before {\tt seq} returns a value.
3337      In particular, this means that {\tt b} may be evaluated before
3338      {\tt a}. If you need to guarantee a specific order of evaluation,
3339      you must use the function {\tt pseq} from the "parallel" package. }
3340    with fixity = infixr 0
3341          -- This fixity is only the one picked up by Haddock. If you
3342          -- change this, do update 'ghcPrimIface' in 'LoadIface.hs'.
3343
3344 pseudoop   "unsafeCoerce#"
3345    a -> b
3346    { The function {\tt unsafeCoerce\#} allows you to side-step the typechecker entirely. That
3347         is, it allows you to coerce any type into any other type. If you use this function,
3348         you had better get it right, otherwise segmentation faults await. It is generally
3349         used when you want to write a program that you know is well-typed, but where Haskell's
3350         type system is not expressive enough to prove that it is well typed.
3351
3352         The following uses of {\tt unsafeCoerce\#} are supposed to work (i.e. not lead to
3353         spurious compile-time or run-time crashes):
3354
3355          * Casting any lifted type to {\tt Any}
3356
3357          * Casting {\tt Any} back to the real type
3358
3359          * Casting an unboxed type to another unboxed type of the same size.
3360            (Casting between floating-point and integral types does not work.
3361            See the {\tt GHC.Float} module for functions to do work.)
3362
3363          * Casting between two types that have the same runtime representation.  One case is when
3364            the two types differ only in "phantom" type parameters, for example
3365            {\tt Ptr Int} to {\tt Ptr Float}, or {\tt [Int]} to {\tt [Float]} when the list is
3366            known to be empty.  Also, a {\tt newtype} of a type {\tt T} has the same representation
3367            at runtime as {\tt T}.
3368
3369         Other uses of {\tt unsafeCoerce\#} are undefined.  In particular, you should not use
3370         {\tt unsafeCoerce\#} to cast a T to an algebraic data type D, unless T is also
3371         an algebraic data type.  For example, do not cast {\tt Int->Int} to {\tt Bool}, even if
3372         you later cast that {\tt Bool} back to {\tt Int->Int} before applying it.  The reasons
3373         have to do with GHC's internal representation details (for the cognoscenti, data values
3374         can be entered but function closures cannot).  If you want a safe type to cast things
3375         to, use {\tt Any}, which is not an algebraic data type.
3376
3377         }
3378    with can_fail = True
3379
3380 -- NB. It is tempting to think that casting a value to a type that it doesn't have is safe
3381 -- as long as you don't "do anything" with the value in its cast form, such as seq on it.  This
3382 -- isn't the case: the compiler can insert seqs itself, and if these happen at the wrong type,
3383 -- Bad Things Might Happen.  See bug #1616: in this case we cast a function of type (a,b) -> (a,b)
3384 -- to () -> () and back again.  The strictness analyser saw that the function was strict, but
3385 -- the wrapper had type () -> (), and hence the wrapper de-constructed the (), the worker re-constructed
3386 -- a new (), with the result that the code ended up with "case () of (a,b) -> ...".
3387
3388 primop  TraceEventOp "traceEvent#" GenPrimOp
3389    Addr# -> State# s -> State# s
3390    { Emits an event via the RTS tracing framework.  The contents
3391      of the event is the zero-terminated byte string passed as the first
3392      argument.  The event will be emitted either to the {\tt .eventlog} file,
3393      or to stderr, depending on the runtime RTS flags. }
3394    with
3395    has_side_effects = True
3396    out_of_line      = True
3397
3398 primop  TraceEventBinaryOp "traceBinaryEvent#" GenPrimOp
3399    Addr# -> Int# -> State# s -> State# s
3400    { Emits an event via the RTS tracing framework.  The contents
3401      of the event is the binary object passed as the first argument with
3402      the the given length passed as the second argument. The event will be
3403      emitted to the {\tt .eventlog} file. }
3404    with
3405    has_side_effects = True
3406    out_of_line      = True
3407
3408 primop  TraceMarkerOp "traceMarker#" GenPrimOp
3409    Addr# -> State# s -> State# s
3410    { Emits a marker event via the RTS tracing framework.  The contents
3411      of the event is the zero-terminated byte string passed as the first
3412      argument.  The event will be emitted either to the {\tt .eventlog} file,
3413      or to stderr, depending on the runtime RTS flags. }
3414    with
3415    has_side_effects = True
3416    out_of_line      = True
3417
3418 primop  GetThreadAllocationCounter "getThreadAllocationCounter#" GenPrimOp
3419    State# RealWorld -> (# State# RealWorld, INT64 #)
3420    { Retrieves the allocation counter for the current thread. }
3421    with
3422    has_side_effects = True
3423    out_of_line      = True
3424
3425 primop  SetThreadAllocationCounter "setThreadAllocationCounter#" GenPrimOp
3426    INT64 -> State# RealWorld -> State# RealWorld
3427    { Sets the allocation counter for the current thread to the given value. }
3428    with
3429    has_side_effects = True
3430    out_of_line      = True
3431
3432 ------------------------------------------------------------------------
3433 section "Safe coercions"
3434 ------------------------------------------------------------------------
3435
3436 pseudoop   "coerce"
3437    Coercible a b => a -> b
3438    { The function {\tt coerce} allows you to safely convert between values of
3439      types that have the same representation with no run-time overhead. In the
3440      simplest case you can use it instead of a newtype constructor, to go from
3441      the newtype's concrete type to the abstract type. But it also works in
3442      more complicated settings, e.g. converting a list of newtypes to a list of
3443      concrete types.
3444    }
3445
3446 ------------------------------------------------------------------------
3447 section "SIMD Vectors"
3448         {Operations on SIMD vectors.}
3449 ------------------------------------------------------------------------
3450
3451 #define ALL_VECTOR_TYPES \
3452   [<Int8,Int#,16>,<Int16,Int#,8>,<Int32,INT32,4>,<Int64,INT64,2> \
3453   ,<Int8,Int#,32>,<Int16,Int#,16>,<Int32,INT32,8>,<Int64,INT64,4> \
3454   ,<Int8,Int#,64>,<Int16,Int#,32>,<Int32,INT32,16>,<Int64,INT64,8> \
3455   ,<Word8,Word#,16>,<Word16,Word#,8>,<Word32,WORD32,4>,<Word64,WORD64,2> \
3456   ,<Word8,Word#,32>,<Word16,Word#,16>,<Word32,WORD32,8>,<Word64,WORD64,4> \
3457   ,<Word8,Word#,64>,<Word16,Word#,32>,<Word32,WORD32,16>,<Word64,WORD64,8> \
3458   ,<Float,Float#,4>,<Double,Double#,2> \
3459   ,<Float,Float#,8>,<Double,Double#,4> \
3460   ,<Float,Float#,16>,<Double,Double#,8>]
3461
3462 #define SIGNED_VECTOR_TYPES \
3463   [<Int8,Int#,16>,<Int16,Int#,8>,<Int32,INT32,4>,<Int64,INT64,2> \
3464   ,<Int8,Int#,32>,<Int16,Int#,16>,<Int32,INT32,8>,<Int64,INT64,4> \
3465   ,<Int8,Int#,64>,<Int16,Int#,32>,<Int32,INT32,16>,<Int64,INT64,8> \
3466   ,<Float,Float#,4>,<Double,Double#,2> \
3467   ,<Float,Float#,8>,<Double,Double#,4> \
3468   ,<Float,Float#,16>,<Double,Double#,8>]
3469
3470 #define FLOAT_VECTOR_TYPES \
3471   [<Float,Float#,4>,<Double,Double#,2> \
3472   ,<Float,Float#,8>,<Double,Double#,4> \
3473   ,<Float,Float#,16>,<Double,Double#,8>]
3474
3475 #define INT_VECTOR_TYPES \
3476   [<Int8,Int#,16>,<Int16,Int#,8>,<Int32,INT32,4>,<Int64,INT64,2> \
3477   ,<Int8,Int#,32>,<Int16,Int#,16>,<Int32,INT32,8>,<Int64,INT64,4> \
3478   ,<Int8,Int#,64>,<Int16,Int#,32>,<Int32,INT32,16>,<Int64,INT64,8> \
3479   ,<Word8,Word#,16>,<Word16,Word#,8>,<Word32,WORD32,4>,<Word64,WORD64,2> \
3480   ,<Word8,Word#,32>,<Word16,Word#,16>,<Word32,WORD32,8>,<Word64,WORD64,4> \
3481   ,<Word8,Word#,64>,<Word16,Word#,32>,<Word32,WORD32,16>,<Word64,WORD64,8>]
3482
3483 primtype VECTOR
3484    with llvm_only = True
3485         vector = ALL_VECTOR_TYPES
3486
3487 primop VecBroadcastOp "broadcast#" GenPrimOp
3488    SCALAR -> VECTOR
3489    { Broadcast a scalar to all elements of a vector. }
3490    with llvm_only = True
3491         vector = ALL_VECTOR_TYPES
3492
3493 primop VecPackOp "pack#" GenPrimOp
3494    VECTUPLE -> VECTOR
3495    { Pack the elements of an unboxed tuple into a vector. }
3496    with llvm_only = True
3497         vector = ALL_VECTOR_TYPES
3498
3499 primop VecUnpackOp "unpack#" GenPrimOp
3500    VECTOR -> VECTUPLE
3501    { Unpack the elements of a vector into an unboxed tuple. #}
3502    with llvm_only = True
3503         vector = ALL_VECTOR_TYPES
3504
3505 primop VecInsertOp "insert#" GenPrimOp
3506    VECTOR -> SCALAR -> Int# -> VECTOR
3507    { Insert a scalar at the given position in a vector. }
3508    with can_fail = True
3509         llvm_only = True
3510         vector = ALL_VECTOR_TYPES
3511
3512 primop VecAddOp "plus#" Dyadic
3513    VECTOR -> VECTOR -> VECTOR
3514    { Add two vectors element-wise. }
3515    with commutable = True
3516         llvm_only = True
3517         vector = ALL_VECTOR_TYPES
3518
3519 primop VecSubOp "minus#" Dyadic
3520    VECTOR -> VECTOR -> VECTOR
3521    { Subtract two vectors element-wise. }
3522    with llvm_only = True
3523         vector = ALL_VECTOR_TYPES
3524
3525 primop VecMulOp "times#" Dyadic
3526    VECTOR -> VECTOR -> VECTOR
3527    { Multiply two vectors element-wise. }
3528    with commutable = True
3529         llvm_only = True
3530         vector = ALL_VECTOR_TYPES
3531
3532 primop VecDivOp "divide#" Dyadic
3533    VECTOR -> VECTOR -> VECTOR
3534    { Divide two vectors element-wise. }
3535    with can_fail = True
3536         llvm_only = True
3537         vector = FLOAT_VECTOR_TYPES
3538
3539 primop VecQuotOp "quot#" Dyadic
3540    VECTOR -> VECTOR -> VECTOR
3541    { Rounds towards zero element-wise. }
3542    with can_fail = True
3543         llvm_only = True
3544         vector = INT_VECTOR_TYPES
3545
3546 primop VecRemOp "rem#" Dyadic
3547    VECTOR -> VECTOR -> VECTOR
3548    { Satisfies \texttt{(quot\# x y) times\# y plus\# (rem\# x y) == x}. }
3549    with can_fail = True
3550         llvm_only = True
3551         vector = INT_VECTOR_TYPES
3552
3553 primop VecNegOp "negate#" Monadic
3554    VECTOR -> VECTOR
3555    { Negate element-wise. }
3556    with llvm_only = True
3557         vector = SIGNED_VECTOR_TYPES
3558
3559 primop VecIndexByteArrayOp "indexArray#" GenPrimOp
3560    ByteArray# -> Int# -> VECTOR
3561    { Read a vector from specified index of immutable array. }
3562    with can_fail = True
3563         llvm_only = True
3564         vector = ALL_VECTOR_TYPES
3565
3566 primop VecReadByteArrayOp "readArray#" GenPrimOp
3567    MutableByteArray# s -> Int# -> State# s -> (# State# s, VECTOR #)
3568    { Read a vector from specified index of mutable array. }
3569    with has_side_effects = True
3570         can_fail = True
3571         llvm_only = True
3572         vector = ALL_VECTOR_TYPES
3573
3574 primop VecWriteByteArrayOp "writeArray#" GenPrimOp
3575    MutableByteArray# s -> Int# -> VECTOR -> State# s -> State# s
3576    { Write a vector to specified index of mutable array. }
3577    with has_side_effects = True
3578         can_fail = True
3579         llvm_only = True
3580         vector = ALL_VECTOR_TYPES
3581
3582 primop VecIndexOffAddrOp "indexOffAddr#" GenPrimOp
3583    Addr# -> Int# -> VECTOR
3584    { Reads vector; offset in bytes. }
3585    with can_fail = True
3586         llvm_only = True
3587         vector = ALL_VECTOR_TYPES
3588
3589 primop VecReadOffAddrOp "readOffAddr#" GenPrimOp
3590    Addr# -> Int# -> State# s -> (# State# s, VECTOR #)
3591    { Reads vector; offset in bytes. }
3592    with has_side_effects = True
3593         can_fail = True
3594         llvm_only = True
3595         vector = ALL_VECTOR_TYPES
3596
3597 primop VecWriteOffAddrOp "writeOffAddr#" GenPrimOp
3598    Addr# -> Int# -> VECTOR -> State# s -> State# s
3599    { Write vector; offset in bytes. }
3600    with has_side_effects = True
3601         can_fail = True
3602         llvm_only = True
3603         vector = ALL_VECTOR_TYPES
3604
3605
3606 primop VecIndexScalarByteArrayOp "indexArrayAs#" GenPrimOp
3607    ByteArray# -> Int# -> VECTOR
3608    { Read a vector from specified index of immutable array of scalars; offset is in scalar elements. }
3609    with can_fail = True
3610         llvm_only = True
3611         vector = ALL_VECTOR_TYPES
3612
3613 primop VecReadScalarByteArrayOp "readArrayAs#" GenPrimOp
3614    MutableByteArray# s -> Int# -> State# s -> (# State# s, VECTOR #)
3615    { Read a vector from specified index of mutable array of scalars; offset is in scalar elements. }
3616    with has_side_effects = True
3617         can_fail = True
3618         llvm_only = True
3619         vector = ALL_VECTOR_TYPES
3620
3621 primop VecWriteScalarByteArrayOp "writeArrayAs#" GenPrimOp
3622    MutableByteArray# s -> Int# -> VECTOR -> State# s -> State# s
3623    { Write a vector to specified index of mutable array of scalars; offset is in scalar elements. }
3624    with has_side_effects = True
3625         can_fail = True
3626         llvm_only = True
3627         vector = ALL_VECTOR_TYPES
3628
3629 primop VecIndexScalarOffAddrOp "indexOffAddrAs#" GenPrimOp
3630    Addr# -> Int# -> VECTOR
3631    { Reads vector; offset in scalar elements. }
3632    with can_fail = True
3633         llvm_only = True
3634         vector = ALL_VECTOR_TYPES
3635
3636 primop VecReadScalarOffAddrOp "readOffAddrAs#" GenPrimOp
3637    Addr# -> Int# -> State# s -> (# State# s, VECTOR #)
3638    { Reads vector; offset in scalar elements. }
3639    with has_side_effects = True
3640         can_fail = True
3641         llvm_only = True
3642         vector = ALL_VECTOR_TYPES
3643
3644 primop VecWriteScalarOffAddrOp "writeOffAddrAs#" GenPrimOp
3645    Addr# -> Int# -> VECTOR -> State# s -> State# s
3646    { Write vector; offset in scalar elements. }
3647    with has_side_effects = True
3648         can_fail = True
3649         llvm_only = True
3650         vector = ALL_VECTOR_TYPES
3651
3652 ------------------------------------------------------------------------
3653
3654 section "Prefetch"
3655         {Prefetch operations: Note how every prefetch operation has a name
3656   with the pattern prefetch*N#, where N is either 0,1,2, or 3.
3657
3658   This suffix number, N, is the "locality level" of the prefetch, following the
3659   convention in GCC and other compilers.
3660   Higher locality numbers correspond to the memory being loaded in more
3661   levels of the cpu cache, and being retained after initial use. The naming
3662   convention follows the naming convention of the prefetch intrinsic found
3663   in the GCC and Clang C compilers.
3664
3665   On the LLVM backend, prefetch*N# uses the LLVM prefetch intrinsic
3666   with locality level N. The code generated by LLVM is target architecture
3667   dependent, but should agree with the GHC NCG on x86 systems.
3668
3669   On the Sparc and PPC native backends, prefetch*N is a No-Op.
3670
3671   On the x86 NCG, N=0 will generate prefetchNTA,
3672   N=1 generates prefetcht2, N=2 generates prefetcht1, and
3673   N=3 generates prefetcht0.
3674
3675   For streaming workloads, the prefetch*0 operations are recommended.
3676   For workloads which do many reads or writes to a memory location in a short period of time,
3677   prefetch*3 operations are recommended.
3678
3679   For further reading about prefetch and associated systems performance optimization,
3680   the instruction set and optimization manuals by Intel and other CPU vendors are
3681   excellent starting place.
3682
3683
3684   The "Intel 64 and IA-32 Architectures Optimization Reference Manual" is
3685   especially a helpful read, even if your software is meant for other CPU
3686   architectures or vendor hardware. The manual can be found at
3687   http://www.intel.com/content/www/us/en/architecture-and-technology/64-ia-32-architectures-optimization-manual.html .
3688
3689   The {\tt prefetch*} family of operations has the order of operations
3690   determined by passing around the {\tt State#} token.
3691
3692   To get a "pure" version of these operations, use {\tt inlinePerformIO} which is quite safe in this context.
3693
3694   It is important to note that while the prefetch operations will never change the
3695   answer to a pure computation, They CAN change the memory locations resident
3696   in a CPU cache and that may change the performance and timing characteristics
3697   of an application. The prefetch operations are marked has_side_effects=True
3698   to reflect that these operations have side effects with respect to the runtime
3699   performance characteristics of the resulting code. Additionally, if the prefetchValue
3700   operations did not have this attribute, GHC does a float out transformation that
3701   results in a let/app violation, at least with the current design.
3702   }
3703
3704
3705
3706 ------------------------------------------------------------------------
3707
3708
3709 --- the Int# argument for prefetch is the byte offset on the byteArray or  Addr#
3710
3711 ---
3712 primop PrefetchByteArrayOp3 "prefetchByteArray3#" GenPrimOp
3713   ByteArray# -> Int# ->  State# s -> State# s
3714   with has_side_effects =  True
3715
3716 primop PrefetchMutableByteArrayOp3 "prefetchMutableByteArray3#" GenPrimOp
3717   MutableByteArray# s -> Int# -> State# s -> State# s
3718   with has_side_effects =  True
3719
3720 primop PrefetchAddrOp3 "prefetchAddr3#" GenPrimOp
3721   Addr# -> Int# -> State# s -> State# s
3722   with has_side_effects =  True
3723
3724 primop PrefetchValueOp3 "prefetchValue3#" GenPrimOp
3725    a -> State# s -> State# s
3726    with strictness  = { \ _arity -> mkClosedStrictSig [botDmd, topDmd] topRes }
3727         has_side_effects =  True
3728 ----
3729
3730 primop PrefetchByteArrayOp2 "prefetchByteArray2#" GenPrimOp
3731   ByteArray# -> Int# ->  State# s -> State# s
3732   with has_side_effects =  True
3733
3734 primop PrefetchMutableByteArrayOp2 "prefetchMutableByteArray2#" GenPrimOp
3735   MutableByteArray# s -> Int# -> State# s -> State# s
3736   with has_side_effects =  True
3737
3738 primop PrefetchAddrOp2 "prefetchAddr2#" GenPrimOp
3739   Addr# -> Int# ->  State# s -> State# s
3740   with has_side_effects =  True
3741
3742 primop PrefetchValueOp2 "prefetchValue2#" GenPrimOp
3743    a ->  State# s -> State# s
3744    with strictness  = { \ _arity -> mkClosedStrictSig [botDmd, topDmd] topRes }
3745         has_side_effects =  True
3746 ----
3747
3748 primop PrefetchByteArrayOp1 "prefetchByteArray1#" GenPrimOp
3749    ByteArray# -> Int# -> State# s -> State# s
3750    with has_side_effects =  True
3751
3752 primop PrefetchMutableByteArrayOp1 "prefetchMutableByteArray1#" GenPrimOp
3753   MutableByteArray# s -> Int# -> State# s -> State# s
3754   with has_side_effects =  True
3755
3756 primop PrefetchAddrOp1 "prefetchAddr1#" GenPrimOp
3757   Addr# -> Int# -> State# s -> State# s
3758   with has_side_effects =  True
3759
3760 primop PrefetchValueOp1 "prefetchValue1#" GenPrimOp
3761    a -> State# s -> State# s
3762    with strictness  = { \ _arity -> mkClosedStrictSig [botDmd, topDmd] topRes }
3763         has_side_effects =  True
3764 ----
3765
3766 primop PrefetchByteArrayOp0 "prefetchByteArray0#" GenPrimOp
3767   ByteArray# -> Int# ->  State# s -> State# s
3768   with has_side_effects =  True
3769
3770 primop PrefetchMutableByteArrayOp0 "prefetchMutableByteArray0#" GenPrimOp
3771   MutableByteArray# s -> Int# -> State# s -> State# s
3772   with has_side_effects =  True
3773
3774 primop PrefetchAddrOp0 "prefetchAddr0#" GenPrimOp
3775   Addr# -> Int# -> State# s -> State# s
3776   with has_side_effects =  True
3777
3778 primop PrefetchValueOp0 "prefetchValue0#" GenPrimOp
3779    a -> State# s -> State# s
3780    with strictness  = { \ _arity -> mkClosedStrictSig [botDmd, topDmd] topRes }
3781         has_side_effects =  True
3782
3783 ------------------------------------------------------------------------
3784 ---                                                                  ---
3785 ------------------------------------------------------------------------
3786
3787 thats_all_folks