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