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