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